feat(whoami): user_id for agents enrolled through a Control principal

Merged
KH
5d ago
+101-2

What

GET /v1/whoami now includes user_id for agents enrolled with a relay-control credential:

  • device-enrolled (sh_at_): the user the device token introspected as
  • launched (sh_lt_): the launching person (the launch credential's sub)
  • enrollment-key agents: omitted
{"agent_id": "ag_...", "name": "<name>", "gid": 11, "groups": [], "group_names": ["local"], "guest": false,
 "user_id": "<control user id>",
 "relaygate": {"agent": "<name>", "groups": ["local"]}}

How

No schema change: the introspected user id is already persisted with the registration as the agent's key id (device:<userId> / launch:<userId>), which policy validation reserves (no enrollment key may use device:* / launch:*), and only the same person can recover the name. controlUserId(agent) reads it back. Self only (whoami answers for the caller's token), and kept off the relaygate provenance card that is stamped on forwarded messages.

Why

relay-control verifies gate-only desktop identities via /v1/whoami and will enforce whoami.user_id == caller user id once present, closing an ownership gap.

Tests

test/control.test.ts "GET /v1/whoami: the Control user behind the caller": device-enrolled includes user_id; launched includes the launching person's id (also after token refresh); key-enrolled omits it; two callers each see only their own; a file-backed store survives a restart with user_id intact and no re-introspection. npm run typecheck and npm test (158) pass.

Docs: docs/contract.md new "Who am I" subsection. README doesn't document whoami.

🤖 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

GET /v1/whoami now includes user_id for agents enrolled with a relay-control credential, closing an ownership gap so relay-control can enforce whoami.user_id == caller user id.

  • Device-enrolled (sh_at_) agents report the user their token introspected as; launched (sh_lt_) agents report the launching person's id, unchanged after token refresh.
  • Key-enrolled agents omit user_id, and it never appears on the relaygate provenance card.
  • No schema change: the id is read back from the already-persisted key id, so it survives restarts without re-introspection.