docs(research): vault's SSH role is at-rest secret storage, not key derivation

A conflation in the research set: alkvault's derive-and-custody surface
(derive_ed25519, SLIP-0010 paths) was being sketched as the SSH key
path. Corrected across the docs — held SSH keys (client outgoing keys
and the server's own host key) are bearer-token-class secrets: opaque
bytes the family holds, vault-encrypted at rest, decrypted at use (the
alkhttp ADR-014 posture). No derivation story, no vault-custody
design, and the Signer-injection idea is withdrawn and recorded with
its dismissal rationale.

- auth-bridge.md: client-side gap re-framed as at-rest storage — the
  at-rest shape (OpenSSH encoding inside alkvault EncryptedData), the
  at-use lifecycle (decrypt-at-dial, one-time decode_secret_key,
  zeroized for the dial), the KeySource-like source shape
- pocs.md: POC-2 rewritten to at-rest key handling (formats comparison,
  decrypt-at-use lifecycle, locked-vault fail-closed, Signer dismissal)
- vision.md: principle 5 scoped (secret store, not key generator/custodian)
- russh.md: Signer seam noted as not presumed to be the vault shape
- AGENTS.md/CHANGELOG: convention 6 + context updated to match

Verification: cargo doc --no-deps, cargo fmt --check, cargo test
(docs-only change)
This commit is contained in:
glm-5.3-flash committed 2026-10-25 10:37:37 +00:00
1 parent ecdf836eeb
commit f4424b7e58
6 files changed
+105 -73

No files matched your search

+7 -4
View File
@@ -102,7 +102,9 @@ session, not just spawned implementation agents.
6. **Key reuse, no env vars** — keys reuse the alknet `main` key model
(`russh::keys`, authorized-key/KeySource handling — see
`/workspace/@alkdev/alknet-main/crates/alknet-core/src/auth/`) via
alkvault-backed sources (family ADR-003 decision 2). No secret
alkvault-backed sources — keys held encrypted at rest, decrypted at
use (the vault is a secret store on this path, not a key generator)
(family ADR-003 decision 2). No secret
material on the wire, in plaintext at rest, or in env vars — the
standing family security posture (family ADR-002 decision 5).
@@ -219,12 +221,13 @@ production code.
against current russh at architecture time
- `auth-bridge.md` — russh auth ↔ alkcall `IdentityProvider` mapping
(server: verified-key fingerprint → `resolve_from_fingerprint`;
client: alkvault-backed key sources, `Signer`-shaped)
client: alkvault-backed key sources — held keys encrypted at rest,
at-rest/bearer-token-class storage, not key derivation)
- `mapping-table.md` — the crate's spine: SSH channel type / request
→ family protocol seam + cargo feature; the alktunnels
absence note; the `alk/ssh` ALPN topology question
- `pocs.md` — POC-1..3 plan (auth bridge, vault key bridge, mapping
bake-off) gating phase 0 completion
- `pocs.md` — POC-1..3 plan (auth bridge, client-side at-rest key
handling, mapping bake-off) gating phase 0 completion
- family docs: `/workspace/@alkdev/alkfamily/docs/` —
`architecture/decisions/003-alkssh-russh-adapter.md` is the structural
decision this repo builds from (and `002-alkforge-gitea-replacement.md`