NITS_focus.md
1 # NIST NCCoE Alignment: Documentation Gaps 2 3 Assessment of README and docs against the NIST "Software and AI Agent Identity and Authorization" concept paper. 4 5 --- 6 7 ## What already maps well (but isn't framed for the NIST audience) 8 9 | NIST Concern | Auths Feature | Where it lives | 10 |---|---|---| 11 | Agent identification | `did:keri` (stable), `did:key` (per-device), `signer_type: Agent/Human/Workload` | `docs/architecture/identity-model.md`, `docs/architecture/attestation-format.md` | 12 | Key management lifecycle | KERI inception, rotation, revocation, pre-rotation | `docs/getting-started/identity-lifecycle.md`, `docs/getting-started/trust-model.md` | 13 | Delegation of authority | `delegated_by` field, attestation chains, `verify_chain()` | `docs/architecture/attestation-format.md` (briefly) | 14 | Least privilege | Capability-scoped attestations, expiration | `docs/architecture/attestation-format.md` | 15 | Non-repudiation / audit | KEL is tamper-evident hash chain, dual signatures, Git commit history | `docs/getting-started/trust-model.md`, `docs/architecture/git-as-storage.md` | 16 | Offline/zero-trust verification | Stateless `auths-verifier`, no server needed | `docs/architecture/crates/auths-verifier.md` | 17 18 The building blocks exist. The problem is they're framed entirely around "developers signing commits" -- the NIST paper cares about **agents acting autonomously in enterprise systems**. 19 20 --- 21 22 ## Gaps: What's missing or buried 23 24 ### 1. No agent-specific framing anywhere 25 26 **Problem:** The README says "Decentralized identity for individuals, AI agents, and their organizations" in the first line, then never mentions agents again. The NIST audience needs to see agents as first-class citizens, not an afterthought. 27 28 The `signer_type` enum (`Human`, `Agent`, `Workload`) exists in code and is mentioned once in `attestation-format.md` but is never explained or motivated. 29 30 **Tasks:** 31 32 - [x] **README.md** -- Add a section "Agent & Workload Identity" after "What can you do with Auths?" showing: 33 - How a CI runner or AI agent gets a `did:keri` identity 34 - How an org issues a scoped attestation to an agent (`signer_type: Agent`, time-limited, capability-restricted) 35 - How a human delegates authority to an agent with `delegated_by` 36 - Keep it to ~20 lines with a code example 37 38 - [x] **docs/architecture/attestation-format.md** -- Expand the `signer_type` field documentation. Currently it's one cell in a table. Add a subsection "Signer Types: Human, Agent, Workload" explaining: 39 - When to use each type 40 - How `signer_type` enables policy engines to distinguish human vs. automated actions 41 - Brief example of an agent attestation JSON 42 43 ### 2. No delegation walkthrough 44 45 **Problem:** The NIST paper asks: "How do we handle delegation of authority for 'on behalf of' scenarios?" and "How do we bind agent identity with human identity to support 'human-in-the-loop' authorizations?" 46 47 Auths has `delegated_by`, attestation chains, and `verify_chain()` -- but there's no doc showing the full delegation flow. 48 49 **Tasks:** 50 51 - [x] **docs/getting-started/delegation.md** (new file) -- A short guide: 52 - Human creates identity, links device 53 - Human issues attestation to an AI agent with `delegated_by` pointing to the human's attestation 54 - Agent acts, signs artifacts 55 - Verifier walks the chain back to the human 56 - Show the JSON at each step 57 - Explain how capabilities narrow at each delegation hop 58 - Link from README's new "Agent & Workload Identity" section 59 - Add to mkdocs.yml 's navigation 60 61 ### 3. No OIDC / OAuth bridge documentation 62 63 **Problem:** The NIST paper lists OAuth 2.0/2.1 and OIDC as primary standards. Auths already does GitHub OAuth for platform claims. But there's no doc explaining how Auths identities bridge to enterprise OIDC -- how an org can issue attestations based on OIDC tokens, or how an Auths `did:keri` can be presented alongside an OIDC flow. 64 65 **Tasks:** 66 67 - [x] **docs/architecture/oidc-bridge.md** (new file) -- Explain the design pattern: 68 - base this on the /Users/bordumb/workspace/repositories/auths-base/auths/crates/auths-oidc-bridge crate 69 - Auths identity is the root; OIDC is a claim/proof that can be linked 70 - GitHub OAuth flow already works this way (show it) 71 - How an enterprise IdP (Okta, Azure AD) could issue attestations after OIDC verification 72 - How MCP's OAuth requirement maps: the MCP server verifies an OAuth token, then the Auths attestation chain provides the cryptographic identity behind it 73 - Keep it architectural, not implementation-heavy -- this is a "here's how it fits" doc 74 75 ### 4. No zero-trust framing 76 77 **Problem:** The NIST paper explicitly asks about zero-trust principles for agent authorization (SP 800-207). Auths IS zero-trust by design -- no implicit trust, verify every attestation, no central authority -- but the docs never use the phrase or map to zero-trust concepts. 78 79 **Tasks:** 80 81 - [x] **docs/getting-started/trust-model.md** -- Add a section "Zero-Trust by Design" near the top, mapping: 82 - "Never trust, always verify" = every attestation is verified cryptographically, no server trust 83 - "Least privilege" = capability-scoped attestations with expiration 84 - "Assume breach" = pre-rotation means key compromise is survivable 85 - "Verify explicitly" = dual signatures, chain verification, witness receipts 86 - Keep it to ~15 lines, referencing SP 800-207 in passing 87 88 ### 5. No enterprise deployment or CI/CD agent story 89 90 **Problem:** The NIST paper's use case #3 is "Enterprise AI agents for software development and deployment." The vision doc mentions CI/CD but the actual docs don't show how a CI runner gets an identity and signs under an org policy. 91 92 **Tasks:** 93 94 - [x] **docs/getting-started/sharing-your-identity.md** -- Expand the "Export an identity bundle for CI" section into a fuller "CI/CD & Automated Agent Identity" section: 95 - How to create a dedicated agent identity (not just export a human's bundle) 96 - How to issue a time-limited, capability-restricted attestation to a CI agent 97 - How the CI agent signs artifacts and the org verifies them 98 - Show the `signer_type: Workload` usage 99 100 ### 6. No MCP integration story 101 102 **Problem:** MCP is the first standard listed in the NIST paper. There's no mention of MCP anywhere in Auths docs. 103 104 **Tasks:** 105 106 - [x] **README.md** -- In the new "Agent & Workload Identity" section, add one sentence: "Auths attestations can serve as the cryptographic identity layer behind MCP's OAuth-based authorization, providing verifiable delegation chains from human principals to AI agents." 107 108 - [x] **docs/architecture/oidc-bridge.md** -- Include an "MCP Integration" subsection showing where Auths fits in the MCP auth flow (MCP uses OAuth; Auths provides the identity that the OAuth token represents) 109 110 ### 7. No comparison to SPIFFE/SPIRE 111 112 **Problem:** The NIST paper mentions SPIFFE/SPIRE for workload identity. Auths solves a similar problem differently. A brief comparison would help the NIST reader understand positioning. 113 114 **Tasks:** 115 116 - [x] **docs/architecture/oidc-bridge.md** (or rename to `enterprise-integration.md`) -- Add a "Comparison with SPIFFE/SPIRE" subsection: 117 - SPIFFE: centralized SPIRE server issues SVIDs, runtime attestation 118 - Auths: self-certifying, no central issuer, Git-native, works offline 119 - Complementary: SPIFFE for service mesh workload identity, Auths for developer/agent identity with delegation chains 120 - 10-15 lines max 121 122 ### 8. No logging/audit trail documentation 123 124 **Problem:** The NIST paper asks: "How can we ensure that agents log their actions and intent in a tamper-proof and verifiable manner?" 125 126 The KEL IS a tamper-proof log. Attestation lifecycle is tracked in Git commits. But there's no doc that explicitly frames this as an audit capability. 127 128 **Tasks:** 129 130 - [x] **docs/getting-started/trust-model.md** -- Add a section "Audit Trail" after the trust boundaries summary: 131 - KEL = tamper-evident history of every key operation 132 - Attestation Git refs = lifecycle audit (creation, extension, revocation as commits) 133 - Seals = cryptographic binding of external events to the identity timeline 134 - Every agent action that produces a signature is traceable through the attestation chain back to the authorizing human 135 - 10-15 lines 136 137 --- 138 139 ## Summary of file changes 140 141 | File | Action | Priority | 142 |---|---|---| 143 | `README.md` | Add "Agent & Workload Identity" section with MCP mention | High | 144 | `docs/getting-started/delegation.md` | New file: delegation walkthrough with agent examples | High | 145 | `docs/getting-started/trust-model.md` | Add "Zero-Trust by Design" and "Audit Trail" sections | High | 146 | `docs/architecture/attestation-format.md` | Expand `signer_type` documentation | Medium | 147 | `docs/architecture/oidc-bridge.md` (or `enterprise-integration.md`) | New file: OIDC bridge, MCP integration, SPIFFE comparison | Medium | 148 | `docs/getting-started/sharing-your-identity.md` | Expand CI/CD section for agent identities | Medium | 149 150 --- 151 152 ## Tone guidance 153 154 The NIST audience is enterprise security architects and standards people. They don't need to be sold on decentralization -- they need to see: 155 156 1. How Auths maps to their existing frameworks (OAuth, OIDC, SPIFFE, zero-trust) 157 2. How it solves the specific problems the paper raises (delegation, audit, non-repudiation, key management for agents) 158 3. Concrete examples, not philosophy 159 160 The vision doc is great for investors/community. The NIST-facing docs should be drier, more standards-aware, and show the mapping explicitly.