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

137 lines
5.6 KiB
Markdown
Raw Blame History

---
status: draft
last_updated: 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](decisions/005-config-types-move-into-alktls.md).
- **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](client.md). 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](decisions/004-accessor-surface.md).
- **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](decisions/004-accessor-surface.md).
- **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](decisions/003-noq-replaces-quinn.md).
- **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](decisions/006-module-layout-and-tests.md).
- **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](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