@wardby/cli 0.2.0 → 0.3.0

package/dist/coding/registry/npm-lockfile.js

@@ -0,0 +1,73 @@
+/**
+ * npm lockfile normaliser. The npm adapter serves metadata whose tarball
+ * links point at the proxy, so `npm install` in the worker records those
+ * proxy URLs as `resolved` in package-lock.json / npm-shrinkwrap.json. They
+ * only resolve inside the sandbox, so before the workspace is collected every
+ * `resolved` value under the proxy's npm route is rewritten to the canonical
+ * public registry URL for the same package and version. `integrity` is left
+ * as is: it covers the same tarball bytes. Only the matched values change;
+ * the rest of the file stays byte-for-byte identical (no JSON round trip).
+ *
+ * Kept free of imports from npm.ts, which imports this module.
+ */
+import semver from "semver";
+const PUBLIC_REGISTRY = "https://registry.npmjs.org/";
+/** Same shape as the adapter's allowlist name check (scoped names are lower case). */
+export const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*|[A-Za-z0-9-~][A-Za-z0-9-._~]*)$/;
+/** A `"resolved": "<value>"` pair whose value has no JSON escapes. */
+const RESOLVED = /("resolved"\s*:\s*")([^"\\]*)(")/g;
+function decode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+function unscoped(name) {
+    return name.slice(name.indexOf("/") + 1);
+}
+/** The package and version a path under the proxy's npm base downloads:
+ *  `-/tarball/<encoded name>/<version>` (the proxy's own route) or the
+ *  standard `<name>/-/<unscoped>-<version>.tgz`, with the scope separator
+ *  literal or percent-encoded. Null for anything else. */
+function parseProxyPath(path) {
+    let name;
+    let version;
+    const own = path.match(/^-\/tarball\/([^/]+)\/([^/]+)$/);
+    if (own) {
+        name = decode(own[1]);
+        version = decode(own[2]);
+    }
+    else {
+        const standard = path.match(/^(.+)\/-\/([^/]+)\.tgz$/);
+        if (!standard)
+            return null;
+        name = decode(standard[1]);
+        const file = decode(standard[2]);
+        if (!name || !file)
+            return null;
+        const prefix = `${unscoped(name)}-`;
+        version = file.startsWith(prefix) ? file.slice(prefix.length) : null;
+    }
+    if (!name || !version || !PACKAGE_NAME.test(name) || semver.valid(version) !== version)
+        return null;
+    return { name, version };
+}
+/** `https://registry.npmjs.org/@scope/pkg/-/pkg-1.0.0.tgz` */
+export function publicNpmTarballUrl(name, version) {
+    return `${PUBLIC_REGISTRY}${name}/-/${unscoped(name)}-${version}.tgz`;
+}
+export function normalizeNpmLockfile(content, registryUrl) {
+    const base = registryUrl.endsWith("/") ? registryUrl : `${registryUrl}/`;
+    return content.replace(RESOLVED, (match, open, url, close) => {
+        if (!url.startsWith(base))
+            return match;
+        const target = parseProxyPath(url.slice(base.length));
+        return target ? `${open}${publicNpmTarballUrl(target.name, target.version)}${close}` : match;
+    });
+}
+export const npmLockfiles = {
+    names: ["package-lock.json", "npm-shrinkwrap.json"],
+    normalize: normalizeNpmLockfile,
+};

package/dist/coding/registry/npm-plan.d.ts

@@ -0,0 +1,29 @@
+import { type DeclaredDependency, type LockfilePlanSupport, type ParsedLockfile, type UpstreamFetch, type VersionFact } from "./types.js";
+/** The registry dependencies a manifest's dependency map declares: each
+ *  one's install folder (`key`), the registry package it installs (an
+ *  alias `"string-width-cjs": "npm:string-width@^4"` installs its target,
+ *  under the alias's own range) and its range. A spec that isn't fetched
+ *  from the registry at all (`file:`, `link:`, a path, `git`/`git+…`, an
+ *  `http(s):` tarball, `github:`/`user/repo` shorthands, `workspace:`)
+ *  contributes nothing: every such spec contains a `:` or a `/`, which no
+ *  semver range or dist-tag does. */
+export declare function registryDependencyEdges(deps: unknown): DeclaredDependency[];
+/** Every registry dependency a manifest declares, in npm's install order
+ *  (dependencies, optionalDependencies, peerDependencies), once per
+ *  install folder: npm lists an optional dependency under `dependencies`
+ *  too, and the first declaration of a folder is the one npm uses. */
+export declare function declaredDependencies(manifest: Record<string, unknown>, fields: readonly string[]): DeclaredDependency[];
+export declare function parseNpmLockfile(body: string, options: {
+    maxEntries: number;
+    proxyRegistryUrl: string;
+}): ParsedLockfile;
+export declare function fetchNpmVersionFact(name: string, version: string, upstream: UpstreamFetch, signal?: AbortSignal): Promise<VersionFact | null>;
+export declare function fetchNpmPublishTimes(name: string, versions: readonly string[], upstream: UpstreamFetch, options: {
+    maxBytes: number;
+    signal: AbortSignal;
+}): Promise<Map<string, Date>>;
+/** Whether a locked version satisfies a declared range: `*` and dist-tags
+ *  accept any version (as npm's own dep-valid does), otherwise strict semver,
+ *  the same match the graph walk uses. */
+export declare function npmEdgeSatisfies(version: string, range: string): boolean;
+export declare const npmLockfilePlan: LockfilePlanSupport;

package/dist/coding/registry/npm-plan.js

@@ -0,0 +1,289 @@
+/**
+ * npm lockfile verification hooks (`POST /registry/npm/-/plan`): parsing a
+ * package-lock.json (lockfileVersion 2 or 3) into entries and npm's own
+ * node_modules resolution rule, and reading the registry's per-version
+ * facts and publish times. Nothing here decides anything: the registry core
+ * verifies every claim against these registry reads (plan.ts).
+ *
+ * Kept free of imports from npm.ts, which imports this module.
+ */
+import semver from "semver";
+import { PACKAGE_NAME } from "./npm-lockfile.js";
+import { JsonMemberTooLarge, scanTopLevelMember } from "./json-scan.js";
+import { RegistryError, } from "./types.js";
+const UPSTREAM = "https://registry.npmjs.org/";
+const NODE_MODULES = "node_modules/";
+/** The largest `time` object kept from a packument (a package with tens of
+ *  thousands of versions has a few MB of it). */
+const MAX_TIME_TEXT = 16 * 1024 * 1024;
+/** A declared semver range as written, or `"*"` for anything that is not
+ *  a valid range (a dist-tag such as `latest`, an empty spec): npm
+ *  resolves those to some published version, so any version counts. */
+function rangeOf(spec) {
+    return spec !== "" && semver.validRange(spec) ? spec : "*";
+}
+/** The registry dependencies a manifest's dependency map declares: each
+ *  one's install folder (`key`), the registry package it installs (an
+ *  alias `"string-width-cjs": "npm:string-width@^4"` installs its target,
+ *  under the alias's own range) and its range. A spec that isn't fetched
+ *  from the registry at all (`file:`, `link:`, a path, `git`/`git+…`, an
+ *  `http(s):` tarball, `github:`/`user/repo` shorthands, `workspace:`)
+ *  contributes nothing: every such spec contains a `:` or a `/`, which no
+ *  semver range or dist-tag does. */
+export function registryDependencyEdges(deps) {
+    const edges = [];
+    if (!deps || typeof deps !== "object")
+        return edges;
+    for (const [key, rawSpec] of Object.entries(deps)) {
+        const spec = typeof rawSpec === "string" ? rawSpec.trim() : "";
+        if (spec.startsWith("npm:")) {
+            const target = spec.slice("npm:".length);
+            const at = target.indexOf("@", 1);
+            const name = at > 0 ? target.slice(0, at) : target;
+            if (PACKAGE_NAME.test(name))
+                edges.push({ key, name, range: rangeOf(at > 0 ? target.slice(at + 1) : "") });
+            continue;
+        }
+        if (/[:/]/.test(spec))
+            continue;
+        edges.push({ key, name: key, range: rangeOf(spec) });
+    }
+    return edges;
+}
+/** Every registry dependency a manifest declares, in npm's install order
+ *  (dependencies, optionalDependencies, peerDependencies), once per
+ *  install folder: npm lists an optional dependency under `dependencies`
+ *  too, and the first declaration of a folder is the one npm uses. */
+export function declaredDependencies(manifest, fields) {
+    const byKey = new Map();
+    for (const field of fields) {
+        for (const edge of registryDependencyEdges(manifest[field]))
+            if (!byKey.has(edge.key))
+                byKey.set(edge.key, edge);
+    }
+    return [...byKey.values()];
+}
+const PUBLISHED_FIELDS = ["dependencies", "optionalDependencies", "peerDependencies"];
+/** A project's own declarations, dev dependencies included (they are
+ *  installed for the project, never for a dependency). */
+const PROJECT_FIELDS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+function badRequest(message) {
+    return new RegistryError(400, "wardby_bad_request", message);
+}
+/** The folder a `node_modules/...` path installs, e.g. `@s/a` for
+ *  `node_modules/x/node_modules/@s/a`; undefined for a path outside any
+ *  node_modules folder (a workspace project). */
+function installFolder(path) {
+    const at = path.lastIndexOf(NODE_MODULES);
+    if (at < 0 || (at > 0 && path[at - 1] !== "/"))
+        return undefined;
+    return path.slice(at + NODE_MODULES.length);
+}
+/** Whether `resolved` names a registry download: the public registry, or
+ *  the proxy's own npm route (a lockfile written through the proxy before
+ *  it is normalized at collection). A missing `resolved` is a registry
+ *  entry too: npm omits it for one it will fetch from the registry. */
+function fromRegistry(resolved, proxyRegistryUrl) {
+    if (resolved === undefined)
+        return true;
+    if (typeof resolved !== "string")
+        return false;
+    return resolved.startsWith(UPSTREAM) || resolved.startsWith(proxyRegistryUrl);
+}
+export function parseNpmLockfile(body, options) {
+    let document;
+    try {
+        document = JSON.parse(body);
+    }
+    catch {
+        throw badRequest("the lockfile is not valid JSON");
+    }
+    if (!document || typeof document !== "object" || Array.isArray(document))
+        throw badRequest("the lockfile is not a JSON object");
+    const lock = document;
+    if (lock.lockfileVersion !== 2 && lock.lockfileVersion !== 3) {
+        throw new RegistryError(400, "wardby_lockfile_unsupported", `lockfileVersion ${JSON.stringify(lock.lockfileVersion ?? null)} is not supported; regenerate the lockfile with npm 7 or later (lockfileVersion 2 or 3)`);
+    }
+    if (!lock.packages || typeof lock.packages !== "object" || Array.isArray(lock.packages))
+        throw new RegistryError(400, "wardby_lockfile_unsupported", "the lockfile has no `packages` section");
+    const packages = lock.packages;
+    const count = Object.keys(packages).length - ("" in packages ? 1 : 0);
+    if (count > options.maxEntries) {
+        throw new RegistryError(413, "wardby_lockfile_too_large", `the lockfile has ${count} entries; at most ${options.maxEntries} are verified (REGISTRY_PLAN_MAX_ENTRIES)`);
+    }
+    const entries = [];
+    const byPath = new Map();
+    /** Paths of link entries (symlinks to local projects): a dependency
+     *  resolving to one is local, not a registry entry. */
+    const links = new Set();
+    const projects = [];
+    for (const [path, raw] of Object.entries(packages)) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw badRequest(`lockfile entry "${path}" is not an object`);
+        const value = raw;
+        const folder = installFolder(path);
+        if (path === "" || folder === undefined) {
+            // The root project, or a workspace project's own folder.
+            projects.push({ path, dependencies: declaredDependencies(value, PROJECT_FIELDS) });
+            continue;
+        }
+        if (value.link === true) {
+            links.add(path);
+            continue;
+        }
+        const name = typeof value.name === "string" ? value.name : folder;
+        const version = typeof value.version === "string" ? value.version : "";
+        const integrity = typeof value.integrity === "string" ? value.integrity : null;
+        let entry;
+        if (value.inBundle === true) {
+            entry = { path, name, version, integrity, kind: "bundled" };
+        }
+        else if (!PACKAGE_NAME.test(name) || semver.valid(version) !== version) {
+            entry = {
+                path,
+                name,
+                version,
+                integrity,
+                kind: "unsupported",
+                unsupportedReason: "not a registry package name and exact version",
+            };
+        }
+        else if (!fromRegistry(value.resolved, options.proxyRegistryUrl)) {
+            entry = {
+                path,
+                name,
+                version,
+                integrity,
+                kind: "unsupported",
+                unsupportedReason: "installed from outside the npm registry",
+            };
+        }
+        else {
+            entry = { path, name, version, integrity, kind: "registry" };
+        }
+        entries.push(entry);
+        byPath.set(path, entry);
+    }
+    const resolve = (fromPath, key) => {
+        // npm searches the package's own node_modules, then each enclosing
+        // package's (never a bare `node_modules` or `@scope` folder), then the
+        // root's; a workspace project's enclosing package is the root.
+        let directory = fromPath;
+        for (;;) {
+            const candidate = `${directory === "" ? "" : `${directory}/`}${NODE_MODULES}${key}`;
+            if (links.has(candidate))
+                return undefined;
+            const found = byPath.get(candidate);
+            if (found)
+                return found;
+            if (directory === "")
+                return undefined;
+            const enclosing = directory.lastIndexOf(`/${NODE_MODULES}`);
+            directory = enclosing < 0 ? "" : directory.slice(0, enclosing);
+        }
+    };
+    return { entries, projects, resolve };
+}
+function encodedName(name) {
+    return name.replaceAll("/", "%2f");
+}
+/** npm's SRI integrity for a dist record: `integrity` as published, or,
+ *  for a version published before npm recorded one, its sha1 `shasum` in
+ *  SRI form (what npm itself records in a lockfile for such a version). */
+function distIntegrity(dist) {
+    if (!dist || typeof dist !== "object")
+        return "";
+    const { integrity, shasum } = dist;
+    if (typeof integrity === "string" && integrity.trim() !== "")
+        return integrity.trim();
+    if (typeof shasum === "string" && /^[a-f0-9]{40}$/.test(shasum))
+        return `sha1-${Buffer.from(shasum, "hex").toString("base64")}`;
+    return "";
+}
+export async function fetchNpmVersionFact(name, version, upstream, signal) {
+    const response = await upstream(`${UPSTREAM}${encodedName(name)}/${encodeURIComponent(version)}`, {
+        accept: "application/json",
+        signal,
+    });
+    if (response.status === 404) {
+        await response.body?.cancel().catch(() => undefined);
+        return null;
+    }
+    if (!response.ok)
+        throw new RegistryError(502, "wardby_upstream_error", `npm returned ${response.status}`);
+    const doc = (await response.json());
+    // The registry also answers a dist-tag here (`/react/latest`), and a
+    // lockfile version is exact, so the answer must be that exact version.
+    if (doc.name !== name || doc.version !== version)
+        return null;
+    const dist = doc.dist;
+    return {
+        name,
+        version,
+        publishedAt: null,
+        integrity: distIntegrity(dist),
+        downloadUrl: typeof dist?.tarball === "string" ? dist.tarball : "",
+        dependencies: declaredDependencies(doc, PUBLISHED_FIELDS),
+    };
+}
+export async function fetchNpmPublishTimes(name, versions, upstream, options) {
+    const response = await upstream(`${UPSTREAM}${encodedName(name)}`, {
+        accept: "application/json",
+        acceptEncoding: "gzip",
+        signal: options.signal,
+    });
+    if (!response.ok || !response.body) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new RegistryError(response.status === 404 ? 404 : 502, response.status === 404 ? "wardby_package_not_found" : "wardby_upstream_error", `npm returned ${response.status} for "${name}"`);
+    }
+    const encoding = response.headers.get("content-encoding")?.trim().toLowerCase();
+    let body = response.body;
+    if (encoding === "gzip")
+        body = body.pipeThrough(new DecompressionStream("gzip"));
+    else if (encoding && encoding !== "identity") {
+        await body.cancel().catch(() => undefined);
+        throw new RegistryError(502, "wardby_upstream_error", `npm answered with an unsupported content-encoding`);
+    }
+    let time;
+    try {
+        // maxBytes bounds the decompressed document, so a small compressed
+        // body cannot expand without limit.
+        time = await scanTopLevelMember(body, "time", { maxBytes: options.maxBytes, maxValueLength: MAX_TIME_TEXT });
+    }
+    catch (error) {
+        if (error instanceof JsonMemberTooLarge)
+            throw new RegistryError(502, "wardby_metadata_too_large", `npm metadata for "${name}" is too large`);
+        throw error;
+    }
+    const times = new Map();
+    if (!time || typeof time !== "object")
+        return times;
+    for (const version of versions) {
+        const value = time[version];
+        if (typeof value !== "string")
+            continue;
+        const date = new Date(value);
+        if (!Number.isNaN(date.getTime()))
+            times.set(version, date);
+    }
+    return times;
+}
+/** Whether a locked version satisfies a declared range: `*` and dist-tags
+ *  accept any version (as npm's own dep-valid does), otherwise strict semver,
+ *  the same match the graph walk uses. */
+export function npmEdgeSatisfies(version, range) {
+    if (range === "*" || range === "")
+        return true;
+    try {
+        return semver.satisfies(version, range);
+    }
+    catch {
+        return false;
+    }
+}
+export const npmLockfilePlan = {
+    parse: parseNpmLockfile,
+    fetchVersionFact: fetchNpmVersionFact,
+    fetchPublishTimes: fetchNpmPublishTimes,
+    edgeSatisfies: npmEdgeSatisfies,
+};

