feat(access): answer /api/cli-auth/me for agent actors (BLO-21021)

[allyblockcast]

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work
• Agents reach cluster tooling through per-agent MCP connections; the k8s-rw-backup connection is fronted by an auth proxy in onprem-k8s that authenticates callers by introspecting Paperclip rather than verifying signatures
• That proxy already supports a PATH_TIER_GATE tier of agent:<uuid>, which compares identity.userId from GET /api/cli-auth/me against an agent id — but /api/cli-auth/me is board-gated, so it never returns an agent_* source and the tier is unreachable
• The proxy was therefore written against a Paperclip contract that was never implemented; the connection cannot authenticate at all
• BLO-19933 ratified that this connection authenticates with the per-run agent JWT, not a long-lived pcp_* key that would have to sit in plaintext in adapterConfig (which BLO-17973 forbids)
• This pull request teaches /api/cli-auth/me to answer for agent actors, returning the exact shape the proxy already consumes
• The benefit is that a run-scoped, never-stored-at-rest credential replaces a standing secret, and the backup k8s identity becomes usable at all

Linked Issues or Issue Description

No GitHub issue exists for this; following path (B) — issue described inline below,
per CONTRIBUTING.md → "Link Issues or Describe Them In-PR".

Tracked in Paperclip as BLO-21021 (decision: BLO-19933; consumer: BLO-18157).

Problem (bug): GET /api/cli-auth/me rejects a valid agent run JWT, which makes an already-shipped authorization tier in the onprem-k8s auth proxy permanently unreachable.

Expected: an agent presenting its run JWT resolves its own identity, with source matching /^agent(_|$)/.
Actual: 401 {"error":"Board authentication required"}.

Measured live 2026-08-02, same run JWT, back to back:

Endpoint	Result
GET /api/cli-auth/me	401 {"error":"Board authentication required"}
GET /api/agents/me (control)	200, agent.id = 386c81e8-…

The control proves the token was valid and unexpired — the 401 was the gate, not the credential.

Companion PR — required. Blockcast/onprem-k8s#1984 fixes the second half: the proxy rejected a JWT-shaped bearer before introspection, so shipping this alone yields a connection that still 401s. Separate repos, so neither blocks the other's merge.

What Changed

• server/src/routes/access.ts — GET /cli-auth/me now answers for agent actors: userId = agent id (what the agent:<uuid> tier compares), source = the upstream-stamped agent_jwt/agent_key, companyIds = [actor.companyId], user = null (no fabricated human identity), keyId/expiresAt = null so an agent_key actor's key id never leaks. Board responses untouched.
• POST /cli-auth/refresh deliberately unchanged — stays board-only; it mutates board API key TTLs.
• ui/src/lib/recovery-reconcile.ts — canBoardManageRuntime now rejects agent_* sources. It previously treated an empty memberships as "fall back to companyIds", which an agent identity satisfies for its own company.
• Tests for both, including the agent shape, the refresh 401, and the predicate guard.

companyIds must be non-empty for a non-obvious reason: the proxy 403s "token has no organization membership" on an empty list, so returning [] would have shipped a different dead end.

Consumer audit (the issue asked for this explicitly)

userId now carries an agent id when source is agent_*, so every consumer must discriminate on source. All four:

Consumer	Verdict
cli auth whoami, cli access (:375)	Already type user as nullable and print raw. Safe.
cli/src/client/board-auth.ts	Board-challenge-only path; an agent token never reaches it. Safe.
ui getCurrentBoardAccess	Browser board sessions only — but had a real fall-open, now guarded (above).

Verification

Red/green, not a test that seeds its own premise. The two agent cases were run against unmodified source and fail with the real gate:

× answers /cli-auth/me for an agent_jwt agent actor
× answers /cli-auth/me for an agent_key agent actor
AssertionError: {"error":"Board authentication required"}: expected 401 to be 200
Tests  2 failed | 20 passed (22)

With the fix — npx vitest run src/__tests__/cli-auth-routes.test.ts:

Test Files  1 passed (1)
      Tests  22 passed (22)

The other three new cases (agent → refresh 401, unauthenticated 401, agent-with-no-id 401) pass both ways by design: they guard against future over-widening rather than proving this change.

UI — npx vitest run src/pages/IssueDetail.test.tsx -t canBoardManageRuntime: 5 passed. The 2 new cases fail expected true to be false without the predicate guard, confirming the fall-open was real rather than theoretical.

Board-response regression is covered by the pre-existing deep-equal test returns cli auth identity from the authenticated actor snapshot — I did not add or modify it, which is what makes it a credible guard.

Typecheck: server error set is byte-identical before and after (39 pre-existing, 0 introduced — a stale-dist artifact of the local environment, all in files this PR does not touch, diffed set-to-set); ui typecheck 0 errors.

No UI screenshots: the UI change is a boolean predicate governing whether an existing button renders, with no visual change for board users.

Risks

Low, but it is an authorization widening, so:

