---
title: "30.11 Verifying a registry's documents"
url: https://una-lang.org/en/docs/spec/30-packages/11-verifying-a-registry-s-documents/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/30-packages.md
---

# 30.11 Verifying a registry's documents

The registry client verifies what it reads with these rules, each a pure function of the bytes; how it reads a registry and applies them is §14.

1. **The log's tree** is that of RFC 9162 §2.1: a leaf's hash is SHA-256 of `0x00` and the leaf, a node's of `0x01` and its children's hashes. An inclusion proof (§2.1.3.2) and a consistency proof (§2.1.4.2) are verified as RFC 9162 states; a consistency proof from a tree of no leaf is empty, and one between equal sizes needs equal roots. Each costs O(log L) hashes for a log of L leaves.
2. **Ed25519 is verified strictly**, by one rule: a key of 32 bytes and a signature of 64; the public key and `R` canonical encodings (`y` below p) of points not of small order; `S` below the group order; and the cofactorless equation.
3. **A signed note** (C2SP `signed-note`) is a text of lines without control characters, ending with a line feed, a blank line, and lines `— <name> <base64>`, whose base64 is canonical and decodes to a 4-byte key hash and the signature. The key hash of an Ed25519 key is the first four bytes of SHA-256 of its name, a line feed, `0x01` and the key; a note is signed by a key when a line of its name and key hash verifies the text. A note is at most 64 KiB, has at most 64 signature lines, and at most one line per key name and key hash; any other note is refused before a signature is verified.
4. **A checkpoint** (C2SP `tlog-checkpoint`) is a note whose text is the origin, the size in decimal without a leading zero and below 2^63, the root hash in base64, and non-empty extension lines. **A cosignature/v1** (C2SP `tlog-cosignature`) of a checkpoint by a witness is a signature line whose key hash uses `0x04`, holding an 8-byte big-endian timestamp and a signature of `cosignature/v1`, `time <t>`, each on its line, then the checkpoint's text.
5. **Witness time** (ADR 0122 rule 36.4). With k the witness threshold:
   - an entry is **logged at** the k-th earliest of the distinct witnesses' earliest cosignatures on checkpoints that include it;
   - the **witness time of a checkpoint** is the k-th latest of the distinct witnesses' cosignatures on it;
   - a wait is the witness time of the later checkpoint minus the logged-at time of the entry;
   - a witness whose timestamps decrease as the log grows is refused (U7010);
   - freshness alone compares a witness time with the local clock, and a local clock more than one hour behind the newest witness time is clock skew (U7010).

   Fewer than k witnesses can move none of these times in an attacker's favor.
