@socketsecurity/lib 5.28.0 → 6.0.1

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

@@ -0,0 +1,42 @@
+/**
+ * @file Resolve a GitHub git ref via GraphQL. Split out of `github/refs.ts` for
+ *   size hygiene. The fallback the REST tier-cascade calls when it detects the
+ *   documented "200 + empty body" incident shape — GraphQL hits a different
+ *   backend at GitHub (not the same Elasticsearch index as REST listings) and
+ *   stays consistent through those incidents.
+ */
+import type { GitHubFetchOptions } from './types';
+/**
+ * Resolve a ref to its commit SHA via GraphQL.
+ *
+ * Why this function exists: This is the fallback that `fetchRefSha` calls when
+ * the REST tier-cascade detects the "GitHub returned 200 + empty body" incident
+ * shape. GraphQL hits a different backend than REST listings, so it stays
+ * consistent through the kinds of incidents that produce empty REST responses.
+ *
+ * What it does: The REST cascade needs three separate calls (tag, branch,
+ * commit) because REST has no single "resolve any ref" endpoint. GraphQL DOES —
+ * `Repository.ref(qualifiedName)` resolves tags AND branches by their
+ * fully-qualified name, and `Repository.object(oid)` resolves a raw commit SHA.
+ * We bundle all three into ONE query using GraphQL aliases (`tagRef`,
+ * `branchRef`, `commit`) and pick whichever resolved.
+ *
+ * Annotated vs lightweight tags: In Git, a "lightweight tag" is just a name
+ * that points directly at a commit. An "annotated tag" is a separate object
+ * (with tagger info, message, etc.) that itself points at the commit. GraphQL's
+ * `Tag.target` field gives us the commit SHA for annotated tags in one shot —
+ * REST needs a _second_ HTTP call to dereference. The `... on Tag { target {
+ * oid } }` / `... on Commit { oid }` inline-fragments handle both shapes.
+ *
+ * Return contract:
+ *
+ * - Returns the SHA string when any form matches.
+ * - Returns `undefined` when the ref genuinely doesn't exist as a tag, branch, OR
+ *   commit. The caller treats `undefined` the same as "REST cascade also
+ *   failed" — a real "ref not found".
+ * - Returns `undefined` (not throws) on transport-level failures too: non-OK
+ *   HTTP, empty GraphQL body, or JSON parse error. The REST cascade's "ref not
+ *   found" message is more useful to the end user than a GraphQL transport
+ *   error.
+ */
+export declare function fetchRefShaViaGraphQL(owner: string, repo: string, ref: string, options: GitHubFetchOptions): Promise<string | undefined>;

package/dist/github/refs-graphql.js

@@ -0,0 +1,109 @@
+"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_graphql_exports = {};
+__export(refs_graphql_exports, {
+  fetchRefShaViaGraphQL: () => fetchRefShaViaGraphQL
+});
+module.exports = __toCommonJS(refs_graphql_exports);
+var import_request = require("../http-request/request");
+var import_json = require("../primordials/json");
+var import_token = require("./token");
+var import_constants = require("./constants");
+async function fetchRefShaViaGraphQL(owner, repo, ref, options) {
+  const token = options.token || (0, import_token.getGitHubToken)();
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "Content-Type": "application/json",
+    "User-Agent": "socket-registry-github-client",
+    ...options.headers
+  };
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const query = `query($owner: String!, $repo: String!, $tag: String!, $branch: String!, $oid: GitObjectID!) {
+    repository(owner: $owner, name: $repo) {
+      tagRef: ref(qualifiedName: $tag) {
+        target {
+          __typename
+          ... on Tag { target { oid } }
+          ... on Commit { oid }
+        }
+      }
+      branchRef: ref(qualifiedName: $branch) {
+        target { oid }
+      }
+      commit: object(oid: $oid) {
+        __typename
+        ... on Commit { oid }
+      }
+    }
+  }`;
+  const looksLikeSha = /^[a-f0-9]{40}$/i.test(ref);
+  const oidArg = looksLikeSha ? ref : "0000000000000000000000000000000000000000";
+  const response = await (0, import_request.httpRequest)(import_constants.GITHUB_GRAPHQL_URL, {
+    body: (0, import_json.JSONStringify)({
+      query,
+      variables: {
+        branch: `refs/heads/${ref}`,
+        oid: oidArg,
+        owner,
+        repo,
+        tag: `refs/tags/${ref}`
+      }
+    }),
+    headers,
+    method: "POST"
+  });
+  if (!response.ok || response.body.byteLength === 0) {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = (0, import_json.JSONParse)(response.body.toString("utf8"));
+  } catch {
+    return void 0;
+  }
+  const repoData = parsed.data?.repository;
+  if (!repoData) {
+    return void 0;
+  }
+  const tagTarget = repoData.tagRef?.target;
+  if (tagTarget) {
+    if (tagTarget.__typename === "Tag") {
+      return tagTarget.target?.oid ?? void 0;
+    }
+    if (tagTarget.__typename === "Commit") {
+      return tagTarget.oid ?? void 0;
+    }
+  }
+  const branchOid = repoData.branchRef?.target?.oid;
+  if (branchOid) {
+    return branchOid;
+  }
+  if (repoData.commit?.__typename === "Commit" && repoData.commit.oid) {
+    return repoData.commit.oid;
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchRefShaViaGraphQL
+});

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

@@ -0,0 +1,23 @@
+/**
+ * @file Resolve a GitHub git ref via REST tier-cascade. Split out of
+ *   `github/refs.ts` for size hygiene. Walks tag → branch → commit endpoints in
+ *   sequence; the first 200 OK wins. If any tier hits the documented
+ *   200-OK-empty-body incident shape, falls back to the GraphQL transport in
+ *   `./refs-graphql`.
+ */
+import type { ResolveRefOptions } from './types';
+/**
+ * Fetch the SHA for a git ref from GitHub API. Internal helper that implements
+ * the multi-strategy ref resolution logic. Tries tags, branches, and direct
+ * commit lookups in sequence.
+ *
+ * @param owner - Repository owner.
+ * @param repo - Repository name.
+ * @param ref - Git reference to resolve.
+ * @param options - Resolution options with authentication token.
+ *
+ * @returns The full commit SHA
+ *
+ * @throws {Error} When ref cannot be resolved after all strategies fail
+ */
+export declare function fetchRefSha(owner: string, repo: string, ref: string, options: ResolveRefOptions): Promise<string>;

package/dist/github/refs-rest.js

@@ -0,0 +1,104 @@
+"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_rest_exports = {};
+__export(refs_rest_exports, {
+  fetchRefSha: () => fetchRefSha
+});
+module.exports = __toCommonJS(refs_rest_exports);
+var import_message = require("../errors/message");
+var import_error = require("../primordials/error");
+var import_fetch = require("./fetch");
+var import_refs_graphql = require("./refs-graphql");
+var import_constants = require("./constants");
+var import_errors = require("./errors");
+async function fetchRefSha(owner, repo, ref, options) {
+  const fetchOptions = {
+    token: options.token
+  };
+  let sawEmptyBody = false;
+  const note404 = (e) => {
+    if (e instanceof import_errors.GitHubEmptyBodyError) {
+      sawEmptyBody = true;
+    }
+    return e;
+  };
+  try {
+    const tagUrl = `${import_constants.GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/tags/${ref}`;
+    const tagData = await (0, import_fetch.fetchGitHub)(tagUrl, fetchOptions);
+    if (tagData.object.type === "tag") {
+      const tagObject = await (0, import_fetch.fetchGitHub)(
+        tagData.object.url,
+        fetchOptions
+      );
+      return tagObject.object.sha;
+    }
+    return tagData.object.sha;
+  } catch (e) {
+    note404(e);
+    try {
+      const branchUrl = `${import_constants.GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/heads/${ref}`;
+      const branchData = await (0, import_fetch.fetchGitHub)(branchUrl, fetchOptions);
+      return branchData.object.sha;
+    } catch (e2) {
+      note404(e2);
+      try {
+        const commitUrl = `${import_constants.GITHUB_API_BASE_URL}/repos/${owner}/${repo}/commits/${ref}`;
+        const commitData = await (0, import_fetch.fetchGitHub)(
+          commitUrl,
+          fetchOptions
+        );
+        return commitData.sha;
+      } catch (e3) {
+        note404(e3);
+        if (sawEmptyBody) {
+          let graphqlSha;
+          let graphqlErr;
+          try {
+            graphqlSha = await (0, import_refs_graphql.fetchRefShaViaGraphQL)(
+              owner,
+              repo,
+              ref,
+              fetchOptions
+            );
+          } catch (cause) {
+            graphqlErr = cause;
+          }
+          if (graphqlSha) {
+            return graphqlSha;
+          }
+          if (graphqlErr !== void 0) {
+            throw new import_error.ErrorCtor(
+              `Failed to resolve ref "${ref}" for ${owner}/${repo}: both REST and GraphQL backends degraded`,
+              { cause: graphqlErr }
+            );
+          }
+        }
+        throw new import_error.ErrorCtor(
+          `Failed to resolve ref "${ref}" for ${owner}/${repo}: ${(0, import_message.errorMessage)(e3)}`
+        );
+      }
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchRefSha
+});

package/dist/github/refs.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file Resolve GitHub git refs (tag / branch / commit) to full commit SHAs.
+ *   Two-tier strategy with cross-backend fallback:
+ *
+ *   1. REST cascade (`fetchRefSha`): tag → branch → commit. The first 200 OK wins.
+ *   2. GraphQL fallback (`fetchRefShaViaGraphQL`): fires only when the REST
+ *      cascade hits the documented 200-OK-empty-body incident shape. GraphQL
+ *      queries hit a different backend at GitHub, so it stays consistent
+ *      through Elasticsearch outages that produce empty REST bodies. Caching: a
+ *      `TtlCache` keyed by `${owner}/${repo}@${ref}` with a 5-minute TTL plus
+ *      in-memory memoization. `clearRefCache()` clears the in-memory tier; the
+ *      persistent disk tier survives so the cache warms quickly on the next
+ *      run. Disable everything with the `DISABLE_GITHUB_CACHE` env var. Module
+ *      shape: this file holds the public `resolveRefToSha` entry point.
+ *      Supporting surface lives in sibling leaves and is re-exported here so
+ *      existing `github/refs` importers keep working unchanged:
+ *
+ *   - REST tier cascade — `./refs-rest`
+ *   - GraphQL fallback — `./refs-graphql`
+ *   - TtlCache singleton + clearRefCache — `./refs-cache`
+ */
+import type { ResolveRefOptions } from './types';
+/**
+ * Resolve a git ref (tag, branch, or commit SHA) to its full commit SHA.
+ * Handles tags (annotated and lightweight), branches, and commit SHAs. Results
+ * are cached in-memory and on disk (with TTL) to minimize API calls.
+ *
+ * Resolution strategy:
+ *
+ * 1. Try as a tag (refs/tags/{ref})
+ * 2. If tag is annotated, dereference to get the commit SHA
+ * 3. If not a tag, try as a branch (refs/heads/{ref})
+ * 4. If not a branch, try as a commit SHA directly
+ *
+ * Caching behavior:
+ *
+ * - In-memory cache (Map) for immediate lookups
+ * - Persistent disk cache (cacache) for durability across runs
+ * - Default TTL: 5 minutes
+ * - Disable caching with `DISABLE_GITHUB_CACHE` env var
+ *
+ * @example
+ *   ;```ts
+ *   // Resolve a tag to commit SHA
+ *   const sha = await resolveRefToSha('owner', 'repo', 'v1.0.0')
+ *   console.log(sha) // 'a1b2c3d4e5f6...'
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // Resolve a branch to latest commit SHA
+ *   const sha = await resolveRefToSha('owner', 'repo', 'main')
+ *   console.log(sha) // Latest commit on main branch
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // Resolve with custom token
+ *   const sha = await resolveRefToSha('owner', 'repo', 'develop', {
+ *     token: 'ghp_customtoken',
+ *   })
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // Commit SHA passes through unchanged (but validates it exists)
+ *   const sha = await resolveRefToSha('owner', 'repo', 'a1b2c3d4')
+ *   console.log(sha) // Full 40-char SHA
+ *   ```
+ *
+ * @param owner - Repository owner (user or organization name)
+ * @param repo - Repository name.
+ * @param ref - Git reference to resolve (tag name, branch name, or commit SHA)
+ * @param options - Resolution options including authentication token.
+ *
+ * @returns The full commit SHA (40-character hex string)
+ *
+ * @throws {Error} When ref cannot be resolved after trying all strategies
+ * @throws {GitHubRateLimitError} When API rate limit is exceeded
+ */
+export declare function resolveRefToSha(owner: string, repo: string, ref: string, options?: ResolveRefOptions | undefined): Promise<string>;
+export { clearRefCache, getGithubCache } from './refs-cache';
+export { fetchRefShaViaGraphQL } from './refs-graphql';
+export { fetchRefSha } from './refs-rest';

package/dist/github/refs.js

@@ -0,0 +1,67 @@
+"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 refs_exports = {};
+__export(refs_exports, {
+  clearRefCache: () => import_refs_cache2.clearRefCache,
+  fetchRefSha: () => import_refs_rest2.fetchRefSha,
+  fetchRefShaViaGraphQL: () => import_refs_graphql.fetchRefShaViaGraphQL,
+  getGithubCache: () => import_refs_cache2.getGithubCache,
+  resolveRefToSha: () => resolveRefToSha
+});
+module.exports = __toCommonJS(refs_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_refs_rest = require("./refs-rest");
+var import_refs_cache = require("./refs-cache");
+var import_refs_cache2 = require("./refs-cache");
+var import_refs_graphql = require("./refs-graphql");
+var import_refs_rest2 = require("./refs-rest");
+async function resolveRefToSha(owner, repo, ref, options) {
+  const opts = {
+    __proto__: null,
+    ...options
+  };
+  const cacheKey = `${owner}/${repo}@${ref}`;
+  if (import_node_process.default.env["DISABLE_GITHUB_CACHE"]) {
+    return await (0, import_refs_rest.fetchRefSha)(owner, repo, ref, opts);
+  }
+  const cache = (0, import_refs_cache.getGithubCache)();
+  return await cache.getOrFetch(cacheKey, async () => {
+    return await (0, import_refs_rest.fetchRefSha)(owner, repo, ref, opts);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearRefCache,
+  fetchRefSha,
+  fetchRefShaViaGraphQL,
+  getGithubCache,
+  resolveRefToSha
+});

package/dist/github/token.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file GitHub token resolution. Three sources, in priority order: environment
+ *   variables, then `git config github.token`. The combined fallback
+ *   (`getGitHubTokenWithFallback`) is what most callers want; the individual
+ *   helpers exist so callers can constrain the search (e.g., env-only contexts
+ *   where shelling out to git would be wrong).
+ */
+import type { SpawnOptions } from '../process/spawn/types';
+/**
+ * Get GitHub authentication token from environment variables. Checks multiple
+ * environment variable names in priority order.
+ *
+ * Environment variables checked (in order):
+ *
+ * 1. `GITHUB_TOKEN` - Standard GitHub token variable
+ * 2. `GH_TOKEN` - Alternative GitHub CLI token variable
+ * 3. `SOCKET_CLI_GITHUB_TOKEN` - Socket-specific token variable
+ *
+ * @example
+ *   ;```ts
+ *   const token = getGitHubToken()
+ *   if (!token) {
+ *     console.warn('No GitHub token found')
+ *   }
+ *   ```
+ *
+ * @returns The first available GitHub token, or `undefined` if none found
+ */
+export declare function getGitHubToken(): string | undefined;
+/**
+ * Get GitHub authentication token from git config. Reads the `github.token`
+ * configuration value from git config. This is a fallback method when
+ * environment variables don't contain a token.
+ *
+ * @example
+ *   ;```ts
+ *   const token = await getGitHubTokenFromGitConfig()
+ *   if (token) {
+ *     console.log('Found token in git config')
+ *   }
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // With custom working directory
+ *   const token = await getGitHubTokenFromGitConfig({
+ *     cwd: '/path/to/repo',
+ *   })
+ *   ```
+ *
+ * @param options - Spawn options for git command execution.
+ *
+ * @returns GitHub token from git config, or `undefined` if not configured
+ */
+export declare function getGitHubTokenFromGitConfig(options?: SpawnOptions | undefined): Promise<string | undefined>;
+/**
+ * Get GitHub authentication token from all available sources. Checks
+ * environment variables first, then falls back to git config. This is the
+ * recommended way to get a GitHub token with maximum compatibility.
+ *
+ * Priority order:
+ *
+ * 1. Environment variables (GITHUB_TOKEN, GH_TOKEN, SOCKET_CLI_GITHUB_TOKEN)
+ * 2. Git config (github.token)
+ *
+ * @example
+ *   ;```ts
+ *   const token = await getGitHubTokenWithFallback()
+ *   if (!token) {
+ *     throw new ErrorCtor('GitHub token required')
+ *   }
+ *   ```
+ *
+ * @returns GitHub token from first available source, or `undefined` if none
+ *   found.
+ */
+export declare function getGitHubTokenWithFallback(): Promise<string | undefined>;

package/dist/github/token.js

@@ -0,0 +1,55 @@
+"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 token_exports = {};
+__export(token_exports, {
+  getGitHubToken: () => getGitHubToken,
+  getGitHubTokenFromGitConfig: () => getGitHubTokenFromGitConfig,
+  getGitHubTokenWithFallback: () => getGitHubTokenWithFallback
+});
+module.exports = __toCommonJS(token_exports);
+var import_github = require("../env/github");
+var import_socket_cli = require("../env/socket-cli");
+var import_child = require("../process/spawn/child");
+function getGitHubToken() {
+  return (0, import_github.getGithubToken)() || (0, import_github.getGhToken)() || (0, import_socket_cli.getSocketCliGithubToken)() || void 0;
+}
+async function getGitHubTokenFromGitConfig(options) {
+  try {
+    const result = await (0, import_child.spawn)("git", ["config", "github.token"], {
+      ...options,
+      stdio: "pipe"
+    });
+    if (result.code === 0 && result.stdout) {
+      return result.stdout.toString().trim();
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function getGitHubTokenWithFallback() {
+  return getGitHubToken() || await getGitHubTokenFromGitConfig();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getGitHubToken,
+  getGitHubTokenFromGitConfig,
+  getGitHubTokenWithFallback
+});