feat(messaging): per-device person messaging credentials (0082)

AG
3d ago
+2122-28

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 web device. A bearer sign-in is its own desktop or cli device, with an id derived from the session. Device fields in the request body are ignored.
  • Mint. POST /v1/agents/{name}/device-tokens with the workspace key, 12 hour TTL, expected agent_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 is 502.
  • 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 is 400.
  • 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) or 403 (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_limited here also sends Retry-After; the hosted route sends none. Clients must not depend on it.
  • 403 device_revoked exists for client parity. No Control route leaves a row in that state today.

Differences from the shared token that clients see

  • The answer gains device and expiresAt.
  • 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
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 gains device and expiresAt.
  • 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.