glm-5.2
7dda6eec68
Drops irpc from alknet-vault entirely. The vault's dispatch is now direct method calls on VaultServiceHandle — no VaultProtocol enum, no VaultMessage, no VaultServiceActor, no mpsc channel, no Service trait, no RemoteService trait, no postcard serialization. The vault is local-only by construction. The core security argument: irpc made the vault remote-capable by default (RemoteService generated unless no_rpc is passed). The IrohProtocol handler forwards all messages without auth. The docs framed 'register an ALPN' as a server-setup change. This is the default-insecure anti-pattern — security should be opt-in, not opt-out. ADR-025 inverts the default: local-only is the only mode, and remote access requires building a separate vault-server crate (a visible architectural act, not a flag flip). The actor path was already dead code — service.md said 'prefer VaultServiceHandle directly — no channel, no serialization.' The actor existed only to make irpc's Service trait work, which existed only to make RemoteService work, which was the footgun. VaultServiceHandle's Arc<RwLock> provides concurrent reads and exclusive writes — better throughput than the actor's sequential processing. DerivedKey serialization simplifies: always redact on serialize (for logging safety), reject '[REDACTED]' on deserialize with an error. No 'postcard preserves bytes' path. This resolves review #002 W8 (silent corruption on JSON-deserialized DerivedKey). Resolves: - OQ-21: remote vault access — resolved (not deferred). Not a vault crate feature; if needed, a separate vault-server crate with its own ADR. - C7: vault-server-crate question decided — not created now, not precluded. - C8: operation access policy table dissolved — all operations local-only by default; if a vault-server crate exposes some remotely, that crate defines the policy. - W8: DerivedKey JSON deserialization — resolved (reject redacted payloads). Amends ADR-005 (irpc remains for alknet-call, not for alknet-vault), ADR-018 (vault is even more standalone — zero RPC framework deps), ADR-019 (vault is the only layer, not just the only direct-caller layer), ADR-008 (vault integration point unchanged, but now local-only by construction).
75 lines
4.8 KiB
Markdown
75 lines
4.8 KiB
Markdown
# ADR-003: Crate Decomposition
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The previous alknet-core crate was a monolith containing transport, interface, server, client, call, auth, config, socks5, credentials, and HTTP — all in one crate with interdependent modules. This created coupling (interface types depended on auth, server depended on call, everything depended on config) and made it impossible to use individual components independently.
|
|
|
|
The new ALPN dispatch model eliminates the need for a shared interface layer. Each handler is self-contained — it receives a byte stream and manages its own protocol. This naturally decomposes into separate crates.
|
|
|
|
Key constraints:
|
|
- Protocol crates must depend on alknet-core for auth/identity/config — but not on each other
|
|
- alknet-vault is already standalone (no alknet-core dependency) and must remain so (see ADR-008)
|
|
- The CLI binary assembles everything — it's the only crate that depends on all handler crates
|
|
- Handlers with protocol-agnostic cores (SFTP, call protocol) preserve the WASM door — browser clients can implement the wire format over WebTransport (see ADR-009, ADR-013)
|
|
- alknet-call includes the call protocol client and adapter traits, not just the server side — this enables alknet-agent and alknet-napi to use it for remote invocation
|
|
- Rust is the canonical implementation language. TypeScript is a reference/browser adaptation, not a parallel implementation (see ADR-013)
|
|
|
|
## Decision
|
|
|
|
The workspace decomposes into the following crates:
|
|
|
|
| Crate | Responsibility | Depends on |
|
|
|-------|---------------|------------|
|
|
| `alknet-core` | ProtocolHandler trait, ALPN router, endpoint, BiStream, AuthContext, IdentityProvider, config, ArcSwap dynamic config | tokio, quinn, rustls, irpc, iroh (feature-gated, added by ADR-010) |
|
|
| `alknet-vault` | Local key vault: BIP39/SLIP-0010/AES-GCM key derivation, encryption | (standalone, no alknet-core) |
|
|
| `alknet-ssh` | SshAdapter (russh, SOCKS5, port forwarding) | alknet-core, russh |
|
|
| `alknet-call` | CallAdapter (JSON-RPC via irpc, operation registry, pub/sub, access control, call protocol client, adapter traits) | alknet-core, irpc |
|
|
| `alknet-agent` | Agent service: LLM execution loop (forked aisdk), tool dispatch via call protocol, provider key retrieval via vault | alknet-call |
|
|
| `alknet-git` | GitAdapter (gix, pkt-line protocol) | alknet-core, gix |
|
|
| `alknet-sftp` | SftpAdapter (russh-sftp protocol core) | alknet-core, russh-sftp |
|
|
| `alknet-msg` | MessageAdapter (E2E encryption, mixnet) | alknet-core |
|
|
| `alknet-http` | HttpAdapter (axum, REST API, MCP endpoint) | alknet-core, axum |
|
|
| `alknet-dns` | DnsAdapter (hickory-proto, pkarr, service discovery) | alknet-core, hickory-proto |
|
|
| `alknet-napi` | Node.js native addon — thin NAPI projection of the call protocol client | alknet-call, napi-rs |
|
|
| `alknet` | CLI binary — registers handlers, starts endpoint | all handler crates, alknet-vault |
|
|
|
|
Dependency flow:
|
|
```
|
|
alknet-vault (standalone)
|
|
alknet-core ← all handler crates ← alknet (CLI)
|
|
alknet-call ← alknet-agent
|
|
alknet-call ← alknet-napi
|
|
```
|
|
|
|
No handler crate depends on another handler crate. Cross-handler communication goes through the call protocol (alknet-call) or through alknet-core's endpoint.
|
|
|
|
alknet-agent depends on alknet-call (not alknet-core directly) because it uses the call protocol client for tool dispatch and the operation registry for tool registration. It receives LLM provider keys through capabilities injected at the assembly layer (from alknet-vault), never from environment variables and never over the call protocol. See ADR-008 and ADR-014.
|
|
|
|
alknet-napi is a thin projection layer — it exposes the Rust call protocol client to Node.js via NAPI. It does not contain business logic or adapter implementations. See ADR-013.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
- Each handler can be developed, tested, and versioned independently
|
|
- WASM-compatible handlers (sftp, call) don't pull in heavy dependencies (russh, axum)
|
|
- alknet-vault remains standalone — no circular dependency risk
|
|
- New handlers are added by creating a crate and registering it with the endpoint
|
|
- Clean separation of concerns — each crate has one job
|
|
|
|
**Negative:**
|
|
- More crates to manage in the workspace — workspace Cargo.toml and version coordination
|
|
- Shared types (AuthContext, BiStream) must live in alknet-core — if they change, all handlers recompile
|
|
- The CLI binary has a large dependency tree (all handlers) — but this is expected for a binary that assembles everything
|
|
- Testing cross-handler behavior requires integration tests in the CLI or a test utility crate
|
|
|
|
## References
|
|
|
|
- Pivot proposal: `docs/research/pivot/alpn-service-architecture.md`
|
|
- ADR-001: ALPN-based protocol dispatch
|
|
- ADR-002: ProtocolHandler trait
|
|
- ADR-004: Auth as shared core (IdentityProvider)
|
|
- ADR-005: irpc as call protocol foundation |