@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/github/constants.js

@@ -0,0 +1,36 @@
+"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 constants_exports = {};
+__export(constants_exports, {
+  DEFAULT_CACHE_TTL_MS: () => DEFAULT_CACHE_TTL_MS,
+  GITHUB_API_BASE_URL: () => GITHUB_API_BASE_URL,
+  GITHUB_GRAPHQL_URL: () => GITHUB_GRAPHQL_URL
+});
+module.exports = __toCommonJS(constants_exports);
+const GITHUB_API_BASE_URL = "https://api.github.com";
+const GITHUB_GRAPHQL_URL = "https://api.github.com/graphql";
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_CACHE_TTL_MS,
+  GITHUB_API_BASE_URL,
+  GITHUB_GRAPHQL_URL
+});

package/dist/github/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Named errors thrown by `github/*` helpers.
+ */
+/**
+ * Thrown by `fetchGitHub` when GitHub returns HTTP 200 OK with a zero-byte body
+ * — the "successful empty response" pattern.
+ *
+ * Why this exists (background for new contributors): GitHub's REST API has a
+ * documented failure mode that is _very_ easy to miss in code review. During
+ * incidents where the search / Elasticsearch backing index is degraded (see
+ * GitHub status pages with titles like "search is degraded" or "Pull Requests
+ * degraded"), the REST `/repos/...` GET endpoints return: - HTTP status: 200 OK
+ * ← looks like success - Body: "" ← but the payload is empty - Headers: no
+ * Retry-After, no rate-limit signal, nothing.
+ *
+ * Without a typed error, calling code does
+ * `JSON.parse(response.body.toString('utf8'))` on an empty string, which throws
+ * a confusing `SyntaxError: Unexpected end of JSON input`. That error has
+ * nothing to do with bad code on our side; it's GitHub's incident manifesting
+ * as a parse failure several frames deep. We surface the actual condition (`200
+ * \+ empty body`) as its own typed exception so the call path can either fall
+ * through to the GraphQL backend (which queries a different data path and uses
+ * a different backend and is unaffected by ES outages), or surface a clean
+ * message to the user.
+ *
+ * The HTTP status is hard-coded to 200 because that's _exactly_ what makes this
+ * insidious — a real 4xx/5xx would already be handled by the rate-limit /
+ * status-code branch above.
+ */
+export declare class GitHubEmptyBodyError extends Error {
+    /**
+     * HTTP status (always 200 — that's what makes this case insidious).
+     */
+    status: number;
+    constructor(url: string);
+}

package/dist/github/errors.js

@@ -0,0 +1,40 @@
+"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 errors_exports = {};
+__export(errors_exports, {
+  GitHubEmptyBodyError: () => GitHubEmptyBodyError
+});
+module.exports = __toCommonJS(errors_exports);
+class GitHubEmptyBodyError extends Error {
+  /**
+   * HTTP status (always 200 — that's what makes this case insidious).
+   */
+  status;
+  constructor(url) {
+    super(`GitHub API returned HTTP 200 with empty body: ${url}`);
+    this.name = "GitHubEmptyBodyError";
+    this.status = 200;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GitHubEmptyBodyError
+});