6. **A release statement** is a signed note whose text is, in this order and each once: `ita-release/1`; `source <source>`; `name <name>`; `version <full version>`; `previous <index> <leaf hash>`, or `previous none` for a name's first entry; `digest <content digest>`; `manifest <digest of its ita.una>`; `edition <edition>`; one `needs <source> <name> <version>` line per need, sorted by name, each of the release's own source; `authority` with the capabilities and operations its public functions and handlers use, as `Http[get], Store[find, put]`, or `none`; and `trust modules <path>, ...`, or `trust none`.
7. **Authority is part of the interface** (rule 26). Within one identity, a release needs no capability, operation or trusted module that the highest earlier release did not; a statement that does is refused, by the registry and by every client.
8. **Root metadata** is a signed note whose text is, in this order: `ita-root/1`; `source <source>`; `version <n>`, from 1; `expires <seconds>`; `root <threshold>` and one `key <name> <base64 key>` line per root key; `log <name> <base64 key>`; `witnesses <threshold>` and a key line per witness; optionally `witnesses-revoked <fingerprint> …`, one or more fingerprints of witness keys, each the hex SHA-256 of the public key in 64 lowercase hex digits, none twice and none a witness of this version, whose cosignatures count for nothing at any version, under any name; a key whose fingerprint any version of the chain lists there is never a witness of a later version, and a chain where one is, is refused (U7010), checked from the pinned version on, since the pin is trusted and the versions before it are never read; `security <threshold>` and a key line per security key; `itauna <threshold>` and a key line per key of the official set. Each threshold is between 1 and its number of keys, and no name or key appears twice. Its digest, which `sources` pins and the lock records, is `sha256:` and the hex SHA-256 of the whole signed note. The first one a client accepts has the pinned digest and the threshold of its own root keys; a version `n + 1` is accepted only with the thresholds of version `n`'s root keys and of its own. Versions passed may have expired; the last one MUST NOT have, in witness time. A root version that rotates a witness out because its key is, or may be, compromised MUST list that key's fingerprint in `witnesses-revoked`: a retired witness not listed still counts on the checkpoints of its versions that the log binds to the current point.
9. **The name map** (rule 36.1) is a sparse Merkle tree of depth 256 over SHA-256 of each name, whose leaf is SHA-256 of `0x00`, the key, the index of the name's latest entry (8 bytes, big-endian), that entry's leaf hash, and its count of entries (8 bytes); an empty subtree of height 0 is 32 zero bytes, and a node and an empty subtree above it are SHA-256 of `0x01` and its two children. A checkpoint carries the map's root in its extension line `ita-map <base64 root>`. **The root a checkpoint names:** every checkpoint MUST carry exactly one extension line `ita-root <n> sha256:<hex>`, the version and digest of the root metadata it was signed under, inside the note's signed text, so the log's signature and every witness cosignature cover it and stripping or altering it invalidates them. A checkpoint without it, with two, or with one that does not parse, is refused (U7010). The resolution point, the latest checkpoint, MUST name the last root version the place serves: one that names an older version while a newer one is served stands for a newer checkpoint withheld, and is unavailable (U7013), never accepted. The version checkpoints name never decreases as the size grows, across the point and every kept checkpoint a client reads; a decrease is refused (U7010). Every copy of the checkpoint of one size names the same version: copies signed by the log that name different versions are two checkpoints of that size, refused (U7010) and recorded as evidence against the registry, and the version first recorded for a size is never replaced. A client verifies a checkpoint's signature with the log key of the root version it names, and counts its cosignatures so: a witness of the last root counts; a retired witness, one that is not, counts only when all three hold: (1) the checkpoint names a root version this witness belongs to, (2) the checkpoint is proven a prefix of a checkpoint signed under the last root by a consistency proof (every kept checkpoint below a point that names the last root is, by the proof that binds it to the point; a lock's point naming an older version is proven so against the latest checkpoint, one more checkpoint read and O(log L) hashes), and (3) no root of the chain lists it in `witnesses-revoked`; any other line is ignored. The threshold k that counts a checkpoint's cosignatures, for its witness time, is the larger of the threshold of the root version it names and the last root's, so a checkpoint naming an older version never counts by fewer than the current threshold. So an entry's logged time takes the k of its first including checkpoint, a request's start the k of its start checkpoint, and an effect, a freshness or a deadline the k of the checkpoint whose witness time it reads. Too few cosignatures that count on a lock's point make it unavailable (U7013), never refused. When the prefix proof of a lock's point cannot be completed, because no place serves the latest checkpoint, the latest checkpoint served names an older version, or no place serves a tile of the consistency proof, it is an omission of the prefix proof, and every result that would count a retired witness's cosignature, on the point or on any kept checkpoint naming an older version (a logged time, a start, an effect, a cadence), is unavailable (U7013), never decided on fewer cosignatures and never evidence of a missing checkpoint; a proof served that does not verify means the log forked (U7010). A rotation therefore leaves older history usable, a retired witness's cosignatures still counting on the checkpoints the log binds to the current point; a lock's point stays unavailable only when no place serves a later checkpoint signed under the last root to prove it a prefix of, or when its counted witnesses are revoked: a fail-safe cost, never a wrong result. A rotation that raises the witness threshold makes older history unavailable (U7013) wherever an older checkpoint a result reads carries fewer cosignatures than the new threshold, since k never drops below the last root's: a fail-safe cost of the rotation, so a registry SHOULD obtain the extra cosignatures on the kept checkpoints it serves, the pinned ones and the start, deadline and pre-deadline ones, before it raises the threshold. A version past the end of the root chain a place serves means a newer root is hidden, and the result is unavailable (U7013, an omission of a root version), never decided under the older key set; a version before the pinned one, or a digest other than that version's, is refused (U7010). A proof of a name's leaf, or of its absence, is a bitmap of 256 bits, set where the sibling at that height is not empty, and those siblings from the leaf up; its size is O(log M) hashes for M names, and checking it takes 256 hashes.
10. **A name's chain.** Each entry about a name names the previous one by its log index and leaf hash, or none. A client walks it from the map's head back to the last entry it holds, each link the previous one's, and the number of links walked MUST equal the map's count minus the count held, or the whole count on a first walk; otherwise U7010. So a map or chain that omits a yank, an advisory, a revocation, a recovery or a transfer is caught.
11. **Yanks and advisories** are entries of a name's chain. A yank is `ita-yank/1`, `source`, `name`, `version` and `previous`, signed by the owner's threshold. An advisory is `ita-advisory/1`, `source`, `name`, `previous`, `id` (1 to 64 letters, digits, `-`, `_` or `.`), `line` (the major line), `affected` (full versions of that line), `fixed <version> <digest>` or `fixed none`, `severity` (`low`, `medium`, `high` or `critical`) and a one-line `summary`; it names each affected version once and a fix later than every affected version, or the advisory is refused; it stands when one security key of the root metadata signs it, which is enough to hold a release back, and lifts the cooldown for the fix it names by digest only when at least the root's security threshold of distinct security keys signs it, and never fewer than two, or one security key and the owner's threshold (ADR 0122 rules 35 and 41). The two counts are of disjoint keys: the owner's signers are counted without any public key of the root's security set, so one key that is both counts once, as a security key. Folded oldest first, a name's entries give each release its digest, its logged-at time, whether it is yanked, the advisories that name it, and whether a lifting advisory names it as its fix; a second statement for one version, a yank or advisory of a version never released, or an advisory no security key signs is U7010. `una ita audit` reports a locked release that is yanked or named by an advisory (U7014).
12. **Publishing** (rule 43) refuses, before building anything, a package without `publish to`, `about` or `license`, with a `sources`, `replace` or `trust` section, or with a need of a path, a workspace member or another source than the one it is published to. Its release statement lists its needs at their least versions, each of its own source, sorted by name.
