Home / Docs / Specification / 30. Packages and dependencies

30.15 Publishing, yanks, audit, watch and bundles

Release v0.4.0

The client's side of ADR 0122 rules 33, 36.2 and 41 to 43, on the registry client of §14. Each rule here holds for una ita; none changes what una check reports, so they are tested as tooling.

  1. Reading and writing a registry. A source is read as §14 states: from the first of its places, its mirrors (§14 rule 1) and then its own URL, whose copy verifies, every byte verified before it is used. A submission is written through the transport of the source's own URL, below its base: a directory's transport writes each file once: into a fresh private file of its own name, then linked into place with a hard link, which fails when the target exists, so two writers never replace each other's file, and a second write of other bytes at the same path is refused; it never writes checkpoint or any path below checkpoint/; an https:// URL has no transport yet, and a command that would send to one stops with a diagnostic saying so (U7013), and sends nothing.

  2. Private sources (rule 42). Each need resolves at one source, with no fallback (§3 rule 2, §10). una ita add <owner>/<name> names the source that serves <owner> itself, and --from another source is a usage error, so a private owner's package is never looked for at another registry. Only the root and itaty.una name sources (§12 rule 1).

  3. Publishing (rule 43). una ita publish [path]:

    • refuses (U7013 at the head) a package that §11 rule 12 refuses; then one whose directory, or any ancestor of it up to the file system's root, holds an entry .git, a directory or a file: the check that a workspace member has no uncommitted change is not available yet, so a package in a git repository is not published, and no program is started to look. The check fails closed: a directory that cannot be resolved, and an entry that cannot be probed for any reason but its absence, refuse, and so does GIT_DIR or GIT_WORK_TREE set in the environment, which can put any directory in a repository; then one whose una check at tier 1 reports any diagnostic, an obligation not proven included;
    • publishes ita.una and the modules exactly as checked, and README.md, CHANGELOG.md and the license files at the top of the package, each read once with no link followed; every other file stays out, and a file or a bound that §9 rule 1 refuses refuses the publication;
    • sends to the source that the head's publish to names: a published package has no sources section, so a source other than itaty is the one that the sources of the nearest workspace whose itaty.una lists the package as a member declares, with its URL and its root's pin, and a source no such workspace declares is refused (U7013). itaty's URL and root are built into una. The URL is given to the transport of rule 1, so a source served over HTTPS stops here with U7013, and nothing is sent;
    • reads the name's state at a fresh checkpoint (§14 rule 3): the head of its chain, its releases and its yanks; a version already released, and authority or a trusted module beyond the highest release of its line in log order (§11 rule 7, §14 rule 6), every release of the name being logged before the new one, whether it is above or below the new version, are refused;
    • gives rule 26's advice: each public header of the highest release of the line in log order, a line of one of its modules that starts with pub read up to its =, that the new release no longer has as written, removed or changed, is printed as advice; nothing is refused for it;
    • writes the release statement of §11 rule 6, whose previous is the head of the name's chain and whose authority is the union of the uses of the package's public functions and of its handlers; signs it with the owner's keys of rule 4; and sends the archive, then the statement, as submit/<leaf>/archive and submit/<leaf>/entry below the source's base, where <leaf> is the hex of the statement's leaf hash (RFC 9162: SHA-256 of 0x00 and the signed note); then records registry/<source>/submitted/<leaf> in Itaoca, for rule 8: the line ita-submitted/1, then url <url>, name <name>, time <seconds>, the witness time of the checkpoint read, and sent <seconds>, the local clock when it was sent, each on its line. A submission sent but not recorded fails the command, saying so, since its promise could never be checked.
  4. The owner's keys (rule 38). The keys that sign a release or a yank are chosen in .una/keys of HOME, which MUST be a directory, not a link, that grants nothing to the group or to others, against the owner's keys and threshold valid at the checkpoint read (§14 rule 5). As a best-effort bound on a local attacker who can already write ~/.una, the directory's device and inode, read with no link followed, are recorded before it is listed; each key file opened MUST be on that device; and after every read the directory MUST still be the same one and still private; any change refuses:

    • the owner's key files are the regular files named <owner>-<id>.key, <id> lowercase hexadecimal, and itauna-<id>.key for a name without an owner;
    • every one of them must read: it is opened with no link followed, checked on the opened descriptor to be a regular file of at most 4 KiB that grants nothing to the group or to others, and read through it, at most one byte more; a link, a larger file, one others can read, one encrypted with a passphrase, and one that does not parse each refuse the command (U7013), so no key file of the owner is silently left out or taken. The copies of a secret this client makes are overwritten with zeros once used, a best effort that cannot reach every copy;
    • a key signs only when its name and its public key are those of a key of the owner, so its signature line carries the name and the key hash that a client looks for (§11 rule 3); every such key signs, and fewer distinct ones than the owner's threshold refuse the command (U7013).

    A key file is read in the form written without a passphrase:

    text
    ita-keyfile/1
    name acme.publisher
    secret <base64 of the 32-byte Ed25519 secret>

    A key whose public key fails §11 rule 2 on a signature of its own is refused. A key file encrypted with a passphrase starts with ita-keyfile-encrypted/1; it is refused with the reason that passphrase encryption is not implemented yet, and never read as clear.

  5. Promises (rule 36.2). The registry answers a submission with a promise, written at submit/<leaf>/promise: a note signed by the log's key whose text is ita-promise/1, source <source>, leaf sha256:<hex> and by <seconds>, each on its line. by is the registry's own commitment and no time of anything else. A submission's window starts at its anchor t, the later of its recorded witness time and its recorded local clock at sending, so a submission sent at a checkpoint up to 24 hours old is not judged against a window that closed before it was sent; the window ends at t plus one hour plus the hour of clock skew §14 rule 3 allows, which leaves the registry's clock and the network their latency. A local clock that runs fast can only widen the window through sent, which fails toward leniency, and is accepted:

    • a promise whose by is later than the end of the window is itself a broken promise;
    • kept means logged by by: the entry is in the name's verified chain at the checkpoint read, by its inclusion proof, and its logged-at time (§14 rule 7) is no later than by, or, with no promise, no later than the end of the window;
    • broken: logged later than that; not logged at a checkpoint whose witness time is past by; or no promise and not logged at a checkpoint whose witness time is past the end of the window;
    • pending otherwise.

    A promise served that does not verify (its signature, its source or leaf, or its text) is reported, and counts as no promise. The first verified promise of a submission is stored in Itaoca at registry/<source>/promises/<leaf>, with the record of the root version it was verified under, ita-promise-root/1 and root <version> sha256:<hex>, at registry/<source>/promises/<leaf>.root, written first; a stored promise is verified again against the log key of that root version in the root chain read, so a later rotation of the log's key leaves it verifiable, and one whose root version the chain does not hold does not verify; one stored with no record is verified against the last root's log key; a later promise whose text differs is a replaced promise, reported as evidence against the registry, and the judgment takes the earliest by of every verified promise seen, so a replacement never turns broken into kept. Kept is final: the submission is settled in the watch position (rule 8) and never judged again. Broken is provisional, as judged from what the places served, whose kept checkpoints may be incomplete and make a logged-at time later than it is: it is reported on every run, and never settled, until it is kept.

  6. Yanks and advisories (rule 41, §11 rule 11, and the amendment of ADR 0122 on the yank command).

    • una ita yank <version> [path] writes the yank statement of a release of the package, whose previous is the head of the name's chain, signs it with the owner's keys of rule 4, at least the owner's threshold, and sends it as submit/<leaf>/entry to the source that the head's publish to names, through the same transport as una ita publish (rule 3), where it is logged in the name's chain; a version not released, or already yanked, is refused (U7013).
    • The client reads a name's yanks and advisories from its chain (§14 rule 4), in log order. A yank stands only when it is of the name and source it is read for, names a release logged before it, its owner's chain is not refused (§14 rule 5), and its signers that the owner's keys as logged at its position count, less those tainted under the chain's compromises (§14 rule 5), meet the owner's threshold as logged there; any other yank is void and ignored, never a refusal of the name; and so is a second yank of a version already yanked; each void yank is noted, and una ita audit reports it (rule 7). An advisory stands only when it is of that name and source, at least one security key of the root signs it, and every version it names is a release logged before it; one security key holds a release back, and lifting the cooldown for the fix it names by digest needs at least the root's security threshold of distinct security keys, never fewer than two, or one security key and the owner's threshold (§11 rule 11). The security keys are judged first: the owner's signers, and the check that the timing of the owner's requests does not change how its keys judge the advisory (§14 rule 1, withheld cosignatures), are read only for an advisory with a fix that its security keys alone do not lift, so a doubt about the owner's timing never makes the name unavailable when the owner's signers cannot change what the advisory does. An advisory whose identifier the chain already holds, and any other entry that does not stand, refuse the name (U7010).
    • Resolution (§10 rule 4) reads a release as yanked when a yank of it stands, or when it counts only with a key revoked as compromised before its position; as advised when an advisory names it; and with no cooldown when a lifting advisory names it, by digest, as its fix. The cooldown is a wait in witness time: the witness time of the resolution point's checkpoint minus the release's logged-at time (§14 rule 7).
  7. una ita audit [path] opens each source of the lock's registry packages at a fresh checkpoint (§14 rule 3), which MUST extend the lock's resolution point of that source by a consistency proof, and reads, for each package, the verified state of its name and of its owner. It reports U7014, once per package with every finding, at the root's need when the root needs the package and otherwise at its line of ita.lock, for a release that is yanked; named by an advisory, with the advisory's identifier, severity and summary; that counts only with a key revoked as compromised since a log entry before it; for a recovery, a dispute or a change of recovery co-signers pending for its owner (the amendment of ADR 0122 on co-signer changes); and for a key change of its owner from a log position after the lock's resolution point. A package whose owner's chain is frozen by competing recoveries or disputes is U7010, giving the freeze's position. What reading the packages found about a registry is reported apart, from the client's typed records and never from a refusal's text, as una ita watch reports a broken or a replaced promise. An owner chain that does not settle (§14 rule 5, invariant (4)), naming the owner, the first log index whose claim differs and the replays made, and an equivocation, two checkpoints of one size that the log signed naming different root versions, naming the size, the versions and the places read, are evidence against the registry, once per record, at the source's registry section of ita.lock (U7010): two signed copies back an equivocation. A request whose deadline checkpoint no place serves, naming the owner, the request's log index and its target witness time, and a cadence gap, naming the range of sizes over which no checkpoint carries the witnesses' threshold of cosignatures, are evidence from an absence, which a place can cause, and two places can be one party: each is only a note, unattributed: a place or the registry, with the places read and how many served the same copy, never U7010 and never a cause of exit code 1. A release of the package's name whose cooldown eligibility a place's withheld cosignatures delay (the client's eligibility-delay observation, §14 rule 1), read on the lines resolution reads for the package, its own and each fix's, is reported for each locked package of the name with the delayed version, its logged time as served and the earliest the merged cosignatures allow: a finding of its U7014 when the delayed version is the fix that an advisory naming the locked release names, and a note otherwise. It also reports a void yank of the release (rule 6). The lock's accepted and effect indices count only as una ita lock --check counts them (§4 rule 2, §14 rule 8): below the lock's resolution point, a recovery or a dispute of the owner's chain there, pending and not canceled for an accepted line, in effect for an effect line; any other index is not honored. An effect after the resolution point that no effect line records is reported (U7014): a recovery or a dispute accepted while pending that has since taken effect needs consent to its effect of its own. The release the registry holds MUST be the one the lock names, by its log index and digest; a lock that names another, and a state that cannot be had verified at a fresh checkpoint, are U7010 at the package, or U7013 when a document that no place serves left it unavailable, told apart by the client's record of omissions (§14 rule 1) and never by a message, so the audit calls nothing clean that it did not verify, and it goes on with the next package, reporting each one. An advisory's identifier, severity and summary, which a registry served, are quoted with every control and direction-changing character escaped, at most 400 characters, as every message quoting a registry is. The exit code is 1 on any. una build never calls it. Costs: per package, one state of its name and one of its owner, each read once per source, then O(A + K) for its advisories and its owner's key events.

  8. una ita watch <owner> [<name>…] [--from <source>], itaty by default, reads the source the package in the current directory, or its workspace, declares, at a fresh checkpoint, and follows the owner's chain owner:<owner> and the chains of the names named and of those the position holds, from the position stored in Itaoca at registry/<source>/watch/<owner>.position:

    Output
    ita-watch/1
    source acme
    owner acme 12
    name acme/ledger 5

    the format line, the source, the owner with the count of its entries seen, and one line per name, sorted, with its count, in one encoding; a position that does not read is a usage error. A position MUST name the source and owner asked for, and each name line a package's name; a settled <hex> line records a submission settled as kept (rule 5). Settled lines whose submission record is gone are pruned; a position holds at most 100,000, and past that settling is refused, telling the user to remove old records in registry/<source>/submitted/. It prints each new entry, its chain, format, log index and leaf hash; a chain whose count is below the one stored is U7010 against the registry. For each submission recorded in Itaoca (rule 3) and not settled, whether or not its name is followed, at most 1,000 in one run, the oldest first, the run saying how many wait for a later one, it reads the promise at the place it was sent, verifies it with the log's key of the last root, judges it by rule 5, and prints it kept, broken, pending or unavailable; a place that serves no promise is judged as no promise, by the window, but a promise that cannot be read or does not verify never counts toward a kept verdict: one that would be kept is unavailable, not settled, and judged again on a later run, since what a place failed to give may only leave a verdict unavailable, never change it; a missing entry or checkpoint is a failure to judge, never a verdict, U7013 when the client recorded a document that no place serves; a failure to read or judge one is a line of its own, and the others and the entries are still printed. A broken or replaced promise, an unavailable verdict, a failure, and a position or first promise that cannot be stored exit with code 1; a broken promise is evidence the owner can publish. It then stores the new position, with the submissions settled. Itaoca is the user's own, local store: its records and positions are trusted as the user's files are, and only what the places serve is verified. Costs: one chain per name followed, each verified as §14 rule 4 states.

  9. Bundles (rule 33). una ita bundle <file> [path] reads each source of the lock's registry packages at the lock's resolution point (§14 rule 3), from its first place that verifies, and writes into one file:

    text
    ita-bundle/1
    <length of the listing>
    <listing: path NUL length NUL hex SHA-256, one line per entry, in ascending byte order>
    <each entry's bytes, in listing order>

    whose entries are packages/<hex>, the archive (§9 rule 3) of the package of digest sha256:<hex>; provenance/<source>/<hex>/checkpoint-<size>, its provenance at the lock's resolution point (§9 rule 7); and registry/<source>/<path>, every file of the source's registry, but its archives, that the client read to verify those releases: the root chain, the checkpoint of the lock's point and the kept checkpoints with the cosignatures that give each release its logged-at time (§14 rule 7), the log's tiles and entry bundles, and the map's tiles of each name and owner. Of each kept checkpoint, whose cosignatures the client merges across places (§14 rule 1, withheld cosignatures), the bundle carries every place's distinct copy, the first at registry/<source>/checkpoint/<size> and the others at registry/<source>/copies/<n>/checkpoint/<size>, n from 1, at most 65 in all, rather than one copy with the lines merged, since a note holds one signature line per key and two places may serve two cosignatures of one witness; unbundling reads them all as the bundle's copies and merges them as the client does, so it computes the same witness times offline. The bundle carries the whole root chain the client walked, every version included, those that revoke witnesses (witnesses-revoked) too, so the last root version every bundled checkpoint names travels with it; and, when the lock's point names an older root version, the latest checkpoint under the current root that the client read and the tiles of the proof that the point is its prefix, so the point's retired witnesses count offline as they count for the client. Unbundling reads root metadata and the latest checkpoint from the bundle alone and applies the client's own rule for a point under an older root (§14 rule 3), never a count of its own: it accepts at the lock's point a checkpoint naming an older version, as the client does at a lock's point, and treats a version a bundled checkpoint names that the bundle lacks as an omission (U7013), never trusting an older root in its place, and a root chain below the root version Itaoca stores, or one that holds that version with another digest than the floor stores (§14, Floors), as a refusal (U7010). A release the registry does not hold at that point as the lock names it, by log index and digest, is U7010, and a source no place serves verified U7010 or U7013; then nothing is written, and the file is written through a fresh file and a rename. At most 100,000 entries and 4 GiB. una ita unbundle <file> [path] opens the bundle with no link followed, checks on the opened descriptor that it is a regular file, reads it once into memory, at most one byte more than the largest bundle, and checks its listing (paths of these forms, strictly ascending, each entry's hash, nothing after the last). Then, for each registry package of the lock that Itaoca does not hold verified already, it verifies its archive's digest against the lock and its provenance as every load does (§9 rule 7, with ita.una's pin), and opens the bundle's copy of its source with the client at the lock's resolution point, with no freshness, against the checkpoint and the root version Itaoca stores for the source as its floors (§14 rule 3), and proves that the point extends the lock's by a consistency proof: the release the client reads MUST be the lock's, by log index and digest, and its name's state, its yanks and advisories and its owner's keys included, MUST verify, and its logged-at time is computed from the kept checkpoints the bundle carries. Only when every one verifies does it store them in Itaoca, and then the source's checkpoint and root version as its floors, through Itaoca's floor API, kept under the registry's identity, each replaced only by a larger one under the floor lock, so unbundling never moves either backwards. A floor that cannot be stored is a note, never a failure; one that exists and cannot be read is unavailable (U7013), and nothing is written: unbundling is offline, as every load is (§9 rule 7), and a bundle's root chain is never verified without the floor. The bundle's copy of a source is a place: its listing commits to the entries it holds, not to the registry files it should hold, so a registry file it lacks is an omission, read from the source's places behind it (§14 rule 1) and verified like the rest; one that none of them serves leaves the state unavailable, U7013, never a different result. A package the bundle does not hold is U7011, any other failure U7010, and then nothing is written. Entries that no locked package uses are not stored. Costs: O(B) for a bundle of B bytes, O(e log e) to sort its e entries, and the client's costs of §14 rule 11.