alkdev/alknet
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f19e7675ac85ce7bec5606ac7098e5a144a82aac
alknet/docs/architecture/open-questions.md
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

16 KiB
Raw Blame History

status, last_updated
status last_updated
draft 2026-06-07

Open Questions

Transport

OQ-01: TLS certificate management strategy

  • Origin: server.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-008 — Support both domain-based and IP-based ACME/Let's Encrypt auto-provisioning, plus manual certs. Domain-based uses standard certbot-style flow with HTTP-01/TLS-ALPN-01 challenges. IP-based uses short-lived certs via TLS-ALPN-01 on port 443. Manual certs via --tls-cert/--tls-key always supported. Implementation uses rustls-acme or similar pure-Rust ACME client.
  • Cross-references: ADR-008, Server spec, TlsTransport implementation

OQ-02: iroh relay configuration defaults

  • Origin: transport.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-009 — Default to n0's free relay servers. Allow override via --iroh-relay <url>. Document self-hosted relay setup. This matches iroh's own defaults and minimizes friction for testing/development.
  • Cross-references: ADR-009, Transport spec

OQ-05: Transport chaining support in CLI

  • Origin: transport.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-010 — Support --transport iroh --proxy socks5://... natively in the CLI. iroh's endpoint builder accepts proxy configuration directly, so the implementation is minimal. Other transport combinations (TCP+TLS) are already implicit.
  • Cross-references: ADR-010, Transport spec

Client

OQ-06: SSH config file parsing

  • Origin: client.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-011 — No ~/.ssh/config parsing, no custom config file. Configuration is programmatic-first: CLI flags, library API structs (ConnectOptions, ServeOptions), and environment variables. Cross-platform path issues (~ expansion) are avoided. The library API is the primary interface; if config files are needed later, they can be a separate layer.
  • Cross-references: ADR-011, Client spec

Server

OQ-07: ACME/Let's Encrypt support

  • Origin: server.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-008 — Same resolution as OQ-01. Both domain-based (standard, domain-bound, auto-renewing) and IP-based (short-lived, no domain required) ACME flows are supported. The domain-based path requires port 80 or DNS access for challenges. The IP-based path uses TLS-ALPN-01 on port 443 and requires the ACME client to run continuously.
  • Cross-references: ADR-008, Server spec, TlsTransport

OQ-08: Connection limits and rate limiting

  • Origin: server.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-013 — Two-layer approach: (1) Structured logging of auth attempts and connections at INFO level for fail2ban integration on Linux — matches our production fail2ban setup with nftables and systemd journal. (2) Built-in rate limiting: --max-connections-per-ip and --max-auth-attempts flags providing platform-independent abuse protection.
  • Cross-references: ADR-013, Server spec, Production fail2ban docs

OQ-04: Authentication beyond Ed25519 keys

  • Origin: client.md, server.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-012 — Ed25519 public key (default, unchanged) + OpenSSH certificate authority support (new, important for multi-user). No password authentication over SSH channels. If a local SOCKS5 proxy needs its own auth, that's a separate concern. Cert-authority makes multi-user management practical: one CA entry in authorized_keys instead of N individual keys. Certificates support expiry and restrictions.
  • Cross-references: ADR-012, Client spec, Server spec

TUN

OQ-03: Windows TUN support scope

  • Origin: tun-shim.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-014 — TUN is deferred entirely from the alknet project. For VPN-like behavior, users run tun2proxy --proxy socks5://127.0.0.1:1080 alongside alknet. This eliminates all TUN-related scope questions (Windows, TCP reconstruction, etc.).
  • Cross-references: ADR-014

OQ-09: TCP reconstruction approach for TUN

  • Origin: tun-shim.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-014 — TUN is deferred from alknet. tun2proxy (external tool) handles this if users need VPN-like behavior.
  • Cross-references: ADR-014

NAPI / PubSub

OQ-10: NAPI wrapper API surface

  • Origin: napi-and-pubsub.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-016 — Expose both connect() and serve() from the start. Both are fundamental operations needed by the pubsub event target system (spokes use connect(), hubs could use serve()). The NAPI layer is transport-agnostic — it doesn't know about pubsub's EventEnvelope. The pubsub adapter wraps the Duplex stream. This ensures the NAPI wrapper is reusable for any stream-based protocol, not tied specifically to pubsub.
  • Cross-references: ADR-016, napi-and-pubsub.md

