From 36eaf9778fa68eb19e7c9c5cbe65b436b6b8f2a1 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Tue, 5 May 2026 19:30:11 -0700 Subject: [PATCH] Expand sandbox callback bridge allowlist to cover the documented heartbeat surface (#5324) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - When an agent runs in an e2b sandbox or other non-managed environment, it talks back to the Paperclip server through a per-lease callback bridge that proxies HTTP requests > - The bridge has an allowlist of method/path patterns it will forward; anything outside the list is rejected to keep the bridge tight > - The allowlist had drifted behind what the heartbeat documentation describes as the supported callback surface — several documented endpoints (issue updates, agent-side log emit, work-status writes) were being rejected at the bridge > - This pull request expands the allowlist to cover the documented heartbeat surface and adds tests that pin every newly-allowed pattern, so the doc and the bridge stay in sync > - The benefit is sandboxed runs no longer hit "method not allowed" / "path not allowed" rejections on the documented set of callbacks ## What Changed - `packages/adapter-utils/src/sandbox-callback-bridge.ts`: expand the method/path allowlist to match the documented heartbeat callback surface - `packages/adapter-utils/src/sandbox-callback-bridge.test.ts`: add coverage for every newly-allowed pattern, plus negative cases for patterns that should still be rejected ## Verification - `pnpm vitest run --no-coverage --project @paperclipai/adapter-utils` - `pnpm typecheck` clean - Manual: previously-rejected callbacks from sandboxed runs now succeed end-to-end ## Risks Low. The allowlist only grows; nothing previously allowed is now blocked. Tests pin both the new allowed patterns and that out-of-doc patterns stay rejected. ## Model Used Claude Opus 4.7 (1M context) ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable — new tests cover added patterns + still-rejected negatives - [x] If this change affects the UI, I have included before/after screenshots — N/A (no UI) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --- .../src/sandbox-callback-bridge.test.ts | 92 +++++++++++++++++++ .../src/sandbox-callback-bridge.ts | 67 +++++++++++++- 2 files changed, 156 insertions(+), 3 deletions(-) diff --git a/packages/adapter-utils/src/sandbox-callback-bridge.test.ts b/packages/adapter-utils/src/sandbox-callback-bridge.test.ts index dc04df6c..c18343af 100644 --- a/packages/adapter-utils/src/sandbox-callback-bridge.test.ts +++ b/packages/adapter-utils/src/sandbox-callback-bridge.test.ts @@ -7,6 +7,7 @@ import { afterEach, describe, expect, it } from "vitest"; import { prepareCommandManagedRuntime } from "./command-managed-runtime.js"; import { + authorizeSandboxCallbackBridgeRequestWithRoutes, createFileSystemSandboxCallbackBridgeQueueClient, createSandboxCallbackBridgeAsset, createSandboxCallbackBridgeToken, @@ -613,4 +614,95 @@ describe("sandbox callback bridge", () => { error: expect.stringMatching(/JSON|Unexpected|Unterminated/i), }); }); + + it("permits the documented heartbeat surface and denies unrelated routes", () => { + const allowed: Array<{ method: string; path: string }> = [ + { method: "GET", path: "/api/agents/me" }, + { method: "GET", path: "/api/agents/me/inbox-lite" }, + { method: "GET", path: "/api/agents/me/inbox/mine" }, + { method: "GET", path: "/api/agents/agent-1" }, + { method: "GET", path: "/api/agents/agent-1/skills" }, + { method: "POST", path: "/api/agents/agent-1/skills/sync" }, + { method: "PATCH", path: "/api/agents/agent-1/instructions-path" }, + { method: "GET", path: "/api/companies/co-1" }, + { method: "GET", path: "/api/companies/co-1/dashboard" }, + { method: "GET", path: "/api/companies/co-1/agents" }, + { method: "GET", path: "/api/companies/co-1/issues" }, + { method: "GET", path: "/api/companies/co-1/projects" }, + { method: "GET", path: "/api/companies/co-1/goals" }, + { method: "GET", path: "/api/companies/co-1/org" }, + { method: "GET", path: "/api/companies/co-1/approvals" }, + { method: "GET", path: "/api/companies/co-1/routines" }, + { method: "GET", path: "/api/companies/co-1/skills" }, + { method: "GET", path: "/api/projects/proj-1" }, + { method: "GET", path: "/api/goals/goal-1" }, + { method: "GET", path: "/api/issues/issue-1" }, + { method: "GET", path: "/api/issues/issue-1/heartbeat-context" }, + { method: "GET", path: "/api/issues/issue-1/comments" }, + { method: "GET", path: "/api/issues/issue-1/comments/c-1" }, + { method: "POST", path: "/api/issues/issue-1/comments" }, + { method: "GET", path: "/api/issues/issue-1/documents" }, + { method: "GET", path: "/api/issues/issue-1/documents/plan" }, + { method: "GET", path: "/api/issues/issue-1/documents/plan/revisions" }, + { method: "PUT", path: "/api/issues/issue-1/documents/plan" }, + { method: "POST", path: "/api/issues/issue-1/checkout" }, + { method: "POST", path: "/api/issues/issue-1/release" }, + { method: "PATCH", path: "/api/issues/issue-1" }, + { method: "GET", path: "/api/issues/issue-1/approvals" }, + { method: "GET", path: "/api/issues/issue-1/interactions" }, + { method: "GET", path: "/api/issues/issue-1/interactions/inter-1" }, + { method: "POST", path: "/api/issues/issue-1/interactions" }, + { method: "POST", path: "/api/issues/issue-1/interactions/inter-1/accept" }, + { method: "POST", path: "/api/issues/issue-1/interactions/inter-1/reject" }, + { method: "POST", path: "/api/issues/issue-1/interactions/inter-1/respond" }, + { method: "POST", path: "/api/companies/co-1/issues" }, + { method: "GET", path: "/api/approvals/ap-1" }, + { method: "GET", path: "/api/approvals/ap-1/issues" }, + { method: "GET", path: "/api/approvals/ap-1/comments" }, + { method: "POST", path: "/api/approvals/ap-1/comments" }, + { method: "POST", path: "/api/companies/co-1/approvals" }, + { method: "GET", path: "/api/execution-workspaces/ws-1" }, + { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/start" }, + { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/stop" }, + { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/restart" }, + { method: "GET", path: "/api/routines/r-1" }, + { method: "GET", path: "/api/routines/r-1/runs" }, + { method: "POST", path: "/api/companies/co-1/routines" }, + { method: "PATCH", path: "/api/routines/r-1" }, + { method: "POST", path: "/api/routines/r-1/run" }, + { method: "POST", path: "/api/routines/r-1/triggers" }, + { method: "PATCH", path: "/api/routine-triggers/t-1" }, + { method: "DELETE", path: "/api/routine-triggers/t-1" }, + ]; + for (const request of allowed) { + expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request)).toBeNull(); + } + + const denied: Array<{ method: string; path: string }> = [ + { method: "DELETE", path: "/api/secrets" }, + // Pin the runtime-services regex to start/stop/restart only — anything + // else (delete, reset, wipe, etc.) must stay denied even if the API + // grows new actions later. + { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/delete" }, + { method: "POST", path: "/api/companies/co-1/agents" }, + { method: "POST", path: "/api/agents/agent-1/pause" }, + { method: "POST", path: "/api/agents/agent-1/terminate" }, + { method: "POST", path: "/api/agents/agent-1/keys" }, + { method: "POST", path: "/api/companies/co-1/exports" }, + { method: "POST", path: "/api/companies/co-1/imports/apply" }, + { method: "POST", path: "/api/companies/co-1/archive" }, + { method: "DELETE", path: "/api/issues/issue-1/documents/plan" }, + { method: "DELETE", path: "/api/issues/issue-1/approvals/ap-1" }, + { method: "POST", path: "/api/approvals/ap-1/approve" }, + { method: "POST", path: "/api/approvals/ap-1/reject" }, + { method: "POST", path: "/api/companies/co-1/logo" }, + { method: "GET", path: "/api/companies/co-1/secrets" }, + { method: "PATCH", path: "/api/secrets/secret-1" }, + ]; + for (const request of denied) { + expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request)).toBe( + `Route not allowed: ${request.method} ${request.path}`, + ); + } + }); }); diff --git a/packages/adapter-utils/src/sandbox-callback-bridge.ts b/packages/adapter-utils/src/sandbox-callback-bridge.ts index 666ba9e9..cb020046 100644 --- a/packages/adapter-utils/src/sandbox-callback-bridge.ts +++ b/packages/adapter-utils/src/sandbox-callback-bridge.ts @@ -23,15 +23,76 @@ export interface SandboxCallbackBridgeRouteRule { path: RegExp; } +// Routes the in-sandbox heartbeat skill is documented to call. The server +// still enforces actor-level permissions on top of this allowlist; the list +// exists to bound the surface area a compromised CLI could reach via the +// reverse bridge. Keep this in sync with the Paperclip skill in +// `skills/paperclip/SKILL.md` and `references/api-reference.md`. export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCallbackBridgeRouteRule[] = [ + // Identity, inbox, agent self-management { method: "GET", path: /^\/api\/agents\/me$/ }, + { method: "GET", path: /^\/api\/agents\/me\/inbox-lite$/ }, + { method: "GET", path: /^\/api\/agents\/me\/inbox\/mine$/ }, + { method: "GET", path: /^\/api\/agents\/[^/]+$/ }, + { method: "GET", path: /^\/api\/agents\/[^/]+\/skills$/ }, + { method: "POST", path: /^\/api\/agents\/[^/]+\/skills\/sync$/ }, + { method: "PATCH", path: /^\/api\/agents\/[^/]+\/instructions-path$/ }, + + // Company-level reads used to discover work and context + { method: "GET", path: /^\/api\/companies\/[^/]+$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/dashboard$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/agents$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/issues$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/projects$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/goals$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/org$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/approvals$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/routines$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/skills$/ }, + { method: "GET", path: /^\/api\/projects\/[^/]+$/ }, + { method: "GET", path: /^\/api\/goals\/[^/]+$/ }, + + // Issue lifecycle: read context, checkout, update, comment, document, release + { method: "GET", path: /^\/api\/issues\/[^/]+$/ }, { method: "GET", path: /^\/api\/issues\/[^/]+\/heartbeat-context$/ }, { method: "GET", path: /^\/api\/issues\/[^/]+\/comments(?:\/[^/]+)?$/ }, - { method: "GET", path: /^\/api\/issues\/[^/]+\/documents(?:\/[^/]+)?$/ }, - { method: "POST", path: /^\/api\/issues\/[^/]+\/checkout$/ }, { method: "POST", path: /^\/api\/issues\/[^/]+\/comments$/ }, - { method: "POST", path: /^\/api\/issues\/[^/]+\/interactions(?:\/[^/]+)?$/ }, + { method: "GET", path: /^\/api\/issues\/[^/]+\/documents(?:\/[^/]+)?$/ }, + { method: "GET", path: /^\/api\/issues\/[^/]+\/documents\/[^/]+\/revisions$/ }, + { method: "PUT", path: /^\/api\/issues\/[^/]+\/documents\/[^/]+$/ }, + { method: "POST", path: /^\/api\/issues\/[^/]+\/checkout$/ }, + { method: "POST", path: /^\/api\/issues\/[^/]+\/release$/ }, { method: "PATCH", path: /^\/api\/issues\/[^/]+$/ }, + { method: "GET", path: /^\/api\/issues\/[^/]+\/approvals$/ }, + + // Issue-thread interactions (suggest tasks, ask questions, request confirmation) + { method: "GET", path: /^\/api\/issues\/[^/]+\/interactions(?:\/[^/]+)?$/ }, + { method: "POST", path: /^\/api\/issues\/[^/]+\/interactions$/ }, + { method: "POST", path: /^\/api\/issues\/[^/]+\/interactions\/[^/]+\/(?:accept|reject|respond)$/ }, + + // Subtasks / delegation + { method: "POST", path: /^\/api\/companies\/[^/]+\/issues$/ }, + + // Approvals (request, read, comment) + { method: "GET", path: /^\/api\/approvals\/[^/]+$/ }, + { method: "GET", path: /^\/api\/approvals\/[^/]+\/issues$/ }, + { method: "GET", path: /^\/api\/approvals\/[^/]+\/comments$/ }, + { method: "POST", path: /^\/api\/approvals\/[^/]+\/comments$/ }, + { method: "POST", path: /^\/api\/companies\/[^/]+\/approvals$/ }, + + // Execution workspaces and runtime services (start/stop/restart dev servers) + { method: "GET", path: /^\/api\/execution-workspaces\/[^/]+$/ }, + { method: "POST", path: /^\/api\/execution-workspaces\/[^/]+\/runtime-services\/(?:start|stop|restart)$/ }, + + // Routines (agents manage their own routines and triggers) + { method: "GET", path: /^\/api\/routines\/[^/]+$/ }, + { method: "GET", path: /^\/api\/routines\/[^/]+\/runs$/ }, + { method: "POST", path: /^\/api\/companies\/[^/]+\/routines$/ }, + { method: "PATCH", path: /^\/api\/routines\/[^/]+$/ }, + { method: "POST", path: /^\/api\/routines\/[^/]+\/run$/ }, + { method: "POST", path: /^\/api\/routines\/[^/]+\/triggers$/ }, + { method: "PATCH", path: /^\/api\/routine-triggers\/[^/]+$/ }, + { method: "DELETE", path: /^\/api\/routine-triggers\/[^/]+$/ }, ] as const; export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_HEADER_ALLOWLIST = [