---
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)