Files

T

glm-5.3-flash d74a27f764 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

2026-09-10 05:37:55 +00:00

4.6 KiB

Raw Blame History

status, last_updated

status	last_updated
accepted	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)

4.6 KiB Raw Blame History