Skip to main content

Module locator

Module locator 

Source
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 no FromStr, From<&str>, AsRef<str>, or Deref<Target = str> — the only way in is the full 64-byte digest.
  • tests/locator_r1_invariants.rs parses this module with syn and 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 — a String, 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 and pub use are forbidden outright in this module. Cid512 may 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 hard compile_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).
LookupHints
Add-only accumulator of out-of-band lookup hints (review rule R7).
MainlineBep5
Real BEP5 client backed by [mainline::async_dht::AsyncDht].
MainlineLocator
The at9p mainline locator: full-width CID in, candidate peers out.
PeerContact
Candidate peer contact returned by the untrusted mainline locator.
RendezvousKey
Fixed-width rendezvous parameters folded into the CID-keyed lookup.

Enums§

MailboxHintDecision
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_hints into 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”).