Skip to content
Open
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ assigned at release.

## Unreleased

- Added: per-device person messaging credentials. `POST /api/v1/workspaces/{id}/messaging/identity/credential` now mints each signed-in device its own 12 hour Relaycast device token for the person's agent (`POST /v1/agents/{name}/device-tokens`, workspace key) instead of handing out the agent's shared token, and answers with `device` (`{id, name, kind}`, derived from the server-side session only, with the name as Relaycast returns it; an answer naming another device id or kind is `502`) and `expiresAt`. Tokens are stored encrypted in `person_device_credentials` (migration 0081), probed on every serve, re-minted inside one hour of expiry or when refused, and revoked at Relaycast when their sign-in ends (on sign-out, which waits at most 5 seconds for Relaycast, else by a sweep on messaging requests; the expiry is the backstop). Device rows are deleted with their sign-in; a removed member's tokens end with the person agent. An 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` inside the window; `Retry-After` is sent but clients must not depend on it, the hosted route sends none). A null or absent value changes nothing and other keys are ignored; only invalid JSON, a non-object body or a malformed hash (uppercase included) is `400 invalid_request`. A device revoked while its sign-in still authenticates answers `403 device_revoked` (no Control route produces this today; it matches the hosted service). A sign-in or membership that ends mid-mint answers `401` for a bearer device (`403` for the web device) and the minted token is revoked upstream. Mints take the same per-person lock as identity registration, recovery and member revocation, and re-check the sign-in and membership after the token is saved. A relay node token minted with a device token ends with that device token, so clients mint it again after a renewal. Desktop handoff tokens get `403 handoff_not_exchanged` / `403 handoff_not_capable`. Against a Relaycast without the device-token route (its exact `404 not_found` "Route not found" answer, agent confirmed) the shared token is served in the old shape and the fallback is logged. See docs/identity.md, "Person messaging credential".
- Fixed: MCP repository-filtered session summaries apply the first 200 characters of a repo-only filter in the session directory before pagination, while still accepting a 512-character repo value and verifying the full returned repository URL. This requires a sessions read API whose session directory list applies `projectContains` as a case-insensitive substring of project ID, catalog project key or recorded repository URL (directory migration `20261105034000` or later). Exact verification can still produce a short or empty page with a cursor. Relay agent listings now link an exact roster agent ID to its already-synced Desktop native session when the agent has no validated Relaycast session declaration. The optional session join is failure-open: the roster still returns a null session ID and attribution with `session_unavailable_reason` set to `enrichment_failed` or `ambiguous_sync`; an independently recorded metadata session kind is preserved. No migration.
- Changed: MCP `list_amp_threads` now returns `{ threads, truncated }` instead of a bare thread array. Clients that parse the old array must read the `threads` field; `truncated` reports whether Amp returned more than the first 100 threads.
- Changed: MCP `list_relay_agents` now returns the first at most 100 matching agents in relay order and adds `total_matching` and `truncated`; it previously returned the whole matching roster.
Expand Down
106 changes: 106 additions & 0 deletions docs/identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -1411,6 +1411,112 @@ capability scope:
Membership is checked live on every request and mint, so removing a person
from an organization takes effect on their next request.

### Person messaging credential

`POST /api/v1/workspaces/{id}/messaging/identity/credential` (scope
`cli:auth` or the browser session) hands the caller a Relaycast token for the
person's own human agent. Each signed-in device gets its own device token for
that one agent, minted with the workspace key
(`POST /v1/agents/{name}/device-tokens`). The agent's shared token never
leaves Control while Relaycast serves device tokens.

