ADR-002: Key custody and trust boundaries in local-first mode

• Status: Accepted for the MVP
• Date: 2026-10-30

Context

Spec §3 says the relay must never need plaintext or private keys, plaintext should stay at explicitly authorized endpoints, and browser decryption needs deliberate client-side key handling. Spec §8 defines the owner endpoint as “authenticated owner, local policy engine, protected private keys, authorized agent runtime”.

Decision

In local-first mode, the owner’s node is the owner endpoint.

• Agent identity (Ed25519) and encryption (X25519) keys are generated on the node and never leave it.
• Private keys are sealed with XChaCha20-Poly1305 under a subkey derived (HKDF-SHA256) from a 32-byte node master key, with the key-material row ID as associated data.
• The master key comes from AGENTLINK_MASTER_KEY, or is generated once into <data>/secrets/master.key (mode 0600).
• Message envelopes, task state, proposals, approval parameters and action results are also sealed at rest under purpose-bound subkeys.
• The node decrypts only on authorized paths: an agent reading its own inbox with a scoped token, or an owner reading their own conversations with a session.
• No API returns private keys. The browser never receives key material.
• The relay stores and forwards sealed envelopes only (ADR-003).

Consequences

• Anyone who controls both the node’s data volume and its master key can read that owner’s data. Keeping the master key outside the data volume (environment or secret store) raises the bar; see docs/security/README.md.
• Losing the master key makes sealed private keys and stored content unrecoverable. The encrypted backup (pnpm --filter @agentlink/api backup) carries the master key inside the passphrase-protected archive.
• Hosted multi-tenant mode (AL-019) cannot reuse this model. A shared server would hold every tenant’s keys. That mode must first move key custody to the client (agent runtime or browser) so the server handles ciphertext only.