Repository navigation
fix(adapter-utils): accept the bridge token in X-API-Key - #12785
Merged
devinfoley merged 4 commits intoOct 15, 2026
Merged
devinfoley merged 4 commits into
devinfoley merged 4 commits into
Conversation
The in-sandbox callback gateway read the bridge token only from "Authorization: Bearer <token>". The public Paperclip API documents the "X-API-Key: <token>" header, so an agent that follows those docs sends that header first and gets a 401 with "Invalid bridge token." The agent then retries with a bearer header and the same token. Both gateways now read the token through one helper. The helper prefers a bearer token in the Authorization header. It falls back to the X-API-Key header. The token still goes to the same constant-time comparison, and the closed header allowlist still strips both headers before either gateway forwards a request. Claude-Session: https://claude.ai/code/session_01U9PF3d9SASC9tomDRjyeVt
Contributor
[Critical impact] The PR appears safe to merge; no actionable issues remain. SummaryBoth sandbox gateways now accept the per-run token in
Reviews (6) · Last reviewed commit: "test(adapter-utils): keep queue response..." · Reviewed by Greptile |
Contributor
Contributor
|
@greptileai apex |
This was referenced Oct 15, 2026
nickyleach
added a commit
that referenced
this pull request
Oct 15, 2026
…16507) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Sandbox agents use the callback bridge to call the Paperclip API. > - The bridge round-trip test checks request delivery and credential removal. > - #12785 added an accepted API-key request before the feedback request. > - The feedback assertions still read request 2, which is now the GitHub credentials request. > - This PR checks request 3 and verifies that all four accepted requests reached the host. > - This restores the shared test gate while retaining the Unicode payload and token checks. ## Linked Issues or Issue Description Related PR: #12785 introduced the stale feedback index. The reported failure appears on #16486 and master. Searches for `workspaces-b`, `sandbox-callback-bridge`, `surrogate`, and `EncoderFallbackException` found no duplicate fix. **What happened?** The `General tests (workspaces-b)` job fails on PRs and master. The hosted PR job and AWS master job both report `System.Text.EncoderFallbackException` for an unpaired `\uD83D`. The runner exits during the test step and does not upload that step's log. The unchanged master test reproduces a deterministic assertion failure at the feedback request. It compares `/runtime-tools/github/credentials` with `/api/companies/company-1/agent-commentary` and prints a diff containing 5,000 crying emoji. The assertion output is the likely trigger for the runner's Unicode logging crash. - [Reported PR job](https://github.com/paperclipai/paperclip/actions/runs/38818474563/job/116719880033) - [Master job with the same runner exception](https://github.com/paperclipai/paperclip/actions/runs/38821128038/job/116717690951) **Expected behavior** The test checks the actual feedback request, verifies its full payload, and confirms that its authorization header is removed. Both shared CI lanes complete normally. **Steps to reproduce** 1. Check out master at `c4a16cbe981f96e2756c7014103c88da67e5514f`. 2. Install dependencies with pnpm 9.15.4. 3. Run `node_modules/.bin/vitest run packages/adapter-utils/src/sandbox-callback-bridge.test.ts -t 'round-trips localhost bridge requests'`. 4. Observe the feedback assertion reading the preceding GitHub credentials request. **Paperclip version or commit** Master at `c4a16cbe981f96e2756c7014103c88da67e5514f`. **Deployment mode** Built from source. GitHub-hosted PR CI and AWS post-merge CI. ## What Changed - Assert that four accepted requests reached the host. - Check feedback delivery and authorization stripping on request 3. - Retain the large Unicode payload and all existing authentication checks. ## Verification - Unchanged master: the focused round-trip test fails at the stale feedback index. - Fixed branch: all 68 tests in `sandbox-callback-bridge.test.ts` pass with real localhost gateways. - `pnpm --filter @paperclipai/adapter-utils typecheck` passes. - `git diff --check` passes. - Exact CI group: `node scripts/run-vitest-stable.mjs --mode general --group general-workspaces-b` passes (4,800 tests passed, 28 skipped across 17 projects). - `pnpm --filter @paperclipai/adapter-utils build` passes. - Greptile reviewed current head `3de15d3374354809ea84ca4df5f93c2473715f02`: 5/5, success, no comments or actionable findings. - All GitHub checks pass on current head `3de15d3374354809ea84ca4df5f93c2473715f02`: 55 successful checks and 2 intentional skips, including `workspaces-b`, build, typecheck, Runner verification, and e2e. - Full local `pnpm test:run` was started and stopped after the CI test lanes passed; it did not complete locally. No worktree-owned test processes remained afterward. - Full local typecheck and build were attempted. Both stop at the Runner Rust commands because `cargo` is absent from the shell PATH. The changed package typecheck passes. The complete repository typecheck and build pass in CI. - The first sandboxed local reproduction could not bind localhost (`EPERM`). It was repeated with listener permission and reached the deterministic assertion failure described above. ## Risks Low risk. This changes three test lines. Runtime behavior, credentials, workflow settings, and payload coverage stay the same. The GitHub runner Unicode logging defect remains upstream; this fix removes the incorrect assertion that triggers it in this test. ## Model Used OpenAI GPT-6 in Codex, with reasoning, repository inspection, and command execution. The exact runtime model identifier and context window size are not exposed in this session. ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Thinking Path
Linked Issues or Issue Description
No existing issue found. I searched the repository for open pull requests matching
x-api-keyandbridge token. Nothing addresses the in-sandbox gateway header convention. The closest neighbours are unrelated: #12632 (Composiomcp.headers.x-api-key) and #12120 (the HTTP/2 transport for this bridge, already merged). The problem followsbug_report.yml:What happened?
An agent running in a sandbox calls the Paperclip API through the loopback callback bridge. When it sends the credential as
X-API-Key: <bridge token>, the gateway answers401with{"error":"Invalid bridge token."}. The token in that header is the correct per-run bridge token.Expected behavior
The gateway accepts the correct per-run bridge token in either header convention. The public API documents
X-API-Key, so an agent that follows the documentation succeeds on its first call.Steps to reproduce
PAPERCLIP_API_URL(the loopback bridge origin) andPAPERCLIP_API_KEY(the bridge token) into the sandbox environment.401 {"error":"Invalid bridge token."}.-H "Authorization: Bearer $PAPERCLIP_API_KEY". The response is200.Paperclip version or commit
Branched from
masterat06c0e883f.Deployment mode
Self-hosted Kubernetes, with the agent in a sandbox execution target and a local model behind an OpenAI-compatible endpoint.
Agent adapter(s) involved
Not adapter-specific (core bug). Observed with a local-model adapter on a sandboxed lane. Any agent that follows the public API documentation sends this header.
Additional context
The variable name is the trigger. The run calls the credential
PAPERCLIP_API_KEY, and an agent that has read the public API documentation knows an API key goes inX-API-Key. Paperclip's own in-prompt guidance usesAuthorization: Bearer $PAPERCLIP_API_KEY, so the two conventions sit side by side.Across 12 observed runs on that lane, the agent's first bridge call used
X-API-Keyin 6 runs. Every one of those runs recovered by retrying with a bearer header and the same token. In some runs the agent first tried unrelated repairs, such as writing a test comment, before it changed the header.What Changed
readBridgeToken(req)helper to the generated in-sandbox gateway source. The helper returns the bearer token fromAuthorizationwhen the header carries one. It otherwise returns thex-api-keyheader value, or an empty string.timingSafeEqualcomparison. The change does not alter the comparison, the token, or its lifetime.X-API-Keyrequest with the right token, anX-API-Keyrequest with a wrong token, and the fact that the header never reaches the host.Verification
Commands run on this branch:
Both new tests are real regression guards. With the test file in place and the source change reverted, each one fails with
expected 401 to be 200: the file-mode round-trip test and the HTTP/2 test. Both pass with the source change applied.A reviewer can confirm the security properties by reading two things. First,
tokensMatchin the generated source is unchanged, so the constant-time comparison against the same per-run token is unchanged. Second,allowedHeadersin the same source is a closed allowlist ofaccept,content-type,if-match, andif-none-match.normalizeHeadersdrops every other header, so neitherauthorizationnorx-api-keyleaves the sandbox on either transport. The independent host-side check inhttp2-bridge-server.tsis untouched, because each gateway setsauthorization: Bearer <token>on the request it forwards.ROADMAP.md check: I grepped
ROADMAP.mdforbridge,x-api-key,redaction, andsandbox callback. There were no matches. This is a small bug fix in an existing subsystem, so it does not overlap planned core work.Duplicate search: I searched pull requests in this repository for
x-api-keyandbridge token. No open or merged pull request changes how the in-sandbox gateway reads the token.Risks
Low risk.
Authorizationheader and a validX-API-Keyheader now succeeds instead of failing. This is intentional: the bridge only ever issues bearer tokens, so no bridge caller relied on that failure.x-api-key, so no forwarded request changes shape.Model Used
Claude Opus 5 (
claude-opus-5), extended thinking at high effort — verify before merge.Checklist
Fixes: #/Closes #/Refs #OR (b) described the issue in-PR following the relevant issue template#NNN/github.com/paperclipai/paperclipURLs)docs/...,fix/...) and contains no internal Paperclip ticket id or instance-derived details@superbiche · contributor · drafted with Claude Opus 5, reviewed before posting; the voice and decisions are mine.