@socketsecurity/lib 6.0.8 → 6.0.9

package/dist/fs/copy.js

@@ -0,0 +1,89 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_object = require('../primordials/object.js');
+const require_paths__internal = require('../paths/_internal.js');
+const require_node_fs = require('../node/fs.js');
+const require_node_path = require('../node/path.js');
+const require_fs_safe = require('./safe.js');
+const require_fs_unique = require('./unique.js');
+
+//#region src/fs/copy.ts
+/**
+* @file Recursive copy for a file or directory tree, with three destination
+*   modes (see {@link CopyMode}). Plain `fs.cp` (even with `force`) overwrites
+*   files present in the source but never deletes destination files absent from
+*   it, so copying onto an existing target leaves stale leftovers behind. The
+*   `'pave'` mode makes the destination an exact copy of the source by staging
+*   a fresh tree in a sibling temp directory and swapping it in with a single
+*   rename — atomic, with no stale survivors.
+*/
+/**
+* Named values for {@link CopyMode}. A frozen object rather than a TypeScript
+* `enum` so the declaration is erasable (enums emit runtime helper code).
+*/
+const CopyMode = require_primordials_object.ObjectFreeze({
+	Fill: "fill",
+	Overlay: "overlay",
+	Pave: "pave"
+});
+/**
+* Recursively copy a file or directory tree from `from` to `to`.
+*
+* Works for both files and directories. The `mode` option chooses how an
+* existing destination is treated — overlay (default), pave, or fill; see
+* {@link CopyMode}.
+*
+* @example
+*   ;```ts
+*   // Overlay (default) — overwrite collisions, keep files already in dest:
+*   await copy('./src', './dest')
+*
+*   // Pave — dest ends up identical to src, no stale survivors:
+*   await copy('./vendor/upstream', './deps/upstream', { mode: CopyMode.Pave })
+*
+*   // Fill — add only what's missing, never overwrite an existing file:
+*   await copy('./defaults', './config', { mode: CopyMode.Fill })
+*   ```
+*
+* @param from - Source file or directory to copy.
+* @param to - Destination path.
+* @param options - Copy options (mode, filter, dereference, abort signal).
+*/
+async function copy(from, to, options) {
+	const fs = require_node_fs.getNodeFs();
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const { mode } = opts;
+	const fromStr = require_paths__internal.pathLikeToString(from);
+	const toStr = require_paths__internal.pathLikeToString(to);
+	const cpOptions = {
+		__proto__: null,
+		dereference: opts.dereference === true,
+		force: mode !== CopyMode.Fill,
+		recursive: true,
+		...opts.filter ? { filter: opts.filter } : {}
+	};
+	if (mode !== CopyMode.Pave) {
+		await fs.promises.cp(fromStr, toStr, cpOptions);
+		return;
+	}
+	const path = require_node_path.getNodePath();
+	const tmp = require_fs_unique.uniqueSync(`${toStr}.tmp`);
+	try {
+		await fs.promises.cp(fromStr, tmp, cpOptions);
+		await require_fs_safe.safeMkdir(path.dirname(toStr));
+		await require_fs_safe.safeDelete(toStr, { signal: opts.signal });
+		await fs.promises.rename(tmp, toStr);
+	} catch (e) {
+		/* c8 ignore start - best-effort cleanup of the staged copy on failure */
+		await require_fs_safe.safeDelete(tmp, { signal: opts.signal });
+		throw e;
+	}
+}
+
+//#endregion
+exports.CopyMode = CopyMode;
+exports.copy = copy;

