The family standing rule (anything worth fuzzing gets fuzzed) on the
crate's ingress surfaces, per the alkgit convention:
- fuzz_targets/{exec_parse,fingerprint,key_decode,terminal_params} —
thin fuzz_target! wrappers over four ingress surfaces:
- exec_parse: the production parse path (from_utf8-fallback ingress
shape), differentially paired against a from-spec grammar oracle;
typed routing classes + determinism.
- fingerprint: blob parse + the single fingerprint path; the
SHA256:/unpadded-base64 contract shape via a from-spec
base64 round-trip oracle; the committed ssh-keygen -lf vectors
replayed inside the gate.
- key_decode: the production decode arm (the #[doc(hidden)]
decode_key_arm exposure, routed through itself); typed-class +
bounded-fixed-message invariants; passphrase-shape robustness
drive on the underlying decode.
- terminal_params: the pty_request conversion via the #[doc(hidden)]
terminal_params exposure; exact clamp, verbatim term, the
reserved-modes {} JSON shape, serialized-shape determinism.
- shared/ — the invariant logic as a stable-clean library; the
corpus gate (cargo test --manifest-path fuzz/shared/Cargo.toml)
replays every committed seed through the batteries and joins
AGENTS.md's verification list.
- corpus/<target>/ committed seeds + the deterministic
gen_fuzz_seeds.py (no-op-diff verified).
- run-detached.sh + nightly pin; the sidecar excluded from the root
workspace (workspace + package excludes; publish dry-run clean).
Exposure shape decided + recorded per target (README + lib.rs doc
comments): fingerprint needs none (fully public ingress); the rest
are #[doc(hidden)] re-exports of the production surfaces, never
forks. Detached campaigns ran per target (600 s default budget, fork
mode): all four clean; the two findings of the first round are
recorded in the task file (the harness oracle's double-/-strip bug;
the PPK echo fixed in the preceding commit).
Verification: corpus gate green (11 tests); scripts/matrix.sh green;
taskgraph validate clean.
- coverage audit recorded in the task file: every mapping.md row ×
every build it can appear in × both directions → the pinning test
- gap rows landed in tests/dispatch_core.rs: the streamlocal_forward
decline, the cancel-form refusions, the git-build pty decline
- never-features pinned in every build both directions; the auth-agent
open recorded pin-bound upstream (russh 0.65 declines AgentForward
opens pre-handler; no client initiator at the pin)
- sftp-only build verified no-op + declining via the matrix run
- matrix runner landed: scripts/matrix.sh (cargo test × 6 builds,
clippy ×2 -D warnings, fmt, doc), joined AGENTS.md verification list
Verification: scripts/matrix.sh green end to end
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)
The phase 0 document set (documented only; no POCs run yet):
- docs/research/vision.md — guiding principles (russh owns the wire,
door-not-backend, fail-closed everything, one seam per mapping,
family identity not SSH identity); non-goals (no sshd, no sftp until
alkfs, no password auth); the five scope questions phase 0/1 must
answer
- docs/research/russh.md — 0.64.1-era inventory: server/client
Handler method tables, Config knobs, keys module (ssh-key re-export,
fingerprint API), the RC-pinned dependency tree (ssh-key, rsa,
pkcs1), MSRV/edition/license posture; alknet-main referenced as a
rough example only, explicitly not decision input
- docs/research/auth-bridge.md — the alkcall mapping: no
resolve_from_signature exists; the actual surface is
IdentityProvider::resolve_from_fingerprint fed by russh-verified key
fingerprints in auth_publickey; auth-method disposition matrix
(only publickey implemented, all defaults overridden); client side
mirrors alkhttp ADR-014 (key sources, not static keys; vault
client-side only); the vault-to-russh-key bridge named as the
missing design piece
- docs/research/mapping-table.md — the spine: channel-type rows with
feature candidates and the verified sibling serve/consume entries
(alktty drive_session, alkgit serve_duplex_resolved, alksocks
serve_socks5_over, alktunnels consumer wrappers + the no-serve-over-
stream absence note); request-level rows; parse-then-route dispatch
inside the session channel; the alk/ssh ALPN topology question
(ADR-004 reserved / ADR-034 stream_types [0,1] / ADR-042 hub never
runs it); alktunnels route choice flagged for ADR
- docs/research/pocs.md — POC-1 (auth bridge + fail-closed declines
against vanilla OpenSSH), POC-2 (vault-to-russh key bridge:
PrivateKey extraction vs vault-backed Signer), POC-3 (mapping
bake-off stages A-D: git exec, socks -D, tunnel -L, pty); all
standalone mode; findings docs are the deliverables
Verification: cargo doc --no-deps, cargo fmt --check, cargo test
(docs-only change; lib untouched)
Phase 0 base for the russh-wrapped SSH adapter (family ADR-003):
- Cargo.toml: single-crate alkssh 0.1.0, MIT OR Apache-2.0, lib only,
publish exclude list matching the sibling-crate policy; deliberately
empty [dependencies] — the russh pin is phase 0 research output
(alknet main's 0.49 is a data point, not the decision). [features]
carries the fail-closed posture as a comment until the capability
feature graph lands with the committed architecture
- src/lib.rs: crate-root doc describing the adapter shape and the
fail-closed feature contract
- LICENSE-MIT / LICENSE-APACHE (alktty's standard texts)
- .gitignore (target/, node_modules/, .worktrees/)
- CHANGELOG.md: Keep a Changelog stub, [Unreleased] initialization
- AGENTS.md: full agent operating instructions — git workflow
(conventional commits, commit-and-push), 13 project conventions
(russh owns the wire, fail-closed capability features, key reuse via
alkvault-backed sources, visible-surface=authorized-surface,
ALPN as one-way door), verification commands, taskgraph
task rules, SDD phase 0 lifecycle status, architecture context
Verification: cargo build/test/clippy --all-targets -D warnings and
cargo fmt --check all pass (lib stub, zero deps)
glm-5.3-flash