Remote Registry Protocol

Reads are public and stable; mutations are authenticated and experimental. Consuming hosted packages - the registry config.json, index reads, and artifact downloads - is a normal client path that needs no account, login, or token (cabin login / cabin logout exist for the authenticated surfaces and are stable too). The mutation surfaces (cabin publish --index-url, cabin yank, and the admin API) require a token, stay gated behind -Z remote-registry, and carry no compatibility promise: those routes, framings, and status codes may change or disappear between releases without a migration path.

Names are scoped. Registry packages are always <scope>/<name> (e.g. fmtlib/fmt): every package route carries the <scope>/<name> pair, the artifact filename embeds the scope and the packaging revision (<scope>-<name>-<version>-<revision>.zip, so a downloaded archive stays self-identifying outside the directory tree), and publish/yank additionally require the token’s user to be a member of the target scope (see registry/docs/architecture.md, “Scopes”). Bare names exist only in local-only manifests and local file registries; cabin publish rejects them before any connection.

This is the authoritative contract for Cabin’s remote registry protocol: exactly what the Cabin client (this repository) and a conforming registry server implement. The registry service itself - accounts, token issuance, hosted storage - is not part of the Cabin crates; its hosted implementation lives under registry/ in this repository, outside the OSS core boundary described in registry-design.md.

Client status today: the config.json fields below and client-side token handling - cabin login / cabin logout plus token-optional reads - are stable, and the hosted registry is the default index origin when no explicit override applies. Publishing (cabin publish against an HTTP index source) and yanking (cabin yank) are implemented behind -Z remote-registry.

The default registry

When a command needs an index and neither the CLI (--index-path / --index-url) nor the config ([registry], see config.md) names one, Cabin uses its default hosted-registry index origin, https://registry.cabinpkg.com. The default behaves exactly like a config-supplied URL: [source-replacement] applies to it, --offline refuses it (pass --index-path, e.g. a cabin vendor output), and --frozen refuses a URL terminal. It only ever materializes when the selected closure actually has versioned dependencies, so dependency-free projects never observe it - and it never applies to cabin publish, cabin yank, or cabin vendor, which keep requiring an explicitly named source (cabin login / cabin logout do fall back to it, since they manage credentials for exactly that hosted registry - reads are public, and a token is what unlocks publishing).

Registry configuration

A remote registry serves the same registry-root layout as the sparse HTTP index documented in package-index.md. Its config.json may carry two additional fields:

{
  "schema": 1,
  "kind": "file-registry",
  "packages": "packages",
  "artifacts": "artifacts",
  "auth-required": false,
  "api": "https://cabinpkg.com"
}

Field	Type	Default	Description
`auth-required`	bool	`false`	When `true`, every request to this registry - including `config.json` itself, package metadata, and artifact downloads - must carry `Authorization: Bearer <token>`. The hosted registry serves `false`: its verified reads are public (`registry/docs/architecture.md`, “Origins and roles”).
`api`	string	absent	Absolute base URL of the registry’s API origin - on the hosted registry the website origin `"https://cabinpkg.com"`, following crates.io’s `"api": "https://crates.io"` discipline (see One role per hostname). Non-`http(s)` schemes and URLs with `userinfo` credentials are rejected, mirroring the index-URL hygiene of the sparse HTTP client. The read routes never consult it. When absent, `cabin publish` fails with an error naming the field: mutation requests are only ever sent to an explicitly declared API origin.

Both index parsers (the local --index-path loader and the sparse HTTP client) recognize the fields unconditionally: a vendored or mirrored copy of a hosted registry loads like any other file registry, and the read routes never consult api - only the gated mutation commands do.

One role per hostname

The hosted registry splits its hostnames by role, exactly crates.io’s discipline (index.crates.io serves the index, static.crates.io the downloads, and crates.io the web UI plus the entire API, glued together by config.json’s dl/api fields):

Hostname	Role
`registry.cabinpkg.com`	The machine read plane only, public for verified content: `config.json`, package metadata, artifact downloads, and `/healthz`. Cabin keeps artifacts on the index host - the client’s same-origin artifact rule makes a separate download host pointless - so this one hostname covers what crates.io splits across `index.crates.io` and `static.crates.io`.
`cabinpkg.com`	The website, plus everything else the registry serves: the browser sign-in flow, the session-cookie user API, the Bearer mutation routes, and the one unauthenticated JSON route - `GET /api/v1/stats`, aggregate download/package totals for the website’s own pages (service-local; not part of the client protocol). `config.json`’s `api` field names this origin.

On the index host, every path outside the read plane - the mutation routes included - answers the same uniform 401 as a missing token, whatever credential comes along: the mutation surface is indistinguishable from any unknown path there.

Authentication

The authenticated surfaces - publish, yank, the admin API, and any registry declaring auth-required - authenticate with a bearer token:

Authorization: Bearer cabin_<base62>

