Files
alkssh/docs/architecture
glm-5.3-flash 22b82af517 docs(architecture): correct the fingerprint base64 alphabet wording
The format contract (ADR-004 decision 1) is SHA256: + unpadded
standard base64 — not url-safe. The ssh-key re-export and ssh-keygen
both emit the +/ alphabet (visible in the recorded fingerprints); the
'url-safe' wording in ADR-004/auth.md/plans/implementation.md and the
POC-1 §1 finding was a misnomer. Wording corrected; the parity
contract itself unchanged on both sides.
2026-10-28 06:27:49 +00:00
..

status, last_updated
status last_updated
reviewed 2026-10-28

Architecture index

Current State

Phase 1 (architecture) — complete pending implementation. Phase 0 is closed: all three POCs passed (121 checks; docs/research/poc-{1,2,3}-*.md) and the research docs record their corrections. The ADR set (001–006) is Accepted — including the post-review amendments (ADR-002's ed25519-only revert; ADR-003/006's dynamic-forward retirement) — and the four spec docs (overview/mapping/client/auth) are reviewed (2026-10-28): the OQ resolution pass closed all thirteen open questions (OQ-08/11 decided, OQ-10 converted to a derivation contract + upstream constraint, OQ-01/04/09/13 closed as fully-decided dispositions) and the review pass came back clean. Implementation may begin.

Architecture Documents

Document Status Scope
overview.md reviewed Crate purpose, family position, surface categories, bounded-resources policy, non-goals
mapping.md reviewed The spine — server-direction rows, dispatch, spawn-and-return, decline matrix
client.md reviewed Client-direction surface: dial, op rows, the acceptor, lifecycle primitives
auth.md reviewed The auth bridge (server) + custody & host-key policy (client)
open-questions.md reviewed Centralized OQ tracker (all OQ-01…13 resolved)

ADR Table

ADR Title Status
ADR-001 The alk/ssh ALPN pin — edge-termination contract for SshAdapter Accepted
ADR-002 The russh pin — 0.65.0, aws-lc-rs, no compression, ed25519-only Accepted
ADR-003 The capability feature graph — flat, independent, two-direction Accepted
ADR-004 Auth dispositions — publickey-only, fail-closed, fingerprint identity Accepted
ADR-005 At-rest key custody — vault-wrapped OpenSSH-PEM, decrypt-at-use Accepted
ADR-006 Mapping decisions — route-1 bridge, exec-only git, session dispatch Accepted

Open Questions

Tracked in open-questions.md — OQ-01 … OQ-13, seeded from the phase 0 POC findings and research docs. All thirteen are resolved: the three mapping-detail decisions settled this pass (OQ-08 shell convention → assembly-supplied serve-config field, no crate default; OQ-10 → closed as the derivation contract on mapping.md's exit rows + the upstream PTY-path constraint; OQ-11 → universal compile + runtime Unix-gated decline), and the previously deferred entries closed as fully-decided dispositions (OQ-01/04/09/13 — the decision surfaces were already fixed by ADR-001/ADR-004 and the decline postures; what remained was forecasts about consumers, not pending alkssh decisions). Upstream dependencies are listed as watch items in the tracker, not OQs.

Document Lifecycle

Status Meaning Transitions
draft Under active development; may change significantly → reviewed when its open questions are resolved
reviewed Final; implementation may begin; changes require review → stable when implementation is complete and verified
stable Locked; changes require review and may warrant an ADR → deprecated when superseded
deprecated Superseded; kept for reference Removed when unreferenced

References

  • docs/sdd_process.md — the SDD process
  • docs/research/ — phase 0 (vision, POC plans + findings, russh inventory, auth bridge, mapping table, reverse-runner extraction)
  • Family: /workspace/@alkdev/alkfamily/docs/architecture/decisions/001..003 (ADR-003 is the alkssh structural decision)
  • Sibling: alkcall ADRs 002/003/004/006/009/010/034/042/051 (ALPN dispatch, auth surface, channels wire/relay); alkhttp ADR-014/073 (secret-material flow and door-surface posture — the patterns ADR-005 and auth.md mirror)