@socketsecurity/lib 5.5.3 → 5.7.0

package/CHANGELOG.md

@@ -5,6 +5,100 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.7.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.7.0) - 2026-02-12
+
+### Added
+
+- **env**: Added `isInEnv()` helper function to check if an environment variable key exists, regardless of its value
+  - Returns `true` even for empty strings, `"false"`, `"0"`, etc.
+  - Follows same override resolution order as `getEnvValue()` (isolated overrides → shared overrides → process.env)
+  - Useful for detecting presence of environment variables independent of their value
+
+- **dlx**: Added new exported helper functions
+  - `downloadBinaryFile()` - Downloads a binary file from a URL to the dlx cache directory
+  - `ensurePackageInstalled()` - Ensures an npm package is installed and cached via Arborist
+  - `getBinaryCacheMetadataPath()` - Gets the file path to dlx binary cache metadata (`.dlx-metadata.json`)
+  - `isBinaryCacheValid()` - Checks if a cached dlx binary is still valid based on TTL and timestamp
+  - `makePackageBinsExecutable()` - Makes npm package binaries executable on Unix systems
+  - `parsePackageSpec()` - Parses npm package spec strings (e.g., `pkg@1.0.0`) into name and version
+  - `resolveBinaryPath()` - Resolves the absolute path to a binary within an installed package
+  - `writeBinaryCacheMetadata()` - Writes dlx binary cache metadata with integrity, size, and source info
+
+- **releases**: Added `createAssetMatcher()` utility function for GitHub release asset pattern matching
+  - Creates matcher functions that test strings against glob patterns, prefix/suffix, or RegExp
+  - Used for dynamic asset discovery in GitHub releases (e.g., matching platform-specific binaries)
+
+### Changed
+
+- **env**: Updated `getCI()` to use `isInEnv()` for more accurate CI detection
+  - Now returns `true` whenever the `CI` key exists in the environment, not just when truthy
+  - Matches standard CI detection behavior where the presence of the key (not its value) indicates a CI environment
+
+### Fixed
+
+- **github**: Fixed JSON parsing crash vulnerability by adding try-catch around `JSON.parse()` in GitHub API responses
+  - Prevents crashes on malformed, incomplete, or binary responses
+  - Error messages now include the response URL for better debugging
+
+- **dlx/binary**: Fixed clock skew vulnerabilities in cache validation
+  - Cache entries with future timestamps (clock skew) are now treated as expired
+  - Metadata writes now use atomic write-then-rename pattern to prevent corruption
+  - Added TOCTOU race protection by re-checking binary existence after metadata read
+
+- **dlx/cache cleanup**: Fixed handling of future timestamps during cache cleanup
+  - Entries with future timestamps (due to clock skew) are now properly treated as expired
+
+- **dlx/package**: Fixed scoped package parsing bug where `@scope/package` was incorrectly parsed
+  - Changed condition from `startsWith('@')` to `atIndex === 0` for more precise detection
+  - Fixes installation failures for scoped packages like `@socketregistry/lib`
+
+- **cache-with-ttl**: Added clock skew detection to TTL cache
+  - Far-future `expiresAt` values (>2x TTL) are now treated as expired
+  - Protects against cache poisoning from clock skew
+
+- **packages/specs**: Fixed unconditional `.git` truncation in Git URL parsing
+  - Now only removes `.git` suffix when URL actually ends with `.git`
+  - Prevents incorrect truncation of URLs containing `.git` in the middle
+
+- **releases/github**: Fixed TOCTOU race condition in binary download verification
+  - Re-checks binary existence after reading version file
+  - Ensures binary is re-downloaded if missing despite version file presence
+
+- **provenance**: Fixed incorrect package name in provenance workflow
+  - Changed from `@socketregistry/lib` to `@socketsecurity/lib`
+
+
+## [5.6.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.6.0) - 2026-02-08
+
+### Added
+
+- **http-request**: Added automatic default headers for JSON and text requests
+  - `httpJson()` now automatically sets `Accept: application/json` header
+  - `httpJson()` automatically sets `Content-Type: application/json` when body is present
+  - `httpText()` now automatically sets `Accept: text/plain` header
+  - `httpText()` automatically sets `Content-Type: text/plain` when body is present
+  - User-provided headers always override defaults
+  - Simplifies API usage - no need to manually set common headers
+
+### Changed
+
+- **http-request**: Renamed HTTP helper functions to support all HTTP methods (BREAKING CHANGE)
+  - `httpGetJson()` → `httpJson()` - Now supports GET, POST, PUT, DELETE, PATCH, etc.
+  - `httpGetText()` → `httpText()` - Now supports all HTTP methods via `method` option
+  - Functions now accept `method` parameter in options (defaults to 'GET')
+  - More flexible API that matches modern fetch-style conventions
+  - **Migration**: Replace `httpGetJson()` calls with `httpJson()` and `httpGetText()` with `httpText()`
+
+### Fixed
+
+- **http-request**: Fixed Content-Type header incorrectly sent with empty string body
+  - Empty string body (`""`) no longer triggers Content-Type header
+  - Changed condition from `if (body !== undefined)` to `if (body)` for semantic correctness
+  - Empty string represents "no content" and should not declare a Content-Type
+  - Affects `httpJson()` and `httpText()` functions
+  - Fixes potential API compatibility issues with servers expecting no Content-Type for empty bodies
+  - Added comprehensive test coverage for empty string edge case
+
 ## [5.5.3](https://github.com/SocketDev/socket-lib/releases/tag/v5.5.3) - 2026-01-20
 
 ### Fixed
