@crewhaus/tool-containers 0.7.0

package/dist/lib/challenge.js

@@ -0,0 +1,174 @@
+/**
+ * The anonymous auth dance, parsed generically.
+ *
+ * A registry answers an unauthenticated manifest request with 401 and a
+ * `WWW-Authenticate: Bearer realm="…",service="…",scope="…"` challenge. The
+ * client fetches a token from the realm and retries. Docker Hub, ghcr.io and
+ * quay.io all differ in the realm host, the service name and whether they echo
+ * a scope — which is precisely why this is driven off the challenge instead of
+ * a table of registries. A registry we have never heard of works for free; a
+ * table would have to be edited every time one appeared.
+ *
+ * The challenge is data from the server, so it is treated as hostile:
+ * the realm must be an absolute https URL with no credentials in it, and the
+ * SCOPE WE ASK FOR IS OUR OWN — a challenge that asks us to request
+ * `repository:someone/else:push` gets our `repository:<what we asked for>:pull`
+ * instead.
+ */
+export class AuthChallengeError extends Error {
+    name = "AuthChallengeError";
+}
+/** RFC 7230 token characters — what an unquoted scheme or auth-param name is made of. */
+const TOKEN_CHARS = /[A-Za-z0-9!#$%&'*+\-.^_`|~]/;
+/**
+ * Parse a `WWW-Authenticate` header into its challenges.
+ *
+ * The grammar is genuinely ambiguous — `,` separates auth-params AND
+ * challenges — so this resolves it the way every HTTP client does: a bare
+ * token that is NOT followed by `=` starts the next challenge. That is what
+ * makes `Basic realm="x", Bearer realm="y"` (quay.io has shipped this shape)
+ * parse as two challenges rather than one Basic with a junk param.
+ */
+export function parseAuthenticateHeader(header) {
+    const challenges = [];
+    let i = 0;
+    const n = header.length;
+    const skipSeparators = () => {
+        while (i < n && (header[i] === " " || header[i] === "\t" || header[i] === ","))
+            i++;
+    };
+    const readToken = () => {
+        const start = i;
+        while (i < n && TOKEN_CHARS.test(header[i]))
+            i++;
+        return header.slice(start, i);
+    };
+    const skipSpace = () => {
+        while (i < n && (header[i] === " " || header[i] === "\t"))
+            i++;
+    };
+    const readValue = () => {
+        if (header[i] === '"') {
+            i++;
+            let out = "";
+            while (i < n) {
+                const ch = header[i];
+                // A quoted-pair escapes the next character verbatim; without this a
+                // realm containing an escaped quote truncates the URL.
+                if (ch === "\\" && i + 1 < n) {
+                    out += header[i + 1];
+                    i += 2;
+                    continue;
+                }
+                if (ch === '"') {
+                    i++;
+                    return out;
+                }
+                out += ch;
+                i++;
+            }
+            throw new AuthChallengeError(`unterminated quoted value in WWW-Authenticate: ${header}`);
+        }
+        return readToken();
+    };
+    while (i < n) {
+        skipSeparators();
+        if (i >= n)
+            break;
+        const scheme = readToken();
+        if (scheme === "") {
+            // Nothing token-shaped here: the header is malformed past this point.
+            break;
+        }
+        const params = {};
+        while (true) {
+            const save = i;
+            skipSeparators();
+            if (i >= n)
+                break;
+            const name = readToken();
+            if (name === "") {
+                i = save;
+                break;
+            }
+            skipSpace();
+            if (header[i] !== "=") {
+                // A bare token — this is the next challenge's scheme, not our param.
+                i = save;
+                break;
+            }
+            i++; // consume "="
+            skipSpace();
+            params[name.toLowerCase()] = readValue();
+        }
+        challenges.push({ scheme, params });
+        // Guard against a pathological header pinning the loop at one position.
+        const before = i;
+        skipSeparators();
+        if (i === before && i < n && !TOKEN_CHARS.test(header[i]))
+            i++;
+    }
+    return challenges;
+}
+/** The Bearer challenge, if the server offered one. Scheme match is case-insensitive. */
+export function bearerChallenge(challenges) {
+    return challenges.find((c) => c.scheme.toLowerCase() === "bearer");
+}
+/**
+ * Build the token request URL from a challenge.
+ *
+ * `scope` is ours, not the challenge's. `service` is taken from the challenge
+ * because registries genuinely differ (`registry.docker.io` vs `ghcr.io`) and
+ * some reject a token request without it — but it is only ever a query
+ * parameter, so the worst a hostile value can do is get its own token refused.
+ */
+export function tokenRequestUrl(challenge, scope) {
+    const realm = challenge.params["realm"];
+    if (realm === undefined || realm === "") {
+        throw new AuthChallengeError("registry asked for Bearer auth but the challenge has no realm — nothing to fetch a token from");
+    }
+    let url;
+    try {
+        url = new URL(realm);
+    }
+    catch {
+        throw new AuthChallengeError(`auth realm "${realm}" is not an absolute URL`);
+    }
+    if (url.protocol !== "https:") {
+        // A token fetched over plaintext can be swapped by anyone on the path, and
+        // a `file:`/`gopher:` realm is an outright attack on the client.
+        throw new AuthChallengeError(`auth realm "${realm}" is not https — refusing to fetch a token over ${url.protocol.replace(":", "")}`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new AuthChallengeError(`auth realm "${realm}" carries credentials — refusing; these tools are anonymous-only`);
+    }
+    const service = challenge.params["service"];
+    if (service !== undefined && service !== "")
+        url.searchParams.set("service", service);
+    url.searchParams.set("scope", scope);
+    return url;
+}
+/**
+ * Pull the bearer token out of a token endpoint's JSON body. Registries are
+ * inconsistent: the distribution spec says `token`, OAuth2 says `access_token`,
+ * and ghcr.io returns both. Parsing here is safe — a token is not content
+ * addressed, so nothing downstream hashes these bytes.
+ */
+export function readTokenBody(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new AuthChallengeError("token endpoint did not return JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new AuthChallengeError("token endpoint returned JSON that is not an object");
+    }
+    const body = parsed;
+    const token = body["token"] ?? body["access_token"];
+    if (typeof token !== "string" || token === "") {
+        throw new AuthChallengeError("token endpoint returned no token — the repository is probably private, and these tools are anonymous-only");
+    }
+    return token;
+}

package/dist/lib/http.d.ts

@@ -0,0 +1,48 @@
+export declare class RegistryHttpError extends Error {
+    readonly name = "RegistryHttpError";
+}
+export type RawResponse = {
+    readonly status: number;
+    readonly headers: Headers;
+    /** The response body exactly as it arrived. Never decoded, never re-encoded. */
+    readonly bytes: Uint8Array;
+    /** The URL the body actually came from, after redirects. */
+    readonly url: string;
+};
+/**
+ * Fetch injection point. Tests replace it so the suite never opens a socket;
+ * production leaves it at `pinnedFetch`, which dials the exact IP the SSRF
+ * check validated.
+ */
+export type RegistryFetch = (req: Request, pinnedIp: string) => Promise<Response>;
+/** Test seam — `_setFetch(undefined)` restores the production dialer. */
+export declare function _setFetch(fn: RegistryFetch | undefined): void;
+export type GetOptions = {
+    readonly accept?: string;
+    readonly authorization?: string;
+    readonly maxBytes: number;
+    readonly signal?: AbortSignal;
+    /** `HEAD` is never used here: a body is the only thing we can verify. */
+    readonly method?: "GET";
+};
+/**
+ * GET a URL, following redirects by hand.
+ *
+ * Two rules the default `fetch` would not enforce for us:
+ *   - every hop is re-checked against the SSRF guard and pinned to the IP it
+ *     validated, because only the first URL is ours — the rest come from the
+ *     server;
+ *   - the `Authorization` header is DROPPED the moment a redirect leaves the
+ *     origin it was minted for. Registries redirect to CDNs and object stores;
+ *     forwarding a pull token to `random-bucket.example.com` hands it away.
+ */
+export declare function httpGet(url: URL, options: GetOptions): Promise<RawResponse>;
+/**
+ * A signal that aborts on the caller's cancellation OR after `timeoutMs`,
+ * whichever comes first. The returned `dispose` must run in a `finally` so a
+ * fast call does not leave a timer holding the process open.
+ */
+export declare function deadlineSignal(outer: AbortSignal | undefined, timeoutMs: number): {
+    signal: AbortSignal;
+    dispose: () => void;
+};

package/dist/lib/http.js

@@ -0,0 +1,179 @@
+/**
+ * The HTTP floor these tools stand on: SSRF-guarded, redirect-aware, and
+ * BYTE-PRESERVING.
+ *
+ * Byte preservation is the whole reason this is not `globalThis.fetch(...)
+ * .then(r => r.json())`. A manifest's digest is sha256 over the exact bytes the
+ * registry sent; decoding to a string and re-encoding is lossless only for
+ * well-formed UTF-8, and `JSON.parse` + `JSON.stringify` is not lossless at
+ * all. Everything here hands the caller a `Uint8Array` and lets the caller
+ * decide when it is safe to parse.
+ *
+ * The SSRF guard is `@crewhaus/tool-fetch`'s `assertNotSsrf` — the same
+ * checker the Fetch tool uses, including the DNS-rebinding backstop and the
+ * pinned IP it returns. A registry that answers a manifest request with
+ * `302 Location: http://169.254.169.254/latest/meta-data/` is the attack this
+ * closes, and it closes it at EVERY hop, not just the first.
+ */
+import { assertNotSsrf } from "@crewhaus/tool-fetch";
+export class RegistryHttpError extends Error {
+    name = "RegistryHttpError";
+}
+/** Registries redirect blobs to object storage; five hops is already generous. */
+const MAX_REDIRECTS = 5;
+/**
+ * Dial `pinnedIp` while keeping the real hostname for the Host header and TLS
+ * SNI, so certificate validation and virtual-host routing still work. Mirrors
+ * `@crewhaus/tool-fetch`'s own dialer, which is module-private there: resolving
+ * in the guard and letting `fetch` re-resolve at connect time is a rebinding
+ * TOCTOU, so the pin has to be applied by whoever makes the request.
+ */
+function pinnedFetch(req, pinnedIp) {
+    const original = new URL(req.url);
+    const host = original.hostname;
+    const unbracketed = host.replace(/^\[/, "").replace(/\]$/, "");
+    if (pinnedIp === "" || unbracketed === pinnedIp)
+        return globalThis.fetch(req);
+    const pinnedUrl = new URL(original.toString());
+    pinnedUrl.hostname = pinnedIp.includes(":") ? `[${pinnedIp}]` : pinnedIp;
+    const headers = new Headers(req.headers);
+    headers.set("host", original.port === "" ? host : `${host}:${original.port}`);
+    const init = {
+        method: req.method,
+        headers,
+        redirect: "manual",
+        signal: req.signal,
+        tls: { serverName: host },
+    };
+    return globalThis.fetch(pinnedUrl.toString(), init);
+}
+let rawFetch = pinnedFetch;
+/** Test seam — `_setFetch(undefined)` restores the production dialer. */
+export function _setFetch(fn) {
+    rawFetch = fn ?? pinnedFetch;
+}
+const USER_AGENT = "crewhaus-tool-containers/0.6";
+/**
+ * GET a URL, following redirects by hand.
+ *
+ * Two rules the default `fetch` would not enforce for us:
+ *   - every hop is re-checked against the SSRF guard and pinned to the IP it
+ *     validated, because only the first URL is ours — the rest come from the
+ *     server;
+ *   - the `Authorization` header is DROPPED the moment a redirect leaves the
+ *     origin it was minted for. Registries redirect to CDNs and object stores;
+ *     forwarding a pull token to `random-bucket.example.com` hands it away.
+ */
+export async function httpGet(url, options) {
+    const tokenOrigin = url.origin;
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (current.protocol !== "https:" && current.protocol !== "http:") {
+            throw new RegistryHttpError(`refusing scheme "${current.protocol.replace(":", "")}" — registry requests are http(s) only`);
+        }
+        const pinnedIp = await assertNotSsrf(current.hostname);
+        const headers = new Headers({ "user-agent": USER_AGENT });
+        if (options.accept !== undefined)
+            headers.set("accept", options.accept);
+        if (options.authorization !== undefined && current.origin === tokenOrigin) {
+            headers.set("authorization", options.authorization);
+        }
+        const res = await rawFetch(new Request(current.toString(), {
+            method: options.method ?? "GET",
+            redirect: "manual",
+            headers,
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        }), pinnedIp);
+        if (res.status >= 300 && res.status < 400 && res.headers.has("location")) {
+            const location = res.headers.get("location") ?? "";
+            let next;
+            try {
+                next = new URL(location, current);
+            }
+            catch {
+                throw new RegistryHttpError(`registry redirected to an unparseable location "${location}"`);
+            }
+            try {
+                await res.body?.cancel();
+            }
+            catch {
+                // Already discarding this response; a failed cancel changes nothing.
+            }
+            current = next;
+            continue;
+        }
+        const bytes = await readCapped(res, options.maxBytes);
+        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.
+ */
+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.
+        }
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return merged;
+}
+/**
+ * A signal that aborts on the caller's cancellation OR after `timeoutMs`,
+ * whichever comes first. The returned `dispose` must run in a `finally` so a
+ * fast call does not leave a timer holding the process open.
+ */
+export function deadlineSignal(outer, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new RegistryHttpError(`registry request timed out after ${timeoutMs}ms`)), timeoutMs);
+    const onAbort = () => controller.abort(outer?.reason);
+    if (outer !== undefined) {
+        if (outer.aborted)
+            controller.abort(outer.reason);
+        else
+            outer.addEventListener("abort", onAbort, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            clearTimeout(timer);
+            outer?.removeEventListener("abort", onAbort);
+        },
+    };
+}