package/dist/fs/safe.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_arrays_predicates = require('../arrays/predicates.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_arrays_predicates = require('../arrays/predicates.js');
 const require_paths__internal = require('../paths/_internal.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_node_fs = require('../node/fs.js');

package/dist/git/_internal.js

@@ -3,8 +3,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_buffer = require('../primordials/buffer.js');
 const require_primordials_object = require('../primordials/object.js');
-const require_primordials_map_set = require('../primordials/map-set.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_primordials_map_set = require('../primordials/map-set.js');
 const require_paths_normalize = require('../paths/normalize.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_node_path = require('../node/path.js');
@@ -13,9 +13,9 @@ const require_primordials_json = require('../primordials/json.js');
 const require_bin_which = require('../bin/which.js');
 const require_ansi_strip = require('../ansi/strip.js');
 const require_process_spawn_child = require('../process/spawn/child.js');
+const require_git_repo = require('./repo.js');
 const require_debug_output = require('../debug/output.js');
 const require_globs_matcher = require('../globs/matcher.js');
-const require_git_repo = require('./repo.js');
 
 //#region src/git/_internal.ts
 /**

package/dist/github/refs.js

@@ -1,7 +1,12 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_github_refs_graphql = require('./refs-graphql.js');
+const require_github_refs_rest = require('./refs-rest.js');
 const require_github_refs_cache = require('./refs-cache.js');
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
 
 //#region src/github/refs.ts
 /**
@@ -89,25 +94,15 @@ async function resolveRefToSha(owner, repo, ref, options) {
 		...options
 	};
 	const cacheKey = `${owner}/${repo}@${ref}`;
-	if (process.env["DISABLE_GITHUB_CACHE"]) return await fetchRefSha$1(owner, repo, ref, opts);
-	return await getGithubCache$1().getOrFetch(cacheKey, async () => {
-		return await fetchRefSha$1(owner, repo, ref, opts);
+	if (node_process.default.env["DISABLE_GITHUB_CACHE"]) return await require_github_refs_rest.fetchRefSha(owner, repo, ref, opts);
+	return await require_github_refs_cache.getGithubCache().getOrFetch(cacheKey, async () => {
+		return await require_github_refs_rest.fetchRefSha(owner, repo, ref, opts);
 	});
 }
 
 //#endregion
 exports.clearRefCache = require_github_refs_cache.clearRefCache;
-Object.defineProperty(exports, 'fetchRefSha', {
-  enumerable: true,
-  get: function () {
-    return fetchRefSha;
-  }
-});
-Object.defineProperty(exports, 'fetchRefShaViaGraphQL', {
-  enumerable: true,
-  get: function () {
-    return fetchRefShaViaGraphQL;
-  }
-});
+exports.fetchRefSha = require_github_refs_rest.fetchRefSha;
+exports.fetchRefShaViaGraphQL = require_github_refs_graphql.fetchRefShaViaGraphQL;
 exports.getGithubCache = require_github_refs_cache.getGithubCache;
 exports.resolveRefToSha = resolveRefToSha;

package/dist/globs/_internal.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_primordials_map_set = require('../primordials/map-set.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_primordials_map_set = require('../primordials/map-set.js');
 const require_paths_normalize = require('../paths/normalize.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_node_fs = require('../node/fs.js');

package/dist/http-request/browser.js

@@ -2,8 +2,8 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_error = require('../primordials/error.js');
-const require_primordials_math = require('../primordials/math.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_primordials_math = require('../primordials/math.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_primordials_date = require('../primordials/date.js');
 const require_primordials_json = require('../primordials/json.js');

package/dist/http-request/checksum-file.js

@@ -2,8 +2,8 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_error = require('../primordials/error.js');
-const require_integrity = require('../integrity.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_integrity = require('../integrity.js');
 const require_http_request_request = require('./request.js');
 
 //#region src/http-request/checksum-file.ts

package/dist/http-request/headers.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_primordials_number = require('../primordials/number.js');
 const require_primordials_object = require('../primordials/object.js');
+const require_primordials_number = require('../primordials/number.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_primordials_date = require('../primordials/date.js');
 const require_primordials_globals = require('../primordials/globals.js');

package/dist/integrity.d.ts

@@ -1,18 +1,36 @@
+/**
+ * SRI-blessed hash algorithms. The W3C set; the prefix is part of the wire
+ * format, not a fleet convention.
+ */
+export type HashAlgorithm = 'sha256' | 'sha384' | 'sha512';
+/**
+ * A cryptographic hash: an algorithm plus the digest in both encodings. Frozen,
+ * plain, self-describing — `h.algorithm` removes every "is this 256 or 512?"
+ * guess, and `h.hex` / `h.sri` are precomputed views (cheap transcodes of the
+ * digest, eager so the value stays serializable and structurally comparable).
+ */
+export interface Hash {
+    readonly algorithm: HashAlgorithm;
+    /**
+     * Lowercase hex digest (64 chars sha256, 96 sha384, 128 sha512).
+     */
+    readonly hex: string;
+    /**
+     * W3C SRI string: `<algorithm>-<base64>`.
+     */
+    readonly sri: string;
+}
+/**
+ * Anything a caller can hand verify/convert as "the expected hash": a parsed
+ * {@link Hash}, an SRI string, or a bare hex digest (algorithm inferred by
+ * length).
+ */
+export type HashInput = string | Hash;
 /**
  * Tagged union representing an expected hash.
  *
- * @example
- *   // Bare SRI (sniffed as integrity):
- *   'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs='
- *
- * @example
- *   // Bare sha256 hex (sniffed as checksum):
- *   'a1b2c3...'
- *
- * @example
- *   // Explicit:
- *   { type: 'integrity', value: 'sha512-...' }
- *   { type: 'checksum', value: 'a1b2c3...' }
+ * @deprecated Prefer {@link HashInput} + {@link parseHash}. Kept for the
+ *   `integrity?: HashSpec` option fields across dlx / external-tools.
  */
 export type HashSpec = string | {
     type: 'integrity';
@@ -22,15 +40,16 @@ export type HashSpec = string | {
     value: string;
 };
 /**
- * Normalized internal form. Always an object.
+ * Normalized internal form of a {@link HashSpec}. 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.
+ * Both pinned hash formats for the same bytes: the sha512 SRI we pin against
+ * and the sha256 hex upstream tools emit. Returned from downloads so callers
+ * record whichever their config uses.
  */
 export interface ComputedHashes {
     /**
@@ -43,7 +62,7 @@ export interface ComputedHashes {
     checksum: string;
 }
 /**
- * Parsed components of an integrity string.
+ * Parsed components of an SRI integrity string.
  */
 export interface ParsedIntegrity {
     /**
@@ -56,60 +75,64 @@ export interface ParsedIntegrity {
     body: string;
 }
 /**
- * Convert a sha256 hex checksum to its SRI integrity form (`sha256-<base64>`).
- * Idempotent on integrity input — call this on user-supplied data without first
- * sniffing the format.
- *
- * The default algorithm is `'sha256'` because this converts a _checksum_, and
- * checksums are sha256 by fleet convention (the GitHub-SHA256SUMS interop shape
- * its only caller, `checksum-file.ts`, parses). Do NOT flip this default to
- * sha512: this function only relabels the hex bytes, it does not re-hash, so a
- * sha512 label on a 256-bit digest would be a lie. The canonical algorithm for
- * OUR-side integrity values is sha512 — emitted by `computeHashes` as the
- * `integrity` (`sha512-<base64>`) field; sha256 is reserved for
- * upstream-SHASUMS interop and content addressing. Pass an explicit algorithm
- * if you have a hex digest from `sha384` or `sha512` (the function does not
- * verify hex length against the algorithm — caller's responsibility).
+ * Convert a hex checksum to its SRI integrity form.
  *
- * @example
- *   ;```typescript
- *   checksumToIntegrity(
- *     '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b',
- *   )
- *   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs='
- *
- *   checksumToIntegrity('sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=')
- *   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=' (idempotent)
- *   ```
+ * @deprecated Prefer `parseHash(x).sri`, which is total across all algorithms
+ *   and infers the algorithm from a bare hex digest. This shim defaults to
+ *   `'sha256'` because it only relabels the hex bytes — it does NOT re-hash, so
+ *   a sha512 label on a 256-bit digest would be a lie. Idempotent on SRI input.
  *
  * @throws TypeError when the input is neither a recognized SRI nor a hex
  *   digest.
  */
-export declare function checksumToIntegrity(input: string, algorithm?: string): string;
+export declare function checksumToIntegrity(input: string, algorithm?: HashAlgorithm): string;
 /**
- * Compute both integrity (sha512 SRI) and checksum (sha256 hex) for a buffer of
- * bytes.
+ * Compute a single {@link Hash} of `bytes`. Defaults to sha512 — the canonical
+ * trust string we pin against. Pass `'sha256'` for the upstream-interop digest.
+ *
+ * @example
+ *   ;```typescript
+ *   computeHash(bytes).sri        // 'sha512-…'  (pin this)
+ *   computeHash(bytes, 'sha256').hex  // '3620a0…' (compare to SHA256SUMS)
+ *   ```
+ */
+export declare function computeHash(bytes: NodeJS.ArrayBufferView, algorithm?: HashAlgorithm): Hash;
+/**
+ * Compute both pinned formats for `bytes`: the sha512 SRI integrity and the
+ * sha256 hex checksum. Use when a config records both (e.g.
+ * `external-tools.json`, dlx lockfiles).
  */
 export declare function computeHashes(bytes: Buffer): ComputedHashes;
 /**
- * Convert a sha256 SRI integrity string to its hex checksum form (64 lowercase
- * chars). Idempotent on checksum input.
+ * Compare two hashes for equality, ENCODING-agnostically. Parses both and —
+ * only when they share an algorithm — timing-safe compares the digests.
  *
- * Throws on `sha384` and `sha512` SRI — checksums are sha256-only by fleet
- * convention. Callers that need a hex digest for those algorithms can call
- * `parseIntegrity(sri)` and decode `.body` manually.
+ * Returns false when the algorithms differ. A sha512 and a sha256 are different
+ * functions of the same bytes: their digests are unrelated values, so they can
+ * never be "equal", and you CANNOT derive or check one against the other
+ * without the original bytes. To confirm a sha256 and a sha512 describe the
+ * same content, hash the bytes both ways (`computeHashes`) or `verifyHash` the
+ * bytes against each — there is no hash-to-hash shortcut across algorithms.
+ *
+ * What this DOES solve is the cross-ENCODING case that bites string `===`: a
+ * sha256 SRI and the same sha256 hex compare equal here.
  *
  * @example
  *   ;```typescript
- *   integrityToChecksum('sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=')
- *   // '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b'
- *
- *   integrityToChecksum(
- *     '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b',
- *   )
- *   // '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b' (idempotent)
+ *   equalHashes('sha256-NiCg…', '3620a0fc…')  // true  (same digest, SRI vs hex)
+ *   equalHashes('sha512-…', '3620a0fc…')       // false (different algorithms)
  *   ```
  *
+ * @throws TypeError when either input is not a recognized hash.
+ */
+export declare function equalHashes(a: HashInput, b: HashInput): boolean;
+/**
+ * Convert an SRI integrity string to its hex checksum form.
+ *
+ * @deprecated Prefer `parseHash(x).hex`, which is total across all algorithms.
+ *   This shim is sha256-only (throws on sha384 / sha512) to preserve its
+ *   historical "checksums are sha256" contract. Idempotent on hex input.
+ *
  * @throws TypeError when the input is neither a recognized SRI nor a hex
  *   checksum, or when the input is a non-sha256 SRI.
  */
@@ -118,49 +141,73 @@ export declare function integrityToChecksum(input: string): string;
  * True when `s` is a sha256 hex checksum (exactly 64 hex chars).
  */
 export declare function isChecksum(s: string): boolean;
+/**
+ * True when `s` is a bare hex digest of a recognized length (sha256 / sha384 /
+ * sha512).
+ */
+export declare function isHex(s: string): boolean;
 /**
  * True when `s` is a W3C SRI integrity string: `sha(256|384|512)-<base64>`.
  */
 export declare function isIntegrity(s: string): boolean;
+/**
+ * Build a frozen {@link Hash} from an algorithm and a hex digest. The internal
+ * constructor — trusts its inputs (lowercases the hex, computes the SRI view);
+ * use {@link parseHash} for untrusted strings, which validates first.
+ */
+export declare function makeHash(algorithm: HashAlgorithm, hex: string): Hash;
 /**
  * Normalize a {@link HashSpec} to its canonical `{ type, value }` form.
  *
- * - Object form is trusted (its `value` is validated for shape).
- * - Bare string matching SRI → integrity.
- * - Bare string of 64 hex chars → checksum.
- * - Anything else throws TypeError.
+ * @deprecated Prefer {@link parseHash}, which returns an algorithm-tagged
+ *   {@link Hash}. Kept for callers that branch on integrity-vs-checksum type.
  *
  * @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;
 /**
- * Split an integrity string into its `{ algorithm, body }` components. `body`
- * is the base64-encoded digest (everything after the algorithm + dash).
+ * Parse any {@link HashInput} into a canonical {@link Hash}. The one entry
+ * point for untrusted input — validates shape + length, then freezes.
  *
- * @example
- *   ;```typescript
- *   parseIntegrity('sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=')
- *   // { algorithm: 'sha256', body: 'NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs=' }
- *   ```
+ * - A {@link Hash} object is re-canonicalized from its `algorithm` + `hex`.
+ * - An SRI string carries its algorithm in the prefix (the body length is checked
+ *   against it).
+ * - A bare hex digest infers the algorithm from its length (64 / 96 / 128).
+ *
+ * @throws TypeError when the input is not a recognized SRI or hex digest, or
+ *   when an SRI body's length doesn't match its declared algorithm.
+ */
+export declare function parseHash(input: HashInput): Hash;
+/**
+ * Split an SRI integrity string into its `{ algorithm, body }` components.
+ * `body` is the base64-encoded digest.
  *
  * @throws Error when the input is not a valid SRI integrity string.
  */
 export declare function parseIntegrity(sri: string): ParsedIntegrity;
 /**
- * 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.
+ * Verify `bytes` against an expected hash. Reads the algorithm the expected
+ * hash declares, computes only that digest, and compares with
+ * `crypto.timingSafeEqual` — so any encoding (hex / SRI / {@link Hash}) and any
+ * algorithm (sha256 / sha384 / sha512) verifies without the caller reconciling
+ * formats first.
+ *
+ * @throws HashMismatchError when the recomputed digest doesn't match.
+ * @throws TypeError when `expected` is not a recognized hash.
  */
-export declare function verifyHash(expected: NormalizedHash, computed: ComputedHashes): void;
+export declare function verifyHash(bytes: NodeJS.ArrayBufferView, expected: HashInput): void;
 /**
- * Thrown when an expected hash doesn't match the computed hash of the
- * downloaded bytes. Carries both sides for diagnostics.
+ * Thrown when an expected hash doesn't match the computed hash of the verified
+ * bytes. Carries both sides (as {@link Hash}) for diagnostics.
  */
-export declare class DlxHashMismatchError extends Error {
-    readonly expected: NormalizedHash;
-    readonly actual: ComputedHashes;
-    constructor(expected: NormalizedHash, actual: ComputedHashes);
+export declare class HashMismatchError extends Error {
+    readonly expected: Hash;
+    readonly actual: Hash;
+    constructor(expected: Hash, actual: Hash);
 }
+/**
+ * @deprecated Renamed to {@link HashMismatchError}. Alias kept for callers that
+ *   catch the old name.
+ */
+export declare const DlxHashMismatchError: typeof HashMismatchError;