@socketsecurity/lib 6.0.8 → 6.0.10

package/dist/npm/meta-cache.js

@@ -0,0 +1,318 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_json = require('../primordials/json.js');
+const require_primordials_url = require('../primordials/url.js');
+const require_http_request_response_types = require('../http-request/response-types.js');
+const require_http_request_node = require('../http-request/node.js');
+const require_cache_ttl_store = require('../cache/ttl/store.js');
+const require_npm_meta_slice = require('./meta-slice.js');
+const require_npm_registry = require('./registry.js');
+
+//#region src/npm/meta-cache.ts
+/**
+* @file Cached packument fetch — `getPackumentSlim` wires the pure slicer
+*   (`./meta-slice`) to an injectable HTTP adapter and the repo's
+*   `createTtlCache` (memo + cacache persistence + in-flight dedupe via
+*   `getOrFetch`). Every `getPackumentSlim`-backed cache is actually three
+*   `TtlCache` instances sharing one cacache directory (`getCachePeers`): the
+*   primary cache (the object callers hold), a persisted long-TTL last
+*   known-good store (`-stale` prefix, `STALE_TTL_MS`), and a short-TTL
+*   storm-control marker (`-storm` prefix, `STALE_SERVE_TTL_MS`). Three
+*   failure-handling policies layer on top:
+*
+*   - **`force`** bypasses a cached entry EXCEPT when it was written within the
+*     last 30 seconds, so a burst of forced refreshes coalesces into one
+*     upstream fetch instead of hammering the registry. A forced refresh NEVER
+*     removes the existing entry before fetching — on failure, whatever was
+*     cached before the call is untouched, and serve-stale-on-error (below)
+*     still has the persisted last-known-good value to fall back on.
+*   - **Negative caching** is narrow and short: only a definitive HTTP 404
+*     (package/version genuinely absent) is cached, for `NEGATIVE_TTL_MS`, and
+*     only when the persisted stale store holds no known-good data for that
+*     key. A transient error (network failure, 5xx) is NEVER negative-cached,
+*     and a still-fresh negative entry is discarded rather than trusted the
+*     moment known-good data exists in the persisted stale store — a retry
+*     always outranks a cached "not found" over real data.
+*   - **Serve-stale-on-error**: every successful fetch also persists the
+*     `PackumentMetaSlim` to the stale store, independent of the primary
+*     entry's own TTL — `STALE_TTL_MS` (7 days) comfortably outlives it, so the
+*     value survives both the primary entry's expiry and a process restart. If
+*     a later refresh fails for ANY reason — including a fresh 404 — the
+*     persisted value is served instead of propagating the error, and the
+*     storm-control marker is (re)written so a burst of callers within
+*     `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+*     failed. ETag revalidation requires a header-capable HTTP adapter; the
+*     current `NpmMetaHttpAdapter` is header-less by design so test doubles and
+*     `httpJson` stay interchangeable with the rest of the npm client surface —
+*     see `NpmMetaHttpAdapter`.
+*/
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const ACCEPT_ABBREVIATED = "application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*";
+const ACCEPT_FULL = "application/json";
+const CACHE_PREFIX = "npm-meta";
+const DEFAULT_TTL_MS = 900 * 1e3;
+const FORCE_MIN_AGE_MS = 3e4;
+const NEGATIVE_TTL_MS = 45e3;
+const STALE_TTL_MS = 10080 * 60 * 1e3;
+const STALE_SERVE_TTL_MS = 6e4;
+const DEFAULT_RETRIES = 2;
+const MAX_RETRIES = 5;
+/**
+* Thrown by `getPackumentSlim` (and the `getVersions` / `getLatestVersion`
+* exact-version / dist-tag lookups) when a specific package, version, or tag
+* is definitively absent. Carries `status` so `extractHttpStatus` reports it
+* the same way as a real `HttpResponseError`.
+*/
+var PackumentNotFoundError = class extends Error {
+	packageName;
+	status;
+	constructor(packageName, status, message) {
+		super(message ?? `getPackumentSlim: "${packageName}" not found (registry returned ${status}).`);
+		this.name = "PackumentNotFoundError";
+		this.packageName = packageName;
+		this.status = status;
+	}
+};
+/**
+* Build the cache key for one (registry, name, variant) tuple. Normalizes
+* `registry` first (`normalizeRegistryUrl`) so two spellings of the same
+* registry collapse to one key.
+*/
+function buildMetaCacheKey(registry, name, variant) {
+	return `${normalizeRegistryUrl(registry)}:${name}:${variant}`;
+}
+/**
+* Deep-clone a `PackumentMetaSlim` via a JSON round-trip — plain
+* JSON-roundtrippable data (strings, numbers, booleans, records), so this is
+* 3-5x faster than `structuredClone` and avoids the HTML structured-clone
+* algorithm entirely. Used at every public read boundary so no two callers
+* ever hold a reference to the same cached object.
+*/
+function cloneMeta(meta) {
+	return require_primordials_json.JSONParse(require_primordials_json.JSONStringify(meta));
+}
+/**
+* Maps a primary cache instance to its persisted-stale + storm-control
+* companions. Keyed by the `TtlCache` instance (not a plain module
+* singleton) so distinct cache instances — e.g. one per test — never see
+* each other's stale/storm data.
+*/
+const cachePeers = /* @__PURE__ */ new WeakMap();
+/**
+* Create a dedicated npm-meta cache instance — same `prefix` /
+* default-`ttl` as the module singleton, overridable per-call. Use this (vs.
+* the default singleton) for test isolation or a non-default TTL. Also
+* creates and registers this instance's persisted-stale + storm-control
+* companions (`registerCachePeers`).
+*/
+function createNpmMetaCache(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const prefix = opts.prefix ?? CACHE_PREFIX;
+	const cache = require_cache_ttl_store.createTtlCache({
+		prefix,
+		ttl: DEFAULT_TTL_MS,
+		...opts
+	});
+	registerCachePeers(cache, prefix);
+	return cache;
+}
+/**
+* The uncached fetch attempt for one packument, run through the negative-cache
+* decision: on success, persists the result to `staleCache` and returns a
+* `hit`; on a definitive 404 with no persisted stale data, returns a `miss`
+* (a normal, non-throwing outcome the caller decides how to cache); any other
+* failure (transient error, or a 404 when stale data DOES exist) rethrows so
+* the caller's serve-stale-on-error path can take over.
+*/
+async function fetchAndCacheEntry(name, key, fetchOptions, staleCache) {
+	try {
+		const meta = await fetchPackumentSlim(name, fetchOptions);
+		await staleCache.set(key, meta);
+		return {
+			cachedAt: Date.now(),
+			kind: "hit",
+			meta
+		};
+	} catch (e) {
+		if (e instanceof require_http_request_response_types.HttpResponseError && e.response.status === 404 && await staleCache.get(key) === void 0) return {
+			cachedAt: Date.now(),
+			kind: "miss",
+			status: 404
+		};
+		throw e;
+	}
+}
+/**
+* The uncached fetch — GET the packument with the variant's `Accept` header
+* and slice it. Split out so `getPackumentSlim`'s cache-key / force logic
+* stays readable. Throws (never negative-caches itself — that decision is
+* `getPackumentSlim`'s, which has the context to know whether stale data
+* already exists for this key).
+*/
+async function fetchPackumentSlim(name, resolved) {
+	const accept = resolved.variant === "full" ? ACCEPT_FULL : ACCEPT_ABBREVIATED;
+	const url = `${normalizeRegistryUrl(resolved.registry)}${require_npm_registry.encodeRegistryName(name)}`;
+	return require_npm_meta_slice.slicePackument(await resolved.http.json(url, {
+		headers: { Accept: accept },
+		retries: resolved.retries,
+		timeout: resolved.timeout
+	}));
+}
+/**
+* Resolve the persisted-stale + storm-control companions for a primary cache
+* instance, creating them lazily (under the default prefix) for a `TtlCache`
+* that wasn't created via `createNpmMetaCache`.
+*/
+function getCachePeers(cache) {
+	return cachePeers.get(cache) ?? registerCachePeers(cache, CACHE_PREFIX);
+}
+let defaultMetaCache;
+/**
+* The module-level default cache instance, created lazily on first use.
+*/
+function getDefaultMetaCache() {
+	if (defaultMetaCache === void 0) defaultMetaCache = createNpmMetaCache();
+	return defaultMetaCache;
+}
+/**
+* Fetch a package's packument, slice it down to `PackumentMetaSlim`, and
+* cache the result. Concurrent calls for the same (registry, name, variant)
+* dedupe to a single upstream request via the cache's `getOrFetch`. See the
+* file-level doc for the `force` / negative-cache / serve-stale-on-error
+* policies.
+*
+* @throws {PackumentNotFoundError} When the registry returns a definitive 404
+*   and no previously-good data exists for this key to serve instead.
+*/
+async function getPackumentSlim(name, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const cache = opts.cache ?? getDefaultMetaCache();
+	const registry = normalizeRegistryUrl(opts.registry ?? NPM_REGISTRY);
+	const variant = opts.variant ?? "abbreviated";
+	const retries = Math.min(opts.retries ?? DEFAULT_RETRIES, MAX_RETRIES);
+	const key = buildMetaCacheKey(registry, name, variant);
+	const { stale: staleCache, storm: stormCache } = getCachePeers(cache);
+	const fetchOptions = {
+		http: opts.http ?? { json: require_http_request_node.httpJson },
+		registry,
+		retries,
+		timeout: opts.timeout,
+		variant
+	};
+	if (opts.force) {
+		const cached = await cache.get(key);
+		if (cached?.kind === "hit" && Date.now() - cached.cachedAt <= FORCE_MIN_AGE_MS) return cloneMeta(cached.meta);
+		let result;
+		try {
+			result = await fetchAndCacheEntry(name, key, fetchOptions, staleCache);
+		} catch (e) {
+			const stale = await serveStaleOnFailure(staleCache, stormCache, key);
+			if (stale !== void 0) return cloneMeta(stale);
+			throw e;
+		}
+		await cache.set(key, result);
+		if (result.kind === "miss") throw new PackumentNotFoundError(name, result.status);
+		return cloneMeta(result.meta);
+	}
+	const storming = await stormCache.get(key);
+	if (storming !== void 0) return cloneMeta(storming);
+	const existing = await cache.get(key);
+	if (existing?.kind === "miss") {
+		if (Date.now() - existing.cachedAt <= NEGATIVE_TTL_MS && await staleCache.get(key) === void 0) throw new PackumentNotFoundError(name, existing.status);
+		await cache.delete(key);
+	}
+	let entry;
+	try {
+		entry = await cache.getOrFetch(key, () => fetchAndCacheEntry(name, key, fetchOptions, staleCache));
+	} catch (e) {
+		const stale = await serveStaleOnFailure(staleCache, stormCache, key);
+		if (stale !== void 0) return cloneMeta(stale);
+		throw e;
+	}
+	if (entry.kind === "miss") throw new PackumentNotFoundError(name, entry.status);
+	return cloneMeta(entry.meta);
+}
+/**
+* Look up the persisted last known-good value for `key`, if any — backed by
+* `STALE_TTL_MS` (7 days), independent of the primary cache's own TTL, and
+* readable from a fresh process. Returns a fresh clone so no two callers ever
+* share a reference to the same cached object.
+*/
+async function getStaleMeta(cache, key) {
+	const found = await getCachePeers(cache).stale.get(key);
+	return found === void 0 ? void 0 : cloneMeta(found);
+}
+/**
+* Normalize a registry base URL so two spellings of the same registry
+* collapse to one cache key and one request URL: lowercase the scheme+host,
+* and ensure exactly one trailing slash. Falls back to the input unchanged
+* when it isn't a parseable absolute URL.
+*/
+function normalizeRegistryUrl(registry) {
+	try {
+		const url = new require_primordials_url.URLCtor(registry);
+		return `${`${url.protocol}//${url.host}`.toLowerCase()}${url.pathname.endsWith("/") ? url.pathname : `${url.pathname}/`}${url.search}`;
+	} catch {
+		return registry;
+	}
+}
+/**
+* Create and register the persisted-stale + storm-control companion caches
+* for `cache` under `prefix`.
+*/
+function registerCachePeers(cache, prefix) {
+	const peers = {
+		stale: require_cache_ttl_store.createTtlCache({
+			prefix: `${prefix}-stale`,
+			ttl: STALE_TTL_MS
+		}),
+		storm: require_cache_ttl_store.createTtlCache({
+			prefix: `${prefix}-storm`,
+			ttl: STALE_SERVE_TTL_MS
+		})
+	};
+	cachePeers.set(cache, peers);
+	return peers;
+}
+/**
+* Persist `meta` as the last known-good value for `key`, independent of the
+* primary entry's own TTL/expiry.
+*/
+async function rememberStaleMeta(cache, key, meta) {
+	await getCachePeers(cache).stale.set(key, cloneMeta(meta));
+}
+/**
+* Serve-stale-on-error: look up the persisted last known-good value and, when
+* found, (re)write the storm-control marker so a burst of callers within
+* `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+* failed.
+*/
+async function serveStaleOnFailure(staleCache, stormCache, key) {
+	const priorGood = await staleCache.get(key);
+	if (priorGood === void 0) return;
+	await stormCache.set(key, priorGood);
+	return priorGood;
+}
+
+//#endregion
+exports.PackumentNotFoundError = PackumentNotFoundError;
+exports.buildMetaCacheKey = buildMetaCacheKey;
+exports.cloneMeta = cloneMeta;
+exports.createNpmMetaCache = createNpmMetaCache;
+exports.fetchAndCacheEntry = fetchAndCacheEntry;
+exports.fetchPackumentSlim = fetchPackumentSlim;
+exports.getCachePeers = getCachePeers;
+exports.getDefaultMetaCache = getDefaultMetaCache;
+exports.getPackumentSlim = getPackumentSlim;
+exports.getStaleMeta = getStaleMeta;
+exports.normalizeRegistryUrl = normalizeRegistryUrl;
+exports.registerCachePeers = registerCachePeers;
+exports.rememberStaleMeta = rememberStaleMeta;
+exports.serveStaleOnFailure = serveStaleOnFailure;