package/dist/lib/manifest.d.ts

@@ -0,0 +1,158 @@
+import { type ImageRef } from "./ref";
+export declare class ManifestError extends Error {
+    readonly name = "ManifestError";
+    /**
+     * True when the bytes in hand are not the bytes that were addressed — a
+     * digest that disagrees with its content, from whichever side claimed it.
+     * A FLAG rather than a phrase in the message: `withDigests` decides between
+     * "note this against one tag" and "abort the whole listing" on this, and a
+     * caller that decided by matching message text would fail open the first
+     * time somebody reworded a sentence.
+     */
+    readonly integrity: boolean;
+    constructor(message: string, integrity?: boolean);
+}
+export declare const MEDIA_TYPES: {
+    readonly dockerManifest: "application/vnd.docker.distribution.manifest.v2+json";
+    readonly dockerList: "application/vnd.docker.distribution.manifest.list.v2+json";
+    readonly ociManifest: "application/vnd.oci.image.manifest.v1+json";
+    readonly ociIndex: "application/vnd.oci.image.index.v1+json";
+    readonly dockerSchema1: "application/vnd.docker.distribution.manifest.v1+json";
+    readonly dockerSchema1Signed: "application/vnd.docker.distribution.manifest.v1+prettyjws";
+};
+/**
+ * Every manifest type we can read, offered in one Accept header. Send all four
+ * or a registry will helpfully convert a manifest list down to a single
+ * manifest for you — and then the digest you report is not the digest of the
+ * tag you asked about.
+ */
+export declare const MANIFEST_ACCEPT: string;
+/** sha256 (or sha512) over the exact bytes, formatted as an OCI digest. */
+export declare function digestBytes(bytes: Uint8Array, algorithm?: "sha256" | "sha512"): string;
+export type DigestVerdict = {
+    /** The digest WE computed. Everything downstream uses this one. */
+    readonly digest: string;
+    /** What `Docker-Content-Digest` claimed, when the registry sent it. */
+    readonly headerDigest: string | null;
+    /** True when a header was present and agreed with the computed digest. */
+    readonly headerAgreed: boolean;
+};
+/**
+ * Compute the digest of a document and check it against everything that claims
+ * to know it: the `Docker-Content-Digest` header, and — when the caller asked
+ * for a specific digest, or followed a descriptor out of an index — the digest
+ * it was promised.
+ *
+ * A mismatch is a refusal, never a warning. It means the bytes in hand are not
+ * the bytes that were addressed, and there is no answer to give that is both
+ * true and useful.
+ */
+export declare function verifyDigest(bytes: Uint8Array, header: string | null, expected: string | null, what: string): DigestVerdict;
+/**
+ * Decode and parse a document AFTER its digest has been taken. `fatal: true`
+ * matters: a lenient decode would replace invalid bytes with U+FFFD and parse a
+ * document that is not what was served.
+ */
+export declare function parseDocument(bytes: Uint8Array, what: string): Record<string, unknown>;
+export type DocumentKind = "manifest" | "index";
+/**
+ * Decide what kind of document this is, preferring what the bytes say about
+ * themselves over what the transport said. A registry's Content-Type can be
+ * absent, generic (`application/json`), or — behind a proxy — simply wrong,
+ * while `mediaType` inside an OCI document is part of the digested content.
+ * Structure is the last resort, for old Docker manifests that omit `mediaType`.
+ */
+export declare function classifyDocument(contentType: string | null, document: Record<string, unknown>): {
+    kind: DocumentKind;
+    mediaType: string;
+};
+export type Descriptor = {
+    readonly mediaType: string;
+    readonly digest: string;
+    readonly size: number;
+};
+export type PlatformDescriptor = Descriptor & {
+    readonly platform: string;
+    readonly os: string;
+    readonly architecture: string;
+    readonly variant?: string;
+    readonly osVersion?: string;
+};
+/** Render a platform the way `docker buildx` prints it: os/arch[/variant]. */
+export declare function platformString(os: string, architecture: string, variant?: string): string;
+/** Parse `linux/arm64/v8` into its parts. Rejects anything else. */
+export declare function parsePlatform(raw: string): {
+    os: string;
+    architecture: string;
+    variant?: string;
+};
+export type IndexEntries = {
+    readonly platforms: readonly PlatformDescriptor[];
+    /**
+     * Entries with no usable platform — buildkit writes provenance and SBOM
+     * manifests into the index as `unknown/unknown`, and selecting one of those
+     * as "the image" is a classic multi-arch bug.
+     */
+    readonly attestations: number;
+};
+export declare function readIndex(document: Record<string, unknown>): IndexEntries;
+/**
+ * Pick the entry for the wanted platform.
+ *
+ * A caller who names a variant gets exactly that. A caller who does not gets
+ * the variant-less entry when there is one, else the first match in index
+ * order — index order, not "best", because the registry's order is the only
+ * ranking anyone can reproduce.
+ */
+export declare function selectPlatform(entries: readonly PlatformDescriptor[], wanted: {
+    os: string;
+    architecture: string;
+    variant?: string;
+}): PlatformDescriptor | undefined;
+export type ManifestSummary = {
+    readonly config: Descriptor;
+    readonly layers: readonly Descriptor[];
+    readonly totalLayerSize: number;
+    /**
+     * Layers whose descriptor carried no usable `size`. `totalLayerSize` is the
+     * sum of the ones that did, so a non-zero count here means that total is a
+     * floor rather than the answer — and somebody sizes a disk on it.
+     */
+    readonly unsizedLayers: number;
+    readonly annotations?: Record<string, string>;
+    readonly subject?: string;
+};
+export declare function readManifest(document: Record<string, unknown>): ManifestSummary;
+export type ConfigSummary = {
+    readonly created?: string;
+    readonly architecture?: string;
+    readonly os?: string;
+    readonly variant?: string;
+    readonly user?: string;
+    readonly workingDir?: string;
+    readonly entrypoint?: readonly string[];
+    readonly cmd?: readonly string[];
+    readonly exposedPorts?: readonly string[];
+    readonly volumes?: readonly string[];
+    readonly labels?: Record<string, string>;
+    readonly envNames?: readonly string[];
+    readonly diffIds?: number;
+};
+/**
+ * The interesting half of the image config blob. Env VALUES are deliberately
+ * dropped and only the names kept: a config blob is where a careless build
+ * leaves a token, and a tool that echoes every `ENV` into a transcript is a
+ * tool that leaks it.
+ */
+export declare function readConfig(document: Record<string, unknown>): ConfigSummary;
+/**
+ * `/v2/<name>/manifests/<reference>` for a parsed reference.
+ *
+ * The reference is re-checked against the tag/digest grammar HERE, at the one
+ * place it becomes a URL path, because not every caller of this function got
+ * its reference from `parseImageRef`: `withDigests` passes tags straight out of
+ * the registry's own `/tags/list`.
+ */
+export declare function manifestPath(ref: ImageRef, reference?: string): string;
+/** `/v2/<name>/blobs/<digest>` — config blobs only; this package never pulls layers. */
+export declare function blobPath(ref: ImageRef, digest: string): string;