@crewhaus/tool-containers 0.7.0

package/README.md

@@ -0,0 +1,136 @@
+# @crewhaus/tool-containers
+
+What is actually behind this image tag.
+
+| Tool | Answers |
+|---|---|
+| `ContainerImageInspect` | which digest does this tag resolve to, and what is inside it |
+| `ContainerImageTags` | what versions of this image exist |
+
+Both talk to the OCI distribution API directly. No daemon, no `docker pull`, no
+layers downloaded, nothing written to disk — resolving a tag to a digest costs
+one or two small GETs, and the image config blob (labels, entrypoint, created
+time) costs one more.
+
+## The digest is computed, not believed
+
+A manifest's digest is `sha256` over the exact bytes the registry sent. That
+makes it fragile in a specific way: parse the JSON and serialize it again — a
+different key order, two spaces instead of three, a literal `é` where the
+registry wrote `é` — and the hash is a different number that still looks
+exactly like a digest. Every image you "pinned" then matches nothing, and "this
+is the image we tested" is false while reading as true.
+
+So the bytes are held as bytes from the socket to the hash. Nothing on the
+digest path is parsed before it is hashed, and nothing is ever re-serialized.
+The registry's `Docker-Content-Digest` header is **checked against the computed
+digest, never copied from it**, and the result reports both whether a header was
+present and whether it agreed. When you ask for `…@sha256:abc`, or when a
+multi-arch index promises a per-platform digest, the bytes that come back are
+verified against that promise too, and a mismatch is a refusal rather than a
+field in the output.
+
+## Multi-arch is two answers, so it returns two
+
+A tag on a modern image is usually an **index**, not an image: one digest
+covering several per-platform manifests. Both digests are real and they are used
+for different things, so both are reported — `resolved` is what the tag points
+at, `manifest` is the single-platform image inside it (`linux/amd64` by default,
+`platform` to choose, `indexOnly` to stop at the index).
+
+Buildkit also writes provenance and SBOM manifests into the index with the
+platform `unknown/unknown`. Those are counted as `attestations` and are never
+selectable — picking one and reporting it as the image is the classic multi-arch
+bug.
+
+Two more things the platform string alone does not settle. Asking for
+`linux/arm64` gets the **variant-less** entry when the index has one, whatever
+order the index lists it in, because that is the image a plain arm64 host would
+pull. And `windows/amd64` is usually several images that differ only in
+`os.version`; when more than one entry matches, the chosen one's `osVersion` and
+a `platformMatches` count travel with the answer, because a digest picked
+blindly out of that set will not run.
+
+## The auth dance, from the challenge
+
+Public images need a token: the registry answers 401 with a
+`WWW-Authenticate: Bearer realm=…,service=…` challenge, the client fetches a
+token from that realm and retries. This is driven entirely off the challenge, so
+Docker Hub, ghcr.io and quay.io all work without appearing in the code — and so
+does the registry nobody here has tried yet. The one registry-specific rule is a
+naming one: `alpine` means `registry-1.docker.io/v2/library/alpine`.
+
+The challenge is data from a server, so it is treated as such. The realm must be
+an absolute `https` URL with no credentials in it, and the scope requested is
+**ours** — a challenge asking us to request `repository:someone/else:push` gets
+a pull scope for the repository the caller actually named.
+
+## What it refuses
+
+A tool that cannot say no is not finished. These say no, with the reason:
+
+- **a digest that does not match its content** — from the header, from the
+  reference, or from an index descriptor;
+- **a private repository** — after an anonymous token has been tried, reported
+  as private rather than as missing, because no retry fixes it;
+- **a registry offering only Basic auth**, naming what it offered;
+- **a schema 1 manifest**, whose digest covers a JWS signature rather than the
+  image content;
+- **a platform the index does not have**, listing the ones it does;
+- **a redirect or an auth realm pointing into the private network** — the SSRF
+  guard from `@crewhaus/tool-fetch` runs on every hop, with the connection
+  pinned to the IP it validated, so a registry cannot answer a manifest request
+  with `302 Location: http://169.254.169.254/…`;
+- **paging that leaves the registry's origin**, because a `Link` header is
+  server-controlled and the alternative is being walked onto another host;
+- **`withDigests` over its fan-out cap**, with the instruction to narrow, rather
+  than quietly crawling somebody's registry;
+- **a reference that is neither a tag nor a digest**, checked at the one place a
+  string becomes a URL path. A tag list is server-controlled data, and
+  `https://reg/v2/owner/app/manifests/` + `../../victim/manifests/latest`
+  normalises to a different repository — whose digest would then be reported as
+  this one's. Entries outside the tag grammar are dropped from a tag list and
+  counted as `malformed` rather than carried; a registry host with a port above
+  65535 is refused by name instead of by a URL parser.
+
+A pull token is also dropped the moment a redirect leaves the origin it was
+minted for. Registries redirect to CDNs and object stores; forwarding the token
+hands it to whoever runs them.
+
+## Tag lists are not semver, and are sorted anyway
+
+A real repository holds `latest`, `edge`, `sha-9f3c1a`, `0.6` and `v1.0.0-rc.1`
+side by side. The default sort partitions: versions first by semver precedence,
+newest first, then everything else in lexicographic order. No *tag* is dropped
+and nothing throws — an unparseable version is still a tag, not an error.
+`1.0.0-alpha.10` sorts above `1.0.0-alpha.2`, because those identifiers are
+numbers.
+
+`match` is a glob over tag names with `*` and `?`. It is matched with a
+two-pointer scan rather than a compiled regex: `*` as `[^]*` makes
+`*a*a*a*a*a*a*a*a*z` cost C(n, 8) backtracks against an n-character tag, which
+for a full-length 128-character tag is hours of CPU inside one synchronous
+`RegExp.test` — where neither `timeoutMs` nor a cancellation signal can reach
+it, since both only take effect between awaits.
+
+`withDigests` resolves each returned tag with a GET and verifies it, rather than
+a HEAD: a `HEAD` gives you the registry's claim about a digest and no bytes to
+check it against, which is the one thing this package will not report. The limit
+is applied before the fan-out, never after.
+
+## What it does not do
+
+- **It does not pull.** Layers are never fetched; only the manifest and, on
+  request, the image config blob.
+- **It does not authenticate.** Anonymous flow only — no credentials are read,
+  stored or sent, and a private repository is refused.
+- **It does not echo environment values.** A config blob is where a careless
+  build leaves a token, so `envNames` lists the names and drops the values.
+- **It does not sort by creation time.** That would cost a manifest plus a
+  config blob per tag to order a list, and the answer would still be the time a
+  config was built rather than the time a tag was pushed.
+- **It does not invent a total.** `totalLayerSize` sums the layer descriptors
+  that carried a `size`; when any did not, `unsizedLayers` says how many, so the
+  number is read as the floor it is.
+- **It does not cache.** The token lives in the call that earned it and dies
+  with it; a second call asks the registry again and gets today's answer.

