intuitive_platform.md
1 # Audit Prompt: Intuitive Platform Design 2 3 You are auditing the `auths` codebase for naming consistency, API intuitiveness, and 4 "Pit of Success" design — the principle that correct usage should be the path of least 5 resistance and mistakes should be hard to make accidentally. 6 7 The goal is to produce a concrete list of changes: renames, interface additions, missing 8 lifecycle steps, and inconsistencies — ordered by impact. Do not produce vague 9 recommendations. Every finding must cite a specific file and line number. 10 11 We want to build the "Stripe for identity" - intuitive, deep, and easy of use 12 13 --- 14 15 ## What auths Is 16 17 `auths` is a decentralized identity system for developers, agents, and CI pipelines. It 18 enables cryptographic commit signing with Git-native storage. No central server, no 19 blockchain — just Git and Ed25519 cryptography. 20 21 **Core concepts** (learn these before auditing): 22 - **Identity**: A root `did:keri:...` key pair stored in `~/.auths` (a Git repo) 23 - **Device**: A delegated `did:key:z...` key that signs on behalf of the identity 24 - **Attestation**: A signed JSON record linking a device to an identity, with scoped capabilities 25 - **Capability**: What a device is allowed to do — `SignCommit`, `SignRelease`, `ManageMembers`, `RotateKeys` 26 - **Bundle**: A self-contained JSON file with the full attestation chain, for offline verification 27 - **Allowed signers**: An ssh-keygen formatted file derived from the bundle, used for `git verify-commit` 28 29 **User personas**: 30 1. **Developer** — runs `auths` on a laptop, signs commits, manages devices, rotates keys 31 2. **Agent** — an MCP tool or CI bot that signs artifacts, publishes attestations, exchanges tokens 32 3. **CI pipeline** — GitHub Actions or similar, verifies commits in a range, enforces signing policy 33 34 --- 35 36 ## Codebase Map 37 38 Read these files to understand each layer before auditing: 39 40 ``` 41 Layer 0: crates/auths-crypto/src/ — Ed25519, DID:key encoding 42 Layer 1: crates/auths-verifier/src/ — standalone verify (FFI/WASM safe) 43 Layer 2: crates/auths-core/src/ — keychains, signing, port traits 44 Layer 3: crates/auths-id/src/ — identity lifecycle, attestations, KERI 45 crates/auths-policy/src/ — policy expression engine 46 Layer 4: crates/auths-storage/src/ — Git storage adapters 47 crates/auths-sdk/src/ — application workflows 48 Layer 5: crates/auths-infra-http/src/ — HTTP client adapters 49 Layer 6: crates/auths-cli/src/ — CLI commands (thin presentation layer) 50 51 Python SDK: packages/auths-python/python/auths/ 52 Rust FFI: crates/auths-mobile-ffi/src/lib.rs 53 packages/auths-verifier-swift/src/lib.rs 54 ``` 55 56 **Key files to read first**: 57 - `crates/auths-sdk/src/workflows/` — the canonical SDK API surface 58 - `crates/auths-sdk/src/context.rs` — `AuthsContext` (the main SDK entry point) 59 - `packages/auths-python/python/auths/__init__.py` — Python public API 60 - `packages/auths-python/python/auths/_client.py` — `Auths` class (Python entry point) 61 - `crates/auths-cli/src/commands/` — CLI commands (mirrors what SDK should expose) 62 - `crates/auths-core/src/ports/` — port trait definitions 63 64 --- 65 66 ## Audit Goals 67 68 ### 1. Full Lifecycle Completeness 69 70 For each of the three personas, map whether the SDK exposes every step of their lifecycle. 71 A persona should be able to complete their entire workflow using only `auths-sdk` (Rust) or 72 the `Auths` class (Python) — without dropping down to lower layers. 73 74 **Developer lifecycle**: 75 ``` 76 init identity → attest device → sign commit → verify commit → rotate keys → revoke device 77 ``` 78 79 **Agent lifecycle**: 80 ``` 81 get token → sign artifact → publish artifact attestation → verify artifact 82 ``` 83 84 **CI lifecycle**: 85 ``` 86 generate allowed_signers → verify commit range → enforce policy → report results 87 ``` 88 89 For each step in each lifecycle, answer: 90 - Does the SDK have a function for this? What is it called? 91 - Does the Python `Auths` class expose it? What is it called? 92 - Does the CLI have a command for this? What is it called? 93 - Is there a gap (missing at any layer)? 94 - Is the name at each layer consistent with the names at other layers? 95 96 Produce a table: 97 98 | Step | SDK function | Python method | CLI command | Gap? | 99 |------|-------------|---------------|-------------|------| 100 | init identity | `setup::initialize()` | `Auths().init()` | `auths init` | — | 101 | ... | ... | ... | ... | ... | 102 103 --- 104 105 ### 2. Naming Consistency Audit 106 107 Audit naming across the full stack. For each concept, the name should be the same word at 108 every layer (SDK → Python → CLI). If they differ, flag it. 109 110 **Check these concepts specifically**: 111 112 | Concept | What to look for | 113 |---------|-----------------| 114 | Identity creation | Is it `init`, `initialize`, `create`, `setup`? Is it consistent? | 115 | Device attestation | Is it `attest`, `delegate`, `authorize`, `provision`? | 116 | Commit signing | Is it `sign`, `sign_commit`, `commit_sign`? | 117 | Commit verification | Is it `verify`, `verify_commit`, `check`? | 118 | Key rotation | Is it `rotate`, `rotate_keys`, `key_rotate`? | 119 | Device revocation | Is it `revoke`, `revoke_device`, `remove`? | 120 | Allowed signers | Is it `generate_allowed_signers`, `allowed_signers_file`, `signers`? | 121 | Identity bundle | Is it `bundle`, `identity_bundle`, `export_bundle`? | 122 | Token exchange | Is it `get_token`, `exchange_token`, `token`? | 123 | Artifact signing | Is it `sign_artifact`, `artifact_sign`, `sign`? | 124 | Artifact publishing | Is it `publish_artifact`, `artifact_publish`, `publish`? | 125 126 For each inconsistency, cite: 127 - The SDK name and file 128 - The Python name and file 129 - The CLI name and file 130 - Your recommended canonical name 131 132 --- 133 134 ### 3. "Pit of Success" Design Audit 135 136 Identify places where a user can make a mistake that the API design could have prevented. 137 138 **Check**: 139 140 **a) Error messages**: When a function fails, does the error tell the user what to do next? 141 - Check `crates/auths-core/src/error.rs` — does `AuthsErrorInfo::suggestion()` return 142 actionable text for every variant? 143 - Check Python `packages/auths-python/python/auths/_errors.py` — do error classes have 144 useful `__str__` output? 145 146 **b) Missing guards**: Are there functions that will silently do the wrong thing if called 147 in the wrong order? 148 - Example: Can a user call `sign_artifact` before `init`? What happens? 149 - Example: Can a user call `verify_commit` with no allowed_signers and get a confusing error? 150 151 **c) Discoverability**: If a user imports `from auths import Auths`, can they discover all 152 available operations via tab completion / `help()`? Check: 153 - `packages/auths-python/python/auths/__init__.py` — is `__all__` complete? 154 - `packages/auths-python/python/auths/_client.py` — does `Auths` have methods for every 155 lifecycle step, or do some require importing submodules? 156 157 **d) Default arguments**: Do functions have sensible defaults so the happy path requires 158 minimal arguments? 159 - Example: `verify_commit_range("HEAD~1..HEAD")` should work with no other arguments. 160 - Flag any required argument that should have a default. 161 162 **e) Kwarg-only dangerous parameters**: Parameters that change behavior significantly 163 (like `mode="warn"` vs `mode="enforce"`) should be keyword-only in Python. 164 165 --- 166 167 ### 4. Consistency of Feature Depth 168 169 Check that the SDK and Python SDK have feature parity — not that every internal function is 170 exposed, but that every user-facing capability at one layer is reachable from the other. 171 172 Compare: 173 - Every `auths-sdk/src/workflows/*.rs` public function → is there a Python equivalent? 174 - Every `Auths` class method → is there an SDK workflow backing it? 175 - Every CLI command in `crates/auths-cli/src/commands/` → is there an SDK workflow for it? 176 177 Flag gaps in either direction. A CLI command with no SDK backing is a violation of the 178 architecture. An SDK workflow with no Python binding is a missing feature. 179 180 --- 181 182 ### 5. FFI / Mobile API Surface 183 184 Read `crates/auths-mobile-ffi/src/lib.rs` and `packages/auths-verifier-swift/src/lib.rs`. 185 186 **Check**: 187 - Do the exported function names match the naming convention established in the SDK? 188 - Is the full developer lifecycle (init → attest → sign → verify) achievable from the FFI? 189 - Is the agent lifecycle (sign artifact → publish → get token) achievable from the FFI? 190 - Are there functions that exist in the FFI but not the SDK (logic that should be extracted)? 191 192 --- 193 194 ## Output Format 195 196 Produce your findings in four sections: 197 198 ### Section A: Lifecycle Coverage Matrix 199 200 The table from Audit Goal 1 above. One row per lifecycle step, columns for SDK / Python / CLI 201 / Gap. 202 203 ### Section B: Naming Inconsistencies 204 205 For each inconsistency, one entry: 206 ``` 207 Concept: [name] 208 SDK: [function name] in [file:line] 209 Python: [method name] in [file:line] 210 CLI: [command name] in [file:line] 211 Fix: rename [X] to [Y] in [file] 212 ``` 213 214 ### Section C: Pit of Success Issues 215 216 For each issue, one entry: 217 ``` 218 Issue: [short title] 219 Location: [file:line] 220 Problem: [what can go wrong] 221 Fix: [concrete change — add default, improve error message, make kwarg-only, etc.] 222 ``` 223 224 ### Section D: Feature Gaps 225 226 For each gap, one entry: 227 ``` 228 Gap: [description] 229 Missing from: [SDK | Python | CLI | FFI] 230 Closest existing: [file:line if partial] 231 Recommended: add [function/method/command name] to [location] 232 ``` 233 234 --- 235 236 ## Constraints 237 238 - Every finding must cite a file path and line number. Do not make general observations. 239 - If you see a missing lifecycle step, note it. But try to refrain from 240 suggesting new features that don't exist at any layer. Focus on missing steps for a full use case/lifecycle. 241 - Do not recommend renaming things that are already consistent. Only flag genuine 242 inconsistencies. 243 - Prioritize findings by user impact. Developer lifecycle gaps are higher priority than 244 FFI naming nits. 245 - Keep Section B and C findings actionable and small. The goal is a list of specific 246 changes, not an essay.