@crewhaus/tool-containers 0.7.0

package/dist/lib/registry.js

@@ -0,0 +1,166 @@
+/**
+ * The OCI distribution client: one GET, one 401, one token, one retry.
+ *
+ * Everything registry-specific is read off the challenge (see `./challenge`),
+ * so Docker Hub, ghcr.io, quay.io and a self-hosted Harbor all take the same
+ * code path. The only registry-specific thing in this package is the
+ * `library/` namespace rewrite in `./ref`, which is a naming rule rather than a
+ * protocol difference.
+ *
+ * The client is per CALL, not per process: the token cache lives in the object
+ * the tool creates and dies with it. A module-level cache would make one call's
+ * result depend on an earlier call's, which is the opposite of what a
+ * deterministic tool is for — and would keep a bearer token alive in memory
+ * long after the call that earned it.
+ */
+import { bearerChallenge, parseAuthenticateHeader, readTokenBody, tokenRequestUrl, } from "./challenge";
+import { RegistryHttpError, deadlineSignal, httpGet } from "./http";
+export class RegistryError extends Error {
+    name = "RegistryError";
+    status;
+    constructor(message, status = 0) {
+        super(message);
+        this.status = status;
+    }
+}
+/** A token body is small; anything larger is not a token endpoint. */
+const MAX_TOKEN_BYTES = 256 * 1024;
+const DEFAULT_TIMEOUT_MS = 20_000;
+/**
+ * A ceiling on requests per tool call. `withDigests` fans out one GET per tag
+ * and each may cost a token exchange, so without this a single call could ask a
+ * registry a few hundred questions and earn a rate-limit ban for the caller.
+ */
+const MAX_REQUESTS = 140;
+export function newClient(host, signal, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return {
+        host,
+        tokens: new Map(),
+        requests: 0,
+        timeoutMs,
+        ...(signal !== undefined ? { signal } : {}),
+    };
+}
+/** `https://<host><path>` — the only place a registry URL is constructed. */
+export function registryUrl(host, path) {
+    return new URL(`https://${host}${path}`);
+}
+async function send(client, url, accept, authorization, maxBytes) {
+    if (client.requests >= MAX_REQUESTS) {
+        throw new RegistryError(`refusing to make more than ${MAX_REQUESTS} registry requests in one call — narrow the request (fewer tags, or drop withDigests)`);
+    }
+    client.requests++;
+    const { signal, dispose } = deadlineSignal(client.signal, client.timeoutMs);
+    try {
+        return await httpGet(url, {
+            maxBytes,
+            signal,
+            ...(accept !== undefined ? { accept } : {}),
+            ...(authorization !== undefined ? { authorization } : {}),
+        });
+    }
+    finally {
+        dispose();
+    }
+}
+/**
+ * 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 async function registryGet(client, path, options) {
+    return registryGetUrl(client, registryUrl(client.host, path), options);
+}
+/**
+ * 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 async function registryGetUrl(client, url, options) {
+    const cached = client.tokens.get(options.scope);
+    let res = await send(client, url, options.accept, cached === undefined ? undefined : `Bearer ${cached}`, options.maxBytes);
+    if (res.status === 401) {
+        const token = await obtainToken(client, res, options.scope, cached !== undefined);
+        client.tokens.set(options.scope, token);
+        res = await send(client, url, options.accept, `Bearer ${token}`, options.maxBytes);
+        // A 401 that survives a freshly minted anonymous token is not a transient
+        // failure and not a missing image: it is a repository we are not allowed to
+        // read. Saying so is more useful than a second round of the same dance.
+        if (res.status === 401)
+            throw privateRefusal(client.host, options.scope);
+    }
+    if (res.status >= 200 && res.status < 300)
+        return res;
+    throw describeFailure(res, client.host, `${url.pathname}${url.search}`);
+}
+/**
+ * Turn a 401 into a bearer token, or into a refusal that says which kind of
+ * "no" this was. `hadToken` distinguishes "we have not authenticated yet" from
+ * "we authenticated and the answer is still no", which is almost always a
+ * private repository — and no amount of retrying fixes that.
+ */
+async function obtainToken(client, res, scope, hadToken) {
+    const header = res.headers.get("www-authenticate");
+    if (header === null) {
+        throw new RegistryError(`${client.host} refused the request with 401 and no WWW-Authenticate challenge — nothing to authenticate against`, 401);
+    }
+    const challenges = parseAuthenticateHeader(header);
+    const bearer = bearerChallenge(challenges);
+    if (bearer === undefined) {
+        const offered = challenges.map((c) => c.scheme).join(", ") || "none";
+        throw new RegistryError(`${client.host} offers ${offered} auth, not Bearer — these tools do the anonymous Bearer flow only, and hold no credentials`, 401);
+    }
+    if (hadToken)
+        throw privateRefusal(client.host, scope);
+    const tokenUrl = tokenRequestUrl(bearer, scope);
+    // No Authorization header here on purpose: this is the anonymous flow, and
+    // the realm is a host the registry named, not one we chose.
+    const tokenRes = await send(client, tokenUrl, "application/json", undefined, MAX_TOKEN_BYTES);
+    if (tokenRes.status < 200 || tokenRes.status >= 300) {
+        throw new RegistryError(`token request to ${tokenUrl.origin}${tokenUrl.pathname} failed with HTTP ${tokenRes.status} for scope ${scope}`, tokenRes.status);
+    }
+    return readTokenBody(new TextDecoder("utf-8", { fatal: false }).decode(tokenRes.bytes));
+}
+/**
+ * Registries report errors in a documented envelope
+ * (`{"errors":[{"code":…,"message":…}]}`). Surfacing that code is the
+ * difference between "MANIFEST_UNKNOWN: no such tag" and "HTTP 404", which a
+ * caller cannot act on.
+ */
+function privateRefusal(host, scope) {
+    return new RegistryError(`${host} refused the request even with an anonymous token for ${scope} — the repository is private, and these tools hold no credentials`, 401);
+}
+export function describeFailure(res, host, path) {
+    const detail = registryErrorDetail(res.bytes);
+    const suffix = detail === "" ? "" : ` — ${detail}`;
+    if (res.status === 404) {
+        return new RegistryError(`${host} has no ${path.replace(/^\/v2\//, "")}${suffix}`, 404);
+    }
+    if (res.status === 429) {
+        return new RegistryError(`${host} rate-limited this request (HTTP 429)${suffix} — anonymous pulls are throttled per IP`, 429);
+    }
+    if (res.status === 403) {
+        return new RegistryError(`${host} denied access to ${path} (HTTP 403)${suffix}`, 403);
+    }
+    return new RegistryError(`${host} answered HTTP ${res.status} for ${path}${suffix}`, res.status);
+}
+function registryErrorDetail(bytes) {
+    if (bytes.byteLength === 0 || bytes.byteLength > 64 * 1024)
+        return "";
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: false }).decode(bytes));
+    }
+    catch {
+        return "";
+    }
+    const errors = parsed?.errors;
+    if (!Array.isArray(errors) || errors.length === 0)
+        return "";
+    const first = errors[0];
+    const code = typeof first.code === "string" ? first.code : "";
+    const message = typeof first.message === "string" ? first.message : "";
+    const joined = [code, message].filter((s) => s !== "").join(": ");
+    return joined.length > 300 ? `${joined.slice(0, 300)}…` : joined;
+}
+export { RegistryHttpError };

