@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/dlx/arborist.d.ts

@@ -1,46 +1,43 @@
 /**
- * @fileoverview Safe Arborist wrapper for dlx installs and lockfile-only
- * resolution.
+ * @file Safe Arborist wrapper for dlx installs and lockfile-only resolution.
+ *   Every Arborist invocation in this module is configured with a fixed set of
+ *   security-hardening options mirroring socket-cli v1.1.79 SafeArborist:
  *
- * Every Arborist invocation in this module is configured with a fixed set
- * of security-hardening options mirroring socket-cli v1.1.79 SafeArborist:
- *
- *   - audit:         false   — no network call to the npm audit endpoint
- *   - fund:          false   — no collection/display of funding URLs
- *   - ignoreScripts: true    — no preinstall/install/postinstall scripts
- *   - progress:      false   — no progress bar on stdout
- *   - saveBundle:    false   — never update bundledDependencies
- *   - silent:        true    — suppress Arborist's default log output
- *
- * `save` varies by operation: {@link safeIdealTree} uses `save: true` so
- * Arborist writes `package-lock.json`; {@link safeReify} uses `save: false`
- * so the caller's `package.json` is never rewritten.
- *
- * A `.npmrc` with the equivalent settings is also written into the
- * install directory as a belt-and-suspenders defense for any downstream
- * tool that reads it.
+ *   - audit: false — no network call to the npm audit endpoint
+ *   - fund: false — no collection/display of funding URLs
+ *   - ignoreScripts: true — no preinstall/install/postinstall scripts
+ *   - progress: false — no progress bar on stdout
+ *   - saveBundle: false — never update bundledDependencies
+ *   - silent: true — suppress Arborist's default log output `save` varies by
+ *     operation: {@link safeIdealTree} uses `save: true` so Arborist writes
+ *     `package-lock.json`; {@link safeReify} uses `save: false` so the caller's
+ *     `package.json` is never rewritten. A `.npmrc` with the equivalent
+ *     settings is also written into the install directory as a
+ *     belt-and-suspenders defense for any downstream tool that reads it.
  */