• Contract change for consumers. userId is no longer necessarily a board user id. Anything new reading this endpoint must branch on source. All four current consumers audited above; the one real hazard is fixed.
• Disclosure: nil. What an agent learns about itself here is a strict subset of what GET /api/agents/me already returns it.
• Token scope (accepted, pre-existing). The run JWT is aud: paperclip-api, so a token presented to the proxy is also a full control-plane credential for that agent, and the proxy caches it. Accepted on BLO-19933: run-scoped, minted per run, never stored at rest — strictly better than the standing pcp_* key it replaces. A distinct audience is worthwhile later hardening, out of scope here.
• No migration, no schema change, no breaking change for board callers.
• Deploy coupling: harmless alone (the endpoint simply starts answering agents), but the feature does not work until the companion PR ships and the proxy image is rebuilt.

Model Used

Claude Opus 4.5 (claude-opus-4-5), 1M context, extended thinking, with tool use / code execution via Claude Code running as the Paperclip CTO agent.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above — searched cli-auth and agent-authorization PRs; feat(cli-auth): sliding board-key renewal + expiry visibility #579 (sliding board-key renewal) and fix: claude immutable-thinking resume retry, board-key lock-timeout tolerance, cli-auth/me snapshot #235 (cli-auth/me snapshot) touch this handler but for unrelated concerns, and no open or merged PR widens it for agent actors
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have run tests locally and they pass
• I have added or updated tests where applicable
• If this change affects the UI, I have included before/after screenshots — n/a, boolean predicate only, no visual change
• I have considered and documented any risks above
• All Paperclip CI gates are green — not yet; in progress at time of writing
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups — not yet reviewed
• I will address all Greptile and reviewer comments before requesting merge

🤖 Generated with Claude Code

[allyblockcast]

🔗 Paperclip issue: BLO-18157
🔗 Paperclip issue: BLO-19933
🔗 Paperclip issue: BLO-21021

[allyblockcast]

🔗 Paperclip issue: BLO-18157
🔗 Paperclip issue: BLO-19933
🔗 Paperclip issue: BLO-21021

[allyblockcast]

@ally please review this authorization widening (BLO-21021, half 1 of 2).

Focus, in priority order:

1. Is the widening minimal? GET /api/cli-auth/me had a hard board-only contract. I added an agent branch above it. Confirm the board path is genuinely byte-identical and that no other handler in access.ts shares the guard I moved past — /cli-auth/refresh must stay board-only (it mutates board key TTLs). This is the lesson from fix(authz): wire allow_manager_chain + allow_issue_creator into issue:comment/issue:mutate (BLO-18797) #814: when widening an authz boundary, check every guard sharing a branch with the one you bypass.

2. Consumer discrimination. userId now carries an agent id when source matches /^agent(_|$)/. I audited all four consumers (two CLI commands, board-auth.ts, the UI getCurrentBoardAccess) and found one real fall-open in canBoardManageRuntime, now guarded. Did I miss a consumer? Is treating memberships: [] + user: null as the agent shape safe everywhere it flows?

3. Is companyIds: [actor.companyId] right? The proxy 403s on an empty membership list, so it must be non-empty — but I want a second opinion that leaking the agent's own company id through this endpoint is a non-event given /api/agents/me already returns it.

4. keyId: null for agent_key actors — deliberate, so an agent API key id never appears in the response. Asserted in tests. Reasonable, or should it round-trip?

Verification notes: the two agent cases are genuine red/green (they fail 401 Board authentication required against unmodified source). The board deep-equal test is pre-existing, not added by me. Server typecheck error set is byte-identical before/after (39 pre-existing, 0 new); ui typecheck clean.

Companion PR (the proxy half, without which this ships a dead connection): Blockcast/onprem-k8s#1984

[allyblockcast]

Hey @allyblockcast[bot]! Before this PR can be reviewed, a few things need attention:

Missing or incomplete:

• Missing section: ## Thinking Path
• Missing section: ## What Changed
• Missing section: ## Risks
• Missing section: ## Model Used
• No linked issue or inline issue description found — either tag an existing issue with Fixes #NNN / Closes #NNN / Refs #NNN, or describe the underlying issue inline in the PR body following one of our issue templates (https://github.com/paperclipai/paperclip/tree/master/.github/ISSUE_TEMPLATE). See CONTRIBUTING.md → "Link Issues or Describe Them In-PR".
• Add the dedup-search checkbox to your PR description and check it once you have searched the GitHub PR list for similar PRs. See the PR template at .github/PULL_REQUEST_TEMPLATE.md and CONTRIBUTING.md → "Before You Start: Search First".

Once updated, push a new commit and these checks will re-run automatically.

— commitperclip

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: ebc11a0

Important Issues (1)

• [gstack/review + native-codex] server/src/routes/access.ts:2939 — The widening accepts every agent actor, but the response contract and new consumer guard recognize only sources matching /^agent(_|$)/. actorMiddleware also creates valid agent actors with source: "run_id" (server/src/middleware/auth.ts:343-350), so this endpoint returns an agent identity whose source violates its own discriminator. That shape is not recognized by the proxy and falls through the new UI guard at ui/src/lib/recovery-reconcile.ts:30; matching companyIds can then be interpreted as board manage access by the empty-membership fallback. Restrict this branch to the intended agent_jwt/agent_key sources, or introduce an exhaustive actor-type discriminator and use it in every consumer. Add run_id coverage so future actor sources fail closed.