- The device comes from the server-side session only; the client cannot name
it (device fields in the body are ignored). The browser session (the `/cloud`
cookie) is the device `{id: "web", name: "web", kind: "web"}`, bound to no
sign-in. A bearer is its
own sign-in's device: kind `desktop` when the session carries a Desktop host
name (the handoff consent or an enrollment key exchange), otherwise `cli`.
The name is that host name with control and bidirectional formatting
characters removed, cut to 80 UTF-16 units on a grapheme boundary, or the
kind when empty. The id is `<slug of the name, up to 32 chars>-<first 8 hex
of sha256(session id)>`: lowercase `[a-z0-9-]`, at most 64 characters, never
Relaycast's reserved `unknown` or `direct`. The session id survives a token
refresh, so a refreshed sign-in keeps its device and token.
- Every mint asks for a 12 hour TTL (`ttl_seconds: 43200`) and sends the
expected `agent_id`; an answer naming another agent, or another device id
or kind, is refused. Relaycast cleans the device name it records (control
characters to spaces, whitespace collapsed, trimmed, at most 80
characters), so the name stored and served is the one in its answer. The
stored expiry is the earlier of Relaycast's `expires_at` and now + 12 hours.
- The answer is
`{identity: {name, agentId, token, relaycastUrl, device: {id, name, kind}, expiresAt}}`.
A stored token is served again while it is more than one hour from expiry
and Relaycast still accepts it (`GET /v1/agent` with the token, on every
request, never cached). A refused token is re-minted. While Relaycast is
unreachable the stored token is served as long as it is unexpired. A probe
answered `403 device_token_forbidden` is a `502`, never a re-mint.
- The request body is optional and read the same way as on the hosted
service, so one client works against both. No body, a JSON object without
`refusedTokenSha256`, or `"refusedTokenSha256": null` changes nothing;
other keys are ignored. A client that saw its token refused may send
`{"refusedTokenSha256": "<64 lowercase hex>"}`, the SHA-256 of that token.
When it matches the stored token (compared in constant time; neither the
hash nor the token is logged) the stored token is dropped without a probe
and a new one minted, at most once per device every 30 seconds, measured
from the stored token's `minted_at` by the database clock so every replica
agrees. Inside that window the answer is `429 rate_limited`. Control also
sends `Retry-After` (seconds), but clients must not depend on it: the
hosted route sends none. A hash that does not match takes the normal path
(probe, no forced mint). A body that is not JSON or not an object, or a
`refusedTokenSha256` that is not 64 lowercase hex (uppercase included), is
`400 invalid_request`. The shared-token fallback below ignores the field.
- A device row revoked while its sign-in still authenticates answers
`403 device_revoked`; sign in again for a new device. No Control route
leaves a row in that state today; the answer exists so clients handle the
same code as on the hosted service. The web device is bound to no sign-in,
so a new browser request mints it again.
- Mints, sweeps of revoked device tokens, the person agent's registration,
takeover and recovery, and member revocation take the same per-person
advisory lock, so a mint never interleaves with a recovery or a removal.
After a minted token is saved, the mint re-checks in the same transaction
that the sign-in is live and the person is still a member; if not, the row
is revoked and the token revoked upstream (or left to the sweep). A sign-in
row deleted while the mint was in flight leaves the token recorded with no
sign-in, already revoked, for the same upstream revoke.
- A device token is never presented to Relaycast's token rotation, recovery
or upgrade routes; recovery uses the workspace key and the shared token.
Relaycast refuses device tokens there with `403 device_token_forbidden`,
which Control treats as an error, never as a refused token to re-mint.
- A relay node token minted with a device token ends when that device token
is revoked, renewed or expires, or when the person agent is taken over. A
client mints its node token again after it receives a renewed device token.
- A mint refused with `404 agent_not_found` or `409 agent_identity_conflict`
recovers the person agent once (the same recovery as a refused shared
token, which ends every device token of the agent) and mints again. Any
other refusal, including `400` and `409 not_a_person_agent`, answers
`502 upstream_unavailable`.
- Tokens are stored encrypted in `person_device_credentials` (migration
0082), one row per workspace, person and device. A device row is deleted
with its sign-in row. Ending a sign-in (sign-out, workspace switch,
revoke-all, API token or Desktop credential revocation) revokes its rows in
the same transaction; revoke-all also revokes the web row. Relaycast is told
with `DELETE /v1/agents/{name}/device-tokens/{device}` (a `404` means
already gone) right after sign-out, which waits at most 5 seconds for it,
and by a bounded sweep on every messaging request until it confirms. A
token Relaycast never hears about still ends at its 12 hour expiry.
- Removing a membership deletes the person's sign-in rows, and with them
their device rows. Their device tokens end because member revocation
deletes the person agent at Relaycast, not by per-device revokes.
- A bearer sign-in that ends while its token is being minted answers `401`,
including when the membership is removed (the sign-in goes with it). The
web device is bound to no sign-in, so for it a membership removed during
the mint answers `403`. Either way the minted token is revoked upstream at
once, or by the sweep if that fails.
- A Desktop browser handoff token never holds a messaging credential: before
its PKCE exchange it answers `403 handoff_not_exchanged`, after it
`403 handoff_not_capable`. The session the exchange issues is the device.
- A Relaycast release without device tokens is detected only by its own
missing-route answer to the mint (`404` with code `not_found` and message
`Route not found`) while a workspace-key lookup still finds the person's
agent under the expected id. Control then answers with the shared person
token in the old shape (`{name, agentId, token, relaycastUrl}`, no `device`
or `expiresAt`) and logs
`[selfhost-api] messaging device credential fallback: Relaycast has no device-token route`
with `workspaceId` and `deviceKind`. Any other answer is not a missing
route.

