alkdev/alknet
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
400c60e7f452f80a5476a6dbe7ea02cc9817974b
alknet/docs/architecture
History
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
..
crates
docs(architecture): security constraints from security review
2026-06-19 06:55:54 +00:00
decisions
docs(architecture): add ADR-017 call protocol client and adapter contract, resolve OQ-15
2026-06-18 10:57:29 +00:00
open-questions.md
docs(architecture): resolve OQ-11 and OQ-19 — all open questions resolved
2026-06-19 06:05:04 +00:00
overview.md
docs(architecture): add ADR-017 call protocol client and adapter contract, resolve OQ-15
2026-06-18 10:57:29 +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 Architecture

Current State

Pre-implementation. The project has completed a pivot from a three-layer model to an ALPN-as-service model. The greenfield workspace contains only alknet-vault (stable) and research/reference material. Foundational ADRs (001–017) are in place, including the BiStream type definition (ADR-007), vault integration (ADR-008), ALPN router/endpoint (ADR-010), AuthContext structure (ADR-011), call protocol stream model (ADR-012), Rust as canonical implementation language (ADR-013), secret material flow with capability injection (ADR-014), privilege model with authority context (ADR-015), abort cascade for nested calls (ADR-016), and call protocol client and adapter contract (ADR-017). The alknet-core and alknet-call crate specs are in draft.

Next step: Review alknet-call spec documents, then begin implementation. All open questions are resolved.

Architecture Documents

Document Status Description
overview.md draft Workspace-level overview, crate graph, shared types, design principles
open-questions.md draft Centralized OQ tracker with door-type classifications
crates/core/README.md draft alknet-core crate index
crates/core/core-types.md draft ProtocolHandler, HandlerError, Connection, BiStream, StreamError
crates/core/endpoint.md draft ALPN router, HandlerRegistry, accept loop, shutdown
crates/core/auth.md draft AuthContext, Identity, IdentityProvider, AuthToken, resolution flow
crates/core/config.md draft StaticConfig, DynamicConfig, ArcSwap, ConfigReloadHandle
crates/call/README.md draft alknet-call crate index
crates/call/call-protocol.md draft CallAdapter, EventEnvelope framing, stream model, PendingRequestMap, bidirectional calls, streaming subscribe example
crates/call/operation-registry.md draft OperationSpec, Handler, OperationRegistry, AccessControl, capability injection, service discovery, irpc integration

ADR Table

ADR Title Status
001 ALPN-Based Protocol Dispatch Accepted
002 ProtocolHandler Trait Accepted
003 Crate Decomposition Accepted
004 Auth as Shared Core (IdentityProvider) Accepted
005 irpc as Call Protocol Foundation Accepted
006 ALPN String Convention and Connection Model Accepted
007 BiStream Type Definition Accepted
008 Vault Integration Point Accepted
009 One-Way Door Decision Framework Accepted
010 ALPN Router and Endpoint Accepted
011 AuthContext Structure and Resolution Flow Accepted
012 Call Protocol Stream Model Accepted
013 Rust as Canonical Implementation Language Accepted
014 Secret Material Flow and Capability Injection Accepted
015 Privilege Model and Authority Context Accepted
016 Abort Cascade for Nested Calls Accepted
017 Call Protocol Client and Adapter Contract Accepted

Open Questions

See open-questions.md for the full tracker.

Resolved one-way doors:

  • OQ-01: BiStream type — trait with Connection parameter (ADR-007)
  • OQ-02: AuthContext timing — hybrid model (ADR-004)
  • OQ-03: ALPN naming — alknet/ prefix, no version (ADR-006)
  • OQ-05: Multi-connectivity endpoint — quinn + iroh, both feature-gated (ADR-010)
  • OQ-06: ALPN per connection, not per stream (ADR-006)
  • OQ-08: Vault integration — CLI-embedded, assembly-layer only (ADR-008, ADR-014)
  • OQ-16: Safe vault operations for call protocol exposure — none for now (ADR-014)
  • OQ-18: Privilege model — internal = authority switch, External/Internal visibility, handler identity + scoped env (ADR-015)
  • OQ-17: Abort cascade — call.aborted cascades to descendants; default abort-dependents, continue-running opt-in (ADR-016)
  • OQ-15: Call protocol client and adapter contract — CallClient opens connections; from_call imports remote ops; connection direction independent of call direction (ADR-017)

Resolved two-way doors:

  • OQ-04: Dynamic handler registration — static at startup (ADR-010)
  • OQ-07: Call protocol scope — bidirectional streams, EventEnvelope, ID-based correlation (ADR-012)
  • OQ-11: Handler-level auth resolution observability — handlers store resolved identity on Connection (Option B); two identity scopes: connection-level (observability) and per-request (ACL)
  • OQ-12: TLS identity provisioning — two use cases: RFC 7250 raw keys (default, P2P) and X.509 certs (domain-hosted, browsers). ACME is a proven pattern.
  • OQ-13: Operation path format — /{service}/{op} is the correct design for alknet-call, not a simplification
  • OQ-14: Batch operation semantics — multiple correlated call.requested events is the correct protocol design, not a simplification
  • OQ-19: Session-scoped registries — agent-written operations via OperationEnv trait layering; protocol doesn't need changes; OperationEnv must remain a trait

Deferred (not active):

  • OQ-09: WASM target boundaries — design constraint, not deliverable
  • OQ-10: Git adapter scope — start with smart protocol, add ERC721 later

All open questions are resolved. No open one-way or two-way doors remain. The architecture is ready for review.

Document Lifecycle

Status Meaning Transitions
draft Under active development. May change significantly. → reviewed when open questions are resolved
reviewed Architecture is 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

References

  • Pivot proposal: docs/research/pivot/alpn-service-architecture.md
  • Cleanup plan: docs/research/pivot/cleanup-plan.md
  • SDD process: docs/sdd_process.md
  • Reference implementation: /workspace/@alkdev/alknet-main/
Reference in New Issue View Git Blame Copy Permalink