@crewhaus/tool-containers 0.7.0 → 0.8.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+CrewHaus Factory
+Copyright 2026 Max Meier
+
+This product includes software developed by Max Meier
+(operating as StudioMax — https://studiomax.io) and contributors.
+
+The CrewHaus name and logo are trademarks of Max Meier. See
+https://github.com/crewhaus/factory/blob/main/TRADEMARK.md for the
+use-of-marks policy.

package/dist/index.js

@@ -115,6 +115,7 @@ async function fetchConfig(client, ref, digest, mediaType) {
 }
 export const containerImageInspect = buildTool({
     name: "ContainerImageInspect",
+    operativeArgs: [{ field: "image", kind: "recipient" }],
     description: "Resolve a container image tag to the digest it points at right now, over the OCI registry API — no daemon, no pull, no Docker. Returns the manifest digest and media type, the per-platform digest when the tag is a multi-arch index, the layer sizes, and the image config's labels, entrypoint and created time. Use it to pin a deployment to a digest, or to read an image's labels without downloading it. Pass compareTo a digest you recorded earlier and the answer says, as a boolean, whether the tag still points at it. The digest is computed from the response bytes and checked against the registry's own header rather than copied from it, so a registry cannot tell this tool that bytes are something they are not. Anonymous pulls only: a private repository is refused, with an explanation, rather than guessed at.",
     inputSchema: z.object({
         image: z
@@ -332,6 +333,7 @@ platformMatches = 1) {
 }
 export const containerImageTags = buildTool({
     name: "ContainerImageTags",
+    operativeArgs: [{ field: "image", kind: "recipient" }],
     description: "List a container repository's tags over the OCI registry API, paged, filtered by glob and sorted newest-first by semver precedence — with tags that are not versions (latest, edge, sha-9f3c1a) kept and listed after them rather than dropped or guessed at. Use it to find the newest release of an image, to check whether a version was ever published, or to see what a repository offers before pinning to one. Set withDigests to resolve each listed tag to its digest, which costs one request per tag and is capped. Anonymous pulls only; a private repository is refused rather than reported as empty.",
     inputSchema: z.object({
         image: z

package/dist/lib/http.js

@@ -16,6 +16,7 @@
  * closes, and it closes it at EVERY hop, not just the first.
  */
 import { assertNotSsrf } from "@crewhaus/tool-fetch";
+import { fetchRaw, readResponseBounded } from "@crewhaus/tool-safety/streams";
 export class RegistryHttpError extends Error {
     name = "RegistryHttpError";
 }
@@ -32,8 +33,15 @@ function pinnedFetch(req, pinnedIp) {
     const original = new URL(req.url);
     const host = original.hostname;
     const unbracketed = host.replace(/^\[/, "").replace(/\]$/, "");
+    // Both branches keep the body RAW (`fetchRaw`, Bun's `decompress: false`):
+    // otherwise Bun inflates a gzip, deflate, br or zstd body in native code
+    // before any reader sees a byte, and a 260 KB gzip of zeros from a
+    // registry (or the object store it redirects to) cost about 1 GB of RSS
+    // before `maxBytes` fired (C093). `readCapped` decodes it, under the cap,
+    // into the same bytes the runtime's decoder gave: a digest is still over
+    // the representation the registry sent.
     if (pinnedIp === "" || unbracketed === pinnedIp)
-        return globalThis.fetch(req);
+        return fetchRaw(req);
     const pinnedUrl = new URL(original.toString());
     pinnedUrl.hostname = pinnedIp.includes(":") ? `[${pinnedIp}]` : pinnedIp;
     const headers = new Headers(req.headers);
@@ -45,7 +53,7 @@ function pinnedFetch(req, pinnedIp) {
         signal: req.signal,
         tls: { serverName: host },
     };
-    return globalThis.fetch(pinnedUrl.toString(), init);
+    return fetchRaw(pinnedUrl.toString(), init);
 }
 let rawFetch = pinnedFetch;
 /** Test seam — `_setFetch(undefined)` restores the production dialer. */
@@ -102,57 +110,43 @@ export async function httpGet(url, options) {
             current = next;
             continue;
         }
-        const bytes = await readCapped(res, options.maxBytes);
+        const bytes = await readCapped(res, options.maxBytes, options.signal);
         return { status: res.status, headers: res.headers, bytes, url: current.toString() };
     }
     throw new RegistryHttpError(`registry redirected more than ${MAX_REDIRECTS} times`);
 }
 /**
- * Drain a body with a hard byte cap, aborting the read once it is exceeded so a
- * hostile or misconfigured registry cannot pin memory. Concatenation happens
- * once at the end, over the exact chunks that arrived.
+ * Drain a body with a hard cap on its DECODED size, so a hostile or
+ * misconfigured registry cannot pin memory: the body arrives raw (see
+ * `pinnedFetch`), a gzip, deflate, br or zstd body is decoded here in small
+ * steps, and the decoder stops at the cap. The bytes returned are exactly
+ * the decoded body; a body past the cap, or one that cannot be decoded, is
+ * refused.
  */
-async function readCapped(res, maxBytes) {
-    if (res.body === null)
-        return new Uint8Array(0);
-    const reader = res.body.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            if (value === undefined)
-                continue;
-            total += value.byteLength;
-            if (total > maxBytes) {
-                try {
-                    await reader.cancel();
-                }
-                catch {
-                    // Already aborting.
-                }
-                throw new RegistryHttpError(`response body exceeded ${maxBytes} bytes — aborted before reading it all`);
-            }
-            chunks.push(value);
-        }
-    }
-    finally {
-        try {
-            reader.releaseLock();
-        }
-        catch {
-            // The stream may already be released; nothing to do.
-        }
+async function readCapped(res, maxBytes, signal) {
+    const read = await readResponseBounded(res, {
+        maxBytes,
+        ...(signal !== undefined ? { signal } : {}),
+    });
+    if (read.ok) {
+        if (!read.truncated)
+            return read.bytes;
+        throw new RegistryHttpError(`response body exceeded ${maxBytes} bytes — aborted before reading it all`);
     }
-    const merged = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        merged.set(chunk, offset);
-        offset += chunk.byteLength;
+    switch (read.code) {
+        case "aborted":
+        case "stalled":
+            // As the runtime reports an abort mid-body, so the caller's timeout
+            // and cancellation handling sees the same thing it always did.
+            throw signal?.reason ?? new RegistryHttpError("the read was aborted before the body ended");
+        case "unsupported-encoding":
+            throw new RegistryHttpError(`the registry sent a body in a stack of content-encodings this tool cannot decode within its ${maxBytes}-byte cap`);
+        case "decode-error":
+        case "auto-decompressed":
+            throw new RegistryHttpError("the registry sent a body labelled as compressed that could not be decoded");
+        default:
+            throw new RegistryHttpError("the registry closed the connection before the body ended");
     }
-    return merged;
 }
 /**
  * A signal that aborts on the caller's cancellation OR after `timeoutMs`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-containers",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "Deterministic OCI registry reads: resolve an image tag to its digest and list tags, with no daemon and no pull",
   "main": "dist/index.js",
@@ -8,17 +8,19 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.7.0",
-    "@crewhaus/tool-builder": "0.7.0",
-    "@crewhaus/tool-catalog": "0.7.0",
-    "@crewhaus/tool-fetch": "0.7.0",
+    "@crewhaus/errors": "0.8.1",
+    "@crewhaus/tool-builder": "0.8.1",
+    "@crewhaus/tool-catalog": "0.8.1",
+    "@crewhaus/tool-fetch": "0.8.1",
+    "@crewhaus/tool-safety": "0.8.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -42,5 +44,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
 }

package/dist/fixtures.d.ts

@@ -1,93 +0,0 @@
-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

@@ -1,244 +0,0 @@
-/**
- * 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" },
-        },
-    };
-}