docs(nips): NIP-AK — Agent Keyrings (owner-sealed, rotating credential delivery)

[akeemjenkins]

What

A spec-first draft NIP, in the NIP-AE precedent (#575): Agent Keyrings, kind:30180 — owner-authored, NIP-44-encrypted, addressable events that deliver an agent's credentials (env vars, a subscription OAuth token, MCP server grants, small credential files) wherever its harness runs.

NIP-OA made identity travel. NIP-AE made memory travel. This proposes making the third machine-bound thing travel: with a keyring, a harness holding the agent's key can materialize its full working credential set on any executor (a laptop, a fleet container, a buzz-backend-kubernetes pod), and the machine becomes disposable.

Design highlights

• Rotation is republication. One blinded address per grant; the newest head is the live credential. The canonical scenario the spec is built around: the owner re-runs /login in Claude Code on their laptop; an owner-side source watcher republishes the sealed head within seconds; every executor converges on push (a live keyring subscription on the same socket as mentions), a mandatory re-query-on-auth-failure rule heals the mid-turn race, and boot-time head fetch collapses any number of missed rotations for offline agents into one head. No catch-up protocol, no user ceremony.
• Owner-authored only, enforced pre-decryption. Agents consume grants and cannot mint, widen, or re-target them; a dedicated kind (vs. a slug convention on 30174) keeps that authorship rule checkable from kind + author alone. A compromised agent key cannot grant itself anything.
• The MCP grant list is the agent's tool allowlist, which turns today's out-of-band credential plumbing (wrapper scripts, hand-edited env) into visible, revocable, rotating grants. The client-behavior section sketches the per-agent keyring panel this enables.
• Blinded addressing per NIP-AE (distinct domain prefix), slug round-trip binding against entry-swapping relays, created_at monotonicity for rollback resistance, tombstone heads for revocation, and a hard rule that the identity key never rides its own keyring.

Kind number

30180, verified unassigned in this repo's kind.rs (30174–30179 are engrams, personas, teams, managed agents, team catalogs, private managed agents) and in the upstream nostr-protocol/nips table as of 2026-08-15. An earlier draft of this spec used 30176 and was renumbered after re-checking against current main — an accidental demonstration of why the registry-first rule in AGENTS.md earns its keep.

Scope of this PR

Docs only — no kind.rs reservation, no implementation. If the direction lands, the natural follow-ups are a buzz keyring CLI surface (pack/grant/rotate/revoke), the harness materialize + heal path in buzz-acp, and the desktop keyring panel with source watchers. Happy to iterate on any of it here.

🤖 Generated with Claude Code