package/dist/lib/tags.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Tag lists: paging, filtering, and the sort that makes them readable.
+ *
+ * Real tag lists are mostly not semver. A typical repository holds `latest`,
+ * `edge`, `sha-9f3c1a`, `0.6`, `v0.6.0-rc.1` and `3.19-alpine` side by side, so
+ * a sort that assumes semver either throws or silently reorders the half it
+ * could not read. This one partitions: versions ordered by semver precedence
+ * first, everything else after it in plain lexicographic order, and nothing
+ * throws on a tag it cannot parse.
+ */
+export declare class TagListError extends Error {
+    readonly name = "TagListError";
+}
+export type ParsedVersion = {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    /** `null` for a release; an identifier list for a prerelease. */
+    readonly prerelease: readonly string[] | null;
+};
+/**
+ * Parse a tag as a version, tolerating the two things registries do that
+ * semver does not: a leading `v`, and a truncated version (`0.6`, `3`).
+ * Build metadata is accepted and ignored for precedence, exactly as semver
+ * says, but the tag string itself still breaks ties so the sort stays total.
+ */
+export declare function parseTagVersion(tag: string): ParsedVersion | null;
+/** Semver §11 precedence. Returns <0, 0 or >0. */
+export declare function compareVersions(a: ParsedVersion, b: ParsedVersion): number;
+export type TagSort = "semver" | "name" | "registry";
+/**
+ * Order a tag list.
+ *
+ * `semver` is newest-first, because that is the question people actually have
+ * ("what is the latest?"), with unparseable tags collected at the end rather
+ * than interleaved by a guess. `name` is lexicographic ascending. `registry`
+ * preserves the order the registry returned, which for most registries is the
+ * order tags were pushed and for some is nothing in particular.
+ */
+export declare function sortTags(tags: readonly string[], sort: TagSort): string[];
+/**
+ * Compile a glob into a matcher. Only `*` and `?` are special.
+ *
+ * This is deliberately NOT a regex. `*` compiles to `[^]*`, and `^[^]*a[^]*a…$`
+ * is the textbook catastrophic backtracker: against a tag of n characters an
+ * 8-wildcard pattern costs C(n, 8) steps — for a full-length 128-character tag
+ * that is ~10^12, hours of CPU inside one synchronous `RegExp.test` that
+ * neither `timeoutMs` nor `ctx.signal` can interrupt, because both only
+ * unblock between awaits. The two-pointer glob match below is the standard
+ * O(pattern x tag) algorithm with one backtrack point, so the worst case is
+ * bounded by the product rather than by a binomial.
+ *
+ * Comparison is by code point, so `?` means one character rather than one
+ * UTF-16 unit — the regex version needed two `?` to match an astral character.
+ */
+export declare function compileGlob(pattern: string): (value: string) => boolean;
+export declare function filterTags(tags: readonly string[], pattern: string | undefined): string[];
+export type TagsPage = {
+    readonly tags: readonly string[];
+    /** Entries that were not tags. Counted, never silently discarded. */
+    readonly malformed: number;
+};
+/**
+ * Read the `tags` array out of a `/tags/list` response. Registries have shipped
+ * `"tags": null` for an empty repository, which is not what the spec says and
+ * is exactly the shape that turns into `Cannot read properties of null`.
+ *
+ * Entries outside the tag grammar are DROPPED here rather than carried
+ * downstream, because the rest of the package treats this array as trusted and
+ * it is not: it is the one place where a string the registry chose becomes a
+ * URL path (`withDigests`) and a regex subject (`match`). A registry that says
+ * its tags include `../../victim/manifests/latest`, or a 4 KB string, is not
+ * describing something anyone can pull. The count is reported, so the answer
+ * still says the registry sent something odd.
+ */
+export declare function readTagsPage(document: Record<string, unknown>): TagsPage;
+/**
+ * Follow RFC 5988 paging — with the link kept on the registry's own origin.
+ *
+ * The `Link` header is server-controlled: a registry that answers page 1 with
+ * `Link: <https://evil.example/v2/...>; rel="next"` would otherwise have the
+ * client walk off to a host the caller never named, carrying an Accept header
+ * and a request pattern that says which images are being audited. Same origin
+ * or we stop and say why.
+ */
+export declare function nextPageUrl(header: string | null, base: URL): URL | null;

