@socketsecurity/lib 5.20.1 → 5.21.0

package/dist/schema/parse.js

@@ -0,0 +1,38 @@
+"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 parse_exports = {};
+__export(parse_exports, {
+  parseSchema: () => parseSchema
+});
+module.exports = __toCommonJS(parse_exports);
+var import_validate = require("./validate");
+function parseSchema(schema, data) {
+  const result = (0, import_validate.validateSchema)(schema, data);
+  if (result.ok) {
+    return result.value;
+  }
+  const summary = result.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join(", ");
+  throw new Error(`Validation failed: ${summary}`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseSchema
+});

package/dist/schema/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Shared types for schema validation.
+ *
+ * `Schema<T>` is the Zod-shaped duck-type contract — any validator with
+ * a `.safeParse(data)` method returning `{ success, data?, error? }`
+ * satisfies it. socket-lib detects Zod (v3 and v4) structurally via this
+ * interface; consumers bring their own Zod.
+ *
+ * `ValidateResult<T>` / `ValidationIssue` / `Infer<S>` / `AnySchema` are
+ * the normalized shapes produced by `@socketsecurity/lib/schema/validate`
+ * and `@socketsecurity/lib/schema/parse`.
+ */
+/**
+ * Result of a Zod-shaped schema's `.safeParse()` call.
+ *
+ * @template T - The expected type of the parsed data
+ */
+export interface ParseResult<T> {
+    /** Indicates whether parsing was successful */
+    success: boolean;
+    /** Parsed and validated data (only present when `success` is `true`) */
+    data?: T | undefined;
+    /** Error information (only present when `success` is `false`) */
+    error?: unknown;
+}
+/**
+ * Zod-shaped duck-type for any validator exposing `safeParse` / `parse`.
+ *
+ * @template T - The expected output type after validation
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const userSchema = z.object({ name: z.string(), age: z.number() })
+ *
+ * // Schema satisfies this interface
+ * const schema: Schema<User> = userSchema
+ * const result = schema.safeParse({ name: 'Alice', age: 30 })
+ * ```
+ */
+export interface Schema<T = unknown> {
+    /** Non-throwing parse. */
+    safeParse(data: unknown): ParseResult<T>;
+    /** Throwing parse. */
+    parse(data: unknown): T;
+    /** Optional schema name for debugging. */
+    _name?: string | undefined;
+}
+/**
+ * Internal structural shape of a Zod v4 schema — carries the inferred
+ * output type on `_zod.output`. Used for type-only detection in `Infer<S>`.
+ *
+ * @internal
+ */
+interface ZodV4LikeSchema<O = unknown> {
+    _zod: {
+        output: O;
+    };
+    safeParse(data: unknown): unknown;
+}
+/**
+ * Internal structural shape of a Zod v3 schema — carries the inferred
+ * output type on `_output`. Used for type-only detection in `Infer<S>`.
+ *
+ * @internal
+ */
+interface ZodV3LikeSchema<O = unknown> {
+    _output: O;
+    safeParse(data: unknown): unknown;
+}
+/**
+ * Internal structural shape of a TypeBox `TSchema` — carries the inferred
+ * output type on the phantom `static` field. Only used inside socket-lib
+ * for type-only detection in `Infer<S>`; external callers should pass
+ * Zod schemas.
+ *
+ * @internal
+ */
+interface TypeBoxLikeSchema {
+    static: unknown;
+}
+/**
+ * Any schema kind the validators accept.
+ */
+export type AnySchema = ZodV4LikeSchema<unknown> | ZodV3LikeSchema<unknown> | TypeBoxLikeSchema | Schema<unknown>;
+/**
+ * Infer the validated output type from any supported schema kind.
+ *
+ * Order matters: TypeBox schemas carry a phantom `static` field, so we
+ * check for TypeBox before falling through to Zod and the duck-type.
+ */
+export type Infer<S> = S extends {
+    static: infer Static;
+} ? Static : S extends {
+    _zod: {
+        output: infer O;
+    };
+} ? O : S extends {
+    _output: infer O;
+} ? O : S extends Schema<infer T> ? T : unknown;
+/**
+ * A single normalized validation error.
+ */
+export interface ValidationIssue {
+    /** Array path into the value (e.g. `['user', 'age']`). */
+    path: Array<string | number>;
+    /** Human-readable description of the failure. */
+    message: string;
+}
+/**
+ * Tagged-union result of `validateSchema`. Callers narrow on `ok`.
+ */
+export type ValidateResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: ValidationIssue[];
+};
+export {};

