docs: port architecture specs and ADRs from alknet-http; write new alkhttp ADRs 067-070
Phase 1 (SDD) — architecture documentation: Ported specs (adapted for alkcall, producer/consumer terms, 6-endpoint gateway, channels-over-WS, Sub/Pub operation types): - overview.md, http-server.md, http-adapters.md, http-mcp.md - README.md index (rewritten for alkhttp) New ADRs: - 067: WebSocket carries the channels protocol (8-byte chunk demux, channel 0 = alk/call, upgrade path /alk/channels) - 068: gateway /publish endpoint for Pub operations (NDJSON body) - 069: WebTransport out of scope in alkhttp (alknet concern) - 070: from_wss consumer adapter (wss feature, tokio-tungstenite) Ported ADRs (25, same numbers, port notes + amendments where the extraction changed facts): 001-004, 010, 014, 015, 017, 022, 023, 027, 034, 036, 037, 039, 041, 042, 044, 045, 046, 047, 048, 049, 051, 066. websocket.md rewritten for the channels session; open-questions.md seeded (OQ-01 WS byte-stream adapter, OQ-02 /publish framing, OQ-03 from_wss reconnect, OQ-04 browser client ownership). Verified: cargo test, clippy -D warnings, fmt, doc --no-deps.
This commit is contained in:
@@ -0,0 +1,91 @@
|
||||
# ADR-004: Auth as Shared Core (IdentityProvider)
|
||||
|
||||
*Ported from alknet ADR-004 (Auth as Shared Core (IdentityProvider)); re-targeted to alkhttp.*
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The previous architecture had authentication spread across multiple layers: `CredentialProvider` with four phases (A–D), `AuthProtocol` as an irpc service, `server_auth` and `client_auth` as separate modules, and `IdentityProvider` as a trait in the core. Different interface types presented credentials differently — SSH used key fingerprints, HTTP used Bearer tokens, DNS used query labels — but the resolution was ad-hoc and tied to the three-layer model.
|
||||
|
||||
The ALPN dispatch model simplifies this: every handler receives the same `AuthContext`, but the credential extraction (how a handler learns who the peer is) differs per ALPN. The resolution (turning a credential into an `Identity`) should be shared across all handlers.
|
||||
|
||||
## Decision
|
||||
|
||||
> **Note**: The original text of this decision described the handler
|
||||
> "enriching or replacing" the `AuthContext`. This was superseded by
|
||||
> ADR-011, which made `AuthContext` immutable in `handle()` (passed as
|
||||
> `&AuthContext`). Handlers resolve identity into a local variable and
|
||||
> store it on `Connection` via `set_identity()`. The text below has been
|
||||
> updated to reflect the ADR-011 model.
|
||||
|
||||
Authentication and identity resolution live in the shared core (now vendored in alkcall) as shared infrastructure. Each handler presents credentials differently, but all resolve through the same `IdentityProvider`:
|
||||
|
||||
```rust
|
||||
pub trait IdentityProvider: Send + Sync + 'static {
|
||||
fn resolve_from_fingerprint(&self, fingerprint: &str) -> Option<Identity>;
|
||||
fn resolve_from_token(&self, token: &AuthToken) -> Option<Identity>;
|
||||
}
|
||||
```
|
||||
|
||||
Credential presentation per handler:
|
||||
|
||||
| Handler | Credential presentation | Resolves via |
|
||||
|---------|------------------------|-------------|
|
||||
| SshAdapter | SSH public key handshake | `resolve_from_fingerprint()` |
|
||||
| CallAdapter | AuthToken in first frame | `resolve_from_token()` |
|
||||
| HttpAdapter | `Authorization: Bearer` header | `resolve_from_token()` |
|
||||
| DnsAdapter | AuthToken in query labels | `resolve_from_token()` |
|
||||
| WebTransportAdapter | AuthToken in CONNECT headers | `resolve_from_token()` |
|
||||
| GitAdapter | Signed push certificate | `resolve_from_fingerprint()` |
|
||||
|
||||
Auth resolution is **hybrid** — the endpoint resolves what it can, and handlers resolve what they must:
|
||||
|
||||
1. **Endpoint-level resolution** (before `handle()` is called): If the TLS handshake provides a client certificate, the endpoint resolves the fingerprint to an `Identity` and passes it in `AuthContext`. This is the case for SSH (where the key exchange happens at the protocol level, but the TLS layer may also provide information).
|
||||
|
||||
2. **Handler-level resolution** (inside `handle()`): For protocols that carry credentials in application frames (AuthToken in the first call frame, Bearer header in HTTP), the handler extracts the credential from the stream and calls `IdentityProvider` to resolve it. The handler then resolves the `Identity` into a local variable and stores it on the `Connection` via `set_identity()` for observability — it does **not** mutate the `AuthContext` (which is passed as `&AuthContext`, an immutable reference — see ADR-011). The per-request identity (for ACL) is resolved separately by the `CallAdapter` at `call.requested` time.
|
||||
|
||||
The `AuthContext` passed to `handle()` may be partial — containing only transport-level information if no TLS client certificate was provided. Handlers must not assume `AuthContext` contains a fully resolved `Identity`. Each handler knows its own credential extraction protocol and is responsible for completing authentication.
|
||||
|
||||
The `CredentialProvider` concept from the previous architecture is simplified: there is no phase progression (A–D). The `IdentityProvider` has two resolution paths — fingerprint and token — and a `ConfigIdentityProvider` implementation that draws from static and dynamic config.
|
||||
|
||||
alkvault stays standalone. It does not depend on the core crate or `IdentityProvider`. The vault provides derived keys on request; identity resolution is a separate concern.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
- Unified identity model — every handler resolves identities the same way through `IdentityProvider`
|
||||
- Handlers own their credential extraction — SSH reads key fingerprints, call reads AuthTokens, HTTP reads Bearer headers
|
||||
- Endpoint provides what it can for free (TLS-level auth), handlers complete what they need
|
||||
- Adding a new credential type is adding a method to `IdentityProvider`, not a new phase
|
||||
- The vault stays standalone — no coupling between key derivation and identity resolution
|
||||
- `AuthContext` is a value type — easy to construct in tests, can be partial for handler-level testing
|
||||
|
||||
**Negative:**
|
||||
- `IdentityProvider` is in the core crate — any change to it recompiles all handlers (mitigated: the trait should be stable; implementation changes don't force recompiles)
|
||||
- Two resolution paths (fingerprint, token) may not cover all future auth schemes (mitigated: the trait can be extended, or a handler can do custom resolution after the initial AuthContext)
|
||||
- Handlers must handle partial AuthContext — the endpoint may not have resolved an Identity, so handlers must be prepared to do credential extraction themselves
|
||||
- WebTransport and browser-based auth needs careful design — AuthToken in CONNECT headers requires the token to be available before the stream is established
|
||||
|
||||
## References
|
||||
|
||||
- Pivot proposal (alknet mono-repo): `docs/research/pivot/alpn-service-architecture.md`
|
||||
- [ADR-002](002-protocol-handler-trait.md): ProtocolHandler trait
|
||||
- [ADR-003](003-crate-decomposition.md): Crate decomposition
|
||||
- ADR-005: irpc as call protocol foundation
|
||||
- The previous architecture had equivalent decisions in ADR-023 (unified auth) and ADR-029 (identity as core type), which are archived in the reference implementation at `/workspace/@alkdev/alknet-main/`.
|
||||
|
||||
## Port notes
|
||||
|
||||
- ADR-011 (AuthContext immutability) and the `IdentityProvider` internals are
|
||||
alkcall-internal concerns; referenced textually without links.
|
||||
- The `WebTransportAdapter` row and the WebTransport negative consequence are
|
||||
retained as historical decision content; in alkhttp the browser path is
|
||||
WebSocket (ADR-048) and h3/WebTransport is out of scope in alkhttp
|
||||
(ADR-069, alknet-side).
|
||||
- Crate renames: "alknet-core" → "the shared core (now vendored in alkcall)",
|
||||
"alknet-vault"/"alknet-secret" → alkvault. (The source alternated between
|
||||
the "alknet-secret" and "alknet-vault" names for the same crate in the
|
||||
Consequences and Decision sections; normalized to alkvault.)
|
||||
Reference in New Issue
Block a user