---
status: reviewed
last_updated: 2026-09-10
---

# alktls — Architecture

The authoritative architecture spec for the alktls crate (Phase 1 of
the SDD process). The spec docs advanced **Draft → Reviewed** at the
Phase 2 implementation review gate (see the lifecycle note at the end);
statuses update here as docs advance.

All docs follow the SDD process conventions: specs reference ADRs and
OQs by number, ADRs explain WHY, `open-questions.md` tracks what is
unresolved.

## Documents

| Doc | Status | Scope |
|-----|--------|-------|
| [overview.md](overview.md) | Reviewed | Purpose, transport picture, API surface, ADR/OQ index |
| [server.md](server.md) | Reviewed | `TlsServerConfig`, resolvers, ACME path, server invariants |
| [client.md](client.md) | Reviewed | `TlsClientConfig`, verifier selection, client auth, root-store fallback |
| [open-questions.md](open-questions.md) | live | The authoritative OQ tracker (all Phase 0 OQs resolved at entry) |

## ADRs

| ADR | Status | Decision |
|-----|--------|----------|
| [001](decisions/001-inherit-alknet-tls-design.md) | Accepted | Inherit the alknet TLS design as the baseline; deviations recorded as alktls ADRs |
| [002](decisions/002-tlserror-shape.md) | Accepted | `TlsError`: the ADR-088 six-variant shape from day one; config-construction scope boundary |
| [003](decisions/003-noq-replaces-quinn.md) | Accepted | The QUIC feature is `noq` (iroh's extracted fork), not `quinn`; iroh stays key-not-config |
| [004](decisions/004-accessor-surface.md) | Accepted | Complete accessors: `for_tcp_tls()` adopted; server borrows, client consumes |
| [005](decisions/005-config-types-move-into-alktls.md) | Accepted | Identity + credentials + fingerprint types move into alktls; auth layer stays out |
| [006](decisions/006-module-layout-and-tests.md) | Accepted | Eight-module layout; seed tests + integration invariant pins |
| [007](decisions/007-cert-type-negotiation.md) | Accepted | RFC 7250 cert-type negotiation: the offer follows the identity (deviation from alknet; resolves OQ-TLS-10) |
| [008](decisions/008-server-path-possession-verification.md) | Accepted | Server-path proof-of-possession: the verifying verifier is the default on every path (resolves OQ-TLS-09) |

## Lifecycle

Docs move `Draft` → `Reviewed` when their open questions are resolved
and the architecture review reports zero critical issues; ADRs are
Accepted at write time and never revert (supersede instead).
`open-questions.md` is the authoritative tracker; the Phase 0 doc's
OQ statuses are the historical record.

**API-freeze note (2026-09-10):** the Phase 2 implementation review
gate (`tasks/review-impl.md`) passed with zero un-pinned divergences
(two ADR amendments recorded — 002's verifier-error path, 003's noq
provider feature). **The public API surface — the `lib.rs` re-export
block per ADR-004/005/006 — is frozen as of that review**; the alknet
rewrite compiles against it. Additive evolution only.

## Phase status

- **Phase 0** (complete, 2026-09-10): `docs/research/phase-0.md` —
  extraction inventory, verified invariants, gaps, noq investigation,
  OQ-TLS-01..08.
- **Phase 1** (this directory): all Phase 0 OQs resolved at entry —
  six via ADR-001..006, two as documented behavior (OQ-TLS-02,
  OQ-TLS-06). **Reviewed 2026-09-10** at the Phase 2 gate.
- **Phase 2** (complete, 2026-09-10): decomposition into `tasks/` +
  execution — the eight-task port graph landed crate-init →
  port-identity/fingerprint/pem-signing → port-server/port-client →
  integration-suite → this review gate. The crate is ready for the
  rewrite to consume.