alkdev/alktls
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4bdc12e84fe9085db65ad2ef44ab228b4d026d41
alktls/docs/architecture/open-questions.md
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

5.6 KiB
Raw Blame History

status, last_updated
status last_updated
draft 2026-09-10

Open Questions

Centralized tracker for alktls. Promoted from Phase 0 (docs/research/phase-0.md OQ-TLS-01..08) on 2026-09-10. Statuses here are authoritative; the Phase 0 doc's statuses are the historical record.

Statuses at a glance

OQ Topic Status Priority
OQ-TLS-01 Config-type ownership resolved (ADR-005) high
OQ-TLS-02 SelfSigned on the client path resolved (documented behavior kept) low
OQ-TLS-03 for_tcp_tls() adoption resolved (ADR-004) medium
OQ-TLS-04 Accessor borrow-vs-consume resolved (ADR-004) medium
OQ-TLS-05 Test surface resolved (ADR-006) low
OQ-TLS-06 ACME task shutdown surface resolved (detached-only for v1) low
OQ-TLS-07 iroh key surface resolved (ADR-005, byte access pinned) low
OQ-TLS-08 quinn → noq feature rename resolved (ADR-003) high

Identity & types

OQ-TLS-01: Where do the config types live, and what moves?

  • Origin: docs/research/phase-0.md §Gaps #3
  • Status: resolved (2026-09-10)
  • Priority: high
  • Resolution: alktls owns the identity types (TlsIdentity, Ed25519SecretKey, AcmeDirectory), the credential bundle (ConnectionCredentials, RemoteIdentity), and the fingerprint helpers. The auth layer (PeerEntry, AuthPolicy, IdentityProvider) stays out — peer-level identity is not TLS. Decision recorded in ADR-005.
  • Cross-references: ADR-001, ADR-005

OQ-TLS-02: SelfSigned on the client path — encode or document?

  • Origin: docs/research/phase-0.md §Gaps #4
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: keep the current behavior (present nothing via NoClientCertResolver) and document it on the identity type and in the client spec. Type-level enforcement (config error, like Acme) was rejected: SelfSigned as a local identity meaning "present nothing" is coherent — the dev cert exists for the server side, and presenting a self-signed client cert would add nothing the fingerprint path uses.
  • Consequences: a future dev client-auth use case would need a type-level change (additive, not a one-way door).
  • Cross-references: ADR-001 (identity model), client spec

OQ-TLS-07: iroh relationship in the rewrite

  • Origin: docs/research/phase-0.md OQ-TLS-07
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: the requirement is pinned and verified — Ed25519SecretKey keeps 32-byte raw access (from_bytes / as_bytes) with the same byte-level surface iroh's iroh_base::SecretKey consumes (from_bytes / to_bytes; 32 raw bytes in/out — verified against iroh 1.1 in Phase 0). iroh stays key-not-config; no for_iroh(). The rewrite's iroh dial consumes the type alktls owns (ADR-005); no alktls-side work remains.
  • Cross-references: ADR-003, ADR-005

API surface

OQ-TLS-03: for_tcp_tls() — adopt the spec accessor?

  • Origin: docs/research/phase-0.md §Gaps #2
  • Status: resolved (2026-09-10)
  • Priority: medium
  • Resolution: adopted — for_tcp_tls(&self) -> tokio_rustls::TlsAcceptor, feature-gated on tcp, infallible. Decision and rationale in ADR-004.
  • Cross-references: ADR-004

OQ-TLS-04: for_quinn() — self or &self?

  • Origin: docs/research/phase-0.md OQ-TLS-04
  • Status: resolved (2026-09-10)
  • Priority: medium
  • Resolution: server accessors take &self (one config feeds N transports — the ADR-082 story, directly expressible); client accessors consume self (per-dial build, zero-cost into_rustls_config). Full rationale in ADR-004.
  • Cross-references: ADR-003, ADR-004

OQ-TLS-08: quinn feature vs noq feature — and the MSRV floor

  • Origin: docs/research/phase-0.md §Prior art: noq
  • Status: resolved (2026-09-10)
  • Priority: high
  • Resolution: the feature is noq (no quinn feature ever published; rename is pre-consumer and free). noq 1.2 pinned ("1.2", default-features off, rustls feature), bump deliberately. The MSRV half of the OQ was separately resolved the same day (ecosystem floor 1.88; time pin dropped). Decision in ADR-003.
  • Cross-references: ADR-002, ADR-003, ADR-004

Quality / process

OQ-TLS-05: Test surface for the invariants

  • Origin: docs/research/phase-0.md §Gaps #5
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: port the in-module seed tests AND add tests/ integration tests for the cross-module surfaces; pin the exact nine-scheme list (regression-proof). Decision in ADR-006.
  • Cross-references: ADR-006

OQ-TLS-06: Does the ACME state machine need a shutdown surface?

  • Origin: docs/research/phase-0.md OQ-TLS-06
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: detached-only — the handle is stored (keeping TlsServerConfig non-Clone) and never aborted; the ACME task runs for the process lifetime. Documented on the type.
  • Consequences: a shutdown() (abort + await) surface would be additive and cheap if the rewrite's graceful-shutdown design wants one later — not a one-way door.
  • Cross-references: ADR-001 (one-ACME-machine rule), server.md

Deferred / Blocked

(none — all promoted OQs are resolved; new OQs added during review land here with their deferral half per docs/sdd_process.md)

Reference in New Issue View Git Blame Copy Permalink