package/dist/npm/meta-slice.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Pure slicing of a raw npm packument into the client's slim shapes — no
+ *   network, no cache. `sliceVersionMeta` handles one version's `dist` /
+ *   `_npmUser` fields; `slicePackument` wraps it with the top-level packument
+ *   fields (`name`, `distTags`, `time.created` / `time.modified`).
+ */
+import type { PackumentMetaSlim, PackumentVersionMetaSlim, RawPackument, RawPackumentVersion } from './meta-types';
+/**
+ * Slice one raw version entry into its `PackumentVersionMetaSlim` shape.
+ *
+ * `trustedPublisher` / `staged` are only set when `_npmUser` is present on the
+ * entry (i.e. the packument was fetched with `variant: 'full'`) — on the
+ * abbreviated variant, trust signals are unknown rather than `false`.
+ */
+export declare function sliceOneVersion(entry: RawPackumentVersion, publishedAt: string | undefined): PackumentVersionMetaSlim;
+/**
+ * Slice a raw packument into `PackumentMetaSlim` — the top-level fields the
+ * client keeps (`name`, `distTags` with a guaranteed `latest` key,
+ * `timeCreated` / `timeModified`, `lastSynced`) plus the per-version map from
+ * `sliceVersionMeta`.
+ */
+export declare function slicePackument(packument: RawPackument): PackumentMetaSlim;
+/**
+ * Slice every version entry in a raw packument into `PackumentVersionMetaSlim`
+ * records, keyed by version string.
+ */
+export declare function sliceVersionMeta(packument: RawPackument): Record<string, PackumentVersionMetaSlim>;

