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:
@@ -0,0 +1,108 @@
|
||||
---
|
||||
status: accepted
|
||||
last_updated: 2026-09-10
|
||||
---
|
||||
|
||||
# ADR-001: Inherit the alknet TLS design; alktls as the rewrite's TLS crate
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (2026-09-10)
|
||||
|
||||
## Context
|
||||
|
||||
alktls is the extraction of the TLS handling from alknet
|
||||
(`crates/alknet-tls` + the config types in `crates/alknet-core`), the
|
||||
last crate extracted before the alknet rewrite begins. alknet already
|
||||
recorded the full TLS design as ADRs (082/083/084/086/087/088/089/
|
||||
091, plus ADR-027's identity model and ADR-034's verifier selection)
|
||||
and a complete crate spec (`docs/architecture/crates/tls/README.md`).
|
||||
The extracted code runs in production today and every
|
||||
behavior-preservation invariant was verified present in Phase 0
|
||||
(`docs/research/phase-0.md` §Prior art).
|
||||
|
||||
Phase 1 must decide how this crate relates to that body of decisions:
|
||||
re-litigate, inherit wholesale, or inherit with recorded deviations.
|
||||
|
||||
## Decision
|
||||
|
||||
alktls **inherits** the alknet TLS design. The alknet ADRs and the
|
||||
`crates/tls` README are adopted as this crate's authoritative prior
|
||||
decisions; Phase 1 does not re-litigate them. This ADR records that
|
||||
inheritance as alktls' own baseline, so this repo's ADR numbering
|
||||
starts from a coherent baseline instead of dangling references into
|
||||
another repo's architecture.
|
||||
|
||||
Concretely, alktls adopts:
|
||||
|
||||
- `TlsServerConfig` / `TlsClientConfig` as the central types, built
|
||||
once, shared across transports via `Arc` (alknet ADR-082). The inner
|
||||
rustls config is `Clone` (Arc-shared resolvers); `TlsServerConfig`
|
||||
is not `Clone` (it holds the ACME task's `JoinHandle`).
|
||||
- The config-construction scope boundary: this crate builds configs;
|
||||
handshake outcomes flow through the transport's connector; ACME
|
||||
runtime errors are stream events logged in the spawned task
|
||||
(alknet ADR-088 §6).
|
||||
- The behavior-preservation invariants verbatim: `max_early_data_size
|
||||
= u32::MAX` on all server paths **plus `enable_early_data = true`
|
||||
on every client config** (the client half of the 0-RTT invariant),
|
||||
`aws_lc_rs::default_provider()` on
|
||||
all paths, `AcceptAnyCertVerifier`'s nine-scheme
|
||||
`supported_verify_schemes()`, crate-side `acme-tls/1` append for the
|
||||
ACME path only, non-empty root store via `webpki-roots` fallback
|
||||
(alknet ADR-082, ADR-084, ADR-088 §5).
|
||||
- The identity model: `TlsIdentity` four variants, `Acme` server-only,
|
||||
client-auth presentation follows the local identity, verifier
|
||||
selection fail-closed (alknet ADR-027, ADR-034, ADR-091).
|
||||
- One ACME state machine per domain, shared across transports; never a
|
||||
second order for a served domain (alknet ADR-082 §The cert-reuse
|
||||
problem).
|
||||
- iroh stays key-not-config: no `for_iroh()`; the identity type
|
||||
exposes 32-byte Ed25519 access for `iroh_base::SecretKey`
|
||||
(alknet ADR-082 §Iroh is different).
|
||||
|
||||
Where alktls deviates from or refines the inherited design, the
|
||||
deviation is recorded as an alktls ADR (001.. this series) rather than
|
||||
silently diverging. The known deviations/corrections at time of
|
||||
writing: the `TlsError` shape (ADR-002), the QUIC feature (ADR-003,
|
||||
which also corrects the extracted code's `default = ["quinn"]` back
|
||||
to the spec's `default = []`), the API surface completion (ADR-004),
|
||||
and config-type ownership (ADR-005).
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- The crate implements proven code, not a new design; Phase 2 is a
|
||||
port with a verified behavior checklist, not an invention.
|
||||
- Design rationale is already written and battle-tested; this repo's
|
||||
ADR series stays small and points at the alknet reasoning where the
|
||||
full argument lives.
|
||||
- The alknet rewrite consumes one crate with one consistent ADR
|
||||
lineage instead of reverse-engineering decisions from scattered
|
||||
alknet ADRs.
|
||||
|
||||
**Negative:**
|
||||
|
||||
- alktls ADRs are derivative — a reader must consult alknet's ADRs for
|
||||
the full rationale of the inherited posture (mitigated: each
|
||||
alktls ADR restates the decision it pins, and the Phase 0 doc
|
||||
carries the verified line references).
|
||||
- If alknet's rewrite later re-decides an inherited posture, both
|
||||
series need a superseding note.
|
||||
|
||||
## References
|
||||
|
||||
- `docs/research/phase-0.md` — the Phase 0 inventory (verified
|
||||
invariants, gaps, noq investigation)
|
||||
- alknet ADR-082 (extraction), ADR-083 (endpoint takes no TLS config),
|
||||
ADR-084 (aws-lc-rs), ADR-027 (identity model), ADR-034 (verifier
|
||||
selection), ADR-086 §3 (split ALPN lists), ADR-087
|
||||
(`TlsClientConfig`), ADR-088 (`TlsError`, root-store fallback), 089
|
||||
(dial seam), 091 (`ConnectionCredentials`)
|
||||
- alknet `docs/architecture/crates/tls/README.md` — the full crate
|
||||
spec this crate implements
|
||||
- ADR-002 — the `TlsError` shape (gap #1)
|
||||
- ADR-003 — the QUIC feature: noq replaces quinn
|
||||
- ADR-004 — the API surface (gap #2, accessor shapes)
|
||||
- ADR-005 — config-type ownership (gap #3)
|
||||
Reference in New Issue
Block a user