@socketsecurity/lib 6.0.8 → 6.0.9

package/dist/integrity.js

@@ -5,100 +5,129 @@ const require_runtime = require('./_virtual/_rolldown/runtime.js');
 const require_crypto_hash = require('./crypto/hash.js');
 const require_primordials_buffer = require('./primordials/buffer.js');
 const require_primordials_error = require('./primordials/error.js');
+const require_primordials_object = require('./primordials/object.js');
+const require_primordials_string = require('./primordials/string.js');
 let node_crypto = require("node:crypto");
 node_crypto = require_runtime.__toESM(node_crypto);
 
 //#region src/integrity.ts
 /**
-* @file Integrity + checksum helpers. The fleet uses two named hash flavors:
-*
-*   - **integrity** — W3C Subresource Integrity string:
-*     `sha(256|384|512)-<base64>`. The same shape the npm registry returns and
-*     the `<script integrity>` HTML attribute accepts. Algorithm is embedded.
-*   - **checksum** — sha256 hex digest, exactly 64 lowercase chars. The shape
-*     produced by `shasum -a 256` and used in GitHub-release SHA256SUMS files.
-*     Conversion is direction-specific so the names read in English:
-*     `checksumToIntegrity(hex)` and `integrityToChecksum(sri)`. Both are
-*     idempotent on the destination format (pass an SRI to
-*     `checksumToIntegrity`, get the same SRI back) so callers can apply them
-*     without first sniffing the input shape. "SSRI" is just another name for
-*     Subresource Integrity — this module is the only one that should mention
-*     it, and only inside `parseIntegrity` to extract the embedded algorithm +
-*     body.
+* @file Integrity + checksum helpers. One concept — a {@link Hash} (algorithm +
+*   digest) — in two encodings:
+*
+*   - **hex** — lowercase hex digest (`shasum -a 256` / GitHub `SHA256SUMS`).
+*   - **sri** — W3C Subresource Integrity `sha(256|384|512)-<base64>` (npm
+*     `dist.integrity`, the `<script integrity>` attribute). Both are views of
+*     the same digest. The algorithm is EXPLICIT on every `Hash` — never
+*     inferred from which function produced it or sniffed from a string's
+*     shape. `verifyHash(bytes, expected)` honors whatever algorithm the
+*     expected hash declares, so a sha256 `SHA256SUMS` digest and a sha512 npm
+*     integrity both "just verify" with no manual conversion. Role split (see
+*     `docs/hash-algorithms.md`, unchanged): we PIN sha512 (`computeHash`
+*     default, `computeHashes().integrity`); sha256 is the upstream-interop
+*     shape (`fetchChecksumFile`, `computeHashes().checksum`). The two only
+*     meet at verify-upstream-256 → pin-512. Algorithms are never flipped —
+*     relabeling a 256-bit digest as sha512 would be a lie, and you can't
+*     re-hash without the bytes. "SSRI" is just another name for Subresource
+*     Integrity — only this module should mention it, inside `parseIntegrity`.
 */
 const INTEGRITY_RE = /^(sha(?:256|384|512))-([A-Za-z0-9+/]+=*)$/;
+const HEX_RE = /^[a-f0-9]+$/i;
 const CHECKSUM_RE = /^[a-f0-9]{64}$/i;