package/dist/lib/tags.js

@@ -0,0 +1,244 @@
+/**
+ * Tag lists: paging, filtering, and the sort that makes them readable.
+ *
+ * Real tag lists are mostly not semver. A typical repository holds `latest`,
+ * `edge`, `sha-9f3c1a`, `0.6`, `v0.6.0-rc.1` and `3.19-alpine` side by side, so
+ * a sort that assumes semver either throws or silently reorders the half it
+ * could not read. This one partitions: versions ordered by semver precedence
+ * first, everything else after it in plain lexicographic order, and nothing
+ * throws on a tag it cannot parse.
+ */
+import { isValidTag } from "./ref";
+export class TagListError extends Error {
+    name = "TagListError";
+}
+/**
+ * Parse a tag as a version, tolerating the two things registries do that
+ * semver does not: a leading `v`, and a truncated version (`0.6`, `3`).
+ * Build metadata is accepted and ignored for precedence, exactly as semver
+ * says, but the tag string itself still breaks ties so the sort stays total.
+ */
+export function parseTagVersion(tag) {
+    const m = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/.exec(tag);
+    if (!m)
+        return null;
+    const prerelease = m[4] === undefined ? null : m[4].split(".");
+    return {
+        major: Number.parseInt(m[1], 10),
+        minor: m[2] === undefined ? 0 : Number.parseInt(m[2], 10),
+        patch: m[3] === undefined ? 0 : Number.parseInt(m[3], 10),
+        prerelease,
+    };
+}
+/** Semver §11 precedence. Returns <0, 0 or >0. */
+export function compareVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    if (a.patch !== b.patch)
+        return a.patch - b.patch;
+    // A release outranks any prerelease of the same version: 1.0.0 > 1.0.0-rc.1.
+    if (a.prerelease === null && b.prerelease === null)
+        return 0;
+    if (a.prerelease === null)
+        return 1;
+    if (b.prerelease === null)
+        return -1;
+    const len = Math.max(a.prerelease.length, b.prerelease.length);
+    for (let i = 0; i < len; i++) {
+        const x = a.prerelease[i];
+        const y = b.prerelease[i];
+        // A shorter identifier list is lower precedence when all earlier ones tie.
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNum = /^\d+$/.test(x);
+        const yNum = /^\d+$/.test(y);
+        if (xNum && yNum) {
+            const diff = Number.parseInt(x, 10) - Number.parseInt(y, 10);
+            if (diff !== 0)
+                return diff;
+            continue;
+        }
+        // Numeric identifiers always have lower precedence than alphanumeric ones.
+        if (xNum !== yNum)
+            return xNum ? -1 : 1;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Order a tag list.
+ *
+ * `semver` is newest-first, because that is the question people actually have
+ * ("what is the latest?"), with unparseable tags collected at the end rather
+ * than interleaved by a guess. `name` is lexicographic ascending. `registry`
+ * preserves the order the registry returned, which for most registries is the
+ * order tags were pushed and for some is nothing in particular.
+ */
+export function sortTags(tags, sort) {
+    if (sort === "registry")
+        return [...tags];
+    if (sort === "name")
+        return [...tags].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const versions = new Map();
+    for (const tag of tags)
+        versions.set(tag, parseTagVersion(tag));
+    return [...tags].sort((a, b) => {
+        const va = versions.get(a) ?? null;
+        const vb = versions.get(b) ?? null;
+        if (va !== null && vb !== null) {
+            const byPrecedence = compareVersions(vb, va); // descending: newest first
+            return byPrecedence !== 0 ? byPrecedence : a < b ? -1 : a > b ? 1 : 0;
+        }
+        if (va !== null)
+            return -1;
+        if (vb !== null)
+            return 1;
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+}
+/**
+ * Compile a glob into a matcher. Only `*` and `?` are special.
+ *
+ * This is deliberately NOT a regex. `*` compiles to `[^]*`, and `^[^]*a[^]*a…$`
+ * is the textbook catastrophic backtracker: against a tag of n characters an
+ * 8-wildcard pattern costs C(n, 8) steps — for a full-length 128-character tag
+ * that is ~10^12, hours of CPU inside one synchronous `RegExp.test` that
+ * neither `timeoutMs` nor `ctx.signal` can interrupt, because both only
+ * unblock between awaits. The two-pointer glob match below is the standard
+ * O(pattern x tag) algorithm with one backtrack point, so the worst case is
+ * bounded by the product rather than by a binomial.
+ *
+ * Comparison is by code point, so `?` means one character rather than one
+ * UTF-16 unit — the regex version needed two `?` to match an astral character.
+ */
+export function compileGlob(pattern) {
+    const pat = [...pattern];
+    return (value) => globMatch(pat, [...value]);
+}
+function globMatch(pat, text) {
+    let p = 0;
+    let t = 0;
+    // The last `*` seen, and how much of the text it had consumed at the time.
+    // Re-entering there is the only backtrack this matcher ever performs.
+    let star = -1;
+    let starText = 0;
+    while (t < text.length) {
+        if (p < pat.length && (pat[p] === "?" || pat[p] === text[t])) {
+            p++;
+            t++;
+        }
+        else if (p < pat.length && pat[p] === "*") {
+            star = p;
+            starText = t;
+            p++;
+        }
+        else if (star !== -1) {
+            starText++;
+            t = starText;
+            p = star + 1;
+        }
+        else {
+            return false;
+        }
+    }
+    while (p < pat.length && pat[p] === "*")
+        p++;
+    return p === pat.length;
+}
+export function filterTags(tags, pattern) {
+    if (pattern === undefined || pattern === "")
+        return [...tags];
+    const match = compileGlob(pattern);
+    return tags.filter((t) => match(t));
+}
+/**
+ * Read the `tags` array out of a `/tags/list` response. Registries have shipped
+ * `"tags": null` for an empty repository, which is not what the spec says and
+ * is exactly the shape that turns into `Cannot read properties of null`.
+ *
+ * Entries outside the tag grammar are DROPPED here rather than carried
+ * downstream, because the rest of the package treats this array as trusted and
+ * it is not: it is the one place where a string the registry chose becomes a
+ * URL path (`withDigests`) and a regex subject (`match`). A registry that says
+ * its tags include `../../victim/manifests/latest`, or a 4 KB string, is not
+ * describing something anyone can pull. The count is reported, so the answer
+ * still says the registry sent something odd.
+ */
+export function readTagsPage(document) {
+    const raw = document["tags"];
+    if (raw === null || raw === undefined)
+        return { tags: [], malformed: 0 };
+    if (!Array.isArray(raw))
+        throw new TagListError("tags/list response has a non-array 'tags' field");
+    const tags = [];
+    let malformed = 0;
+    for (const entry of raw) {
+        if (typeof entry === "string" && isValidTag(entry))
+            tags.push(entry);
+        else
+            malformed++;
+    }
+    return { tags, malformed };
+}
+/**
+ * Follow RFC 5988 paging — with the link kept on the registry's own origin.
+ *
+ * The `Link` header is server-controlled: a registry that answers page 1 with
+ * `Link: <https://evil.example/v2/...>; rel="next"` would otherwise have the
+ * client walk off to a host the caller never named, carrying an Accept header
+ * and a request pattern that says which images are being audited. Same origin
+ * or we stop and say why.
+ */
+export function nextPageUrl(header, base) {
+    if (header === null || header.trim() === "")
+        return null;
+    for (const part of splitLinks(header)) {
+        const m = /^\s*<([^>]*)>\s*(.*)$/.exec(part);
+        if (!m)
+            continue;
+        const params = m[2];
+        if (!/\brel\s*=\s*"?next"?/i.test(params))
+            continue;
+        let url;
+        try {
+            url = new URL(m[1], base);
+        }
+        catch {
+            throw new TagListError(`registry sent an unparseable Link header: ${header}`);
+        }
+        if (url.origin !== base.origin) {
+            throw new TagListError(`registry's next-page Link points at ${url.origin}, not ${base.origin} — refusing to follow paging off the registry`);
+        }
+        return url;
+    }
+    return null;
+}
+/** Split a Link header on commas that separate entries, not ones inside <> or "". */
+function splitLinks(header) {
+    const parts = [];
+    let current = "";
+    let inAngle = false;
+    let inQuote = false;
+    for (const ch of header) {
+        if (ch === "<" && !inQuote)
+            inAngle = true;
+        else if (ch === ">" && !inQuote)
+            inAngle = false;
+        else if (ch === '"')
+            inQuote = !inQuote;
+        if (ch === "," && !inAngle && !inQuote) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim() !== "")
+        parts.push(current);
+    return parts;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@crewhaus/tool-containers",
+  "version": "0.7.0",
+  "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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./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",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-containers"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-containers#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}