dsh-plugin-shop 0.6.0 → 0.7.0

package/lib/index.js

@@ -7,7 +7,9 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync,
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
 import { z } from "zod";
+import { gunzipSync } from "node:zlib";
 import { JSON_SCHEMA, Type, dump, load } from "js-yaml";
 //#region src/own-version.ts
 /** The shop's own published version, read from the package.json that ships
@@ -19,8 +21,332 @@ import { JSON_SCHEMA, Type, dump, load } from "js-yaml";
 function ownVersion() {
 	return JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
 }
+//#endregion
+//#region src/host/origin.ts
+/** The transport seam under `loadCatalog` (design §3).
+*
+* An origin answers a cheap probe, then serves the pointer and the files the
+* pointer names. HTTP and npm are interchangeable behind it, so every line of
+* cache and validation logic in `catalog.ts` stays transport-blind. */
+/** A failure of the link, not of the content: the wire threw, or answered
+* non-2xx. This is the ONLY class `loadCatalog` retries on another origin.
+* A bad schema, a sha mismatch, or a refused url is an interpretation
+* failure and throws — masking a corrupt origin behind a healthy one is
+* exactly the silent-wrongness this project refuses. */
+var TransportError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "TransportError";
+	}
+};
+/** Resolve the pointer's data URL against the catalog base. An absolute URL —
+* any scheme, or a protocol-relative `//host/...` — would hand the pointer a
+* fetch primitive to arbitrary hosts, so it is refused loudly before any
+* fetch (§9.2). The guard is the resolved origin, not the raw string: WHATWG
+* normalization strips leading whitespace and accepts backslash spellings
+* before the string could be inspected, so only comparing the resolved URL's
+* origin to the base's closes every spelling class. */
+function resolveDataUrl(baseUrl, url) {
+	const resolved = new URL(url, baseUrl);
+	if (resolved.origin !== new URL(baseUrl).origin) throw new Error("catalog data url must be relative to the catalog base");
+	return resolved.href;
+}
+/** The transport this project has always used: a static `v1/` tree. */
+function httpOrigin(baseUrl, fetchImpl) {
+	const id = `http:${baseUrl}`;
+	return {
+		id,
+		async probe(signal) {
+			let response;
+			try {
+				response = await fetchImpl(new URL("index.json", baseUrl).href, { signal });
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`catalog pointer fetch failed for ${id}: ${detail}`, { cause: error });
+			}
+			if (!response.ok) throw new TransportError(`catalog pointer returned ${response.status} for ${id}`);
+			const pointerText = await response.text();
+			return {
+				id,
+				pointer: async () => pointerText,
+				file: async (url) => {
+					const resolved = resolveDataUrl(baseUrl, url);
+					let dataResponse;
+					try {
+						dataResponse = await fetchImpl(resolved);
+					} catch (error) {
+						const detail = error instanceof Error ? error.message : String(error);
+						throw new TransportError(`catalog data fetch failed for ${id}: ${detail}`, { cause: error });
+					}
+					if (!dataResponse.ok) throw new TransportError(`catalog data returned ${dataResponse.status} for ${id}`);
+					return dataResponse.text();
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/host/tar.ts
+/** A read-only ustar parser: the npm transport's only way into a tarball.
+*
+* Pure — bytes in, a path-to-bytes map out. It handles exactly what `npm
+* pack` emits and refuses everything else loudly, because the alternative to
+* a small strict reader is a fourth runtime dependency (design §4). */
+/** Bytes up to the first NUL, as ASCII. Tar pads its fixed-width text fields
+* with NULs, so a plain toString would carry them into the path. */
+function cstring(field) {
+	const end = field.indexOf(0);
+	return field.subarray(0, end === -1 ? field.length : end).toString("ascii");
+}
+/** Tar sizes are octal text, NUL- or space-terminated. An unparseable size
+* would desynchronise every subsequent header, so it throws rather than
+* guessing zero. */
+function parseOctal(field) {
+	const text = cstring(field).trim();
+	if (text === "") return 0;
+	const value = Number.parseInt(text, 8);
+	if (!Number.isInteger(value) || value < 0) throw new Error(`tar: unparseable size field ${JSON.stringify(text)}`);
+	return value;
+}
+/** `..` in any position, or a leading `/`, would let an archive write outside
+* the directory it claims. Nothing we publish contains either, so a tarball
+* that does is hostile or corrupt — refuse it rather than filter it. */
+function assertContained(path) {
+	if (path.startsWith("/") || path.split("/").includes("..")) throw new Error(`tar: ${JSON.stringify(path)} escapes the archive root`);
+	return path;
+}
+/**
+* Parse an uncompressed tar archive into path → bytes.
+*
+* Directory entries and every non-regular type (symlinks, pax and GNU
+* extension headers) are skipped: npm packs regular files under `package/`,
+* and a catalog tarball that needs anything else is not one we published.
+*/
+function readTar(buffer) {
+	const files = /* @__PURE__ */ new Map();
+	let offset = 0;
+	while (offset + 512 <= buffer.length) {
+		const header = buffer.subarray(offset, offset + 512);
+		if (header.every((byte) => byte === 0)) break;
+		const name = cstring(header.subarray(0, 100));
+		const prefix = cstring(header.subarray(345, 500));
+		const size = parseOctal(header.subarray(124, 136));
+		const typeflag = String.fromCharCode(header[156] ?? 0);
+		const path = prefix === "" ? name : `${prefix}/${name}`;
+		offset += 512;
+		if (typeflag === "0" || typeflag === "\0") files.set(assertContained(path), buffer.subarray(offset, offset + size));
+		offset += Math.ceil(size / 512) * 512;
+	}
+	return files;
+}
+//#endregion
+//#region src/host/npm-origin.ts
+/** The npm transport (design §2, §3): the catalog as a package.
+*
+* Shell — this and `origin.ts`'s fetch half are the only places the catalog
+* loader touches the network. The payoff is measured, not assumed: the same
+* bytes reach a China-side machine at 12.53 MB/s from npmmirror against
+* 0.03 MB/s from GitHub Pages. */
+/** The abbreviated `latest` manifest. Non-strict: a registry may add keys,
+* and stripping them is what keeps an old host working against a new one. */
+const latestSchema = z.object({
+	version: z.string(),
+	dist: z.object({
+		tarball: z.string(),
+		integrity: z.string()
+	})
+});
+/** Where the published package keeps the catalog tree (design §2). */
+const PACKAGE_ROOT = "package/v1/";
+/** Verify tarball bytes against npm's own Subresource-Integrity string.
+* `dist.integrity` may carry several space-separated digests; npm publishes
+* one, and the first is the one we check. */
+function verifyIntegrity(bytes, integrity, registryUrl) {
+	const first = integrity.trim().split(/\s+/)[0] ?? "";
+	const dash = first.indexOf("-");
+	const algorithm = dash === -1 ? "" : first.slice(0, dash);
+	const expected = dash === -1 ? "" : first.slice(dash + 1);
+	if (algorithm !== "sha512" && algorithm !== "sha256") throw new TransportError(`npm origin ${registryUrl}: unsupported dist.integrity algorithm ${JSON.stringify(algorithm)}`);
+	if (createHash(algorithm).update(bytes).digest("base64") !== expected) throw new Error(`npm origin ${registryUrl}: tarball failed dist.integrity check (${algorithm})`);
+}
+/** Normalise to a trailing slash so relative `URL` resolution against a
+* registry that carries a path — every corporate registry, e.g.
+* `https://artifactory.corp/api/npm/npm-repo` — keeps that path instead of
+* eating its last segment; a host-root registry's trailing slash is already
+* a no-op either way. Exported so `catalog.ts`'s dedupe compares against the
+* same normalised form `npmOrigin` races on. */
+function normalizeRegistryUrl(url) {
+	return url.endsWith("/") ? url : `${url}/`;
+}
+/**
+* An origin that reads the catalog out of `<registryUrl>`'s copy of
+* `<packageName>`.
+*
+* The probe is the abbreviated `latest` manifest — 13.5 KB against the live
+* registry — so the race is decided without downloading anything large. The
+* tarball is fetched lazily on the first `pointer()` or `file()` and kept on
+* the handle, so one origin download serves the whole load.
+*/
+function npmOrigin(rawRegistryUrl, packageName, fetchImpl) {
+	const registryUrl = normalizeRegistryUrl(rawRegistryUrl);
+	const id = `npm:${registryUrl}`;
+	return {
+		id,
+		async probe(signal) {
+			let url;
+			try {
+				url = new URL(`${encodeURIComponent(packageName)}/latest`, registryUrl).href;
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`npm origin ${registryUrl} is not a usable registry url: ${detail}`, { cause: error });
+			}
+			let response;
+			try {
+				response = await fetchImpl(url, { signal });
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`npm origin ${registryUrl} probe failed: ${detail}`, { cause: error });
+			}
+			if (!response.ok) throw new TransportError(`npm origin ${registryUrl} returned ${response.status}`);
+			let manifest;
+			try {
+				manifest = latestSchema.parse(await response.json());
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`npm origin ${registryUrl} returned an unparsable manifest: ${detail}`, { cause: error });
+			}
+			let files = null;
+			const load = async () => {
+				if (files !== null) return files;
+				let tarballUrl;
+				try {
+					tarballUrl = new URL(manifest.dist.tarball);
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl}: dist.tarball is not a valid url: ${detail}`, { cause: error });
+				}
+				if (tarballUrl.origin !== new URL(registryUrl).origin) throw new TransportError(`npm origin ${registryUrl}: dist.tarball host ${tarballUrl.origin} is not the registry's`);
+				let tarballResponse;
+				try {
+					tarballResponse = await fetchImpl(tarballUrl.href);
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl} tarball fetch failed: ${detail}`, { cause: error });
+				}
+				if (!tarballResponse.ok) throw new TransportError(`npm origin ${registryUrl} tarball returned ${tarballResponse.status}`);
+				let bytes;
+				try {
+					bytes = Buffer.from(await tarballResponse.arrayBuffer());
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl} tarball body read failed: ${detail}`, { cause: error });
+				}
+				verifyIntegrity(bytes, manifest.dist.integrity, registryUrl);
+				let parsed;
+				try {
+					parsed = readTar(gunzipSync(bytes));
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl} served an unparsable tarball: ${detail}`, { cause: error });
+				}
+				files = parsed;
+				return files;
+			};
+			const read = async (name) => {
+				const entry = (await load()).get(`${PACKAGE_ROOT}${name}`);
+				if (entry === void 0) throw new TransportError(`npm origin ${registryUrl}: ${name} is not in the catalog package`);
+				return entry.toString("utf8");
+			};
+			return {
+				id,
+				pointer: async () => read("index.json"),
+				file: async (url) => {
+					if (url.includes("/") || url.startsWith(".")) throw new Error(`npm origin ${registryUrl}: ${JSON.stringify(url)} must be a plain file name`);
+					return read(url);
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/host/race.ts
+/**
+* Yield each promise's outcome as it settles, tagged with its argument index.
+*
+* Deliberately NOT an `async function*`. Two properties depend on that:
+*
+* 1. **Handlers attach synchronously, at call time.** An async generator's
+*    body does not run until its first `next()`, so wiring the handlers
+*    inside one would leave a rejection unhandled for as long as the caller
+*    waits before iterating — which crashes the process under Node's default
+*    unhandled-rejection policy.
+* 2. **Order is recorded when each promise settles**, not when a consumer
+*    asks. Re-racing the survivors on every turn tie-breaks on argument
+*    order instead: `Promise.race` over promises that are ALREADY settled
+*    resolves with the first in iteration order, not the first to have
+*    settled — and a consumer doing any work between yields, which is
+*    exactly this module's use case, is what lets two settle inside one turn.
+*/
+function inCompletionOrder(promises) {
+	const settled = [];
+	let wake = null;
+	const record = (outcome) => {
+		settled.push(outcome);
+		const resume = wake;
+		wake = null;
+		resume?.();
+	};
+	for (const [index, promise] of promises.entries()) promise.then((value) => {
+		record({
+			index,
+			value
+		});
+	}, (reason) => {
+		record({
+			index,
+			reason
+		});
+	});
+	return (async function* () {
+		for (let delivered = 0; delivered < promises.length; delivered += 1) {
+			if (settled.length === delivered) await new Promise((resolve) => {
+				wake = resolve;
+			});
+			const outcome = settled[delivered];
+			if (outcome === void 0) throw new Error("inCompletionOrder: woke with nothing settled");
+			yield outcome;
+		}
+	})();
+}
 /** A cached catalog younger than this is served without touching the network. */
 const FRESH_MS = 3e5;
+/** How long a probe may take before the race gives up on that origin. Long
+* enough for a slow but working link, short enough that a black-holed origin
+* does not hold the shelf closed. */
+const PROBE_TIMEOUT_MS = 1e4;
+/** How long the committed origin has to produce its pointer. `httpOrigin`
+* answers instantly — its probe already fetched the bytes — but `npmOrigin`
+* downloads its tarball here, so this is a bulk-transfer budget, not a probe
+* one. Without it a winner that stalls mid-body parks the race forever while
+* healthy origins sit settled and unread, which is the exact failure the race
+* exists to prevent. Generous against every measured npm origin (12.53 MB/s
+* mirror -> 0.12 s for 1.5 MB; npmjs direct 1.99 MB/s -> 0.75 s). */
+const COMMIT_TIMEOUT_MS = 3e4;
+/** Reject with a TransportError if `work` outlives `COMMIT_TIMEOUT_MS`. The
+* underlying fetch is left to finish or fail on its own and its result is
+* discarded: aborting it would need a signal threaded through OriginHandle,
+* and a stalled origin we have already abandoned costs nothing but its own
+* socket. */
+async function withCommitTimeout(work, id) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(new TransportError(`${id} did not produce a pointer within ${COMMIT_TIMEOUT_MS} ms`)), COMMIT_TIMEOUT_MS);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
 /** Records when the loader itself wrote the cache; the pointer's `builtAt` is
 * the catalog's build time, not the cache's fetch time. */
 const META_FILE = "index.meta.json";
@@ -122,18 +448,6 @@ const nodeFs$1 = {
 		writeFileSync(path, data);
 	}
 };
-/** Resolve the pointer's data URL against the catalog base. An absolute URL —
-* any scheme, or a protocol-relative `//host/...` — would hand the pointer a
-* fetch primitive to arbitrary hosts, so it is refused loudly before any
-* fetch (§9.2). The guard is the resolved origin, not the raw string: WHATWG
-* normalization strips leading whitespace and accepts backslash spellings
-* before the string could be inspected, so only comparing the resolved URL's
-* origin to the base's closes every spelling class. */
-function resolveDataUrl(baseUrl, url) {
-	const resolved = new URL(url, baseUrl);
-	if (resolved.origin !== new URL(baseUrl).origin) throw new Error("catalog data url must be relative to the catalog base");
-	return resolved.href;
-}
 /** Read and verify a cached/fetched stars sidecar; ANY irregularity degrades
 * to an empty map — stars are advisory (spec §5). */
 function parseStarsText(text) {
@@ -158,7 +472,10 @@ function parseStarsText(text) {
 * included, degrades to no stars (spec §5).
 */
 async function loadCatalog(options) {
-	const { baseUrl, cacheDir, refresh = false, fetchImpl = fetch, now = () => /* @__PURE__ */ new Date(), fsImpl = nodeFs$1 } = options;
+	const { cacheDir, refresh = false, fetchImpl = fetch, now = () => /* @__PURE__ */ new Date(), fsImpl = nodeFs$1 } = options;
+	if (options.baseUrl === void 0 === (options.origins === void 0)) throw new Error("loadCatalog: exactly one of baseUrl or origins is required");
+	const originList = options.origins ?? [httpOrigin(options.baseUrl, fetchImpl)];
+	if (originList.length === 0) throw new Error("loadCatalog: no origins");
 	const indexPath = join(cacheDir, "index.json");
 	const metaPath = join(cacheDir, META_FILE);
 	/** The timestamp freshness is measured from: the sidecar's fetch time when
@@ -211,34 +528,41 @@ async function loadCatalog(options) {
 			};
 		}
 	}
-	let pointerText;
-	try {
-		const response = await fetchImpl(new URL("index.json", baseUrl).href);
-		if (!response.ok) throw new Error(`catalog pointer returned ${response.status}`);
-		pointerText = await response.text();
-	} catch (error) {
+	const cachedOrThrow = (error) => {
 		const cached = readCached();
 		if (cached !== null) return {
 			snapshot: cached,
 			stale: true
 		};
 		throw error;
+	};
+	let handle = null;
+	let pointerText = "";
+	let lastTransportError = new TransportError("no catalog origin was reachable");
+	for await (const settled of inCompletionOrder(originList.map((origin) => origin.probe(AbortSignal.timeout(PROBE_TIMEOUT_MS))))) {
+		if (!("value" in settled)) {
+			if (!(settled.reason instanceof TransportError)) throw settled.reason;
+			lastTransportError = settled.reason;
+			continue;
+		}
+		try {
+			pointerText = await withCommitTimeout(settled.value.pointer(), settled.value.id);
+			handle = settled.value;
+			break;
+		} catch (error) {
+			if (!(error instanceof TransportError)) throw error;
+			lastTransportError = error;
+		}
 	}
+	if (handle === null) return cachedOrThrow(lastTransportError);
 	const pointer = pointerSchema.parse(JSON.parse(pointerText));
 	if (pointer.schemaVersion > 6) throw new Error(`catalog schemaVersion ${pointer.schemaVersion} is newer than this build supports (6)`);
-	const dataUrl = resolveDataUrl(baseUrl, pointer.plugins.url);
 	let dataText;
 	try {
-		const dataResponse = await fetchImpl(dataUrl);
-		if (!dataResponse.ok) throw new Error(`catalog data returned ${dataResponse.status}`);
-		dataText = await dataResponse.text();
+		dataText = await handle.file(pointer.plugins.url);
 	} catch (error) {
-		const cached = readCached();
-		if (cached !== null) return {
-			snapshot: cached,
-			stale: true
-		};
-		throw error;
+		if (!(error instanceof TransportError)) throw error;
+		return cachedOrThrow(error);
 	}
 	const actual = createHash("sha256").update(dataText).digest("hex");
 	if (actual !== pointer.plugins.sha256) throw new Error(`catalog data failed integrity check: expected ${pointer.plugins.sha256}, got ${actual}`);
@@ -247,13 +571,10 @@ async function loadCatalog(options) {
 	validateEntryCoherence(data.plugins);
 	let stars = {};
 	if (pointer.stars !== void 0) try {
-		const starsResponse = await fetchImpl(resolveDataUrl(baseUrl, pointer.stars.url));
-		if (starsResponse.ok) {
-			const starsText = await starsResponse.text();
-			if (createHash("sha256").update(starsText).digest("hex") === pointer.stars.sha256) {
-				stars = parseStarsText(starsText);
-				fsImpl.write(join(cacheDir, basename(pointer.stars.url)), starsText);
-			}
+		const starsText = await handle.file(pointer.stars.url);
+		if (createHash("sha256").update(starsText).digest("hex") === pointer.stars.sha256) {
+			stars = parseStarsText(starsText);
+			fsImpl.write(join(cacheDir, basename(pointer.stars.url)), starsText);
 		}
 	} catch {}
 	const snapshot = {
@@ -271,6 +592,76 @@ async function loadCatalog(options) {
 		stale: false
 	};
 }
+/** The npm package carrying the same `v1/` tree (design §2). */
+const CATALOG_PACKAGE = "dsh-plugin-shop-catalog";
+/** Registries raced by default: the domestic mirror first for legibility —
+* the race, not the order, decides the winner. */
+const DEFAULT_REGISTRIES = ["https://registry.npmmirror.com/", "https://registry.npmjs.org/"];
+/**
+* The origins to race for this installation (design §3).
+*
+* @param catalogUrl - the row's configured base.
+* @param npmRegistry - the user's own registry from `~/.npmrc`, or null.
+*/
+function catalogOrigins(catalogUrl, fetchImpl, npmRegistry) {
+	if (catalogUrl !== "https://LivXue.github.io/dsh-plugin-shop/v1/") return [httpOrigin(catalogUrl, fetchImpl)];
+	const registries = [...DEFAULT_REGISTRIES];
+	const normalizedNpmRegistry = npmRegistry === null ? null : normalizeRegistryUrl(npmRegistry);
+	if (normalizedNpmRegistry !== null && !registries.includes(normalizedNpmRegistry)) registries.unshift(normalizedNpmRegistry);
+	return [...registries.map((registry) => npmOrigin(registry, CATALOG_PACKAGE, fetchImpl)), httpOrigin(catalogUrl, fetchImpl)];
+}
+//#endregion
+//#region src/host/npmrc.ts
+/** The user's configured npm registry, if they have one (design §3).
+*
+* Pure: the caller injects the read. This is a deliberately partial reading
+* of npm's config resolution — only the user-level `registry=` line — and
+* that is safe precisely because the origin list is raced: a registry we
+* guess wrong about loses a 400-byte request and nothing else.
+*
+* That property only holds for a value that is actually a URL, which is why
+* the value is VALIDATED here rather than left to the caller. `npmOrigin`
+* addresses its probe with `new URL(<pkg>/latest, registryUrl)`, which
+* throws a raw `TypeError` — not a `TransportError` — for anything that is
+* not an absolute URL, and `catalog.ts`'s race loop rethrows everything that
+* is not a `TransportError`. An unvalidated `registry=` line would therefore
+* fail the WHOLE load with npmmirror, npmjs and Pages all healthy and no
+* cache fallback: the opposite of the stated property. Not a hypothetical
+* shape either — `registry=${NPM_REGISTRY}/` is npm's own documented config
+* expansion, it works perfectly for npm, and a reader that does not expand
+* it captures the literal. */
+/** The value, if it is an absolute `http:`/`https:` URL; otherwise null.
+*
+* Both halves earn their place. The parse rejects a bare host, a relative
+* path, and an unexpanded `${VAR}`. The scheme check then rejects what
+* `new URL` happily accepts but the raced origins cannot fetch from —
+* `file:` and `ftp:` parse fine and are not registries a `fetch` can read.
+* The raw string is returned rather than the parsed href, so the value the
+* user wrote is what reaches `normalizeRegistryUrl` and the origin id. */
+function asRegistryUrl(value) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return null;
+	}
+	return parsed.protocol === "http:" || parsed.protocol === "https:" ? value : null;
+}
+/**
+* @param readFile - returns the file's text, or null when it does not exist.
+* @param home - the user's home directory.
+*/
+function npmrcRegistry(readFile, home) {
+	const text = readFile(join(home, ".npmrc"));
+	if (text === null) return null;
+	for (const line of text.split("\n")) {
+		const value = /^\s*registry\s*=\s*(\S+)\s*$/.exec(line)?.[1];
+		if (value === void 0) continue;
+		const url = asRegistryUrl(value);
+		if (url !== null) return url;
+	}
+	return null;
+}
 //#endregion
 //#region src/host/install.ts
 /**
@@ -1334,6 +1725,9 @@ let ShopGateway = (() => {
 		/** The install gate runs against the last loaded snapshot, never a fresh
 		* fetch per request (§7.2: the Host's cached snapshot is the truth). */
 		lastSnapshot = null;
+		/** The origin list built for the last-seen `catalogUrl`, memoised so the
+		* user's npmrc is read at most once per gateway (see `originsFor`). */
+		originCache = null;
 		/** The incompatibility map already computed for `lastSnapshot`, keyed by
 		* that snapshot's own object identity. Design §3 asks for the verdict
 		* once per loaded snapshot, not once per RPC call: `loadCatalog` serves
@@ -1520,6 +1914,25 @@ let ShopGateway = (() => {
 				cacheDir
 			};
 		}
+		/** The origins to race for this row's catalog. Read once per gateway: the
+		* user's npmrc does not change under a running dsh, and re-reading it on
+		* every catalog call would put a filesystem read on the hot path. */
+		originsFor(catalogUrl) {
+			if (this.originCache?.catalogUrl === catalogUrl) return this.originCache.origins;
+			const registry = npmrcRegistry((path) => {
+				try {
+					return readFileSync(path, "utf8");
+				} catch {
+					return null;
+				}
+			}, homedir());
+			const origins = catalogOrigins(catalogUrl, fetch, registry);
+			this.originCache = {
+				catalogUrl,
+				origins
+			};
+			return origins;
+		}
 		/** The explicit restart override. Only the row's `config:` sub-object is
 		* passed to a plugin — a top-level `allowRestart:` beside `name:` would be
 		* silently ignored by the loader (dsh-market README, #227). */
@@ -1531,7 +1944,7 @@ let ShopGateway = (() => {
 		async catalog(args) {
 			const { catalogUrl, cacheDir } = this.rowConfig();
 			const { snapshot, stale } = await (this.options.loadCatalog ?? loadCatalog)({
-				baseUrl: catalogUrl,
+				origins: this.originsFor(catalogUrl),
 				cacheDir,
 				refresh: args?.refresh ?? false
 			});
@@ -1569,7 +1982,7 @@ let ShopGateway = (() => {
 			if (this.lastSnapshot === null) {
 				const { catalogUrl, cacheDir } = this.rowConfig();
 				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					baseUrl: catalogUrl,
+					origins: this.originsFor(catalogUrl),
 					cacheDir
 				});
 				this.lastSnapshot = snapshot;
@@ -1677,7 +2090,7 @@ let ShopGateway = (() => {
 			if (this.lastSnapshot === null) {
 				const { catalogUrl, cacheDir } = this.rowConfig();
 				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					baseUrl: catalogUrl,
+					origins: this.originsFor(catalogUrl),
 					cacheDir
 				});
 				this.lastSnapshot = snapshot;
@@ -1755,7 +2168,7 @@ let ShopGateway = (() => {
 			if (this.lastSnapshot === null) {
 				const { catalogUrl, cacheDir } = this.rowConfig();
 				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					baseUrl: catalogUrl,
+					origins: this.originsFor(catalogUrl),
 					cacheDir
 				});
 				this.lastSnapshot = snapshot;

package/lib/typert.host.js

@@ -154,7 +154,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopCatalogResult',
         schema: dsh_plugin_shop_shop_catalog_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":543,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":568,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installed',
@@ -169,7 +169,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop#shop/installed:result',
         schema: dsh_plugin_shop_shop_installed_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":723,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":748,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStart',
@@ -195,7 +195,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallResult',
         schema: dsh_plugin_shop_shop_installStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":593,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":618,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStatus',
@@ -220,7 +220,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallStatusResult',
         schema: dsh_plugin_shop_shop_installStatus_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":712,"column":3},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":737,"column":3},
     },
     {
       id: 'dsh-plugin-shop#shop/restart',
@@ -235,7 +235,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopRestartResult',
         schema: dsh_plugin_shop_shop_restart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":873,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":898,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/setEnabled',
@@ -260,7 +260,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopSetEnabledResult',
         schema: dsh_plugin_shop_shop_setEnabled_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":460,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":466,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/uninstallStart',
@@ -286,7 +286,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUninstallResult',
         schema: dsh_plugin_shop_shop_uninstallStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":815,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":840,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/updateStart',
@@ -311,7 +311,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUpdateResult',
         schema: dsh_plugin_shop_shop_updateStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":933,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":958,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/version',
@@ -326,7 +326,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopVersionResult',
         schema: dsh_plugin_shop_shop_version_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":917,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":942,"column":9},
     },
   ],
   model: {