From 22b82af517916bf28fa852ce889180fef4c58171 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Wed, 28 Oct 2026 06:27:49 +0000 Subject: [PATCH] docs(architecture): correct the fingerprint base64 alphabet wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/architecture/auth.md | 10 ++++++---- docs/architecture/decisions/004-auth-dispositions.md | 4 +++- docs/plans/implementation.md | 2 +- docs/research/poc-1-auth-bridge.md | 7 +++++-- 4 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/architecture/auth.md b/docs/architecture/auth.md index 04b6001..957fb9c 100644 --- a/docs/architecture/auth.md +++ b/docs/architecture/auth.md @@ -23,10 +23,12 @@ verifies a signature; its auth surface is *dispositional* (ADR-004). 0.65.0 shape — the key is the `.public_key` field, and the client's signature `.algorithm` is exposed for optional hardening). 2. alkssh computes the fingerprint via the `ssh-key` re-export - (`HashAlg::Sha256`) — `SHA256:` + unpadded url-safe base64. The - string format is a **contract invariant** (ADR-004): parity with - assembly-registered values is proven against independent issuers - (`ssh-keygen -lf` — POC-1 §1). + (`HashAlg::Sha256`) — `SHA256:` + unpadded base64 over the + standard alphabet (`ssh-keygen -lf` byte-format; not the + url-safe alphabet). The string format is a **contract invariant** + (ADR-004): parity with assembly-registered values is proven + against independent issuers (`ssh-keygen -lf` — POC-1 §1, pinned + by the committed vectors in `tests/vectors/`). 3. `resolve_from_fingerprint` → `Some(identity)` → accept; `None` → reject — fail-closed, and the resolved-identity-`None` path never creates a "weakly authorized" session. diff --git a/docs/architecture/decisions/004-auth-dispositions.md b/docs/architecture/decisions/004-auth-dispositions.md index 20b228c..5f84518 100644 --- a/docs/architecture/decisions/004-auth-dispositions.md +++ b/docs/architecture/decisions/004-auth-dispositions.md @@ -37,7 +37,9 @@ twice: which methods exist, and what unauthenticated attempts receive. 1. **`auth_publickey` is implemented — the only method.** Handler: fingerprint (`ssh-key` re-export, `HashAlg::Sha256`, - `SHA256:` + unpadded url-safe base64) → + `SHA256:` + unpadded base64 over the standard alphabet — + `+/`, not the url-safe alphabet; byte-identical to + `ssh-keygen -lf`) → `resolve_from_fingerprint` → `Some` → accept with the resolved identity; `None` → reject. The fingerprint *string format* is a contract invariant: registration strings from any standard issuer diff --git a/docs/plans/implementation.md b/docs/plans/implementation.md index c0f3292..424a808 100644 --- a/docs/plans/implementation.md +++ b/docs/plans/implementation.md @@ -101,7 +101,7 @@ test. The alkssh analog of alkgit's seam wave. pins (hard-decline on mismatch) and case-2 assembly policies are the implementor's; the crate ships the fail-closed default (reject unknown) and is otherwise policy-blind — no accept-all built-in. -- **Fingerprint** (ADR-004) — the `SHA256:` + unpadded url-safe base64 +- **Fingerprint** (ADR-004) — the `SHA256:` + unpadded base64 computation via the `ssh-key` re-export (`HashAlg::Sha256`); the string format is a contract invariant, proven against independent issuers (`ssh-keygen -lf` vectors, the POC-1 §1 checkpoint shape). diff --git a/docs/research/poc-1-auth-bridge.md b/docs/research/poc-1-auth-bridge.md index 1a047cd..e2227e7 100644 --- a/docs/research/poc-1-auth-bridge.md +++ b/docs/research/poc-1-auth-bridge.md @@ -32,8 +32,11 @@ the OQ seeds this POC produced. ### 1. Fingerprint-format parity — confirmed, format is exactly the registered string `public_key.fingerprint(HashAlg::Sha256).to_string()` (via the -`ssh-key` re-export) yields `SHA256:` — -byte-identical to `ssh-keygen -lf` on the same public key. The +`ssh-key` re-export) yields `SHA256:` — byte-identical to `ssh-keygen -lf` on the same public key. (An +earlier phrasing of this section called the encoding "url-safe"; the +observed strings and OpenSSH's own format use the standard alphabet — +unpadded standard base64 is the invariant.) The `resolve_from_fingerprint` string compare works with values that were registered from OpenSSH tooling output. Parity was additionally observed against the vanilla client's own host-key check