phase 1: architecture spec — overview, server/client, ADR-001..006

- ADR-001: inherit the alknet TLS design as the baseline; deviations
  recorded as alktls ADRs
- ADR-002: TlsError ships the ADR-088 six-variant shape from day one
  (typed #[from] sources; NoqWrap; no string catch-all)
- ADR-003: the QUIC feature is noq (iroh's extracted fork), pre-
  consumer rename; default = [] per the lean-crate convention
  (corrects the extracted code's default = ["quinn"])
- ADR-004: complete accessors — for_tcp_tls() adopted, rustls_config()
  adopted; server accessors borrow (&self), client accessors consume
- ADR-005: identity + credentials + fingerprint types move into
  alktls; auth layer stays out
- ADR-006: eight-module layout; seed tests + integration invariant
  pins (exact nine-scheme list, client enable_early_data)
- specs: overview (transport picture, terminology), server.md (ACME
  lifecycle, invariants), client.md (verifier selection matrix, root-
  store fallback); open-questions.md promotes OQ-TLS-01..08 (all
  resolved at entry)
- Cargo.toml: quinn feature -> noq (per ADR-003); AGENTS.md aligned

Architecture review pass done: 0 critical, 2 major (ADR-002 AcmeConfig
doc comment contradiction; ADR-003 unrecorded default deviation) and
8 minors all addressed; cross-references verified against alknet ADRs,
rustls/noq/iroh sources.

Verified: cargo test, test --all-features, clippy -D warnings,
fmt --check, doc --no-deps
This commit is contained in:
2026-09-10 05:37:55 +00:00
parent e93238cb4a
commit d74a27f764
15 changed files with 1570 additions and 246 deletions
+6 -5
View File
@@ -49,7 +49,7 @@ not change `git config`, skip hooks, or use `git commit -i`.
This is the TLS crate — shared TLS setup types for the alk* stack:
server and client `rustls` configs, cert resolvers, verifiers, and
ACME state-machine wiring, transport-agnostic and shareable across
transports (quinn, `tokio-rustls` TCP+TLS, and anything else that
transports (noq, `tokio-rustls` TCP+TLS, and anything else that
consumes a `rustls` config). It is the extraction of the TLS handling
from alknet (alknet ADR-082/087/088 and the `crates/tls` spec are the
prior art). The conventions below apply to all work in `src/` and
@@ -80,8 +80,8 @@ session, not just spawned implementation agents.
in `[dependencies]` (dev-dependencies may use `full`).
4. **The default crate should stay lean** — TLS setup and config types
only. Transport-specific wrapping is feature-gated: `quinn` (the
`for_quinn()` accessors), `tcp` (`tokio-rustls`), `acme` (the ACME
only. Transport-specific wrapping is feature-gated: `noq` (the
`for_noq()` accessors), `tcp` (`tokio-rustls`), `acme` (the ACME
state machine, a heavy dep). The `rustls` dep is always present —
it is the core library. Unlike the sibling protocol crates
(alktunnels, alktty), wasm is not a load-bearing target here: the
@@ -139,8 +139,9 @@ session, not just spawned implementation agents.
logged in the spawned task, not `TlsError` variants. Do not grow
`TlsError` to cover handshake outcomes.
9. **Feature gates** — transport-specific deps are opt-in (`quinn`,
`tcp`, `acme`). The base crate compiles lean. Verify `cargo test`
9. **Feature gates** — transport-specific deps are opt-in (`noq`,
`tcp`, `acme`); `default = []` — the default crate compiles lean
(ADR-003). Verify `cargo test`
(default) and `cargo test --all-features` both pass whenever features
are touched.