package/dist/schema/validate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Universal schema validator — non-throwing.
+ *
+ * Accepts any Zod-shaped schema (`.safeParse`-exposing) and returns a tagged
+ * result `{ ok: true, value } | { ok: false, errors }` with normalized
+ * `{ path, message }` issues. No runtime dependency on `zod` — detection
+ * is purely structural.
+ *
+ * @internal
+ * socket-lib additionally recognizes TypeBox schemas for its own internal
+ * use (e.g. `src/ipc.ts`'s stub-file validation). That path is not a
+ * supported consumer API.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { validateSchema } from '@socketsecurity/lib/schema/validate'
+ *
+ * const User = z.object({ name: z.string() })
+ * const r = validateSchema(User, data)
+ * if (r.ok) r.value.name // string
+ * else r.errors           // ValidationIssue[]
+ * ```
+ */
+import type { Infer, ValidateResult } from './types';
+/**
+ * Validate `data` against a Zod-style `schema`. Non-throwing.
+ *
+ * The return type narrows `value` to `Infer<S>`, so callers get
+ * `z.infer<typeof S>` with no casts. Errors are normalized to
+ * `{ path, message }` regardless of the underlying validator.
+ *
+ * @throws {TypeError} When `schema` is not a recognized validator kind.
+ */
+export declare function validateSchema<S>(schema: S, data: unknown): ValidateResult<Infer<S>>;

package/dist/{validation/validate-schema.js → schema/validate.js}

@@ -18,12 +18,11 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var validate_schema_exports = {};
-__export(validate_schema_exports, {
-  parseSchema: () => parseSchema,
+var validate_exports = {};
+__export(validate_exports, {
   validateSchema: () => validateSchema
 });
-module.exports = __toCommonJS(validate_schema_exports);
+module.exports = __toCommonJS(validate_exports);
 function isTypeBoxSchema(schema) {
   if (schema === null || typeof schema !== "object") {
     return false;
@@ -90,19 +89,10 @@ function validateSchema(schema, data) {
     };
   }
   throw new TypeError(
-    "validateSchema: unsupported schema kind. Expected a TypeBox schema, a Zod schema, or an object with a safeParse method."
+    "validateSchema: unsupported schema kind. Expected a Zod schema or an object with a safeParse method."
   );
 }
-function parseSchema(schema, data) {
-  const result = validateSchema(schema, data);
-  if (result.ok) {
-    return result.value;
-  }
-  const summary = result.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join(", ");
-  throw new Error(`Validation failed: ${summary}`);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  parseSchema,
   validateSchema
 });

package/dist/suppress-warnings.js

@@ -95,7 +95,6 @@ function suppressWarningType(warningType) {
 }
 async function withSuppressedWarnings(warningType, callback) {
   const wasAlreadySuppressed = suppressedWarnings.has(warningType);
-  const original = import_node_process.default.emitWarning;
   suppressWarningType(warningType);
   try {
     return await callback();
@@ -103,7 +102,6 @@ async function withSuppressedWarnings(warningType, callback) {
     if (!wasAlreadySuppressed) {
       suppressedWarnings.delete(warningType);
     }
-    import_node_process.default.emitWarning = original;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/url.js

@@ -73,7 +73,11 @@ function urlSearchParamAsBoolean(value, options) {
   };
   if (typeof value === "string") {
     const trimmed = value.trim();
-    return trimmed === "1" || trimmed.toLowerCase() === "true";
+    if (trimmed === "") {
+      return !!defaultValue;
+    }
+    const lowered = trimmed.toLowerCase();
+    return lowered === "1" || lowered === "true" || lowered === "yes" || lowered === "on";
   }
   if (value === null || value === void 0) {
     return !!defaultValue;

package/dist/versions.js

@@ -111,11 +111,11 @@ function isValidVersion(version) {
 }
 function maxVersion(versions) {
   const semver = getSemver();
-  return semver.maxSatisfying(versions, "*") || void 0;
+  return semver.maxSatisfying(versions, "*", { includePrerelease: true }) || void 0;
 }
 function minVersion(versions) {
   const semver = getSemver();
-  return semver.minSatisfying(versions, "*") || void 0;
+  return semver.minSatisfying(versions, "*", { includePrerelease: true }) || void 0;
 }
 function parseVersion(version) {
   const semver = getSemver();

package/dist/words.js

@@ -27,18 +27,15 @@ __export(words_exports, {
 module.exports = __toCommonJS(words_exports);
 // @__NO_SIDE_EFFECTS__
 function capitalize(word) {
-  const { length } = word;
-  if (length === 0) {
+  if (word.length === 0) {
     return word;
   }
-  if (length === 1) {
-    return word.toUpperCase();
-  }
-  return `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`;
+  const [first, ...rest] = [...word];
+  return (first ?? "").toUpperCase() + rest.join("").toLowerCase();
 }
 // @__NO_SIDE_EFFECTS__
 function determineArticle(word) {
-  return /^[aeiou]/.test(word) ? "an" : "a";
+  return /^[aeiou]/i.test(word) ? "an" : "a";
 }
 // @__NO_SIDE_EFFECTS__
 function pluralize(word, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.20.1",
+  "version": "5.21.0",
   "packageManager": "pnpm@11.0.0-rc.2",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
@@ -547,6 +547,18 @@
       "types": "./dist/releases/socket-btm.d.ts",
       "default": "./dist/releases/socket-btm.js"
     },
+    "./schema/parse": {
+      "types": "./dist/schema/parse.d.ts",
+      "default": "./dist/schema/parse.js"
+    },
+    "./schema/types": {
+      "types": "./dist/schema/types.d.ts",
+      "default": "./dist/schema/types.js"
+    },
+    "./schema/validate": {
+      "types": "./dist/schema/validate.d.ts",
+      "default": "./dist/schema/validate.js"
+    },
     "./sea": {
       "types": "./dist/sea.d.ts",
       "default": "./dist/sea.js"
@@ -655,18 +667,6 @@
       "types": "./dist/url.d.ts",
       "default": "./dist/url.js"
     },
-    "./validation/json-parser": {
-      "types": "./dist/validation/json-parser.d.ts",
-      "default": "./dist/validation/json-parser.js"
-    },
-    "./validation/types": {
-      "types": "./dist/validation/types.d.ts",
-      "default": "./dist/validation/types.js"
-    },
-    "./validation/validate-schema": {
-      "types": "./dist/validation/validate-schema.d.ts",
-      "default": "./dist/validation/validate-schema.js"
-    },
     "./versions": {
       "types": "./dist/versions.d.ts",
       "default": "./dist/versions.js"
@@ -724,7 +724,7 @@
     "@socketregistry/is-unicode-supported": "1.0.5",
     "@socketregistry/packageurl-js": "1.4.2",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.19.1",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.20.1",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20260415.1",
     "@vitest/coverage-v8": "4.0.3",

package/dist/validation/json-parser.d.ts

@@ -1,58 +0,0 @@
-/**
- * @fileoverview Safe JSON parsing with validation and security controls.
- * Provides protection against prototype pollution, size limits, and schema
- * validation.
- *
- * Key Features:
- * - Prototype pollution protection: Blocks `__proto__`, `constructor`, and
- *   `prototype` keys via JSON.parse reviver at any depth.
- * - Size limits: Configurable maximum JSON string size (default 10MB).
- * - Schema validation: Optional Zod-compatible schema validation.
- * - Memory safety: Prevents memory exhaustion attacks.
- */
-import type { SafeJsonParseOptions, Schema } from './types';
-/**
- * Safely parse JSON with optional schema validation and security controls.
- * Throws errors on parse failures, validation failures, or security violations.
- *
- * This is the recommended method for parsing untrusted JSON input as it
- * provides multiple layers of security including prototype pollution
- * protection and size limits.
- *
- * @template T - The expected type of the parsed data
- * @param jsonString - The JSON string to parse
- * @param schema - Optional Zod-compatible schema for validation
- * @param options - Parsing options for security and behavior control
- * @returns The parsed and validated data
- *
- * @throws {Error} When JSON string exceeds `maxSize`.
- * @throws {Error} When JSON parsing fails.
- * @throws {Error} When prototype pollution keys are detected (unless
- *   `allowPrototype` is `true`).
- * @throws {Error} When schema validation fails.
- *
- * @example
- * ```ts
- * // Basic parsing with type inference
- * const data = safeJsonParse<User>('{"name":"Alice","age":30}')
- *
- * // With schema validation
- * import { z } from 'zod'
- * const userSchema = z.object({
- *   name: z.string(),
- *   age: z.number()
- * })
- * const user = safeJsonParse('{"name":"Alice","age":30}', userSchema)
- *
- * // With size limit
- * const data = safeJsonParse(jsonString, undefined, {
- *   maxSize: 1024 * 1024 // 1MB
- * })
- *
- * // Allow prototype keys (DANGEROUS — only for trusted sources)
- * const data = safeJsonParse('{"__proto__": {}}', undefined, {
- *   allowPrototype: true
- * })
- * ```
- */
-export declare function safeJsonParse<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: SafeJsonParseOptions): T;

package/dist/validation/json-parser.js

@@ -1,63 +0,0 @@
-"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 json_parser_exports = {};
-__export(json_parser_exports, {
-  safeJsonParse: () => safeJsonParse
-});
-module.exports = __toCommonJS(json_parser_exports);
-const DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-function prototypePollutionReviver(key, value) {
-  if (DANGEROUS_KEYS.has(key)) {
-    throw new Error(
-      "JSON contains potentially malicious prototype pollution keys"
-    );
-  }
-  return value;
-}
-function safeJsonParse(jsonString, schema, options = {}) {
-  const { allowPrototype = false, maxSize = 10 * 1024 * 1024 } = options;
-  const byteLength = Buffer.byteLength(jsonString, "utf8");
-  if (byteLength > maxSize) {
-    throw new Error(
-      `JSON string exceeds maximum size limit${maxSize !== 10 * 1024 * 1024 ? ` of ${maxSize} bytes` : ""}`
-    );
-  }
-  let parsed;
-  try {
-    parsed = allowPrototype ? JSON.parse(jsonString) : JSON.parse(jsonString, prototypePollutionReviver);
-  } catch (error) {
-    throw new Error(`Failed to parse JSON: ${error}`);
-  }
-  if (schema) {
-    const result = schema.safeParse(parsed);
-    if (!result.success) {
-      const error = result.error;
-      const errors = error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(", ");
-      throw new Error(`Validation failed: ${errors}`);
-    }
-    return result.data;
-  }
-  return parsed;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  safeJsonParse
-});

package/dist/validation/types.d.ts

@@ -1,118 +0,0 @@
-/**
- * @fileoverview Validation type definitions.
- * Provides core types for schema validation and JSON parsing with security features.
- */
-/**
- * Result of a schema validation operation.
- * Contains either successful parsed data or error information.
- *
- * @template T - The expected type of the parsed data
- *
- * @example
- * ```ts
- * const result: ParseResult<User> = schema.safeParse(data)
- * if (result.success) {
- *   console.log(result.data) // User object
- * } else {
- *   console.error(result.error) // Error details
- * }
- * ```
- */
-export interface ParseResult<T> {
-    /** Indicates whether parsing was successful */
-    success: boolean;
-    /** Parsed and validated data (only present when `success` is `true`) */
-    data?: T | undefined;
-    /** Error information (only present when `success` is `false`) */
-    error?: unknown;
-}
-/**
- * Base schema interface compatible with Zod and similar validation libraries.
- * Provides both safe and throwing parsing methods.
- *
- * @template T - The expected output type after validation
- *
- * @example
- * ```ts
- * import { z } from 'zod'
- *
- * const userSchema = z.object({
- *   name: z.string(),
- *   age: z.number()
- * })
- *
- * // Schema satisfies this interface
- * const schema: Schema<User> = userSchema
- * const result = schema.safeParse({ name: 'Alice', age: 30 })
- * ```
- */
-export interface Schema<T = unknown> {
-    /**
-     * Safely parse data without throwing errors.
-     * Returns a result object indicating success or failure.
-     *
-     * @param data - The data to validate
-     * @returns Parse result with success flag and data or error
-     */
-    safeParse(data: unknown): ParseResult<T>;
-    /**
-     * Parse data and throw an error if validation fails.
-     * Use this when you want to fail fast on invalid data.
-     *
-     * @param data - The data to validate
-     * @returns The validated and parsed data
-     * @throws {Error} When validation fails
-     */
-    parse(data: unknown): T;
-    /**
-     * Optional schema name for debugging and error messages.
-     * Useful for identifying which schema failed in complex validation chains.
-     */
-    _name?: string | undefined;
-}
-/**
- * Options for configuring safe JSON parsing with security controls.
- * Distinct from `JsonParseOptions` in `@socketsecurity/lib/json/types`
- * which is scoped to reviver/error-handling for fs-oriented JSON reads.
- *
- * @example
- * ```ts
- * const options: SafeJsonParseOptions = {
- *   maxSize: 1024 * 1024, // 1MB limit
- *   allowPrototype: false // Block prototype pollution
- * }
- * ```
- */
-export interface SafeJsonParseOptions {
-    /**
-     * Allow dangerous prototype pollution keys (`__proto__`, `constructor`, `prototype`).
-     * Set to `true` only if you trust the JSON source completely.
-     *
-     * @default false
-     *
-     * @example
-     * ```ts
-     * // Will throw error by default
-     * safeJsonParse('{"__proto__": {"polluted": true}}')
-     *
-     * // Allows the parse (dangerous!)
-     * safeJsonParse('{"__proto__": {"polluted": true}}', undefined, {
-     *   allowPrototype: true
-     * })
-     * ```
-     */
-    allowPrototype?: boolean | undefined;
-    /**
-     * Maximum allowed size of JSON string in bytes.
-     * Prevents memory exhaustion from extremely large payloads.
-     *
-     * @default 10_485_760 (10 MB)
-     *
-     * @example
-     * ```ts
-     * // Limit to 1KB
-     * safeJsonParse(jsonString, undefined, { maxSize: 1024 })
-     * ```
-     */
-    maxSize?: number | undefined;
-}