@socketsecurity/lib 6.0.9 → 6.0.10

package/dist/npm/meta.js

@@ -0,0 +1,347 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+const require_errors_message = require('../errors/message.js');
+const require_http_request_response_types = require('../http-request/response-types.js');
+const require_promises_iterate = require('../promises/iterate.js');
+const require_npm_meta_slice = require('./meta-slice.js');
+const require_npm_meta_cache = require('./meta-cache.js');
+const require_versions__internal = require('../versions/_internal.js');
+
+//#region src/npm/meta.ts
+/**
+* @file Cached, batch-capable npm registry metadata client — the Socket-wide
+*   replacement for ad-hoc packument fetchers. Sibling of `./registry` (pure
+*   parsers + injectable HTTP): this module owns caching (`./meta-cache`),
+*   slimming (`./meta-slice`), and the derived helpers built on top
+*   (`getVersions`, `getLatestVersion`, `getPublishDate`,
+*   `getVersionTrustInfo`, `getBatch`) plus their `safe*` fail-open variants.
+*   Node-only (the cache layer is cacache-backed) — unlike `./registry`, this
+*   module is not browser-safe.
+*/
+/**
+* Extract the HTTP status code from a caught error when it came from the
+* `httpJson` adapter (`HttpResponseError`) or a synthesized
+* `PackumentNotFoundError`; `undefined` for anything else (network failure,
+* abort, a custom test-double error).
+*/
+function extractHttpStatus(error) {
+	if (error instanceof require_http_request_response_types.HttpResponseError) return error.response.status;
+	if (error instanceof require_npm_meta_cache.PackumentNotFoundError) return error.status;
+}
+/**
+* Fetch `getPackumentSlim` for every name with bounded concurrency, returning
+* an index-preserving array. Every item is attempted regardless of
+* `throwOnError` — nothing is aborted in-flight. A per-item failure becomes a
+* `PackageError` at that index; when `throwOnError` is `true`, once every
+* item has settled the error from the LOWEST-INDEX failed item is thrown —
+* deterministic regardless of settle order.
+*/
+async function getBatch(names, options) {
+	const opts = {
+		__proto__: null,
+		concurrency: 8,
+		throwOnError: false,
+		...options
+	};
+	const results = Array.from({ length: names.length });
+	const failures = [];
+	await require_promises_iterate.pEach(names.map((name, index) => ({
+		index,
+		name
+	})), async (item) => {
+		try {
+			results[item.index] = await require_npm_meta_cache.getPackumentSlim(item.name, opts);
+		} catch (e) {
+			failures.push({
+				error: e,
+				index: item.index
+			});
+			results[item.index] = {
+				error: require_errors_message.errorMessage(e),
+				name: item.name,
+				status: extractHttpStatus(e)
+			};
+		}
+	}, opts.concurrency);
+	if (opts.throwOnError && failures.length > 0) {
+		let lowest = failures[0];
+		for (let i = 0, { length } = failures; i < length; i += 1) {
+			const failure = failures[i];
+			if (failure.index < lowest.index) lowest = failure;
+		}
+		throw lowest.error;
+	}
+	return results;
+}
+/**
+* Resolve the latest version — `distTags.latest` when no `range` is given, or
+* (when `range` is given) the same dist-tag / exact-version / semver-range
+* resolution `getVersions` uses (`resolveRequestedVersions`), narrowed to a
+* single version. There is no silent fallback to `distTags.latest`: a
+* dist-tag or exact version that doesn't resolve throws (same contract as
+* `getVersions`), and a range matching nothing throws too — an unsatisfiable
+* range must never return a version outside what the caller asked for.
+*
+* @throws {PackumentNotFoundError} When `range` names an exact version or
+*   dist-tag that isn't present in the packument, or a semver range that no
+*   version satisfies.
+*/
+async function getLatestVersion(name, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const meta = await require_npm_meta_cache.getPackumentSlim(name, opts);
+	if (!opts.range) {
+		const version = meta.distTags["latest"] ?? "";
+		return {
+			distTags: meta.distTags,
+			publishedAt: meta.versions[version]?.time || void 0,
+			version
+		};
+	}
+	const candidates = resolveRequestedVersions(name, meta, opts);
+	const version = require_versions__internal.getSemver().maxSatisfying(candidates, "*", {
+		includePrerelease: true,
+		loose: !!opts.loose
+	});
+	if (!version) throw new require_npm_meta_cache.PackumentNotFoundError(name, 404, `getLatestVersion: no version of "${name}" satisfies "${opts.range}".`);
+	return {
+		distTags: meta.distTags,
+		publishedAt: meta.versions[version]?.time || void 0,
+		version
+	};
+}
+/**
+* Look up a single version's publish time (ISO string), or `undefined` when
+* the version isn't in the packument.
+*/
+async function getPublishDate(name, version, options) {
+	return (await require_npm_meta_cache.getPackumentSlim(name, options)).versions[version]?.time || void 0;
+}
+/**
+* Per-version trust signals (forces `variant: 'full'` — `_npmUser` is absent
+* from the abbreviated packument).
+*/
+async function getVersionTrustInfo(name, options) {
+	const meta = await require_npm_meta_cache.getPackumentSlim(name, {
+		__proto__: null,
+		...options,
+		variant: "full"
+	});
+	const result = {};
+	const versions = Object.keys(meta.versions);
+	for (let i = 0, { length } = versions; i < length; i += 1) {
+		const version = versions[i];
+		const entry = meta.versions[version];
+		result[version] = {
+			approver: entry.staged,
+			attestations: entry.attestations,
+			integrity: entry.integrity,
+			shasum: entry.shasum,
+			trustedPublisher: entry.trustedPublisher
+		};
+	}
+	return result;
+}
+/**
+* List versions, optionally filtered by `range` (a semver range, an exact
+* version, or a dist-tag name — see `GetVersionsOptions.range`), an `after`
+* time floor, and/or a `minAgeDays` maturity window. See `GetVersionsOptions`
+* for the `minAgeDays` end-of-UTC-day anchor semantics.
+*
+* @throws {PackumentNotFoundError} When `range` names an exact version or
+*   dist-tag that isn't present in the packument.
+*/
+async function getVersions(name, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const meta = await require_npm_meta_cache.getPackumentSlim(name, opts);
+	const time = {};
+	const versionKeys = Object.keys(meta.versions);
+	for (let i = 0, { length } = versionKeys; i < length; i += 1) {
+		const version = versionKeys[i];
+		time[version] = meta.versions[version].time;
+	}
+	let versions = resolveRequestedVersions(name, meta, opts);
+	if (opts.after !== void 0) {
+		const floorMs = toEpochMs(opts.after);
+		versions = versions.filter((v) => {
+			const publishedAt = time[v];
+			return !!publishedAt && Date.parse(publishedAt) >= floorMs;
+		});
+	}
+	if (opts.minAgeDays !== void 0) {
+		const minAgeDays = opts.minAgeDays;
+		const now = Date.now();
+		versions = versions.filter((v) => {
+			const publishedAt = time[v];
+			return !!publishedAt && isMatured(publishedAt, minAgeDays, now);
+		});
+	}
+	return {
+		distTags: meta.distTags,
+		time,
+		versions
+	};
+}
+/**
+* `true` when `publishedAt` is at least `minAgeDays` days old, anchored to the
+* END of `publishedAt`'s UTC day (Socket soak-window semantics) — a version
+* published at any point during a UTC day matures at the same wall-clock
+* instant, `minAgeDays` later at 23:59:59.999 UTC. Returns `false` for an
+* unparseable `publishedAt`.
+*/
+function isMatured(publishedAt, minAgeDays, now = Date.now()) {
+	const publishedMs = Date.parse(publishedAt);
+	if (Number.isNaN(publishedMs)) return false;
+	const published = new Date(publishedMs);
+	return now >= Date.UTC(published.getUTCFullYear(), published.getUTCMonth(), published.getUTCDate(), 23, 59, 59, 999) + minAgeDays * 24 * 60 * 60 * 1e3;
+}
+/**
+* Resolve `options.range` against a packument's dist-tags / version set.
+* Exported standalone so its resolution order is independently testable. See
+* `GetVersionsOptions.range` for the full priority-order contract (dist-tag →
+* exact version → semver range filter).
+*
+* @throws {PackumentNotFoundError} When `range` names a dist-tag or exact
+*   version that isn't present in the packument.
+*/
+function resolveRequestedVersions(name, meta, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const allVersions = Object.keys(meta.versions);
+	const { range } = opts;
+	if (!range) return allVersions;
+	if (Object.hasOwn(meta.distTags, range)) {
+		const tagged = meta.distTags[range];
+		if (!Object.hasOwn(meta.versions, tagged)) throw new require_npm_meta_cache.PackumentNotFoundError(name, 404, `getVersions: dist-tag "${range}" on "${name}" points to version "${tagged}", which is not in the packument.`);
+		return [tagged];
+	}
+	const semver = require_versions__internal.getSemver();
+	const normalized = semver.valid(range, { loose: !!opts.loose });
+	if (normalized) {
+		const resolvedVersion = Object.hasOwn(meta.versions, normalized) ? normalized : range;
+		if (!Object.hasOwn(meta.versions, resolvedVersion)) throw new require_npm_meta_cache.PackumentNotFoundError(name, 404, `getVersions: version "${range}" not found for "${name}".`);
+		return [resolvedVersion];
+	}
+	const semverOptions = {
+		includePrerelease: !!opts.includePrerelease,
+		loose: !!opts.loose
+	};
+	return allVersions.filter((v) => semver.satisfies(v, range, semverOptions));
+}
+/**
+* Fail-open `getLatestVersion` — `undefined` on any error.
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
+async function safeGetLatestVersion(name, options) {
+	try {
+		return await getLatestVersion(name, options);
+	} catch {
+		return;
+	}
+}
+/**
+* Fail-open `getPackumentSlim` — `undefined` on any error.
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
+async function safeGetPackumentSlim(name, options) {
+	try {
+		return await require_npm_meta_cache.getPackumentSlim(name, options);
+	} catch {
+		return;
+	}
+}
+/**
+* Fail-open `getPublishDate` — `undefined` on any error.
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
+async function safeGetPublishDate(name, version, options) {
+	try {
+		return await getPublishDate(name, version, options);
+	} catch {
+		return;
+	}
+}
+/**
+* Fail-open `getVersionTrustInfo` — an empty record on any error.
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
+async function safeGetVersionTrustInfo(name, options) {
+	try {
+		return await getVersionTrustInfo(name, options);
+	} catch {
+		return {};
+	}
+}
+/**
+* Fail-open `getVersions` — an empty result on any error.
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
+async function safeGetVersions(name, options) {
+	try {
+		return await getVersions(name, options);
+	} catch {
+		return {
+			distTags: {},
+			time: {},
+			versions: []
+		};
+	}
+}
+const ALL_DIGITS_RE = /^\d+$/;
+/**
+* Resolve an `after` filter value to epoch milliseconds. A `number` is used
+* as-is. A string is treated as an epoch ONLY when it is entirely digits
+* (`/^\d+$/`) — never by trying `Number()` first, which would also accept
+* whitespace, exponents, and other numeric-ish forms `Date.parse` should get
+* a chance at instead. Anything not all-digits is parsed via `Date.parse`.
+*
+* @throws {RangeError} When `after` cannot be resolved to a valid epoch —
+*   silently skipping the `after` filter on an unparseable value is the exact
+*   reference-implementation bug this module exists to avoid.
+*/
+function toEpochMs(after) {
+	const epochMs = typeof after === "number" ? after : ALL_DIGITS_RE.test(after) ? Number(after) : Date.parse(after);
+	if (Number.isNaN(epochMs)) throw new require_primordials_error.RangeErrorCtor(`toEpochMs: "${after}" is not a valid ISO 8601 date string or numeric epoch`);
+	return epochMs;
+}
+
+//#endregion
+exports.PackumentNotFoundError = require_npm_meta_cache.PackumentNotFoundError;
+exports.buildMetaCacheKey = require_npm_meta_cache.buildMetaCacheKey;
+exports.createNpmMetaCache = require_npm_meta_cache.createNpmMetaCache;
+exports.extractHttpStatus = extractHttpStatus;
+exports.fetchPackumentSlim = require_npm_meta_cache.fetchPackumentSlim;
+exports.getBatch = getBatch;
+exports.getDefaultMetaCache = require_npm_meta_cache.getDefaultMetaCache;
+exports.getLatestVersion = getLatestVersion;
+exports.getPackumentSlim = require_npm_meta_cache.getPackumentSlim;
+exports.getPublishDate = getPublishDate;
+exports.getStaleMeta = require_npm_meta_cache.getStaleMeta;
+exports.getVersionTrustInfo = getVersionTrustInfo;
+exports.getVersions = getVersions;
+exports.isMatured = isMatured;
+exports.rememberStaleMeta = require_npm_meta_cache.rememberStaleMeta;
+exports.resolveRequestedVersions = resolveRequestedVersions;
+exports.safeGetLatestVersion = safeGetLatestVersion;
+exports.safeGetPackumentSlim = safeGetPackumentSlim;
+exports.safeGetPublishDate = safeGetPublishDate;
+exports.safeGetVersionTrustInfo = safeGetVersionTrustInfo;
+exports.safeGetVersions = safeGetVersions;
+exports.sliceOneVersion = require_npm_meta_slice.sliceOneVersion;
+exports.slicePackument = require_npm_meta_slice.slicePackument;
+exports.sliceVersionMeta = require_npm_meta_slice.sliceVersionMeta;
+exports.toEpochMs = toEpochMs;