Reads on the hosted registry need no token. When the client holds one for the origin it is still attached; a presented token that fails to validate answers the uniform 401 rather than being ignored, so a rotated or revoked credential fails loudly instead of silently reading as anonymous.
Tokens are issued on the registry’s web UI after GitHub sign-in. Its URL is not derived from the index origin by convention; it is discovered through the login-URL challenge below.
Token scopes: publish, yank, and verify (the verification lifecycle’s verifier scope). Any valid token additionally opens the read plane’s verify-scope carve-outs (pending-artifact fetches).

Every unauthenticated (401) response from the Bearer plane carries a WWW-Authenticate challenge naming the token-creation page, mirroring Cargo’s Cargo login_url challenge:

WWW-Authenticate: Cabin login_url="https://cabinpkg.com/settings/tokens"

The grammar is the scheme token Cabin (ASCII case-insensitive, per RFC 7235) followed by a quoted login_url parameter carrying an absolute http(s) URL. The header is byte-identical on every path and failure reason - a missing token on the mutation surface, an invalid token, and an unknown path all answer the same challenge - so the 401s the Bearer plane still emits stay indistinguishable from one another. Because the read plane serves unauthenticated GETs, reads themselves no longer challenge; the challenge survives on every non-read-plane path of the index host, which is where discovery finds it.

Client-side token handling

Token handling is part of the stable read path: whenever a credential is available for the index origin, the sparse HTTP client authenticates its reads with it, and cabin login / cabin logout manage the stored credential.

`cabin login` and `cabin logout`

cabin login resolves the registry from --index-url (or the [registry] index-url setting in config.md, else the default registry - a local index-path is rejected, since tokens only apply to HTTP registries), names the resolved origin, discovers the token-creation page, and reads the token from stdin - without echo when stdin is a terminal, as a plain read otherwise so piping works. The credential commands consult user-level config only: a checked-out project’s .cabin/config.toml (registry selection or [source-replacement]) must not be able to steer where a pasted credential is stored. The advisory probe is skipped entirely under offline mode:

$ echo "$TOKEN" | cabin login
logging in to `https://registry.cabinpkg.com`
visit https://cabinpkg.com/settings/tokens to create a token
       Login token for `https://registry.cabinpkg.com` saved

Discovery is advisory and always unauthenticated: one GET of the index’s config.json - an auth-required registry answers it with the challenged 401 - and, when that read succeeds instead (public reads), one GET of the index root, which is off the read plane and answers the uniform 401 with the same challenge on the hosted registry. On a 401 carrying the login-URL challenge, the challenge’s URL is printed verbatim. Every other outcome - a missing or malformed challenge, an implausible URL, or a failed probe (offline) - degrades to a generic create a token in the registry's web interface hint. The probe never blocks login: the pasted token is read and stored either way.

The token must start with cabin_; the confirmation only ever names the origin. cabin logout removes the entry for the effective index origin and reports whether one existed.

Credential storage

Tokens live in credentials.toml inside the user config home - the same directory resolution as the user-level config.toml in config.md: $CABIN_CONFIG_HOME verbatim when set, else the platform user config home with the cabin suffix (Linux and macOS: $XDG_CONFIG_HOME/cabin / $HOME/.config/cabin; Windows: %APPDATA%\cabin).

[registries."https://registry.cabinpkg.com"]
token = "cabin_..."

Keys are normalized index origins - scheme + host + port, no path, no trailing slash. Unknown fields are rejected. On Unix the file is created with mode 0600, and Cabin warns once per invocation when an existing file is group- or world-readable. Writes are atomic (sibling temp file + rename). Credentials are deliberately not part of config.toml: config.md rejects credential-shaped tables so a secret can never ride along in a published archive.

Environment override

When CABIN_REGISTRY_TOKEN is set and non-empty, its value wins over credentials.toml for the origins it applies to: the default registry’s origin and loopback origins (local testing). Any other registry always uses credentials.toml - the override carries no origin key of its own, and an invocation’s index origin can come from project-level config or [source-replacement], so an unrestricted override would let any built project route the credential to an origin of its choosing. The override is useful for CI, where writing a credentials file is undesirable; it also works when no user config home can be resolved at all. Cabin removes the variable from the environment of every child it spawns - cabin run / cabin test executables, the Ninja build backend (and the compile / wrapper commands it runs), the toolchain detection probes, clang-format, run-clang-tidy, and pkg-config - so spawned code cannot read the credential.

When the token is sent

With a credential available, every request to the registry - config.json, package metadata, and artifact downloads - carries Authorization: Bearer <token>. A stored token is sent to exactly two destinations: (a) the index origin it is stored under, and (b) the api origin declared by that index’s authenticated config.json, where the mutation routes live - and nowhere else. This mirrors Cargo, whose tokens go to the api host named in config.json. Neither destination ever sees the token over plain http except loopback hosts (127.0.0.0/8, ::1, localhost), which keeps local testing possible. Client-side error mapping: a 401 without a stored credential advises cabin login --index-url <origin> (the actionable path to a working read); a 401 despite one reports the token as rejected (revoked or expired); a 403 reports a missing scope. The token never appears in logs, error messages, or debug output.

Read routes

The read routes are the same shapes as the sparse HTTP index in package-index.md, served from the index origin:

Route	Purpose
`GET /config.json`	Registry configuration (this document’s fields included).
`GET /packages/<scope>/<name>.json`	Per-package index document.
`GET /artifacts/<scope>/<name>/<scope>-<name>-<version>-<revision>.zip`	Source archive download, one route per packaging revision. The `<revision>` segment must be exactly 16 lowercase hex characters and the `<version>` segment must not carry SemVer build metadata; anything else is a `404` before storage is consulted.

On the hosted registry all three serve unauthenticated GETs: no account, login, or token is needed to consume verified packages, and non-GET methods answer 405. A request that does present a token gets it validated - an invalid one is the uniform 401 with the error envelope body {"errors":[{"detail":"authentication required"}]} and the login-URL challenge, never a silent downgrade to anonymous. On a registry declaring auth-required, all three instead return that same 401 whenever the request carries no valid token, identical whether or not the requested package exists. Either way the 401 bytes match every non-read-plane path of the index host, so the mutation surface stays indistinguishable from unknown paths.

On a registry with the verification lifecycle, the composed /packages/<scope>/<name>.json document contains verified revisions only - each version’s revision pointer names its current one and its revisions map lists every verified revision of it - and the artifact route serves verified revisions to ordinary tokens; a package with no verified revisions is indistinguishable from an unknown one. A superseded verified revision stays downloadable, which is what keeps lockfiles that pin it building.

Publish

PUT /api/v1/packages/<scope>/<name>/<version>[?new-revision=true]

Requires a token with the publish scope. The route lives on the API origin - the api base URL (the website origin, on the hosted registry) the registry’s config.json must declare for mutations. The request body is a length-prefixed frame (crates.io-style):

[u32 LE metadata_len][canonical per-version metadata JSON]
[u32 LE archive_len][zip bytes]

The metadata JSON is exactly the canonical document cabin package emits - one packaging revision of a version, carrying that revision’s checksum and revision-qualified source path.

A new-revision query parameter accepts only the value true (any other value is a 400, so a typo can never silently drop the opt-in); other query parameters are ignored. It is the opt-in described under Revisions below.

Server-side behavior is part of the contract:

Validation. The server validates the framing, parses the metadata under the index schema (schema values other than 1 are refused - a document the verifier cannot judge must never enter the pending queue), requires the URL’s <scope>/<name> / <version> segments to match the metadata (the metadata’s name field carries the full <scope>/<name> string), requires every key of the metadata’s dependencies and dev-dependencies maps to be a canonical <scope>/<name> name (system-dependencies is exempt - its keys name system packages, not registry packages), requires a declared upstream provenance block to pass a lexical mirror of the manifest’s provenance rules (credential-free HTTPS URL, 64-hex sha256, "tar.gz" / "zip" format, single-component strip-prefix, non-escaping copy paths, non-escaping patches entries distinct from copy paths and the root manifest - the server never fetches the URL), requires a declared links map to pass a lexical mirror of the manifest’s rules (valid target-name keys, identities of ASCII letters, digits, ., _, +, and -, each identity claimed at most once), and verifies the archive bytes against the metadata’s sha256:<hex> checksum. Failures are 400. Two name-level rules join the same 400 family (registry/docs/architecture.md, “Name fidelity”): a reserved package name (package name is reserved - the DOS device stems plus a short project vocabulary), and, for a publish that would create a new package, a name that collides with an existing same-scope package under -/_ folding (package name conflicts with an existing package in this scope (differs only in '-' vs '_')). A version must be a plain upstream version: a <version> segment carrying SemVer build metadata is a 400 (package version must not carry build metadata; packaging corrections are published as revisions of the same version).
Idempotency. Re-publishing byte-identical metadata and archive succeeds with 200 and body {"ok":true,"no_op":true,"revision":"<16 hex>","verification":"<status>"}, reporting the recorded revision and its current verification status. The stored metadata is preserved, not rewritten.
Revisions. Different bytes for a version that already has a live (pending or verified) revision require the ?new-revision=true opt-in. Without it the request is a 409 explaining the mechanism: the version is already published with different bytes; published revisions are immutable - pass --new-revision to publish the changed bytes as a new packaging revision of this version, or bump the version. With it, a new revision is created in pending. Two different archives whose digests share the same 16-hex prefix are a loud 409 (a packaging revision with this id already exists with different bytes), never a silent overwrite.
The revision contract. A revision must not change what resolution consumes: dependencies, features, and standards are identical across every revision of a version, so a respin can never alter a decision the resolver already made. A change to any of them is a new version, not a revision. links joins the contract with a one-way rule: a revision may add a claim table to a version published without one (identities are stamped onto already-published versions as recipes adopt the key - note this retroactively applies to every packaging revision of the version, older pinned revisions included, whose archived manifests may predate the declaration), but an existing table can never be changed or removed by a respin. cabin publish --registry-dir rejects a violating respin outright, naming the field that changed; it is a protocol obligation on any registry implementing this contract.
Recovery. A version whose revisions are all rejected never became part of the registry, so fresh bytes are accepted without the opt-in. Byte-identical bytes revive the rejected revision in place - new metadata, timestamp, and publisher - back to pending with a 201.
A publish that creates or revives a revision succeeds with 201 and body {"ok":true,"name":...,"version":...,"checksum":...,"revision":"<16 hex>","verification":"pending"}: the revision is accepted but becomes resolvable only once verified. Clients read the verification and revision fields tolerantly - a registry without the lifecycle simply omits them.

