@socketsecurity/lib 5.18.1 → 5.19.0

package/dist/dlx/integrity.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Integrity specification helpers for dlx downloads.
+ *
+ * Single supported format per flavor:
+ *   - integrity: SRI with sha512 only (what npm registry returns)
+ *   - checksum:  sha256 hex (what `shasum -a 256` produces; common for
+ *                binary release assets on GitHub)
+ *
+ * Callers may pass a {@link HashSpec} as a bare string (sniffed via
+ * format) or as an explicit `{ type, value }` object. The normalized
+ * form carried around internally is always the object.
+ */
+/**
+ * Tagged union representing an expected hash.
+ *
+ * @example
+ * // Bare SRI (sniffed as integrity):
+ * 'sha512-abc...'
+ *
+ * @example
+ * // Bare sha256 hex (sniffed as checksum):
+ * 'a1b2c3...'
+ *
+ * @example
+ * // Explicit:
+ * { type: 'integrity', value: 'sha512-abc...' }
+ * { type: 'checksum', value: 'a1b2c3...' }
+ */
+export type HashSpec = string | {
+    type: 'integrity';
+    value: string;
+} | {
+    type: 'checksum';
+    value: string;
+};
+/**
+ * Normalized internal form. Always an object.
+ */
+export interface NormalizedHash {
+    type: 'integrity' | 'checksum';
+    value: string;
+}
+/**
+ * Both hash formats for the same bytes. Returned from downloads so callers
+ * can record whichever format their config uses.
+ */
+export interface ComputedHashes {
+    /** SRI integrity: `sha512-<base64>`. Matches what the npm registry returns. */
+    integrity: string;
+    /** SHA-256 hex (64 chars). Matches `shasum -a 256`. */
+    checksum: string;
+}
+/**
+ * Normalize a {@link HashSpec} to its canonical `{ type, value }` form.
+ *
+ * - Object form is trusted (its `value` is validated for shape).
+ * - Bare string matching sha512 SRI → integrity.
+ * - Bare string of 64 hex chars → checksum.
+ * - Anything else throws TypeError.
+ *
+ * @throws TypeError if the string is not a recognized format, or if an
+ *   explicit object's value doesn't match its declared type.
+ */
+export declare function normalizeHash(spec: HashSpec): NormalizedHash;
+/**
+ * Compute both integrity (sha512 SRI) and checksum (sha256 hex) for a
+ * buffer of bytes.
+ */
+export declare function computeHashes(bytes: Buffer): ComputedHashes;
+/**
+ * Verify computed hashes against an expected {@link NormalizedHash}.
+ * Uses `crypto.timingSafeEqual` for constant-time comparison.
+ *
+ * @throws DlxHashMismatchError when the hash of the matching type
+ *   doesn't match the expected value.
+ */
+export declare function verifyHash(expected: NormalizedHash, computed: ComputedHashes): void;
+/**
+ * Thrown when an expected hash doesn't match the computed hash of the
+ * downloaded bytes. Carries both sides for diagnostics.
+ */
+export declare class DlxHashMismatchError extends Error {
+    readonly expected: NormalizedHash;
+    readonly actual: ComputedHashes;
+    constructor(expected: NormalizedHash, actual: ComputedHashes);
+}

package/dist/dlx/integrity.js

