akm-cli 0.9.17-alpha.3 → 0.9.17-alpha.5

package/dist/registry/resolve.js

@@ -6,10 +6,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { jsonWithByteCap } from "../core/common.js";
-import { NotFoundError, UsageError } from "../core/errors.js";
+import { ConfigError, NotFoundError, UsageError } from "../core/errors.js";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github.js";
-import { cancelRegistryResponse, fetchRegistryResponse } from "./network.js";
+import { fetchRegistryJson } from "./network.js";
 import { isExactSemver, isSemverRange, maxSatisfying } from "./semver.js";
 /**
  * Pass an HTTPS bearer credential to Git without placing it in the remote URL
@@ -64,12 +63,12 @@ export function validateGitRef(ref) {
 export function parseRegistryRef(rawRef) {
     const ref = rawRef.trim();
     if (!ref)
-        throw new Error("Registry ref is required.");
+        throw new UsageError("Registry ref is required.", "MISSING_REQUIRED_ARGUMENT");
     // Detect registry search result IDs (e.g. "skills-sh:org/skills/name")
     // that are not installable refs. Known installable prefixes are handled below.
     const registryIdHint = detectRegistrySearchId(ref);
     if (registryIdHint) {
-        throw new Error(registryIdHint);
+        throw new UsageError(registryIdHint);
     }
     if (ref.startsWith("npm:")) {
         return parseNpmRef(ref.slice(4), ref);
@@ -160,7 +159,7 @@ export async function resolveRegistryArtifact(parsed, options) {
 function parseNpmRef(input, originalRef) {
     const trimmed = input.trim();
     if (!trimmed)
-        throw new Error("Invalid npm ref.");
+        throw new UsageError("Invalid npm ref.");
     const parsed = splitNpmNameAndVersion(trimmed);
     validateNpmPackageName(parsed.packageName);
     return {
@@ -175,12 +174,12 @@ function parseGithubShorthand(input, originalRef) {
     const [repoPart, requestedRef] = splitRefSuffix(input.trim());
     const segments = repoPart.split("/").filter(Boolean);
     if (segments.length !== 2) {
-        throw new Error("Invalid GitHub ref. Expected owner/repo or owner/repo#ref.");
+        throw new UsageError("Invalid GitHub ref. Expected owner/repo or owner/repo#ref.");
     }
     const owner = segments[0];
     const repo = segments[1].replace(/\.git$/i, "");
     if (!owner || !repo) {
-        throw new Error("Invalid GitHub ref. Expected owner/repo.");
+        throw new UsageError("Invalid GitHub ref. Expected owner/repo.");
     }
     return {
         source: "github",
@@ -197,7 +196,7 @@ function parseRemoteUrl(rawUrl) {
         url = new URL(rawUrl);
     }
     catch {
-        throw new Error("Invalid registry URL.");
+        throw new UsageError("Invalid registry URL.");
     }
     if (url.hostname === "github.com") {
         return parseGithubUrl(url, rawUrl);
@@ -207,7 +206,7 @@ function parseRemoteUrl(rawUrl) {
 function parseGithubUrl(url, rawUrl) {
     const segments = url.pathname.split("/").filter(Boolean);
     if (segments.length < 2) {
-        throw new Error("Invalid GitHub URL. Expected https://github.com/owner/repo.");
+        throw new UsageError("Invalid GitHub URL. Expected https://github.com/owner/repo.");
     }
     const owner = segments[0];
     const repo = segments[1].replace(/\.git$/i, "");
@@ -224,7 +223,7 @@ function parseGithubUrl(url, rawUrl) {
 function parseGitUrl(input, originalRef) {
     const [urlPart, requestedRef] = splitRefSuffix(input.trim());
     if (!urlPart)
-        throw new Error("Invalid git ref. A URL is required.");
+        throw new UsageError("Invalid git ref. A URL is required.");
     // Normalize the URL for the id (strip .git suffix, fragment)
     const normalized = urlPart.replace(/\.git$/i, "");
     return {
@@ -251,7 +250,7 @@ function tryParseLocalRef(rawRef, explicitPath) {
     }
     if (!stat.isDirectory()) {
         if (explicitPath) {
-            throw new Error("Local add path must be a directory, but the provided path is not one.");
+            throw new UsageError("Local add path must be a directory, but the provided path is not one.");
         }
         // Bare name exists but isn't a directory — not a local ref
         return undefined;
@@ -292,55 +291,11 @@ function isPathLikeRef(ref) {
 }
 /** Default public npm registry host. */
 const DEFAULT_NPM_REGISTRY_HOST = "registry.npmjs.org";
-/**
- * Typed error raised when the npm registry returns a tarball URL on a host
- * that is not the public registry or the operator-configured mirror. Carries
- * a stable `.code` so callers (and JSON envelope output) can branch on it
- * without parsing the message string.
- */
-export class UntrustedNpmTarballError extends Error {
-    code = "UNTRUSTED_NPM_TARBALL";
-    _hint;
-    constructor(msg, hint) {
-        super(msg);
-        this.name = "UntrustedNpmTarballError";
-        this._hint = hint;
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-    hint() {
-        return (this._hint ??
-            "Set AKM_NPM_REGISTRY to your private npm mirror's base URL if you install from a non-default registry.");
-    }
-}
-/**
- * Resolve the set of npm registry hosts whose tarballs are considered trusted.
- * Always includes the public npm registry, plus the host of an operator-set
- * `AKM_NPM_REGISTRY` environment variable (if it parses to a valid URL).
- */
-export function trustedNpmTarballHosts() {
-    const hosts = new Set([DEFAULT_NPM_REGISTRY_HOST]);
-    const override = process.env.AKM_NPM_REGISTRY?.trim();
-    if (override) {
-        // A malformed override must not be silently ignored (falling back to the
-        // public registry as though nothing was configured) — that would install
-        // from the wrong registry without telling the operator (R-035).
-        let overrideHost;
-        try {
-            overrideHost = new URL(override).hostname.toLowerCase();
-        }
-        catch {
-            throw new UsageError(`AKM_NPM_REGISTRY is set to an invalid URL: ${override}`);
-        }
-        if (overrideHost)
-            hosts.add(overrideHost);
-    }
-    return hosts;
-}
+const UNTRUSTED_TARBALL_HINT = "Set AKM_NPM_REGISTRY to your private npm mirror's base URL if you install from a non-default registry.";
 /**
  * Validate that an npm tarball URL starts at the exact metadata registry
- * origin. A compromised mirror must not change scheme or port (or nominate a
- * different host) in `dist.tarball`; later public redirects remain subject to
- * the outbound boundary's hop-by-hop policy.
+ * origin: a mirror must not change scheme or port, or nominate a different
+ * host, in `dist.tarball`.
  */
 export function validateNpmTarballUrl(tarballUrl, packageRef, registryOrigin) {
     let url;
@@ -348,39 +303,20 @@ export function validateNpmTarballUrl(tarballUrl, packageRef, registryOrigin) {
         url = new URL(tarballUrl);
     }
     catch {
-        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned an invalid tarball URL: ${tarballUrl}`);
+        throw new NotFoundError(`npm package ${packageRef} returned an invalid tarball URL: ${tarballUrl}`, "REGISTRY_RESPONSE_INVALID", UNTRUSTED_TARBALL_HINT);
     }
     if (url.protocol !== "https:" && url.protocol !== "http:") {
-        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned a tarball with disallowed scheme "${url.protocol}".`);
+        throw new NotFoundError(`npm package ${packageRef} returned a tarball with disallowed scheme "${url.protocol}".`, "REGISTRY_RESPONSE_INVALID", UNTRUSTED_TARBALL_HINT);
     }
-    const expectedOrigin = registryOrigin ?? new URL(npmMetadataRegistry().baseUrl).origin;
+    const expectedOrigin = registryOrigin ?? new URL(npmMetadataRegistry()).origin;
     if (url.origin !== expectedOrigin) {
-        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned a tarball URL on untrusted origin "${url.origin}" (expected: ${expectedOrigin}).`);
+        throw new NotFoundError(`npm package ${packageRef} returned a tarball URL on untrusted origin "${url.origin}" (expected: ${expectedOrigin}).`, "REGISTRY_RESPONSE_INVALID", UNTRUSTED_TARBALL_HINT);
     }
 }
-/** Network policy for a tarball URL that already passed {@link validateNpmTarballUrl}. */
-export function npmArtifactNetworkPolicy(artifact) {
-    if (!artifact.registryOrigin) {
-        throw new UsageError("npm artifact network policy requires the registry origin that authorized its metadata.");
-    }
-    return {
-        kind: "npm-api",
-        registryOrigin: new URL(artifact.registryOrigin).origin,
-        allowPrivateRegistryOrigin: artifact.allowPrivateRegistryOrigin === true,
-    };
-}
 /**
- * Resolve the npm registry base URL used to fetch package METADATA.
- *
- * R-035: `AKM_NPM_REGISTRY` previously only widened the trusted-tarball-host
- * allowlist (see {@link trustedNpmTarballHosts}) while the metadata endpoint
- * stayed hardcoded to the public registry — so an operator-configured mirror
- * was never actually consulted, making the `UntrustedNpmTarballError.hint()`
- * text below false. Honoring the override here for metadata too makes the
- * hint true: installs really do resolve entirely against the configured
- * mirror when it is set, mirroring how a private npm registry replaces the
- * default wholesale (like npm's own `--registry` flag) rather than being
- * merged with it.
+ * The npm registry base URL for package METADATA: `AKM_NPM_REGISTRY` when set
+ * (a private mirror replaces the default wholesale, like npm's own
+ * `--registry`), else the public registry.
  */
 function npmMetadataRegistry() {
     const override = process.env.AKM_NPM_REGISTRY?.trim();
@@ -393,22 +329,16 @@ function npmMetadataRegistry() {
             url = new URL(override);
         }
         catch {
-            throw new UsageError(`AKM_NPM_REGISTRY is set to an invalid URL: ${override}`);
+            throw new ConfigError(`AKM_NPM_REGISTRY is set to an invalid URL: ${override}`, "REGISTRY_URL_INVALID");
         }
-        const base = `${url.origin}${url.pathname === "/" ? "" : url.pathname}`;
-        return { baseUrl: base.replace(/\/+$/, ""), allowPrivateRegistryOrigin: true };
+        return `${url.origin}${url.pathname === "/" ? "" : url.pathname}`.replace(/\/+$/, "");
     }
-    return { baseUrl: `https://${DEFAULT_NPM_REGISTRY_HOST}`, allowPrivateRegistryOrigin: false };
+    return `https://${DEFAULT_NPM_REGISTRY_HOST}`;
 }
 async function resolveNpmArtifact(parsed) {
     const encodedName = encodeURIComponent(parsed.packageName);
-    const npmRegistry = npmMetadataRegistry();
-    const npmPolicy = {
-        kind: "npm-api",
-        registryOrigin: new URL(npmRegistry.baseUrl).origin,
-        allowPrivateRegistryOrigin: npmRegistry.allowPrivateRegistryOrigin,
-    };
-    const metadata = await fetchJson(`${npmRegistry.baseUrl}/${encodedName}`, undefined, npmPolicy);
+    const registryBase = npmMetadataRegistry();
+    const metadata = await fetchJson(`${registryBase}/${encodedName}`, undefined);
     const versions = asRecord(metadata.versions);
     const distTags = asRecord(metadata["dist-tags"]);
     const requested = parsed.requestedVersionOrTag;
@@ -429,15 +359,15 @@ async function resolveNpmArtifact(parsed) {
         }
     }
     if (!resolvedVersion || !(resolvedVersion in versions)) {
-        throw new Error(`Unable to resolve npm ref "${parsed.ref}".`);
+        throw new NotFoundError(`Unable to resolve npm ref "${parsed.ref}".`, "REGISTRY_NOT_FOUND");
     }
     const versionMeta = asRecord(versions[resolvedVersion]);
     const dist = asRecord(versionMeta.dist);
     const tarballUrl = asString(dist.tarball);
     if (!tarballUrl) {
-        throw new Error(`npm package ${parsed.packageName}@${resolvedVersion} does not expose a tarball URL.`);
+        throw new NotFoundError(`npm package ${parsed.packageName}@${resolvedVersion} does not expose a tarball URL.`, "REGISTRY_RESPONSE_INVALID");
     }
-    validateNpmTarballUrl(tarballUrl, `${parsed.packageName}@${resolvedVersion}`, npmPolicy.registryOrigin);
+    validateNpmTarballUrl(tarballUrl, `${parsed.packageName}@${resolvedVersion}`, new URL(registryBase).origin);
     const resolvedRevision = asString(dist.shasum) ?? asString(dist.integrity);
     return {
         id: parsed.id,
@@ -446,8 +376,6 @@ async function resolveNpmArtifact(parsed) {
         artifactUrl: tarballUrl,
         resolvedVersion,
         resolvedRevision,
-        registryOrigin: npmPolicy.registryOrigin,
-        allowPrivateRegistryOrigin: npmPolicy.allowPrivateRegistryOrigin,
     };
 }
 async function resolveGithubArtifact(parsed, credential) {
@@ -468,7 +396,7 @@ async function resolveGithubArtifact(parsed, credential) {
     }
     const headers = { ...githubHeaders(), ...(credential ? { Authorization: `Bearer ${credential}` } : {}) };
     if (parsed.requestedRef) {
-        const commit = await tryFetchJson(`${repoBase}/commits/${encodeURIComponent(parsed.requestedRef)}`, headers, GITHUB_API_POLICY);
+        const commit = await tryFetchJson(`${repoBase}/commits/${encodeURIComponent(parsed.requestedRef)}`, headers);
         const resolvedRevision = asString(commit?.sha) ?? parsed.requestedRef;
         return {
             id: parsed.id,
@@ -479,7 +407,7 @@ async function resolveGithubArtifact(parsed, credential) {
             resolvedVersion: parsed.requestedRef,
         };
     }
-    const latestRelease = await tryFetchJson(`${repoBase}/releases/latest`, headers, GITHUB_API_POLICY);
+    const latestRelease = await tryFetchJson(`${repoBase}/releases/latest`, headers);
     if (latestRelease) {
         const tarballUrl = asString(latestRelease.tarball_url);
         if (tarballUrl) {
@@ -493,12 +421,12 @@ async function resolveGithubArtifact(parsed, credential) {
             };
         }
     }
-    const repoMeta = await fetchJson(repoBase, headers, GITHUB_API_POLICY);
+    const repoMeta = await fetchJson(repoBase, headers);
     const defaultBranch = asString(repoMeta.default_branch);
     if (!defaultBranch) {
-        throw new Error(`Unable to resolve default branch for ${parsed.owner}/${parsed.repo}.`);
+        throw new NotFoundError(`Unable to resolve default branch for ${parsed.owner}/${parsed.repo}.`, "REGISTRY_RESPONSE_INVALID");
     }
-    const commit = await tryFetchJson(`${repoBase}/commits/${encodeURIComponent(defaultBranch)}`, headers, GITHUB_API_POLICY);
+    const commit = await tryFetchJson(`${repoBase}/commits/${encodeURIComponent(defaultBranch)}`, headers);
     return {
         id: parsed.id,
         source: parsed.source,
@@ -530,7 +458,7 @@ async function resolveGitArtifact(parsed, credential) {
         // `git ls-remote`), a plain git source has no fallback resolver — an
         // unresolved revision here would silently disable the post-clone
         // revision-integrity check in `verifyClonedRevision` (R-011).
-        throw new Error(`Unable to resolve ${parsed.requestedRef ?? "HEAD"} for ${parsed.url} via 'git ls-remote'; refusing to install without a verifiable revision.`);
+        throw new NotFoundError(`Unable to resolve ${parsed.requestedRef ?? "HEAD"} for ${parsed.url} via 'git ls-remote'; refusing to install without a verifiable revision.`, "REGISTRY_NOT_FOUND");
     }
     return {
         id: parsed.id,
@@ -573,21 +501,21 @@ function splitNpmNameAndVersion(input) {
 }
 function validateNpmPackageName(name) {
     if (!name)
-        throw new Error("Invalid npm package name: name is required.");
+        throw new UsageError("Invalid npm package name: name is required.");
     if (name.length > 214)
-        throw new Error(`Invalid npm package name: "${name}" exceeds 214 characters.`);
+        throw new UsageError(`Invalid npm package name: "${name}" exceeds 214 characters.`);
     if (name !== name.toLowerCase() && !name.startsWith("@")) {
-        throw new Error(`Invalid npm package name: "${name}" must be lowercase.`);
+        throw new UsageError(`Invalid npm package name: "${name}" must be lowercase.`);
     }
     if (name.startsWith(".") || name.startsWith("_")) {
-        throw new Error(`Invalid npm package name: "${name}" cannot start with . or _.`);
+        throw new UsageError(`Invalid npm package name: "${name}" cannot start with . or _.`);
     }
     if (/[~'!()*]/.test(name) ||
         name.includes(" ") ||
         encodeURIComponent(name)
             .replace(/%40/g, "@")
             .replace(/%2[Ff]/g, "/") !== name) {
-        throw new Error(`Invalid npm package name: "${name}" contains invalid characters.`);
+        throw new UsageError(`Invalid npm package name: "${name}" contains invalid characters.`);
     }
 }
 function looksLikeGithubOwnerRepo(ref) {
@@ -662,24 +590,20 @@ function readGitValue(repoRoot, ...args) {
     const value = result.stdout.trim();
     return value || undefined;
 }
-// Cap JSON responses at 10 MB — npm package manifests and GitHub API
-// responses are typically a few KB; a compromised registry streaming
-// tens of MB of JSON is a DoS surface, not a feature.
+// npm package manifests and GitHub API responses are typically a few KB; 10 MB
+// is the cap on what one is allowed to send.
 const REGISTRY_JSON_BYTE_CAP = 10 * 1024 * 1024;
-const GITHUB_API_POLICY = { kind: "github-api" };
-async function fetchJson(url, headers, policy) {
-    const response = await fetchRegistryResponse(url, { headers }, { policy, timeoutMs: 30_000 });
-    if (!response.ok) {
-        await cancelRegistryResponse(response);
-        throw new Error(`Request failed (${response.status}) for ${url}`);
-    }
-    return jsonWithByteCap(response, REGISTRY_JSON_BYTE_CAP, { bodyTimeoutMs: 30_000 });
-}
-async function tryFetchJson(url, headers, policy) {
-    const response = await fetchRegistryResponse(url, { headers }, { policy, timeoutMs: 30_000 });
-    if (!response.ok) {
-        await cancelRegistryResponse(response);
-        return null;
-    }
-    return jsonWithByteCap(response, REGISTRY_JSON_BYTE_CAP, { bodyTimeoutMs: 30_000 });
+async function fetchJson(url, headers) {
+    return fetchRegistryJson(url, { headers, timeoutMs: 30_000, maxBytes: REGISTRY_JSON_BYTE_CAP });
+}
+/** `fetchJson` for optional GitHub lookups: a not-found / unusable answer is `null`, a transient failure still throws. */
+async function tryFetchJson(url, headers) {
+    try {
+        return await fetchJson(url, headers);
+    }
+    catch (error) {
+        if (error instanceof NotFoundError)
+            return null;
+        throw error;
+    }
 }