package/dist/npm/meta-slice.js

@@ -0,0 +1,68 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/npm/meta-slice.ts
+/**
+* Slice one raw version entry into its `PackumentVersionMetaSlim` shape.
+*
+* `trustedPublisher` / `staged` are only set when `_npmUser` is present on the
+* entry (i.e. the packument was fetched with `variant: 'full'`) — on the
+* abbreviated variant, trust signals are unknown rather than `false`.
+*/
+function sliceOneVersion(entry, publishedAt) {
+	const dist = entry.dist;
+	const npmUser = entry._npmUser;
+	const slim = { time: publishedAt ?? "" };
+	if (entry.deprecated !== void 0) slim.deprecated = entry.deprecated;
+	if (entry.engines !== void 0) slim.engines = entry.engines;
+	if (dist?.integrity !== void 0) slim.integrity = dist.integrity;
+	if (dist?.shasum !== void 0) slim.shasum = dist.shasum;
+	if (dist?.tarball !== void 0) slim.tarball = dist.tarball;
+	if (dist?.attestations !== void 0) slim.attestations = dist.attestations;
+	if (npmUser !== void 0) {
+		slim.trustedPublisher = !!npmUser.trustedPublisher;
+		slim.staged = !!npmUser.approver;
+	}
+	return slim;
+}
+/**
+* Slice a raw packument into `PackumentMetaSlim` — the top-level fields the
+* client keeps (`name`, `distTags` with a guaranteed `latest` key,
+* `timeCreated` / `timeModified`, `lastSynced`) plus the per-version map from
+* `sliceVersionMeta`.
+*/
+function slicePackument(packument) {
+	const rawDistTags = packument["dist-tags"] ?? {};
+	return {
+		distTags: {
+			latest: rawDistTags["latest"] ?? "",
+			...rawDistTags
+		},
+		lastSynced: Date.now(),
+		name: packument.name ?? "",
+		timeCreated: packument.time?.["created"],
+		timeModified: packument.time?.["modified"],
+		versions: sliceVersionMeta(packument)
+	};
+}
+/**
+* Slice every version entry in a raw packument into `PackumentVersionMetaSlim`
+* records, keyed by version string.
+*/
+function sliceVersionMeta(packument) {
+	const rawVersions = packument.versions ?? {};
+	const time = packument.time ?? {};
+	const result = {};
+	const versions = Object.keys(rawVersions);
+	for (let i = 0, { length } = versions; i < length; i += 1) {
+		const version = versions[i];
+		result[version] = sliceOneVersion(rawVersions[version], time[version]);
+	}
+	return result;
+}
+
+//#endregion
+exports.sliceOneVersion = sliceOneVersion;
+exports.slicePackument = slicePackument;
+exports.sliceVersionMeta = sliceVersionMeta;

