macula_resolve_address (macula v4.2.6)

View Source

Resolve a macula-net IPv6 address to its hosting station's QUIC endpoint via the DHT.

Phase 2 (PLAN_MACULA_NET_PHASE2.md §4.2). Two DHT lookups:

  1. address_pubkey_map record keyed by sha256("address_pubkey_map" || addr) — returns the station pubkey that owns the address.
  2. station_endpoint record keyed by sha256("station_endpoint" || pubkey) — returns {quic_port, host_advertised}.

Both records are signature-verified. The redirect record is also address-bound: derive_address(realm, record.key) == addr MUST hold, otherwise the answer is rejected. This makes the cheapest spoof (sign a record claiming someone else's address) detectable without consulting any external trust authority — the address derivation IS the proof of ownership.

The DHT is decoupled via a find_fn callback. Production wires fun(Key) -> macula:find_record(Client, Key) end; tests pass a capture function.

Summary

Types

endpoint/0
error_reason/0
find_fn/0

Functions

resolve(Addr, Realm, FindFn)

Resolve a macula-net address. Realm is the 32-byte realm pubkey used for address derivation; the binding check rejects any redirect whose signer doesn't derive to Addr under that realm.

Types

endpoint/0

-type endpoint() ::
          #{station_pubkey := <<_:256>>,
            quic_port := 1..65535,
            host_advertised := [binary()],
            alpn := binary() | undefined,
            expires_at := pos_integer(),
            hosted_daemon => <<_:256>>}.

error_reason/0

-type error_reason() ::
          not_found | bad_signature | bad_address_binding | bad_delegation | delegation_expired |
          malformed_record |
          term().

find_fn/0

-type find_fn() :: fun((Key :: <<_:256>>) -> {ok, macula_record:record()} | {error, not_found | term()}).

Functions

resolve(Addr, Realm, FindFn)

-spec resolve(Addr :: <<_:128>>, Realm :: <<_:256>>, find_fn()) ->
                 {ok, endpoint()} | {error, error_reason()}.

Resolve a macula-net address. Realm is the 32-byte realm pubkey used for address derivation; the binding check rejects any redirect whose signer doesn't derive to Addr under that realm.