Skip to content

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

Open
agent-relay-code[bot] wants to merge 9 commits into
mainfrom
feat/person-device-credentials
Open

agent-relay-code[bot] wants to merge 9 commits into
mainfrom
feat/person-device-credentials

Conversation

@agent-relay-code

@agent-relay-code agent-relay-code Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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.

Written for commit 795edd2. Summary will update on new commits.

View guided diff Turn on auto-fix

layered-control-agent-host and others added 5 commits November 19, 2026 12:36
Each signed-in device gets its own Relaycast device token for the person's
agent instead of the agent's shared token. Tokens are stored encrypted in
person_device_credentials (migration 0080), bound to the sign-in session,
probed on every serve, renewed inside one hour of expiry and revoked when
the sign-in ends.

Co-Authored-By: Claude <noreply@anthropic.com>
…e the device Relaycast returns, bound the sign-out revoke

- A sign-in row deleted while its device token is being minted no longer
  fails the save: the token is recorded revoked with no sign-in, the
  request answers 401 and the token is revoked upstream or by the sweep.
- The credential body is read like the hosted route: a null or absent
  refusedTokenSha256 is no report and other keys are ignored.
- The device served and stored is the one in Relaycast's mint answer; an
  answer naming another device id or kind is refused.
- Sign-out waits at most 5 seconds for the upstream device-token revoke.
- Tests no longer assume a device token prefix.
- Schema manifest regenerated for migration 0080.

Co-Authored-By: Claude <noreply@anthropic.com>
Another open change uses 0080. Schema manifest regenerated.

Co-Authored-By: Claude <noreply@anthropic.com>
@agent-relay-code agent-relay-code Bot added the merge-train:hold Do not merge until the owner gives the go label Nov 19, 2026
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8399e1a0-f926-4de5-9e15-5488e17fb194

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@agent-relay-code

Copy link
Copy Markdown
Contributor Author

Local checks, run one at a time under the host's memory guard.

On 81048b1 (the content of the pushed head before the migration was renumbered): typecheck clean; person-device-credentials 28/28, messaging 33/33, desktop-mcp-credentials 11/11, app 2/2, admin 13/13.

On c23ea09 (pushed head; only the migration file name, two text mentions and the manifest differ): person-device-credentials 28/28, messaging 33/33; schema manifest regenerated with the PostgreSQL 15 harness and the verify run passed.

Not run locally: the full suite. CI on this head is the complete run.

@agent-relay-code

Copy link
Copy Markdown
Contributor Author

Contract re-check: the upstream device-token route now has an accepted head. I compared it with the head this PR was written against. The mint request and its 201 body (agent_id, device, token, expires_at), the revoke route and its { revoked } body, and the error codes this PR maps are unchanged; the upstream changes since then are about which sockets are closed when a device token dies. No change is needed here.

Exact-head CI on c23ea09 is green (both required jobs). This PR still carries merge-train:hold. The feature needs a Relaycast engine release that contains that route before it does anything on a site.

layered-control-agent-host and others added 2 commits November 19, 2026 16:47
Main took 0081 for another table. The migration file is renamed, the
identity doc names 0082 and the verifier schema manifest is regenerated
through the synthetic PostgreSQL 15 harness.

Co-Authored-By: Claude <noreply@anthropic.com>
CHANGELOG.md keeps both sides.

Co-Authored-By: Claude <noreply@anthropic.com>
@agent-relay-code agent-relay-code Bot changed the title feat(messaging): per-device person messaging credentials (0081) feat(messaging): per-device person messaging credentials (0082) Nov 19, 2026
layered-control-agent-host and others added 2 commits November 19, 2026 17:31
…n-device-credentials

CHANGELOG conflict only: both Unreleased entries kept.

Co-Authored-By: Claude <noreply@anthropic.com>
…ntials

CHANGELOG conflict only: both Unreleased entries kept, main wording of the
session summaries bullet.

Co-Authored-By: Claude <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-train:hold Do not merge until the owner gives the go

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants