akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/registry/network.js

@@ -0,0 +1,279 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { isIP } from "node:net";
+import { bareHostname, classifyNetworkAddress, classifyNetworkHostname, resolveHostnameAddresses, } from "../core/network-policy.js";
+import { assertRegistryPinnedTransportAvailable, requestRegistryAddressPinned, } from "./pinned-transport.js";
+export { requestRegistryAddressPinned } from "./pinned-transport.js";
+export class RegistryNetworkError extends Error {
+    code = "REGISTRY_NETWORK_POLICY";
+    constructor(message) {
+        super(message);
+        this.name = "RegistryNetworkError";
+    }
+}
+const GITHUB_API_ORIGIN = "https://api.github.com";
+const MAX_REGISTRY_REDIRECTS = 8;
+const MAX_REGISTRY_RETRY_DELAY_MS = 30_000;
+let allowRegistryFixturesForTests = false;
+let registryHostnameResolverForTests;
+let registryPinnedRequestForTests;
+/**
+ * Single outbound HTTP boundary for registry metadata requests.
+ *
+ * Every retry and redirect returns through this function's resolve, validate,
+ * and pinned-connect sequence before another request can start.
+ */
+export async function fetchRegistryResponse(rawUrl, init, options, redirectCount = 0) {
+    const url = parseRegistryUrl(rawUrl);
+    const response = await requestRegistryHop(url, init, options);
+    if (!isRedirect(response.status))
+        return response;
+    if (options.policy.kind === "github-api") {
+        await cancelRegistryResponse(response);
+        throw new RegistryNetworkError("GitHub API registry metadata policy does not permit redirects");
+    }
+    if (redirectCount >= MAX_REGISTRY_REDIRECTS) {
+        await cancelRegistryResponse(response);
+        throw new RegistryNetworkError(`Too many redirects while fetching registry metadata from ${url.origin}`);
+    }
+    const location = response.headers.get("location");
+    if (!location) {
+        await cancelRegistryResponse(response);
+        throw new RegistryNetworkError(`Redirect from registry host ${url.hostname} did not include Location`);
+    }
+    await cancelRegistryResponse(response);
+    let nextUrl;
+    try {
+        nextUrl = new URL(location, url);
+    }
+    catch {
+        throw new RegistryNetworkError(`Redirect from registry host ${url.hostname} included an invalid Location`);
+    }
+    const nextInit = redirectInit(init, url, nextUrl, response.status);
+    return fetchRegistryResponse(nextUrl.toString(), nextInit, options, redirectCount + 1);
+}
+async function requestRegistryHop(url, init, options) {
+    const maxRetries = options.retries ?? 3;
+    const injectedTransport = options.requestPinnedForTesting ?? registryPinnedRequestForTests;
+    if (!injectedTransport)
+        assertRegistryPinnedTransportAvailable();
+    const transport = injectedTransport ?? requestRegistryAddressPinned;
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+        const attemptDeadline = Date.now() + options.timeoutMs;
+        const allowPrivate = privateNetworkAllowed(url, options);
+        const addresses = await validatedRegistryAddresses(url, options, allowPrivate, options.timeoutMs, init?.signal);
+        if (Date.now() >= attemptDeadline) {
+            throw new RegistryNetworkError(`Registry request to ${url.hostname} attempt deadline expired before transport could start`);
+        }
+        const address = addresses[attempt % addresses.length];
+        if (!address) {
+            throw new RegistryNetworkError(`Refusing registry request to ${url.hostname}: no validated address available`);
+        }
+        try {
+            const remainingMs = attemptDeadline - Date.now();
+            if (remainingMs <= 0) {
+                throw new RegistryNetworkError(`Registry request to ${url.hostname} attempt deadline expired before transport could start`);
+            }
+            const response = await transport(url, address, init, remainingMs);
+            if (attempt < maxRetries && shouldRetry(response.status)) {
+                const delay = retryDelay(response, attempt);
+                await cancelRegistryResponse(response);
+                await abortableDelay(delay, init?.signal);
+                continue;
+            }
+            return response;
+        }
+        catch (error) {
+            if (attempt >= maxRetries || init?.signal?.aborted)
+                throw error;
+            await abortableDelay(backoffDelay(attempt), init?.signal);
+        }
+    }
+    throw new Error("Registry retry loop is unreachable");
+}
+function parseRegistryUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new RegistryNetworkError("Registry request URL is invalid");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new RegistryNetworkError(`Registry requests require HTTP(S), not ${url.protocol || "an empty scheme"}`);
+    }
+    if (url.username || url.password) {
+        throw new RegistryNetworkError(`Registry request URL must not contain embedded credentials: ${url.hostname}`);
+    }
+    return url;
+}
+function privateNetworkAllowed(url, options) {
+    if (options.allowPrivateHostsForTesting === true)
+        return true;
+    if (options.policy.kind !== "npm-api" || !options.policy.allowPrivateRegistryOrigin)
+        return false;
+    const expectedOrigin = normalizedOrigin(options.policy.registryOrigin, "npm registry");
+    return url.origin === expectedOrigin;
+}
+async function validatedRegistryAddresses(url, options, allowPrivate, timeoutMs, signal) {
+    assertPolicyOrigin(url, options.policy);
+    const hostname = bareHostname(url.hostname);
+    const literal = isIP(hostname) !== 0;
+    const hostClass = classifyNetworkHostname(hostname);
+    assertAllowedClass(hostClass, hostname, allowPrivate);
+    if (literal)
+        return [hostname];
+    let addresses;
+    try {
+        addresses = await resolveAddressesWithDeadline(hostname, options.resolveHostname ?? registryHostnameResolverForTests, timeoutMs, signal);
+    }
+    catch (error) {
+        if (error instanceof RegistryNetworkError || signal?.aborted)
+            throw error;
+        throw new RegistryNetworkError(`Refusing registry request to ${hostname}: DNS resolution failed`);
+    }
+    if (addresses.length === 0) {
+        throw new RegistryNetworkError(`Refusing registry request to ${hostname}: hostname resolved to no addresses`);
+    }
+    for (const address of addresses) {
+        const addressClass = classifyNetworkAddress(address);
+        assertAllowedClass(addressClass, `${hostname} (${address})`, allowPrivate, true);
+    }
+    return addresses;
+}
+async function resolveAddressesWithDeadline(hostname, resolver, timeoutMs, signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error("Registry request aborted");
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            action();
+        };
+        const onAbort = () => finish(() => reject(signal?.reason ?? new Error("Registry request aborted")));
+        const timer = setTimeout(() => finish(() => reject(new RegistryNetworkError(`Refusing registry request to ${hostname}: DNS resolution timed out after ${timeoutMs}ms`))), Math.max(1, timeoutMs));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        void resolveHostnameAddresses(hostname, resolver).then((addresses) => finish(() => resolve(addresses)), (error) => finish(() => reject(error)));
+    });
+}
+function assertPolicyOrigin(url, policy) {
+    if (policy.kind === "github-api" && url.origin !== GITHUB_API_ORIGIN) {
+        throw new RegistryNetworkError(`GitHub API origin policy rejected registry request to ${url.origin}`);
+    }
+    if (policy.kind === "npm-api") {
+        const expected = normalizedOrigin(policy.registryOrigin, "npm registry");
+        if (url.origin !== expected && classifyNetworkHostname(url.hostname) !== "public") {
+            throw new RegistryNetworkError(`npm registry redirect policy rejected non-public origin ${url.origin}`);
+        }
+    }
+}
+function normalizedOrigin(rawUrl, label) {
+    try {
+        return new URL(rawUrl).origin;
+    }
+    catch {
+        throw new RegistryNetworkError(`Configured ${label} origin is invalid`);
+    }
+}
+function assertAllowedClass(addressClass, destination, allowPrivate, resolved = false) {
+    if (addressClass === "public")
+        return;
+    if (allowPrivate && (addressClass === "private" || addressClass === "loopback"))
+        return;
+    const qualifier = resolved ? "resolves to " : "is ";
+    throw new RegistryNetworkError(`Refusing registry request: ${destination} ${qualifier}non-public ${addressClass} destination`);
+}
+function redirectInit(init, currentUrl, nextUrl, status) {
+    if (!init)
+        return init;
+    const headers = new Headers(init.headers);
+    if (currentUrl.origin !== nextUrl.origin) {
+        headers.delete("authorization");
+        headers.delete("cookie");
+        headers.delete("proxy-authorization");
+    }
+    const method = (init.method ?? "GET").toUpperCase();
+    const switchToGet = ((status === 301 || status === 302) && method === "POST") ||
+        (status === 303 && method !== "GET" && method !== "HEAD");
+    if (!switchToGet)
+        return { ...init, headers };
+    for (const name of ["content-encoding", "content-language", "content-length", "content-location", "content-type"]) {
+        headers.delete(name);
+    }
+    return { ...init, method: "GET", body: undefined, headers };
+}
+function isRedirect(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/** Release a terminal response body so pinned helper/socket resources cannot linger. */
+export async function cancelRegistryResponse(response) {
+    await response.body?.cancel().catch(() => undefined);
+}
+function shouldRetry(status) {
+    return status === 429 || status >= 500;
+}
+function retryDelay(response, attempt) {
+    const retryAfter = response.headers.get("retry-after");
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds)) {
+            return seconds >= 0 ? Math.min(MAX_REGISTRY_RETRY_DELAY_MS, seconds * 1_000) : backoffDelay(attempt);
+        }
+        const date = Date.parse(retryAfter);
+        if (Number.isFinite(date))
+            return Math.min(MAX_REGISTRY_RETRY_DELAY_MS, Math.max(0, date - Date.now()));
+    }
+    return backoffDelay(attempt);
+}
+function backoffDelay(attempt) {
+    return Math.min(MAX_REGISTRY_RETRY_DELAY_MS, 500 * 2 ** attempt * (0.5 + Math.random() * 0.5));
+}
+/** Test-only visibility for the server-controlled Retry-After clamp. */
+export function _registryRetryDelayForTests(response, attempt) {
+    return retryDelay(response, attempt);
+}
+function abortableDelay(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("Registry request aborted"));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error("Registry request aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Existing local HTTP fixtures remain available only inside the test process. */
+export function allowPrivateRegistryFixtureForTests(rawUrl) {
+    if (!allowRegistryFixturesForTests)
+        return false;
+    try {
+        const url = new URL(rawUrl);
+        const hostClass = classifyNetworkHostname(url.hostname);
+        const port = Number.parseInt(url.port, 10);
+        return hostClass === "loopback" && Number.isInteger(port) && port >= 1024 && port <= 65_535;
+    }
+    catch {
+        return false;
+    }
+}
+/** Test-harness seam; production composition never enables these overrides. */
+export function _setRegistryNetworkOverridesForTests(overrides) {
+    allowRegistryFixturesForTests = overrides?.allowLoopbackFixtures === true;
+    registryHostnameResolverForTests = overrides?.resolveHostname;
+    registryPinnedRequestForTests = overrides?.requestPinned;
+}

package/dist/registry/pinned-request-helper.js

@@ -0,0 +1,247 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/** Parse and validate the private stdin request before any socket is opened. */
+async function readNodePinnedHelperRequest(isIP) {
+    const MAX_PRELUDE_BYTES = 64 * 1024;
+    const iterator = process.stdin[Symbol.asyncIterator]();
+    let buffered = Buffer.alloc(0);
+    const readExact = async (length) => {
+        while (buffered.byteLength < length) {
+            const next = await iterator.next();
+            if (next.done)
+                throw new Error("Registry helper input ended before the request prelude was complete");
+            buffered = Buffer.concat([buffered, Buffer.from(next.value)]);
+        }
+        const result = buffered.subarray(0, length);
+        buffered = buffered.subarray(length);
+        return result;
+    };
+    const preludeLength = (await readExact(4)).readUInt32BE(0);
+    if (preludeLength === 0 || preludeLength > MAX_PRELUDE_BYTES) {
+        throw new Error("Registry helper request prelude exceeds its protocol limit");
+    }
+    const raw = JSON.parse((await readExact(preludeLength)).toString("utf8"));
+    if (typeof raw.url !== "string" || typeof raw.address !== "string") {
+        throw new Error("Registry helper request prelude is invalid");
+    }
+    const url = new URL(raw.url);
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
+        throw new Error("Registry helper accepts only credential-free HTTP(S) URLs");
+    }
+    const addressFamily = isIP(raw.address);
+    if (addressFamily === 0)
+        throw new Error("Registry helper requires a numeric pinned address");
+    if (typeof raw.timeoutMs !== "number" || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs <= 0) {
+        throw new Error("Registry helper timeout is invalid");
+    }
+    if (!Array.isArray(raw.headers) || raw.headers.length > 256) {
+        throw new Error("Registry helper headers are invalid");
+    }
+    const headers = {};
+    for (const pair of raw.headers) {
+        if (!Array.isArray(pair) ||
+            pair.length !== 2 ||
+            typeof pair[0] !== "string" ||
+            typeof pair[1] !== "string" ||
+            pair[0].length > 256 ||
+            pair[1].length > 16_384) {
+            throw new Error("Registry helper header entry is invalid");
+        }
+        headers[pair[0].toLowerCase()] = pair[1];
+    }
+    for (const name of [
+        "connection",
+        "keep-alive",
+        "proxy-authorization",
+        "proxy-connection",
+        "te",
+        "trailer",
+        "transfer-encoding",
+        "upgrade",
+    ]) {
+        delete headers[name];
+    }
+    headers.host = url.host;
+    return {
+        addressFamily: addressFamily,
+        bodyPresent: raw.bodyPresent === true,
+        headers,
+        initialBody: buffered,
+        iterator,
+        method: typeof raw.method === "string" ? raw.method.toUpperCase() : "GET",
+        pinnedAddress: raw.address,
+        timeoutMs: raw.timeoutMs,
+        url,
+    };
+}
+/**
+ * The body of the one-request Node helper used by Bun's registry transport.
+ * Its parser is passed explicitly when the parent serializes both functions.
+ */
+export async function nodePinnedRequestHelperMain(readRequest, http, https, isIP) {
+    const MAX_FRAME_BYTES = 1024 * 1024;
+    const FRAME_PRELUDE = 0;
+    const FRAME_BODY = 1;
+    const FRAME_END = 2;
+    const FRAME_ERROR = 3;
+    const writeBuffer = async (value) => {
+        await new Promise((resolve, reject) => {
+            process.stdout.write(value, (error) => (error ? reject(error) : resolve()));
+        });
+    };
+    const writeFrame = async (type, payload = new Uint8Array()) => {
+        if (payload.byteLength > MAX_FRAME_BYTES && type !== FRAME_BODY) {
+            throw new Error("Registry helper frame exceeds its protocol limit");
+        }
+        if (type === FRAME_BODY && payload.byteLength > MAX_FRAME_BYTES) {
+            for (let offset = 0; offset < payload.byteLength; offset += MAX_FRAME_BYTES) {
+                await writeFrame(type, payload.subarray(offset, Math.min(payload.byteLength, offset + MAX_FRAME_BYTES)));
+            }
+            return;
+        }
+        const header = Buffer.allocUnsafe(5);
+        header[0] = type;
+        header.writeUInt32BE(payload.byteLength, 1);
+        await writeBuffer(header);
+        if (payload.byteLength > 0)
+            await writeBuffer(payload);
+    };
+    const errorPayload = (error) => {
+        const candidate = error;
+        return Buffer.from(JSON.stringify({
+            name: typeof candidate?.name === "string" ? candidate.name.slice(0, 128) : "Error",
+            message: typeof candidate?.message === "string" ? candidate.message.slice(0, 8_192) : String(error).slice(0, 8_192),
+            code: typeof candidate?.code === "string" ? candidate.code.slice(0, 128) : undefined,
+        }));
+    };
+    try {
+        const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+        if (!Number.isInteger(nodeMajor) || nodeMajor < 24) {
+            throw new Error(`The pinned registry helper requires Node.js >= 24; found ${process.versions.node}`);
+        }
+        const { addressFamily, bodyPresent, headers, initialBody, iterator, method, pinnedAddress, timeoutMs, url } = await readRequest(isIP);
+        const hostname = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;
+        const lookup = (_hostname, options, callback) => {
+            if (typeof options === "object" && options !== null && "all" in options && options.all === true) {
+                callback(null, [{ address: pinnedAddress, family: addressFamily }]);
+            }
+            else {
+                callback(null, pinnedAddress, addressFamily);
+            }
+        };
+        const requestOptions = {
+            protocol: url.protocol,
+            hostname,
+            port: url.port || undefined,
+            path: `${url.pathname}${url.search}`,
+            method,
+            headers,
+            lookup,
+            // One helper owns exactly one fresh connection. It never pools a socket
+            // selected for an earlier DNS answer.
+            agent: false,
+            ...(url.protocol === "https:" && isIP(hostname) === 0 ? { servername: hostname } : {}),
+        };
+        let responseStarted = false;
+        let requestFinished = false;
+        let request;
+        const responseDone = new Promise((resolve, reject) => {
+            const requestFn = url.protocol === "https:" ? https.request : http.request;
+            request = requestFn(requestOptions, async (response) => {
+                responseStarted = true;
+                try {
+                    await writeFrame(FRAME_PRELUDE, Buffer.from(JSON.stringify({
+                        status: response.statusCode ?? 500,
+                        statusText: response.statusMessage ?? "",
+                        rawHeaders: response.rawHeaders,
+                    })));
+                    for await (const chunk of response) {
+                        await writeFrame(FRAME_BODY, Buffer.from(chunk));
+                    }
+                    await writeFrame(FRAME_END);
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            const headerTimer = setTimeout(() => {
+                request?.destroy(new Error(`Registry request timed out after ${timeoutMs}ms while awaiting response headers`));
+            }, timeoutMs);
+            request.once("response", () => clearTimeout(headerTimer));
+            request.once("error", (error) => {
+                clearTimeout(headerTimer);
+                if (!responseStarted)
+                    reject(error);
+            });
+        });
+        const writeRequestChunk = async (chunk) => {
+            if (!request || request.destroyed)
+                throw new Error("Registry helper request closed while streaming its body");
+            const activeRequest = request;
+            if (activeRequest.write(chunk))
+                return;
+            await new Promise((resolve, reject) => {
+                const onDrain = () => {
+                    cleanup();
+                    resolve();
+                };
+                const onError = (error) => {
+                    cleanup();
+                    reject(error);
+                };
+                const cleanup = () => {
+                    activeRequest.off("drain", onDrain);
+                    activeRequest.off("error", onError);
+                };
+                activeRequest.once("drain", onDrain);
+                activeRequest.once("error", onError);
+            });
+        };
+        const bodyDone = (async () => {
+            if (!request)
+                throw new Error("Registry helper request was not initialized");
+            if (bodyPresent) {
+                if (initialBody.byteLength > 0) {
+                    await writeRequestChunk(initialBody);
+                }
+                while (true) {
+                    const next = await iterator.next();
+                    if (next.done)
+                        break;
+                    await writeRequestChunk(Buffer.from(next.value));
+                }
+            }
+            requestFinished = true;
+            request.end();
+        })();
+        try {
+            await Promise.all([responseDone, bodyDone]);
+        }
+        catch (error) {
+            if (!requestFinished && !responseStarted)
+                request?.destroy(error);
+            throw error;
+        }
+    }
+    catch (error) {
+        try {
+            await writeFrame(FRAME_ERROR, errorPayload(error));
+        }
+        catch {
+            // The parent also treats an unframed EOF as a transport failure.
+        }
+        process.exitCode = 1;
+    }
+}
+/** Materialize both self-contained passes into a one-request Node program. */
+export function nodePinnedRequestHelperSource() {
+    return (`import * as http from "node:http";\n` +
+        `import * as https from "node:https";\n` +
+        `import { isIP } from "node:net";\n` +
+        `(${nodePinnedRequestHelperMain.toString()})(${readNodePinnedHelperRequest.toString()}, http, https, isIP).catch((error) => {\n` +
+        `  console.error(error instanceof Error ? error.message : String(error));\n` +
+        `  process.exitCode = 1;\n` +
+        `});\n`);
+}