@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/github/types.d.ts

@@ -0,0 +1,277 @@
+/**
+ * @file Public type surface for `github/*` modules — pure interfaces. No I/O or
+ *   runtime side effects so this module stays cheap to import everywhere.
+ *   Constants live in `./constants`, named errors in `./errors`.
+ */
+/**
+ * Options for GitHub API fetch requests.
+ */
+export interface GitHubFetchOptions {
+    /**
+     * GitHub authentication token. If not provided, will attempt to use token
+     * from environment variables.
+     */
+    token?: string | undefined;
+    /**
+     * Additional HTTP headers to include in the request. Will be merged with
+     * default headers (Accept, User-Agent, Authorization).
+     */
+    headers?: Record<string, string> | undefined;
+}
+/**
+ * Error thrown when GitHub API rate limit is exceeded. Extends the standard
+ * Error with additional rate limit information.
+ */
+export interface GitHubRateLimitError extends Error {
+    /**
+     * HTTP status code (always 403 for rate limit errors)
+     */
+    status: number;
+    /**
+     * Date when the rate limit will reset. Undefined if reset time is not
+     * available in response headers.
+     */
+    resetTime?: Date | undefined;
+}
+/**
+ * GitHub ref object returned by the API. Represents a git reference (tag or
+ * branch).
+ */
+export interface GitHubRef {
+    /**
+     * The object this ref points to.
+     */
+    object: {
+        /**
+         * SHA of the commit or tag object.
+         */
+        sha: string;
+        /**
+         * Type of object ('commit' or 'tag')
+         */
+        type: string;
+        /**
+         * API URL to fetch the full object details.
+         */
+        url: string;
+    };
+    /**
+     * Full ref path (e.g., 'refs/tags/v1.0.0' or 'refs/heads/main')
+     */
+    ref: string;
+    /**
+     * API URL for this ref.
+     */
+    url: string;
+}
+/**
+ * GitHub annotated tag object returned by the API. Represents a git tag with
+ * metadata.
+ */
+export interface GitHubTag {
+    /**
+     * Tag annotation message.
+     */
+    message: string;
+    /**
+     * The commit this tag points to.
+     */
+    object: {
+        /**
+         * SHA of the commit.
+         */
+        sha: string;
+        /**
+         * Type of object (usually 'commit')
+         */
+        type: string;
+        /**
+         * API URL to fetch the commit details.
+         */
+        url: string;
+    };
+    /**
+     * SHA of this tag object itself.
+     */
+    sha: string;
+    /**
+     * Tag name (e.g., 'v1.0.0')
+     */
+    tag: string;
+    /**
+     * Information about who created the tag. Undefined for lightweight tags.
+     */
+    tagger?: {
+        /**
+         * Tag creation date in ISO 8601 format.
+         */
+        date: string;
+        /**
+         * Tagger's email address.
+         */
+        email: string;
+        /**
+         * Tagger's name.
+         */
+        name: string;
+    };
+    /**
+     * API URL for this tag object.
+     */
+    url: string;
+}
+/**
+ * GitHub commit object returned by the API. Represents a git commit with
+ * metadata.
+ */
+export interface GitHubCommit {
+    /**
+     * Full commit SHA.
+     */
+    sha: string;
+    /**
+     * API URL for this commit.
+     */
+    url: string;
+    /**
+     * Commit details.
+     */
+    commit: {
+        /**
+         * Commit message.
+         */
+        message: string;
+        /**
+         * Author information.
+         */
+        author: {
+            /**
+             * Commit author date in ISO 8601 format.
+             */
+            date: string;
+            /**
+             * Author's email address.
+             */
+            email: string;
+            /**
+             * Author's name.
+             */
+            name: string;
+        };
+    };
+}
+/**
+ * Options for resolving git refs to commit SHAs.
+ */
+export interface ResolveRefOptions {
+    /**
+     * GitHub authentication token. If not provided, will attempt to use token
+     * from environment variables.
+     */
+    token?: string | undefined;
+}
+/**
+ * GitHub Security Advisory (GHSA) details. Represents a complete security
+ * advisory from GitHub's database.
+ */
+export interface GhsaDetails {
+    /**
+     * GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
+     */
+    ghsaId: string;
+    /**
+     * Short summary of the vulnerability.
+     */
+    summary: string;
+    /**
+     * Detailed description of the vulnerability.
+     */
+    details: string;
+    /**
+     * Severity level ('low', 'moderate', 'high', 'critical')
+     */
+    severity: string;
+    /**
+     * Alternative identifiers (CVE IDs, etc.)
+     */
+    aliases: string[];
+    /**
+     * ISO 8601 timestamp when advisory was published.
+     */
+    publishedAt: string;
+    /**
+     * ISO 8601 timestamp when advisory was last updated.
+     */
+    updatedAt: string;
+    /**
+     * ISO 8601 timestamp when advisory was withdrawn. `null` if advisory is still
+     * active.
+     */
+    withdrawnAt: string | null;
+    /**
+     * External reference URLs for more information.
+     */
+    references: Array<{
+        url: string;
+    }>;
+    /**
+     * Affected packages and version ranges.
+     */
+    vulnerabilities: Array<{
+        /**
+         * Package information.
+         */
+        package: {
+            /**
+             * Ecosystem (e.g., 'npm', 'pip', 'maven')
+             */
+            ecosystem: string;
+            /**
+             * Package name.
+             */
+            name: string;
+        };
+        /**
+         * Version range expression for vulnerable versions.
+         */
+        vulnerableVersionRange: string;
+        /**
+         * First patched version that fixes the vulnerability. `null` if no patched
+         * version exists yet.
+         */
+        firstPatchedVersion: {
+            identifier: string;
+        } | null;
+    }>;
+    /**
+     * CVSS (Common Vulnerability Scoring System) information. `null` if CVSS
+     * score is not available.
+     */
+    cvss: {
+        /**
+         * CVSS score (0.0-10.0)
+         */
+        score: number;
+        /**
+         * CVSS vector string describing the vulnerability characteristics.
+         */
+        vectorString: string;
+    } | null;
+    /**
+     * CWE (Common Weakness Enumeration) categories.
+     */
+    cwes: Array<{
+        /**
+         * CWE identifier (e.g., 'CWE-79')
+         */
+        cweId: string;
+        /**
+         * Human-readable CWE name.
+         */
+        name: string;
+        /**
+         * Description of the weakness category.
+         */
+        description: string;
+    }>;
+}

package/dist/github/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/globs/_internal.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Private internals for `globs/*` modules — lazy module accessors,
+ *   normalization helpers, and the matcher LRU cache. The `defaultIgnore` list
+ *   lives in the public `defaults.ts` file; this file re-exports it so
+ *   co-located helpers can import everything through one path.
+ */
+import { defaultIgnore } from './defaults';
+import type * as fastGlobType from '../external/fast-glob';
+import type picomatchType from '../external/picomatch';
+export { defaultIgnore };
+export declare const MATCHER_CACHE_MAX_SIZE = 100;
+export declare const matcherCache: Map<string, (path: string) => boolean>;
+export { getNodeFs as getFs } from '../node/fs';
+export { getNodeFsPromises as getFsPromises } from '../node/fs-promises';
+export declare function getFastGlob(): typeof fastGlobType;
+export declare function getPicomatch(): typeof picomatchType;
+/**
+ * Glob results are normalized to forward slashes regardless of the backend
+ * (node:fs.glob returns native-OS separators on Windows; fast-glob already
+ * returns forward slashes). Single contract: callers don't have to think about
+ * separators per platform. Routes through `paths/normalize.normalizePath` so
+ * this stays consistent with every other path-shaped string in the lib.
+ */
+export declare function normalizeGlobResults(out: string[]): string[];
+/**
+ * Normalize a user-provided ignore array by running every entry through
+ * stripTrailingSlash. Returns undefined when `ignore` is not an array so
+ * callers can skip merging the option entirely.
+ *
+ * Uses a pre-sized for-loop instead of `.map`: socket-lib uses primordials (the
+ * prototype `Array.prototype.map` can be intercepted or replaced by user code
+ * at module load), and a hand-rolled loop is also marginally faster — no
+ * callback indirection, no growth of the result array.
+ */
+export declare function normalizeIgnorePatterns(ignore: unknown): string[] | undefined;
+/**
+ * Strip a trailing `/` from a glob pattern so fast-glob's deep filter matches
+ * it. See header comment in `glob.ts` for the full rationale — shortest
+ * summary: a `dist/` ignore pattern lets fast-glob walk the whole subtree
+ * before filtering, while `dist` (no slash) skips the walk entirely.
+ *
+ * CharCode 47 is `/`. Reading it that way avoids a per-call string allocation
+ * for the literal — primordials-friendly, no behavior change vs.
+ * `pattern.endsWith('/')`.
+ */
+export declare function stripTrailingSlash(pattern: string): string;

package/dist/globs/_internal.js

@@ -0,0 +1,96 @@
+"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, {
+  MATCHER_CACHE_MAX_SIZE: () => MATCHER_CACHE_MAX_SIZE,
+  defaultIgnore: () => import_defaults.defaultIgnore,
+  getFastGlob: () => getFastGlob,
+  getFs: () => import_fs.getNodeFs,
+  getFsPromises: () => import_fs_promises.getNodeFsPromises,
+  getPicomatch: () => getPicomatch,
+  matcherCache: () => matcherCache,
+  normalizeGlobResults: () => normalizeGlobResults,
+  normalizeIgnorePatterns: () => normalizeIgnorePatterns,
+  stripTrailingSlash: () => stripTrailingSlash
+});
+module.exports = __toCommonJS(internal_exports);
+var import_array = require("../primordials/array");
+var import_map_set = require("../primordials/map-set");
+var import_string = require("../primordials/string");
+var import_normalize = require("../paths/normalize");
+var import_defaults = require("./defaults");
+var import_fs = require("../node/fs");
+var import_fs_promises = require("../node/fs-promises");
+const MATCHER_CACHE_MAX_SIZE = 100;
+const matcherCache = new import_map_set.MapCtor();
+let _fastGlob;
+let _picomatch;
+// @__NO_SIDE_EFFECTS__
+function getFastGlob() {
+  if (_fastGlob === void 0) {
+    _fastGlob = require("../external/fast-glob.js");
+  }
+  return _fastGlob;
+}
+// @__NO_SIDE_EFFECTS__
+function getPicomatch() {
+  if (_picomatch === void 0) {
+    _picomatch = require("../external/picomatch.js");
+  }
+  return _picomatch;
+}
+function normalizeGlobResults(out) {
+  for (let i = 0; i < out.length; i += 1) {
+    out[i] = (0, import_normalize.normalizePath)(out[i]);
+  }
+  return out;
+}
+function normalizeIgnorePatterns(ignore) {
+  if (!(0, import_array.ArrayIsArray)(ignore)) {
+    return void 0;
+  }
+  const source = ignore;
+  const { length } = source;
+  const normalized = new import_array.ArrayCtor(length);
+  for (let i = 0; i < length; i++) {
+    normalized[i] = stripTrailingSlash(source[i]);
+  }
+  return normalized;
+}
+function stripTrailingSlash(pattern) {
+  if (pattern.length > 1 && (0, import_string.StringPrototypeCharCodeAt)(pattern, pattern.length - 1) === 47) {
+    return pattern.slice(0, -1);
+  }
+  return pattern;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MATCHER_CACHE_MAX_SIZE,
+  defaultIgnore,
+  getFastGlob,
+  getFs,
+  getFsPromises,
+  getPicomatch,
+  matcherCache,
+  normalizeGlobResults,
+  normalizeIgnorePatterns,
+  stripTrailingSlash
+});

package/dist/globs/defaults.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file The npm-packlist-derived `defaultIgnore` list. Public starting point
+ *   for caller-customized ignore arrays — also consumed internally by
+ *   `_internal` (matcher / stream callers fall back to this list when no
+ *   `ignore` option is supplied).
+ */
+export declare const defaultIgnore: readonly string[];

package/dist/globs/defaults.js

@@ -0,0 +1,61 @@
+"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 defaults_exports = {};
+__export(defaults_exports, {
+  defaultIgnore: () => defaultIgnore
+});
+module.exports = __toCommonJS(defaults_exports);
+var import_mutate = require("../objects/mutate");
+const defaultIgnore = (0, import_mutate.objectFreeze)([
+  // https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files
+  "**/.git",
+  "**/.npmrc",
+  "**/node_modules",
+  // https://github.com/npm/npm-packlist/blob/v10.0.0/lib/index.js#L15-L38
+  "**/.DS_Store",
+  "**/.gitignore",
+  "**/.hg",
+  "**/.lock-wscript",
+  "**/.npmignore",
+  "**/.svn",
+  "**/.wafpickle-*",
+  "**/.*.swp",
+  "**/._*/**",
+  "**/archived-packages/**",
+  "**/build/config.gypi",
+  "**/CVS",
+  "**/npm-debug.log",
+  "**/*.orig",
+  // Inline generic socket-registry .gitignore entries.
+  "**/.env",
+  "**/.eslintcache",
+  "**/.nvm",
+  "**/.tap",
+  "**/.vscode",
+  "**/*.tsbuildinfo",
+  "**/Thumbs.db",
+  // Inline additional ignores.
+  "**/bower_components"
+]);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defaultIgnore
+});

package/dist/globs/match.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file `glob` (async) and `globSync` — fast-glob wrappers with a
+ *   `node:fs.glob` fast-path when the option surface lines up.
+ *   `canUseNodeFsGlob` is the per-call gate. Trailing-slash workaround for
+ *   fast-glob ignore patterns
+ *   ───────────────────────────────────────────────────────── TL;DR: when you
+ *   pass `ignore: ['**\/dist/']` to fast-glob, the `dist` directory still gets
+ *   walked. Strip the trailing slash before passing it to fast-glob and the
+ *   ignore actually takes effect. Why this exists ─────────────── The gitignore
+ *   convention is to write directory entries with a trailing slash: `dist/`,
+ *   `node_modules/`, `coverage/`. Tools that translate gitignore lines into
+ *   glob patterns (including socket-cli's `globWithGitIgnore` helper,
+ *   npm-packlist, etc.) preserve that slash. fast-glob has TWO independent
+ *   filters that handle the trailing slash differently:
+ *
+ *   1. The DEEP filter decides whether to walk INTO a candidate directory. The
+ *      deep filter compiles `**\/dist/` into a regex that requires a trailing
+ *      slash on the input, but it tests `entryPath = 'dist'` (no slash, because
+ *      readdir entries don't include one). So fast-glob walks in anyway.
+ *   2. The ENTRY filter (post-walk) retries with a trailing slash appended for
+ *      directory entries — so it correctly excludes the results, but only AFTER
+ *      the entire subtree has been walked. Net effect: a `dist/` ignore pattern
+ *      correctly removes contents from the result array, but only after
+ *      walking. On a 300k-file `dist/` under tight memory this is the
+ *      difference between "instant" and "OOM kill". Stripping the trailing
+ *      slash makes it `**\/dist`, which both filters interpret correctly.
+ */
+import type { FastGlobOptions, Pattern } from './types';
+/**
+ * Whether the caller's option bag is fully expressible with `node:fs.glob`
+ * (`cwd` + `exclude`). Any other option means we must fall back to fast-glob,
+ * which exposes the wider surface.
+ *
+ * Exported for unit tests; not part of the public API.
+ *
+ * @internal
+ */
+export declare function canUseNodeFsGlob(options: FastGlobOptions | undefined): boolean;
+/**
+ * Asynchronously find files matching glob patterns.
+ *
+ * @example
+ *   ;```typescript
+ *   const files = await glob('src/*.ts', { cwd: '/tmp/project' })
+ *   console.log(files) // ['src/index.ts', 'src/utils.ts']
+ *   ```
+ */
+export declare function glob(patterns: Pattern | Pattern[], options?: FastGlobOptions): Promise<string[]>;
+/**
+ * Synchronously find files matching glob patterns. Wrapper around
+ * fast-glob.sync.
+ *
+ * @example
+ *   ;```typescript
+ *   const files = globSync('*.json', { cwd: '/tmp/project' })
+ *   console.log(files) // ['package.json', 'tsconfig.json']
+ *   ```
+ */
+export declare function globSync(patterns: Pattern | Pattern[], options?: FastGlobOptions): string[];

package/dist/globs/match.js

@@ -0,0 +1,84 @@
+"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 match_exports = {};
+__export(match_exports, {
+  canUseNodeFsGlob: () => canUseNodeFsGlob,
+  glob: () => glob,
+  globSync: () => globSync
+});
+module.exports = __toCommonJS(match_exports);
+var import_resolvers = require("../promises/resolvers");
+var import_internal = require("./_internal");
+function canUseNodeFsGlob(options) {
+  if (!options) {
+    return true;
+  }
+  for (const key of Object.keys(options)) {
+    if (key !== "cwd" && key !== "ignore") {
+      return false;
+    }
+  }
+  return true;
+}
+// @__NO_SIDE_EFFECTS__
+async function glob(patterns, options) {
+  const normalizedIgnore = (0, import_internal.normalizeIgnorePatterns)(options?.ignore);
+  if (canUseNodeFsGlob(options)) {
+    const out2 = await (0, import_resolvers.fromAsync)(
+      (0, import_internal.getFsPromises)().glob(patterns, {
+        ...options?.cwd ? { cwd: options.cwd } : {},
+        ...normalizedIgnore ? { exclude: normalizedIgnore } : {}
+      })
+    );
+    return (0, import_internal.normalizeGlobResults)(out2);
+  }
+  const fastGlob = (0, import_internal.getFastGlob)();
+  const out = await fastGlob.glob(patterns, {
+    ...options,
+    ...normalizedIgnore ? { ignore: normalizedIgnore } : {}
+  });
+  return (0, import_internal.normalizeGlobResults)(out);
+}
+// @__NO_SIDE_EFFECTS__
+function globSync(patterns, options) {
+  const normalizedIgnore = (0, import_internal.normalizeIgnorePatterns)(options?.ignore);
+  if (canUseNodeFsGlob(options)) {
+    return (0, import_internal.normalizeGlobResults)([
+      ...(0, import_internal.getFs)().globSync(patterns, {
+        ...options?.cwd ? { cwd: options.cwd } : {},
+        ...normalizedIgnore ? { exclude: normalizedIgnore } : {}
+      })
+    ]);
+  }
+  const fastGlob = (0, import_internal.getFastGlob)();
+  return (0, import_internal.normalizeGlobResults)(
+    fastGlob.globSync(patterns, {
+      ...options,
+      ...normalizedIgnore ? { ignore: normalizedIgnore } : {}
+    })
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  canUseNodeFsGlob,
+  glob,
+  globSync
+});