Files

glm-5.1 cfc44008d3 Sync architecture specs with Phase 2 research findings

- Add definitions.md: normative terminology disambiguation (Interface, Service,
  Transport, Token, Identity, Domain, Scope, CredentialProvider, etc.)
- Add credentials.md: CredentialProvider trait and CredentialSet enum for
  outbound auth, mirroring IdentityProvider pattern for inbound auth
- Rewrite interface.md: StreamInterface/MessageInterface split (ADR-035),
  InterfaceRequest/InterfaceResponse, HttpInterface/DnsInterface stubs,
  ListenerConfig with Stream/Http/Dns variants, credential presentation table
- Update auth.md: API keys in DynamicConfig (ADR-037), credential presentation
  per (Transport, Interface) pair, ApiKeyEntry struct in AuthPolicy
- Update configuration.md: API keys, ListenerConfig with Http/Dns variants,
  expanded TOML config examples
- Update call-protocol.md: resolve OQ-IF-01 (InterfaceEvent carries
  EventEnvelope + Identity), add MessageInterface awareness to protocol
  adapter layer
- Update overview.md: three-layer model now includes StreamInterface/
  MessageInterface, CredentialProvider/CredentialSet exports, definitions.md
  reference, ADRs 035-037
- Update open-questions.md: resolve OQ-IF-01, OQ-IF-02, add OQ-P2-01
  through OQ-P2-04, add OQ-CP-01 through OQ-CP-04, add OQ-DEF-01,
  OQ-DEF-03, OQ-DEF-08
- Update README.md: add definitions.md, credentials.md, ADRs 035-037,
  phase2 research docs, current state description

Key architectural decisions:
- ADR-035: StreamInterface/MessageInterface split (two Layer 2 traits)
- ADR-036: CredentialProvider as core type (outbound auth, alknet_core::credentials)
- ADR-037: API keys as DynamicConfig auth (hash-verified bearer tokens)

2026-06-09 08:09:45 +00:00

9.0 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-06-09

Alknet Architecture

Current State

Architecture spec sync in progress. Phase 0 foundation complete (ADRs 001–037). Phase 1 core modifications partially implemented (interface trait, config split, identity provider, forwarding policy). Phase 2 core bridge research complete; spec documents updated to reflect StreamInterface/MessageInterface split, CredentialProvider as core type, and API keys in DynamicConfig.

Remaining open questions: OQ-15 (QUIC coexistence), OQ-19 (WebTransport TLS), OQ-20 (worker registration), OQ-CP-01 (per-identity credentials), OQ-CP-02 (OIDC provider location), OQ-CP-03 (credential rotation). 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 + API keys, credential presentation per interface
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	StreamInterface, MessageInterface, credential presentation, ListenerConfig
configuration.md	draft	StaticConfig, DynamicConfig, API keys, 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
credentials.md	draft	CredentialProvider, CredentialSet (outbound auth)
definitions.md	draft	Terminology disambiguation and concept mapping

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
phase2/definitions.md	draft	Terminology disambiguation (promoted to architecture/definitions.md)
phase2/interface-model.md	draft	StreamInterface/MessageInterface analysis (promoted to interface.md)
phase2/credential-provider.md	draft	CredentialProvider research (promoted to credentials.md)
phase2/tls-transport.md	draft	HTTP interface, stealth handoff, ListenerConfig (promoted to interface.md, auth.md)

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
035	StreamInterface / MessageInterface split	Accepted
036	CredentialProvider as core type (outbound auth)	Accepted
037	API keys as DynamicConfig auth	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), OQ-IF-01 (Interface session / EventEnvelope relationship), OQ-IF-02 (ForwardingPolicy placement). 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 is complete and verified
`stable`	Locked. Changes require review and may warrant an ADR.	→ `deprecated` when superseded
`deprecated`	Superseded. Kept for reference.	Removed when no longer referenced

9.0 KiB Raw Blame History Unescape Escape