package/dist/github/fetch.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file Authenticated GitHub REST fetch. `fetchGitHub` is the single entry
+ *   point that the rest of the github/ modules go through for REST calls. It
+ *   handles four things the callers shouldn't have to repeat:
+ *
+ *   1. Token resolution (env → git config) when the caller doesn't pass an
+ *      explicit token.
+ *   2. Standard headers (Accept, User-Agent) merged with caller- supplied headers.
+ *   3. Rate-limit detection — when GitHub returns 403 with `x-ratelimit-remaining:
+ *      0`, throw a typed `GitHubRateLimitError` so callers can react (set
+ *      GITHUB_TOKEN, retry after reset).
+ *   4. Empty-body detection — 200 OK + zero-byte body is the documented incident
+ *      shape (see GitHubEmptyBodyError JSDoc). Raised as a typed error so the
+ *      ref / GHSA modules can fall back to GraphQL on a different backend.
+ *      `getGhsaUrl` lives here because it's the URL counterpart to the GHSA
+ *      fetch path — the only other consumer is the GHSA module.
+ */
+import type { GitHubFetchOptions } from './types';
+/**
+ * Fetch data from GitHub API with automatic authentication and rate limit
+ * handling. Makes authenticated requests to the GitHub REST API with proper
+ * error handling.
+ *
+ * Features: - Automatic token injection from environment if not provided - Rate
+ * limit detection with helpful error messages - Standard GitHub API headers
+ * (Accept, User-Agent) - JSON response parsing.
+ *
+ * @example
+ *   ```ts
+ *   // Fetch repository information
+ *   interface Repo {
+ *   name: string
+ *   full_name: string
+ *   default_branch: string
+ *   }
+ *   const repo = await fetchGitHub<Repo>(
+ *   'https://api.github.com/repos/owner/repo',
+ *   )
+ *   console.log(`Default branch: ${repo.default_branch}`)
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // With custom token and headers
+ *   const data = await fetchGitHub('https://api.github.com/user', {
+ *     token: 'ghp_customtoken',
+ *     headers: { 'X-Custom-Header': 'value' },
+ *   })
+ *   ```
+ *
+ * @example
+ *   ```ts
+ *   // Handle rate limit errors
+ *   try {
+ *   await fetchGitHub('https://api.github.com/repos/owner/repo')
+ *   } catch (e) {
+ *   if (e.status === 403 && e.resetTime) {
+ *   console.error(`Rate limited until ${e.resetTime}`)
+ *   }
+ *   }
+ *   ```
+ *
+ * @template T - Expected response type (defaults to `unknown`)
+ *
+ * @param url - Full GitHub API URL (e.g.,
+ *   'https://api.github.com/repos/owner/repo')
+ * @param options - Fetch options including token and custom headers.
+ *
+ * @returns Parsed JSON response of type `T`
+ *
+ * @throws {GitHubRateLimitError} When API rate limit is exceeded (status 403)
+ * @throws {Error} For other API errors with status code and message
+ */
+export declare function fetchGitHub<T = unknown>(url: string, options?: GitHubFetchOptions | undefined): Promise<T>;
+/**
+ * Generate GitHub Security Advisory URL from GHSA ID. Constructs the public
+ * advisory URL for a given GHSA identifier.
+ *
+ * @example
+ *   ;```ts
+ *   const url = getGhsaUrl('GHSA-1234-5678-90ab')
+ *   console.log(url) // 'https://github.com/advisories/GHSA-1234-5678-90ab'
+ *   ```
+ *
+ * @param ghsaId - GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
+ *
+ * @returns Full URL to the advisory page
+ */
+export declare function getGhsaUrl(ghsaId: string): string;

package/dist/github/fetch.js

@@ -0,0 +1,87 @@
+"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 fetch_exports = {};
+__export(fetch_exports, {
+  fetchGitHub: () => fetchGitHub,
+  getGhsaUrl: () => getGhsaUrl
+});
+module.exports = __toCommonJS(fetch_exports);
+var import_message = require("../errors/message");
+var import_request = require("../http-request/request");
+var import_date = require("../primordials/date");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_token = require("./token");
+var import_errors = require("./errors");
+async function fetchGitHub(url, options) {
+  const opts = { __proto__: null, ...options };
+  const token = opts.token || (0, import_token.getGitHubToken)();
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "socket-registry-github-client",
+    ...opts.headers
+  };
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const response = await (0, import_request.httpRequest)(url, { headers });
+  if (!response.ok) {
+    if (response.status === 403) {
+      const rateLimit = response.headers["x-ratelimit-remaining"];
+      const rateLimitStr = typeof rateLimit === "string" ? rateLimit : rateLimit?.[0];
+      if (rateLimitStr === "0") {
+        const resetTime = response.headers["x-ratelimit-reset"];
+        const resetTimeStr = typeof resetTime === "string" ? resetTime : resetTime?.[0];
+        const resetDate = resetTimeStr ? new import_date.DateCtor(Number(resetTimeStr) * 1e3) : void 0;
+        const error = new import_error.ErrorCtor(
+          `GitHub API rate limit exceeded${resetDate ? `. Resets at ${resetDate.toLocaleString()}` : ""}. Use GITHUB_TOKEN environment variable to increase rate limit.`
+        );
+        error.status = 403;
+        error.resetTime = resetDate;
+        throw error;
+      }
+    }
+    throw new import_error.ErrorCtor(
+      `GitHub API error ${response.status}: ${response.statusText}`
+    );
+  }
+  if (response.body.byteLength === 0) {
+    throw new import_errors.GitHubEmptyBodyError(url);
+  }
+  try {
+    return (0, import_json.JSONParse)(response.body.toString("utf8"));
+  } catch (e) {
+    throw new import_error.ErrorCtor(
+      `Failed to parse GitHub API response: ${(0, import_message.errorMessage)(e)}
+URL: ${url}
+Response may be malformed or incomplete.`,
+      { cause: e }
+    );
+  }
+}
+function getGhsaUrl(ghsaId) {
+  return `https://github.com/advisories/${ghsaId}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchGitHub,
+  getGhsaUrl
+});

package/dist/github/ghsa.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @file GitHub Security Advisory (GHSA) lookups. Three layers, narrowest first:
+ *
+ *   - `cacheFetchGhsa` — caches GHSA fetches in the same `TtlCache` used by ref
+ *     resolution (5-minute TTL, two-tier).
+ *   - `fetchGhsaDetails` — REST `/advisories/:id` with the same empty-body
+ *     fallback to GraphQL that ref resolution uses.
+ *   - `fetchGhsaDetailsViaGraphQL` — GraphQL `securityAdvisory(...)` with shape
+ *     normalization back to the REST surface so callers don't have to know
+ *     which transport ran.
+ */
+import type { GhsaDetails, GitHubFetchOptions } from './types';
+/**
+ * Fetch GitHub Security Advisory details with caching. Retrieves advisory
+ * information with two-tier caching (in-memory + persistent). Cached results
+ * are stored with the default TTL (5 minutes).
+ *
+ * Caching behavior:
+ *
+ * - Checks in-memory cache first for immediate response
+ * - Falls back to persistent disk cache if not in memory
+ * - Fetches from API only if not cached
+ * - Stores result in both cache tiers
+ * - Respects `DISABLE_GITHUB_CACHE` env var
+ *
+ * @example
+ *   ;```ts
+ *   // First call hits API
+ *   const advisory = await cacheFetchGhsa('GHSA-1234-5678-90ab')
+ *
+ *   // Second call within 5 minutes returns cached data
+ *   const cached = await cacheFetchGhsa('GHSA-1234-5678-90ab')
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // Disable caching for fresh data
+ *   process.env.DISABLE_GITHUB_CACHE = '1'
+ *   const advisory = await cacheFetchGhsa('GHSA-xxxx-yyyy-zzzz')
+ *   ```
+ *
+ * @param ghsaId - GHSA identifier to fetch.
+ * @param options - Fetch options including authentication token.
+ *
+ * @returns Complete advisory details
+ *
+ * @throws {Error} If advisory cannot be found or API request fails
+ * @throws {GitHubRateLimitError} When API rate limit is exceeded
+ */
+export declare function cacheFetchGhsa(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;
+/**
+ * Fetch GitHub Security Advisory details from the API. Retrieves complete
+ * advisory information including severity, affected packages, CVSS scores, and
+ * CWE classifications.
+ *
+ * @example
+ *   ```ts
+ *   const advisory = await fetchGhsaDetails('GHSA-1234-5678-90ab')
+ *   console.log(`Severity: ${advisory.severity}`)
+ *   console.log(`Affects: ${advisory.vulnerabilities.length} packages`)
+ *   if (advisory.cvss) {
+ *   console.log(`CVSS Score: ${advisory.cvss.score}`)
+ *   }
+ *   ```
+ *
+ * @example
+ *   ```ts
+ *   // Check if vulnerability is patched
+ *   const advisory = await fetchGhsaDetails('GHSA-xxxx-yyyy-zzzz')
+ *   for (const vuln of advisory.vulnerabilities) {
+ *   if (vuln.firstPatchedVersion) {
+ *   console.log(
+ *   `Patched in ${vuln.package.name}@${vuln.firstPatchedVersion.identifier}`,
+ *   )
+ *   }
+ *   }
+ *   ```
+ *
+ * @param ghsaId - GHSA identifier to fetch (e.g., 'GHSA-xxxx-yyyy-zzzz')
+ * @param options - Fetch options including authentication token.
+ *
+ * @returns Complete advisory details with normalized field names
+ *
+ * @throws {Error} If advisory cannot be found or API request fails
+ * @throws {GitHubRateLimitError} When API rate limit is exceeded
+ */
+export declare function fetchGhsaDetails(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;
+/**
+ * GraphQL counterpart for `fetchGhsaDetails`.
+ *
+ * What it does: Queries the GraphQL `securityAdvisory(ghsaId)` connection and
+ * reshapes the response to match the REST `/advisories/:id` JSON so callers
+ * don't have to know which transport ran.
+ *
+ * Three normalizations the REST shape differs from GraphQL on:
+ *
+ * 1. Severity case REST returns lowercase strings like "moderate", "high". GraphQL
+ *    returns SCREAMING_CASE enum values: "MODERATE", "HIGH", "CRITICAL". We
+ *    `.toLowerCase()` so callers can compare against a single canonical form.
+ * 2. Identifiers vs. aliases REST has an `aliases: ["CVE-2024-..."]` array — a
+ *    flat list of non-GHSA IDs (CVEs, etc.) for the same vulnerability. GraphQL
+ *    has `identifiers: [{type, value}]` which INCLUDES the advisory's own GHSA
+ *    id alongside CVE ids. We filter out the GHSA self-reference so the list
+ *    matches REST.
+ * 3. Connection wrapping GraphQL wraps array fields in `{ nodes: [...] }`
+ *    connection objects (it's how pagination works in GraphQL). REST returns
+ *    plain arrays. We unwrap with `?.nodes ?? []`.
+ *
+ * `description` (GraphQL) maps to `details` (REST) — same data, different field
+ * name. The mapping below renames it.
+ *
+ * Token handling: We re-derive the token from `options.token ||
+ * getGitHubToken()` because this function may be called from places that didn't
+ * thread an explicit token through. GraphQL queries to private data require
+ * auth even when the equivalent REST GET works anonymously, so the auth header
+ * is mandatory in practice.
+ */
+export declare function fetchGhsaDetailsViaGraphQL(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;

package/dist/github/ghsa.js

@@ -0,0 +1,178 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ghsa_exports = {};
+__export(ghsa_exports, {
+  cacheFetchGhsa: () => cacheFetchGhsa,
+  fetchGhsaDetails: () => fetchGhsaDetails,
+  fetchGhsaDetailsViaGraphQL: () => fetchGhsaDetailsViaGraphQL
+});
+module.exports = __toCommonJS(ghsa_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_request = require("../http-request/request");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_fetch = require("./fetch");
+var import_refs = require("./refs");
+var import_token = require("./token");
+var import_constants = require("./constants");
+var import_errors = require("./errors");
+async function cacheFetchGhsa(ghsaId, options) {
+  const cache = (0, import_refs.getGithubCache)();
+  const key = `ghsa:${ghsaId}`;
+  if (import_node_process.default.env["DISABLE_GITHUB_CACHE"]) {
+    return await fetchGhsaDetails(ghsaId, options);
+  }
+  return await cache.getOrFetch(key, async () => {
+    return await fetchGhsaDetails(ghsaId, options);
+  });
+}
+async function fetchGhsaDetails(ghsaId, options) {
+  const url = `https://api.github.com/advisories/${ghsaId}`;
+  try {
+    const data = await (0, import_fetch.fetchGitHub)(url, options);
+    return {
+      ghsaId: data.ghsa_id,
+      summary: data.summary,
+      details: data.details,
+      severity: data.severity,
+      aliases: data.aliases || [],
+      publishedAt: data.published_at,
+      updatedAt: data.updated_at,
+      withdrawnAt: data.withdrawn_at,
+      references: data.references || [],
+      vulnerabilities: data.vulnerabilities || [],
+      cvss: data.cvss,
+      cwes: data.cwes || []
+    };
+  } catch (e) {
+    if (e instanceof import_errors.GitHubEmptyBodyError) {
+      try {
+        return await fetchGhsaDetailsViaGraphQL(ghsaId, options);
+      } catch (cause) {
+        throw new import_error.ErrorCtor(
+          `Failed to fetch advisory ${ghsaId}: both REST and GraphQL backends degraded`,
+          { cause }
+        );
+      }
+    }
+    throw e;
+  }
+}
+async function fetchGhsaDetailsViaGraphQL(ghsaId, options) {
+  const opts = { __proto__: null, ...options };
+  const token = opts.token || (0, import_token.getGitHubToken)();
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "Content-Type": "application/json",
+    "User-Agent": "socket-registry-github-client",
+    ...opts.headers
+  };
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const query = `query($ghsaId: String!) {
+    securityAdvisory(ghsaId: $ghsaId) {
+      ghsaId
+      summary
+      description
+      severity
+      publishedAt
+      updatedAt
+      withdrawnAt
+      cvss { score vectorString }
+      cwes(first: 50) { nodes { cweId name description } }
+      references { url }
+      vulnerabilities(first: 100) {
+        nodes {
+          package { ecosystem name }
+          vulnerableVersionRange
+          firstPatchedVersion { identifier }
+        }
+      }
+      identifiers { type value }
+    }
+  }`;
+  const response = await (0, import_request.httpRequest)(import_constants.GITHUB_GRAPHQL_URL, {
+    body: (0, import_json.JSONStringify)({ query, variables: { ghsaId } }),
+    headers,
+    method: "POST"
+  });
+  if (!response.ok) {
+    throw new import_error.ErrorCtor(
+      `GitHub GraphQL API error ${response.status}: ${response.statusText}`
+    );
+  }
+  if (response.body.byteLength === 0) {
+    throw new import_errors.GitHubEmptyBodyError(import_constants.GITHUB_GRAPHQL_URL);
+  }
+  let parsed;
+  try {
+    parsed = (0, import_json.JSONParse)(response.body.toString("utf8"));
+  } catch (cause) {
+    throw new import_error.ErrorCtor(
+      `Failed to parse GitHub GraphQL response for advisory ${ghsaId}`,
+      { cause }
+    );
+  }
+  if (parsed.errors?.length) {
+    throw new import_error.ErrorCtor(
+      `GraphQL securityAdvisory(${ghsaId}) returned errors: ${parsed.errors.map((e) => e.message).join("; ")}`
+    );
+  }
+  const adv = parsed.data?.securityAdvisory;
+  if (!adv) {
+    throw new import_error.ErrorCtor(`GHSA ${ghsaId} not found`);
+  }
+  return {
+    ghsaId: adv.ghsaId,
+    summary: adv.summary,
+    details: adv.description,
+    severity: adv.severity.toLowerCase(),
+    aliases: adv.identifiers?.filter((i) => i.type !== "GHSA").map((i) => i.value) ?? [],
+    publishedAt: adv.publishedAt,
+    updatedAt: adv.updatedAt,
+    withdrawnAt: adv.withdrawnAt ?? "",
+    references: adv.references ?? [],
+    vulnerabilities: adv.vulnerabilities?.nodes ?? [],
+    // GhsaDetails.cvss is typed `... | null` to match the REST
+    // `/advisories/:id` shape. Preserving `null` here is the external-
+    // API-contract exception called out in the lint rule docs.
+    // oxlint-disable-next-line socket/prefer-undefined-over-null
+    cvss: adv.cvss ?? null,
+    cwes: adv.cwes?.nodes ?? []
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cacheFetchGhsa,
+  fetchGhsaDetails,
+  fetchGhsaDetailsViaGraphQL
+});

package/dist/github/refs-cache.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file TtlCache singleton for github/refs. Split out of `github/refs.ts` for
+ *   size hygiene. Owns the lazy `_githubCache` slot, the accessor
+ *   (`getGithubCache`), and the in-memory-only clear (`clearRefCache`). Caching
+ *   strategy:
+ *
+ *   - In-memory cache (Map) for immediate lookups
+ *   - Persistent disk cache (cacache) for durability across runs
+ *   - Default TTL: 5 minutes
+ *   - Disable everything with the `DISABLE_GITHUB_CACHE` env var
+ */
+import type { TtlCache } from '../cache/ttl/types';
+/**
+ * Clear the ref resolution cache (in-memory only). Clears the in-memory
+ * memoization cache without affecting the persistent disk cache. Useful for
+ * testing or when you need fresh data from the API.
+ *
+ * Note: This only clears the in-memory cache. The persistent cacache storage
+ * remains intact and will be used to rebuild the in-memory cache on next
+ * access.
+ *
+ * @example
+ *   ;```ts
+ *   // Clear cache to force fresh API calls
+ *   await clearRefCache()
+ *   const sha = await resolveRefToSha('owner', 'repo', 'main')
+ *   // This will hit the persistent cache or API, not in-memory cache
+ *   ```
+ *
+ * @returns Promise that resolves when cache is cleared
+ */
+export declare function clearRefCache(): Promise<void>;
+/**
+ * Get or create the GitHub cache instance. Lazy initializes the cache with
+ * default TTL and memoization enabled. Used internally for caching GitHub API
+ * responses.
+ *
+ * @returns The singleton cache instance
+ */
+export declare function getGithubCache(): TtlCache;

package/dist/github/refs-cache.js

@@ -0,0 +1,49 @@
+"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 refs_cache_exports = {};
+__export(refs_cache_exports, {
+  clearRefCache: () => clearRefCache,
+  getGithubCache: () => getGithubCache
+});
+module.exports = __toCommonJS(refs_cache_exports);
+var import_store = require("../cache/ttl/store");
+var import_constants = require("./constants");
+let _githubCache;
+async function clearRefCache() {
+  if (_githubCache) {
+    await _githubCache.clear({ memoOnly: true });
+  }
+}
+function getGithubCache() {
+  if (_githubCache === void 0) {
+    _githubCache = (0, import_store.createTtlCache)({
+      memoize: true,
+      prefix: "github-refs",
+      ttl: import_constants.DEFAULT_CACHE_TTL_MS
+    });
+  }
+  return _githubCache;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearRefCache,
+  getGithubCache
+});