feat(identity): agent identities with signed delegation certificates

[geekgonecrazy]

Lets you issue a keyed identity to an agent and have it work on your behalf,
bounded by a grant you sign, revocable in one command.

Server side: atomicdotdev/atomic-storage#100 · Design: docs/agent-identity-design.md

---

The decision everything follows from

Grants are presented, not registered.

A grant is a certificate signed by a key the server already trusts — yours, from
registration — so it proves itself the moment you hand it over. The agent
carries it in an Atomic-Delegation header; the server verifies it on the spot.
Same shape as JOSE x5c, SPIFFE SVIDs, UCANs, macaroons.

Operation	Frequency	Server call?
Register an agent identity	once	yes
Issue / extend / widen a grant	often	no
Revoke a grant, or an epoch	rare	yes

The point is not the saved round trip. It is that a four-hour grant scoped to
one project now costs exactly what a year-long grant scoped to everything
costs. There is no lazy path left, so short-and-narrow stops being the
disciplined choice and becomes the obvious one.

Withdrawal is the asymmetry: a credential the holder possesses cannot prove its
own revocation, so that is the one thing that must reach the server.

What exists today, for contrast

Agent attribution is a naming convention. atomic-agent/src/identity.rs derives
an author by plus-tagging the human's identity — claude+60f5 <lee@atomic.dev>
— and signs with the human's key. Legible in log and blame, worth
nothing cryptographically, bounded by nothing.

The Delegation model in atomic-identity has been there since the initial
commit and was never wired to anything: zero call sites, no persistence, no CLI,
no signing (Delegation::new took &Identity, so it could not sign —
signature was hardcoded None), and AgentEnvelope.delegation_id was always
None. This connects it end to end.

Three invariants

1. An agent can never exceed its human. Effective permission is
   your grants ∩ the grant's scope — an intersection, never a union. Losing
   your org access takes your agents with you on the next request, with no
   cascade to run.
2. Possession is not authority. Holding the agent key proves you are the
   agent and says nothing about what it may do.
3. One signature format. Grants ride the existing eddsa-jcs-2022 path in
   atomic-canonical, same as intents and memories. Delegation::signing_data's
   ad-hoc byte concat is deleted rather than kept as a second path to drift.

Try it

agent is what you register once. grant is what you issue often. That split
is the model.

# once — the only part that touches the server
$ atomic identity agent create claude --agent-type claude-code

# often — no server call, so make them short and narrow
$ atomic identity grant new alice+claude --can record,push --projects acme/api --expires 4h

Three ways to get a grant to an agent, in the order you will want them:

# 1. nothing to install, nothing to clean up
$ export ATOMIC_DELEGATION=$(atomic identity grant new alice+claude --expires 1h --export)

# 2. a file
$ atomic identity grant new alice+claude --expires 8h -o grant.json
$ atomic identity grant load grant.json          # on the agent's machine

# 3. piped
$ atomic identity grant new alice+claude --export | ssh runner 'atomic identity grant load -'

Extending something that was already scoped right, without retyping it:

$ atomic identity agent renew alice+claude --expires 8h

renew carries the existing --can and --projects forward and only changes
the expiry. Like every issuance it reaches no server; --publish sends it up
for listings only. Note it does not withdraw the previous grant — reissuing
with a tighter scope leaves the wider one valid until its own expiry, so a
narrowing needs agent revoke (which bumps the epoch) to bite immediately.

Withdrawal, inspection, and the key-compromise button:

$ atomic identity agent revoke alice+claude --reason "laptop lost"
$ atomic identity grant revoke --all-mine        # everything you ever issued
$ atomic identity grant verify <urn> --offline   # no server needed
$ atomic identity agent list

For a key generated somewhere you will never see it:

# on the runner
$ atomic identity new ci-runner --type agent --request-delegation > request.json
# on your machine — verifies the self-signature, then countersigns
$ atomic identity delegate --request request.json --can record,push --expires 7d -o grant.json
# back on the runner
$ atomic identity grant load grant.json

Withdrawal needs three mechanisms, not one

Because grants are not registered, nothing can enumerate what is outstanding
— so a deny-list keyed by id is not sufficient on its own.

	Reaches	Use when
Expiry	that grant	always — the backstop that needs nothing
Deny-list	one grant, by id	you know which one to kill
Epoch	everything issued before an instant	you don't, or there is no list

agent revoke bumps the agent's epoch and deny-lists known grants. The epoch
is the part that actually stops the agent — it reaches grants issued from a
laptop you no longer have. It also closes the narrowing gap that an earlier
revision of this PR had: issuing a tighter grant and bumping the epoch kills the
old broader one at once, instead of leaving it live until its own expiry.

grant revoke --all-mine is the key-compromise button. If your signing key leaks
an attacker can mint grants nobody knows exist, and a time-based statement is the
only thing that reaches them. It refuses --local, because it is a claim only
the server can make.

Review notes

Start at atomic-canonical/src/delegation.rs (the certificate, its
verification, and the wire encoding), then atomic-cli/src/commands/delegation.rs
— the single place that answers "which grant applies right now".

• Grants carry delegatorKey as well as delegateKey. did:atomic is
  base32(blake3(pubkey)) — a fingerprint, not reversible — so without the
  delegator's did:key a machine holding only the agent's key (a CI runner,
  anyone auditing a clone) has nothing to verify the signature against. Note
  precisely what verify_self_contained proves: integrity, not trust. That
  the key belongs to who you think is settled by comparing against a key you
  already trust — which is what the server does with its registered copy.
