Files

glm-5.2 cb98f42cd4 docs(architecture): resolve review #002 remaining Tier 4 findings

Add ADR-026 (vault key model — HD derivation) recording the foundational
HD-derivation decision, 74' coin type reservation, SLIP-0010/Ed25519
default, secp256k1 feature-gating, and AES-256-GCM cipher choice. These
were previously inline rationale with no ADR (W9).

Extend ADR-018 with an explicit EncryptedData wire format lock — fields,
encoding, and semantics are frozen; no removal without a format-version
migration (W10).

Resolve the remaining guard clauses and spec decisions:

- W2: Capabilities must be immutable after construction (no interior
  mutability). Makes the Arc vs deep-copy clone semantics genuinely
  two-way.
- W5: Published to_* specs are compatibility contracts — best-effort
  mappings are two-way before first publication, one-way after. Version
  generated specs.
- W6: Salt field clarification — v2 salt is permanently unused; a future
  KDF is a different derivation family, not a version-indexed path; the
  field saves a wire-format change only.
- W7: unlock_new returns Zeroizing<String> — the mnemonic is the root of
  trust and must not linger in freed memory.
- W17: OQ-09 WASM — server-side dispatch door is honestly closed
  (Connection is concrete, tokio-bound), not implicitly preserved.
- W18: OQ-10 git — composability fork (raw smart protocol vs call-protocol
  projection) is a separate decision from ERC721 scope.
- W20: from_openapi must prefix imported error codes (HTTP_404) to avoid
  collision with protocol-level codes (NOT_FOUND). Normative rule, not
  naming convention.
- W21: ScopedOperationEnv field is private — construction via new()/
  empty(), query via allows(). Makes the future subgraph refactor
  non-breaking.
- C13: Connection::set_identity — the endpoint does not read identity()
  after handle() returns (Connection is moved into the spawned task).
  Observability is handler-side logging. Simplest honest answer.
- W1: OperationAdapter trait is async, returns Vec<HandlerRegistration>.
  from_call requires async discovery; ADR-022 changed the return type.
- W11: CompositionAuthority::as_identity() defined — constructs a
  synthetic Identity (label as id, scopes, resources) not resolvable via
  IdentityProvider. Second Identity construction path, acknowledged.
- W14: SecretKey is iroh::SecretKey (Ed25519) — consistent with the
  endpoint's iroh dependency.
- W19: Grandchild abort propagation is inherit-by-default (option a) —
  invoke() with no explicit policy inherits parent's policy. ContinueRunning
  auto-propagates to grandchildren unless explicitly overridden.

2026-06-23 08:20:27 +00:00

auth.md

docs(architecture): security constraints from security review

2026-06-19 06:55:54 +00:00

config.md

docs(architecture): resolve review #002 remaining Tier 4 findings

2026-06-23 08:20:27 +00:00

core-types.md

docs(architecture): resolve review #002 remaining Tier 4 findings

2026-06-23 08:20:27 +00:00

endpoint.md

docs(architecture): resolve review #002 Tiers 1-3 — mechanical and consistency fixes

2026-06-22 05:46:37 +00:00

README.md

docs(architecture): resolve review #002 Tiers 1-3 — mechanical and consistency fixes

2026-06-22 05:46:37 +00:00

README.md

status, last_updated

status	last_updated
draft	2026-06-22-21

alknet-core

Core library for ALPN-based protocol dispatch. Every handler crate depends on alknet-core.

Documents

Document	Status	Description
core-types.md	draft	ProtocolHandler trait, HandlerError, Connection, BiStream, StreamError
endpoint.md	draft	ALPN router, HandlerRegistry, accept loop, graceful shutdown
auth.md	draft	AuthContext, Identity, IdentityProvider, AuthToken, resolution flow
config.md	draft	StaticConfig, DynamicConfig, ArcSwap, ConfigReloadHandle

Applicable ADRs

ADR	Title	Relevance
001	ALPN-Based Protocol Dispatch	Core architectural model
002	ProtocolHandler Trait	The trait every handler implements
003	Crate Decomposition	alknet-core's position in the crate graph
004	Auth as Shared Core	IdentityProvider in core
006	ALPN String Convention	ALPN format, one-ALPN-per-connection
007	BiStream Type Definition	Connection, BiStream trait, SendStream, RecvStream
009	One-Way Door Framework	Decision classification
010	ALPN Router and Endpoint	Endpoint, HandlerRegistry, accept loop
011	AuthContext Structure	AuthContext fields and resolution flow
015	Privilege Model and Authority Context	Per-request identity on OperationContext; admin scope for config reload

Relevant Open Questions

OQ	Title	Status	Relevance
OQ-04	Dynamic handler registration	resolved (start static)	HandlerRegistry is immutable at startup
OQ-05	Multi-connectivity endpoint	resolved (quinn + iroh)	AlknetEndpoint supports both, both feature-gated
OQ-11	Handler-level auth resolution observability	resolved	Handlers store resolved identity on Connection; two identity scopes (connection-level for observability, per-request for ACL)

Key Design Principles

One trait, one dispatch point: ProtocolHandler is the only abstraction handlers implement. No StreamInterface/MessageInterface split.
ALPN does the routing: The endpoint dispatches by ALPN string. No byte-peeking, no ListenerConfig enum.
Handlers own their wire format: Each handler manages its own protocol parsing. alknet-core provides the Connection, not the framing.
Auth is hybrid: The endpoint provides what it can (TLS-level auth). Handlers complete what they need. AuthContext may be partial.
WASM door preserved: BiStream is a trait, Connection is an opaque type. Core types don't assume tokio or quinn in public APIs.