alkdev/alknet
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(architecture): add ADR-014 secret material flow, remove vault ops from call protocol

Browse Source 
Resolve the contradiction between ADR-008's "capability source" model
and operation-registry.md showing vault operations on the wire. ADR-014
establishes: vault is assembly-layer only, capabilities carry outbound
credentials (distinct from inbound identity), call protocol carries no
secret material, adapters take credential sources not static tokens.

- Add ADR-014 (Secret Material Flow and Capability Injection)
- Remove vault/derive, vault/unlock, vault/decrypt from call protocol
  registration examples and all spec examples
- Add Capabilities field to OperationContext, propagate through
  LocalOperationEnv nested calls
- Add Capability Injection section to operation-registry.md
- Add no-secret-material wire constraint to call-protocol.md
- Add streaming subscribe example (LLM chat with Vercel UI chunks)
- Add Security Model section to overview.md (identity vs capabilities)
- Trim WASM treatment from ~20 lines to a design-constraint note
- Add OQ-16 (resolved: no vault ops on wire), update OQ-08, OQ-15
- Update ADR-003, ADR-008, ADR-013 to remove stale "via call protocol"
  vault references
This commit is contained in:
glm-5.2
2026-06-18 03:16:45 +00:00
parent 6219a323b6
commit 6a7d4b9755
10 changed files with 388 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/architecture/decisions/008-secret-service-integration.md
View File

@@ -28,18 +28,21 @@ The vault is a capability source, not a service endpoint. Operations that need p
## Decision
**Option 4: CLI-embedded with call protocol exposure.**
**Option 4: CLI-embedded, assembly-layer only.**
The CLI binary (the `alknet` crate) is the integration point. It:
1. Instantiates `VaultServiceHandle` locally at startup (or on-demand with Unlock/Lock lifecycle).
2. Registers vault operations (DeriveEd25519, DeriveEncryptionKey, Encrypt, Decrypt, etc.) in the call protocol's operation registry.
3. Other handlers access vault capabilities by calling operations on `alknet/call` — they don't import alknet-vault directly.
2. Derives and decrypts the credentials each handler needs.
3. Injects those credentials into handler capabilities at construction time.
4. Other handlers access vault-derived material through their `OperationContext.capabilities` — they don't import alknet-vault directly and don't call vault operations over the wire.
**alknet-vault does NOT get its own ALPN.** Key derivation is a local operation — the master seed never crosses the network. If a remote node needs derived public keys (e.g., for identity verification), they're shared through the call protocol, not through direct vault access.
**The vault is accessed at the assembly layer, not by individual handlers.** The CLI (or a configuration middleware it sets up) is the only component that talks to the vault directly. Derived keys and decrypted credentials are injected into operation contexts — handlers receive the material they need, not a vault reference.
**No vault operations are registered in the call protocol.** The vault is not exposed over the wire. This is the mechanism this ADR described in prose ("derived keys and decrypted credentials are injected into operation contexts at the assembly layer"); ADR-014 specifies it as a one-way door with explicit constraints. See ADR-014.
This is analogous to the reverse-proxy admin key pattern (ADR-028 in the reverse-proxy project): the proxy reads the key file once at startup, hashes it, and individual handlers never see the file. Here, the CLI unlocks the vault once at startup, and individual handlers receive the results of vault operations through their contexts.
## Consequences
@@ -63,6 +66,7 @@ This is analogous to the reverse-proxy admin key pattern (ADR-028 in the reverse
- ADR-003: Crate decomposition (alknet-vault is standalone)
- ADR-005: irpc as call protocol foundation
- ADR-009: One-way door decision framework
- OQ-08: Secret service integration point (resolved by this ADR)
- ADR-014: Secret material flow and capability injection (specifies the mechanism this ADR described in prose)
- OQ-08: Secret service integration point (resolved by this ADR, refined by ADR-014)
- alknet-vault implementation: `crates/alknet-vault/`
- Reverse-proxy ADR-028: Admin HTTP API (analogous key management pattern)