Gate-only installs answer `403 gate_only` instead (below).

### Gate-only installs (relaygate)

On a gate-only install, relaygate is the only public way into Relaycast and
Expand Down
44 changes: 44 additions & 0 deletions migrations/0082_person_device_credentials.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
-- Per-device person messaging credentials (docs/identity.md, "Person messaging credential"): each signed-in
-- device of a person gets its own device-scoped Relaycast token for the person's human agent, minted with the
-- workspace key. One row per (workspace, person, device); the token is encrypted with the keyring like
-- person_identities.token_ciphertext. A row is served only while it is not revoked, still names the person's
-- current agent on the workspace's current Relaycast workspace, and is outside the renewal margin of expires_at.
CREATE TABLE IF NOT EXISTS person_device_credentials (
id uuid PRIMARY KEY,
workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-- Derived server-side: `web` for the browser session, otherwise `<slug of the name>-<8 hex of the sign-in>`.
device_id text NOT NULL,
device_name text NOT NULL,
device_kind text NOT NULL CHECK (device_kind IN ('desktop', 'cli', 'web')),
-- The sign-in session the token belongs to; NULL for the web device. Session rows are never deleted by the
-- application (sign-out sets revoked_at), so the cascade only fires with the user, membership or workspace.
session_id uuid REFERENCES token_sessions(id) ON DELETE CASCADE,
relaycast_workspace_id text NOT NULL,
-- The person agent the token was minted for; agent_name is the path segment the upstream revoke addresses.
agent_name text NOT NULL,
agent_remote_id text NOT NULL,
token_ciphertext text NOT NULL,
expires_at timestamptz NOT NULL,
-- When the stored token was minted. A client report of a refused token forces at most one mint per device per
-- 30 seconds, decided against this column so every replica agrees.
minted_at timestamptz NOT NULL DEFAULT now(),
-- Set in the same transaction that ends the sign-in session, removes the member or abandons a mint.
revoked_at timestamptz,
-- Set once Relaycast confirmed the device token is gone (revoked, or 404), or when the agent itself was deleted.
upstream_revoked_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (workspace_id, user_id, device_id)
);

-- Ending a sign-in session revokes the live rows bound to it.
CREATE INDEX IF NOT EXISTS person_device_credentials_live_session_idx
ON person_device_credentials (session_id)
WHERE revoked_at IS NULL;

-- The upstream revocation sweep reads revoked rows Relaycast has not confirmed yet, least recently tried first
-- (a failed attempt moves updated_at), so one unreachable Relaycast workspace cannot hold up the rest.
CREATE INDEX IF NOT EXISTS person_device_credentials_upstream_pending_idx
ON person_device_credentials (updated_at)
WHERE revoked_at IS NOT NULL AND upstream_revoked_at IS NULL;
Loading
Loading