Expand description
at9p mainline (BEP5) locator — see #889 / epic #880 Track C.
Mainline (BEP5) DHT locator — untrusted peer rendezvous for did:at9p.
Track C of the at9p epic (#880, story C1 = #889). This module wraps the
standalone [mainline] crate (MIT, pubky/pkarr lineage) to provide
arbitrary-infohash announce_peer / get_peers, which iroh’s internal
pkarr integration cannot do (it is NodeId-lookup only).
§Trust model
The DHT is an untrusted locator: it only ever yields candidate peer contacts. Zero authority is derived from anything read here — capsules fetched from returned peers must pass the full GATE pipeline (canon → H512 == cid512 → composite signature) before use (#879 §5.6).
§TRUNC20 confinement (review rule R2)
BEP5 keys are 20-byte infohashes; at9p identities are 64-byte BLAKE3-512
CIDs. The truncation from 64 → 20 bytes happens in exactly one place:
[rendezvous_infohash], private to this module. Every public API takes
the full [Cid512] plus fixed-width rendezvous parameters; no truncated
form escapes this module.
§No name path — review rule R1 (story C4 = #892)
Every public entry point on [MainlineLocator] takes a [Cid512]. There
is deliberately no string-name lookup, no name → cid resolution, and
no name → cid cache anywhere in this module. A name cache inside the
DHT client re-opens threat A5: it turns the DHT into a trusted namespace
authority (whoever poisons the cache chooses which capsule a name resolves
to), exactly the “toxic mold” failure mode #879 §3 excludes. Names are
resolved by a PQ-signed NameRecord from a trusted namespace authority
(PDS / discovery / MoQ group) above this layer; the locator only ever
answers “where might bytes for this cid live”, never “which cid does
this name mean”.
This is enforced structurally as a closed-world allowlist, not by enumerating forbidden string forms:
- [
Cid512] is a[u8; 64]newtype with noFromStr,From<&str>,AsRef<str>, orDeref<Target = str>— the only way in is the full 64-byte digest. tests/locator_r1_invariants.rsparses this module withsynand fails unless every public function/method parameter, public struct/enum field, and type-alias RHS is one of the vetted types —Cid512,RendezvousKey,PeerContact,LookupHints,SocketAddrV4, primitives, and byte views (recursing through&/Option/Vec/Box/slices). Any other type — aString, a struct-wrapped name (NameQuery), a generic (<S: ToString>,impl Display), an externally-aliased name — is rejected because it is not vetted, so a name path cannot enter in any new form; adding a public parameter type is a deliberate allowlist edit. Macros andpub useare forbidden outright in this module.Cid512may not gain a string-conversion trait impl. See the test’s module doc for the coverage matrix, the known limitation (test-time vs compile-time), and the follow-up tracking a hardcompile_error!enforcement.
§Add-only hints — review rule R7 (story C4 = #892)
#879 §6.1 lists two rendezvous strategies: (1) BEP5 announce_peer /
get_peers (chosen), and (2) a BEP44 deterministic-mailbox channel whose
keypair is derived from the cid and is therefore public-by-construction —
an overwrite war that is availability-only, acceptable only because the
values are untrusted hints. The v1 decision (Q3) is recorded by
[V1_MAILBOX_HINT_CHANNEL]: BEP5-only for v1; the mailbox is deferred.
Whether or not the mailbox ships, R7 is load-bearing: a hint channel may
only add lookup targets — it may never prune, replace, or terminate the
watermark-anchored BEP5 scan (A14: a bogus “current epoch” hint that skips
the scan converts an availability channel into a rollback assist). That
constraint is encoded in [LookupHints], an accumulator whose API is
add-only by construction (no remove / replace / clear), and in
[MainlineLocator::providers_with_hints], which always performs the
scan and then unions the hints in. There is no code path that lets a hint
skip the scan.
§wasm / browser note (documented, not built — C1 acceptance)
There is no raw mainline DHT from wasm: browsers cannot open UDP
sockets, and iroh itself falls back to a pkarr HTTP relay
(dns.iroh.link) there. The wasm locator therefore needs either a relay
bridge (an HTTP/WebTransport endpoint on a trusted-for-liveness node that
proxies get_peers) or a PDS fallback (capsule fetched via atproto
records, #910). That surface is shared with #470 and is deliberately not
implemented here; this module is native-only.
Structs§
- Cid512
- A full-width at9p content identifier (64-byte BLAKE3-512 CID).
- Lookup
Hints - Add-only accumulator of out-of-band lookup hints (review rule R7).
- Mainline
Bep5 - Real BEP5 client backed by [
mainline::async_dht::AsyncDht]. - Mainline
Locator - The at9p mainline locator: full-width CID in, candidate peers out.
- Peer
Contact - Candidate peer contact returned by the untrusted mainline locator.
- Rendezvous
Key - Fixed-width rendezvous parameters folded into the CID-keyed lookup.
Enums§
- Mailbox
Hint Decision - v1 decision on the BEP44 deterministic-mailbox hint channel (#879 §6.1, Q3 — resolved by story C4 / #892).
Constants§
- CID512_
LEN - Length in bytes of an at9p content identifier (BLAKE3-512 digest).
- MAX_
HINTED_ PEERS - Maximum number of out-of-band candidate peers one lookup will union in.
- MAX_
HINTED_ RENDEZVOUS - Maximum number of out-of-band rendezvous buckets one lookup will scan in
addition to the canonical key. Bounds DHT work: a malicious hint source
(untrusted PDS record, relay bridge, mailbox) cannot amplify a single
MainlineLocator::providers_with_hintsinto an unbounded fan-out. - MAX_
LOCATOR_ RESULTS - Maximum total candidate peers a single lookup will return (canonical scan unioned with hints, post-dedup). Keeps a flooded provider list from being amplified into unbounded downstream fetch work.
- RENDEZVOUS_
EPOCH_ LEN - Width in bytes of the rendezvous epoch.
- RENDEZVOUS_
K_ INDEX_ LEN - Width in bytes of the fixed-width rendezvous k-index.
- V1_
MAILBOX_ HINT_ CHANNEL - The v1 mailbox decision: BEP5-only (#879 §6.1 names option 1 “chosen”).