@@ -0,0 +1,112 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var integrity_exports = {};
+__export(integrity_exports, {
+  DlxHashMismatchError: () => DlxHashMismatchError,
+  computeHashes: () => computeHashes,
+  normalizeHash: () => normalizeHash,
+  verifyHash: () => verifyHash
+});
+module.exports = __toCommonJS(integrity_exports);
+var import_node_crypto = require("node:crypto");
+const INTEGRITY_PREFIX = "sha512-";
+const INTEGRITY_BODY_RE = /^[A-Za-z0-9+/=]+$/;
+const CHECKSUM_RE = /^[a-f0-9]{64}$/i;
+function isIntegrityString(s) {
+  if (!s.startsWith(INTEGRITY_PREFIX)) {
+    return false;
+  }
+  const body = s.slice(INTEGRITY_PREFIX.length);
+  return body.length > 0 && INTEGRITY_BODY_RE.test(body);
+}
+function isChecksumString(s) {
+  return CHECKSUM_RE.test(s);
+}
+function normalizeHash(spec) {
+  if (typeof spec === "object" && spec !== null) {
+    if (spec.type === "integrity") {
+      if (!isIntegrityString(spec.value)) {
+        throw new TypeError(
+          `Expected SRI integrity string "sha512-<base64>", got: ${spec.value}`
+        );
+      }
+      return { type: "integrity", value: spec.value };
+    }
+    if (spec.type === "checksum") {
+      if (!isChecksumString(spec.value)) {
+        throw new TypeError(
+          `Expected sha256 hex string (64 hex chars), got: ${spec.value}`
+        );
+      }
+      return { type: "checksum", value: spec.value };
+    }
+    throw new TypeError(
+      `Unknown hash type: ${spec.type}`
+    );
+  }
+  if (typeof spec !== "string") {
+    throw new TypeError(
+      `HashSpec must be a string or { type, value } object, got: ${typeof spec}`
+    );
+  }
+  if (isIntegrityString(spec)) {
+    return { type: "integrity", value: spec };
+  }
+  if (isChecksumString(spec)) {
+    return { type: "checksum", value: spec };
+  }
+  throw new TypeError(
+    `Unrecognized hash format. Expected SRI integrity ("sha512-<base64>") or sha256 hex (64 hex chars), got: ${spec}`
+  );
+}
+function computeHashes(bytes) {
+  const integrity = `sha512-${(0, import_node_crypto.createHash)("sha512").update(bytes).digest("base64")}`;
+  const checksum = (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
+  return { integrity, checksum };
+}
+function verifyHash(expected, computed) {
+  const actual = expected.type === "integrity" ? computed.integrity : computed.checksum;
+  const expectedBuf = Buffer.from(expected.value);
+  const actualBuf = Buffer.from(actual);
+  if (expectedBuf.length !== actualBuf.length || !(0, import_node_crypto.timingSafeEqual)(expectedBuf, actualBuf)) {
+    throw new DlxHashMismatchError(expected, computed);
+  }
+}
+class DlxHashMismatchError extends Error {
+  expected;
+  actual;
+  constructor(expected, actual) {
+    const actualValue = expected.type === "integrity" ? actual.integrity : actual.checksum;
+    super(
+      `Hash mismatch (${expected.type}): expected ${expected.value}, got ${actualValue}`
+    );
+    this.name = "DlxHashMismatchError";
+    this.expected = expected;
+    this.actual = actual;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DlxHashMismatchError,
+  computeHashes,
+  normalizeHash,
+  verifyHash
+});

package/dist/dlx/lockfile.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Package pin generation for dlx installs.
+ *
+ * `generatePackagePin` resolves an npm package against the registry
+ * using Arborist's lockfile-only mode and fetches its top-level tarball
+ * to return both hash formats plus the lockfile content — everything
+ * needed to vendor a reproducible install.
+ *
+ * The `LockfileSpec` type is also exported here for use as the
+ * `lockfile` option on `downloadPackage`. Sniff/write handling lives
+ * inline in `./package.ts` — no helper.
+ */
+import type { ComputedHashes } from './integrity';
+/**
+ * Lockfile source for the `lockfile` option on `downloadPackage`.
+ *
+ * Bare strings are sniffed: a leading `{` (after whitespace) means
+ * JSON content, anything else is treated as a filesystem path. Pass the
+ * explicit `{ type, value }` form to override sniffing.
+ *
+ * @example
+ * // Sniffed as path:
+ * './scripts/dlx/claude/package-lock.json'
+ * // Sniffed as content:
+ * '{ "lockfileVersion": 3, ... }'
+ * // Explicit:
+ * { type: 'path', value: '/abs/package-lock.json' }
+ * { type: 'content', value: '{ ... }' }
+ */
+export type LockfileSpec = string | {
+    type: 'path';
+    value: string;
+} | {
+    type: 'content';
+    value: string;
+};
+/**
+ * Default minimum release age in days applied when a caller passes
+ * neither `minReleaseDays` nor `minReleaseMins`. Pass `minReleaseDays: 0`
+ * to disable the cutoff explicitly.
+ */
+export declare const DEFAULT_MIN_RELEASE_DAYS = 7;
+/**
+ * Options for generating a vendorable pin for an npm package.
+ */
+export interface GeneratePackagePinOptions {
+    /** Package spec, e.g. `'@anthropic-ai/claude-code@2.1.92'`. */
+    package: string;
+    /**
+     * Minimum release age in days. Refuses to resolve any version (direct
+     * or transitive) published more recently than `Date.now() - N days`.
+     *
+     * Matches npm's `min-release-age` config (unit: days). Mutually
+     * exclusive with {@link minReleaseMins}. Defaults to
+     * {@link DEFAULT_MIN_RELEASE_DAYS} (7) when neither field is set.
+     * Pass `0` to disable.
+     */
+    minReleaseDays?: number | undefined;
+    /**
+     * Minimum release age in minutes. Refuses to resolve any version
+     * published more recently than `Date.now() - N minutes`.
+     *
+     * Matches pnpm's `minimumReleaseAge` config (unit: minutes). Mutually
+     * exclusive with {@link minReleaseDays}.
+     */
+    minReleaseMins?: number | undefined;
+}
+/**
+ * Result of {@link generatePackagePin}. All file data is returned as
+ * content — the caller decides whether/where to write it.
+ */
+export interface PinDetails {
+    /** Resolved package name. */
+    name: string;
+    /** Resolved package version. */
+    version: string;
+    /** Both hash formats of the top-level tarball. */
+    hash: ComputedHashes;
+    /** `package.json` JSON content, ready to write to disk. */
+    packageJson: string;
+    /** `package-lock.json` JSON content, ready to write to disk. */
+    lockfile: string;
+}
+/**
+ * Thrown when a lockfile spec is malformed (unrecognized string, missing
+ * file, invalid JSON) or drifts from its package.json.
+ */
+export declare class DlxLockfileError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    } | undefined);
+}
+/**
+ * Generate a vendorable pin for an npm package without installing it.
+ *
+ * Runs Arborist in lockfile-only mode (`packageLockOnly: true`) against a
+ * temporary directory, fetches the top-level tarball once to compute
+ * sha256 hex (since Arborist only exposes SRI from the registry), then
+ * tears the tmp directory down before returning.
+ *
+ * The result contains everything a caller needs to pin the package for
+ * future installs: the exact resolved name/version, both hash formats,
+ * and the lockfile content (ready to commit).
+ *
+ * @example
+ * ```ts
+ * const pin = await generatePackagePin({
+ *   package: '@anthropic-ai/claude-code@2.1.92',
+ * })
+ * await fs.writeFile('./claude.lock.json', pin.lockfile, 'utf8')
+ * // pin.hash.integrity → 'sha512-…'
+ * // pin.hash.checksum  → hex
+ * ```
+ */
+export declare function generatePackagePin(options: GeneratePackagePinOptions): Promise<PinDetails>;

