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 <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip committed 2026-11-13 17:41:40 -08:00
1 parent cefef8f11d
commit bac360ae33
3 files changed
+84 -3

No files matched your search

+8
View File
@@ -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.
@@ -40,7 +40,7 @@ function localDuplexChannel(command: readonly string[], cwd: string): CommandMan
async function broker(resolveCredentials = vi.fn(async (binding: ReturnType<typeof run>) => ({
status: "available", env: { GH_TOKEN: `fixture-${binding.runId}` },
})), remote = false, bridgeUnavailable = false, onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>,
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 });
@@ -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.