@crewhaus/tool-containers 0.7.0

package/dist/lib/manifest.js

@@ -0,0 +1,347 @@
+/**
+ * Digests, media types and the two shapes a tag can resolve to.
+ *
+ * THE RULE THIS FILE EXISTS TO ENFORCE: hash first, parse second, and never
+ * hash anything but the bytes that arrived. `JSON.parse` followed by
+ * `JSON.stringify` changes key order, whitespace and `é`-style escapes —
+ * all of which are inside the sha256 preimage. A digest computed from
+ * reserialized JSON is not wrong in some subtle academic way; it is a different
+ * number, it matches nothing, and it makes "this is the image we tested" false
+ * while looking exactly like it is true.
+ *
+ * So: `digestBytes` takes `Uint8Array`, `parseDocument` is only ever called on
+ * a value that has already been hashed, and nothing in this package ever
+ * re-serializes a manifest.
+ */
+import { createHash } from "node:crypto";
+import { assertPullReference, parseDigest } from "./ref";
+export class ManifestError extends Error {
+    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.
+     */
+    integrity;
+    constructor(message, integrity = false) {
+        super(message);
+        this.integrity = integrity;
+    }
+}
+export const MEDIA_TYPES = {
+    dockerManifest: "application/vnd.docker.distribution.manifest.v2+json",
+    dockerList: "application/vnd.docker.distribution.manifest.list.v2+json",
+    ociManifest: "application/vnd.oci.image.manifest.v1+json",
+    ociIndex: "application/vnd.oci.image.index.v1+json",
+    dockerSchema1: "application/vnd.docker.distribution.manifest.v1+json",
+    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 const MANIFEST_ACCEPT = [
+    MEDIA_TYPES.ociIndex,
+    MEDIA_TYPES.ociManifest,
+    MEDIA_TYPES.dockerList,
+    MEDIA_TYPES.dockerManifest,
+].join(", ");
+/** sha256 (or sha512) over the exact bytes, formatted as an OCI digest. */
+export function digestBytes(bytes, algorithm = "sha256") {
+    return `${algorithm}:${createHash(algorithm).update(bytes).digest("hex")}`;
+}
+/**
+ * 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 function verifyDigest(bytes, header, expected, what) {
+    const algorithm = expected === null ? "sha256" : parseDigest(expected).algorithm;
+    const digest = digestBytes(bytes, algorithm);
+    if (expected !== null && digest !== expected) {
+        throw new ManifestError(`${what}: the registry served bytes whose digest is ${digest}, but ${expected} was requested — refusing to report a digest that does not match its content`, true);
+    }
+    let headerAgreed = false;
+    if (header !== null && header.trim() !== "") {
+        const claimed = header.trim().toLowerCase();
+        // Compare only when the header uses an algorithm we computed; a registry
+        // claiming sha512 while we hashed sha256 is a mismatch of question, not of
+        // answer, so we recompute in the header's algorithm before disagreeing.
+        const claimedAlgorithm = claimed.split(":")[0];
+        const ours = claimedAlgorithm === algorithm
+            ? digest
+            : claimedAlgorithm === "sha256" || claimedAlgorithm === "sha512"
+                ? digestBytes(bytes, claimedAlgorithm)
+                : null;
+        if (ours === null) {
+            throw new ManifestError(`${what}: registry claims digest algorithm "${claimedAlgorithm}", which cannot be recomputed here`, true);
+        }
+        if (ours !== claimed) {
+            throw new ManifestError(`${what}: Docker-Content-Digest says ${claimed} but the bytes hash to ${ours} — the header is not evidence, and it disagrees with the content`, true);
+        }
+        headerAgreed = true;
+    }
+    return {
+        digest,
+        headerDigest: header === null ? null : header.trim().toLowerCase(),
+        headerAgreed,
+    };
+}
+/**
+ * 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 function parseDocument(bytes, what) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new ManifestError(`${what} is not valid UTF-8`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new ManifestError(`${what} is not valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new ManifestError(`${what} is not a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * 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 function classifyDocument(contentType, document) {
+    const declared = typeof document["mediaType"] === "string" ? document["mediaType"] : "";
+    const transport = (contentType ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+    const mediaType = declared !== "" ? declared : transport;
+    if (mediaType === MEDIA_TYPES.dockerSchema1 || mediaType === MEDIA_TYPES.dockerSchema1Signed) {
+        throw new ManifestError("this tag is a schema 1 manifest, whose digest covers a JWS signature rather than the image content — pull it with a v2 client or ask the registry for a v2 manifest; a schema 1 digest would not mean what the caller thinks it means");
+    }
+    if (mediaType === MEDIA_TYPES.ociIndex || mediaType === MEDIA_TYPES.dockerList) {
+        return { kind: "index", mediaType };
+    }
+    if (mediaType === MEDIA_TYPES.ociManifest || mediaType === MEDIA_TYPES.dockerManifest) {
+        return { kind: "manifest", mediaType };
+    }
+    // No usable media type: fall back to shape. `manifests` is an index, a
+    // `config` descriptor plus `layers` is an image manifest.
+    if (Array.isArray(document["manifests"])) {
+        return { kind: "index", mediaType: mediaType === "" ? MEDIA_TYPES.ociIndex : mediaType };
+    }
+    if (Array.isArray(document["layers"]) && typeof document["config"] === "object") {
+        return { kind: "manifest", mediaType: mediaType === "" ? MEDIA_TYPES.ociManifest : mediaType };
+    }
+    if (document["schemaVersion"] === 1 || Array.isArray(document["fsLayers"])) {
+        throw new ManifestError("this tag is a schema 1 manifest (fsLayers/schemaVersion 1) — its digest covers a signature envelope, not the image content");
+    }
+    throw new ManifestError(`cannot tell what kind of document this is — media type "${mediaType || "(none)"}", and it has neither "manifests" nor "layers"`);
+}
+function readDescriptor(raw, what) {
+    if (typeof raw !== "object" || raw === null)
+        throw new ManifestError(`${what} is not a descriptor`);
+    const d = raw;
+    const rawDigest = typeof d["digest"] === "string" ? d["digest"] : "";
+    if (rawDigest === "")
+        throw new ManifestError(`${what} has no digest`);
+    // Refuse an unverifiable algorithm here, not three calls later — and store
+    // the NORMALISED form. Hex case is not identity: a descriptor written
+    // `sha256:AB…` addresses the same bytes as `sha256:ab…`, but comparing it
+    // against a freshly computed (lower-case) digest would raise the tampering
+    // refusal, which has to stay believable.
+    const parsed = parseDigest(rawDigest);
+    return {
+        mediaType: typeof d["mediaType"] === "string" ? d["mediaType"] : "",
+        digest: `${parsed.algorithm}:${parsed.hex}`,
+        size: typeof d["size"] === "number" && Number.isFinite(d["size"]) ? d["size"] : -1,
+    };
+}
+/** Render a platform the way `docker buildx` prints it: os/arch[/variant]. */
+export function platformString(os, architecture, variant) {
+    return variant === undefined || variant === ""
+        ? `${os}/${architecture}`
+        : `${os}/${architecture}/${variant}`;
+}
+/** Parse `linux/arm64/v8` into its parts. Rejects anything else. */
+export function parsePlatform(raw) {
+    const parts = raw
+        .trim()
+        .toLowerCase()
+        .split("/")
+        .filter((p) => p !== "");
+    if (parts.length < 2 || parts.length > 3) {
+        throw new ManifestError(`"${raw}" is not a platform — write os/arch or os/arch/variant, e.g. linux/arm64/v8`);
+    }
+    const [os, architecture, variant] = parts;
+    return variant === undefined ? { os, architecture } : { os, architecture, variant };
+}
+export function readIndex(document) {
+    const raw = document["manifests"];
+    if (!Array.isArray(raw))
+        throw new ManifestError("index has no manifests array");
+    const platforms = [];
+    let attestations = 0;
+    for (const [i, entry] of raw.entries()) {
+        const descriptor = readDescriptor(entry, `index entry ${i}`);
+        const p = entry["platform"];
+        const platform = typeof p === "object" && p !== null ? p : {};
+        const os = typeof platform["os"] === "string" ? platform["os"] : "";
+        const architecture = typeof platform["architecture"] === "string" ? platform["architecture"] : "";
+        const variant = typeof platform["variant"] === "string" ? platform["variant"] : undefined;
+        const osVersion = typeof platform["os.version"] === "string" ? platform["os.version"] : undefined;
+        if (os === "" || architecture === "" || os === "unknown" || architecture === "unknown") {
+            attestations++;
+            continue;
+        }
+        platforms.push({
+            ...descriptor,
+            platform: platformString(os, architecture, variant),
+            os,
+            architecture,
+            ...(variant !== undefined ? { variant } : {}),
+            ...(osVersion !== undefined ? { osVersion } : {}),
+        });
+    }
+    return { platforms, attestations };
+}
+/**
+ * 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 function selectPlatform(entries, wanted) {
+    const matches = entries.filter((e) => e.os === wanted.os && e.architecture === wanted.architecture);
+    if (matches.length === 0)
+        return undefined;
+    if (wanted.variant !== undefined)
+        return matches.find((e) => e.variant === wanted.variant);
+    return matches.find((e) => e.variant === undefined) ?? matches[0];
+}
+export function readManifest(document) {
+    const config = readDescriptor(document["config"], "manifest config");
+    const rawLayers = document["layers"];
+    if (!Array.isArray(rawLayers))
+        throw new ManifestError("manifest has no layers array");
+    const layers = rawLayers.map((l, i) => readDescriptor(l, `layer ${i}`));
+    const totalLayerSize = layers.reduce((sum, l) => sum + (l.size > 0 ? l.size : 0), 0);
+    const unsizedLayers = layers.filter((l) => l.size < 0).length;
+    const annotations = readStringMap(document["annotations"]);
+    const subject = document["subject"];
+    const subjectDigest = typeof subject === "object" &&
+        subject !== null &&
+        typeof subject["digest"] === "string"
+        ? subject["digest"]
+        : undefined;
+    return {
+        config,
+        layers,
+        totalLayerSize,
+        unsizedLayers,
+        ...(annotations !== undefined ? { annotations } : {}),
+        ...(subjectDigest !== undefined ? { subject: subjectDigest } : {}),
+    };
+}
+/**
+ * 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 function readConfig(document) {
+    const cfg = typeof document["config"] === "object" && document["config"] !== null
+        ? document["config"]
+        : {};
+    const rootfs = typeof document["rootfs"] === "object" && document["rootfs"] !== null
+        ? document["rootfs"]
+        : {};
+    const diffIds = Array.isArray(rootfs["diff_ids"])
+        ? rootfs["diff_ids"].length
+        : undefined;
+    const env = Array.isArray(cfg["Env"])
+        ? cfg["Env"]
+            .filter((e) => typeof e === "string")
+            .map((e) => (e.includes("=") ? e.split("=")[0] : e))
+        : undefined;
+    return {
+        ...pickString(document, "created"),
+        ...pickString(document, "architecture"),
+        ...pickString(document, "os"),
+        ...pickString(document, "variant"),
+        ...pickString(cfg, "User", "user"),
+        ...pickString(cfg, "WorkingDir", "workingDir"),
+        ...pickStrings(cfg, "Entrypoint", "entrypoint"),
+        ...pickStrings(cfg, "Cmd", "cmd"),
+        ...(readKeySet(cfg["ExposedPorts"]) !== undefined
+            ? { exposedPorts: readKeySet(cfg["ExposedPorts"]) }
+            : {}),
+        ...(readKeySet(cfg["Volumes"]) !== undefined ? { volumes: readKeySet(cfg["Volumes"]) } : {}),
+        ...(readStringMap(cfg["Labels"]) !== undefined ? { labels: readStringMap(cfg["Labels"]) } : {}),
+        ...(env !== undefined ? { envNames: env } : {}),
+        ...(diffIds !== undefined ? { diffIds } : {}),
+    };
+}
+function pickString(source, key, as = key) {
+    const value = source[key];
+    return typeof value === "string" && value !== "" ? { [as]: value } : {};
+}
+function pickStrings(source, key, as) {
+    const value = source[key];
+    if (!Array.isArray(value))
+        return {};
+    const strings = value.filter((v) => typeof v === "string");
+    return strings.length === 0 ? {} : { [as]: strings };
+}
+function readKeySet(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const keys = Object.keys(value).sort();
+    return keys.length === 0 ? undefined : keys;
+}
+function readStringMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof v === "string")
+            out[k] = v;
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/**
+ * `/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 function manifestPath(ref, reference = ref.reference) {
+    assertPullReference(reference);
+    return `/v2/${ref.repository}/manifests/${reference}`;
+}
+/** `/v2/<name>/blobs/<digest>` — config blobs only; this package never pulls layers. */
+export function blobPath(ref, digest) {
+    parseDigest(digest); // same containment rule: a blob is only ever addressed by digest
+    return `/v2/${ref.repository}/blobs/${digest}`;
+}

package/dist/lib/ref.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Image reference parsing — the `[registry/]repository[:tag][@digest]` grammar
+ * every container tool in the world accepts and almost nobody writes down.
+ *
+ * Two things here are load-bearing rather than cosmetic:
+ *
+ *   1. The repository is interpolated into a URL path (`/v2/<name>/manifests/…`).
+ *      Anything outside the OCI grammar is REFUSED rather than escaped, so a
+ *      reference like `ghcr.io/a/../../v2/other/manifests/latest` cannot walk
+ *      the client onto a different repository — or off `/v2/` entirely.
+ *   2. Docker Hub is not `docker.io`. The API host is `registry-1.docker.io`
+ *      and a one-segment name means the `library/` namespace, so `alpine` is
+ *      `registry-1.docker.io/v2/library/alpine`. Every other registry uses the
+ *      name as written.
+ */
+export declare class ImageRefError extends Error {
+    readonly name = "ImageRefError";
+}
+export type ImageRef = {
+    /** What the caller means by the registry — `docker.io`, not the API host. */
+    readonly registry: string;
+    /** The host actually contacted; differs from `registry` only for Docker Hub. */
+    readonly apiHost: string;
+    /** Fully qualified repository, `library/` synthesised for Hub official images. */
+    readonly repository: string;
+    /** The tag or digest this reference selects. */
+    readonly reference: string;
+    readonly referenceKind: "tag" | "digest";
+    /** Normalised `registry/repository:tag` (or `@digest`), for echoing back. */
+    readonly canonical: string;
+};
+/**
+ * Validate a digest string and return its algorithm. Refuses an algorithm we
+ * cannot recompute: reporting a digest we could not check against the bytes
+ * would be exactly the lie this package exists to avoid.
+ */
+export declare function parseDigest(raw: string): {
+    algorithm: string;
+    hex: string;
+};
+export type ParseOptions = {
+    /**
+     * `false` for the tags endpoint, which addresses a repository and not one
+     * version of it. A tag is then still parsed and reported, so a caller who
+     * pastes a full reference gets an answer instead of a lecture.
+     */
+    readonly defaultTag?: boolean;
+};
+/**
+ * Parse `[registry/]repository[:tag][@digest]`.
+ *
+ * When both a tag and a digest are present (`alpine:3.19@sha256:…`, which is
+ * what a pinned reference looks like) the DIGEST wins, because that is what the
+ * registry will serve — the tag in such a reference is a human label and may
+ * have been moved since it was written down.
+ */
+export declare function parseImageRef(raw: string, options?: ParseOptions): ImageRef;
+/** True when `value` is a tag under the distribution grammar. */
+export declare function isValidTag(value: string): boolean;
+/**
+ * Refuse a reference that is neither a tag nor a digest BEFORE it reaches
+ * `/v2/<name>/manifests/<reference>`.
+ *
+ * A caller's reference arrives through `parseImageRef` and is already checked.
+ * A tag read out of `/tags/list` is NOT: it is a JSON string the registry
+ * chose, and `new URL("https://reg/v2/owner/app/manifests/" + "../../victim/manifests/latest")`
+ * normalises to `https://reg/v2/victim/manifests/latest` — a different
+ * repository, whose digest would then be reported as this one's tag. For a URL
+ * path, containment is a grammar check; escaping the string would only turn a
+ * silent redirection into a 404.
+ */
+export declare function assertPullReference(reference: string): void;
+/** The scope a pull token must ask for, for this repository. */
+export declare function pullScope(repository: string): string;

package/dist/lib/ref.js

@@ -0,0 +1,192 @@
+/**
+ * Image reference parsing — the `[registry/]repository[:tag][@digest]` grammar
+ * every container tool in the world accepts and almost nobody writes down.
+ *
+ * Two things here are load-bearing rather than cosmetic:
+ *
+ *   1. The repository is interpolated into a URL path (`/v2/<name>/manifests/…`).
+ *      Anything outside the OCI grammar is REFUSED rather than escaped, so a
+ *      reference like `ghcr.io/a/../../v2/other/manifests/latest` cannot walk
+ *      the client onto a different repository — or off `/v2/` entirely.
+ *   2. Docker Hub is not `docker.io`. The API host is `registry-1.docker.io`
+ *      and a one-segment name means the `library/` namespace, so `alpine` is
+ *      `registry-1.docker.io/v2/library/alpine`. Every other registry uses the
+ *      name as written.
+ */
+/** Registries that mean Docker Hub, whatever the caller typed. */
+const DOCKER_HUB_ALIASES = new Set(["docker.io", "index.docker.io", "registry-1.docker.io"]);
+const DOCKER_HUB_API_HOST = "registry-1.docker.io";
+/**
+ * One path component of a repository name, per the distribution spec:
+ * lowercase alphanumerics with single `.`/`_`, double `__`, or runs of `-` as
+ * separators. Uppercase is invalid — refusing `Alpine` is kinder than the 404
+ * the registry would answer with.
+ */
+const COMPONENT_RE = /^[a-z0-9]+(?:(?:\.|_|__|-+)[a-z0-9]+)*$/;
+/** A tag: up to 128 characters, no leading `.` or `-`. */
+const TAG_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
+/** A registry host, optionally with a port. No scheme, no path, no userinfo. */
+const HOST_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)*(?::\d{1,5})?$/;
+/** OCI digest grammar: `<algorithm>:<encoded>`. */
+const DIGEST_RE = /^([a-z0-9]+(?:[.+_-][a-z0-9]+)*):([a-zA-Z0-9=_-]+)$/;
+/** Hex length of the digests we can actually recompute from response bytes. */
+const SUPPORTED_DIGESTS = { sha256: 64, sha512: 128 };
+export class ImageRefError extends Error {
+    name = "ImageRefError";
+}
+/**
+ * Validate a digest string and return its algorithm. Refuses an algorithm we
+ * cannot recompute: reporting a digest we could not check against the bytes
+ * would be exactly the lie this package exists to avoid.
+ */
+export function parseDigest(raw) {
+    const m = DIGEST_RE.exec(raw);
+    if (!m) {
+        throw new ImageRefError(`"${raw}" is not a digest — expected <algorithm>:<hex>, e.g. sha256:…`);
+    }
+    const algorithm = m[1];
+    const hex = m[2].toLowerCase();
+    const expected = SUPPORTED_DIGESTS[algorithm];
+    if (expected === undefined) {
+        throw new ImageRefError(`digest algorithm "${algorithm}" is not supported — this tool verifies sha256 and sha512, and will not report a digest it cannot recompute`);
+    }
+    if (hex.length !== expected || !/^[0-9a-f]+$/.test(hex)) {
+        throw new ImageRefError(`"${raw}" is not a valid ${algorithm} digest — expected ${expected} hex characters, got ${hex.length}`);
+    }
+    return { algorithm, hex };
+}
+/** True when the first path segment names a registry rather than a namespace. */
+function looksLikeHost(segment) {
+    return segment.includes(".") || segment.includes(":") || segment === "localhost";
+}
+/**
+ * Parse `[registry/]repository[:tag][@digest]`.
+ *
+ * When both a tag and a digest are present (`alpine:3.19@sha256:…`, which is
+ * what a pinned reference looks like) the DIGEST wins, because that is what the
+ * registry will serve — the tag in such a reference is a human label and may
+ * have been moved since it was written down.
+ */
+export function parseImageRef(raw, options = {}) {
+    const input = raw.trim();
+    if (input === "")
+        throw new ImageRefError("image reference is empty");
+    if (input.length > 512) {
+        throw new ImageRefError(`image reference is ${input.length} characters — that is not a reference`);
+    }
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(input)) {
+        throw new ImageRefError(`"${input}" has a URL scheme — an image reference has none; write ghcr.io/owner/name:tag`);
+    }
+    let rest = input;
+    let digest = null;
+    const at = rest.indexOf("@");
+    if (at !== -1) {
+        const tail = rest.slice(at + 1);
+        if (tail.includes("@")) {
+            throw new ImageRefError(`"${input}" has more than one "@" — expected at most name@digest`);
+        }
+        const parsed = parseDigest(tail);
+        digest = `${parsed.algorithm}:${parsed.hex}`;
+        rest = rest.slice(0, at);
+    }
+    // Split the registry off only when the first segment is host-shaped. `foo/bar`
+    // is a Docker Hub namespace, `foo.io/bar` is a registry — that single rule is
+    // the whole disambiguation, and it is why `localhost` is special-cased.
+    let registryRaw = "";
+    let name = rest;
+    const slash = rest.indexOf("/");
+    if (slash !== -1) {
+        const head = rest.slice(0, slash);
+        if (looksLikeHost(head)) {
+            registryRaw = head;
+            name = rest.slice(slash + 1);
+        }
+    }
+    // The tag separator is the last `:` that cannot be a registry port, i.e. one
+    // that appears after the final `/`.
+    let tag = null;
+    const lastSlash = name.lastIndexOf("/");
+    const colon = name.indexOf(":", lastSlash + 1);
+    if (colon !== -1) {
+        tag = name.slice(colon + 1);
+        name = name.slice(0, colon);
+        if (!TAG_RE.test(tag)) {
+            throw new ImageRefError(`"${tag}" is not a valid tag — tags are up to 128 characters of letters, digits, ".", "_" and "-", and cannot start with "." or "-"`);
+        }
+    }
+    if (registryRaw !== "" && !HOST_RE.test(registryRaw)) {
+        throw new ImageRefError(`"${registryRaw}" is not a valid registry host`);
+    }
+    // HOST_RE allows five port digits; 65536..99999 are not ports. Without this
+    // the refusal is a raw `TypeError: … cannot be parsed as a URL` thrown from
+    // `new URL` three calls later, which names neither the input nor the rule.
+    const port = registryRaw.slice(registryRaw.lastIndexOf(":") + 1);
+    if (registryRaw.includes(":") && (Number(port) < 1 || Number(port) > 65535)) {
+        throw new ImageRefError(`"${registryRaw}" has port ${port}, which is not a port`);
+    }
+    if (name === "")
+        throw new ImageRefError(`"${input}" has no repository name`);
+    const components = name.split("/");
+    for (const component of components) {
+        if (component === "") {
+            throw new ImageRefError(`"${name}" has an empty path component`);
+        }
+        if (!COMPONENT_RE.test(component)) {
+            const hint = /[A-Z]/.test(component)
+                ? " — repository names are lowercase"
+                : component === "." || component === ".."
+                    ? " — relative path segments are not part of a repository name"
+                    : "";
+            throw new ImageRefError(`"${component}" is not a valid repository path component${hint}`);
+        }
+    }
+    if (components.length > 8) {
+        throw new ImageRefError(`"${name}" has ${components.length} path components — expected at most 8`);
+    }
+    const hubAlias = registryRaw === "" || DOCKER_HUB_ALIASES.has(registryRaw.toLowerCase());
+    const registry = hubAlias ? "docker.io" : registryRaw.toLowerCase();
+    const apiHost = hubAlias ? DOCKER_HUB_API_HOST : registry;
+    // Hub's official images live under `library/`; the short form everyone types
+    // is the only place in this grammar where a path segment is synthesised.
+    const repository = hubAlias && components.length === 1 ? `library/${name}` : name;
+    const defaultTag = options.defaultTag ?? true;
+    const reference = digest ?? tag ?? (defaultTag ? "latest" : "");
+    const referenceKind = digest !== null ? "digest" : "tag";
+    const canonical = digest !== null
+        ? `${registry}/${repository}@${digest}`
+        : reference === ""
+            ? `${registry}/${repository}`
+            : `${registry}/${repository}:${reference}`;
+    return { registry, apiHost, repository, reference, referenceKind, canonical };
+}
+/** True when `value` is a tag under the distribution grammar. */
+export function isValidTag(value) {
+    return TAG_RE.test(value);
+}
+/**
+ * Refuse a reference that is neither a tag nor a digest BEFORE it reaches
+ * `/v2/<name>/manifests/<reference>`.
+ *
+ * A caller's reference arrives through `parseImageRef` and is already checked.
+ * A tag read out of `/tags/list` is NOT: it is a JSON string the registry
+ * chose, and `new URL("https://reg/v2/owner/app/manifests/" + "../../victim/manifests/latest")`
+ * normalises to `https://reg/v2/victim/manifests/latest` — a different
+ * repository, whose digest would then be reported as this one's tag. For a URL
+ * path, containment is a grammar check; escaping the string would only turn a
+ * silent redirection into a 404.
+ */
+export function assertPullReference(reference) {
+    if (isValidTag(reference))
+        return;
+    // Digest-shaped gets the digest parser's specific reason (bad length,
+    // unsupported algorithm) rather than this generic one.
+    if (DIGEST_RE.test(reference)) {
+        parseDigest(reference);
+        return;
+    }
+    throw new ImageRefError(`"${reference.length > 80 ? `${reference.slice(0, 80)}…` : reference}" is neither a tag nor a digest — refusing to put it in a registry URL path`);
+}
+/** The scope a pull token must ask for, for this repository. */
+export function pullScope(repository) {
+    return `repository:${repository}:pull`;
+}