+import Arborist from '../external/@npmcli/arborist';
 /**
  * Shared options for the safe-arborist operations below.
  */
 export interface SafeArboristOptions {
     /**
      * Install directory. Arborist reads `package.json` (and, for reify,
-     * `package-lock.json`) from this directory and creates `node_modules`
-     * here when installing.
+     * `package-lock.json`) from this directory and creates `node_modules` here
+     * when installing.
      *
      * Must already exist before calling. The caller is responsible for its
      * lifecycle (including cleanup of tmp directories).
      */
     path: string;
     /**
-     * Refuse to resolve any version published after this date. Passed to
-     * Arborist (and pacote) as the `before` option. Matches npm's
-     * `min-release-age` semantics once a caller converts days → Date.
+     * Refuse to resolve any version published after this date. Passed to Arborist
+     * (and pacote) as the `before` option. Matches npm's `min-release-age`
+     * semantics once a caller converts days → Date.
      */
     before?: Date | undefined;
     /**
      * Suppress Arborist's default log output.
+     *
      * @default true
      */
     quiet?: boolean | undefined;
@@ -54,11 +51,17 @@ export interface SafeIdealTreeResult {
      * registry (sourced from Arborist's idealTree, not from a tarball).
      */
     integrity: string;
-    /** Resolved package name. */
+    /**
+     * Resolved package name.
+     */
     name: string;
-    /** Resolved package version. */
+    /**
+     * Resolved package version.
+     */
     version: string;
-    /** `package-lock.json` JSON content written by Arborist. */
+    /**
+     * `package-lock.json` JSON content written by Arborist.
+     */
     lockfile: string;
 }
 /**
@@ -66,9 +69,9 @@ export interface SafeIdealTreeResult {
  */
 export interface SafeReifyOptions extends SafeArboristOptions {
     /**
-     * When true, Arborist reifies against the existing `package-lock.json`
-     * in `path` without rewriting it. When false, Arborist may update the
-     * lockfile to match resolved dependencies.
+     * When true, Arborist reifies against the existing `package-lock.json` in
+     * `path` without rewriting it. When false, Arborist may update the lockfile
+     * to match resolved dependencies.
      *
      * Pin-mode callers set this to true so committed lockfiles are the
      * authoritative resolution.
@@ -77,58 +80,80 @@ export interface SafeReifyOptions extends SafeArboristOptions {
      */
     packageLock?: boolean | undefined;
 }
+/**
+ * Fixed Arborist options that must not be overridden by callers. Mirrors
+ * socket-cli v1.1.79's SafeArborist overrides: audit: false, fund: false,
+ * ignoreScripts: true, save: false, saveBundle: false, silent: true, progress:
+ * false.
+ */
+export declare function getBaseArboristOptions(installPath: string, options: {
+    quiet: boolean;
+}): ConstructorParameters<typeof Arborist>[0];
+/**
+ * Read the single declared dependency from a package.json. We only support one
+ * top-level dep per snapshot, which keeps the result unambiguous (no "which of
+ * N deps did we pin?").
+ */
+export declare function readSingleDependency(packageJsonPath: string): string;
+/**
+ * Read the top-level package from an Arborist idealTree's inventory. Arborist's
+ * `Inventory` extends `Map`, so iteration yields `[key, node]` pairs — use
+ * `.values()` to get nodes directly.
+ */
+export declare function readTopLevelFromIdealTree(tree: unknown, targetName: string): {
+    name: string;
+    version: string;
+    integrity: string;
+};
 /**
  * Run Arborist in `packageLockOnly` mode against a directory that already
  * contains a `package.json` with a single dependency. Resolves the graph
- * against the registry and writes `package-lock.json` into `path`, but
- * does NOT install into `node_modules`.
+ * against the registry and writes `package-lock.json` into `path`, but does NOT
+ * install into `node_modules`.
  *
- * Used by snapshot/bootstrap flows to obtain a lockfile + top-level
- * integrity without paying for a full install.
+ * Used by snapshot/bootstrap flows to obtain a lockfile + top-level integrity
+ * without paying for a full install.
  *
- * Uses `save: true` (rather than our usual `save: false`) so Arborist
- * actually writes the lockfile — without that flag, `reify()` in
- * `packageLockOnly` mode with no `add` list skips the write.
+ * Uses `save: true` (rather than our usual `save: false`) so Arborist actually
+ * writes the lockfile — without that flag, `reify()` in `packageLockOnly` mode
+ * with no `add` list skips the write.
  */
 export declare function safeIdealTree(options: SafeArboristOptions): Promise<SafeIdealTreeResult>;
 /**
- * Install into `node_modules` using Arborist's reify operation. Honors
- * the committed `package-lock.json` in `path` when `packageLock: true`.
+ * Install into `node_modules` using Arborist's reify operation. Honors the
+ * committed `package-lock.json` in `path` when `packageLock: true`.
  *
- * Does not fetch registry metadata for versions already pinned by the
- * lockfile — arborist uses the lockfile's `integrity` strings to fetch
- * tarballs by ssri. This is the strongest form of pinning pnpm/npm
- * offer.
+ * Does not fetch registry metadata for versions already pinned by the lockfile
+ * — arborist uses the lockfile's `integrity` strings to fetch tarballs by ssri.
+ * This is the strongest form of pinning pnpm/npm offer.
  */
 export declare function safeReify(options: SafeReifyOptions): Promise<void>;
 /**
- * Options for {@link writeSafeNpmrc}. Optional release-age hints are
- * echoed into the generated `.npmrc` as defense-in-depth for any
- * downstream tool that shells out to npm/pnpm in the directory.
+ * Options for {@link writeSafeNpmrc}. Optional release-age hints are echoed into
+ * the generated `.npmrc` as defense-in-depth for any downstream tool that
+ * shells out to npm/pnpm in the directory.
  */
 export interface WriteSafeNpmrcOptions {
-    /** npm `min-release-age` (days). Mutually exclusive with minReleaseMins. */
+    /**
+     * Npm `min-release-age` (days). Mutually exclusive with minReleaseMins.
+     */
     minReleaseDays?: number | undefined;
-    /** pnpm `minimumReleaseAge` (minutes). Mutually exclusive with minReleaseDays. */
+    /**
+     * Pnpm `minimumReleaseAge` (minutes). Mutually exclusive with minReleaseDays.
+     */
     minReleaseMins?: number | undefined;
 }
 /**
- * Write a hardened `.npmrc` into `path`. Used by both preview and pin
- * flows as a second layer of protection alongside the Arborist options.
+ * Write a hardened `.npmrc` into `path`. Used by both preview and pin flows as
+ * a second layer of protection alongside the Arborist options.
  *
- * Content written (always):
- *   ignore-scripts=true
- *   audit=false
- *   fund=false
- *   save=false
- *   save-bundle=false
- *   progress=false
+ * Content written (always): ignore-scripts=true audit=false fund=false
+ * save=false save-bundle=false progress=false.
  *
  * When {@link WriteSafeNpmrcOptions.minReleaseDays} is set, also writes:
- *   min-release-age=<days>
+ * min-release-age=<days>
  *
- * When {@link WriteSafeNpmrcOptions.minReleaseMins} is set, also writes
- * the pnpm-style equivalent:
- *   minimum-release-age=<minutes>
+ * When {@link WriteSafeNpmrcOptions.minReleaseMins} is set, also writes the
+ * pnpm-style equivalent: minimum-release-age=<minutes>
  */
 export declare function writeSafeNpmrc(installPath: string, options?: WriteSafeNpmrcOptions | undefined): Promise<void>;

package/dist/dlx/arborist.js

@@ -30,6 +30,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var arborist_exports = {};
 __export(arborist_exports, {
+  getBaseArboristOptions: () => getBaseArboristOptions,
+  readSingleDependency: () => readSingleDependency,
+  readTopLevelFromIdealTree: () => readTopLevelFromIdealTree,
   safeIdealTree: () => safeIdealTree,
   safeReify: () => safeReify,
   writeSafeNpmrc: () => writeSafeNpmrc
@@ -37,24 +40,13 @@ __export(arborist_exports, {
 module.exports = __toCommonJS(arborist_exports);
 var import_arborist = __toESM(require("../external/@npmcli/arborist"));
 var import_socket = require("../paths/socket");
-var import_primordials = require("../primordials");
-let _fs;
-// @__NO_SIDE_EFFECTS__
-function getFs() {
-  if (_fs === void 0) {
-    _fs = require("node:fs");
-  }
-  return _fs;
-}
-let _path;
-// @__NO_SIDE_EFFECTS__
-function getPath() {
-  if (_path === void 0) {
-    _path = require("node:path");
-  }
-  return _path;
-}
-function getBaseArboristOptions(installPath, quiet) {
+var import_array = require("../primordials/array");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_object = require("../primordials/object");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+function getBaseArboristOptions(installPath, options) {
   return {
     __proto__: null,
     path: installPath,
@@ -65,17 +57,17 @@ function getBaseArboristOptions(installPath, quiet) {
     progress: false,
     save: false,
     saveBundle: false,
-    silent: quiet
+    silent: options.quiet
   };
 }
 function readSingleDependency(packageJsonPath) {
-  const fs = /* @__PURE__ */ getFs();
+  const fs = (0, import_fs.getNodeFs)();
   const raw = fs.readFileSync(packageJsonPath, "utf8");
-  const pkg = (0, import_primordials.JSONParse)(raw);
+  const pkg = (0, import_json.JSONParse)(raw);
   const deps = pkg.dependencies ?? {};
-  const names = (0, import_primordials.ObjectKeys)(deps);
+  const names = (0, import_object.ObjectKeys)(deps);
   if (names.length !== 1) {
-    throw new import_primordials.ErrorCtor(
+    throw new import_error.ErrorCtor(
       `safeIdealTree expects exactly one top-level dependency in ${packageJsonPath}, found ${names.length}`
     );
   }
@@ -85,7 +77,7 @@ function readTopLevelFromIdealTree(tree, targetName) {
   const root = tree;
   const inventory = root?.inventory;
   if (!inventory || typeof inventory.values !== "function") {
-    throw new import_primordials.ErrorCtor("Arborist idealTree missing inventory");
+    throw new import_error.ErrorCtor("Arborist idealTree missing inventory");
   }
   for (const node of inventory.values()) {
     if (node.isProjectRoot) {
@@ -93,7 +85,7 @@ function readTopLevelFromIdealTree(tree, targetName) {
     }
     if (node.name === targetName && node.depth === 1) {
       if (!node.version || !node.integrity) {
-        throw new import_primordials.ErrorCtor(
+        throw new import_error.ErrorCtor(
           `Arborist idealTree node for ${targetName} missing version/integrity`
         );
       }
@@ -104,19 +96,19 @@ function readTopLevelFromIdealTree(tree, targetName) {
       };
     }
   }
-  throw new import_primordials.ErrorCtor(
+  throw new import_error.ErrorCtor(
     `Arborist idealTree inventory has no top-level node for ${targetName}`
   );
 }
 async function safeIdealTree(options) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
   const { before, path: installPath, quiet = true } = options;
   const targetName = readSingleDependency(
     path.join(installPath, "package.json")
   );
   const arb = new import_arborist.default({
-    ...getBaseArboristOptions(installPath, quiet),
+    ...getBaseArboristOptions(installPath, { quiet }),
     ...before !== void 0 ? { before } : {},
     packageLockOnly: true,
     save: true
@@ -133,20 +125,20 @@ async function safeIdealTree(options) {
 async function safeReify(options) {
   const { packageLock = true, path: installPath, quiet = true } = options;
   const arb = new import_arborist.default({
-    ...getBaseArboristOptions(installPath, quiet),
+    ...getBaseArboristOptions(installPath, { quiet }),
     packageLock
   });
   await arb.reify();
 }
 async function writeSafeNpmrc(installPath, options) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
   const { minReleaseDays, minReleaseMins } = {
     __proto__: null,
     ...options
   };
   if (minReleaseDays !== void 0 && minReleaseMins !== void 0) {
-    throw new import_primordials.ErrorCtor(
+    throw new import_error.ErrorCtor(
       "writeSafeNpmrc: minReleaseDays and minReleaseMins are mutually exclusive"
     );
   }
@@ -159,10 +151,10 @@ async function writeSafeNpmrc(installPath, options) {
     "progress=false"
   ];
   if (minReleaseDays !== void 0) {
-    (0, import_primordials.ArrayPrototypePush)(lines, `min-release-age=${minReleaseDays}`);
+    (0, import_array.ArrayPrototypePush)(lines, `min-release-age=${minReleaseDays}`);
   }
   if (minReleaseMins !== void 0) {
-    (0, import_primordials.ArrayPrototypePush)(lines, `minimum-release-age=${minReleaseMins}`);
+    (0, import_array.ArrayPrototypePush)(lines, `minimum-release-age=${minReleaseMins}`);
   }
   await fs.promises.writeFile(
     path.join(installPath, ".npmrc"),
@@ -172,6 +164,9 @@ async function writeSafeNpmrc(installPath, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  getBaseArboristOptions,
+  readSingleDependency,
+  readTopLevelFromIdealTree,
   safeIdealTree,
   safeReify,
   writeSafeNpmrc

package/dist/dlx/binary-cache.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @file On-disk cache metadata helpers for dlx binaries.
+ *
+ *   - `getDlxCachePath` — root of the binary cache (alias of getSocketDlxDir)
+ *   - `getBinaryCacheMetadataPath` — path to a cache entry's .dlx-metadata.json
+ *   - `isBinaryCacheValid` — TTL-based liveness check
+ *   - `writeBinaryCacheMetadata` — atomic write of cache metadata
+ *   - `cleanDlxCache` — TTL-based eviction sweep
+ *   - `listDlxCache` — enumerate cached binaries with their metadata Split out of
+ *     `dlx/binary.ts` for size hygiene.
+ */
+import { getSocketDlxDir } from '../paths/socket';
+import type { DlxMetadata } from './binary-types';
+/**
+ * Clean expired entries from the DLX cache.
+ *
+ * @example
+ *   ;```typescript
+ *   // Remove cache entries older than the default TTL
+ *   const removed = await cleanDlxCache()
+ *
+ *   // Remove entries older than 1 hour
+ *   const removed2 = await cleanDlxCache(60 * 60 * 1000)
+ *   ```
+ */
+export declare function cleanDlxCache(maxAge?: number): Promise<number>;
+/**
+ * Get metadata file path for a cached binary.
+ *
+ * @example
+ *   ;```typescript
+ *   const metaPath = getBinaryCacheMetadataPath('/tmp/dlx-cache/a1b2c3d4')
+ *   // '/tmp/dlx-cache/a1b2c3d4/.dlx-metadata.json'
+ *   ```
+ */
+export declare function getBinaryCacheMetadataPath(cacheEntryPath: string): string;
+/**
+ * Get the DLX binary cache directory path. Alias of `getSocketDlxDir` — DLX
+ * binary cache uses the same directory as dlx-package for unified DLX storage.
+ *
+ * @example
+ *   ;```typescript
+ *   const cachePath = getDlxCachePath()
+ *   ```
+ */
+export declare const getDlxCachePath: typeof getSocketDlxDir;
+/**
+ * Check if a cached binary is still valid.
+ *
+ * @example
+ *   ;```typescript
+ *   const ttl = 7 * 24 * 60 * 60 * 1000
+ *   const valid = await isBinaryCacheValid('/tmp/dlx-cache/a1b2c3d4', ttl)
+ *   if (!valid) {
+ *     // Re-download the binary
+ *   }
+ *   ```
+ */
+export declare function isBinaryCacheValid(cacheEntryPath: string, cacheTtl: number): Promise<boolean>;
+/**
+ * Get information about cached binaries.
+ *
+ * @example
+ *   ```typescript
+ *   const entries = await listDlxCache()
+ *   for (const entry of entries) {
+ *   console.log(`${entry.name}: ${entry.size} bytes`)
+ *   }
+ *   ```
+ */
+export declare function listDlxCache(): Promise<Array<{
+    age: number;
+    integrity: string;
+    name: string;
+    size: number;
+    url: string;
+}>>;
+/**
+ * Read the DlxMetadata for a cached binary. Returns `undefined` when the
+ * metadata file is missing, unreadable, or doesn't match the expected shape.
+ * Useful for callers that want to recover the integrity / size / source URL of
+ * an already-cached download without re-fetching.
+ *
+ * @example
+ *   ```typescript
+ *   const meta = await readBinaryCacheMetadata(cacheEntryDir)
+ *   if (meta) {
+ *   console.log(`Pinned integrity: ${meta.integrity}`)
+ *   }
+ *   ```
+ */
+export declare function readBinaryCacheMetadata(cacheEntryPath: string): Promise<DlxMetadata | undefined>;
+/**
+ * Write metadata for a cached binary. Uses unified schema shared with C++
+ * decompressor and CLI dlxBinary.
+ *
+ * @example
+ *   ;```typescript
+ *   await writeBinaryCacheMetadata(
+ *     '/tmp/dlx-cache/a1b2c3d4',
+ *     'a1b2c3d4',
+ *     'https://example.com/tool',
+ *     'sha512-abc123...',
+ *     15000000,
+ *   )
+ *   ```
+ */
+export declare function writeBinaryCacheMetadata(cacheEntryPath: string, cacheKey: string, url: string, integrity: string, size: number): Promise<void>;