alkdev/alknet
6
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34729c78467fff3722d4727b5d3bca208ca82f5d
alknet/docs/architecture/questions/037-x-509-outgoing-only-case-three-peer-roles.md
T
glm-5.2 1baa619ce9 docs(arch): decompose open-questions.md into per-OQ files under questions/ 
The monolithic open-questions.md (1310 lines, 47 OQs) was large enough to be
unmanageable, with high size variance (OQ-42 at 220 lines next to OQ-06 at 8).
Decomposed into one file per OQ under docs/architecture/questions/ (NNN-slug.md,
mirroring the ADR convention), with open-questions.md retained as the index:
theme-grouped tables plus a cross-theme Deferred/Blocked section that surfaces
the 6 deferred OQs with their Blocked-on conditions inline (the safe-exit
visibility surface). Per-OQ content moved verbatim; all 62 inbound links stay
valid (none used anchors). README's curated OQ summary dropped (now redundant
with the index tables).

Also seeds tasks/architecture/ with this task plus two follow-ups found during
the decompose: OQ-09/10 missing structured Blocked-on fields, and the
tasks/architecture/ blocker-task half of the Safe Exit protocol being
unenforced.
2026-07-06 16:07:59 +00:00

3.4 KiB
Raw Blame History

OQ-37: X.509 Outgoing-Only Case (Three Peer Roles)

  • Origin: ADR-030 §"Bearer tokens" (the three credential types), the discussion that X.509 is fundamentally different from Ed25519

  • Status: resolved (2026-06-28 by ADR-034)

  • Door type: One-way (how X.509 server identity integrates with the peer model)

  • Priority: medium → resolved

  • Resolution: The pre-ADR-034 framing conflated three distinct remote roles under "X.509 endpoint." ADR-034 names them and resolves the peer-model question:

    1. Public X.509 endpoint — a remote HTTPS / alknet/call-over-TLS server reachable by domain, authenticated by CA verification (WebPkiServerVerifier). The local node is a client; it authenticates by bearer token. Not a PeerEntry on the client side — it is not in the call-protocol peer graph (ADR-029), gets no PeerId, and is not addressable via PeerRef::Specific. Ops discovered via from_call/from_openapi/from_mcp land in the connection's Layer 2 overlay and are invoked through the connection handle.
    2. Transport relay — iroh's DERP-equivalent (iroh-relay). Infrastructure, not an alknet peer; no PeerEntry / PeerId. Inherited with the iroh feature; its identity is iroh's concern.
    3. Hub / hosting node — an alknet application peer (head/worker hub, git-hosting hub) that also exposes a public domain + X.509 for browsers. A single PeerEntry with mixed fingerprints (ed25519:... + SHA256:...), already supported by ADR-030. Browsers connecting to it are not alknet peers — served by alknet-http, bearer-token auth, no PeerId.

    The "make PeerEntry symmetric" instinct is rejected. PeerEntry is for peers in the call-protocol peer graph; pure-client connections to public X.509 endpoints are not in that graph on the client side. The asymmetry reflects a real trust-model difference: known peers have stable logical identities (pin the fingerprint); public APIs don't (trust the CA, hold the connection handle directly).

    Client-side verifier selection rule (extends OQ-29): known peer (PeerEntry present) → fingerprint pin (Ed25519 ed25519:<hex> or X.509 SHA256:<hex>); unknown X.509 remote (PeerEntry absent) → CA verification. An unknown Ed25519 raw-key remote cannot be verified at all (no CA fallback) and fails closed — same model as iroh.

    Downstream, not blocking, recorded so they don't get lost: WebTransport relay-as-proxy (browser → proxy → P2P hub) is the remaining scope question tracked as OQ-38 (h3/WebTransport itself is now in scope, ADR-038); ADR-030 §6's fingerprint normalization already keeps the proxied path clean. On-chain / smart-contract peer discovery (relays syncing git repos via iroh gossip) is a source of PeerEntry records, fits the OQ-36 repo/adapter pattern (alknet-peer-store-onchain implementing IdentityProvider), and does not change the auth model.

    Not blocking the ADR-029 migration — the Ed25519 path is the primary use case and was already resolved; this ADR closes the X.509 outgoing-only remainder.

  • Cross-references: ADR-027, ADR-029, ADR-030, ADR-033, ADR-034, OQ-29, OQ-36, client-and-adapters.md, endpoint.md, auth.md

Reference in new issue View Git Blame Copy Permalink