package/dist/lib/registry.d.ts

@@ -0,0 +1,37 @@
+import { type RawResponse, RegistryHttpError } from "./http";
+export declare class RegistryError extends Error {
+    readonly name = "RegistryError";
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export type RegistryClient = {
+    readonly host: string;
+    readonly signal?: AbortSignal;
+    readonly tokens: Map<string, string>;
+    /** Requests actually issued, reported back so a caller can see what it cost. */
+    requests: number;
+    readonly timeoutMs: number;
+};
+export declare function newClient(host: string, signal?: AbortSignal, timeoutMs?: number): RegistryClient;
+export type RegistryGetOptions = {
+    readonly accept?: string;
+    readonly maxBytes: number;
+    /** The pull scope this path needs, e.g. `repository:library/alpine:pull`. */
+    readonly scope: string;
+};
+/** `https://<host><path>` — the only place a registry URL is constructed. */
+export declare function registryUrl(host: string, path: string): URL;
+/**
+ * GET a registry path, performing the anonymous token dance if the registry
+ * asks for one. Returns the raw bytes; the caller decides whether to hash them,
+ * parse them, or both — in that order.
+ */
+export declare function registryGet(client: RegistryClient, path: string, options: RegistryGetOptions): Promise<RawResponse>;
+/**
+ * The same dance against an already-built URL — what paging needs, since the
+ * next page arrives as a `Link` header rather than a path we compose. The
+ * caller has already checked that the URL is on the registry's own origin.
+ */
+export declare function registryGetUrl(client: RegistryClient, url: URL, options: RegistryGetOptions): Promise<RawResponse>;
+export declare function describeFailure(res: RawResponse, host: string, path: string): RegistryError;
+export { RegistryHttpError };