+const ALGORITHM_HEX_LENGTH = {
+	sha256: 64,
+	sha384: 96,
+	sha512: 128
+};
+const HEX_LENGTH_TO_ALGORITHM = {
+	64: "sha256",
+	96: "sha384",
+	128: "sha512"
+};
 /**
-* 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).
-*
-* @example
-*   ;```typescript
-*   checksumToIntegrity(
-*     '3620a0fcaf81ecd3aaeccd5965919d90dbc913f4d07a96e11e7cafc2c785054b',
-*   )
-*   // 'sha256-NiCg/K+B7NOq7M1ZZZGdkNvJE/TQepbhHnyvwseFBUs='
+* Convert a hex checksum to its SRI integrity form.
 *
-*   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.
 */
 function checksumToIntegrity(input, algorithm = "sha256") {
 	if (isIntegrity(input)) return input;
-	if (!/^[a-f0-9]+$/i.test(input)) throw new require_primordials_error.TypeErrorCtor(`checksumToIntegrity: expected a hex digest or SRI string, got: ${input}`);
-	return `${algorithm}-${require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(input, "hex"), "base64")}`;
+	if (!HEX_RE.test(input)) throw new require_primordials_error.TypeErrorCtor(`checksumToIntegrity: expected a hex digest or SRI string, got: ${input}`);
+	return makeHash(algorithm, input).sri;
 }
 /**
-* 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)
+*   ```
+*/
+function computeHash(bytes, algorithm = "sha512") {
+	return makeHash(algorithm, require_crypto_hash.hash(algorithm, bytes, "hex"));
+}
+/**
+* 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).
 */
 function computeHashes(bytes) {
 	return {
-		integrity: `sha512-${require_crypto_hash.hash("sha512", bytes, "base64")}`,
-		checksum: require_crypto_hash.hash("sha256", bytes, "hex")
+		integrity: computeHash(bytes, "sha512").sri,
+		checksum: computeHash(bytes, "sha256").hex
 	};
 }
 /**
-* 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.
+*
+* 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.
 *
-* 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.
+* 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.
+*/
+function equalHashes(a, b) {
+	const aHash = parseHash(a);
+	const bHash = parseHash(b);
+	if (aHash.algorithm !== bHash.algorithm) return false;
+	const aBuf = require_primordials_buffer.BufferFrom(aHash.hex, "hex");
+	const bBuf = require_primordials_buffer.BufferFrom(bHash.hex, "hex");
+	return aBuf.length === bBuf.length && node_crypto.default.timingSafeEqual(aBuf, bBuf);
+}
+/**
+* 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.
 */
 function integrityToChecksum(input) {
 	if (isChecksum(input)) return input;
 	const parsed = parseIntegrity(input);
-	if (parsed.algorithm !== "sha256") throw new require_primordials_error.TypeErrorCtor(`integrityToChecksum: ${parsed.algorithm} integrity has no 64-hex-char checksum form — checksums are sha256-only by fleet convention.`);
+	if (parsed.algorithm !== "sha256") throw new require_primordials_error.TypeErrorCtor(`integrityToChecksum: ${parsed.algorithm} integrity has no 64-hex-char checksum form — checksums are sha256-only by fleet convention. Use parseHash(x).hex for any algorithm.`);
 	return require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(parsed.body, "base64"), "hex");
 }
 /**
@@ -108,18 +137,36 @@ function isChecksum(s) {
 	return CHECKSUM_RE.test(s);
 }
 /**
+* True when `s` is a bare hex digest of a recognized length (sha256 / sha384 /
+* sha512).
+*/
+function isHex(s) {
+	return HEX_RE.test(s) && HEX_LENGTH_TO_ALGORITHM[s.length] !== void 0;
+}
+/**
 * True when `s` is a W3C SRI integrity string: `sha(256|384|512)-<base64>`.
 */
 function isIntegrity(s) {
 	return INTEGRITY_RE.test(s);
 }
 /**
+* 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.
+*/
+function makeHash(algorithm, hex) {
+	const lowerHex = require_primordials_string.StringPrototypeToLowerCase(hex);
+	return require_primordials_object.ObjectFreeze({
+		algorithm,
+		hex: lowerHex,
+		sri: `${algorithm}-${require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(lowerHex, "hex"), "base64")}`
+	});
+}
+/**
 * 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.
@@ -154,14 +201,37 @@ function normalizeHash(spec) {
 	throw new require_primordials_error.TypeErrorCtor(`normalizeHash: unrecognized hash format. Expected SRI integrity ("sha(256|384|512)-<base64>") or sha256 hex checksum (64 hex chars), got: ${spec}`);
 }
 /**
-* 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.
+*/
+function parseHash(input) {
+	if (typeof input === "object" && input !== null) return makeHash(input.algorithm, input.hex);
+	const sriMatch = INTEGRITY_RE.exec(input);
+	if (sriMatch) {
+		const algorithm = sriMatch[1];
+		const hex = require_primordials_buffer.BufferPrototypeToString(require_primordials_buffer.BufferFrom(sriMatch[2], "base64"), "hex");
+		const expectedLength = ALGORITHM_HEX_LENGTH[algorithm];
+		if (hex.length !== expectedLength) throw new require_primordials_error.TypeErrorCtor(`parseHash: ${algorithm} SRI body decodes to ${hex.length} hex chars, expected ${expectedLength}: ${input}`);
+		return makeHash(algorithm, hex);
+	}
+	if (HEX_RE.test(input)) {
+		const algorithm = HEX_LENGTH_TO_ALGORITHM[input.length];
+		if (algorithm === void 0) throw new require_primordials_error.TypeErrorCtor(`parseHash: hex digest is ${input.length} chars; expected 64 (sha256), 96 (sha384), or 128 (sha512): ${input}`);
+		return makeHash(algorithm, input);
+	}
+	throw new require_primordials_error.TypeErrorCtor(`parseHash: expected an SRI string ("sha(256|384|512)-<base64>") or a hex digest, got: ${input}`);
+}
+/**
+* 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.
 */
@@ -174,41 +244,55 @@ function parseIntegrity(sri) {
 	};
 }
 /**
-* Verify computed hashes against an expected {@link NormalizedHash}. Uses
-* `crypto.timingSafeEqual` for constant-time comparison.
+* 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 DlxHashMismatchError when the hash of the matching type doesn't match
-*   the expected value.
+* @throws HashMismatchError when the recomputed digest doesn't match.
+* @throws TypeError when `expected` is not a recognized hash.
 */
-function verifyHash(expected, computed) {
-	const actual = expected.type === "integrity" ? computed.integrity : computed.checksum;
-	const expectedBuf = require_primordials_buffer.BufferFrom(expected.value);
-	const actualBuf = require_primordials_buffer.BufferFrom(actual);
-	if (expectedBuf.length !== actualBuf.length || !node_crypto.default.timingSafeEqual(expectedBuf, actualBuf)) throw new DlxHashMismatchError(expected, computed);
+function verifyHash(bytes, expected) {
+	const expectedHash = parseHash(expected);
+	const actualHash = computeHash(bytes, expectedHash.algorithm);
+	const expectedBuf = require_primordials_buffer.BufferFrom(expectedHash.hex, "hex");
+	const actualBuf = require_primordials_buffer.BufferFrom(actualHash.hex, "hex");
+	if (expectedBuf.length !== actualBuf.length || !node_crypto.default.timingSafeEqual(expectedBuf, actualBuf)) throw new HashMismatchError(expectedHash, actualHash);
 }
 /**
-* 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.
 */
-var DlxHashMismatchError = class extends Error {
+var HashMismatchError = class 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";
+		super(`Hash mismatch (${expected.algorithm}): expected ${expected.sri}, got ${actual.sri}`);
+		this.name = "HashMismatchError";
 		this.expected = expected;
 		this.actual = actual;
 	}
 };
+/**
+* @deprecated Renamed to {@link HashMismatchError}. Alias kept for callers that
+*   catch the old name.
+*/
+const DlxHashMismatchError = HashMismatchError;
 
 //#endregion
 exports.DlxHashMismatchError = DlxHashMismatchError;
+exports.HashMismatchError = HashMismatchError;
 exports.checksumToIntegrity = checksumToIntegrity;
+exports.computeHash = computeHash;
 exports.computeHashes = computeHashes;
+exports.equalHashes = equalHashes;
 exports.integrityToChecksum = integrityToChecksum;
 exports.isChecksum = isChecksum;
+exports.isHex = isHex;
 exports.isIntegrity = isIntegrity;
+exports.makeHash = makeHash;
 exports.normalizeHash = normalizeHash;
+exports.parseHash = parseHash;
 exports.parseIntegrity = parseIntegrity;
 exports.verifyHash = verifyHash;

package/dist/logger/colors.d.ts

@@ -5,13 +5,12 @@
  *   emitted via the 24-bit `[38;2;...m` escape because `yoctocolors-cjs`
  *   doesn't ship an `rgb()` helper.
  */
-import yoctocolorsCjs from '../external/yoctocolors-cjs';
 import type { ColorValue } from '../colors/types';
 /**
  * Apply a color to text using yoctocolors. Handles both named colors and RGB
  * tuples.
  */
-export declare function applyColor(text: string, color: ColorValue, colors: typeof yoctocolorsCjs): string;
+export declare function applyColor(text: string, color: ColorValue): string;
 /**
  * Get the yoctocolors module for terminal colors.
  */

package/dist/logger/colors.js

@@ -17,9 +17,9 @@ src_external_yoctocolors_cjs = require_runtime.__toESM(src_external_yoctocolors_
 * Apply a color to text using yoctocolors. Handles both named colors and RGB
 * tuples.
 */
-function applyColor(text, color, colors) {
+function applyColor(text, color) {
 	if (typeof color === "string") {
-		const formatter = colors[color];
+		const formatter = src_external_yoctocolors_cjs.default[color];
 		return formatter ? formatter(text) : text;
 	}
 	const { 0: r, 1: g, 2: b } = color;

package/dist/logger/symbols-builder.js

@@ -26,18 +26,17 @@ src_external__socketregistry_is_unicode_supported = require_runtime.__toESM(src_
 */
 function buildLoggerSymbols(theme) {
 	const supported = (0, src_external__socketregistry_is_unicode_supported.default)();
-	const colors = require_logger_colors.getYoctocolors();
 	/* c8 ignore start - ASCII-fallback symbol arms only fire on
 	terminals without unicode support; tests run on unicode TTYs. */
 	return {
 		__proto__: null,
-		fail: require_logger_colors.applyColor(supported ? "✖" : "×", theme.colors.error, colors),
-		info: require_logger_colors.applyColor(supported ? "ℹ" : "i", theme.colors.info, colors),
-		progress: require_logger_colors.applyColor(supported ? "∴" : ":.", theme.colors.step, colors),
-		skip: require_logger_colors.applyColor(supported ? "↻" : "@", theme.colors.step, colors),
-		step: require_logger_colors.applyColor(supported ? "→" : ">", theme.colors.step, colors),
-		success: require_logger_colors.applyColor(supported ? "✔" : "√", theme.colors.success, colors),
-		warn: require_logger_colors.applyColor(supported ? "⚠" : "‼", theme.colors.warning, colors)
+		fail: require_logger_colors.applyColor(supported ? "✖" : "×", theme.colors.error),
+		info: require_logger_colors.applyColor(supported ? "ℹ" : "i", theme.colors.info),
+		progress: require_logger_colors.applyColor(supported ? "∴" : ":.", theme.colors.step),
+		skip: require_logger_colors.applyColor(supported ? "↻" : "@", theme.colors.step),
+		step: require_logger_colors.applyColor(supported ? "→" : ">", theme.colors.step),
+		success: require_logger_colors.applyColor(supported ? "✔" : "√", theme.colors.success),
+		warn: require_logger_colors.applyColor(supported ? "⚠" : "‼", theme.colors.warning)
 	};
 	/* c8 ignore stop */
 }

package/dist/logger/symbols.js

@@ -39,14 +39,14 @@ function createLogSymbols() {
 		const stepColor = theme.colors.step;
 		/* c8 ignore start - ASCII-fallback symbol arms only fire on
 		terminals without unicode support; tests run on unicode TTYs. */
-		target["fail"] = require_logger_colors.applyColor(supported ? "✖" : "×", errorColor, colors);
-		target["info"] = require_logger_colors.applyColor(supported ? "ℹ" : "i", infoColor, colors);
-		target["progress"] = require_logger_colors.applyColor(supported ? "∴" : ":.", stepColor, colors);
-		target["reason"] = colors.dim(require_logger_colors.applyColor(supported ? "∴" : ":.", warningColor, colors));
-		target["skip"] = require_logger_colors.applyColor(supported ? "↻" : "@", stepColor, colors);
-		target["step"] = require_logger_colors.applyColor(supported ? "→" : ">", stepColor, colors);
-		target["success"] = require_logger_colors.applyColor(supported ? "✔" : "√", successColor, colors);
-		target["warn"] = require_logger_colors.applyColor(supported ? "⚠" : "‼", warningColor, colors);
+		target["fail"] = require_logger_colors.applyColor(supported ? "✖" : "×", errorColor);
+		target["info"] = require_logger_colors.applyColor(supported ? "ℹ" : "i", infoColor);
+		target["progress"] = require_logger_colors.applyColor(supported ? "∴" : ":.", stepColor);
+		target["reason"] = colors.dim(require_logger_colors.applyColor(supported ? "∴" : ":.", warningColor));
+		target["skip"] = require_logger_colors.applyColor(supported ? "↻" : "@", stepColor);
+		target["step"] = require_logger_colors.applyColor(supported ? "→" : ">", stepColor);
+		target["success"] = require_logger_colors.applyColor(supported ? "✔" : "√", successColor);
+		target["warn"] = require_logger_colors.applyColor(supported ? "⚠" : "‼", warningColor);
 		/* c8 ignore stop */
 	};
 	const init = () => {

package/dist/node/module.d.ts

@@ -1,7 +1,78 @@
 /**
- * @file Lazy-loader for `node:module`. See `node/fs.ts` for the design
- *   rationale shared across all `node/*.ts` lazy-loaders.
+ * @file Accessors for `node:module` that work across runtimes. Ambient
+ *   `require` is bound in CommonJS but unbound in ESM and inside
+ *   ahead-of-time-compiled package modules (e.g. Perry), where reading it
+ *   throws. And Perry's `require('module')` value omits `isBuiltin`. So instead
+ *   of the ambient `require('module')` lazy-loader, `isBuiltin`/`createRequire`
+ *   are imported as named values from the bare `module` specifier — which
+ *   resolves on Node and Perry, and which browser bundlers can stub via
+ *   resolve.fallback (a `node:` prefix would throw UnhandledSchemeError
+ *   there).
+ *   `require` is DIRECTORY-SPECIFIC: `createRequire(base)` resolves relative
+ *   specifiers (`./x`, `../y`) from `base`'s directory. For builtins and bare
+ *   packages that's irrelevant (they resolve the same anywhere), so the cached
+ *   `getRequire` / `requireBuiltin` bind to THIS file. A RELATIVE specifier
+ *   must resolve from the CALLER's directory, so use `requireFrom` with the
+ *   caller's `import.meta.url` — binding such a load to this file would resolve
+ *   it against `src/node/` instead. Bundled, every module collapses to one base
+ *   and either works; unbundled (e.g. AOT-compiled from source), each module
+ *   sits at its own nested path and the base matters.
  */
 import type * as NodeModule from 'node:module';
+/**
+ * Bind a working `require`. Ambient `require` exists in CommonJS; in ESM and
+ * ahead-of-time-compiled package modules it is unbound (reading it throws or
+ * yields undefined), so fall back to `createRequire`. Returns undefined off
+ * Node and in browsers, where neither is available.
+ *
+ * `fromUrl` sets the resolution base — pass a caller's `import.meta.url` to
+ * resolve that caller's RELATIVE specifiers. When omitted, the base is this
+ * file, which is correct only for builtins / bare packages (dir-independent).
+ * With `fromUrl` the ambient `require` is skipped: it is bound to THIS file, so
+ * it would resolve a relative specifier from the wrong directory.
+ */
+export declare function bindRequire(fromUrl?: string | undefined): ((id: string) => unknown) | undefined;
+/**
+ * Returns `node:module` (or undefined off Node), loaded through the bound
+ * `require`. Cached across calls.
+ */
 export declare function getNodeModule(): typeof NodeModule;
+/**
+ * Returns a working `require` bound to THIS file, binding one on first call
+ * (see bindRequire). Cached across calls; undefined off Node / in browsers.
+ *
+ * For builtins and bare packages only — the resolution base is this file, so a
+ * relative specifier would resolve from `src/node/`. Use `requireFrom` for
+ * relative loads.
+ */
+export declare function getRequire(): ((id: string) => unknown) | undefined;
+/**
+ * Is `name` a Node built-in module? Resolved from the statically-imported
+ * `isBuiltin`, so it works on Node and on ahead-of-time-compiled binaries
+ * (Perry), where ambient `require('module')` would lack `isBuiltin`. Returns
+ * false in browsers, where the bare `module` import is stubbed away.
+ *
+ * Single source of truth for "is this a Node builtin?" probes across socket-lib
+ * (used by the smol-binding loaders to gate their `node:smol-*` loads).
+ */
 export declare function isNodeBuiltin(name: string): boolean;
+/**
+ * Load a built-in module by *computed* specifier through the bound `require`
+ * (see getRequire). The specifier is a parameter — never a literal at the call
+ * site — so browser bundlers neither walk nor bundle it. Returns undefined
+ * where no `require` can be bound.
+ *
+ * Builtins / bare packages only (dir-independent); for a relative specifier use
+ * `requireFrom`. Used by `getNodeModule` for `node:module`, and by the
+ * smol-binding loaders for the optional `node:smol-*` native bindings (gated
+ * behind `isNodeBuiltin`, true only on socket-btm's smol Node binary).
+ */
+export declare function requireBuiltin(specifier: string): unknown;
+/**
+ * Load a module by specifier from a CALLER-supplied base (its
+ * `import.meta.url`). Use this for RELATIVE specifiers (`./x`, `../y`), whose
+ * resolution depends on the caller's directory — `requireBuiltin` binds to this
+ * file and would resolve them from `src/node/`. Not cached: the binding is
+ * per-caller. Returns undefined where no `require` can be bound.
+ */
+export declare function requireFrom(fromUrl: string, specifier: string): unknown;

package/dist/node/module.js

@@ -2,30 +2,115 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_constants_runtime = require('../constants/runtime.js');
+let module$1 = require("module");
 
 //#region src/node/module.ts
+/**
+* @file Accessors for `node:module` that work across runtimes. Ambient
+*   `require` is bound in CommonJS but unbound in ESM and inside
+*   ahead-of-time-compiled package modules (e.g. Perry), where reading it
+*   throws. And Perry's `require('module')` value omits `isBuiltin`. So instead
+*   of the ambient `require('module')` lazy-loader, `isBuiltin`/`createRequire`
+*   are imported as named values from the bare `module` specifier — which
+*   resolves on Node and Perry, and which browser bundlers can stub via
+*   resolve.fallback (a `node:` prefix would throw UnhandledSchemeError
+*   there).
+*   `require` is DIRECTORY-SPECIFIC: `createRequire(base)` resolves relative
+*   specifiers (`./x`, `../y`) from `base`'s directory. For builtins and bare
+*   packages that's irrelevant (they resolve the same anywhere), so the cached
+*   `getRequire` / `requireBuiltin` bind to THIS file. A RELATIVE specifier
+*   must resolve from the CALLER's directory, so use `requireFrom` with the
+*   caller's `import.meta.url` — binding such a load to this file would resolve
+*   it against `src/node/` instead. Bundled, every module collapses to one base
+*   and either works; unbundled (e.g. AOT-compiled from source), each module
+*   sits at its own nested path and the base matters.
+*/
 let cachedModule;
-function getNodeModule() {
+let cachedRequire;
+/**
+* Bind a working `require`. Ambient `require` exists in CommonJS; in ESM and
+* ahead-of-time-compiled package modules it is unbound (reading it throws or
+* yields undefined), so fall back to `createRequire`. Returns undefined off
+* Node and in browsers, where neither is available.
+*
+* `fromUrl` sets the resolution base — pass a caller's `import.meta.url` to
+* resolve that caller's RELATIVE specifiers. When omitted, the base is this
+* file, which is correct only for builtins / bare packages (dir-independent).
+* With `fromUrl` the ambient `require` is skipped: it is bound to THIS file, so
+* it would resolve a relative specifier from the wrong directory.
+*/
+function bindRequire(fromUrl) {
 	if (!require_constants_runtime.IS_NODE) return;
-	return cachedModule ??= /*@__PURE__*/ require("module");
+	if (!fromUrl && typeof require === "function") return require;
+	if (typeof module$1.createRequire === "function") try {
+		return (0, module$1.createRequire)(fromUrl ?? require("url").pathToFileURL(__filename).href);
+	} catch {
+		return;
+	}
+}
+/**
+* Returns `node:module` (or undefined off Node), loaded through the bound
+* `require`. Cached across calls.
+*/
+function getNodeModule() {
+	return cachedModule ??= requireBuiltin("module");
 }
 /**
-* Lazy + cached reference to `node:module`'s `isBuiltin(name)`. First call
-* resolves the binding; subsequent calls dispatch through the cached function
-* reference. Safe to detach — `isBuiltin` is `this`-free.
+* Returns a working `require` bound to THIS file, binding one on first call
+* (see bindRequire). Cached across calls; undefined off Node / in browsers.
 *
-* Returns `false` in browser / non-CJS environments where `require` is
-* undefined — no `node:` modules are built-in there.
+* For builtins and bare packages only — the resolution base is this file, so a
+* relative specifier would resolve from `src/node/`. Use `requireFrom` for
+* relative loads.
+*/
+function getRequire() {
+	if (cachedRequire === void 0) cachedRequire = bindRequire();
+	return cachedRequire;
+}
+/**
+* Is `name` a Node built-in module? Resolved from the statically-imported
+* `isBuiltin`, so it works on Node and on ahead-of-time-compiled binaries
+* (Perry), where ambient `require('module')` would lack `isBuiltin`. Returns
+* false in browsers, where the bare `module` import is stubbed away.
 *
 * Single source of truth for "is this a Node builtin?" probes across socket-lib
-* (used by the smol-binding loaders to gate `require('node:smol-*')`).
+* (used by the smol-binding loaders to gate their `node:smol-*` loads).
 */
-let cachedIsBuiltin;
 function isNodeBuiltin(name) {
-	if (!require_constants_runtime.IS_NODE) return false;
-	return (cachedIsBuiltin ??= getNodeModule().isBuiltin)(name);
+	if (!require_constants_runtime.IS_NODE || typeof module$1.isBuiltin !== "function") return false;
+	return (0, module$1.isBuiltin)(name);
+}
+/**
+* Load a built-in module by *computed* specifier through the bound `require`
+* (see getRequire). The specifier is a parameter — never a literal at the call
+* site — so browser bundlers neither walk nor bundle it. Returns undefined
+* where no `require` can be bound.
+*
+* Builtins / bare packages only (dir-independent); for a relative specifier use
+* `requireFrom`. Used by `getNodeModule` for `node:module`, and by the
+* smol-binding loaders for the optional `node:smol-*` native bindings (gated
+* behind `isNodeBuiltin`, true only on socket-btm's smol Node binary).
+*/
+function requireBuiltin(specifier) {
+	const req = getRequire();
+	if (req) return req(specifier);
+}
+/**
+* Load a module by specifier from a CALLER-supplied base (its
+* `import.meta.url`). Use this for RELATIVE specifiers (`./x`, `../y`), whose
+* resolution depends on the caller's directory — `requireBuiltin` binds to this
+* file and would resolve them from `src/node/`. Not cached: the binding is
+* per-caller. Returns undefined where no `require` can be bound.
+*/
+function requireFrom(fromUrl, specifier) {
+	const req = bindRequire(fromUrl);
+	if (req) return req(specifier);
 }
 
 //#endregion
+exports.bindRequire = bindRequire;
 exports.getNodeModule = getNodeModule;
-exports.isNodeBuiltin = isNodeBuiltin;
+exports.getRequire = getRequire;
+exports.isNodeBuiltin = isNodeBuiltin;
+exports.requireBuiltin = requireBuiltin;
+exports.requireFrom = requireFrom;