alknet/docs/architecture/questions/063-tlserror-shape.md

# OQ-63: `TlsError` Shape

- **Origin**: `docs/architecture/crates/tls/README.md`
  (`TlsError` is referenced as the `Result` error type in
  `TlsServerConfig::new`, `TlsClientConfig::new`, `for_quinn()`, and the
  crate's public signatures, but is never sketched or defined); ADR-082
  (same — `TlsError` in signatures, no shape); ADR-087 (extends the
  surface to `TlsClientConfig::new` — the client-side error variants).
- **Status**: resolved (ADR-088)
- **Door type**: one-way (the error type is the public API surface of
  `alknet-tls`; changing it after consumers exist is a breaking change
  to every assembly-layer call site)
- **Priority**: high (an implementer cannot write the crate without
  deciding this; guessing produces divergent shapes — one thin
  `rustls::Error` wrapper vs a 10-variant enum with per-path context)
- **Impacts**: Blocks `alknet-tls` implementation — both
  `TlsServerConfig::new` and `TlsClientConfig::new` reference `TlsError`
  in their signatures. Blocks the hub's assembly-layer wiring (which
  calls both). This is the next decision needed before the TLS crate
  can be implemented.
- **Resolution**: **Decided (ADR-088).** `TlsError` is a single
  `#[non_exhaustive]` enum with one variant per failure category, owned
  by `alknet-tls` (not re-exported from core). The variants, grounded in
  the actual error-producing call sites and the dependency-crate sources
  (rustls 0.23.41, rustls-pemfile 2.2.0, rcgen 0.13.2, quinn-proto
  0.11.15, rustls-acme 0.12.1):

  - **Cert/key loading** (`X509`: file read + PEM parse;
    `SelfSigned`: rcgen generation) — currently `io::Error`-wrapped in
    the core code.
  - **rustls config construction** (`builder_with_provider` /
    `with_safe_default_protocol_versions` /
    `with_single_cert` / `with_cert_resolver`) — currently
    `rustls::Error`-wrapped.
  - **quinn wrap** (`QuicServerConfig::try_from(rustls::ServerConfig)`)
    — the one path where `for_quinn()` can fail; currently
    `io::Error::other(e)`-wrapped.
  - **ACME** — `rustls-acme` has its own error types; the ACME task
    runs in the background and surfaces errors via events (logged, not
    returned from `new`), so `new`'s ACME path may only need to cover
    "ACME feature not enabled but `TlsIdentity::Acme` configured"
    (currently an `io::ErrorKind::Unsupported`).
  - **Client verifier construction** (ADR-087) — `TlsClientConfig::new`
    builds a `rustls::ClientConfig` with ADR-034's verifier selection.
    Failure modes: verifier construction error (bad fingerprint format,
    CA store init failure), unknown-remote fail-closed (not an error to
    return — it's a `Result::Err` the caller gets for trying to connect
    to an unknown raw-key remote), provider init failure. These
    overlap with the server-side rustls-build errors but have
    client-specific context (verifier selection inputs).

  The open question was the granularity: a single `TlsError` enum with
  variants per failure category (cert-load, rustls-build, quinn-wrap,
  acme-disabled) vs a thin wrapper around `rustls::Error` /
  `io::Error`. **Resolved: the single-enum shape.** The thin wrapper is
  actively wrong here — three findings from the dependency-crate source
  drive the decision: (1) `for_quinn()` fails with
  `NoInitialCipherSuite`, a distinct type from `rustls::Error` — a thin
  `rustls::Error` wrapper cannot represent the `for_quinn()` failure;
  (2) `rustls_pemfile::Error` is not a `std::error::Error` (no
  `Display`, no `Error` impl), so pemfile's BufRead APIs return
  `io::Error` — a `#[from] rustls_pemfile::Error` would not compile;
  (3) `WebPkiServerVerifier::build()` returns `VerifierBuilderError`,
  not `rustls::Error` — a thin wrapper cannot represent "empty CA root
  store" as a first-class failure. The six variants: `CertLoad(io::Error)`,
  `SelfSigned(rcgen::Error)`, `Rustls(rustls::Error)`,
  `VerifierBuild(VerifierBuilderError)`, `QuinnWrap(NoInitialCipherSuite)`
  (quinn-gated), `AcmeConfig(String)`. ACME `EventError`/`OrderError`
  are deliberately absent — they are stream events, logged not returned
  from `new`. The unknown-raw-key fail-closed is deliberately absent —
  it is a handshake-time rejection (dial time), not a
  config-construction error (`new` time). See ADR-088 for the full
  rationale, the variant definitions, and the "what is NOT a variant"
  list.

  Subsidiary question: does `TlsError` live in `alknet-tls` (owned by
  the crate that produces it) or is it re-exported from `alknet-core`?
  **Resolved: `alknet-tls`, owned by the crate that produces it.**
  `alknet-core`'s `EndpointError` no longer has a `TlsConfig` variant
  after ADR-083 (the endpoint takes no TLS config); core does not need to
  know about `TlsError`. Re-exporting from core would invert the
  ownership (core re-exporting a type from a crate that depends on it).
- **Cross-references**: ADR-088 (the resolution — single enum, owned by
  `alknet-tls`, six variants), ADR-082 (the extraction that introduces
  `TlsError`), ADR-083 (the endpoint refactor that removes
  `EndpointError::TlsConfig`, making `TlsError` the sole TLS error
  surface), ADR-087 (extends the surface to client-side variants),
  `crates/alknet-core/src/endpoint.rs` (the current
  `io::Error`-wrapping pattern the new type replaces),
  `crates/alknet-call/src/client/call_client.rs` (the current
  `String`-wrapping pattern on the client side)