glm-5.1
916ed91b79
Address implementation-identified gaps: - Add irpc integration model (SecretServiceHandle vs Client<SecretProtocol>, dispatch paths) - Add Key Caching subsection (derivation path as cache key, 1-hour TTL, LRU, cleared on Lock) - Specify DerivedKey.private_key must derive Zeroize per ADR-038 - Add Password Derivation subsection (HMAC-SHA512, Base64url encoding) - Add secp256k1 derivation note (BIP-0032 algorithm, feature flag) - Document EncryptedData.salt as reserved for future KDF-based key rotation - Add Test Vectors section (BIP39, SLIP-0010, AES-256-GCM known-answer) - Mark OQ-SVC-04 as resolved - Update dependencies (secp256k1 feature-gated, future KDF deps) - Update crate structure diagram (add cache.rs, vectors_tests.rs)
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 | reviewed | 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 |
| 038 | Seed lifecycle and memory security (zeroize for v1) | 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 |