Publishing from the client

cabin publish targets a remote registry when the effective index source is an HTTP URL (--index-url, or the [registry] index-url setting in config.md) and no --registry-dir is given. Without -Z remote-registry, the --index-url flag (even combined with --dry-run) and publishing against a config-supplied HTTP index both fail with the standard experimental-feature error. The flow is log in once, publish, then resolve like any consumer:

$ echo "$TOKEN" | cabin login --index-url https://registry.cabinpkg.com
logging in to `https://registry.cabinpkg.com`
visit https://cabinpkg.com/settings/tokens to create a token
       Login token for `https://registry.cabinpkg.com` saved
$ cabin -Z remote-registry publish --manifest-path fmt/cabin.toml \
    --index-url https://registry.cabinpkg.com
Published fmt 10.2.1 to https://registry.cabinpkg.com
  checksum: sha256:...
  revision: 9a93b2b7dfdac77c
$ cabin resolve --manifest-path app/cabin.toml

Client-side behavior:

The staging pipeline is the same one cabin package and the local cabin publish --registry-dir run - same validation, same publish lints (package-format.md), same deterministic archive and canonical per-version metadata document. The uploaded bytes are byte-identical to what cabin package writes into dist/ for the same source tree.
config.json (which supplies the api origin) and the lint baseline ride the read path with the publisher’s token attached; the upload carries the same bearer token to the API origin, under the same https-or-loopback cleartext rule.
On 201 the client reports the published name, version, checksum, and revision. On 200 it reports that byte-identical bytes were already published and exits successfully - the same “re-running with identical input succeeds” semantics as the local flows. On 409 it explains that the version exists with different bytes, that published revisions are immutable, and that the remedies are --new-revision or a version bump.
cabin publish --new-revision sends the ?new-revision=true opt-in. The same flag drives the local --registry-dir flow, so the rule is identical whichever registry is targeted: changed bytes for a published version are a deliberate act, never an accident of a forgotten version bump.
When the response’s optional "verification" field says "pending", the report adds that the version was accepted and becomes resolvable after verification (typically within a few minutes). The field is read tolerantly: a registry that omits it changes nothing.
--dry-run stays entirely local: it stages into --output-dir (default dist/) and never opens a connection.

Verification lifecycle

Verification is per packaging revision, not per version:

publish (201) --> pending --verdict: verified--> verified (resolvable, immutable)
                    ^  |
                    |  +--verdict: rejected--> rejected (blob reclaimed, quota refunded)
                    |                              |
                    +--republish, identical bytes--+
                                   (201)

pending - accepted and stored, but not part of the registry yet: excluded from composed /packages/<scope>/<name>.json documents and not downloadable with ordinary tokens. An external verifier inspects pending revisions and renders a verdict through the admin API.
verified - part of the registry: composed, resolvable, downloadable, and covered by the immutability guarantee, which applies to verified revisions only.
rejected - the revision never became part of the registry: its archive blob is reclaimed (unless another live revision stores the same bytes) and the publisher’s storage quota is refunded. Republishing the identical bytes revives that revision to pending for a fresh verdict; different bytes create a new revision, needing the opt-in only while some other revision of the version is still live.

A version’s current revision - the one the composed document’s revision field names - is the verified revision with the newest published_at, breaking ties on the greater revision id. Its revisions map carries every verified revision of the version, so superseded ones stay resolvable by pin. Pending and rejected revisions appear in neither: a respin under review never disturbs what consumers are being served, and it becomes current only when it is verified.

Fail-safe direction. If the verifier never runs, nothing new ever becomes resolvable. Broken verification infrastructure can only keep content unexposed; it must never expose unverified content.

The verifier may also abstain - render no verdict at all, because an advisory name check wants an operator’s eyes first (registry/docs/architecture.md, “Name fidelity”). Abstain is not a wire state: the version simply stays pending, and clients see exactly what they would see while awaiting any verdict.

