feat(messaging): per-device person messaging credentials (0082)
What
POST /api/v1/workspaces/{id}/messaging/identity/credential now gives each signed-in device its own Relaycast device token for the person's agent, instead of the agent's shared token. This is the relay-control side of the per-device person messaging credential that the hosted service has; one client works against both.
- Device from the session only. The browser session is the
webdevice. A bearer sign-in is its owndesktoporclidevice, with an id derived from the session. Device fields in the request body are ignored. - Mint.
POST /v1/agents/{name}/device-tokenswith the workspace key, 12 hour TTL, expectedagent_id. The device served and stored is the one in Relaycast's answer (it cleans the name); an answer naming another agent, device id or kind is502. - Storage.
person_device_credentials(migration 0082), tokens encrypted, one row per workspace, person and device. Rows are deleted with their sign-in row. - Serve. A stored token is probed on every request, re-minted inside one hour of expiry or when Relaycast refuses it, and served unprobed only while Relaycast is unreachable.
- Refused-token report. Optional body
{"refusedTokenSha256": "<64 lowercase hex>"}forces a re-mint when it matches the stored token, at most once per device per 30 seconds (429 rate_limited). Null or absent is no report; other keys are ignored; invalid JSON, a non-object or a malformed hash is400. - Revocation. Every path that ends a sign-in (sign-out, workspace switch, revoke-all, API token and Desktop credential revocation) revokes its device rows in the same transaction. Relaycast is told right after sign-out (bounded at 5 seconds) and by a bounded sweep on messaging requests; the 12 hour expiry is the backstop. Removing a member ends the tokens by deleting the person agent.
- Races. Mints take the per-person lock that registration, recovery and member revocation take, and re-check the sign-in and membership after the token is saved. A sign-in or membership that ends mid-mint answers
401(bearer) or403(web) and the minted token is revoked upstream. A sign-in row deleted mid-mint leaves the token recorded, revoked, for the same upstream revoke. - Fallback. Against a Relaycast without the device-token route (its exact
404 not_found"Route not found" answer, with the agent confirmed by lookup) the shared token is served in the old shape and the fallback is logged. - Desktop handoff tokens get
403 handoff_not_exchanged/403 handoff_not_capable. A gate-only install mints no device token.
Details: docs/identity.md, "Person messaging credential".
Not final
- The Relaycast device-token route is not merged upstream and its head is not final. This is coded against its current contract; the HTTP shape is not expected to change, but if it does this PR changes with it. Until a Relaycast with the route is deployed, every install takes the shared-token fallback, so behaviour is unchanged.
429 rate_limitedhere also sendsRetry-After; the hosted route sends none. Clients must not depend on it.403 device_revokedexists for client parity. No Control route leaves a row in that state today.
Differences from the shared token that clients see
- The answer gains
deviceandexpiresAt. - A relay node token minted with a device token ends with that device token, so clients mint it again after a renewal.
Checks
- Local, on the pushed head: typecheck;
test/person-device-credentials.test.ts,test/messaging.test.ts,test/desktop-mcp-credentials.test.ts,test/app.test.ts,test/admin.test.ts(results in the first comment). - Schema manifest regenerated with the PostgreSQL 15 harness and verified.
- No live proof: no deployed Relaycast serves the route.
Hold
merge-train:hold: the upstream route is not final, and another open PR also adds a migration; whichever lands second keeps its own number only if they still differ.
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
The messaging credential endpoint now mints each signed-in device its own 12-hour Relaycast device token for the person's agent, instead of serving the agent's shared token. The device comes from the server-side session only; device fields in the request body are ignored.
Minting and storage
- The device served and stored is the one in Relaycast's answer; an answer naming another agent, device, or kind returns 502.
- Tokens are encrypted in
person_device_credentials(migration 0082), re-minted within an hour of expiry or when refused, and the response gainsdeviceandexpiresAt. - A refused-token report forces a re-mint at most once per device per 30 seconds.
Revocation and scope
- Every path that ends a sign-in revokes its device rows in the same transaction, with an upstream revoke and a bounded sweep as backstop.
- Against a Relaycast without the device-token route, the shared token is served in the old shape.
- The upstream route is not final and the PR is on hold; until one is deployed every install takes the fallback, so behavior is unchanged.