@@ -780,7 +874,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **DLX binary metadata structure**: Updated `writeMetadata()` to use unified schema with additional fields
+- **DLX binary metadata structure**: Updated `writeBinaryCacheMetadata()` to use unified schema with additional fields
   - Now includes `cache_key` (first 16 chars of SHA-512 hash)
   - Added `size` field for cached binary size
   - Added `checksum_algorithm` field (currently "sha256")

package/dist/cache-with-ttl.js

@@ -54,7 +54,11 @@ function createTtlCache(options) {
     return `${opts.prefix}:${key}`;
   }
   function isExpired(entry) {
-    return Date.now() > entry.expiresAt;
+    const now = Date.now();
+    if (entry.expiresAt > now + ttl * 2) {
+      return true;
+    }
+    return now > entry.expiresAt;
   }
   function createMatcher(pattern) {
     const fullPattern = buildKey(pattern);

package/dist/dlx/binary.d.ts

@@ -10,9 +10,9 @@ export interface DlxBinaryOptions {
      */
     name?: string | undefined;
     /**
-     * Expected checksum (sha256) for verification.
+     * Expected SRI integrity hash (sha512-<base64>) for verification.
      */
-    checksum?: string | undefined;
+    integrity?: string | undefined;
     /**
      * Cache TTL in milliseconds (default: 7 days).
      */
@@ -47,65 +47,40 @@ export interface DlxBinaryResult {
 }
 /**
  * Metadata structure for cached binaries (.dlx-metadata.json).
- * Unified schema shared across TypeScript (dlxBinary) and C++ (socket_macho_decompress).
+ * Unified schema shared across TypeScript (dlxBinary) and C++ stub extractor.
  *
- * Core Fields (present in all implementations):
+ * Fields:
  * - version: Schema version (currently "1.0.0")
  * - cache_key: First 16 chars of SHA-512 hash (matches directory name)
  * - timestamp: Unix timestamp in milliseconds
- * - checksum: Full hash of cached binary (SHA-512 for C++, SHA-256 for TypeScript)
- * - checksum_algorithm: "sha512" or "sha256"
- * - platform: "darwin" | "linux" | "win32"
- * - arch: "x64" | "arm64"
+ * - integrity: SRI hash (sha512-<base64>, aligned with npm)
  * - size: Size of cached binary in bytes
  * - source: Origin information
- *   - type: "download" (from URL) or "decompression" (from embedded binary)
+ *   - type: "download" | "extract" | "package"
  *   - url: Download URL (if type is "download")
- *   - path: Source binary path (if type is "decompression")
+ *   - path: Source binary path (if type is "extract")
+ *   - spec: Package spec (if type is "package")
+ * - update_check: Update checking metadata (optional)
+ *   - last_check: Timestamp of last update check
+ *   - last_notification: Timestamp of last user notification
+ *   - latest_known: Latest known version string
  *
- * Extra Fields (implementation-specific):
- * - For C++ decompression:
- *   - compressed_size: Size of compressed data in bytes
- *   - compression_algorithm: Brotli level (numeric)
- *   - compression_ratio: original_size / compressed_size
- *
- * Example (TypeScript download):
+ * Example:
  * ```json
  * {
  *   "version": "1.0.0",
  *   "cache_key": "a1b2c3d4e5f67890",
  *   "timestamp": 1730332800000,
- *   "checksum": "sha256-abc123...",
- *   "checksum_algorithm": "sha256",
- *   "platform": "darwin",
- *   "arch": "arm64",
+ *   "integrity": "sha512-abc123base64...",
  *   "size": 15000000,
  *   "source": {
  *     "type": "download",
  *     "url": "https://example.com/binary"
- *   }
- * }
- * ```
- *
- * Example (C++ decompression):
- * ```json
- * {
- *   "version": "1.0.0",
- *   "cache_key": "0123456789abcdef",
- *   "timestamp": 1730332800000,
- *   "checksum": "sha512-def456...",
- *   "checksum_algorithm": "sha512",
- *   "platform": "darwin",
- *   "arch": "arm64",
- *   "size": 13000000,
- *   "source": {
- *     "type": "decompression",
- *     "path": "/usr/local/bin/socket"
  *   },
- *   "extra": {
- *     "compressed_size": 1700000,
- *     "compression_algorithm": 3,
- *     "compression_ratio": 7.647
+ *   "update_check": {
+ *     "last_check": 1730332800000,
+ *     "last_notification": 1730246400000,
+ *     "latest_known": "2.1.0"
  *   }
  * }
  * ```
@@ -116,17 +91,19 @@ export interface DlxMetadata {
     version: string;
     cache_key: string;
     timestamp: number;
-    checksum: string;
-    checksum_algorithm: string;
-    platform: string;
-    arch: string;
+    integrity: string;
     size: number;
     source?: {
-        type: 'download' | 'decompression';
+        type: 'download' | 'extract' | 'package';
         url?: string;
         path?: string;
+        spec?: string;
+    };
+    update_check?: {
+        last_check: number;
+        last_notification: number;
+        latest_known: string;
     };
-    extra?: Record<string, unknown>;
 }
 /**
  * Clean expired entries from the DLX cache.
@@ -146,6 +123,12 @@ export declare function downloadBinary(options: Omit<DlxBinaryOptions, 'spawnOpt
     binaryPath: string;
     downloaded: boolean;
 }>;
+/**
+ * Download a file from a URL with integrity checking and concurrent download protection.
+ * Uses processLock to prevent multiple processes from downloading the same binary simultaneously.
+ * Internal helper function for downloading binary files.
+ */
+export declare function downloadBinaryFile(url: string, destPath: string, integrity?: string | undefined): Promise<string>;
 /**
  * Execute a cached binary without re-downloading.
  * Similar to executePackage from dlx-package.
@@ -164,15 +147,27 @@ export declare function executeBinary(binaryPath: string, args: readonly string[
  * Uses same directory as dlx-package for unified DLX storage.
  */
 export declare function getDlxCachePath(): string;
+/**
+ * Get metadata file path for a cached binary.
+ */
+export declare function getBinaryCacheMetadataPath(cacheEntryPath: string): string;
+/**
+ * Check if a cached binary is still valid.
+ */
+export declare function isBinaryCacheValid(cacheEntryPath: string, cacheTtl: number): Promise<boolean>;
 /**
  * Get information about cached binaries.
  */
 export declare function listDlxCache(): Promise<Array<{
     age: number;
-    arch: string;
-    checksum: string;
+    integrity: string;
     name: string;
-    platform: string;
     size: number;
     url: string;
 }>>;
+/**
+ * Write metadata for a cached binary.
+ * Uses unified schema shared with C++ decompressor and CLI dlxBinary.
+ * Schema documentation: See DlxMetadata interface in this file (exported).
+ */
+export declare function writeBinaryCacheMetadata(cacheEntryPath: string, cacheKey: string, url: string, integrity: string, size: number): Promise<void>;

package/dist/dlx/binary.js

@@ -22,15 +22,18 @@ __export(binary_exports, {
   cleanDlxCache: () => cleanDlxCache,
   dlxBinary: () => dlxBinary,
   downloadBinary: () => downloadBinary,
+  downloadBinaryFile: () => downloadBinaryFile,
   executeBinary: () => executeBinary,
+  getBinaryCacheMetadataPath: () => getBinaryCacheMetadataPath,
   getDlxCachePath: () => getDlxCachePath,
-  listDlxCache: () => listDlxCache
+  isBinaryCacheValid: () => isBinaryCacheValid,
+  listDlxCache: () => listDlxCache,
+  writeBinaryCacheMetadata: () => writeBinaryCacheMetadata
 });
 module.exports = __toCommonJS(binary_exports);
 var import_platform = require("../constants/platform");
 var import_time = require("../constants/time");
 var import_cache = require("./cache");
-var import_manifest = require("./manifest");
 var import_http_request = require("../http-request");
 var import_fs = require("../fs");
 var import_objects = require("../objects");
@@ -62,115 +65,6 @@ function getPath() {
   }
   return _path;
 }
-function getMetadataPath(cacheEntryPath) {
-  return (/* @__PURE__ */ getPath()).join(cacheEntryPath, ".dlx-metadata.json");
-}
-async function isCacheValid(cacheEntryPath, cacheTtl) {
-  const fs = /* @__PURE__ */ getFs();
-  try {
-    const metaPath = getMetadataPath(cacheEntryPath);
-    if (!fs.existsSync(metaPath)) {
-      return false;
-    }
-    const metadata = await (0, import_fs.readJson)(metaPath, { throws: false });
-    if (!(0, import_objects.isObjectObject)(metadata)) {
-      return false;
-    }
-    const now = Date.now();
-    const timestamp = metadata["timestamp"];
-    if (typeof timestamp !== "number" || timestamp <= 0) {
-      return false;
-    }
-    const age = now - timestamp;
-    return age < cacheTtl;
-  } catch {
-    return false;
-  }
-}
-async function downloadBinaryFile(url, destPath, checksum) {
-  const crypto = /* @__PURE__ */ getCrypto();
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
-  const cacheEntryDir = path.dirname(destPath);
-  const lockPath = path.join(cacheEntryDir, "concurrency.lock");
-  return await import_process_lock.processLock.withLock(
-    lockPath,
-    async () => {
-      if (fs.existsSync(destPath)) {
-        const stats = await fs.promises.stat(destPath);
-        if (stats.size > 0) {
-          const fileBuffer2 = await fs.promises.readFile(destPath);
-          const hasher2 = crypto.createHash("sha256");
-          hasher2.update(fileBuffer2);
-          return hasher2.digest("hex");
-        }
-      }
-      try {
-        await (0, import_http_request.httpDownload)(url, destPath);
-      } catch (e) {
-        throw new Error(
-          `Failed to download binary from ${url}
-Destination: ${destPath}
-Check your internet connection or verify the URL is accessible.`,
-          { cause: e }
-        );
-      }
-      const fileBuffer = await fs.promises.readFile(destPath);
-      const hasher = crypto.createHash("sha256");
-      hasher.update(fileBuffer);
-      const actualChecksum = hasher.digest("hex");
-      if (checksum && actualChecksum !== checksum) {
-        await (0, import_fs.safeDelete)(destPath);
-        throw new Error(
-          `Checksum mismatch: expected ${checksum}, got ${actualChecksum}`
-        );
-      }
-      if (!import_platform.WIN32) {
-        await fs.promises.chmod(destPath, 493);
-      }
-      return actualChecksum;
-    },
-    {
-      // Align with npm npx locking strategy.
-      staleMs: 5e3,
-      touchIntervalMs: 2e3
-    }
-  );
-}
-async function writeMetadata(cacheEntryPath, cacheKey, url, binaryName, checksum, size) {
-  const metaPath = getMetadataPath(cacheEntryPath);
-  const metadata = {
-    version: "1.0.0",
-    cache_key: cacheKey,
-    timestamp: Date.now(),
-    checksum,
-    checksum_algorithm: "sha256",
-    platform: (0, import_platform.getPlatform)(),
-    arch: (0, import_platform.getArch)(),
-    size,
-    source: {
-      type: "download",
-      url
-    }
-  };
-  const fs = /* @__PURE__ */ getFs();
-  await fs.promises.writeFile(metaPath, JSON.stringify(metadata, null, 2));
-  try {
-    const spec = `${url}:${binaryName}`;
-    await import_manifest.dlxManifest.setBinaryEntry(spec, cacheKey, {
-      checksum,
-      checksum_algorithm: metadata.checksum_algorithm,
-      platform: metadata.platform,
-      arch: metadata.arch,
-      size,
-      source: {
-        type: "download",
-        url
-      }
-    });
-  } catch {
-  }
-}
 async function cleanDlxCache(maxAge = import_time.DLX_BINARY_CACHE_TTL) {
   const cacheDir = getDlxCachePath();
   const fs = /* @__PURE__ */ getFs();
@@ -183,7 +77,7 @@ async function cleanDlxCache(maxAge = import_time.DLX_BINARY_CACHE_TTL) {
   const entries = await fs.promises.readdir(cacheDir);
   for (const entry of entries) {
     const entryPath = path.join(cacheDir, entry);
-    const metaPath = getMetadataPath(entryPath);
+    const metaPath = getBinaryCacheMetadataPath(entryPath);
     try {
       if (!await (0, import_fs.isDir)(entryPath)) {
         continue;
@@ -194,7 +88,7 @@ async function cleanDlxCache(maxAge = import_time.DLX_BINARY_CACHE_TTL) {
       }
       const timestamp = metadata["timestamp"];
       const age = typeof timestamp === "number" && timestamp > 0 ? now - timestamp : Number.POSITIVE_INFINITY;
-      if (age > maxAge) {
+      if (age < 0 || age > maxAge) {
         await (0, import_fs.safeDelete)(entryPath, { force: true, recursive: true });
         cleaned += 1;
       }
@@ -214,8 +108,8 @@ async function cleanDlxCache(maxAge = import_time.DLX_BINARY_CACHE_TTL) {
 async function dlxBinary(args, options, spawnExtra) {
   const {
     cacheTtl = import_time.DLX_BINARY_CACHE_TTL,
-    checksum,
     force: userForce = false,
+    integrity,
     name,
     spawnOptions,
     url,
@@ -231,13 +125,16 @@ async function dlxBinary(args, options, spawnExtra) {
   const cacheEntryDir = path.join(cacheDir, cacheKey);
   const binaryPath = (0, import_normalize.normalizePath)(path.join(cacheEntryDir, binaryName));
   let downloaded = false;
-  let computedChecksum = checksum;
-  if (!force && fs.existsSync(cacheEntryDir) && await isCacheValid(cacheEntryDir, cacheTtl)) {
+  let computedIntegrity = integrity;
+  if (!force && fs.existsSync(cacheEntryDir) && await isBinaryCacheValid(cacheEntryDir, cacheTtl)) {
     try {
-      const metaPath = getMetadataPath(cacheEntryDir);
+      const metaPath = getBinaryCacheMetadataPath(cacheEntryDir);
       const metadata = await (0, import_fs.readJson)(metaPath, { throws: false });
-      if (metadata && typeof metadata === "object" && !Array.isArray(metadata) && typeof metadata["checksum"] === "string") {
-        computedChecksum = metadata["checksum"];
+      if (metadata && typeof metadata === "object" && !Array.isArray(metadata) && typeof metadata["integrity"] === "string") {
+        computedIntegrity = metadata["integrity"];
+        if (!fs.existsSync(binaryPath)) {
+          downloaded = true;
+        }
       } else {
         downloaded = true;
       }
@@ -271,14 +168,13 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
         { cause: e }
       );
     }
-    computedChecksum = await downloadBinaryFile(url, binaryPath, checksum);
+    computedIntegrity = await downloadBinaryFile(url, binaryPath, integrity);
     const stats = await fs.promises.stat(binaryPath);
-    await writeMetadata(
+    await writeBinaryCacheMetadata(
       cacheEntryDir,
       cacheKey,
       url,
-      binaryName,
-      computedChecksum || "",
+      computedIntegrity || "",
       stats.size
     );
   }
@@ -301,8 +197,8 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
 async function downloadBinary(options) {
   const {
     cacheTtl = import_time.DLX_BINARY_CACHE_TTL,
-    checksum,
     force = false,
+    integrity,
     name,
     url
   } = { __proto__: null, ...options };
@@ -315,7 +211,7 @@ async function downloadBinary(options) {
   const cacheEntryDir = path.join(cacheDir, cacheKey);
   const binaryPath = (0, import_normalize.normalizePath)(path.join(cacheEntryDir, binaryName));
   let downloaded = false;
-  if (!force && fs.existsSync(cacheEntryDir) && await isCacheValid(cacheEntryDir, cacheTtl)) {
+  if (!force && fs.existsSync(cacheEntryDir) && await isBinaryCacheValid(cacheEntryDir, cacheTtl)) {
     downloaded = false;
   } else {
     try {
@@ -341,14 +237,17 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
         { cause: e }
       );
     }
-    const computedChecksum = await downloadBinaryFile(url, binaryPath, checksum);
+    const computedIntegrity = await downloadBinaryFile(
+      url,
+      binaryPath,
+      integrity
+    );
     const stats = await fs.promises.stat(binaryPath);
-    await writeMetadata(
+    await writeBinaryCacheMetadata(
       cacheEntryDir,
       cacheKey,
       url,
-      binaryName,
-      computedChecksum || "",
+      computedIntegrity || "",
       stats.size
     );
     downloaded = true;
@@ -358,6 +257,54 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
     downloaded
   };
 }
+async function downloadBinaryFile(url, destPath, integrity) {
+  const crypto = /* @__PURE__ */ getCrypto();
+  const fs = /* @__PURE__ */ getFs();
+  const path = /* @__PURE__ */ getPath();
+  const cacheEntryDir = path.dirname(destPath);
+  const lockPath = path.join(cacheEntryDir, "concurrency.lock");
+  return await import_process_lock.processLock.withLock(
+    lockPath,
+    async () => {
+      if (fs.existsSync(destPath)) {
+        const stats = await fs.promises.stat(destPath);
+        if (stats.size > 0) {
+          const fileBuffer2 = await fs.promises.readFile(destPath);
+          const hash2 = crypto.createHash("sha512").update(fileBuffer2).digest("base64");
+          return `sha512-${hash2}`;
+        }
+      }
+      try {
+        await (0, import_http_request.httpDownload)(url, destPath);
+      } catch (e) {
+        throw new Error(
+          `Failed to download binary from ${url}
+Destination: ${destPath}
+Check your internet connection or verify the URL is accessible.`,
+          { cause: e }
+        );
+      }
+      const fileBuffer = await fs.promises.readFile(destPath);
+      const hash = crypto.createHash("sha512").update(fileBuffer).digest("base64");
+      const actualIntegrity = `sha512-${hash}`;
+      if (integrity && actualIntegrity !== integrity) {
+        await (0, import_fs.safeDelete)(destPath);
+        throw new Error(
+          `Integrity mismatch: expected ${integrity}, got ${actualIntegrity}`
+        );
+      }
+      if (!import_platform.WIN32) {
+        await fs.promises.chmod(destPath, 493);
+      }
+      return actualIntegrity;
+    },
+    {
+      // Align with npm npx locking strategy.
+      staleMs: 5e3,
+      touchIntervalMs: 2e3
+    }
+  );
+}
 function executeBinary(binaryPath, args, spawnOptions, spawnExtra) {
   const needsShell = import_platform.WIN32 && /\.(?:bat|cmd|ps1)$/i.test(binaryPath);
   const path = /* @__PURE__ */ getPath();
@@ -375,6 +322,34 @@ function executeBinary(binaryPath, args, spawnOptions, spawnExtra) {
 function getDlxCachePath() {
   return (0, import_socket.getSocketDlxDir)();
 }
+function getBinaryCacheMetadataPath(cacheEntryPath) {
+  return (/* @__PURE__ */ getPath()).join(cacheEntryPath, ".dlx-metadata.json");
+}
+async function isBinaryCacheValid(cacheEntryPath, cacheTtl) {
+  const fs = /* @__PURE__ */ getFs();
+  try {
+    const metaPath = getBinaryCacheMetadataPath(cacheEntryPath);
+    if (!fs.existsSync(metaPath)) {
+      return false;
+    }
+    const metadata = await (0, import_fs.readJson)(metaPath, { throws: false });
+    if (!(0, import_objects.isObjectObject)(metadata)) {
+      return false;
+    }
+    const now = Date.now();
+    const timestamp = metadata["timestamp"];
+    if (typeof timestamp !== "number" || timestamp <= 0) {
+      return false;
+    }
+    const age = now - timestamp;
+    if (age < 0) {
+      return false;
+    }
+    return age < cacheTtl;
+  } catch {
+    return false;
+  }
+}
 async function listDlxCache() {
   const cacheDir = getDlxCachePath();
   const fs = /* @__PURE__ */ getFs();
@@ -391,7 +366,7 @@ async function listDlxCache() {
       if (!await (0, import_fs.isDir)(entryPath)) {
         continue;
       }
-      const metaPath = getMetadataPath(entryPath);
+      const metaPath = getBinaryCacheMetadataPath(entryPath);
       const metadata = await (0, import_fs.readJson)(metaPath, { throws: false });
       if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
         continue;
@@ -406,10 +381,8 @@ async function listDlxCache() {
         const binaryStats = await fs.promises.stat(binaryPath);
         results.push({
           age: now - (metaObj["timestamp"] || 0),
-          arch: metaObj["arch"] || "unknown",
-          checksum: metaObj["checksum"] || "",
+          integrity: metaObj["integrity"] || "",
           name: binaryFile,
-          platform: metaObj["platform"] || "unknown",
           size: binaryStats.size,
           url
         });
@@ -419,12 +392,34 @@ async function listDlxCache() {
   }
   return results;
 }
+async function writeBinaryCacheMetadata(cacheEntryPath, cacheKey, url, integrity, size) {
+  const metaPath = getBinaryCacheMetadataPath(cacheEntryPath);
+  const metadata = {
+    version: "1.0.0",
+    cache_key: cacheKey,
+    timestamp: Date.now(),
+    integrity,
+    size,
+    source: {
+      type: "download",
+      url
+    }
+  };
+  const fs = /* @__PURE__ */ getFs();
+  const tmpPath = `${metaPath}.tmp.${process.pid}`;
+  await fs.promises.writeFile(tmpPath, JSON.stringify(metadata, null, 2));
+  await fs.promises.rename(tmpPath, metaPath);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cleanDlxCache,
   dlxBinary,
   downloadBinary,
+  downloadBinaryFile,
   executeBinary,
+  getBinaryCacheMetadataPath,
   getDlxCachePath,
-  listDlxCache
+  isBinaryCacheValid,
+  listDlxCache,
+  writeBinaryCacheMetadata
 });