package/dist/npm/registry.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @file Browser-safe npm registry client — pure parsers + injectable-fetch
+ *   shell. Safe for Chrome MV3 service workers, content scripts, and any
+ *   environment without `node:*` builtins. The HTTP adapter is injected by the
+ *   caller (`{ http: { json } }`) so Node callers pass `httpJson` from
+ *   `@socketsecurity/lib/http-request` and browser callers pass `httpJson` from
+ *   `@socketsecurity/lib/http-request/browser`. No network dependency at module
+ *   load time.
+ *
+ *   ## Endpoints covered
+ *
+ *   - Packument: `registry.npmjs.org/<pkg>`
+ *   - Version manifest (package.json):
+ *     `cdn.jsdelivr.net/npm/<pkg>@<ver>/package.json`
+ *   - Weekly downloads: `api.npmjs.org/downloads/point/last-week/<pkg>`
+ *   - Attestation bundle: `registry.npmjs.org/-/npm/v1/attestations/<pkg>@<ver>`
+ *   - Org packages: `registry.npmjs.org/-/org/<org>/package`
+ *
+ *   ## URL encoding
+ *
+ *   Registry endpoints (`registry.npmjs.org`, `api.npmjs.org`): scoped names
+ *   encode to `@scope%2Fname` (one `encodeURIComponent` call that encodes the
+ *   slash, then `%40` is restored to `@`).
+ *   CDN endpoint (`cdn.jsdelivr.net`): scope and name are encoded separately,
+ *   preserving the literal `/` between them. A prior extension bug sent
+ *   `@scope%2Fname` to the CDN which returned 400; the fix is this split-encode
+ *   path.
+ *
+ *   ## Trusted Publisher detection
+ *
+ *   From the packument alone, only `!!dist.attestations` is detectable —
+ *   proving provenance was signed but not identifying which repo or workflow is
+ *   configured as the TP. To get repo + workflow call `getAttestations()` then
+ *   `parseProvenancePredicate()` to parse the SLSA
+ *   `externalParameters.workflow` field. The npm access page
+ *   (`/package/<name>/access`) is session-only HTML and is out of scope for
+ *   this public client.
+ */
+/**
+ * Injectable HTTP adapter. Pass `httpJson` from
+ * `@socketsecurity/lib/http-request` (Node) or
+ * `@socketsecurity/lib/http-request/browser` (browser / extension).
+ */
+export interface NpmHttpOptions {
+    http: {
+        json<T>(url: string): Promise<T>;
+    };
+}
+export interface AttestationBundleEntry {
+    predicateType?: string | undefined;
+    bundle?: unknown | undefined;
+}
+export interface AttestationBundle {
+    attestations?: AttestationBundleEntry[] | undefined;
+}
+export interface DownloadsRecord {
+    downloads: number;
+    package: string;
+}
+export interface OrgPackagesRecord {
+    [packageName: string]: string;
+}
+export interface PackumentVersionDist {
+    attestations?: {
+        url?: string | undefined;
+    } | undefined;
+    tarball?: string | undefined;
+}
+export interface PackumentVersion {
+    deprecated?: string | undefined;
+    dist?: PackumentVersionDist | undefined;
+    [field: string]: unknown;
+}
+export interface PackumentRecord {
+    'dist-tags': Record<string, string>;
+    distTags: Record<string, string>;
+    name: string;
+    time?: Record<string, string> | undefined;
+    versions: Record<string, PackumentVersion>;
+}
+export interface ProvenancePredicate {
+    buildDefinition?: {
+        externalParameters?: {
+            workflow?: {
+                path?: string | undefined;
+                ref?: string | undefined;
+                repository?: string | undefined;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+    runDetails?: {
+        builder?: {
+            id?: string | undefined;
+        } | undefined;
+    } | undefined;
+}
+/**
+ * Result of Trusted Publisher detection from a version entry.
+ *
+ * When `configured` is true, `repo` and `workflow` are populated only if the
+ * attestation bundle was fetched and parsed — `detectTrustedPublisher()` alone
+ * (from packument data) cannot provide them. Call `getAttestations()` +
+ * `parseProvenancePredicate()` to obtain those fields.
+ */
+export interface TrustedPublisherResult {
+    configured: boolean;
+    repo?: string | undefined;
+    workflow?: string | undefined;
+}
+/**
+ * Build the CDN path `<encoded-name>@<encoded-version>/package.json`.
+ * Exposed as a pure function so callers can construct the full URL themselves.
+ */
+export declare function buildCdnPath(name: string, version: string): string;
+/**
+ * Detect Trusted Publisher configuration from a packument version entry.
+ *
+ * From the packument alone, only the presence of `dist.attestations` is
+ * detectable (`configured: true` means provenance was signed; it does NOT
+ * confirm that a TP source is configured on npmjs.com). To get `repo` and
+ * `workflow`, fetch the attestation bundle with `getAttestations()` and parse
+ * it with `parseProvenancePredicate()`.
+ */
+export declare function detectTrustedPublisher(versionEntry: PackumentVersion): TrustedPublisherResult;
+/**
+ * Encode a package name for use in registry CDN URLs.
+ * Scope and name are encoded individually, preserving the literal `/`.
+ * Use this for `cdn.jsdelivr.net` URLs — fixes the `@scope%2Fname` → 400 bug.
+ */
+export declare function encodeCdnName(name: string): string;
+/**
+ * Encode a package name for use in registry / download-API URLs.
+ *
+ * Registry form (`cdn: false`, the default): `encodeURIComponent` then restore
+ * the leading `@` so `@scope/name` → `@scope%2Fname`.
+ *
+ * CDN form (`cdn: true`): scope and name are encoded individually so the
+ * literal `/` separator is preserved: `@scope/name` → `@scope/name` (each
+ * segment encoded separately). This fixes the `@scope%2Fname` → 400 bug on
+ * `cdn.jsdelivr.net`.
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
+export declare function encodePackageName(name: string, options?: {
+    cdn?: boolean | undefined;
+} | undefined): string;
+/**
+ * Encode a package name for use in registry / download-API URLs.
+ * Applies `encodeURIComponent` then restores `@` so scoped names become
+ * `@scope%2Fname`.
+ */
+export declare function encodeRegistryName(name: string): string;
+/**
+ * Fetch the attestation bundle for a package version from the npm transparency
+ * log. Returns `undefined` when no attestations entry is present in the
+ * packument (404 is treated as absent rather than an error).
+ */
+export declare function getAttestations(name: string, version: string, options: NpmHttpOptions): Promise<AttestationBundle | undefined>;
+/**
+ * Fetch the list of packages belonging to an npm org.
+ * Returns package names as a string array.
+ */
+export declare function getOrgPackages(org: string, options: NpmHttpOptions): Promise<string[]>;
+/**
+ * Fetch and parse the full packument for a package.
+ */
+export declare function getPackument(name: string, options: NpmHttpOptions): Promise<PackumentRecord>;
+/**
+ * Fetch a version's package.json via the jsDelivr CDN.
+ *
+ * Uses split-encode for scoped names so `cdn.jsdelivr.net` receives the literal
+ * `/` between scope and name (not `%2F` which causes 400s).
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
+export declare function getVersionManifest(name: string, version: string, options: NpmHttpOptions): Promise<Record<string, unknown>>;
+/**
+ * Fetch last-week download counts for a package from the npm downloads API.
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
+export declare function getWeeklyDownloads(name: string, options: NpmHttpOptions): Promise<DownloadsRecord>;
+/**
+ * Return true when `versionEntry.dist.attestations` is present — indicating a
+ * SLSA provenance attestation was produced for this version.
+ */
+export declare function hasProvenance(versionEntry: PackumentVersion): boolean;
+/**
+ * Return `true` when `version` of `name` is already published to the registry.
+ * Authoritative — reads the packument's `versions` map rather than a CDN, so a
+ * pre-publish guard never false-negatives on CDN lag (the asymmetric-cost case:
+ * a wrong "not published" invites a duplicate-version publish attempt). Returns
+ * `false` when the package does not exist or the packument fetch fails.
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
+export declare function isVersionPublished(name: string, version: string, options: NpmHttpOptions): Promise<boolean>;
+/**
+ * Parse a raw packument JSON response into a typed `PackumentRecord`.
+ * Adds the `distTags` alias for `dist-tags` so callers don't need bracket
+ * notation. Returns `undefined` when the input is not a valid packument shape.
+ */
+export declare function parsePackument(raw: unknown): PackumentRecord | undefined;
+/**
+ * Parse an npm transparency-log attestation bundle (the JSON returned from
+ * `registry.npmjs.org/-/npm/v1/attestations/<pkg>@<ver>`) and extract the
+ * SLSA provenance predicate.
+ *
+ * Returns the first SLSA provenance v1 predicate found, or `undefined` when
+ * none is present or the bundle is malformed.
+ */
+export declare function parseProvenancePredicate(bundle: unknown): ProvenancePredicate | undefined;