• A broken ATOMIC_DELEGATION fails rather than falling back to the store.
  Silently using a different grant than the one asked for is how an agent ends
  up acting under a scope nobody intended. Empty is treated as unset, so a stray
  ATOMIC_DELEGATION= in a shell profile breaks nothing.
• grant new binds to the active server by default, with --any-server as
  the deliberate opt-out. An unbound grant is valid against every deployment, so
  binding has to be what happens when you say nothing — and an unresolvable
  profile is an error, not a silent "any".
• DID derivation moved into atomic-identity (IdentityId::to_did,
  PublicKey::to_did_key). The DID is the identity's identifier, so one
  derivation means a did:atomic can never disagree with an IdentityId.
• agent_identity is a separate config field from identity. Enrollment
  and revocation authenticate as the human; recording and pushing authenticate
  as the agent. One field could not express "this machine holds both keys",
  which is the normal laptop.
• Recording keeps the author line identical (claude+60f5). Legibility was
  never the problem; the key behind it was. A mistyped or non-agent identity
  falls back rather than failing — signing agent work with the human's key
  while calling it keyed attribution is worse than the honest fallback.
• atomic identity register refuses agent identities. Registration mints a
  tenant named for the identity; an agent must never own one.

Something to know about key storage

IdentityStore::save_secret_key writes encryption = "none" on both
branches — password protection is an unimplemented TODO. Every secret key on
disk is base64 plaintext at 0600, and that predates this change.

Rather than pretend otherwise, the design leans on making agent keys cheap to
rotate — which is exactly what "issuing is free" buys. Real encryption for
human parent keys is a separate, still-needed fix, called out in the design
doc.

Also in this PR

The first commit (7d06c24) is four pre-existing fixes that were already in the
working tree, kept separate so this work stays reviewable on its own: bare
:::ref target canonicalization (the shape intent new --review itself
scaffolded produced an edge triage could never see), vault paths treated as
lifecycle rather than undeclared work, and intent title in --json.

Testing

cargo test --workspace under RUSTFLAGS=-Dwarnings exits 0 — 42 test
binaries. cargo clippy --workspace -- -D warnings, cargo fmt --check, and
RUSTDOCFLAGS=-Dwarnings cargo doc --workspace --no-deps clean.

Coverage worth knowing about: scope widening breaking the proof (the attack this
exists to stop), a swapped delegateKey and a swapped @id, request
self-signature as proof of possession, revocation only by the delegator, the
delegated JWT kid/sub inversion, transport round-trip and determinism
(content-hash caching depends on it), the 16KB cap rejecting before parse, and
four ATOMIC_DELEGATION cases — used, wrong-agent-refused,
broken-does-not-fall-back, empty-ignored.

[geekgonecrazy]

Reworked: grants are presented, not registered

Pushed a457abe. The earlier design had the round trip on the wrong operation —
a grant had to be POSTed to the server before an agent could use it, which made
a short-lived narrowly-scoped grant more work than a standing broad one.
Backwards from the practice we want.

A certificate is signed by a key the server already trusts, so it proves itself.
It now travels with the request in an Atomic-Delegation header and is verified
on arrival — the shape of JOSE x5c, SPIFFE SVIDs, macaroons.

Operation	Frequency	Server call?
Register an agent identity	once	yes
Issue / extend / widen a grant	often	no
Revoke a grant, or an epoch	rare	yes

The point is not the saved round trip. It is that a four-hour grant scoped to
one project now costs exactly what a year-long grant scoped to everything costs,
so short-and-narrow stops being the disciplined choice and becomes the obvious
one.

Getting a grant to an agent

# nothing to install
$ export ATOMIC_DELEGATION=$(atomic identity grant new alice+claude --expires 1h --export)

# a file
$ atomic identity grant new alice+claude --expires 8h -o grant.json
$ atomic identity grant load grant.json

# piped
$ atomic identity grant new alice+claude --export | ssh runner 'atomic identity grant load -'

--export writes only the wire form to stdout (summary to stderr) so command
substitution captures exactly the grant.

agent is what you register once; grant is what you issue often. That split
is the model, and the command surface now reflects it.

Two judgement calls worth review

A broken ATOMIC_DELEGATION fails rather than falling back to the store.
Silently using a different grant than the one asked for is how an agent ends up
acting under a scope nobody intended. Empty is treated as unset, so a stray
ATOMIC_DELEGATION= in a shell profile breaks nothing.

Withdrawal now has a hard network dependency, and says so. agent revoke
bumps the agent's epoch and deny-lists known grants. The epoch is the part
that actually stops the agent — it reaches grants issued from a laptop you no
longer have, which a deny-list keyed by id cannot. When the server is
unreachable the output distinguishes the two outcomes explicitly: known grants
are refused locally straight away, grants it has never seen remain valid.

This also closes the narrowing gap from the earlier design: issuing a tighter
grant and bumping the epoch kills the old broader one immediately instead of
leaving it live until its own expiry.

grant revoke --all-mine is the key-compromise button. If your signing key
leaks an attacker can mint grants nobody knows exist, and only a time-based
statement reaches them.

Testing

cargo test --workspace under RUSTFLAGS=-Dwarnings exits 0. Clippy -D warnings, cargo fmt --check and RUSTDOCFLAGS=-Dwarnings cargo doc clean.

New coverage: transport round-trip and determinism (content-hash caching depends
on it), the 16KB cap rejecting before parse, a tampered certificate surviving
transport but failing verification, and four env-var cases — used, wrong agent
refused, broken-does-not-fall-back, empty-ignored. Every test in
commands::delegation is now serialized; they touch a process-wide env var and
were stepping on each other in parallel.