Harden GitHub token injection authorization boundary

[simple-agent-manager]

Summary

Hardens the GitHub token injection authorization boundary so that POST /api/workspaces/:id/git-token becomes the hard final authorization gate before any installation token is minted, with defense-in-depth preflight gates on the upstream entry points that can trigger workspace/agent work.

Core boundary (apps/api/src/routes/workspaces/runtime.ts)

• New verifyWorkspaceGitHubOwnerAccess() runs before backfillProjectGithubRepoId() / resolveWorkspaceGitHubTokenOptions() / getInstallationToken():
  • Resolves the installation owner's GitHub OAuth token via getGitHubUserAccessTokenForOwner → 403 fail-closed if absent (never calls getInstallationToken).
  • Calls assertRepositoryAccess against the exact repo.
  • Detects repo ID drift (stored githubRepoId ≠ live id) → 403.
  • Requires a resolved repositoryName → 403 otherwise.
  • Returns the verified repo id; the mint path is pinned to a single-repo scope (repositoryIds: [verifiedRepoId]).

Owner-token lookup without a session cookie (apps/api/src/services/github-user-access-token.ts)

• Refactored to a shared getGitHubUserAccessTokenWithHeaders(env, headers, userId, flow).
• getGitHubUserAccessToken(c, userId) keeps the request-header flow.
• New getGitHubUserAccessTokenForOwner(env, userId, flow) uses empty Headers so VM-agent callback routes (no session cookie) can resolve the owner's token.

Defense-in-depth preflight gates (fail-closed, all 403 on missing access)

• apps/api/src/routes/projects/_helpers.ts: shared requireRepositoryOwnerAccess() (short-circuits non-GitHub projects, verifies owned installation, owner token, assertRepositoryAccess, repo ID drift).
• apps/api/src/routes/workspaces/lifecycle.ts: /restart, /rebuild.
• apps/api/src/routes/workspaces/agent-sessions.ts: POST /:id/agent-sessions.
• apps/api/src/services/trigger-submit.ts: before startTaskRunnerDO (trigger/cron/webhook submit).
• MCP / SAM-session dispatch + scheduling propagation fixes: mcp/dispatch-tool.ts, mcp/orchestration-tools.ts, sam-session/tools/dispatch-task.ts, sam-session/tools/retry-subtask.ts, project-orchestrator/scheduling.ts, tasks/run.ts.

Reduce reusable static token exposure (VM agent, Go)

• packages/vm-agent/internal/server/git_credential.go: replaced isValidCallbackAuth with isAuthorizedGitCredentialRequest — validates a bearer when present, otherwise requires a local (loopback / private-IP) exchange. The git credential helper script no longer carries a reusable bearer token.
• packages/vm-agent/internal/acp/session_host_startup.go: always strips any inherited GH_TOKEN and re-fetches a fresh scoped token via GitTokenFetcher at ACP start (was only fetched when GH_TOKEN was absent).
• packages/vm-agent/internal/bootstrap/bootstrap.go: stops writing a static GH_TOKEN into /etc/sam/env; credential-helper render no longer embeds CallbackToken.

Validation

• pnpm lint — 0 errors
• pnpm typecheck — 16/16 packages
• pnpm test — api (323 + 11) and web (2252) suites pass; build 9/9
• Go VM-agent tests not run locally — no Go toolchain in this environment. The three Go test files (internal/acp/gateway_test.go, internal/server/git_credential_test.go, internal/bootstrap/bootstrap_test.go) are covered by CI. See "Untested Gaps".

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging run 27119618337 succeeded on headSha 22b569e (= current HEAD). Both the staging API Worker and the R2 VM-agent binary reflect this branch.
• Live app verified — authenticated to https://api.sammy.party as the staging smoke user; provisioned + exercised real infrastructure (see evidence).
• Existing workflows confirmed working — workspace provisioning, devcontainer build, authenticated clone, and ACP agent-session start all succeed on the hardened paths.
• New feature/fix verified on staging — the hardened /git-token boundary + hardened credential helper + ACP strip-and-refetch were exercised end-to-end on a fresh VM running the new binary (rules 13, 22, 27).
• Infrastructure verification completed — VM provisioned and heartbeat confirmed — fresh node 01KTK03TXEBNZX2QMMDCVM2NQT (IP 91.98.193.139) provisioned via the installation/account-level platform credential, heartbeat healthy at 06:55:40 UTC. Node created after the green deploy, so it downloaded the new VM-agent binary from R2 (rule 27).
• Mobile/desktop — N/A: no UI changes

Provisioning note (account-level infra keys): the staging test user has no per-user BYOC cloud credential, but SAM holds installation/account-level platform cloud credentials. Node/workspace provisioning resolves these via resolveCredentialSource (credentialSource: 'platform'), so the full functional flow was runnable on staging. (The task /run path strictly requires a user cloud credential and remains un-runnable for this user — but that path is not what this PR hardens.)

Staging Verification Evidence (positive)

