alkdev/alknet

0 Fork 0

Files

T

glm-5.2 1baa619ce9 docs(arch): decompose open-questions.md into per-OQ files under questions/

The monolithic open-questions.md (1310 lines, 47 OQs) was large enough to be
unmanageable, with high size variance (OQ-42 at 220 lines next to OQ-06 at 8).
Decomposed into one file per OQ under docs/architecture/questions/ (NNN-slug.md,
mirroring the ADR convention), with open-questions.md retained as the index:
theme-grouped tables plus a cross-theme Deferred/Blocked section that surfaces
the 6 deferred OQs with their Blocked-on conditions inline (the safe-exit
visibility surface). Per-OQ content moved verbatim; all 62 inbound links stay
valid (none used anchors). README's curated OQ summary dropped (now redundant
with the index tables).

Also seeds tasks/architecture/ with this task plus two follow-ups found during
the decompose: OQ-09/10 missing structured Blocked-on fields, and the
tasks/architecture/ blocker-task half of the Safe Exit protocol being
unenforced.

2026-07-06 16:07:59 +00:00

2.4 KiB

Raw Blame History

OQ-12: TLS Identity Provisioning in AlknetEndpoint

Origin: endpoint.md, config.md
Status: resolved
Door type: One-way
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(Ed25519SecretKey) in StaticConfig covers this. As of ADR-027, 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. 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. 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 captures all four modes (X509, RawKey, SelfSigned, Acme). ADR-027 records the design decisions for ACME integration and RawKey decoupling.
Cross-references: ADR-010, ADR-027, config.md, endpoint.md

2.4 KiB Raw Blame History

OQ-12: TLS Identity Provisioning in AlknetEndpoint

2.4 KiB

Raw Blame History