Admin API (scope `verify`)

The verify scope belongs to the verifier: it may list pending revisions and download their artifacts (ordinary tokens cannot; rejected revisions are downloadable by no one), and it gates the two admin routes, which authenticate with the same Authorization: Bearer mechanism on the same API origin.

GET /api/v1/admin/versions?status=pending

Lists revisions by status (pending, verified, or rejected; anything else is 400) as a single JSON object, {"versions":[...]}. Each entry carries name, version, revision, checksum (lowercase SHA-256 hex), the publisher’s registry-native user id as published_by, published_at, and the stored canonical metadata document as metadata. Deterministic: ordered by name, then version, then revision.

GET /api/v1/admin/packages

The package corpus for the verifier’s name advisories: {"packages":[{"scope":...,"name":...,"vetted":<bool>}]}, every package ordered by scope then name, vetted reporting whether any of its revisions is verified - the advisories skip a name that was accepted once. Deliberately not “has any verdict”: a rejection never vets a name, so rejecting an abstained squat cannot exempt that same name’s next version.

PATCH /api/v1/admin/versions/<scope>/<name>/<version>
{ "verdict": "verified" | "rejected", "reason": "...", "checksum": "...", "published_at": "..." }

Renders a verdict on a pending revision; reason is required for rejections and recorded on the revision. The route names a version, so checksum and published_at are required for both verdicts (400 without them): checksum selects which revision of that version the verdict applies to, and published_at - which changes whenever a revision is revived - binds it to exactly the row generation the listing reported. A rejected revision can be revived at any moment under the same checksum, so a stale verdict of either direction must never land on a generation it never judged. A binding that does not match the stored row conflicts (409), and the same guard is enforced transactionally: a verdict racing a conflicting verdict or a revival answers 409 rather than applying. verified stamps verified_at and makes the revision resolvable; rejected reclaims the blob (when no live revision references its bytes) and refunds the publisher’s storage quota. The response reports the resulting state and whether the request changed it, mirroring yank: {"ok":true,"name":...,"version":...,"revision":"...","verification":"...","changed":<bool>}.

Verdicts are idempotent for the same value: repeating the verdict a verified revision already carries is a 200 no-op. Conflicts are 409: a rejecting verdict on a verified revision hits the immutability wall, and any verdict on a rejected revision is refused - republishing is the recovery path, and a late duplicate verdict must never race the revival. An unknown (name, version, revision) triple is an authenticated 404.

The verifier’s checks

The hosted registry’s verifier is cabin-registry-verify, run every few minutes by a GitHub Actions workflow (operations live in the service runbook). It inspects each pending archive against the canonical metadata the listing reported - parsing the zip container by hand, decompressing each entry through a bounded reader, never extracting the registry archive to disk, and assuming the archive is hostile. The archive must conform to the strict zip profile whose normative definition is registry/docs/archive-format.md; this section is the user-facing summary. The checks, in order:

Size discipline: the sum of the entries’ declared uncompressed sizes is a cheap up-front cap, and the running decompressed total is capped again as each entry is inflated, at min(max(ratio x compressed size, floor), absolute cap) - the floor covers the container framing the entry cap permits, since framing alone “expands” small archives beyond any sane ratio. The entry count and per-entry path length are capped too, and crossing any cap aborts the inspection: a decompression bomb is rejected, never inflated.
Structure: the container must be a well-formed zip in the strict profile - the end-of-central-directory record at the fixed len - 22 offset (single disk, zero comment, no zip64), the local records and the central directory tiling the file contiguously with no gaps, overlaps, or bytes outside the tiled regions, each entry stored or deflated with no data descriptors, extra fields, or comments and every general-purpose flag clear except the UTF-8 bit on non-ASCII names, and every local header agreeing with its central header. Each deflated entry must decompress to a clean stream end that consumes exactly its compressed span and yields exactly its declared uncompressed size, and its declared CRC-32 must match the bytes produced. Entries are regular files only (directory entries or attributes are rejected; directories are implied), with safe relative paths - no absolute paths, no .., no duplicates, no \, no empty or . component, and none of the Windows-hostile shapes the shared path predicate forbids (:, a control character, < > " | ? *, a leading or trailing space, a trailing dot, or a reserved device name) - no name colliding with another under case-insensitive folding, no regular file used as another entry’s parent directory, and cabin.toml at the archive root.
Consistency: the embedded manifest is parsed with Cabin’s real manifest parser, must pass the same publishability rules cabin package enforces (no [patch] table, no path dependencies, no escaping source paths, no standard contradictions), must have every target source it declares present in the archive (a package missing a declared source would extract but fail to build), and must reproduce the entire stored canonical metadata document through the same derivation publish used - name, version, the three dependency tables, language-standard fields and the per-target standards table, the per-target links claims, features, profiles, toolchain, build settings, the upstream provenance block, and the source block - and the archive bytes must hash to the recorded checksum (defense in depth; the server already checked at publish).
Upstream provenance, when the metadata declares a [package.upstream] block (manifest.md). The workflow downloads the pinned upstream archive itself - the binary still performs no HTTP, and the privileged token is never sent to the publisher-controlled URL - and passes it to the verifier, which requires the bytes to hash to the pinned SHA-256, interprets the archive with the same hardened extraction foundation ports use (bomb caps, lexical path safety, strip-prefix matching, symlinks skipped) in a scratch directory, applies the declared copy steps in order, then applies the declared patches in order - byte-exact unified diffs, using the patch bytes shipped inside the published archive itself, so verification needs exactly two inputs: the pinned upstream archive and the published package - collects the resulting tree under cabin package’s include / exclude policy, and requires the published archive’s entries to match the expected tree byte for byte - except the root cabin.toml, which is the publisher’s manifest, never upstream’s, and the declared patch files themselves, which are publisher-authored transformation inputs rather than products of the upstream tree (and are for that reason held to a strict diff-only grammar: free text around the diff would let one file be both a valid patch and valid source code, laundering unverified bytes past the comparison). When the upstream download fails - including a pinned archive over the 256 MiB download cap, which is part of the provenance contract (manifest.md), or when the run’s bounded upstream-download time budget is exhausted (versions are processed in a shuffled order, so slow upstream hosts cannot pin the same versions to the front of every pass) - the verifier still runs the structure and consistency passes (which can reject on their own); a version whose provenance could then not be checked stays pending, because a transport failure must not terminally reject a package (the stuck-pending alert summons an operator instead). Deterministic disagreements - a digest mismatch, an uninterpretable archive, an inapplicable copy step, a malformed or inapplicable patch, a diverging tree - are rejections with the stable codes below.

A rejection records machine-readable reason codes in the revision’s verification_reason:

Code	Check
`decompressed_too_large`	decompression cap crossed
`too_many_entries`	entry-count cap crossed
`path_too_long`	path-length cap crossed
`unsupported_zip_feature`	a banned zip feature: a compression method other than store/deflate, a general-purpose flag outside the profile (any bit but the UTF-8 bit, which must be set exactly on non-ASCII names), a nonzero extra field, a comment, zip64, or a data descriptor
`header_mismatch`	a local header disagrees with its central header, or a declared uncompressed size or CRC-32 disagrees with the decompressed bytes
`forbidden_entry_type`	a non-regular entry: a symlink, a directory entry or attribute, or any other non-file type
`absolute_path`	absolute entry path (POSIX or Windows-drive form)
`path_traversal`	`..` path component
`invalid_path`	empty, non-UTF-8, `\`-bearing, or an empty/`.` component; a trailing-slash directory marker; or a Windows-hostile shape (`:`, a control character, `< > ”
`duplicate_path`	the same path (byte for byte) twice
`case_conflict`	two paths that fold to the same string under Unicode default lowercasing, including a file used as a case-folded parent directory
`path_conflict`	a regular file used as another entry’s parent directory
`missing_source`	the manifest declares a target source absent from the archive
`manifest_missing`	no `cabin.toml` at the archive root
`manifest_invalid`	the manifest does not parse as a publishable package
`name_mismatch`	manifest name disagrees with metadata or the listing
`version_mismatch`	manifest version disagrees with metadata or the listing
`dependency_mismatch`	manifest dependency tables disagree with metadata
`language_standard_mismatch`	manifest standard fields or the derived standards table disagree with metadata
`checksum_mismatch`	archive bytes do not hash to the recorded checksum
`metadata_mismatch`	any other canonical-metadata field disagrees with what the manifest derives
`archive_invalid`	not a well-formed zip container: a bad or misplaced EOCD, a non-contiguous layout, or bytes outside the tiled regions
`upstream_mismatch`	the stored `upstream` block disagrees with the manifest’s `[package.upstream]` declaration
`upstream_checksum_mismatch`	the downloaded upstream archive does not hash to the pinned SHA-256
`upstream_archive_invalid`	the pinned upstream archive cannot be interpreted as declared: the hardened extractor refused it, its compressed stream would not decode (`stream`), an entry name cannot be materialized on the verifier’s filesystem (`file name`), the declared strip prefix is absent (`strip prefix`), or the extracted file set violates packaging rules (`file set`)
`upstream_copy_invalid`	a declared copy step cannot be applied to the extracted upstream tree: its `from` file is absent (`missing source`), or its `to` cannot name a regular file there (`destination`)
`upstream_patch_invalid`	a declared patch file cannot be applied to the assembled upstream tree: the published archive lacks the declared entry (`missing file`), the patch exceeds the 1 MiB per-file cap (`too large`), the patch path also names a file the upstream transformation produces (`shadows tree`), it is not strictly a unified diff - free text around the diff or inside git’s preamble lines is rejected along with structural corruption (`malformed`), it carries binary content (`binary`), a diff header path cannot address the tree (`unsafe path`), the patched file is absent (`missing target`), the patched or created path cannot name a regular file (`target conflict`), the patched file exceeds the 16 MiB per-target cap (`target too large`), the `patches` list carries more than 1024 file entries (`too many file entries`), applying the whole list would read or rewrite more than 128 MiB of the tree (`work budget exceeded`), or the tree’s bytes do not match the patch context exactly (`context mismatch`)
`upstream_tree_mismatch`	the published tree is not the declared transformation of the upstream archive; the detail names the first divergence in sorted-path order, reporting missing and diverging files before unexplained extras: `missing file`, `file contents`, or `extra file`

A recorded reason is the code above, optionally followed by one parenthesized detail that narrows the cause - unsupported_zip_feature (zip64), header_mismatch (crc), invalid_path (trailing dot). The machine-readable code is always the first token; the detail is fixed text and never echoes archive bytes.

The cap mechanism is public contract; the cap values are configuration (VERIFY_RATIO_CAP, VERIFY_ABS_CAP_BYTES, VERIFY_MAX_ENTRIES, VERIFY_MAX_PATH_LEN, defaulting to 10x, 256 MiB, 10000 entries, and 256 bytes). Verifier failures leave revisions pending - fail-safe: broken verification infrastructure keeps content unexposed, never exposes it.

Name advisories. Before downloading anything, the workflow checks each version that would introduce a new package name against the package corpus: confusability under a skeleton fold (-/_ fold away, 1/i to l, 0 to o) against every existing package and scope, edit distance 1 on the folded full name against other scopes’ packages, and a short unambiguous-profanity list matched as folded substrings. A finding never rejects - the workflow abstains (no verdict; the version stays pending) and an operator reviews it, so a false positive costs a delay, never a rejection. Once any version of a package is verified, later versions skip the advisories; a rejection never vets a name. The rationale and rules live in registry/docs/architecture.md, “Name fidelity”.

Server checks versus client extraction

These server-side checks agree in spirit with the client’s extraction safety contract, and the two are deliberately independent. The client’s rules are the ones that must hold: cabin extracts archives from third-party registries and local file registries too, and must stay safe against a hosted registry that has itself been compromised. Nothing on the client trusts this verifier.

The verifier is at least as strict as the client on every axis they share. It inspects only archives cabin package produced, so it enforces the whole strict zip profile - rejecting the zip64, extra-field, data-descriptor, and non-contiguous-layout constructions the client’s extractor merely tolerates. It shares the client’s lexical path-portability predicate through cabin-fs, so the two reject the same Windows-hostile shapes (\, :, control characters, < > " | ? *, leading or trailing spaces, trailing dots, reserved device names) by construction rather than by parallel maintenance. It additionally rejects case-folded name collisions the client deliberately tolerates (they would refuse archives legitimate on case-sensitive Linux). Its default caps (10x ratio, 256 MiB, 10000 entries, 256-byte paths) sit at or below the client’s (32x ratio, 1 GiB, 10000 entries, 256-byte paths). A version that passes verification therefore clears the client’s extraction rules.

That the verifier is stricter does not fold the two into one. The caps above are configurable, so a registry operator cannot widen the client’s limits by widening their own - only the client’s constants do that. “Verified” therefore means the archive is safe to extract by the client’s own rules; it is never a promise the client may delegate its safety to a registry.

Yank

PATCH /api/v1/packages/<scope>/<name>/<version>/yank

Requires a token with the yank scope, on the same API origin as publish. The JSON body sets the version’s yanked state in the per-package index document:

{ "yanked": true }

{"yanked": false} un-yanks. The route is idempotent: setting the state a version already has succeeds with 200 and body {"ok":true}. Yank is version-level - it covers every packaging revision of the version at once, and there is no per-revision yank. It applies to versions with at least one verified revision - a version whose revisions are all pending or rejected was never part of the registry’s resolvable surface, so there is nothing to retract and it answers an authenticated 404.

Yanking from the client

cabin yank takes a strict <scope>/<name>@<version> spec - an exact scoped package name and an exact SemVer version, no ranges - and resolves the registry exactly like remote publish: --index-url, else the [registry] index-url setting in config.md - never the default registry; a mutation must not target a registry the user did not name. A local index-path is rejected, since yanked state lives in the remote registry’s index. The registry’s config.json must declare the api origin the request is sent to.

$ cabin -Z remote-registry yank fmtlib/fmt@10.2.1 --index-url https://registry.cabinpkg.com
fmtlib/fmt@10.2.1 is now yanked
$ cabin -Z remote-registry yank --undo fmtlib/fmt@10.2.1 --index-url https://registry.cabinpkg.com
fmtlib/fmt@10.2.1 is no longer yanked

The report states the resulting state. Because the route is idempotent, that wording also covers the no-op: yanking an already-yanked version succeeds and prints the same line. A 404 reports that the version is not published on this registry; 401 / 403 follow the token conventions of the read path.

What yanking means - matching the resolver behavior in package-index.md:

A yanked version is excluded from new resolution: cabin resolve skips it when picking candidates, and if every matching version is yanked, resolution fails.
Every revision’s artifact stays downloadable: existing lockfiles that already pin the yanked version keep building. Yanking never mutates or deletes an archive - published bytes stay immutable.
Unpublish / delete is deliberately not offered: removing bytes other projects may already depend on breaks reproducible builds, so the strongest retraction is the yank flag.

Status codes

Code	Meaning
`200`	Success without a state change: an idempotent no-op (byte-identical re-publish, or a yank set to the state the version already has).
`201`	Publish that created a packaging revision - a first publish of the version, an opted-in respin, or the revival of a rejected revision.
`400`	Malformed request: bad framing, invalid metadata, a version carrying build metadata, an invalid JSON body, or a `new-revision` query value other than `true`.
`401`	An invalid token, or a missing token on a surface that requires one - the mutation routes, and every non-read-plane path of the index host (never reveals whether anything exists there). Carries the login-URL challenge.
`403`	Valid token, but the scope the route requires is missing - or a per-user quota refusal, distinguished by the envelope’s `code` field.
`404`	Request for an unknown package, version, or revision - including revisions that are not verified, which are indistinguishable from unknown ones without the `verify` scope.
`409`	Publish of different bytes for a version with a live revision and no `new-revision` opt-in; a revision-id collision between two different archives; or a conflicting verdict.
`413`	The uploaded archive exceeds the per-archive size limit (envelope code `archive_too_large`).
`429`	A rate limit: the publish token bucket is empty (code `rate_limited`), or the caller’s daily allowance of registry-side archive reads is spent (code `read_rate_limited`). Carries `Retry-After` (seconds) saying when the limit resets.
`503`	The registry is protecting its own infrastructure budget (the hosted service blocks itself before provider limits or real spend are reached): its service-wide breaker tripped, or its per-request cost governor refused - or could not be reached - for the specific resource the request needed. Writes refuse first; archive downloads refuse when the registry’s read allowance for fresh storage reads is exhausted (recently downloaded archives can keep serving from the registry’s edge cache through that), or service-wide when the registry’s operator has paused reads outright. Carries `Retry-After` (seconds) and the envelope code `registry_over_budget`. The refusal is operator-side and temporary, so it is a `503` rather than a `402`: nothing the caller can pay clears it, and `503` has explicit `Retry-After` semantics where `402` has none.

Error envelope

Every non-2xx response carries the same JSON envelope:

{ "errors": [ { "detail": "authentication required" } ] }

Quota, rate-limit, and budget refusals additionally carry a machine-readable code field:

{ "errors": [ { "detail": "total package quota exhausted", "code": "quota_packages_total" } ] }

Clients must ignore unknown fields in the envelope; errors without a code stay exactly as before. The defined codes:

`code`	Status	Meaning
`rate_limited`	`429`	The publish token bucket is empty; `Retry-After` says when it refills.
`read_rate_limited`	`429`	The caller’s daily allowance of registry-side archive reads is spent; `Retry-After` reaches the next UTC day. Cached downloads are unaffected.
`archive_too_large`	`413`	The archive exceeds the per-archive size limit.
`quota_storage`	`403`	The publish would exceed the total stored-bytes quota.
`quota_packages_daily`	`403`	The daily new-package quota is exhausted.
`quota_packages_total`	`403`	The total package quota is exhausted.
`quota_versions_daily`	`403`	The daily per-package version quota is exhausted.
`registry_over_budget`	`503`	The registry’s budget protection refused the request: the service-wide breaker has the plane paused, or the per-request cost governor refused (or could not answer for) the specific resource the request needed; `Retry-After` covers the next re-evaluation.

Cabin maps these refusals to actionable messages. For the breaker it keys on the registry_over_budget code, not on the 503 alone - a 503 can also come from the hosting platform, and an outage must not be reported as a budget refusal; a 503 without the code stays a plain server error. A coded 503 on the mutation routes reports the registry as temporarily not accepting publishes (over its free budget), a coded 503 on the read routes reports package downloads and index reads as temporarily disabled to stay within the registry’s infrastructure budget, and the 429 reports the rate limit - each echoing Retry-After as a “try again in N seconds” hint when the header is usable; the 413 reports the archive as too large, appending the server’s detail; and a 403 whose code starts with quota_ surfaces the server’s detail verbatim - the detail itself embeds the registry’s usage-dashboard URL (https://cabinpkg.com/dashboard on the hosted registry), so the client never derives a web URL from the index origin. Unknown codes fall back to the plain detail string.