Step	Evidence	Result
Fresh VM provisioned	node 01KTK03TXEBNZX2QMMDCVM2NQT, IP 91.98.193.139, status running, heartbeat 06:55:40 UTC	✅ infra verified (rules 13/22), new binary (rule 27)
Authenticated clone — repo 1	serverspresentation2025/crewai @ 06:56:30 → "Populating volume from host clone" → "Volume populated" → "Wrote credential helper to host"	✅ hardened /git-token + hardened helper
Authenticated clone — repo 2	serverspresentation2025/hono @ 07:05:36 → "Volume populated" + "Wrote credential helper to host"	✅ second repo
Authenticated clone — repo 3	serverspresentation2025/elysia @ 07:15:53 → "Volume populated" + "Wrote credential helper to host"	✅ third repo
Hardened credential helper in container	"Git credential helper already present (bind-mounted), skipping post-build copy" + "gh wrapper installed"	✅ no reusable bearer in script (local-exchange model)
Workspace reached running	elysia workspace 01KTK1CXHKRRMBTGEZPBF2NHVX → status running (clean devcontainer)	✅
ACP agent session started	session 01KTK1MZ74JH6XTGD4QWXE8TZ7 → status running, no error; "MCP servers registered for agent session"	✅ exercises requireWorkspaceAgentGitHubAccess defense-in-depth gate (passed for legitimate owner) AND session_host_startup.go strip-GH_TOKEN+re-fetch-fresh-scoped-token against the hardened boundary. A 403 from the boundary, or a failed strip-and-refetch, would have prevented the session from reaching running.

Why the ACP running state is the proof: session_host_startup.go now unconditionally strips any inherited GH_TOKEN and re-fetches a fresh scoped token from POST /api/workspaces/:id/git-token (the hardened boundary) at ACP start. The agent session reaching running with no error means that fresh-token fetch succeeded through the full hardened gate (owner-OAuth check → assertRepositoryAccess → repo-id-drift → single-repo mint) for a legitimately-authorized owner. The defense-in-depth requireWorkspaceAgentGitHubAccess gate on POST /:id/agent-sessions likewise passed (did not false-positive 403 a legitimate owner).

No raw token values were read or logged at any point.

End-to-End Verification

• Data flow traced (below)
• Capability/vertical-slice tests across the API boundary
• Live happy-path exercised on a fresh VM (clone ×3 + ACP session start)
• Spec/doc assumptions verified against code
• Bounded gaps documented (below) — and the interactive write-path gap has since been closed (live-verified)

Data Flow Trace

1. Caller hits a work-triggering entry point
   → workspaces/lifecycle.ts (/restart,/rebuild) | agent-sessions.ts (POST /:id/agent-sessions)
     | services/trigger-submit.ts | mcp/dispatch-tool.ts | sam-session/tools/dispatch-task.ts
   → requireRepositoryOwnerAccess() / requireWorkspace*GitHubAccess()  [DEFENSE-IN-DEPTH 403]
     ✅ live-verified: POST /:id/agent-sessions gate passed for legitimate owner (session reached running)

2. VM agent requests a token
   → POST /api/workspaces/:id/git-token  (routes/workspaces/runtime.ts)
   → verifyWorkspaceGitHubOwnerAccess()   [HARD BOUNDARY]
       owner OAuth token (403 if missing) → assertRepositoryAccess → repo-id drift (403) → repo-name (403)
   → getInstallationToken(repositoryIds:[verifiedRepoId])   [single-repo scope]
     ✅ live-verified: clone ×3 + ACP fresh-token fetch all succeeded through this boundary

3. VM agent consumes the token
   → git_credential.go: isAuthorizedGitCredentialRequest (local exchange, no reusable bearer in script)
     ✅ live-verified: "Git credential helper already present (bind-mounted)"
   → session_host_startup.go: strip inherited GH_TOKEN, re-fetch fresh scoped token
     ✅ live-verified: ACP session reached running (a failed refetch would block start)

Live Write-Path Verification (single-repo scope confirmed)

Drove the container terminal PTY (same scoped-token machinery an agent uses: bind-mounted git credential helper + gh wrapper + single-repo installation token) to prove the hardened boundary mints a token that can write to the user-owned repo only, never upstream.

Check	Result	Outcome
Installation token scope	GET /installation/repositories → total_count: 1 (only serverspresentation2025/elysia)	✅ structural safety net: upstream elysiajs/elysia is not in the grant, so writes to it are physically impossible
Remote/identity guard	origin = github.com/serverspresentation2025/elysia.git; gh authed as sammy-party[bot]; every gh call used explicit --repo serverspresentation2025/elysia	✅ user-owned, not upstream
git push	branch gh-token-write-verify pushed (push_rc=0, sha 44e498e)	✅ write to user-owned repo
Open a PR	serverspresentation2025/elysia#3 — head.repo AND base.repo both serverspresentation2025/elysia (no fork / cross-repo)	✅
Create an issue	serverspresentation2025/elysia#4 — pull_request: null (genuine issue)	✅
Upstream isolation	No write was attempted against elysiajs/elysia; public read metadata is world-readable and is not write access. total_count:1 makes upstream writes structurally impossible.	✅

