Skip to main content

Module at9p_gate

Module at9p_gate 

Source
Expand description

GATE verification pipeline for did:at9p genesis capsules (#884, design #879 §5.6).

Given the claimed self-certifying identifier did:at9p:<cid512> and the raw bytes fetched for it from some untrusted locator, this module decides — as a pure, I/O-free, synchronous function — whether those bytes are the genuine capsule that identifier names. It composes three gates, in a fixed order:

  1. canon-gate (R3 / A16) — decode the bytes with the strict deterministic DAG-CBOR codec and require reserialize(decode(bytes)) == bytes. Non- canonical encodings are rejected, never normalized, so no two byte strings can present as “the same” capsule. Capsule::from_dag_cbor already enforces this round-trip plus every schema gate.
  2. hash-gate (A1 / A16) — recompute the BLAKE3-512 CID512 over the canonical bytes and require it to equal the claimed cid512. This is the self-certification binding: the identity is the hash of the capsule, so a capsule whose bytes do not hash to the claimed identifier is rejected even when its own self-signature is perfectly valid (A1: forging a capsule for a known cid512 is a BLAKE3-512 second-preimage, infeasible).
  3. sig-gate (§4.4 / R4 / A19) — composite-verify via verify_capsule, which pins Hybrid (EdDSA and ML-DSA-65) independent of node CryptoPolicy and checks the per-record COSE context string.

§Why this order (cheapest-first, and each gate depends on the prior)

  • canon before hash. The hash is only meaningful over canonical bytes: without the canonical check first, an attacker could serve a non-canonical re-encoding of a legitimate capsule whose hash differs, or (worse) rely on decoder laxity. canon-gate is also the cheapest — one decode + one re-encode + a memcmp.
  • hash before sig. The composite verification (ML-DSA-65) is by far the most expensive step; the hash comparison is a single BLAKE3 pass. Rejecting an identity mismatch before touching the signature avoids spending a PQ verify on bytes that cannot possibly be the requested capsule. More importantly, hash-gate establishes which identity these bytes claim to be; sig-gate then confirms the capsule’s own keys signed it. A valid self- signature over the wrong cid must still be rejected (see the tests), and ordering hash before sig makes that structural.

The pipeline returns a VerifiedCapsule — a witness that all three gates passed, constructible only here — or a GateError naming the gate that rejected the input.

Structs§

VerifiedCapsule
A capsule that has passed the full canon → hash → sig GATE pipeline for a specific claimed cid512.

Enums§

GateError
Which gate of the verify_genesis_capsule pipeline rejected the input.

Constants§

DID_AT9P_PREFIX
The did:at9p: method prefix. A did:at9p identifier is exactly this prefix followed by the base32 CIDv1 (cid512) of the genesis capsule.

Functions§

verify_did_at9p
Verify a full did:at9p:<cid512> identifier against fetched capsule bytes.
verify_genesis_capsule
Verify that capsule_bytes are the genuine genesis capsule named by the claimed did:at9p:<did_body> identifier, where did_body is the bare cid512 (no did:at9p: prefix).