docs(adr-027): TLS identity redesign — ACME + RawKey decoupling
ADR-027 resolves the architectural gap surfaced when ACME integration became a concrete target: 1. TlsIdentity::Acme variant — static config data (domains, cache_dir, directory, contact) with async AcmeState constructed at endpoint setup via two-phase TlsSetup (not stuffed into the Clone-able enum). 2. TlsIdentity::RawKey decoupled from the iroh feature — uses Ed25519SecretKey (alknet-core-owned wrapper over ed25519_dalek) instead of iroh::SecretKey. Raw-key TLS identity (RFC 7250, the default for most alknet nodes) now works in quinn-only builds. iroh transport converts via SecretKey::from_bytes. 3. ACME feature-gated behind new acme feature (rustls-acme optional dep). Non-ACME builds don't compile it. 4. dispatch_quinn guard for acme-tls/1 challenge connections — TLS-ALPN-01 is handled at the rustls cert resolver layer during the handshake; the guard closes challenge connections gracefully instead of logging a misleading "no handler" warning. Research confirmed QUIC (quinn) handles ACME challenges differently than TCP (reverse-proxy): quinn gives no ClientHello peek hook, but the challenge is fully answered at the cert resolution step before the connection surfaces to the application. No handler registration needed. Spec updates: config.md, endpoint.md, open-questions.md (OQ-12), overview.md + README.md (ADR index), ADR-010 (cross-ref). Tasks: core/rawkey-decouple-from-iroh (gen 1, no deps), core/acme-integration (gen 2, depends on rawkey). Graph: 36 tasks.
This commit is contained in:
@@ -61,6 +61,7 @@ last_updated: 2026-06-23
|
||||
| [024](decisions/024-operation-registry-layering.md) | Operation Registry Layering | Accepted |
|
||||
| [025](decisions/025-vault-local-only-dispatch.md) | Vault Local-Only Dispatch | Accepted |
|
||||
| [026](decisions/026-vault-key-model-hd-derivation.md) | Vault Key Model — HD Derivation | Accepted |
|
||||
| [027](decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md) | TLS Identity Redesign — ACME + RawKey Decoupling | Accepted |
|
||||
|
||||
## Open Questions
|
||||
|
||||
@@ -82,7 +83,7 @@ See [open-questions.md](open-questions.md) for the full tracker.
|
||||
- **OQ-04**: Dynamic handler registration — static at startup (ADR-010); scoped to the `HandlerRegistry` (ALPN-level) by ADR-024, which governs `OperationRegistry` mutability separately
|
||||
- **OQ-07**: Call protocol scope — bidirectional streams, EventEnvelope, ID-based correlation (ADR-012)
|
||||
- **OQ-11**: Handler-level auth resolution observability — handlers store resolved identity on Connection (Option B); two identity scopes: connection-level (observability) and per-request (ACL)
|
||||
- **OQ-12**: TLS identity provisioning — two use cases: RFC 7250 raw keys (default, P2P) and X.509 certs (domain-hosted, browsers). ACME is a proven pattern.
|
||||
- **OQ-12**: TLS identity provisioning — two use cases: RFC 7250 raw keys (default, P2P) and X.509 certs (domain-hosted, browsers). ACME designed in ADR-027; RawKey decoupled from iroh feature.
|
||||
- **OQ-13**: Operation path format — `/{service}/{op}` is the correct design for alknet-call, not a simplification
|
||||
- **OQ-14**: Batch operation semantics — multiple correlated `call.requested` events is the correct protocol design, not a simplification
|
||||
- **OQ-19**: Session-scoped registries — agent-written operations via `OperationEnv` trait layering; protocol doesn't need changes; `OperationEnv` must remain a trait. Generalized by ADR-024 to cover connection-scoped overlays as well.
|
||||
|
||||
@@ -41,15 +41,24 @@ pub enum TlsIdentity {
|
||||
/// RFC 7250 raw Ed25519 public key.
|
||||
/// No domain, no CA, no cert renewal. Key = identity.
|
||||
/// Same model as iroh's NodeId, but for direct QUIC connections.
|
||||
/// `SecretKey` is `iroh::SecretKey` (Ed25519) — re-exported from iroh,
|
||||
/// which alknet-core already depends on (feature-gated, ADR-010). The
|
||||
/// key can be derived from alknet-vault at the assembly layer
|
||||
/// (endpoint.md) or generated fresh. See OQ-12, W14.
|
||||
RawKey(iroh::SecretKey),
|
||||
/// Uses `Ed25519SecretKey` (alknet-core-owned wrapper over
|
||||
/// `ed25519_dalek::SigningKey`) — not coupled to the `iroh` feature.
|
||||
/// Available in quinn-only builds. See ADR-027.
|
||||
RawKey(Ed25519SecretKey),
|
||||
|
||||
/// Self-signed X.509 cert for development.
|
||||
/// Generated on startup, not validated by external clients.
|
||||
SelfSigned,
|
||||
|
||||
/// ACME auto-provisioning via Let's Encrypt (rustls-acme).
|
||||
/// Produces X.509 certs at runtime; handles TLS-ALPN-01 challenges
|
||||
/// and automatic renewal. Feature-gated behind `acme`. See ADR-027.
|
||||
Acme {
|
||||
domains: Vec<String>,
|
||||
cache_dir: PathBuf,
|
||||
directory: AcmeDirectory, // Production, Staging, Custom(url)
|
||||
contact: Vec<String>, // e.g. ["mailto:admin@example.com"]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
@@ -57,7 +66,52 @@ pub enum TlsIdentity {
|
||||
|
||||
TLS identity in alknet has two distinct use cases, not one. The original `tls_cert: Option<PathBuf>` / `tls_key: Option<PathBuf>` assumed X.509 was the only TLS identity model. RFC 7250 raw public keys (used by iroh, supported by rustls) provide a fundamentally different mode: Ed25519 key as identity, no X.509, no CA, no domain. This is the default for most alknet nodes — it works natively with SSH auth and git. X.509 certs are for domain-hosted services and browser/WebTransport clients, which don't support RFC 7250.
|
||||
|
||||
The `TlsIdentity` enum captures both use cases plus a development mode. See OQ-12 for the full rationale.
|
||||
The `TlsIdentity` enum captures all four modes. See OQ-12 for the use-case
|
||||
rationale and [ADR-027](../../decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md)
|
||||
for the ACME + RawKey decoupling design.
|
||||
|
||||
### `Ed25519SecretKey`
|
||||
|
||||
A thin alknet-core-owned wrapper over `ed25519_dalek::SigningKey`. Not
|
||||
feature-gated — available in all builds. Used by `TlsIdentity::RawKey`
|
||||
for RFC 7250 raw public key TLS identity. When the `iroh` transport is
|
||||
configured, `build_iroh_endpoint` converts to `iroh::SecretKey::from_bytes`
|
||||
(see ADR-027, Decision 4).
|
||||
|
||||
### `AcmeDirectory`
|
||||
|
||||
```rust
|
||||
pub enum AcmeDirectory {
|
||||
Production, // Let's Encrypt production
|
||||
Staging, // Let's Encrypt staging
|
||||
Custom(String), // custom ACME directory URL
|
||||
}
|
||||
```
|
||||
|
||||
### Construction examples (updated)
|
||||
|
||||
```rust
|
||||
// P2P / key-based identity (default for most nodes) — no iroh dep needed
|
||||
let p2p_config = StaticConfig {
|
||||
listen_addr: Some("0.0.0.0:4433".parse()?),
|
||||
tls_identity: Some(TlsIdentity::RawKey(Ed25519SecretKey::generate())),
|
||||
iroh_relay: None,
|
||||
drain_timeout: Duration::from_secs(2),
|
||||
};
|
||||
|
||||
// Domain-hosted service with ACME auto-provisioning
|
||||
let acme_config = StaticConfig {
|
||||
listen_addr: Some("0.0.0.0:443".parse()?),
|
||||
tls_identity: Some(TlsIdentity::Acme {
|
||||
domains: vec!["relay.alk.dev".to_string()],
|
||||
cache_dir: "/var/lib/alknet/acme".into(),
|
||||
directory: AcmeDirectory::Production,
|
||||
contact: vec!["mailto:admin@alk.dev".to_string()],
|
||||
}),
|
||||
iroh_relay: None,
|
||||
drain_timeout: Duration::from_secs(2),
|
||||
};
|
||||
```
|
||||
|
||||
### Key differences from reference implementation
|
||||
|
||||
@@ -80,12 +134,12 @@ The reference `StaticConfig` (in `alknet-main/crates/alknet-core/src/config/stat
|
||||
// P2P / key-based identity (default for most nodes)
|
||||
let p2p_config = StaticConfig {
|
||||
listen_addr: Some("0.0.0.0:4433".parse()?),
|
||||
tls_identity: Some(TlsIdentity::RawKey(iroh::SecretKey::generate())),
|
||||
tls_identity: Some(TlsIdentity::RawKey(Ed25519SecretKey::generate())),
|
||||
iroh_relay: None,
|
||||
drain_timeout: Duration::from_secs(2),
|
||||
};
|
||||
|
||||
// Domain-hosted service (relays, public services, browsers)
|
||||
// Domain-hosted service (relays, public services, browsers) — manual certs
|
||||
let domain_config = StaticConfig {
|
||||
listen_addr: Some("0.0.0.0:4433".parse()?),
|
||||
tls_identity: Some(TlsIdentity::X509 {
|
||||
|
||||
@@ -206,7 +206,7 @@ This mode works natively with SSH auth (same key type) and git (SSH key-based au
|
||||
Nodes that serve browser/WebTransport clients, or nodes with public domain names, use X.509 certificates. This has two sub-cases:
|
||||
|
||||
- **Manual**: Provide cert/key file paths via `TlsIdentity::X509`. The endpoint loads them at startup and builds a standard `rustls::ServerConfig`.
|
||||
- **ACME auto-provisioning**: Let's Encrypt via `rustls-acme`. The reverse-proxy project (`/workspace/@alkdev/reverse-proxy`) demonstrates the complete pattern: per-listener ACME state machine, `ResolvesServerCertAcme` rustls integration, TLS-ALPN-01 challenge handling, automatic renewal. This is a proven, solved implementation pattern. It will be adapted to alknet's `AlknetEndpoint` context as an additional `TlsIdentity` variant or `ResolvesServerCert` implementation.
|
||||
- **ACME auto-provisioning**: Let's Encrypt via `rustls-acme`. `TlsIdentity::Acme { domains, cache_dir, directory, contact }` carries the static config; the endpoint constructs the `AcmeState` async state machine and `ResolvesServerCertAcme` at setup time (ADR-027). The `acme` feature gate keeps `rustls-acme` out of non-ACME builds. See [ADR-027](../../decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md) for the full design.
|
||||
|
||||
`TlsIdentity::SelfSigned` is for development only — the endpoint generates a self-signed cert on startup. External clients will not trust it.
|
||||
|
||||
@@ -219,10 +219,17 @@ The iroh endpoint does not need TLS certificate configuration — it uses `NodeI
|
||||
| Path | Identity model | Client compatibility | Use case |
|
||||
|------|---------------|---------------------|----------|
|
||||
| quinn + `TlsIdentity::RawKey` | RFC 7250 Ed25519 raw key | alknet-native, SSH, git | Personal nodes, P2P, most deployments |
|
||||
| quinn + `TlsIdentity::X509` | X.509 domain certificate | All clients including browsers | Relays, public services, WebTransport |
|
||||
| quinn + `TlsIdentity::X509` | X.509 domain certificate (manual) | All clients including browsers | Relays, public services, WebTransport |
|
||||
| quinn + `TlsIdentity::Acme` | X.509 via ACME auto-provisioning | All clients including browsers | Public relays, domain-hosted services |
|
||||
| quinn + `TlsIdentity::SelfSigned` | X.509 self-signed cert | None (dev only) | Local development |
|
||||
| iroh | NodeId (Ed25519, RFC 7250 built-in) | alknet-native, iroh clients | NAT traversal, home servers |
|
||||
|
||||
Note: `TlsIdentity::RawKey` uses `Ed25519SecretKey` (alknet-core-owned,
|
||||
backed by `ed25519-dalek`), not `iroh::SecretKey`. It is available in
|
||||
quinn-only builds without the `iroh` feature. When the iroh transport is
|
||||
also configured, `build_iroh_endpoint` converts the key to
|
||||
`iroh::SecretKey::from_bytes` (ADR-027).
|
||||
|
||||
## Graceful Shutdown
|
||||
|
||||
```rust
|
||||
@@ -294,4 +301,4 @@ See [open-questions.md](../../open-questions.md) for full details.
|
||||
|
||||
- **OQ-04**: Resolved — HandlerRegistry is static at startup.
|
||||
- **OQ-05**: Resolved — multi-connectivity endpoint with quinn + iroh, both feature-gated.
|
||||
- **OQ-12**: Resolved — two distinct TLS identity use cases: RFC 7250 raw keys (default, P2P) and X.509 certs (domain-hosted, browsers). ACME is a proven pattern from the reverse-proxy project, not speculative future work.
|
||||
- **OQ-12**: Resolved — two distinct TLS identity use cases: RFC 7250 raw keys (default, P2P) and X.509 certs (domain-hosted, browsers). ACME auto-provisioning designed in [ADR-027](../../decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md); RawKey decoupled from the `iroh` feature (available in quinn-only builds).
|
||||
@@ -183,7 +183,7 @@ pub enum HandlerError {
|
||||
**Negative:**
|
||||
- alknet-core depends on both quinn and iroh (mitigated: both are feature-gated; a node that only needs one doesn't compile the other)
|
||||
- The endpoint is more complex than a single quinn listener — it manages multiple accept loops
|
||||
- TLS identity provisioning has two distinct use cases: RFC 7250 raw keys (default for P2P/key-based identity) and X.509 certs (for domain-hosted services and browsers). ACME auto-provisioning for X.509 is a proven pattern from the reverse-proxy project, not speculative future work. See OQ-12.
|
||||
- TLS identity provisioning has two distinct use cases: RFC 7250 raw keys (default for P2P/key-based identity) and X.509 certs (for domain-hosted services and browsers). ACME auto-provisioning and RawKey decoupling from the `iroh` feature are designed in ADR-027. See OQ-12.
|
||||
- No runtime handler registration without regenerating the TLS config (mitigated: two-way door, start static, add ArcSwap later if needed)
|
||||
|
||||
## References
|
||||
|
||||
@@ -0,0 +1,279 @@
|
||||
# ADR-027: TLS Identity Redesign — ACME Integration + RawKey Decoupling
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
OQ-12 marked "resolved" identified two TLS identity use cases: RFC 7250
|
||||
raw Ed25519 keys (default, P2P) and X.509 certs (domain-hosted, browsers).
|
||||
ACME auto-provisioning was described as "additive — it will be adapted
|
||||
when domain-hosted nodes need it." That deferral created two
|
||||
architectural issues that surface now that ACME is a concrete target.
|
||||
|
||||
### Issue 1: `TlsIdentity` cannot represent ACME
|
||||
|
||||
`TlsIdentity` is `#[derive(Debug, Clone)]` and lives in `StaticConfig` —
|
||||
a static, synchronous config value. ACME requires:
|
||||
|
||||
- A long-lived async state machine (`AcmeState` event loop, spawned for
|
||||
the endpoint's lifetime) that handles ordering, challenge response,
|
||||
cert renewal, and cache I/O.
|
||||
- TLS-ALPN-01 challenge handling: `acme-tls/1` must be in the server's
|
||||
`alpn_protocols`, and a `ResolvesServerCertAcme` must serve challenge
|
||||
certs during the TLS handshake.
|
||||
- Config fields: domains, cache directory, ACME directory URL, contact
|
||||
email.
|
||||
|
||||
`AcmeState` is not `Clone`. It cannot be a `TlsIdentity` variant. The
|
||||
current `build_rustls_server_config(&TlsIdentity) -> ServerConfig` is
|
||||
synchronous — there's no room for spawning an async state machine or
|
||||
holding a runtime resolver handle. The reverse-proxy project solved this
|
||||
with a two-phase construction: static config → `TlsMode` (runtime
|
||||
objects) → `ServerConfig`. alknet needs the same split.
|
||||
|
||||
### Issue 2: `RawKey` is coupled to the `iroh` feature
|
||||
|
||||
`TlsIdentity::RawKey(iroh::SecretKey)` is gated `#[cfg(feature = "iroh")]`.
|
||||
The `RawKeyCertResolver` and `Ed25519SigningKey` impls are gated
|
||||
`#[cfg(all(feature = "quinn", feature = "iroh"))]`. This means a
|
||||
quinn-only build (the default feature set) **cannot use RFC 7250 raw-key
|
||||
identity** — the very mode described as "default for most alknet nodes."
|
||||
|
||||
The coupling is artificial. `iroh::SecretKey` is a thin newtype over
|
||||
`ed25519_dalek::SigningKey` (`pub struct SecretKey(SigningKey)`). The
|
||||
alknet code uses exactly three APIs: `.public().as_bytes()`, `.sign(msg)`,
|
||||
and `.clone()`. None of these are iroh-specific. The raw-key TLS path
|
||||
needs Ed25519 signing + SPKI encoding — both available from
|
||||
`ed25519-dalek` + `rustls` without iroh.
|
||||
|
||||
The iroh *transport* (`build_iroh_endpoint`) does need `iroh::SecretKey`
|
||||
for `iroh::Endpoint::builder().secret_key(...)`. If `TlsIdentity::RawKey`
|
||||
no longer carries an `iroh::SecretKey`, the iroh transport must convert
|
||||
from the new key type — trivial since `iroh::SecretKey::from_bytes(&[u8;
|
||||
32])` accepts raw Ed25519 key bytes.
|
||||
|
||||
### ACME challenge handling with quinn (QUIC, not TCP)
|
||||
|
||||
Research confirmed how TLS-ALPN-01 works with quinn:
|
||||
|
||||
- The `ResolvesServerCertAcme` resolver intercepts the challenge at the
|
||||
**cert resolution step**, during the TLS handshake, before the
|
||||
handshake result is surfaced to the application.
|
||||
- When an ACME CA connects with ALPN `[acme-tls/1]`, rustls calls the
|
||||
resolver, which returns the challenge cert. The handshake completes.
|
||||
The CA inspects the cert's SAN and validates the challenge — no
|
||||
application-layer data exchange needed.
|
||||
- quinn's `connecting.await` then returns a completed `Connection` with
|
||||
ALPN `acme-tls/1`. alknet's `dispatch_quinn` would find no handler for
|
||||
that ALPN and close the connection. **The challenge already succeeded**
|
||||
— the close is cosmetic.
|
||||
- Unlike the reverse-proxy (TCP + `LazyConfigAcceptor`), quinn gives no
|
||||
"peek at ClientHello" hook. The challenge is fully TLS-layer-handled;
|
||||
the application only needs to close challenge connections gracefully
|
||||
(silent close, not a "no handler" warning).
|
||||
|
||||
Key constraint: ACME requires `with_cert_resolver(ResolvesServerCertAcme)`,
|
||||
not `with_single_cert`. You cannot just append `acme-tls/1` to an
|
||||
`X509`/`SelfSigned` config — there'd be no resolver to serve the
|
||||
challenge cert. ACME is a distinct `ServerConfig` construction path.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Add `TlsIdentity::Acme` variant (static config data only)
|
||||
|
||||
```rust
|
||||
pub enum TlsIdentity {
|
||||
X509 { cert: PathBuf, key: PathBuf },
|
||||
RawKey(Ed25519SecretKey), // see Decision 3
|
||||
SelfSigned,
|
||||
Acme { // NEW
|
||||
domains: Vec<String>,
|
||||
cache_dir: PathBuf,
|
||||
directory: AcmeDirectory, // enum: Production, Staging, Custom(String)
|
||||
contact: Vec<String>, // e.g. ["mailto:admin@example.com"]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`Acme` holds only static, `Clone`/`Debug`-safe config data. No
|
||||
`AcmeState`, no resolver, no runtime objects. The async state machine is
|
||||
constructed at endpoint setup time (Decision 2).
|
||||
|
||||
### 2. Split server-config construction into two phases
|
||||
|
||||
Replace the synchronous `build_rustls_server_config(&TlsIdentity) ->
|
||||
ServerConfig` with a two-phase construction:
|
||||
|
||||
**Phase 1 — `TlsSetup` (async, at endpoint construction):**
|
||||
|
||||
```rust
|
||||
struct TlsSetup {
|
||||
server_config: rustls::ServerConfig,
|
||||
acme_state: Option<AcmeStateHandle>, // spawned task + handle for shutdown
|
||||
}
|
||||
```
|
||||
|
||||
For `X509`, `SelfSigned`, `RawKey`: construct `ServerConfig`
|
||||
synchronously (current path, unchanged). `acme_state` is `None`.
|
||||
|
||||
For `Acme`: construct `AcmeConfig`, spawn the `AcmeState` event loop,
|
||||
get `ResolvesServerCertAcme`, build `ServerConfig` with
|
||||
`with_cert_resolver(resolver)`, add `acme-tls/1` to `alpn_protocols`.
|
||||
`acme_state` is `Some(handle)` so the endpoint can abort the ACME task
|
||||
on shutdown.
|
||||
|
||||
**Phase 2 — use `TlsSetup.server_config` to build `quinn::ServerConfig`:**
|
||||
|
||||
Same as today: `QuicServerConfig::try_from(rustls_config)` →
|
||||
`quinn::ServerConfig::with_crypto(...)`.
|
||||
|
||||
The `TlsSetup` is constructed inside `AlknetEndpoint::new()` (or
|
||||
`run_quinn_accept_loop`), not inside `TlsIdentity`. The `TlsIdentity`
|
||||
enum stays a pure data structure.
|
||||
|
||||
### 3. Decouple `RawKey` from iroh — use `ed25519-dalek` directly
|
||||
|
||||
Replace `TlsIdentity::RawKey(iroh::SecretKey)` with
|
||||
`TlsIdentity::RawKey(Ed25519SecretKey)`, where `Ed25519SecretKey` is a
|
||||
thin alknet-core-owned wrapper over `ed25519_dalek::SigningKey`:
|
||||
|
||||
```rust
|
||||
pub struct Ed25519SecretKey(ed25519_dalek::SigningKey);
|
||||
```
|
||||
|
||||
This type is `Clone`, `Debug` (redacting), `Zeroize`, and not gated
|
||||
behind any feature flag. `ed25519-dalek` becomes a direct dependency of
|
||||
alknet-core (it's already in the dependency tree transitively via iroh).
|
||||
|
||||
The `RawKeyCertResolver` and `Ed25519SigningKey` rustls impls move from
|
||||
`#[cfg(all(feature = "quinn", feature = "iroh"))]` to
|
||||
`#[cfg(feature = "quinn")]` — raw-key TLS identity works in quinn-only
|
||||
builds.
|
||||
|
||||
The `iroh` feature gate on `TlsIdentity::RawKey` is removed. The
|
||||
variant is always available.
|
||||
|
||||
### 4. iroh transport converts from `Ed25519SecretKey`
|
||||
|
||||
`build_iroh_endpoint` currently reads `TlsIdentity::RawKey(iroh::SecretKey)`
|
||||
and passes it to `iroh::Endpoint::builder().secret_key(...)`. After
|
||||
decoupling, it converts:
|
||||
|
||||
```rust
|
||||
if let Some(TlsIdentity::RawKey(key)) = static_config.tls_identity.as_ref() {
|
||||
let iroh_key = iroh::SecretKey::from_bytes(key.as_bytes());
|
||||
builder = builder.secret_key(iroh_key);
|
||||
}
|
||||
```
|
||||
|
||||
`iroh::SecretKey::from_bytes(&[u8; 32])` accepts raw Ed25519 key bytes —
|
||||
no information loss. This conversion is `#[cfg(feature = "iroh")]` only.
|
||||
|
||||
### 5. ACME ALPN challenge handling in `dispatch_quinn`
|
||||
|
||||
Add an early-return guard in `dispatch_quinn` before the handler lookup:
|
||||
|
||||
```rust
|
||||
if alpn == b"acme-tls/1" {
|
||||
debug!("acme-tls/1 challenge connection completed at TLS layer; closing");
|
||||
connection.close(0u32.into(), b"acme done");
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
This avoids the misleading "no handler for ALPN" warning. The challenge
|
||||
is already answered at the TLS layer; the application just closes
|
||||
gracefully. No `ProtocolHandler` registration for `acme-tls/1`.
|
||||
|
||||
### 6. Feature-gate ACME behind a new `acme` feature
|
||||
|
||||
Add a `acme` feature to alknet-core:
|
||||
|
||||
```toml
|
||||
[features]
|
||||
acme = ["dep:rustls-acme"]
|
||||
```
|
||||
|
||||
`TlsIdentity::Acme` is available regardless of feature (it's just config
|
||||
data), but constructing `TlsSetup` with an `Acme` variant requires the
|
||||
`acme` feature. Without it, `TlsIdentity::Acme` at endpoint construction
|
||||
returns an error ("ACME feature not enabled"). This keeps the
|
||||
footprint down for nodes that don't need ACME — `rustls-acme` and its
|
||||
dependencies are only compiled when the feature is on.
|
||||
|
||||
### 7. `acme-tls/1` in ALPN list only when ACME is active
|
||||
|
||||
When `TlsIdentity::Acme` is configured, `acme-tls/1` is appended to the
|
||||
`alpn_protocols` list alongside the handler ALPNs. When ACME is not
|
||||
configured, `acme-tls/1` is not advertised — no behavior change for
|
||||
non-ACME nodes.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **Breaking change to `TlsIdentity`**: `RawKey(iroh::SecretKey)` →
|
||||
`RawKey(Ed25519SecretKey)`. Pre-1.0 crate, in-repo consumers only.
|
||||
The assembly layer and tests that construct `TlsIdentity::RawKey` must
|
||||
update.
|
||||
- **`ed25519-dalek` becomes a direct dependency** of alknet-core. It's
|
||||
already in the dependency tree (transitive via iroh), so no new
|
||||
compilation cost for `iroh` builds. Quinn-only builds that were not
|
||||
using `RawKey` before will now compile `ed25519-dalek` — it's a small,
|
||||
pure-Rust crate with no C dependencies.
|
||||
- **`rustls-acme` is feature-gated** (`acme` feature). Nodes not using
|
||||
ACME don't compile it. The feature is compatible with `quinn` (ACME
|
||||
is quinn-only; iroh uses its own TLS).
|
||||
- **`build_rustls_server_config` becomes async** (or is replaced by an
|
||||
async `TlsSetup::new`). The accept loop already runs in an async
|
||||
context, so this is a local change.
|
||||
- **ACME state machine lifecycle**: the `AcmeState` task is spawned in
|
||||
`AlknetEndpoint::new()` and aborted on shutdown. The `TlsSetup` struct
|
||||
carries the `JoinHandle` so `AlknetEndpoint::shutdown()` can abort it.
|
||||
- **No handler needed for `acme-tls/1`**: the `dispatch_quinn` guard
|
||||
handles it. `HandlerRegistry` is not involved.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### A. ACME as a `ResolvesServerCert` wrapper behind `X509`
|
||||
|
||||
OQ-12 suggested ACME "fits naturally as an additional `TlsIdentity`
|
||||
variant or as a `rustls::ResolvesServerCert` implementation behind the
|
||||
existing `X509` path." The second option — wrapping `X509` — was
|
||||
rejected because ACME needs async state + config fields (domains, cache,
|
||||
contact) that don't fit behind the static `X509 { cert, key }` variant.
|
||||
A `ResolvesServerCert` that internally does ACME would need to be
|
||||
constructed at config time with those fields, which means `X509` would
|
||||
need to carry them — bloating the variant for non-ACME users. A
|
||||
dedicated `Acme` variant is cleaner.
|
||||
|
||||
### B. Keep `RawKey` coupled to iroh, only add ACME
|
||||
|
||||
Rejected because the coupling is the root cause of quinn-only builds not
|
||||
supporting the "default" identity mode. Fixing only ACME would leave the
|
||||
artificial iroh dependency in place. Since both changes touch
|
||||
`TlsIdentity` and `build_rustls_server_config`, doing them together
|
||||
avoids two breaking changes to the same enum.
|
||||
|
||||
### C. Use `iroh::SecretKey` for both, re-export from alknet-core
|
||||
|
||||
Rejected because it would make `iroh` a non-optional dependency of
|
||||
alknet-core, defeating the feature-gated transport design (ADR-010).
|
||||
`ed25519-dalek` is a lightweight, pure-Rust crate; `iroh` is not.
|
||||
|
||||
### D. Register a no-op `ProtocolHandler` for `acme-tls/1`
|
||||
|
||||
Rejected because it would require the handler registry to know about
|
||||
ACME (a TLS-layer concern), polluting the ALPN dispatch abstraction.
|
||||
The `dispatch_quinn` guard is a one-line check that keeps ACME handling
|
||||
in the endpoint layer where it belongs.
|
||||
|
||||
## Cross-References
|
||||
|
||||
- OQ-12 (TLS identity provisioning) — updated by this ADR
|
||||
- [ADR-010](010-alpn-router-and-endpoint.md) — multi-connectivity endpoint, feature-gated transports
|
||||
- [ADR-004](004-auth-as-shared-core.md) — auth as shared core
|
||||
- `docs/architecture/crates/core/endpoint.md` — TLS identity use cases, updated
|
||||
- `docs/architecture/crates/core/config.md` — `TlsIdentity` enum, updated
|
||||
- `/workspace/@alkdev/reverse-proxy/src/tls/` — proven ACME implementation pattern
|
||||
- `rustls-acme` crate — ACME state machine + cert resolver
|
||||
@@ -172,16 +172,16 @@ These questions are acknowledged but not active. They will be promoted to open w
|
||||
- **Priority**: high
|
||||
- **Resolution**: TLS identity in alknet has two distinct use cases, not one:
|
||||
|
||||
**Use case 1 — P2P / key-based identity (default for most alknet nodes):** RFC 7250 raw Ed25519 public keys. No domain, no CA, no cert renewal. The Ed25519 public key IS the node's identity. This is the same model iroh uses with its `NodeId`. It works natively with SSH auth (same key type) and git (SSH key-based auth). `TlsIdentity::RawKey` in `StaticConfig` covers this. This is the primary identity mode for alknet-native clients — most nodes will use this.
|
||||
**Use case 1 — P2P / key-based identity (default for most alknet nodes):** RFC 7250 raw Ed25519 public keys. No domain, no CA, no cert renewal. The Ed25519 public key IS the node's identity. This is the same model iroh uses with its `NodeId`. It works natively with SSH auth (same key type) and git (SSH key-based auth). `TlsIdentity::RawKey(Ed25519SecretKey)` in `StaticConfig` covers this. As of [ADR-027](decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md), `RawKey` uses `ed25519_dalek::SigningKey` (via an alknet-core wrapper), **not** `iroh::SecretKey` — so raw-key TLS identity is available in quinn-only builds without the `iroh` feature.
|
||||
|
||||
**Use case 2 — Domain-hosted services (relays, public-facing nodes):** X.509 certificates with domain names. Required for browser/WebTransport clients, which don't support RFC 7250. This has two sub-cases:
|
||||
- **Manual**: Provide cert/key file paths via `TlsIdentity::X509`. Already specified in `StaticConfig`.
|
||||
- **ACME auto-provisioning**: Let's Encrypt via rustls-acme. The reverse-proxy project (`/workspace/@alkdev/reverse-proxy`) demonstrates the complete pattern: per-listener ACME state machine, `ResolvesServerCertAcme` rustls integration, TLS-ALPN-01 challenge handling, automatic renewal. This is a proven, solved implementation pattern — not speculative future work. It will be adapted to alknet's `AlknetEndpoint` context when domain-hosted nodes need it.
|
||||
- **ACME auto-provisioning**: Let's Encrypt via `rustls-acme`. `TlsIdentity::Acme { domains, cache_dir, directory, contact }` carries static config; the endpoint constructs the `AcmeState` async state machine at setup time. Feature-gated behind `acme`. Designed in [ADR-027](decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md). The reverse-proxy project (`/workspace/@alkdev/reverse-proxy`) demonstrates the proven pattern: `AcmeConfig`, `ResolvesServerCertAcme`, TLS-ALPN-01 challenge handling, automatic renewal.
|
||||
|
||||
**Browser constraint**: Browsers require X.509 and don't support RFC 7250. For browser/WebTransport clients, domain-hosted nodes with X.509 certs are mandatory. All other clients (SSH, git, alknet-native) work with raw keys by default.
|
||||
|
||||
The `TlsIdentity` enum in `StaticConfig` already captures all three modes (`X509`, `RawKey`, `SelfSigned`). ACME auto-provisioning is additive — it produces an X.509 cert at runtime rather than from files, and fits naturally as an additional `TlsIdentity` variant or as a `rustls::ResolvesServerCert` implementation behind the existing `X509` path.
|
||||
- **Cross-references**: ADR-010, [config.md](crates/core/config.md), [endpoint.md](crates/core/endpoint.md)
|
||||
The `TlsIdentity` enum in `StaticConfig` captures all four modes (`X509`, `RawKey`, `SelfSigned`, `Acme`). [ADR-027](decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md) records the design decisions for ACME integration and RawKey decoupling.
|
||||
- **Cross-references**: ADR-010, ADR-027, [config.md](crates/core/config.md), [endpoint.md](crates/core/endpoint.md)
|
||||
|
||||
### OQ-13: Operation Path Format and Routing Scope
|
||||
|
||||
|
||||
@@ -217,6 +217,7 @@ All design decisions are documented as ADRs in [decisions/](decisions/).
|
||||
| [024](decisions/024-operation-registry-layering.md) | Operation Registry Layering | Curated (static) + session/connection overlays (dynamic); `OperationEnv` as trait-object integration point |
|
||||
| [025](decisions/025-vault-local-only-dispatch.md) | Vault Local-Only Dispatch | Dropped irpc from vault; direct method calls; local-only by construction |
|
||||
| [026](decisions/026-vault-key-model-hd-derivation.md) | Vault Key Model — HD Derivation | HD derivation from BIP39 seed; `74'` coin type; SLIP-0010/Ed25519 default; AES-256-GCM for credentials |
|
||||
| [027](decisions/027-tls-identity-redesign-acme-rawkey-decoupling.md) | TLS Identity Redesign — ACME + RawKey Decoupling | `TlsIdentity::Acme` variant + two-phase server config; `RawKey` uses `ed25519-dalek` (not `iroh::SecretKey`); `acme` feature gate |
|
||||
|
||||
## Open Questions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user