OQ-11: napi-rs vs uniffi for FFI bridge

  • Origin: napi-and-pubsub.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-015 — Use napi-rs. It's the standard for Node.js native addons, matches our primary consumer (TypeScript/Node.js), and has the best ecosystem and documentation. If future Python or mobile consumers are needed, a separate uniffi layer can be added — the Rust core doesn't change.
  • Cross-references: ADR-015, napi-and-pubsub.md

Configuration

OQ-12: Per-user forwarding scope vs global rules

  • Origin: research/configuration.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-031 — Start with global rules + principal matching from Identity.scopes. Per-user scope from peer_credentials.metadata.scopes via IdentityProvider. The ForwardingPolicy evaluates rules against Identity.id and Identity.scopes from the authenticated identity.
  • Cross-references: ADR-031, configuration.md

OQ-13: Config file auto-reload via file watching

  • Origin: research/configuration.md
  • Status: resolved
  • Priority: low
  • Resolution: No file watching. CLI loads once at startup; NAPI/head reload explicitly. File watching is a potential attack vector and unnecessary complexity for a security tool.
  • Cross-references: configuration.md

OQ-14: ArcSwap vs RwLock for dynamic config

  • Origin: research/configuration.md
  • Status: resolved
  • Priority: low
  • Resolution: ArcSwap. Lock-free reads on the hot path (every auth check, every channel open). RwLock adds contention. arc-swap is small (~500 lines) and well-maintained.
  • Cross-references: configuration.md

OQ-15: TLS + WebTransport + iroh QUIC listener coexistence

OQ-16: Transport-specific forwarding policy (e.g., WebTransport clients restricted to alknet-* channels)

  • Origin: research/configuration.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-031 — Add TransportKind match in ForwardingRule. WebTransport clients can be restricted to alknet-* channels via TargetPattern::AlknetPrefix combined with a TransportKind::WebTransport filter.
  • Cross-references: ADR-031, configuration.md

OQ-17: Transport-aware auth layer (SSH keys vs API keys for non-SSH transports)

  • Origin: research/configuration.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-023 — Unified auth with shared key material. SSH transports use SSH pubkey auth. Non-SSH transports (WebTransport) use Ed25519-signed timestamp tokens. Both verify against the same authorized_keys set. The presentation differs per transport, but the identity is unified. AuthPolicy holds both SshAuthConfig and TokenAuthConfig, with TokenKeySource::Shared as the default (same keys for both paths). IdentityProvider trait decouples alknet-core from identity storage.
  • Cross-references: ADR-023, identity.md, OQ-15

OQ-23: irpc dependency — always or behind feature flag?

  • Origin: research/integration-plan.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-027 — Feature flag. Nodes that only do SSH tunneling don't need the service layer. irpc is behind a feature flag in alknet-core and an independent dependency in alknet-secret and alknet-storage.
  • Cross-references: ADR-027

OQ-24: DNS control channel scope for initial implementation?

  • Origin: research/integration-plan.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-026 — DNS control channel carries call protocol frames only (no SSH tunneling over DNS). The (DNS transport, raw framing interface) pair sends EventEnvelope directly. SSH-over-DNS is a future possibility but out of scope.
  • Cross-references: ADR-026, interface.md

OQ-25: alknet-storage and alknet-secret irpc dependency

  • Origin: research/integration-plan.md
  • Status: resolved
  • Priority: low —
  • Resolution: ADR-027 — Independently. They're separate crates. irpc is a shared library they both use as an independent dependency.
  • Cross-references: ADR-027

Auth

OQ-18: Source of Identity.scopes — ForwardingPolicy, IdentityProvider, or both?

  • Origin: auth.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-029 and ADR-031 — IdentityProvider owns scopes. The Identity struct includes scopes and resources fields populated by the IdentityProvider implementation (config-based or database-backed). ForwardingPolicy uses scopes from Identity — it consumes them, it doesn't produce them.
  • Cross-references: ADR-029, ADR-031, identity.md