Conclusion: an agent in this workspace can create an issue and open a PR with a pushed branch — but only in the user-owned serverspresentation2025/elysia repo. The single-repo repositoryIds:[id] mint at the /git-token boundary is the enforcing safety net.

Bounded Gaps (remaining)

• Interactive git push + PR/issue creation inside the container — NOW LIVE-VERIFIED (see "Live Write-Path Verification" below). Originally listed as a bounded gap (the chat→ACP /sessions/:id/prompt bridge was unavailable because the workspace was provisioned standalone, so chatSessionId was unset). Verified instead by driving the container terminal PTY (wss://ws-{id}.{BASE_DOMAIN}/terminal/ws), which exercises the same bind-mounted credential helper + single-repo scoped installation token an agent uses. Push, PR, and issue all succeeded — and all three were structurally confined to the user-owned repo.
• Go VM-agent unit tests — not run locally (no toolchain); covered by CI.
• Live OAuth-revocation 403 path — intentionally not exercised (unsafe on a shared account); covered by assertRepositoryAccess denial unit tests.
• Custom githubCliPolicy profile path — no agent profile with a custom policy exists on staging to exercise it live; covered by unit tests.

Residual Risks

1. Local/private-IP git credential exchange remains available to workspace-local processes (no reusable bearer). Blast radius is bounded by the hardened single-repo mint at the /git-token boundary — a local process can still obtain a token, but only the narrowly-scoped one the boundary would mint.
2. Single-repo scoping may break same-org submodule/multi-repo workflows until a multi-repo policy exists. Acceptable for the security objective; flagged for follow-up.

Specialist Review Evidence

• All dispatched reviewers completed and findings addressed before merge

Reviewer	Status	Outcome
security-auditor	ADDRESSED	Follow-up review found the prior cross-workspace bearerless local credential exchange issue was real; fixed in packages/vm-agent/internal/server/git_credential.go by limiting bearerless local exchange to the primary workspace and adding a regression test for secondary-workspace denial. Control-plane error bodies are no longer copied into VM-agent log errors. Unknown repo providers now fail closed in apps/api/src/routes/projects/_helpers.ts.
go-specialist	ADDRESSED	VM-agent Go changes are narrowly scoped. Added tests for rejecting bearerless local exchange to non-primary workspaces and preserving bearer-authenticated non-primary workspace access. Local Go toolchain is unavailable in this workspace; CI VM-agent Go jobs must remain the compiler/test authority.
cloudflare-specialist	PASS	No wrangler/D1/KV/R2 config changes. Deployment must continue through GitHub Actions staging pipeline; Cloudflare API should be used only for observation. Runtime token mint remains in the API Worker and preserves D1-scoped workspace/project/installation lookups.

Agent Preflight

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

GitHub official documentation for GitHub App installation access tokens and repository-scoped installation tokens: https://docs.github.com/en/rest/apps/apps#create-an-installation-access-token-for-an-app. Existing in-repo contracts for assertRepositoryAccess, getInstallationToken, workspace callback auth, and VM-agent credential-helper behavior were also reviewed before changing the token boundary.

Codebase Impact Analysis

Credential-boundary changes span apps/api/src/routes/workspaces/runtime.ts, apps/api/src/routes/projects/_helpers.ts, workspace/task spawn gates under apps/api/src/routes/workspaces/, apps/api/src/routes/mcp/, apps/api/src/services/trigger-submit.ts, and VM-agent credential handling under packages/vm-agent/internal/server/, packages/vm-agent/internal/acp/, and packages/vm-agent/internal/bootstrap/. The final follow-up commit d68bc0c5 is scoped to _helpers.ts, git_credential.go, and git_credential_test.go.

Documentation & Specs

N/A: no public user-facing setup or behavior documentation changed; the security boundary and residual risks are documented in this PR body, and repo markdown outside public docs is not treated as user documentation.

Constitution & Risk Check

Checked fail-fast boundary behavior and no-hardcoded-values risk. The GitHub mint path fails closed before privileged token minting when owner OAuth/repo access/repo id checks fail; bearerless local VM-agent credential exchange is now constrained to the primary workspace only, preventing local cross-workspace token pivoting on warm nodes. Unknown repository providers now fail closed rather than silently bypassing GitHub owner-intersection checks.

Staging Verification (2026-06-08)

• Deployed staging with GitHub Actions run https://github.com/raphaeltm/simple-agent-manager/actions/runs/27141879596 from commit d68bc0c.
• Playwright UI verification used https://app.sammy.party/projects/01KJVGMWX26SGQ5DX94GMTJRQN/chat with marker pr1252-20260608135926.
• Elysia positive path succeeded: https://github.com/serverspresentation2025/elysia/pull/6 and https://github.com/serverspresentation2025/elysia/issues/7.
• Hono negative path in the same SAM project failed as expected: transcript reported all GitHub operations against serverspresentation2025/hono failed with GraphQL: Could not resolve to a Repository; no hono issue/PR URL appeared.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud