@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/globs/matcher.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file `getGlobMatcher` — picomatch-backed sync predicate with an LRU-memoized
+ *   matcher cache. `getMatchesGlob` exposes Node 22+'s native
+ *   `path.matchesGlob` for the rare case where the caller wants strict
+ *   (`nocase: false`, `dot: false`) matching.
+ */
+import type { Pattern } from './types';
+/**
+ * Return a glob-matcher function, memoized by pattern + options.
+ *
+ * The returned function is a fast synchronous predicate built on picomatch.
+ * Results are memoized — calling `getGlobMatcher(['*.ts'])` a thousand times in
+ * a loop returns the same compiled matcher each time, so callers do not need to
+ * hoist it themselves.
+ *
+ * The cache is LRU with a cap of 100 entries. Cache keys fold together the
+ * (sorted) pattern list and (sorted) option set, so arguments that differ only
+ * in ordering share a matcher.
+ *
+ * Default options: `dot: true`, `nocase: true`. Patterns starting with `!`
+ * become ignore patterns.
+ *
+ * @example
+ *   ;```typescript
+ *   const isMatch = getGlobMatcher('*.ts')
+ *   isMatch('index.ts') // true
+ *   isMatch('index.js') // false
+ *
+ *   const isSource = getGlobMatcher(['src/**', '!**\/*.test.ts'])
+ *   ```
+ */
+export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
+    dot?: boolean;
+    nocase?: boolean;
+    ignore?: string[];
+}): (path: string) => boolean;
+/**
+ * Resolve `path.matchesGlob` (or `undefined` if the runtime predates it).
+ * Probes once and caches the result for every subsequent call.
+ *
+ * Used by `getGlobMatcher`'s narrow fast-path — see the conditions spelled out
+ * at the call site. Exported for unit tests.
+ *
+ * @internal
+ */
+export declare function getMatchesGlob(): ((p: string, pattern: string) => boolean) | undefined;

package/dist/globs/matcher.js

@@ -0,0 +1,99 @@
+"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 matcher_exports = {};
+__export(matcher_exports, {
+  getGlobMatcher: () => getGlobMatcher,
+  getMatchesGlob: () => getMatchesGlob
+});
+module.exports = __toCommonJS(matcher_exports);
+var import_array = require("../primordials/array");
+var import_json = require("../primordials/json");
+var import_object = require("../primordials/object");
+var import_string = require("../primordials/string");
+var import_internal = require("./_internal");
+let _matchesGlob;
+let _matchesGlobProbed = false;
+// @__NO_SIDE_EFFECTS__
+function getGlobMatcher(glob, options) {
+  const patterns = (0, import_array.ArrayIsArray)(glob) ? glob : [glob];
+  const sortedPatterns = [...patterns].sort();
+  const sortedOptions = options ? (0, import_object.ObjectKeys)(options).sort().map((k) => {
+    const value = options[k];
+    const normalized = (0, import_array.ArrayIsArray)(value) ? [...value].sort() : value;
+    return `${k}:${(0, import_json.JSONStringify)(normalized)}`;
+  }).join(",") : "";
+  const key = `${sortedPatterns.join("|")}:${sortedOptions}`;
+  const existing = import_internal.matcherCache.get(key);
+  if (existing) {
+    import_internal.matcherCache.delete(key);
+    import_internal.matcherCache.set(key, existing);
+    return existing;
+  }
+  if (import_internal.matcherCache.size >= import_internal.MATCHER_CACHE_MAX_SIZE) {
+    const oldest = import_internal.matcherCache.keys().next().value;
+    if (oldest !== void 0) {
+      import_internal.matcherCache.delete(oldest);
+    }
+  }
+  let matcher;
+  if (patterns.length === 1 && !(0, import_string.StringPrototypeStartsWith)(patterns[0], "!") && options !== void 0 && options.nocase === false && options.dot === false && (options.ignore === void 0 || options.ignore.length === 0)) {
+    const matchesGlob = /* @__PURE__ */ getMatchesGlob();
+    if (matchesGlob !== void 0) {
+      const pattern = patterns[0];
+      matcher = (p) => matchesGlob(p, pattern);
+    }
+  }
+  if (matcher === void 0) {
+    const positivePatterns = patterns.filter(
+      (p) => !(0, import_string.StringPrototypeStartsWith)(p, "!")
+    );
+    const negativePatterns = patterns.filter((p) => (0, import_string.StringPrototypeStartsWith)(p, "!")).map((p) => p.slice(1));
+    const matchOptions = {
+      dot: true,
+      nocase: true,
+      ...options,
+      ...negativePatterns.length > 0 ? { ignore: negativePatterns } : {}
+    };
+    const picomatch = (0, import_internal.getPicomatch)();
+    matcher = picomatch(
+      positivePatterns.length > 0 ? positivePatterns : patterns,
+      matchOptions
+    );
+  }
+  import_internal.matcherCache.set(key, matcher);
+  return matcher;
+}
+// @__NO_SIDE_EFFECTS__
+function getMatchesGlob() {
+  if (!_matchesGlobProbed) {
+    const fn = require("node:path").matchesGlob;
+    if (typeof fn === "function") {
+      _matchesGlob = fn;
+    }
+    _matchesGlobProbed = true;
+  }
+  return _matchesGlob;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getGlobMatcher,
+  getMatchesGlob
+});

package/dist/globs/stream.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file `globStreamLicenses` — license-file discovery as an async stream.
+ *   Specialized for the npm-packlist-style license file search (`LICENSE*`,
+ *   `COPYING*`, etc.) with optional originals inclusion.
+ */
+import type { GlobOptions } from './types';
+/**
+ * Create a stream of license file paths matching glob patterns.
+ *
+ * @example
+ *   ;```typescript
+ *   const stream = globStreamLicenses('/tmp/my-package')
+ *   for await (const licensePath of stream) {
+ *     console.log(licensePath)
+ *   }
+ *   ```
+ */
+export declare function globStreamLicenses(dirname: string, options?: GlobOptions): NodeJS.ReadableStream;

package/dist/globs/stream.js

@@ -0,0 +1,58 @@
+"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 stream_exports = {};
+__export(stream_exports, {
+  globStreamLicenses: () => globStreamLicenses
+});
+module.exports = __toCommonJS(stream_exports);
+var import_globs = require("../paths/globs");
+var import_array = require("../primordials/array");
+var import_internal = require("./_internal");
+// @__NO_SIDE_EFFECTS__
+function globStreamLicenses(dirname, options) {
+  const {
+    ignore: ignoreOpt,
+    ignoreOriginals,
+    recursive,
+    ...globOptions
+  } = { __proto__: null, ...options };
+  const baseIgnore = (0, import_array.ArrayIsArray)(ignoreOpt) ? (0, import_internal.normalizeIgnorePatterns)(ignoreOpt) : import_internal.defaultIgnore;
+  const ignore = [...baseIgnore, "**/*.{cjs,cts,js,json,mjs,mts,ts}"];
+  if (ignoreOriginals) {
+    ignore.push(import_globs.LICENSE_ORIGINAL_GLOB_RECURSIVE);
+  }
+  const fastGlob = (0, import_internal.getFastGlob)();
+  return fastGlob.globStream(
+    [recursive ? import_globs.LICENSE_GLOB_RECURSIVE : import_globs.LICENSE_GLOB],
+    {
+      __proto__: null,
+      absolute: true,
+      caseSensitiveMatch: false,
+      cwd: dirname,
+      ...globOptions,
+      ...ignore ? { ignore } : {}
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  globStreamLicenses
+});

package/dist/globs/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file Public type surface for `globs/*` modules — the `Pattern` alias, the
+ *   `FastGlobOptions` mirror of fast-glob's option surface, and the
+ *   `GlobOptions` extension that adds Socket-specific `recursive` /
+ *   `ignoreOriginals` flags. Pure types, no runtime side effects.
+ */
+export type Pattern = string;
+export interface FastGlobOptions {
+    absolute?: boolean;
+    baseNameMatch?: boolean;
+    braceExpansion?: boolean;
+    caseSensitiveMatch?: boolean;
+    concurrency?: number;
+    cwd?: string;
+    deep?: number;
+    dot?: boolean;
+    extglob?: boolean;
+    followSymbolicLinks?: boolean;
+    fs?: unknown;
+    globstar?: boolean;
+    ignore?: string[];
+    ignoreFiles?: string[];
+    markDirectories?: boolean;
+    objectMode?: boolean;
+    onlyDirectories?: boolean;
+    onlyFiles?: boolean;
+    stats?: boolean;
+    suppressErrors?: boolean;
+    throwErrorOnBrokenSymbolicLink?: boolean;
+    unique?: boolean;
+}
+export interface GlobOptions extends FastGlobOptions {
+    ignoreOriginals?: boolean;
+    recursive?: boolean;
+}

package/dist/globs/types.js

@@ -0,0 +1,18 @@
+"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 __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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/http-request/_internal.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Private lazy loaders for the Node.js modules used by the
+ *   `http-request/*` leaves. The `_` prefix keeps this module out of the
+ *   generated package.json `exports` map (the `dist/**\/_*` ignore pattern in
+ *   `scripts/fix/generate-package-exports.mts` filters it out), so it is not
+ *   part of the public surface — it exists only as a re-export shim so existing
+ *   siblings keep working unchanged. New code should import the canonical
+ *   helpers directly:
+ *
+ *   - `getNodeCrypto` from `@socketsecurity/lib/node/crypto`
+ *   - `getNodeFs` from `@socketsecurity/lib/node/fs`
+ *   - `getNodeHttp` from `@socketsecurity/lib/node/http`
+ *   - `getNodeHttps` from `@socketsecurity/lib/node/https`
+ */
+export { getNodeCrypto as getCrypto } from '../node/crypto';
+export { getNodeFs as getFs } from '../node/fs';
+export { getNodeHttp as getHttp } from '../node/http';
+export { getNodeHttps as getHttps } from '../node/https';

package/dist/http-request/_internal.js

@@ -0,0 +1,39 @@
+"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 internal_exports = {};
+__export(internal_exports, {
+  getCrypto: () => import_crypto.getNodeCrypto,
+  getFs: () => import_fs.getNodeFs,
+  getHttp: () => import_http.getNodeHttp,
+  getHttps: () => import_https.getNodeHttps
+});
+module.exports = __toCommonJS(internal_exports);
+var import_crypto = require("../node/crypto");
+var import_fs = require("../node/fs");
+var import_http = require("../node/http");
+var import_https = require("../node/https");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getCrypto,
+  getFs,
+  getHttp,
+  getHttps
+});

package/dist/http-request/browser-fetch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file Thin wrapper over the global `fetch()` so tests can mock the network
+ *   layer via `vi.mock('@socketsecurity/lib/http-request/browser-fetch')`
+ *   without monkey-patching `globalThis.fetch` (which conflicts with the
+ *   project's nock-based test setup). The wrapper itself is `c8 ignore`-marked
+ *   because the body is a single uncoverable fetch call; coverage credit is
+ *   preserved by the wider test suite that mocks this module and asserts the
+ *   call shape.
+ */
+export declare function doFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/http-request/browser-fetch.js

@@ -0,0 +1,32 @@
+"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 browser_fetch_exports = {};
+__export(browser_fetch_exports, {
+  doFetch: () => doFetch
+});
+module.exports = __toCommonJS(browser_fetch_exports);
+function doFetch(input, init) {
+  return fetch(input, init);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  doFetch
+});

package/dist/http-request/browser.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @file Browser-safe HTTP request layer — mirrors the public surface of
+ *   `@socketsecurity/lib/http-request` (`httpJson`, `httpText`, `httpRequest`,
+ *   `HttpResponseError`) but uses the browser's `fetch` API instead of Node's
+ *   `node:https`. Designed for Chrome MV3 service workers, content scripts,
+ *   popups, and any other browser context that doesn't have `node:http` /
+ *   `node:https` / `node:stream`. Consumers import from
+ *   `@socketsecurity/lib/http-request/browser` directly, OR from
+ *   `@socketsecurity/lib/http-request` inside a bundler that resolves the
+ *   `browser` package.json conditional (rolldown, vite, esbuild) — the bundler
+ *   picks this entry automatically. API parity with the Node side is the goal —
+ *   same function names, same option shapes (where browsers can support them),
+ *   same error shape. Caveats:
+ *
+ *   - `HttpResponse.body` is `Uint8Array` here, vs Node's `Buffer`. Most callers
+ *     use `arrayBuffer()` / `text()` / `json()` and don't care.
+ *   - `HttpResponse.headers` is `Record<string, string>` here, vs Node's
+ *     `IncomingHttpHeaders` (which has array-valued headers like `set-cookie`).
+ *     Browser `fetch()` flattens repeated headers per spec.
+ *   - Hooks (`onRequest` / `onResponse`) are not yet supported in the browser
+ *     path. Add when needed.
+ */
+/**
+ * Browser-side HTTP error. Mirrors the Node-side `HttpResponseError` shape
+ * (same `.name`, same `.response.status/statusText` access pattern, same
+ * `instanceof` semantics) but constructs from a `BrowserHttpResponse` instead
+ * of a Node `HttpResponse`.
+ */
+export declare class HttpResponseError extends Error {
+    response: BrowserHttpResponse;
+    constructor(response: BrowserHttpResponse, message?: string | undefined);
+}
+/**
+ * Combine an external `signal` with an internal `timeout`-driven
+ * AbortController so either can cancel the in-flight fetch.
+ */
+export declare function combineSignals(external: AbortSignal | undefined, timeoutMs: number | undefined): {
+    signal: AbortSignal | undefined;
+    cleanup: () => void;
+};
+export declare function attempt(url: string, options: BrowserHttpRequestOptions): Promise<BrowserHttpResponse>;
+export declare function decodeText(bytes: Uint8Array): string;
+/**
+ * Per-attempt request info passed to `hooks.onRequest`. Mirrors the Node-side
+ * `HttpHookRequestInfo` shape so callers can share hook implementations.
+ */
+export interface BrowserHttpHookRequestInfo {
+    method: string;
+    url: string;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+}
+/**
+ * Per-attempt response info passed to `hooks.onResponse`. Either `status`
+ * (success) or `error` (network failure) is populated.
+ */
+export interface BrowserHttpHookResponseInfo {
+    method: string;
+    url: string;
+    duration: number;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    error?: Error | undefined;
+}
+export interface BrowserHttpHooks {
+    onRequest?: ((info: BrowserHttpHookRequestInfo) => void) | undefined;
+    onResponse?: ((info: BrowserHttpHookResponseInfo) => void) | undefined;
+}
+export interface BrowserHttpRequestOptions {
+    /**
+     * Request body. Strings, Blobs, FormData, ArrayBuffer all pass through to
+     * fetch unchanged. Objects are NOT auto-stringified — the convenience wrapper
+     * `httpJson` handles JSON serialization.
+     */
+    body?: string | Blob | FormData | ArrayBuffer | Uint8Array | undefined;
+    /**
+     * Whether to follow redirects automatically. Defaults to true (browser fetch
+     * default). Setting `false` sets `redirect: 'manual'` so 3xx responses are
+     * returned to the caller instead of followed.
+     */
+    followRedirects?: boolean | undefined;
+    /**
+     * Request headers. Object form for ergonomics; passed through to fetch.
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Lifecycle hooks for observing request/response events. Mirrors the
+     * Node-side `hooks` field. Hooks fire per-attempt — retries trigger separate
+     * hook calls.
+     */
+    hooks?: BrowserHttpHooks | undefined;
+    /**
+     * Maximum response body size in bytes. Responses larger than this are
+     * truncated and treated as a network failure (so retries can fire). Defaults
+     * to no limit. Useful when calling untrusted endpoints.
+     */
+    maxResponseSize?: number | undefined;
+    /**
+     * HTTP method. Defaults to GET.
+     */
+    method?: string | undefined;
+    /**
+     * Number of retry attempts on 5xx / network failure. Defaults to 0 (no
+     * retries).
+     */
+    retries?: number | undefined;
+    /**
+     * Base delay (ms) between retries. Doubles per attempt (exponential).
+     * Defaults to 250ms.
+     */
+    retryDelay?: number | undefined;
+    /**
+     * Abort signal forwarded to fetch. Combined with `timeout` via
+     * AbortController when both are present.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Throw on non-2xx response. Defaults to false; `httpJson` / `httpText` set
+     * this to true so callers don't have to check `.ok`.
+     */
+    throwOnError?: boolean | undefined;
+    /**
+     * Per-attempt timeout in milliseconds. Implemented via AbortController;
+     * exceeds the timeout aborts the fetch and the attempt counts as a network
+     * failure (retryable). Defaults to no timeout (fetch defaults).
+     */
+    timeout?: number | undefined;
+}
+/**
+ * Browser-shaped HTTP response. Surface mirrors the Node-side `HttpResponse`
+ * but with browser-native body types.
+ */
+export interface BrowserHttpResponse {
+    /**
+     * Raw response body. `Uint8Array` instead of Node's `Buffer`.
+     */
+    body: Uint8Array;
+    /**
+     * Response headers, lowercased keys (matching Node side's lowercase
+     * convention). Repeated headers are joined with `, ` per fetch spec.
+     */
+    headers: Record<string, string>;
+    /**
+     * Convenience: true when status is 2xx.
+     */
+    ok: boolean;
+    /**
+     * HTTP status code.
+     */
+    status: number;
+    /**
+     * HTTP status text.
+     */
+    statusText: string;
+    /**
+     * Final URL after any redirects.
+     */
+    url: string;
+    /**
+     * Body as ArrayBuffer.
+     */
+    arrayBuffer(): ArrayBuffer;
+    /**
+     * Body parsed as JSON. Throws on invalid JSON.
+     */
+    json<T = unknown>(): T;
+    /**
+     * Body decoded as UTF-8 text.
+     */
+    text(): string;
+}
+export declare function headersToRecord(headers: Headers): Record<string, string>;
+/**
+ * GET / POST a JSON endpoint. Automatically sets `Accept: application/json` and
+ * `Content-Type: application/json` (when a body is present). Throws
+ * `HttpResponseError` on non-2xx.
+ */
+export declare function httpJson<T = unknown>(url: string, options?: BrowserHttpRequestOptions | undefined): Promise<T>;
+/**
+ * Lower-level HTTP request. Use `httpJson` / `httpText` for the common cases.
+ * Returns the response unconditionally — callers inspect `.ok` or pass
+ * `throwOnError: true` to get a thrown `HttpResponseError` on non-2xx.
+ */
+export declare function httpRequest(url: string, options?: BrowserHttpRequestOptions | undefined): Promise<BrowserHttpResponse>;
+/**
+ * GET / POST a text endpoint. Throws `HttpResponseError` on non-2xx.
+ */
+export declare function httpText(url: string, options?: BrowserHttpRequestOptions | undefined): Promise<string>;
+export declare function sleep(ms: number): Promise<void>;