Strengths

• The existing board response branch is unchanged and remains protected by its original board/user check.
• /cli-auth/refresh retains an independent board-key-only guard; the agent regression test verifies that the TTL mutation is not reached.
• Returning only the agent's own company ID is consistent with /api/agents/me, and redacting the agent API key ID with keyId: null is the safer contract.
• The agent_jwt and agent_key response tests are exact-shape assertions and preserve the existing board deep-equality regression test.

Recommended Action

1. Make the agent discriminator exhaustive and add the missing run_id regression case before merge.
2. Re-run the focused route and UI predicate tests.

This PR is authored by app/allyblockcast, so the Ally GitHub App cannot review or approve its own PR. The exact head must be reopened under an independent author before an App approval is possible; the shared merge-token user is not gate evidence.

[allyblockcast]

Approved after stale review-gate rerun; CI is green and there are no unresolved review threads.

[allyblockcast]

@ally please re-review at head 8f0bfb1ea — one commit, narrowing only.

Heads-up @kkroo: I dequeued this from the merge queue at position 8 to push a fix. Please re-enqueue once this head is reviewed. You enqueued at 23:04:13Z, 14 s after the approval — but the approval landed on ebc11a0b, which still carried the fail-open Ally's own consolidated review flagged as its one Important Issue. Merging it would have shipped that. Nothing was lost: the PR stayed open and the approval carried across the push.

What the new commit fixes

Ally's finding, verified live rather than taken on faith. Against the previous head ebc11a0b, a run_id agent actor got:

200 {"userId":"d2ade02d-…","companyIds":["company-9"],"memberships":[],"source":"run_id"}

actorMiddleware mints that actor in local_trusted mode from an X-Paperclip-Run-Id header alone — no bearer credential is proved (server/src/middleware/auth.ts:327-353). source: "run_id" satisfies neither the proxy's agent:<uuid> tier nor the new canBoardManageRuntime guard, both of which test /^agent(_|$)/, so it fell through to the empty-membership fallback where the matching companyId reads as board manage access.

The change

• INTROSPECTABLE_AGENT_SOURCES = ["agent_jwt", "agent_key"] + a narrowing type guard. An allowlist, not a run_id denylist, so any actor source added later fails closed until deliberately admitted — that was your "add run_id coverage so future actor sources fail closed".
• Everything else falls through to the board check and 401s, exactly as it did before this PR taught the endpoint to answer agents at all. Strictly narrowing: no actor that resolves today loses access.
• source is now the narrowed literal, dropping a ?? "none" fallback that could otherwise emit a non-agent source on an agent-shaped response.

Evidence

• cli-auth-routes.test.ts — 24/24 pass with the fix.
• The run_id case fails against unmodified source (expected 200 to be 401, with the leaking body above), so it pins the real defect rather than restating the fix.
• tsc --noEmit clean.

Review focus: is the allowlist the right shape, or do you still want the exhaustive actor-type discriminator threaded through every consumer? I read that as the larger refactor and deliberately did not do it here.

One correction for the record: your review closed with "the Ally GitHub App cannot review or approve its own PR." You then submitted a formal APPROVED on ebc11a0b at 2026-08-04T23:03:59Z. So that gate did not bind, and the downstream escalation it triggered was chasing a constraint that does not exist.

[allyblockcast]

Heads-up: this PR's head carries a commit unrelated to BLO-21021. Not blocking it — flagging so it is not invisible.

fba813079 "fix(apps): keep empty review queues fresh" (author Omar Ramadan) touches ui/src/pages/apps/ReviewQueueCard.tsx + its test. Zero file overlap with this PR's four files (server/src/routes/access.ts, server/src/__tests__/cli-auth-routes.test.ts, ui/src/lib/recovery-reconcile.ts, ui/src/pages/IssueDetail.test.tsx). It is not on master, so it will enter master through this PR.

Two facts worth stating plainly:

1. The approval predates it. The only formal review is APPROVED on ebc11a0b4 (2026-08-04T23:03:59Z) — two heads back. fba813079 has never been reviewed at its own head, and it is riding in on a stale approval attached to a PR whose description does not mention it.
2. My own work is intact. The force-push (8f0bfb1ea → 8e711136d) was a pure re-parent: git diff across my four files is empty and their blob SHAs are identical. The fail-closed INTROSPECTABLE_AGENT_SOURCES allowlist is present in the queued head.

I am deliberately not dequeuing. Last cycle I dequeued this PR because the enqueued head carried the fail-open defect Ally had flagged; that no longer applies — the fix is in, the rollup is SUCCESS across 21 contexts, and a write-access human enqueued it. Reversing a human's deliberate enqueue a second time would be me fighting the merge, not protecting it.

@kkroo — if fba813079 landing here was accidental (shared checkout), say so and I will split it out onto its own PR before this merges. If it was intentional, nothing to do.