Files
PaperClipAI/doc
DottaandClaude Opus 5.5 7b1c01a8a8 Add a Cloud run liveness check for inspection authority (#22005)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A hosted deployment can let an inspection authority read an
instance's data on behalf of a running agent, with signed, short-lived
permits verified by the instance
> - Before it grants a read, the authority must know that the agent's
run is still live on the instance
> - The existing `/run-authority` check needs the agent's own
managed-run credential, so the authority cannot ask with its own
credentials
> - This pull request adds a signed run liveness question that the
authority asks with its own key
> - The benefit is that the authority can fail closed on stale runs
without holding any agent credential

## Linked Issues or Issue Description

**Subsystem affected**
Server: customer-success inspection routes

**Problem or motivation**
The inspection authority cannot ask "is run R of agent A in company C
live?" with its own credentials. Without an answer it must refuse.

**Proposed solution**
Add `POST /api/customer-success/v1/run-liveness` on the existing
customer-success router (mounted before actor middleware,
`Cache-Control: no-store`).

**Contract**
- Enabled only when `PAPERCLIP_CUSTOMER_SUCCESS_AUTHORITY_ENABLED=true`.
Requests with a `Cookie` or `Authorization` header are refused.
- Header `x-paperclip-cloud-inspection`: EdDSA JWS, header `{alg:
"EdDSA", typ: "paperclip-inspection-liveness+jwt", kid}`, verified
against `PAPERCLIP_CUSTOMER_SUCCESS_INSPECTION_JWKS`.
- Claims `{v: 1, iss: "paperclip-cloud", aud:
"paperclip-customer-success-liveness/v1", sub: <this stack id>, jti,
iat, exp <= iat + 60, companyId, agentId, runId}`. The stack id comes
from the runtime identity, the same as `/read`.
- The canonical JSON body `{agentId, companyId, runId}` must equal the
claims.
- Response `200 {version: 1, companyId, agentId, runId, active}`.


**Alternatives considered**
Reuse `/run-authority`. Rejected: it requires the agent's own
managed-run credential, which the authority does not hold.

## What Changed

- `server/src/routes/customer-success.ts`: new `/run-liveness` route and
`verifyRunLivenessQuestion`. The shared JWS checks (signature, kid, typ,
issuer, audience, subject, time window, jti) move into one helper that
`verifyInspectionPermit` also uses, with the same behavior. Each token
type has its own `typ` and `aud`, so a permit is never accepted as a
liveness question and the reverse.
- `server/src/services/customer-success-authority.ts`:
`customerSuccessRunLiveness` uses the run rules of
`customerSuccessRunAuthority` (agent in the company with status idle,
running or active; run of that agent is `running`, not finished, not
write-revoked). It does not need a managed identity key. It runs in a
read-only transaction and creates no actor, session, activity or key.

## Verification

- `cd server && npx vitest run
src/__tests__/customer-success-run-liveness.test.ts
src/__tests__/customer-success.test.ts
src/__tests__/customer-success-cloud.test.ts` (15 passed, 1 skipped
pre-existing).
- New tests: active answer with no new activity, API key or identity key
rows; inactive for a finished run, a write-revoked run, a paused agent,
another company and an unknown run; wrong `sub`, expired token, window
over 60 seconds, bad signature, inspection-permit `typ` and wrong
audience are refused; a body that differs from the claims (or has extra
fields) is refused; disabled authority, `Cookie` and `Authorization` are
refused.
- Existing permit tests pass after the verifier refactor.
- `npx tsc --noEmit -p server`.

## Risks

- Low risk. The route is off by default and needs a key the operator
configured. Answers only say active or not; they return no data beyond
the asked ids.
- No replay fence: a question is read-only and valid for at most 60
seconds.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file editing, test execution).

## 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
#` / `Refs #` 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 08:07:44 -06:00
..
…
…
…
…