package/dist/dlx/lockfile.js

@@ -0,0 +1,139 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var lockfile_exports = {};
+__export(lockfile_exports, {
+  DEFAULT_MIN_RELEASE_DAYS: () => DEFAULT_MIN_RELEASE_DAYS,
+  DlxLockfileError: () => DlxLockfileError,
+  generatePackagePin: () => generatePackagePin
+});
+module.exports = __toCommonJS(lockfile_exports);
+var import_node_os = require("node:os");
+var import_pacote = __toESM(require("../external/pacote"));
+var import_fs = require("../fs");
+var import_arborist = require("./arborist");
+var import_integrity = require("./integrity");
+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;
+}
+const DEFAULT_MIN_RELEASE_DAYS = 7;
+class DlxLockfileError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "DlxLockfileError";
+  }
+}
+function specName(spec) {
+  const atIdx = spec.lastIndexOf("@");
+  if (atIdx <= 0) {
+    return spec;
+  }
+  return spec.slice(0, atIdx);
+}
+function specRange(spec) {
+  const atIdx = spec.lastIndexOf("@");
+  if (atIdx <= 0) {
+    return "latest";
+  }
+  return spec.slice(atIdx + 1) || "latest";
+}
+async function generatePackagePin(options) {
+  const fs = /* @__PURE__ */ getFs();
+  const path = /* @__PURE__ */ getPath();
+  const { minReleaseDays, minReleaseMins, package: spec } = options;
+  if (typeof spec !== "string" || spec.length === 0) {
+    throw new DlxLockfileError("generatePackagePin requires a package spec");
+  }
+  if (minReleaseDays !== void 0 && minReleaseMins !== void 0) {
+    throw new DlxLockfileError(
+      "generatePackagePin: minReleaseDays and minReleaseMins are mutually exclusive"
+    );
+  }
+  const effectiveDays = minReleaseDays !== void 0 ? minReleaseDays : minReleaseMins !== void 0 ? void 0 : DEFAULT_MIN_RELEASE_DAYS;
+  const ageMs = effectiveDays !== void 0 ? effectiveDays * 864e5 : minReleaseMins !== void 0 ? minReleaseMins * 6e4 : 0;
+  const before = ageMs > 0 ? new Date(Date.now() - ageMs) : void 0;
+  const scratch = path.join(
+    (0, import_node_os.tmpdir)(),
+    `socket-lib-pin-${process.pid}-${Date.now()}`
+  );
+  await (0, import_fs.safeMkdir)(scratch, { recursive: true });
+  try {
+    const packageJson = JSON.stringify(
+      {
+        name: "socket-lib-pin",
+        version: "0.0.0",
+        private: true,
+        dependencies: { [specName(spec)]: specRange(spec) }
+      },
+      null,
+      2
+    );
+    await fs.promises.writeFile(
+      path.join(scratch, "package.json"),
+      packageJson + "\n",
+      "utf8"
+    );
+    await (0, import_arborist.writeSafeNpmrc)(scratch, {
+      minReleaseDays: effectiveDays,
+      minReleaseMins
+    });
+    const ideal = await (0, import_arborist.safeIdealTree)({ path: scratch, before });
+    const tarball = await import_pacote.default.tarball(`${ideal.name}@${ideal.version}`);
+    const hash = (0, import_integrity.computeHashes)(tarball);
+    return {
+      name: ideal.name,
+      version: ideal.version,
+      hash,
+      packageJson,
+      lockfile: ideal.lockfile
+    };
+  } finally {
+    await (0, import_fs.safeDelete)(scratch, { force: true });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_MIN_RELEASE_DAYS,
+  DlxLockfileError,
+  generatePackagePin
+});

package/dist/dlx/manifest.d.ts

@@ -1,3 +1,29 @@
+/**
+ * @fileoverview DLX manifest storage utilities.
+ * Manages persistent caching of DLX package and binary metadata with TTL support
+ * and atomic file operations.
+ *
+ * Key Functions:
+ * - getManifestEntry: Retrieve manifest entry by spec
+ * - setPackageEntry: Store npm package metadata
+ * - setBinaryEntry: Store binary download metadata
+ *
+ * Features:
+ * - TTL-based cache expiration
+ * - Atomic file operations with locking
+ * - JSON-based persistent storage
+ * - Error-resistant implementation
+ *
+ * Storage Format:
+ * - Stores in ~/.socket/_dlx/.dlx-manifest.json
+ * - Per-spec manifest entries with timestamps
+ * - Thread-safe operations using process lock utility
+ *
+ * Usage:
+ * - Update check caching
+ * - Binary metadata tracking
+ * - Rate limiting registry requests
+ */
 /**
  * Details for npm package entries.
  */
@@ -136,5 +162,4 @@ export declare class DlxManifest {
      */
     setPackageEntry(spec: string, cacheKey: string, details: PackageDetails): Promise<void>;
 }
-// Export singleton instance using default manifest location.
 export declare const dlxManifest: DlxManifest;

package/dist/dlx/manifest.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -34,14 +35,14 @@ let _path;
 // @__NO_SIDE_EFFECTS__
 function getFs() {
   if (_fs === void 0) {
-    _fs = require("fs");
+    _fs = require("node:fs");
   }
   return _fs;
 }
 // @__NO_SIDE_EFFECTS__
 function getPath() {
   if (_path === void 0) {
-    _path = require("path");
+    _path = require("node:path");
   }
   return _path;
 }