package/dist/coding/registry/npm.d.ts

@@ -0,0 +1,7 @@
+import { type DependencySpec, type RegistryAdapter } from "./types.js";
+/** The registry package each dependency entry installs, and the range it
+ *  asks for (aliases resolved, non-registry specs dropped; see
+ *  registryDependencyEdges). This is the single place both the metadata
+ *  path and the graph walk get dependency names from. */
+export declare function registryDependencies(deps: Record<string, string> | undefined): DependencySpec[];
+export declare const npmAdapter: RegistryAdapter;

package/dist/coding/registry/npm.js

@@ -0,0 +1,252 @@
+/**
+ * npm registry adapter: parses npm allowlist syntax and semver ranges,
+ * routes proxy requests against the npm HTTP protocol (packuments,
+ * `-/tarball/<name>/<version>` downloads, and the standard
+ * `<name>/-/<unscoped>-<version>.tgz` path lockfiles record), and configures npm/npmrc for
+ * the sandboxed worker to use the proxy with install-time scripts disabled.
+ */
+import semver from "semver";
+import { npmLockfiles } from "./npm-lockfile.js";
+import { npmLockfilePlan, registryDependencyEdges } from "./npm-plan.js";
+import { AllowlistEntryError, RegistryError, } from "./types.js";
+/** Scoped names are lower case (npm never allowed capitals in them); an
+ *  unscoped legacy name may contain capitals, and npm treats it as a
+ *  different package from its lower-case spelling (`JSONStream` is not
+ *  `jsonstream`), so names are never case-folded anywhere. */
+const NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*|[A-Za-z0-9-~][A-Za-z0-9-._~]*)$/;
+const SCOPE_WILDCARD = /^(@[a-z0-9-~][a-z0-9-._~]*)\/\*$/;
+const UPSTREAM = "https://registry.npmjs.org/";
+/** The per-version fields npm's installer reads (the same set as npm's
+ *  abbreviated "install-v1" manifest). Only these are kept from an
+ *  upstream packument, so the cached metadata never holds readmes,
+ *  descriptions, maintainers and other bulk the proxy does not render. */
+const MANIFEST_FIELDS = [
+    "name",
+    "version",
+    "dist",
+    "dependencies",
+    "optionalDependencies",
+    "devDependencies",
+    "peerDependencies",
+    "peerDependenciesMeta",
+    "bundleDependencies",
+    "bundledDependencies",
+    "acceptDependencies",
+    "bin",
+    "directories",
+    "engines",
+    "os",
+    "cpu",
+    "libc",
+    "deprecated",
+    "hasInstallScript",
+    "_hasShrinkwrap",
+    "license",
+    "funding",
+];
+function abbreviated(manifest) {
+    const source = manifest;
+    const kept = Object.fromEntries(MANIFEST_FIELDS.filter((field) => field in source).map((f) => [f, source[f]]));
+    return kept;
+}
+function integrityOf(dist) {
+    const sri = dist.integrity?.match(/^(sha512|sha384|sha256)-([A-Za-z0-9+/=]+)$/);
+    if (sri)
+        return { algorithm: sri[1], hex: Buffer.from(sri[2], "base64").toString("hex") };
+    if (dist.shasum && /^[a-f0-9]{40}$/.test(dist.shasum))
+        return { algorithm: "sha1", hex: dist.shasum };
+    return null;
+}
+/** The registry package each dependency entry installs, and the range it
+ *  asks for (aliases resolved, non-registry specs dropped; see
+ *  registryDependencyEdges). This is the single place both the metadata
+ *  path and the graph walk get dependency names from. */
+export function registryDependencies(deps) {
+    return registryDependencyEdges(deps).map(({ name, range }) => ({ name, range }));
+}
+/** Maps `<name>/-/<unscoped>-<version>.tgz` (already percent-decoded) to
+ *  the same download route as `-/tarball/<name>/<version>`, or null. The
+ *  filename must name this exact package (case-sensitive, as npm names
+ *  are) and an exact semver version, so it can never smuggle a path
+ *  separator or `..` through: neither can appear in a valid version. */
+function standardTarball(name, filename) {
+    if (!NAME.test(name))
+        return null;
+    const unscoped = name.slice(name.indexOf("/") + 1);
+    const prefix = `${unscoped}-`;
+    if (!filename.startsWith(prefix) || !filename.endsWith(".tgz"))
+        return null;
+    const version = filename.slice(prefix.length, -".tgz".length);
+    if (semver.valid(version) !== version)
+        return null;
+    return { kind: "download", name, version, filename: `${version}.tgz` };
+}
+function validName(name) {
+    if (!NAME.test(name))
+        throw new AllowlistEntryError(`"${name}" is not a valid npm package name`);
+    return name;
+}
+/** Per-version fixed cost, in bytes, of the trimmed form (Map entry,
+ *  VersionInfo, FileRef, Date, arrays), used only for the metadata cache's
+ *  byte budget. Deliberately generous. */
+const VERSION_OVERHEAD_BYTES = 400;
+const DEPENDENCY_OVERHEAD_BYTES = 80;
+/** Extracts what the proxy uses from a full packument, copying every value
+ *  it keeps, so the document itself is never retained: per version its
+ *  dependency specs, publish time, tarball URL and integrity (all the graph
+ *  walk, the version filter and downloads read), plus, with `render`, the
+ *  data `renderMetadata` serves. */
+function trimPackument(name, doc, render) {
+    const versions = new Map();
+    const renderData = render
+        ? { name: String(doc.name), distTags: { ...(doc["dist-tags"] ?? {}) }, manifests: new Map(), times: new Map() }
+        : undefined;
+    let approxBytes = 256 + name.length;
+    for (const [version, info] of Object.entries(doc.versions ?? {})) {
+        const published = doc.time?.[version];
+        const dependencySpecs = [info.dependencies, info.optionalDependencies, info.peerDependencies].flatMap((deps) => registryDependencies(deps));
+        const dependencies = [...new Set(dependencySpecs.map((spec) => spec.name))];
+        const file = {
+            filename: `${version}.tgz`,
+            version,
+            upstreamUrl: String(info.dist.tarball),
+            integrity: integrityOf(info.dist),
+            sizeBytes: null,
+            allowed: true,
+            publishedAt: published ? new Date(published) : null,
+        };
+        versions.set(version, { version, dependencies, dependencySpecs, files: [file] });
+        approxBytes += VERSION_OVERHEAD_BYTES + 2 * version.length + file.upstreamUrl.length;
+        approxBytes += file.integrity?.hex.length ?? 0;
+        for (const spec of dependencySpecs)
+            approxBytes += DEPENDENCY_OVERHEAD_BYTES + spec.name.length + spec.range.length;
+        if (renderData) {
+            const manifest = JSON.stringify(abbreviated(info));
+            renderData.manifests.set(version, manifest);
+            approxBytes += manifest.length + 64;
+            if (published) {
+                renderData.times.set(version, String(published));
+                approxBytes += published.length + 64;
+            }
+        }
+    }
+    return { name, versions, raw: renderData, approxBytes };
+}
+export const npmAdapter = {
+    id: "npm",
+    osvEcosystem: "npm",
+    upstreamHosts: ["registry.npmjs.org"],
+    collectExclude: ["node_modules"],
+    dependenciesInMetadata: true,
+    lockfiles: npmLockfiles,
+    lockfilePlan: npmLockfilePlan,
+    parseAllowlistEntry(raw) {
+        const value = raw.trim();
+        // Scopes are always lower case on npm, so folding one cannot select a
+        // different package; package names are kept exactly as written.
+        const scope = value.toLowerCase().match(SCOPE_WILDCARD);
+        if (scope)
+            return { name: `${scope[1]}/`, wildcard: true };
+        const at = value.indexOf("@", 1);
+        const name = validName(at > 0 ? value.slice(0, at) : value);
+        if (at < 0)
+            return { name, wildcard: false };
+        const range = value.slice(at + 1);
+        if (!semver.validRange(range))
+            throw new AllowlistEntryError(`"${range}" is not a valid npm version range`);
+        return { name, wildcard: false, range };
+    },
+    normalizeName: (name) => name,
+    satisfies: (version, range) => semver.satisfies(version, range),
+    compareVersions(a, b) {
+        if (!semver.valid(a) || !semver.valid(b))
+            throw new Error(`not a semver version: "${a}" / "${b}"`);
+        return semver.compare(a, b);
+    },
+    route(method, subpath) {
+        if (method !== "GET" && method !== "HEAD")
+            return null;
+        const tarball = subpath.match(/^-\/tarball\/([^/]+)\/([^/]+)$/);
+        // The standard upstream tarball path, `<name>/-/<unscoped>-<version>.tgz`,
+        // which a lockfile's `resolved` URLs point at once npm rewrites their
+        // host to the configured registry (replace-registry-host). The name is
+        // one segment (`react`, `@scope%2fpkg`) or a literal scope plus name
+        // (`@scope/pkg`); the filename is one raw segment.
+        const standard = subpath.match(/^((?:@[^/]+\/)?[^/]+)\/-\/([^/]+)$/);
+        try {
+            if (tarball) {
+                const name = decodeURIComponent(tarball[1]);
+                const version = decodeURIComponent(tarball[2]);
+                if (!NAME.test(name) || !semver.valid(version))
+                    return null;
+                return { kind: "download", name, version, filename: `${version}.tgz` };
+            }
+            if (standard)
+                return standardTarball(decodeURIComponent(standard[1]), decodeURIComponent(standard[2]));
+            const name = decodeURIComponent(subpath);
+            return NAME.test(name) ? { kind: "metadata", name } : null;
+        }
+        catch {
+            throw new RegistryError(400, "wardby_bad_request", "malformed percent-encoding in the registry path");
+        }
+    },
+    async fetchMetadata(name, upstream, options = {}) {
+        const response = await upstream(`${UPSTREAM}${name.replaceAll("/", "%2f")}`, { accept: "application/json" });
+        if (response.status === 404)
+            throw new RegistryError(404, "wardby_package_not_found", `npm has no package "${name}"`);
+        if (!response.ok)
+            throw new RegistryError(502, "wardby_upstream_error", `npm returned ${response.status}`);
+        // The full packument is only ever a local of `trimPackument`: nothing
+        // returned from here references it, so it is garbage as soon as the
+        // trimmed form is built (a large one is tens of MB parsed).
+        return trimPackument(name, (await response.json()), options.render === true);
+    },
+    renderMetadata(meta, keep, keptFiles, proxyBase) {
+        const raw = meta.raw;
+        if (!raw)
+            throw new Error(`npm metadata for "${meta.name}" was fetched without render data`);
+        const versions = {};
+        const time = {};
+        for (const version of keep) {
+            const manifest = raw.manifests.get(version);
+            if (manifest === undefined || !keptFiles.has(`${version}.tgz`))
+                continue;
+            const info = JSON.parse(manifest);
+            versions[version] = {
+                ...info,
+                dist: { ...info.dist, tarball: `${proxyBase}-/tarball/${encodeURIComponent(meta.name)}/${version}` },
+            };
+            const published = raw.times.get(version);
+            if (published !== undefined)
+                time[version] = published;
+        }
+        const kept = Object.keys(versions);
+        const tags = Object.fromEntries(Object.entries(raw.distTags).filter(([, version]) => kept.includes(version)));
+        if (!tags.latest && kept.length > 0)
+            tags.latest = semver.maxSatisfying(kept, "*") ?? kept[kept.length - 1];
+        return {
+            contentType: "application/json",
+            body: JSON.stringify({ name: raw.name, "dist-tags": tags, time, versions }),
+        };
+    },
+    resolveDownload(route, meta) {
+        return meta.versions.get(route.version)?.files.find((file) => file.filename === route.filename) ?? null;
+    },
+    workerConfig({ registryUrl, token, cacheDir }) {
+        const npmrc = `${cacheDir}/npmrc`;
+        return {
+            env: {
+                npm_config_registry: registryUrl,
+                npm_config_userconfig: npmrc,
+                npm_config_ignore_scripts: "true",
+                npm_config_cache: cacheDir,
+                npm_config_audit: "false",
+                npm_config_fund: "false",
+                npm_config_update_notifier: "false",
+                // The only registry the npm shim (npm-shim.mjs) sends a lockfile to.
+                WARDBY_NPM_PLAN_REGISTRY: registryUrl,
+            },
+            files: [{ path: npmrc, content: `${registryUrl.replace(/^https?:/, "")}:_authToken=${token}\n`, mode: 0o600 }],
+        };
+    },
+};

package/dist/coding/registry/pypi.d.ts

@@ -0,0 +1,4 @@
+import { type RegistryAdapter } from "./types.js";
+export declare function normalizePypiName(name: string): string;
+export declare function requiresDist(metadataText: string): string[];
+export declare const pypiAdapter: RegistryAdapter;