package/dist/fixtures.d.ts

@@ -0,0 +1,93 @@
+import type { RegistryFetch } from "./lib/http";
+export declare const bytesOf: (text: string) => Uint8Array;
+export declare const sha256Of: (text: string) => string;
+/**
+ * An image config blob. `APP_TOKEN` is here on purpose: it is the shape of the
+ * accident this package must not amplify, and the test asserts the value never
+ * reaches the output.
+ */
+export declare const CONFIG_JSON = "{\"architecture\":\"amd64\",\"os\":\"linux\",\"created\":\"2026-04-02T10:11:12.13Z\",\n   \"config\":{\"User\":\"app\",\"WorkingDir\":\"/srv\",\"Entrypoint\":[\"/bin/app\"],\"Cmd\":[\"--serve\"],\n      \"Env\":[\"PATH=/usr/local/bin:/usr/bin\",\"APP_TOKEN=s3cr3t-do-not-echo\"],\n      \"ExposedPorts\":{\"8080/tcp\":{}},\n      \"Labels\":{\"org.opencontainers.image.title\":\"caf\\u00e9-runner\",\"org.opencontainers.image.version\":\"1.4.2\"}},\n   \"rootfs\":{\"type\":\"layers\",\"diff_ids\":[\"sha256:1111111111111111111111111111111111111111111111111111111111111111\",\"sha256:2222222222222222222222222222222222222222222222222222222222222222\"]}}";
+export declare const CONFIG_DIGEST: string;
+/** An OCI image manifest, amd64. Note the indentation and the escaped é. */
+export declare const OCI_AMD64_JSON: string;
+export declare const OCI_AMD64_DIGEST: string;
+/** The same image for arm64/v8, with no annotations. */
+export declare const OCI_ARM64_JSON: string;
+export declare const OCI_ARM64_DIGEST: string;
+/**
+ * A multi-arch index with a buildkit attestation entry — the `unknown/unknown`
+ * descriptor that a naive "first manifest wins" resolver picks and then reports
+ * a provenance document as if it were the image.
+ */
+export declare const OCI_INDEX_JSON: string;
+export declare const OCI_INDEX_DIGEST: string;
+/** Docker's own manifest list + v2 manifest, which Hub still serves for older images. */
+export declare const DOCKER_AMD64_JSON: string;
+export declare const DOCKER_AMD64_DIGEST: string;
+export declare const DOCKER_LIST_JSON: string;
+export declare const DOCKER_LIST_DIGEST: string;
+/** A schema 1 manifest — digest over a signature envelope, which is why it is refused. */
+export declare const SCHEMA1_JSON = "{\"schemaVersion\":1,\"name\":\"library/ancient\",\"tag\":\"1.0\",\"architecture\":\"amd64\",\"fsLayers\":[{\"blobSum\":\"sha256:8888888888888888888888888888888888888888888888888888888888888888\"}],\"signatures\":[{\"header\":{\"alg\":\"ES256\"},\"signature\":\"abc\",\"protected\":\"def\"}]}";
+/** An OCI artifact: image-manifest shaped, but its config is a Helm chart. */
+export declare const HELM_MANIFEST_JSON = "{\"schemaVersion\":2,\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"config\":{\"mediaType\":\"application/vnd.cncf.helm.config.v1+json\",\"size\":141,\"digest\":\"sha256:9999999999999999999999999999999999999999999999999999999999999999\"},\"layers\":[{\"mediaType\":\"application/vnd.cncf.helm.chart.content.v1.tar+gzip\",\"size\":4096,\"digest\":\"sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999\"}]}";
+export type RegistryFixture = {
+    /** The host the client talks to — Hub's is not `docker.io`. */
+    readonly apiHost: string;
+    /** Exactly what the registry puts on the 401. */
+    readonly challenge: (repository: string) => string;
+    readonly tokenUrl: string;
+    readonly token: string;
+    readonly tokenBody: string;
+};
+export declare const DOCKER_HUB: RegistryFixture;
+export declare const GHCR: RegistryFixture;
+export declare const QUAY: RegistryFixture;
+export type RecordedCall = {
+    readonly url: string;
+    readonly method: string;
+    readonly authorization: string | null;
+    readonly accept: string | null;
+    readonly pinnedIp: string;
+};
+export type StubRoute = {
+    /** Exact URL, or a predicate over the parsed URL. */
+    readonly match: string | ((url: URL) => boolean);
+    readonly respond: (req: Request, url: URL) => Response;
+};
+export type Stub = {
+    readonly fetch: RegistryFetch;
+    readonly calls: RecordedCall[];
+};
+/** Build a fetch from an ordered route table. First match wins; no match is a 404. */
+export declare function stubFetch(routes: readonly StubRoute[]): Stub;
+export declare function jsonResponse(status: number, body: string, headers?: Record<string, string>): Response;
+export type Served = {
+    readonly body: string;
+    readonly mediaType: string;
+    /**
+     * What to put in `Docker-Content-Digest`. Omitted ⇒ the true digest of the
+     * bytes; `null` ⇒ no header at all, which some proxies do.
+     */
+    readonly contentDigest?: string | null;
+};
+export type TagPage = {
+    readonly body: string;
+    readonly nextLast?: string;
+    readonly link?: string;
+};
+export type RepoContent = {
+    /** Keyed by reference: a tag, or a `sha256:…` digest. */
+    readonly manifests?: Record<string, Served>;
+    readonly blobs?: Record<string, Served>;
+    /** Pages in order; page 0 is the request with no `last` parameter. */
+    readonly tagPages?: readonly TagPage[];
+};
+/**
+ * Serve one repository from one registry fixture, including the 401 → token →
+ * retry dance. Requests without a bearer token get the registry's own
+ * challenge, which is what makes these tests exercise the real flow rather than
+ * a happy path with the auth step removed.
+ */
+export declare function registryStub(fixture: RegistryFixture, repository: string, content: RepoContent, extraRoutes?: readonly StubRoute[]): Stub;
+/** The standard multi-arch repository, served by whichever registry is passed. */
+export declare function multiArchContent(): RepoContent;

