docs(arch): ADR-034 — outgoing-only X.509 and three peer roles, resolve OQ-37
Untangles the conflation of three distinct remote roles under 'X.509 endpoint': (1) public X.509 endpoint — a remote HTTPS/call-over-TLS server the local node is a client of (no PeerEntry, no PeerId, not in the peer graph; CA verification + bearer token); (2) transport relay — iroh's DERP-equivalent, infrastructure, not an alknet peer; (3) hub / hosting node — an alknet peer that also exposes a public domain + X.509 for browsers (mixed-fingerprint PeerEntry, already supported by ADR-030). The load-bearing one-way door is the client-side verifier selection rule: known peer (PeerEntry present) → fingerprint pin; unknown X.509 remote → CA verification (WebPkiServerVerifier); unknown Ed25519 remote → fails closed. This closes the AcceptAnyServerCertVerifier security hole OQ-29 flagged, with the peer-model criterion (PeerEntry presence) made explicit. The 'make PeerEntry symmetric' instinct is rejected — pure-client connections to public APIs have no stable logical identity to pin. Documents that CallCredentials.remote_identity: None is load-bearing (None = public X.509 endpoint → CA path, not a missing field; Some = known peer → fingerprint pin), closing a subtle gap where an implementer could have defaulted to a placeholder or treated None as skip-verify. Records WebTransport relay-as-proxy (deferred with h3/WebTransport, new OQ-HTTP-07) and on-chain/smart-contract peer discovery (fits the OQ-36 repo/adapter pattern, no auth-model change) so they aren't lost. Amends auth.md and client-and-adapters.md with the three-role naming, the verifier selection rule, and the Option semantics; updates OQ-37 to resolved in open-questions.md, README.md, and both crate READMEs.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-06-25
|
||||
last_updated: 2026-06-28
|
||||
---
|
||||
|
||||
# alknet-http — Phase 0 Research Findings
|
||||
@@ -166,6 +166,19 @@ HTTP/2 is sufficient. WebTransport is the browser path for the agent service
|
||||
lands as a fast-follow when the agent service needs browser streaming. This
|
||||
keeps v1 focused on the adapter + REST surface. Two-way door.
|
||||
|
||||
**WebTransport relay-as-proxy (recorded via ADR-034, not a v1 item):** a
|
||||
distinct WebTransport feature — a proxy that terminates the browser's
|
||||
WebTransport connection and forwards encrypted traffic to a P2P hub's
|
||||
Ed25519 endpoint (so the hub need not expose its own public X.509 cert)
|
||||
— belongs in this same deferral bucket. It does not change the auth
|
||||
model: the browser still authenticates by bearer token, the hub still
|
||||
resolves it via `PeerEntry.auth_token_hash`, and the proxy is
|
||||
transport-only. ADR-030 §6's fingerprint normalization
|
||||
(`ed25519:<hex>` across quinn/iroh) was already designed to keep the
|
||||
proxied path clean. See
|
||||
[ADR-034](../../architecture/decisions/034-outgoing-only-x509-and-three-peer-roles.md)
|
||||
§5 for the recording.
|
||||
|
||||
### DH-3: How does HTTP map to call-protocol operations?
|
||||
*(One-way door — needs an ADR)*
|
||||
|
||||
@@ -335,6 +348,12 @@ implementation detail; the credential (API key/token) comes from
|
||||
strategy for generated OpenAPI specs (tied to the registry's External
|
||||
operation set version) needs specifying. One-way door after first
|
||||
publication.
|
||||
- **OQ-HTTP-07 (WebTransport relay-as-proxy)**: a WebTransport proxy that
|
||||
fronts a P2P hub for browsers (so the hub need not expose public X.509)
|
||||
is a real feature for the browser-to-P2P-peer case. Deferred with h3 /
|
||||
WebTransport (DH-2); recorded in ADR-034 §5 so it is not lost. Does not
|
||||
change the auth model (bearer token + `PeerEntry.auth_token_hash`;
|
||||
proxy is transport-only). Two-way door; lands with the `h3` fast-follow.
|
||||
|
||||
## Next Steps (Phase 0 → Phase 1)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user