Files

glm-5.2 400c60e7f4 docs(architecture): security constraints from security review

Address security review findings by adding explicit constraints to specs
and implementation specialist role:

Architectural constraints (spec updates):
- metadata does not propagate through OperationEnv::invoke() — fresh
  HashMap for nested calls, closes the back-door leak channel where a
  handler that puts a secret in metadata would leak it to children and
  across from_call to remote nodes (ADR-014)
- Config reload must be authenticated/local-only — malicious reload =
  root-equivalent privilege grant (config.md)
- from_call trust is transitive — scoped env bounds reachability, not
  what the remote op does (operation-registry.md)
- Token entropy ≥128 bits — prefix is lookup aid not secret, offline
  hash verification requires high-entropy tokens (auth.md)

Implementation constraints (auth.md security constraints section + role spec):
- OsRng for cryptographic nonces (AES-GCM IV reuse is catastrophic)
- CachedKey derives Zeroize/ZeroizeOnDrop (no secrets in freed heap)
- No unwrap()/expect() outside tests (poisoned lock recovery, not crash)
- Implementation specialist role spec updated with all four constraints

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

auth.md

docs(architecture): security constraints from security review

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

config.md

docs(architecture): security constraints from security review

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

core-types.md

docs(architecture): fix OQ-05 — multi-connectivity endpoint, not multi-transport

2026-06-16 12:41:03 +00:00

endpoint.md

docs(architecture): untangle TLS identity use cases, remove phase framing, add ADR-013 Rust canonical + agent crate

2026-06-17 09:32:44 +00:00

README.md

docs(architecture): resolve OQ-11 and OQ-19 — all open questions resolved

2026-06-19 06:05:04 +00:00

README.md

status, last_updated

status	last_updated
draft	2026-06-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

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.