package/dist/fixtures.js

@@ -0,0 +1,244 @@
+/**
+ * Recorded registry shapes, and a fetch stub that serves them.
+ *
+ * These are the three registries this package is meant to work against —
+ * Docker Hub, ghcr.io and quay.io — reduced to what actually differs between
+ * them: the challenge header, the realm host, whether a service and a scope are
+ * echoed, and whether anything else shares the `WWW-Authenticate` line. If the
+ * generic challenge-driven flow handles these three it handles the fourth one
+ * nobody has tried yet, which is the entire argument for not special-casing
+ * Docker Hub.
+ *
+ * The manifest bytes are deliberately UGLY: three-space indentation, keys in
+ * the order a builder emitted them rather than sorted, and a `é` escape
+ * instead of a literal é. `JSON.stringify(JSON.parse(bytes))` produces
+ * different bytes for every one of them, which is the property the digest tests
+ * need — a reserializing implementation passes a fixture whose formatting is
+ * already canonical and fails in production.
+ */
+import { createHash } from "node:crypto";
+const encoder = new TextEncoder();
+export const bytesOf = (text) => encoder.encode(text);
+export const sha256Of = (text) => `sha256:${createHash("sha256").update(encoder.encode(text)).digest("hex")}`;
+// ─── documents ──────────────────────────────────────────────────────────────
+/**
+ * An image config blob. `APP_TOKEN` is here on purpose: it is the shape of the
+ * accident this package must not amplify, and the test asserts the value never
+ * reaches the output.
+ */
+export const CONFIG_JSON = `{"architecture":"amd64","os":"linux","created":"2026-04-02T10:11:12.13Z",
+   "config":{"User":"app","WorkingDir":"/srv","Entrypoint":["/bin/app"],"Cmd":["--serve"],
+      "Env":["PATH=/usr/local/bin:/usr/bin","APP_TOKEN=s3cr3t-do-not-echo"],
+      "ExposedPorts":{"8080/tcp":{}},
+      "Labels":{"org.opencontainers.image.title":"caf\\u00e9-runner","org.opencontainers.image.version":"1.4.2"}},
+   "rootfs":{"type":"layers","diff_ids":["sha256:1111111111111111111111111111111111111111111111111111111111111111","sha256:2222222222222222222222222222222222222222222222222222222222222222"]}}`;
+export const CONFIG_DIGEST = sha256Of(CONFIG_JSON);
+/** An OCI image manifest, amd64. Note the indentation and the escaped é. */
+export const OCI_AMD64_JSON = `{ "schemaVersion": 2,
+   "mediaType": "application/vnd.oci.image.manifest.v1+json",
+   "config": {
+      "mediaType": "application/vnd.oci.image.config.v1+json",
+      "size": ${CONFIG_JSON.length},
+      "digest": "${CONFIG_DIGEST}"
+   },
+   "layers": [
+      { "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", "size": 3401687,
+        "digest": "sha256:3333333333333333333333333333333333333333333333333333333333333333" },
+      { "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", "size": 128,
+        "digest": "sha256:4444444444444444444444444444444444444444444444444444444444444444" }
+   ],
+   "annotations": { "org.opencontainers.image.title": "caf\\u00e9-runner",
+      "org.opencontainers.image.revision": "9f3c1ad" }
+}`;
+export const OCI_AMD64_DIGEST = sha256Of(OCI_AMD64_JSON);
+/** The same image for arm64/v8, with no annotations. */
+export const OCI_ARM64_JSON = `{ "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json",
+   "config": { "mediaType": "application/vnd.oci.image.config.v1+json", "size": ${CONFIG_JSON.length}, "digest": "${CONFIG_DIGEST}" },
+   "layers": [ { "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", "size": 3211987,
+        "digest": "sha256:5555555555555555555555555555555555555555555555555555555555555555" } ]
+}`;
+export const OCI_ARM64_DIGEST = sha256Of(OCI_ARM64_JSON);
+/**
+ * A multi-arch index with a buildkit attestation entry — the `unknown/unknown`
+ * descriptor that a naive "first manifest wins" resolver picks and then reports
+ * a provenance document as if it were the image.
+ */
+export const OCI_INDEX_JSON = `{ "schemaVersion": 2,
+   "mediaType": "application/vnd.oci.image.index.v1+json",
+   "manifests": [
+      { "mediaType": "application/vnd.oci.image.manifest.v1+json", "size": ${OCI_AMD64_JSON.length},
+        "digest": "${OCI_AMD64_DIGEST}",
+        "platform": { "architecture": "amd64", "os": "linux" } },
+      { "mediaType": "application/vnd.oci.image.manifest.v1+json", "size": ${OCI_ARM64_JSON.length},
+        "digest": "${OCI_ARM64_DIGEST}",
+        "platform": { "architecture": "arm64", "os": "linux", "variant": "v8" } },
+      { "mediaType": "application/vnd.oci.image.manifest.v1+json", "size": 566,
+        "digest": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+        "platform": { "architecture": "unknown", "os": "unknown" },
+        "annotations": { "vnd.docker.reference.type": "attestation-manifest" } }
+   ]
+}`;
+export const OCI_INDEX_DIGEST = sha256Of(OCI_INDEX_JSON);
+/** Docker's own manifest list + v2 manifest, which Hub still serves for older images. */
+export const DOCKER_AMD64_JSON = `{"schemaVersion":2,"mediaType":"application/vnd.docker.distribution.manifest.v2+json","config":{"mediaType":"application/vnd.docker.container.image.v1+json","size":${CONFIG_JSON.length},"digest":"${CONFIG_DIGEST}"},"layers":[{"mediaType":"application/vnd.docker.image.rootfs.diff.tar.gzip","size":3401687,"digest":"sha256:7777777777777777777777777777777777777777777777777777777777777777"}]}`;
+export const DOCKER_AMD64_DIGEST = sha256Of(DOCKER_AMD64_JSON);
+export const DOCKER_LIST_JSON = `{"schemaVersion":2,"mediaType":"application/vnd.docker.distribution.manifest.list.v2+json","manifests":[{"mediaType":"application/vnd.docker.distribution.manifest.v2+json","size":${DOCKER_AMD64_JSON.length},"digest":"${DOCKER_AMD64_DIGEST}","platform":{"architecture":"amd64","os":"linux"}}]}`;
+export const DOCKER_LIST_DIGEST = sha256Of(DOCKER_LIST_JSON);
+/** A schema 1 manifest — digest over a signature envelope, which is why it is refused. */
+export const SCHEMA1_JSON = `{"schemaVersion":1,"name":"library/ancient","tag":"1.0","architecture":"amd64","fsLayers":[{"blobSum":"sha256:8888888888888888888888888888888888888888888888888888888888888888"}],"signatures":[{"header":{"alg":"ES256"},"signature":"abc","protected":"def"}]}`;
+/** An OCI artifact: image-manifest shaped, but its config is a Helm chart. */
+export const HELM_MANIFEST_JSON = `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","config":{"mediaType":"application/vnd.cncf.helm.config.v1+json","size":141,"digest":"sha256:9999999999999999999999999999999999999999999999999999999999999999"},"layers":[{"mediaType":"application/vnd.cncf.helm.chart.content.v1.tar+gzip","size":4096,"digest":"sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999"}]}`;
+export const DOCKER_HUB = {
+    apiHost: "registry-1.docker.io",
+    // Hub omits the scope on the /v2/ probe and includes it on a manifest 401.
+    challenge: (repository) => `Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:${repository}:pull"`,
+    tokenUrl: "https://auth.docker.io/token",
+    token: "hub-token",
+    tokenBody: `{"token":"hub-token","access_token":"hub-token","expires_in":300,"issued_at":"2026-09-18T09:00:00.000000000Z"}`,
+};
+export const GHCR = {
+    apiHost: "ghcr.io",
+    challenge: (repository) => `Bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:${repository}:pull"`,
+    tokenUrl: "https://ghcr.io/token",
+    token: "ghcr-token",
+    tokenBody: `{"token":"ghcr-token"}`,
+};
+export const QUAY = {
+    apiHost: "quay.io",
+    // quay has shipped two challenges on one line; the Bearer one is second.
+    challenge: (repository) => `Basic realm="quay.io", Bearer realm="https://quay.io/v2/auth",service="quay.io",scope="repository:${repository}:pull"`,
+    tokenUrl: "https://quay.io/v2/auth",
+    token: "quay-token",
+    tokenBody: `{"token":"quay-token","expires_in":600,"issued_at":"2026-09-18T09:00:00Z"}`,
+};
+/** Build a fetch from an ordered route table. First match wins; no match is a 404. */
+export function stubFetch(routes) {
+    const calls = [];
+    const fetch = async (req, pinnedIp) => {
+        const url = new URL(req.url);
+        calls.push({
+            url: req.url,
+            method: req.method,
+            authorization: req.headers.get("authorization"),
+            accept: req.headers.get("accept"),
+            pinnedIp,
+        });
+        for (const route of routes) {
+            const hit = typeof route.match === "string" ? req.url === route.match : route.match(url);
+            if (hit)
+                return route.respond(req, url);
+        }
+        return jsonResponse(404, `{"errors":[{"code":"NOT_FOUND","message":"no stub route for ${url.pathname}"}]}`);
+    };
+    return { fetch, calls };
+}
+export function jsonResponse(status, body, headers = {}) {
+    return new Response(bytesOf(body), {
+        status,
+        headers: { "content-type": "application/json", ...headers },
+    });
+}
+/**
+ * Serve one repository from one registry fixture, including the 401 → token →
+ * retry dance. Requests without a bearer token get the registry's own
+ * challenge, which is what makes these tests exercise the real flow rather than
+ * a happy path with the auth step removed.
+ */
+export function registryStub(fixture, repository, content, extraRoutes = []) {
+    const base = `https://${fixture.apiHost}/v2/${repository}`;
+    const authorized = (req) => req.headers.get("authorization") === `Bearer ${fixture.token}`;
+    const unauthorized = () => jsonResponse(401, `{"errors":[{"code":"UNAUTHORIZED","message":"authentication required"}]}`, {
+        "www-authenticate": fixture.challenge(repository),
+    });
+    const serve = (served) => {
+        const headers = { "content-type": served.mediaType };
+        const digest = served.contentDigest === undefined ? sha256Of(served.body) : served.contentDigest;
+        if (digest !== null)
+            headers["docker-content-digest"] = digest;
+        return new Response(bytesOf(served.body), { status: 200, headers });
+    };
+    const routes = [
+        // Overrides first: a test that wants one path to redirect or fail says so
+        // without having to restate the rest of the registry.
+        ...extraRoutes,
+        {
+            match: (url) => `${url.origin}${url.pathname}` === fixture.tokenUrl,
+            respond: () => jsonResponse(200, fixture.tokenBody),
+        },
+        {
+            match: (url) => `${url.origin}${url.pathname}`.startsWith(`${base}/manifests/`),
+            respond: (req, url) => {
+                if (!authorized(req))
+                    return unauthorized();
+                const reference = decodeURIComponent(url.pathname.split("/manifests/")[1] ?? "");
+                const served = content.manifests?.[reference];
+                if (served === undefined) {
+                    return jsonResponse(404, `{"errors":[{"code":"MANIFEST_UNKNOWN","message":"manifest unknown: ${reference}"}]}`);
+                }
+                return serve(served);
+            },
+        },
+        {
+            match: (url) => `${url.origin}${url.pathname}`.startsWith(`${base}/blobs/`),
+            respond: (req, url) => {
+                if (!authorized(req))
+                    return unauthorized();
+                const digest = url.pathname.split("/blobs/")[1] ?? "";
+                const served = content.blobs?.[digest];
+                if (served === undefined) {
+                    return jsonResponse(404, `{"errors":[{"code":"BLOB_UNKNOWN","message":"blob unknown"}]}`);
+                }
+                return serve(served);
+            },
+        },
+        {
+            match: (url) => `${url.origin}${url.pathname}` === `${base}/tags/list`,
+            respond: (req, url) => {
+                if (!authorized(req))
+                    return unauthorized();
+                const pages = content.tagPages ?? [];
+                const last = url.searchParams.get("last");
+                const index = last === null ? 0 : pages.findIndex((p) => p.nextLast === last) + 1;
+                const page = pages[index];
+                if (page === undefined)
+                    return jsonResponse(404, `{"errors":[{"code":"NOT_FOUND"}]}`);
+                const headers = {};
+                const n = url.searchParams.get("n") ?? "100";
+                // Registries send a RELATIVE next link; resolving it against the page
+                // URL is part of what the client has to get right.
+                const link = page.link ??
+                    (page.nextLast === undefined
+                        ? undefined
+                        : `</v2/${repository}/tags/list?n=${n}&last=${page.nextLast}>; rel="next"`);
+                if (link !== undefined)
+                    headers["link"] = link;
+                return jsonResponse(200, page.body, headers);
+            },
+        },
+    ];
+    return stubFetch(routes);
+}
+/** The standard multi-arch repository, served by whichever registry is passed. */
+export function multiArchContent() {
+    return {
+        manifests: {
+            "1.4.2": { body: OCI_INDEX_JSON, mediaType: "application/vnd.oci.image.index.v1+json" },
+            latest: { body: OCI_INDEX_JSON, mediaType: "application/vnd.oci.image.index.v1+json" },
+            [OCI_INDEX_DIGEST]: {
+                body: OCI_INDEX_JSON,
+                mediaType: "application/vnd.oci.image.index.v1+json",
+            },
+            [OCI_AMD64_DIGEST]: {
+                body: OCI_AMD64_JSON,
+                mediaType: "application/vnd.oci.image.manifest.v1+json",
+            },
+            [OCI_ARM64_DIGEST]: {
+                body: OCI_ARM64_JSON,
+                mediaType: "application/vnd.oci.image.manifest.v1+json",
+            },
+        },
+        blobs: {
+            [CONFIG_DIGEST]: { body: CONFIG_JSON, mediaType: "application/vnd.oci.image.config.v1+json" },
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { ManifestError } from "./lib/manifest";
+export { _setFetch, type RegistryFetch } from "./lib/http";
+export { RegistryError } from "./lib/registry";
+export { ImageRefError } from "./lib/ref";
+export { ManifestError };
+export declare const containerImageInspect: RegisteredTool;
+export declare const containerImageTags: RegisteredTool;
+/** Every tool this package registers, in the order a catalog should list them. */
+export declare const CONTAINER_TOOLS: ReadonlyArray<RegisteredTool>;