Crate dig_stun 

dig-stun — the DIG ecosystem’s single home for reflexive-address discovery: how a node learns the public address the outside world sees its traffic arrive from, and how it decides whether to believe what it was told. SPEC.md at the repository root is the normative contract this crate implements; every public item here is cross-referenced to the section that specifies it.

It owns exactly five things (SPEC.md §1):

1. The RFC 5389 Binding codec (encode_binding_request, parse_binding_response, parse_binding_request, encode_binding_success) — request and success-response, both directions.
2. The UDP STUN client (query_reflexive_address) — one Binding transaction against one server over one socket. This is the crate’s only I/O and its only async fn; every other public item is a pure function.
3. The address-scope classifier (scope) — the single predicate every consumer uses to ask “could this address be a legitimate reflexive candidate, and could a stranger route to it?”.
4. The peer-observation role (observe) and the agreement rule (establish) — the parts that let every directly-reachable DIG node act as a reflexive-address source for its peers, and let a requesting node combine what several sources said without trusting any one of them.
5. The signed-Binding credential (credential, §14) — the challenge/response that lets a DIG-operated UDP STUN server tell a DIG node’s ask from anyone else’s, and the exact bytes a requester signs. The crate owns the wire form, the nonce contract, the signing preimage and the verifier; it does NOT hold private keys (§14.6).

It deliberately does NOT own the happy-eyeballs walk over several STUN servers (that is dig_nat::stun::discover_reflexive_address, which composes this crate with dig-ip), a UDP STUN listener for DIG nodes (nodes never open one — observe), tier policy (which servers to ask, in what order — the consumer’s job), any proof of inbound reachability (SPEC.md §1, §10), or any membership policy over a verified credential identity — that is a decision of the deployment that runs the server (§14.10).

Modules

credential

The signed-Binding credential (SPEC.md §14) — how a DIG-operated UDP STUN server tells a DIG node’s ask from anyone else’s.

establish

Provenance and agreement (SPEC.md §7): how several untrusted readings of this node’s own reflexive address combine into something worth writing into an on-chain advertisement — or, failing that, into nothing at all.

observe

The peer-observation responder role (SPEC.md §6) — how a directly-reachable DIG node answers dig.getObservedAddress for a peer, and the abuse bounds on doing so.

scope

The single address-scope classifier (SPEC.md §5) — the one range table every consumer asks “could this address be a legitimate reflexive candidate, and could a stranger route to it?” against.

Enums

StunError

Errors decoding a STUN message or performing a Binding transaction (SPEC.md §2.8).

Constants

ATTR_MAPPED_ADDRESS

Legacy MAPPED-ADDRESS attribute type (RFC 5389 §15.1) — some servers still emit it.

ATTR_XOR_MAPPED_ADDRESS

XOR-MAPPED-ADDRESS attribute type (RFC 5389 §15.2).

BINDING_REQUEST

Binding request message type (RFC 5389 §6 — method Binding = 0x001, class Request = 0b00).

BINDING_SUCCESS

Binding success response message type (method Binding, class Success = 0b10).

MAGIC_COOKIE

STUN magic cookie (RFC 5389 §6). Always the first 4 bytes after the message type + length.

Functions

encode_binding_request

Encode a STUN Binding request: a 20-byte header (type, length = 0, cookie, the 96-bit transaction id) and no attributes. transaction_id is caller-supplied so the response can later be matched to this request (SPEC.md §2.3).

encode_binding_success

Encode a STUN Binding success response carrying reflexive in one XOR-MAPPED-ADDRESS attribute and nothing else — no MAPPED-ADDRESS, no SOFTWARE, no FINGERPRINT (SPEC.md §2.7). The server-side counterpart of parse_binding_response.

new_transaction_id

Generate a 96-bit STUN transaction id from a CSPRNG (RFC 5389 §10.1: “It primarily serves to correlate requests with responses… and MUST be uniformly and randomly chosen from the interval 0 .. 296 - 1, and SHOULD be cryptographically random”).

parse_binding_request

Parse a STUN Binding request datagram, returning its transaction id (SPEC.md §2.5). The server-side counterpart of parse_binding_response, used to answer a peer or the operator/ relay/public UDP tiers with encode_binding_success.

parse_binding_response

Parse a STUN Binding success response, returning the reflexive SocketAddr from its XOR-MAPPED-ADDRESS (preferred) or legacy MAPPED-ADDRESS attribute (SPEC.md §2.4).

query_reflexive_address

Perform a single STUN Binding transaction against server over socket, returning the discovered reflexive (public) SocketAddr of socket.

Type Aliases

TransactionId

The 96-bit STUN transaction id. A plain array alias (not a newtype) so dig-nat’s re-exported signatures stay unchanged for its existing consumers (SPEC.md §2.1, §8.2).