Files

glm-5.1 d3633b7839 docs: complete Phase 0 architecture — spec updates, review fixes, and link portability

Update four existing specs (overview, server, napi-and-pubsub, call-protocol) to
reflect Phase 0 decisions: three-layer model, IdentityProvider, ForwardingPolicy,
OperationEnv, static/dynamic config split. Review all 9 Phase 0a ADRs (026-034)
for consistency. Fix 4 critical issues from architecture review: missing OQ-SVC-05
in open-questions.md, deprecated hub terminology, undefined AuthService and noq
terms. Replace inline OQ text with cross-references per format rules. Add
ConfigServiceImpl definition to configuration.md. Port absolute workspace paths
to project-relative links by copying referenced docs (feasibility, certbot,
fail2ban, event_source_types) into docs/research/.

2026-06-07 11:27:52 +00:00

7.6 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-06-07

Alknet Architecture

Current State

Architecture specification in active development. Phase 0 foundation complete: ADRs 001–034 accepted, new spec documents created for all components, existing specs updated for the three-layer model, crate decomposition, unified identity, OperationEnv, and forwarding policy. Remaining open questions: OQ-15 (QUIC coexistence), OQ-19 (WebTransport TLS), OQ-20 (worker registration), OQ-IF-01 (Interface session/EventEnvelope), OQ-IF-02 (ForwardingPolicy placement). See open-questions.md.

Architecture Documents

Document	Status	Description
overview.md	reviewed	Package purpose, crate structure, three-layer model, exports, dependencies
transport.md	reviewed	Transport abstraction: TCP, TLS, iroh
auth.md	draft	Unified auth: SSH + token, IdentityProvider trait
call-protocol.md	draft	Bidirectional call/event protocol, OperationEnv, three dispatch paths
client.md	reviewed	Client connection, SOCKS5, port forwarding
server.md	reviewed	Server acceptance, IdentityProvider, ForwardingPolicy, channel handling
tun-shim.md	deprecated	TUN interface wrapper — deferred, use tun2proxy
napi-and-pubsub.md	reviewed	NAPI wrapper, reload API, pubsub event target adapter
identity.md	draft	Identity type, IdentityProvider trait, auth flows
services.md	draft	irpc service layer, OperationEnv, three dispatch paths
interface.md	draft	Layer 2: Interface trait, SshInterface, RawFramingInterface
configuration.md	draft	StaticConfig, DynamicConfig, forwarding policy, reload
storage.md	draft	alknet-storage: metagraph, identity, ACL, honker
flowgraph.md	draft	alknet-flowgraph: call graph, operation graph, petgraph
secret-service.md	draft	alknet-secret: BIP39, SLIP-0010, AES-GCM, SecretProtocol

Research Documents

Document	Status	Description
configuration.md	draft	Configuration architecture (source for promoted spec)
core.md	draft	Core overview, transport, call protocol, DNS
services.md	draft	irpc service protocols, OperationContext, application services
storage.md	draft	Metagraph, identity, ACL, secrets, honker
flow.md	draft	FlowGraph, operation graph, call graph, petgraph mapping
integration-plan.md	draft	Phased integration plan for services, pubsub, and operations
feasibility/	—	SSH tunnel feasibility assessment and related analyses
event-sourcing/	—	Event sourcing patterns and event-driven architecture reference
ops/	—	Production ops reference: certbot, fail2ban

ADR Table

ADR	Title	Status
001	Pluggable transport via `AsyncRead+AsyncWrite` trait	Accepted
002	TUN shim as separate process	Superseded by ADR-014
003	iroh stream via `tokio::io::join`	Accepted
004	SSH runs over transport, not alongside	Accepted
005	SOCKS5 as primary interface, TUN as add-on	Accepted
006	No logging of tunnel destinations	Accepted
007	NAPI exposes single duplex stream	Accepted
008	ACME/Let's Encrypt certificate provisioning	Accepted
009	Default iroh relay with override	Accepted
010	Transport chaining in CLI	Accepted
011	Programmatic-first API, no file-based config	Accepted
012	Ed25519 keys + OpenSSH cert-authority, no password auth	Accepted
013	Fail2ban-friendly logging + built-in rate limiting	Accepted
014	Defer TUN, recommend local SOCKS5 + tun2proxy	Accepted
015	napi-rs for FFI bridge	Accepted
016	NAPI exposes both connect() and serve()	Accepted
017	Stealth mode — protocol multiplexing on port 443	Accepted
018	Control channel for pubsub over SSH	Accepted
019	`--proxy` dual semantics (client vs server)	Accepted
023	Unified auth with shared key material + token auth	Accepted
024	Bidirectional call protocol (EventEnvelope)	Accepted
025	Handler/spec separation for downstream service registration	Accepted
026	Transport/interface separation (three-layer model)	Accepted
027	Crate decomposition (core, secret, storage, flowgraph)	Accepted
028	Auth as irpc service behind feature flag	Accepted
029	Identity as core type in alknet-core	Accepted
030	Static/dynamic config split with ArcSwap	Accepted
031	Forwarding policy with rule-based allow/deny	Accepted
032	Event boundary discipline (domain, irpc, call protocol)	Accepted
033	OperationEnv as universal composition mechanism	Accepted
034	Head/worker terminology replacing hub/spoke	Accepted

ADR numbers 020–022 were allocated to proposals that were withdrawn before acceptance and are not listed.

Open Questions

See open-questions.md for all open and resolved questions. Key resolved questions from Phase 0: OQ-12, OQ-16, OQ-18 (forwarding policy and identity scopes), OQ-17 (transport-aware auth), OQ-23 (irpc feature flag), OQ-24 (DNS control channel scope), OQ-25 (crate irpc dependencies). Key open questions: OQ-15 (QUIC coexistence), OQ-19 (WebTransport TLS), OQ-20 (worker registration).

Lifecycle Definitions

Status	Meaning	Transitions
`draft`	Under active development. May change significantly.	→ `reviewed` when open questions resolved
`reviewed`	Architecture final. Implementation may begin. Changes require review.	→ `stable` when implementation verified
`stable`	Locked. Changes require review and may warrant an ADR.	→ `deprecated` when superseded
`deprecated`	Superseded. Kept for reference.	Removed when no longer referenced

7.6 KiB Raw Blame History Unescape Escape