@@ -69,19 +70,19 @@ class DlxManifest {
   readManifest() {
     try {
       if (!fs.existsSync(this.manifestPath)) {
-        return /* @__PURE__ */ Object.create(null);
+        return { __proto__: null };
       }
       const rawContent = (0, import_fs.readFileUtf8Sync)(this.manifestPath);
       const content = (typeof rawContent === "string" ? rawContent : rawContent.toString("utf8")).trim();
       if (!content) {
-        return /* @__PURE__ */ Object.create(null);
+        return { __proto__: null };
       }
       return JSON.parse(content);
     } catch (error) {
       logger.warn(
         `Failed to read manifest: ${error instanceof Error ? error.message : String(error)}`
       );
-      return /* @__PURE__ */ Object.create(null);
+      return { __proto__: null };
     }
   }
   /**
@@ -212,7 +213,9 @@ class DlxManifest {
    */
   async set(name, record) {
     await import_process_lock.processLock.withLock(this.lockPath, async () => {
-      let data = /* @__PURE__ */ Object.create(null);
+      let data = {
+        __proto__: null
+      };
       try {
         if (fs.existsSync(this.manifestPath)) {
           const content2 = fs.readFileSync(this.manifestPath, "utf8");

package/dist/dlx/package.d.ts

@@ -1,5 +1,38 @@
-import type { SpawnExtra, SpawnOptions } from '../spawn';
+/**
+ * @fileoverview DLX package execution - Install and execute npm packages.
+ *
+ * This module provides functionality to install and execute npm packages
+ * in the ~/.socket/_dlx directory, similar to npx but with Socket's own cache.
+ *
+ * Uses content-addressed storage like npm's _npx:
+ * - Hash is generated from package spec (name@version)
+ * - Each unique spec gets its own directory: ~/.socket/_dlx/<hash>/
+ * - Allows caching multiple versions of the same package
+ *
+ * Concurrency protection:
+ * - Uses process-lock to prevent concurrent installation corruption
+ * - Lock file created at ~/.socket/_dlx/<hash>/concurrency.lock
+ * - Uses npm npx's concurrency.lock naming convention (5s stale, 2s touching)
+ * - Prevents multiple processes from corrupting the same package installation
+ *
+ * Version range handling:
+ * - Exact versions (1.0.0) use cache if available
+ * - Range versions (^1.0.0, ~1.0.0) auto-force to get latest within range
+ * - User can override with explicit force: false
+ *
+ * Key difference from dlx-binary.ts:
+ * - dlx-binary.ts: Downloads standalone binaries from URLs
+ * - dlx-package.ts: Installs npm packages from registries
+ *
+ * Implementation:
+ * - Uses Arborist for package installation (like npx, no npm CLI required)
+ * - Split into downloadPackage() and executePackage() for flexibility
+ * - dlxPackage() combines both for convenience
+ */
 import { spawn } from '../spawn';
+import type { HashSpec } from './integrity';
+import type { LockfileSpec } from './lockfile';
+import type { SpawnExtra, SpawnOptions } from '../spawn';
 export interface DownloadPackageResult {
     /** Path to the installed package directory. */
     packageDir: string;
@@ -8,7 +41,29 @@ export interface DownloadPackageResult {
     /** Whether the package was newly installed. */
     installed: boolean;
 }
-export interface DlxPackageOptions {
+/**
+ * Shared install-pinning options used by both {@link DlxPackageOptions}
+ * and the lower-level {@link ensurePackageInstalled}.
+ */
+export interface EnsurePackageInstallOptions {
+    /**
+     * Expected hash of the top-level package tarball. Accepts either:
+     * - A bare sha512 SRI string (sniffed as integrity).
+     * - A bare sha256 hex string (sniffed as checksum).
+     * - An explicit `{ type: 'integrity' | 'checksum', value }` object.
+     */
+    hash?: HashSpec | undefined;
+    /**
+     * Vendored `package-lock.json` to drive a reproducible install. Accepts
+     * a filesystem path (sniffed) or raw JSON content (sniffed via leading
+     * `{`), or an explicit `{ type: 'path' | 'content', value }` object.
+     *
+     * When provided, the lockfile is written into the install dir before
+     * Arborist runs and a hardened `.npmrc` is placed alongside it.
+     */
+    lockfile?: LockfileSpec | undefined;
+}
+export interface DlxPackageOptions extends EnsurePackageInstallOptions {
     /**
      * Package to install (e.g., '@cyclonedx/cdxgen@10.0.0').
      * Aligns with npx --package flag.
@@ -114,7 +169,7 @@ export declare function downloadPackage(options: DlxPackageOptions): Promise<Dow
  * console.log(`Installed: ${installed}, dir: ${packageDir}`)
  * ```
  */
-export declare function ensurePackageInstalled(packageName: string, packageSpec: string, force: boolean): Promise<{
+export declare function ensurePackageInstalled(packageName: string, packageSpec: string, force: boolean, install?: EnsurePackageInstallOptions | undefined): Promise<{
     installed: boolean;
     packageDir: string;
 }>;