Module record 

macula 12’s DHT records, as macula_record and macula-go sign and verify them. A record is the signed object {key, tbs, signature} under MACULA-PQ-RECORD-V1; its tbs holds type, alg, version, created_at, expires_at and payload, and subject only on a domain type (tags 0x20 to 0xFF). sign refuses a key whose purpose does not fit the type; verify reads a record’s wire form in the design’s order and keeps its tbs bytes, so encode sends them unchanged.

A record is named by the key id of its key: the node_id for node records, procedure advertisements, content announcements and station endpoints, and the key id for every other type. A tombstone is named as the type it withdraws.

Structs

ContentAnnouncement

A content announcement’s payload.

ContentAnnouncementOptions

Where the content is served, then its name, size and chunk count, each left out when empty or None; ttl_ms, 0 for the default, 48 hours.

NodeRecord

A node record’s payload, as macula_record reads it. A field left out, or of another kind, is zero, empty or None.

NodeRecordOptions

A node record’s optional fields: station_id is None for the node itself; empty text and None coordinates are left out; kind is “station” or “daemon”; peers are kept sorted and once each; ttl_ms is 0 for the default, 48 hours.

OrgDirectory

An org directory’s payload: a realm’s statement that the org org_name is held by the key with key id org_key.

ProcedureAdvertisement

A procedure advertisement’s payload. kem_key is the provider’s KEM key as carried and its id, when the advertisement names one: a verified record’s pair is well formed, the key’s id its own.

ProcedureAdvertisementOptions

A procedure advertisement’s optional fields: its authorization, the provider’s KEM key as carried, which the advertisement names with its id (macula 13, E2E design amendment A1), and ttl_ms, 0 for the default and maximum, 5 minutes.

ProcedureDelegation

A procedure delegation’s payload: an org’s grant, signed by its org key, that the node advertiser may serve procedures under the org.

Record

A record: unsigned as a builder returns it, or signed or verified, when signed holds what signing or verifying gave. The payload is a map. subject names a domain record’s subject, None for none and on every other type.

RecordType

A record’s type tag.

Signed

What signing or verifying gave a record: the key as carried, its key id, the alg, the tbs bytes, and the signature.

StationEndpoint

A station endpoint’s payload: its QUIC port, 0 when it carries none from 1 to 65535, and the hosts it is dialled at.

StationEndpointOptions

A station endpoint’s optional fields: the hosts it is dialled at, left out when none; its ALPN, left out when empty; ttl_ms, 0 for the default and maximum, 5 minutes.

Tombstone

A tombstone’s payload: what it withdraws, why, and the withdrawn record’s slot fields.

TombstoneOptions

A tombstone’s optional fields: detail, left out when empty, and ttl_ms, 0 for the clock tolerance, 5 minutes.

Trust

What a caller trusts for its realm: the verifier’s profile and the realm key as carried, None when none is pinned.

Verified

A record verify returned. Only verify makes one.

Enums

Authorization

A procedure advertisement’s provider authorization, as macula_record’s read_authorization/1 reads it.

Reason

Why a tombstone withdraws a record.

RecordError

The refusals of a record, named as macula_record names them.

Constants

CLOCK_TOLERANCE_MS

How far a verifier’s clock may be from a record’s created_at and expires_at, 5 minutes.

MAX_ENDORSEMENT_WINDOW_MS

The longest a realm member endorsement admits its member, 30 days.

MAX_RECORD_BYTES

The longest wire form a record may have, 256 KiB.

OWN_NAMESPACE_PREFIX

Starts the namespace of a node’s own procedures, ~<node_id>/<name>.

Functions

content_key

The storage key every announcement of a content id shares.

encode

The wire form of a signed or verified record: its {key, tbs, signature} map, tbs unchanged.

envelope

An unsigned record of a domain type, 0x20 to 0xFF, with subject, living ttl_ms, or 48 hours when 0. An empty subject would name a slot apart from no subject, so it is refused.

in_own_namespace

Whether procedure names a node’s own namespace, ~ before its first slash, spelled well or not.

namespace_node

The node_id a ~ namespace names: exactly 64 lowercase hex characters, the one spelling of a node_id in a namespace.

new_content_announcement

An unsigned announcement by announcer_node, which signs it. A content id of another size or tag, or an empty procedure, is refused.

new_node_record

An unsigned node record about node_id, which signs it. A coordinate out of its range, or NaN, is refused.

new_procedure_advertisement

An unsigned advertisement, by advertiser_node, which signs it, of procedure in realm_id, served through serving_station. It builds no authorization but an org directory and a procedure delegation.

new_station_endpoint

An unsigned record of a station’s dialable endpoint. A QUIC port of 0 is refused.

new_tombstone

An unsigned tombstone that withdraws withdrawn: it names the record’s type, version and slot fields, takes its slot, and lives until the record has expired plus the clock tolerance, or ttl_ms past its own creation when later, so no replica serves the record again after it lapses.

org_directory_key

The storage key of an org directory record.

own_namespace

Whether a verified procedure advertisement is in its advertiser’s own namespace and admissible there: ~<node_id>/<name> where node_id is the advertiser_node verifying bound to its signer, with no authorization.

own_procedure

name in the own namespace of node: ~<node_id hex>/name.

payload_bounded

Checks a payload before anything is signed: its encoding is at most 256 KiB, and it nests at most 63 levels, which a record’s tbs leaves it under the decoding rule’s 64.

procedure_delegation_key

The storage key of a procedure delegation.

procedure_key

The storage key of a procedure’s advertisements.

procedure_org

A procedure’s org namespace: the text before the first / of its name. A name without a slash, or with _ before it, has none; a name starting with a slash is malformed.

read_content_announcement

Reads a content announcement’s payload.

read_node_record

Reads a node record’s payload.

read_org_directory

Reads an org directory’s payload.

read_procedure_advertisement

Reads a procedure advertisement’s payload.

read_procedure_delegation

Reads a procedure delegation’s payload.

read_station_endpoint

Reads a station endpoint’s payload.

read_tombstone

Reads a tombstone’s payload.

refresh

r with a new version, created now, with the same lifetime, signed again with key.

sign

Signs r with key, as macula_record’s sign/2 does. Refused, in macula’s order: a key whose purpose does not fit the type; a lifetime that runs backwards or past its type’s maximum; a payload that names a signer other than the key; a tbs or payload a verifier would refuse; and a record over 256 KiB.

station_endpoint_key

The storage key of a station’s endpoint record.

storage_key

The storage key of r. A record stored under its signer must be signed or verified.

verify

Reads a record’s wire form under the verifier’s profile and clock now_ms, as macula_record’s verify/3 does, in this order: a wire form over 256 KiB, before anything is decoded; a signed object that carries its key; its signature and alg; a tbs of exactly its fields; created_at no more than 5 minutes ahead and expires_at no more than 5 minutes behind; a lifetime within its type’s maximum; its type’s payload rules; and a payload that names its signer by the key’s id.

verify_authorization

A caller’s check of a verified procedure advertisement’s provider authorization against the realm it trusts, at now_ms. An org procedure needs an org directory and a procedure delegation, and the realm key: the directory must verify, carry the realm key and name the advertisement’s realm and the procedure’s org; the delegation must verify, signed by the org key the directory names, for the advertiser; and the advertisement expires no later than either.