From bac360ae337748de42856cd1375243895194144f Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 13 Nov 2026 17:41:40 -0800 Subject: [PATCH] fix(runtime): verify the GitHub bridge before agent startup A sandbox callback gateway can emit its readiness greeting and then lose its HTTP/2 channel before the agent starts. Native GitHub access still published that gateway's address, leaving git and gh without credentials although the managed connection remained usable. Probe the authenticated inactive broker from the execution target before publishing its environment. Close an HTTP/2 bridge that fails this probe and try the existing file transport once. No run is active during this fallback, so it cannot acquire credentials or replay agent operations. Add real-gateway regression coverage for immediate transport loss, delayed loss reporting, and unavailable fallback with host credential isolation. Verify the broker, launcher, and operation-time identity contracts; run the server typecheck and repository build. The initial full-suite attempt stopped during embedded PostgreSQL setup, before tests could collect. Co-Authored-By: Paperclip --- doc/execution-github-identity.md | 8 ++++ .../native-github-access.test.ts | 41 ++++++++++++++++++- .../native-runtime/native-github-access.ts | 38 ++++++++++++++++- 3 files changed, 84 insertions(+), 3 deletions(-) diff --git a/doc/execution-github-identity.md b/doc/execution-github-identity.md index 86b5a3c3a1a..da7881f47ab 100644 --- a/doc/execution-github-identity.md +++ b/doc/execution-github-identity.md @@ -194,6 +194,14 @@ Native warm sessions retain their token-free launchers and inactive broker until session retirement; environment deletion and orderly controller shutdown close idle owners first. Cleanup failures are logged and do not change the run result. +Remote native sessions verify the GitHub callback bridge from inside their execution +environment before publishing the launcher environment. The probe authenticates +to the inactive broker and acquires no GitHub credential. If the HTTP/2 bridge +fails this startup check, the controller closes it and tries the existing file +bridge once. Both transports use the same live identity and credential resolver. +This startup fallback cannot replay an agent command. A later HTTP/2 loss +still makes the warm session unavailable for reuse. + ## Project authorization for background repository work Background provisioning and workspace maintenance have no responsible task user. diff --git a/server/src/services/native-runtime/native-github-access.test.ts b/server/src/services/native-runtime/native-github-access.test.ts index 1f8b07172b1..daa3e4099d5 100644 --- a/server/src/services/native-runtime/native-github-access.test.ts +++ b/server/src/services/native-runtime/native-github-access.test.ts @@ -40,7 +40,7 @@ function localDuplexChannel(command: readonly string[], cwd: string): CommandMan async function broker(resolveCredentials = vi.fn(async (binding: ReturnType) => ({ status: "available", env: { GH_TOKEN: `fixture-${binding.runId}` }, })), remote = false, bridgeUnavailable = false, onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise, -duplex?: { enabled?: boolean; capability: boolean; unavailable?: boolean; recorder?: DuplexObservabilityRecorder }) { +duplex?: { enabled?: boolean; capability: boolean; unavailable?: boolean; startupFailure?: "lost" | "unreachable"; fallbackUnavailable?: boolean; recorder?: DuplexObservabilityRecorder }) { const root = await mkdtemp(path.join(tmpdir(), "native-github-reuse-")); cleanups.push(() => rm(root, { recursive: true, force: true })); const bin = path.join(root, "real-bin"); @@ -71,8 +71,18 @@ duplex?: { enabled?: boolean; capability: boolean; unavailable?: boolean; record const result = await createNativeGitHubAccess({ scope, target, cwd: root, env: { PATH: `${bin}:${path.dirname(process.execPath)}:/usr/bin:/bin`, PAPERCLIP_API_KEY: "old-run-api-key" }, resolveCredentials, onLog }, bridgeUnavailable ? async () => { throw new Error("fixture bridge unavailable"); } : async input => { + if (duplex?.fallbackUnavailable && input.enableSandboxDuplexBridge === false) throw new Error("fixture fallback unavailable"); const bridge = await startAdapterExecutionTargetPaperclipBridge(input); bridgeModes.push(bridge?.env.PAPERCLIP_API_BRIDGE_MODE); + if (duplex?.startupFailure && bridge?.env.PAPERCLIP_API_BRIDGE_MODE === "http2_v1") { + const channel = await openDuplexChannel.mock.results.at(-1)!.value; + channel.stop(); + await vi.waitFor(() => expect(bridge.readRunDisposition?.().failed).toBe(true)); + if (duplex.startupFailure === "unreachable") { + // A transport can stop serving before its control channel reports a loss. + bridge.readRunDisposition = () => ({ failed: false, lossReason: null }); + } + } return bridge; }); cleanups.push(result.stop); @@ -157,6 +167,35 @@ it("marks a lost HTTP/2 bridge unavailable before the next warm admission", asyn channel.stop(); await vi.waitFor(() => expect(b.ready).toBe(false), { timeout: 2000 }); }); +it.each(["lost", "unreachable"] as const)("recovers a %s GitHub bridge after its greeting before starting managed commands", async startupFailure => { + const b = await broker(undefined, true, false, undefined, { enabled: true, capability: true, startupFailure }); + expect(b.bridgeModes).toEqual(["http2_v1", "queue_v1"]); + expect(b.ready).toBe(true); + expect(b.resolveCredentials).not.toHaveBeenCalled(); + const release = b.activate(run("recovered")); + const result = await promisify(execFile)(path.join(b.env.PAPERCLIP_GITHUB_LAUNCHER_DIR, "gh"), [], { + env: { ...process.env, ...b.env, GH_TOKEN: "ambient-must-not-leak" }, + timeout: 15_000, + }); + expect(result.stdout).toBe("fixture-recovered"); + expect(result.stderr).toBe(""); + expect(b.resolveCredentials.mock.calls.map(([binding]) => binding.runId)).toEqual(["recovered"]); + release(); +}, 30_000); +it("keeps host credentials isolated when neither GitHub startup transport works", async () => { + const b = await broker(undefined, true, false, undefined, { + enabled: true, capability: true, startupFailure: "lost", fallbackUnavailable: true, + }); + expect(b.ready).toBe(false); + expect(b.openDuplexChannel).toHaveBeenCalledOnce(); + expect(b.env.PAPERCLIP_GITHUB_BROKER_TOKEN).toBe(""); + b.activate(run("unavailable")); + const result = await promisify(execFile)(path.join(b.env.PAPERCLIP_GITHUB_LAUNCHER_DIR, "gh"), [], { + env: { ...process.env, ...b.env, GH_TOKEN: "ambient-must-not-leak" }, + }); + expect(result.stdout).toBe("anonymous"); + expect(b.resolveCredentials).not.toHaveBeenCalled(); +}); it("closes a healthy HTTP/2 bridge without reporting a lost active run", async () => { const onLog = vi.fn(async (_stream: "stdout" | "stderr", _chunk: string) => undefined); const b = await broker(undefined, true, false, onLog, { enabled: true, capability: true }); diff --git a/server/src/services/native-runtime/native-github-access.ts b/server/src/services/native-runtime/native-github-access.ts index 870dbbbbac9..643de78d9e1 100644 --- a/server/src/services/native-runtime/native-github-access.ts +++ b/server/src/services/native-runtime/native-github-access.ts @@ -6,6 +6,7 @@ import { adapterExecutionTargetDuplexObservabilityRecorder, githubOperationLauncherDirectory, prepareGitHubOperationLaunchers, + runAdapterExecutionTargetProcess, startAdapterExecutionTargetPaperclipBridge, } from "@paperclipai/adapter-utils/execution-target"; import { githubBrokerEnvironment } from "@paperclipai/adapter-utils/github-launcher"; @@ -98,7 +99,7 @@ export async function createNativeGitHubAccess(input: { const address = server.address(); if (!address || typeof address === "string") throw new Error("GitHub broker did not listen"); const url = `http://127.0.0.1:${address.port}`; - try { + const startVerifiedBridge = async (enableSandboxDuplexBridge: boolean) => { bridge = await startBridge({ ...location, runtimeRootDir: input.target?.kind === "remote" @@ -107,13 +108,46 @@ export async function createNativeGitHubAccess(input: { adapterKey: "native-github", hostApiToken: token, hostApiUrl: url, - enableSandboxDuplexBridge: duplexRequested, + enableSandboxDuplexBridge, duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(input.target), onLog: input.onLog, }); if (input.target?.kind === "remote" && !bridge) { throw new Error("GitHub session requires a remote callback bridge"); } + if (!bridge) return null; + // A gateway greeting does not prove that HTTP/2 can carry a request. + // Probe from the execution target before publishing its endpoint. No run + // is active yet, so this checks transport/authentication without acquiring + // a GitHub credential or performing any provider operation. + const probe = await runAdapterExecutionTargetProcess(location.runId, input.target, "node", ["-e", ` + (async () => { + const response = await fetch(process.env.PAPERCLIP_API_URL + '/runtime-tools/github/credentials', { + method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), + headers: { authorization: 'Bearer ' + process.env.PAPERCLIP_API_KEY, 'content-type': 'application/json' }, + body: '{}', + }); + const body = await response.json(); + if (response.status !== 403 || body.error !== 'No active GitHub run') process.exitCode = 1; + })().catch(() => { process.exitCode = 1; }); + `], { cwd: input.cwd, env: bridge.env, timeoutSec: 15, graceSec: 1, onLog: async () => {} }); + if (probe.exitCode !== 0 || probe.timedOut || bridge.readRunDisposition?.().failed) { + throw new Error("GitHub session transport verification failed"); + } + return bridge; + }; + try { + try { + bridge = await startVerifiedBridge(duplexRequested); + } catch (error) { + if (!duplexRequested || bridge?.env.PAPERCLIP_API_BRIDGE_MODE !== "http2_v1") throw error; + // Only the inactive readiness probe can have crossed this bridge. + // Replacing it cannot replay an agent command or change its identity. + await bridge.stop(); + bridge = null; + await input.onLog?.("stderr", "[paperclip] GitHub HTTP/2 startup check failed; retrying with the file bridge.\n").catch(() => undefined); + bridge = await startVerifiedBridge(false); + } } catch { // GitHub remains optional. Stage anonymous wrappers for this session; // the supervisor retries transport setup on the next run.