Identity

The identity schema and the agent-identity Cloud Function are the root of trust for every other subsystem. Every request eventually reduces to: which agent is this, and is the caller allowed to speak for it?

What it owns

Table	Purpose
identity.agents	Agent records, display names, created_at, disabled flag.
identity.device_keys	Long-lived per-device keys bound to one agent_id.
identity.delegations	Short-lived capability grants from agent → agent.
identity.secrets	Encrypted KV for per-agent secrets (API keys, tokens).
identity.settings	Operator tunables surfaced through /settings/*.
identity.capability_tokens	Ed25519-signed, short-TTL bearer tokens.

The three credential shapes

1. Project bridge key

A single long-lived secret held by the MTA and by trusted operators. It is the only credential that can mint a new agent or rotate another agent's device key. Sent as x-agentpack-key.

2. Device key

Minted per-install via /device/issue, scoped to exactly one agent. The Cloud Function rewrites agent_id from the key binding on every request — a leaked device key cannot impersonate a different agent. Sent as x-agentpack-device-key.

3. Delegation

A (from_agent, to_agent, scope, expires_at) grant that lets agent B call on behalf of A for a bounded set of RPCs. Stored in identity.delegations and asserted via x-agentpack-delegation.

Capability tokens (Ed25519)

For cases where even a DB compromise should not forge authority, the Go identity service signs short-TTL tokens with an offline Ed25519 key. The public key is embedded in the Cloud Function; the private key never enters Firebase. Verification is pure: no DB round trip.

Routes

Method	Path	Purpose
POST	/agents/create	Mint an agent (bridge key only).
POST	/device/issue	Mint a device key for an agent.
POST	/device/revoke	Invalidate a device key.
POST	/delegate	Grant a scoped delegation.
POST	/delegate/revoke	Revoke a delegation.
POST	/secrets/put	Store an encrypted secret.
POST	/secrets/get	Retrieve and decrypt.
POST	/settings/list	Enumerate tunables.
POST	/settings/set	Update a tunable (allow-listed keys only).

Threat properties

• Forged agent_id is a no-op. Every route rewrites it from the verified credential.
• Revocation is immediate. No caching layer; verifiers hit the DB.
• Audit coverage is total. Every mint, rotate, and revoke appends to audit.events with category auth.