OQ-19: Separate TLS identity for WebTransport vs shared with SSH-over-TLS?

  • Origin: auth.md
  • Status: open
  • Priority: low
  • Resolution: (deferred to Phase 4 — QUIC is UDP, TLS-over-TCP is TCP, they can share port 443 without conflict)
  • Cross-references: OQ-15, interface.md

Call Protocol

OQ-20: Worker registration and discovery on connect/disconnect

  • Origin: call-protocol.md
  • Status: open
  • Priority: medium
  • Resolution: (pending — registration on connect / cleanup on disconnect is the leading approach but needs spec in call-protocol.md)
  • Cross-references: ADR-024, ADR-025

OQ-21: Routing calls to specific workers with same-service operations

  • Origin: call-protocol.md
  • Status: resolved
  • Priority: medium —
  • Resolution: ADR-024, ADR-025 — Operation paths use /{node}/{service}/{op} format. The first path segment identifies the node and routes the call to the correct connected node. Multiple workers exposing the same service are differentiated by the node prefix (/dev1/fs/readFile vs /dev2/fs/readFile). The head maintains a routing table mapping node identity to connection.
  • Cross-references: call-protocol.md, ADR-024, ADR-025

OQ-22: Client streaming (streaming inputs) in the call protocol?

  • Origin: call-protocol.md
  • Status: resolved
  • Priority: low —
  • Resolution: Deferred. Current model (single request, optional streaming response) covers all identified use cases. Client streaming can be added later if needed.
  • Cross-references: ADR-024

Services

OQ-SVC-01: Should the secret service support multiple seed phrases (one per tenant)?

  • Origin: secret-service.md
  • Status: open
  • Priority: low
  • Resolution: (deferred — one seed per node is simplest; multi-seed can be added later by indexing Unlock with a tenant ID)
  • Cross-references: secret-service.md

OQ-SVC-02: Should service protocols use postcard (binary) or JSON for remote calls?

  • Origin: research/services.md
  • Status: resolved
  • Priority: low —
  • Resolution: Postcard for irpc (Rust-to-Rust, efficient). JSON for call protocol (cross-language, universal). The irpc remote path naturally uses postcard.
  • Cross-references: services.md

OQ-SVC-03: How does the secret service integrate with the existing EncryptedDataSchema from @alkdev/storage?

  • Origin: secret-service.md
  • Status: open
  • Priority: medium
  • Resolution: (pending — Rust implementation replaces PBKDF2 password-based encryption with derived AES-256-GCM keys; EncryptedData format is a superset; migration by re-encrypting)
  • Cross-references: secret-service.md, storage.md

OQ-SVC-04: Should workers cache derived keys locally?

  • Origin: secret-service.md
  • Status: resolved
  • Priority: low —
  • Resolution: Yes, with a TTL (default: 1 hour). The head can revoke by invalidating the session.
  • Cross-references: secret-service.md

OQ-SVC-05: How does the NFT-based ACL smart contract interact with the secret service?

  • Origin: storage.md
  • Status: open
  • Priority: low
  • Resolution: The Ethereum signing key (m/44'/60'/0'/0/0) is derived from the same seed as the secret service. The smart contract is a separate concern — it reads on-chain ACL state, it doesn't call the secret service.
  • Cross-references: storage.md, secret-service.md

Interface

OQ-IF-01: How does the Interface session type relate to the call protocol's EventEnvelope stream?

  • Origin: interface.md
  • Status: open
  • Priority: high
  • Resolution: (pending — needs design during Phase 1.8 implementation)
  • Cross-references: interface.md, ADR-026

OQ-IF-02: Should SshInterface own ForwardingPolicy checks or should they move to Layer 3?

  • Origin: interface.md
  • Status: open
  • Priority: medium
  • Resolution: (pending — current thinking: forwarding check is Layer 3 policy, but channel open/close lifecycle is Layer 2. The Interface reports channel open requests to Layer 3; Layer 3 applies ForwardingPolicy.)
  • Cross-references: interface.md, ADR-031
Reference in New Issue View Git Blame Copy Permalink