glm-5.3-flash
d74a27f764
- 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
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
---
|
|
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) |