package/dist/npm/meta-types.d.ts

@@ -0,0 +1,282 @@
+/**
+ * @file Type surface for the npm metadata client (`./meta`, `./meta-cache`,
+ *   `./meta-slice`) — the raw packument shapes accepted from the registry, the
+ *   slimmed shapes the client returns, and the options/result records for the
+ *   derived helpers (`getVersions`, `getLatestVersion`, `getBatch`, …). Pure
+ *   types, no runtime side effects.
+ */
+import type { TtlCache } from '../cache/ttl/types';
+import type { HttpRequestOptions } from '../http-request/node';
+/**
+ * Per-name/per-batch failure shape returned by `getBatch` in place of a
+ * `PackumentMetaSlim` entry when a fetch fails and `throwOnError` is `false`.
+ */
+export interface PackageError {
+    error: string;
+    name: string;
+    status?: number | undefined;
+}
+/**
+ * Options for `getBatch`. Extends the single-package fetch options — every
+ * name in the batch shares the same registry/variant/cache/http adapter.
+ */
+export interface BatchOptions extends GetPackumentSlimOptions {
+    /**
+     * Number of packages fetched concurrently.
+     *
+     * @default 8
+     */
+    concurrency?: number | undefined;
+    /**
+     * When `true`, every item is still attempted (nothing is aborted
+     * in-flight), but once every item has settled, the error from the
+     * LOWEST-INDEX failed item is thrown — deterministic regardless of settle
+     * order. When `false` (default), failures are captured as `PackageError`
+     * entries at their original index.
+     *
+     * @default false
+     */
+    throwOnError?: boolean | undefined;
+}
+/**
+ * Index-preserving element of `getBatch`'s return array — either the slimmed
+ * packument or a `PackageError` for that name.
+ */
+export type BatchResult = PackageError | PackumentMetaSlim;
+/**
+ * Options shared by every `getPackumentSlim`-backed helper.
+ */
+export interface GetPackumentSlimOptions {
+    /**
+     * Cache instance backing the fetch. Defaults to a lazily-created module
+     * singleton (`prefix: 'npm-meta'`, 15-minute TTL). Pass a dedicated instance
+     * (`createNpmMetaCache`) for test isolation or a non-default TTL.
+     */
+    cache?: TtlCache | undefined;
+    /**
+     * Bypass a cached entry and refetch — unless the entry is younger than 30
+     * seconds, in which case the cached value is still served (coalesces bursts
+     * of forced refreshes into one upstream fetch).
+     *
+     * @default false
+     */
+    force?: boolean | undefined;
+    /**
+     * Injectable HTTP adapter, mirroring `NpmHttpOptions` from `./registry`.
+     * Defaults to `httpJson` from `../http-request/node`.
+     */
+    http?: NpmMetaHttpAdapter | undefined;
+    /**
+     * Registry base URL.
+     *
+     * @default 'https://registry.npmjs.org'
+     */
+    registry?: string | undefined;
+    /**
+     * Forwarded to the HTTP adapter.
+     */
+    retries?: number | undefined;
+    /**
+     * Forwarded to the HTTP adapter.
+     */
+    timeout?: number | undefined;
+    /**
+     * `'abbreviated'` (default) omits `_npmUser` trust signals and most
+     * metadata — cheap, used for version listing. `'full'` is required to read
+     * `trustedPublisher` / `staged` / `integrity` / `shasum`.
+     *
+     * @default 'abbreviated'
+     */
+    variant?: PackumentVariant | undefined;
+}
+/**
+ * Options for `getVersions` / `getLatestVersion` — semver filtering layered on
+ * top of the base fetch options.
+ */
+export interface GetVersionsOptions extends GetPackumentSlimOptions {
+    /**
+     * Time floor — only versions published at or after this instant are kept
+     * (inclusive). Accepts an ISO 8601 string OR a numeric epoch (a `number` or
+     * a numeric string matching `/^\d+$/`) — a string is treated as an epoch
+     * ONLY when it is entirely digits; anything else is parsed as an ISO 8601
+     * date, so a date string is never misread as an epoch. Throws `RangeError`
+     * (via `toEpochMs`) when the value is neither. A version with no recorded
+     * publish time is EXCLUDED rather than included by default: it cannot be
+     * proven to satisfy the floor, and for a time-based filter a false negative
+     * (unfairly dropped) is the safer failure mode than a false positive
+     * (unfairly kept).
+     */
+    after?: string | number | undefined;
+    /**
+     * Whether `range` may match a prerelease version (`2.0.0-beta.0`) even when
+     * the range itself has no prerelease component. Passed explicitly to every
+     * semver call this module makes — never left to the vendored semver's
+     * implicit default.
+     *
+     * @default false
+     */
+    includePrerelease?: boolean | undefined;
+    /**
+     * Loose semver parsing for `range`.
+     *
+     * @default false
+     */
+    loose?: boolean | undefined;
+    /**
+     * Maturity filter in days — only versions whose publish time is at least
+     * this many days old are kept. The publish time is anchored to the END of
+     * its UTC day before `minAgeDays` is added (Socket soak-window semantics), so
+     * a version published at any point during a UTC day matures at the same
+     * wall-clock instant. Like `after`, a version with no recorded publish time
+     * is excluded.
+     */
+    minAgeDays?: number | undefined;
+    /**
+     * A semver range, an exact version, or a dist-tag name — resolved in that
+     * priority order against the packument (npm forbids a dist-tag name that is
+     * also valid semver, so the three never collide):
+     *
+     * 1. A dist-tag key (e.g. `"beta"`) resolves to the single version it points to.
+     *    Throws `PackumentNotFoundError` if that version is missing from the
+     *    packument (a stale or inconsistent packument).
+     * 2. An exact, valid semver version resolves to itself. Throws
+     *    `PackumentNotFoundError` if it isn't in the packument — `getVersions`
+     *    never falls back to the full list on a specific miss.
+     * 3. Anything else is treated as a semver range filter. Versions that don't
+     *    satisfy it are dropped; an empty result (not an error) when nothing
+     *    matches, since a narrow-but-valid range matching zero versions is not a
+     *    "not found" case.
+     */
+    range?: string | undefined;
+}
+/**
+ * Result of `getVersions` — the filtered version list plus enough context
+ * (`time`, `distTags`) that callers rarely need a second fetch.
+ */
+export interface GetVersionsResult {
+    distTags: Record<string, string>;
+    time: Record<string, string>;
+    versions: string[];
+}
+/**
+ * Result of `getLatestVersion`.
+ */
+export interface LatestVersionResult {
+    distTags: Record<string, string>;
+    publishedAt: string | undefined;
+    version: string;
+}
+/**
+ * Injectable HTTP adapter for the metadata client. Signature-compatible with
+ * `httpJson` from `../http-request/node` so the default is a direct reference.
+ */
+export interface NpmMetaHttpAdapter {
+    json<T>(url: string, options?: HttpRequestOptions | undefined): Promise<T>;
+}
+/**
+ * The slimmed packument this client returns — top-level fields plus the
+ * per-version map from `sliceVersionMeta`.
+ */
+export interface PackumentMetaSlim {
+    distTags: Record<string, string>;
+    /**
+     * `Date.now()` at fetch time (not the registry's `time.modified`) — lets
+     * callers reason about cache freshness without inspecting the cache layer.
+     */
+    lastSynced: number;
+    name: string;
+    timeCreated?: string | undefined;
+    timeModified?: string | undefined;
+    versions: Record<string, PackumentVersionMetaSlim>;
+}
+/**
+ * `'abbreviated'` matches npm's `Accept: application/vnd.npm.install-v1+json`
+ * fast packument (no `_npmUser`); `'full'` is the plain packument.
+ */
+export type PackumentVariant = 'abbreviated' | 'full';
+/**
+ * Slimmed per-version metadata — `sliceVersionMeta`'s output shape for one
+ * version entry.
+ */
+export interface PackumentVersionMetaSlim {
+    attestations?: unknown | undefined;
+    deprecated?: string | undefined;
+    engines?: Record<string, string> | undefined;
+    integrity?: string | undefined;
+    shasum?: string | undefined;
+    /**
+     * Boolean form of `_npmUser?.approver` — `true` when the version was
+     * published through a staged/approval flow.
+     */
+    staged?: boolean | undefined;
+    tarball?: string | undefined;
+    time: string;
+    /**
+     * Boolean form of `_npmUser?.trustedPublisher`.
+     */
+    trustedPublisher?: boolean | undefined;
+}
+/**
+ * Raw `_npmUser` shape from a full-variant packument version entry.
+ */
+export interface RawNpmUser {
+    approver?: unknown | undefined;
+    trustedPublisher?: boolean | undefined;
+}
+/**
+ * Raw packument JSON as received from the registry — the input to
+ * `slicePackument` / `sliceVersionMeta`.
+ *
+ * Deliberately separate from `./registry`'s `PackumentRecord` /
+ * `PackumentVersion` / `PackumentVersionDist` hierarchy, not an oversight:
+ * this client needs `_npmUser`, `engines`, and the full `dist.integrity` /
+ * `dist.shasum` fields (for `getVersionTrustInfo` and the
+ * abbreviated-vs-full variant split), none of which `./registry`'s
+ * browser-safe, Trusted-Publisher-detection-only surface carries. The two
+ * hierarchies are NOT meant to be interchangeable — passing a `./registry`
+ * `PackumentVersion` where a `RawPackumentVersion` is expected needs an
+ * explicit re-shape, since `PackumentVersion`'s `engines` and other extra
+ * fields resolve through its `[field: string]: unknown` index signature.
+ * `test/unit/npm/meta-types.test.mts` type-checks the fields the two
+ * hierarchies DO intentionally share, so a future edit to either side can't
+ * silently break that overlap.
+ */
+export interface RawPackument {
+    'dist-tags'?: Record<string, string> | undefined;
+    name?: string | undefined;
+    time?: Record<string, string> | undefined;
+    versions?: Record<string, RawPackumentVersion> | undefined;
+}
+/**
+ * Raw per-version entry from a packument. `_npmUser` is present only on the
+ * `'full'` variant.
+ */
+export interface RawPackumentVersion {
+    _npmUser?: RawNpmUser | undefined;
+    deprecated?: string | undefined;
+    dist?: RawVersionDist | undefined;
+    engines?: Record<string, string> | undefined;
+    [field: string]: unknown;
+}
+/**
+ * Raw `dist` shape from a packument version entry.
+ */
+export interface RawVersionDist {
+    attestations?: unknown | undefined;
+    integrity?: string | undefined;
+    shasum?: string | undefined;
+    tarball?: string | undefined;
+}
+/**
+ * Per-version trust signals returned by `getVersionTrustInfo`. `approver`
+ * mirrors `PackumentVersionMetaSlim.staged` — named for its source field
+ * (`_npmUser.approver`) since this helper is specifically about trust
+ * provenance rather than general slimmed metadata.
+ */
+export interface VersionTrustInfo {
+    approver?: boolean | undefined;
+    attestations?: unknown | undefined;
+    integrity?: string | undefined;
+    shasum?: string | undefined;
+    trustedPublisher?: boolean | undefined;
+}