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:
2026-06-28 10:47:49 +00:00
parent 3f011cbb82
commit 6cc8715ccf
8 changed files with 602 additions and 65 deletions

View File

@@ -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)