nexus-agents 2.55.0 → 2.56.0

package/dist/chunk-R66AWJJ7.js

@@ -0,0 +1,120 @@
+import {
+  ConfigError,
+  err,
+  ok
+} from "./chunk-UOUJZIKH.js";
+
+// src/adapters/sdk/types.ts
+var PROVIDER_ENV_KEYS = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  google: "GOOGLE_AI_API_KEY",
+  "custom-openai": "NEXUS_CUSTOM_API_KEY"
+};
+var CUSTOM_API_BASE_URL_ENV = "NEXUS_CUSTOM_API_BASE_URL";
+var CUSTOM_API_ALLOW_PRIVATE_ENV = "NEXUS_CUSTOM_API_ALLOW_PRIVATE";
+
+// src/adapters/sdk/custom-api-validation.ts
+import { isIPv4, isIPv6 } from "net";
+function validateCustomApiBaseUrl(raw, opts = {}) {
+  if (raw === void 0 || raw.trim() === "") {
+    return err(
+      new ConfigError(
+        "Custom API base URL is required but missing. Set NEXUS_CUSTOM_API_BASE_URL or pass `baseUrl` in config."
+      )
+    );
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return err(new ConfigError(`Custom API base URL is not a valid URL: ${raw}`));
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return err(
+      new ConfigError(`Custom API base URL must use http or https, got "${url.protocol}" in ${raw}`)
+    );
+  }
+  const allowPrivate = opts.allowPrivate === true || resolveAllowPrivateFromEnv();
+  if (!allowPrivate) {
+    const rejection = classifyPrivateHost(url.hostname);
+    if (rejection !== null) {
+      return err(
+        new ConfigError(
+          `Custom API base URL rejected (SSRF guard, reason="${rejection.reason}"): ${rejection.message}. Set ${CUSTOM_API_ALLOW_PRIVATE_ENV}=1 to bypass if the gateway runs on a trusted internal host.`
+        )
+      );
+    }
+  }
+  return ok(url);
+}
+function resolveAllowPrivateFromEnv() {
+  const v = process.env[CUSTOM_API_ALLOW_PRIVATE_ENV];
+  return v === "1" || v === "true";
+}
+function classifyPrivateHost(hostname) {
+  const stripped = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  const normalized = stripped.toLowerCase();
+  if (isIPv4(normalized)) {
+    return classifyIPv4(normalized);
+  }
+  if (isIPv6(normalized)) {
+    return classifyIPv6(normalized);
+  }
+  if (normalized === "localhost" || normalized.endsWith(".localhost") || normalized.endsWith(".local")) {
+    return {
+      reason: "loopback",
+      message: `hostname "${hostname}" resolves to loopback/mDNS`
+    };
+  }
+  return null;
+}
+var IPV4_RULES = [
+  { match: (a) => a === 127, reason: "loopback", label: "IPv4 loopback" },
+  { match: (a) => a === 10, reason: "private_range", label: "IPv4 private (10/8)" },
+  {
+    match: (a, b) => a === 172 && b >= 16 && b <= 31,
+    reason: "private_range",
+    label: "IPv4 private (172.16/12)"
+  },
+  {
+    match: (a, b) => a === 192 && b === 168,
+    reason: "private_range",
+    label: "IPv4 private (192.168/16)"
+  },
+  {
+    match: (a, b) => a === 169 && b === 254,
+    reason: "link_local",
+    label: "IPv4 link-local (169.254/16 \u2014 AWS IMDS)"
+  },
+  { match: (a) => a === 0, reason: "reserved", label: "IPv4 reserved (0/8)" }
+];
+function classifyIPv4(ip) {
+  const parts = ip.split(".").map((p) => Number.parseInt(p, 10));
+  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return null;
+  const [a, b] = parts;
+  for (const rule of IPV4_RULES) {
+    if (rule.match(a, b)) {
+      return { reason: rule.reason, message: `${rule.label} (${ip})` };
+    }
+  }
+  return null;
+}
+function classifyIPv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === "::1") return { reason: "loopback", message: `IPv6 loopback (${ip})` };
+  if (lower.startsWith("fe80:"))
+    return { reason: "link_local", message: `IPv6 link-local (${ip})` };
+  if (/^fc|^fd/.test(lower)) {
+    return { reason: "private_range", message: `IPv6 unique-local (${ip}, fc00::/7)` };
+  }
+  return null;
+}
+
+export {
+  PROVIDER_ENV_KEYS,
+  CUSTOM_API_BASE_URL_ENV,
+  CUSTOM_API_ALLOW_PRIVATE_ENV,
+  validateCustomApiBaseUrl
+};
+//# sourceMappingURL=chunk-R66AWJJ7.js.map

package/dist/chunk-R66AWJJ7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/sdk/types.ts","../src/adapters/sdk/custom-api-validation.ts"],"sourcesContent":["/**\n * nexus-agents/adapters/sdk - Shared Types\n *\n * Type definitions for AI SDK adapter layer.\n *\n * @module adapters/sdk/types\n * (Source: Issue #1123 — AI SDK provider layer)\n */\n\n/**\n * Supported AI SDK provider identifiers.\n *\n * `custom-openai` is for OpenAI-compatible gateways (multi-vendor proxies,\n * self-hosted LLM servers, corporate model gateways) — uses the same\n * @ai-sdk/openai package but with a configurable `baseURL`.\n */\nexport type SdkProviderId = 'anthropic' | 'openai' | 'google' | 'custom-openai';\n\n/**\n * Configuration for creating an AI SDK adapter.\n */\nexport interface SdkAdapterConfig {\n  /** Provider identifier */\n  providerId: SdkProviderId;\n  /** Model to use (e.g., 'claude-sonnet-4-6', 'gpt-4o') */\n  modelId: string;\n  /** API key (falls back to environment variable) */\n  apiKey?: string;\n  /**\n   * Base URL for OpenAI-compatible gateways. Required when\n   * `providerId === 'custom-openai'`, ignored otherwise. Falls back to\n   * the `NEXUS_CUSTOM_API_BASE_URL` environment variable.\n   */\n  baseUrl?: string;\n  /** Request timeout in milliseconds */\n  timeout?: number;\n  /** Maximum retries on transient failures */\n  maxRetries?: number;\n}\n\n/**\n * Maps provider IDs to their environment variable names.\n */\nexport const PROVIDER_ENV_KEYS: Record<SdkProviderId, string> = {\n  anthropic: 'ANTHROPIC_API_KEY',\n  openai: 'OPENAI_API_KEY',\n  google: 'GOOGLE_AI_API_KEY',\n  'custom-openai': 'NEXUS_CUSTOM_API_KEY',\n};\n\n/**\n * Environment variable name for the custom gateway base URL.\n * Keep in sync with `SdkAdapterConfig.baseUrl`.\n */\nexport const CUSTOM_API_BASE_URL_ENV = 'NEXUS_CUSTOM_API_BASE_URL';\n\n/**\n * Escape hatch: set to `1`/`true` to allow the custom gateway base URL to\n * resolve to a loopback or RFC 1918 private address. Default is DENY —\n * SSRF defense. Only disable this when you know the gateway runs on a\n * trusted internal host and you accept the risk.\n */\nexport const CUSTOM_API_ALLOW_PRIVATE_ENV = 'NEXUS_CUSTOM_API_ALLOW_PRIVATE';\n","/**\n * Validation for the `custom-openai` SDK adapter's gateway URL.\n *\n * The base URL is user-provided, so without validation the adapter becomes\n * an SSRF vector: a malicious prompt that reshaped env vars, or a typo in\n * the config, could point nexus-agents at `http://169.254.169.254/` (AWS\n * metadata) or `http://localhost:5432/` (internal services). This module\n * rejects such URLs unless the user explicitly opts in via\n * `NEXUS_CUSTOM_API_ALLOW_PRIVATE=1`.\n *\n * Called out in the #2119 consensus vote by the Security Engineer role.\n *\n * @module adapters/sdk/custom-api-validation\n */\n\nimport { isIPv4, isIPv6 } from 'node:net';\nimport { ConfigError, ok, err, type Result } from '../../core/index.js';\nimport { CUSTOM_API_ALLOW_PRIVATE_ENV } from './types.js';\n\n/**\n * Why a given URL was rejected. Machine-readable so error messages can\n * distinguish root causes in downstream tooling.\n */\nexport type BaseUrlRejectionReason =\n  | 'empty'\n  | 'not_a_url'\n  | 'not_http_https'\n  | 'loopback'\n  | 'link_local'\n  | 'private_range'\n  | 'reserved';\n\ninterface RejectionDetail {\n  readonly reason: BaseUrlRejectionReason;\n  readonly message: string;\n}\n\n/**\n * Validates a user-provided custom-gateway base URL. Returns the URL as an\n * `ok` Result if it passes, or a `ConfigError` with a machine-readable\n * reason if it fails.\n *\n * Pass `{ allowPrivate: true }` (or set the env var) to bypass the SSRF\n * checks — use this only when the gateway is on a trusted internal host\n * and you accept the risk.\n */\nexport function validateCustomApiBaseUrl(\n  raw: string | undefined,\n  opts: { readonly allowPrivate?: boolean } = {}\n): Result<URL, ConfigError> {\n  if (raw === undefined || raw.trim() === '') {\n    return err(\n      new ConfigError(\n        'Custom API base URL is required but missing. Set NEXUS_CUSTOM_API_BASE_URL or pass `baseUrl` in config.'\n      )\n    );\n  }\n\n  let url: URL;\n  try {\n    url = new URL(raw);\n  } catch {\n    return err(new ConfigError(`Custom API base URL is not a valid URL: ${raw}`));\n  }\n\n  if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n    return err(\n      new ConfigError(`Custom API base URL must use http or https, got \"${url.protocol}\" in ${raw}`)\n    );\n  }\n\n  const allowPrivate = opts.allowPrivate === true || resolveAllowPrivateFromEnv();\n  if (!allowPrivate) {\n    const rejection = classifyPrivateHost(url.hostname);\n    if (rejection !== null) {\n      return err(\n        new ConfigError(\n          `Custom API base URL rejected (SSRF guard, reason=\"${rejection.reason}\"): ${rejection.message}. ` +\n            `Set ${CUSTOM_API_ALLOW_PRIVATE_ENV}=1 to bypass if the gateway runs on a trusted internal host.`\n        )\n      );\n    }\n  }\n\n  return ok(url);\n}\n\nfunction resolveAllowPrivateFromEnv(): boolean {\n  const v = process.env[CUSTOM_API_ALLOW_PRIVATE_ENV];\n  return v === '1' || v === 'true';\n}\n\n/**\n * Returns a rejection reason if the hostname resolves (by string form) to\n * a loopback, link-local, or RFC 1918 private address; `null` otherwise.\n *\n * Note: this is a string-level check. It does NOT perform DNS resolution,\n * so a public DNS name that secretly resolves to a private IP will pass.\n * Callers who need that level of defense should add a runtime connect\n * check and validate the socket peer address.\n */\nfunction classifyPrivateHost(hostname: string): RejectionDetail | null {\n  // URL.hostname wraps IPv6 literals in brackets (e.g. \"[::1]\"); strip them\n  // before the net-module checks, which expect bare forms.\n  const stripped =\n    hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;\n  const normalized = stripped.toLowerCase();\n\n  // Literal IPv4 loopback or private-range address\n  if (isIPv4(normalized)) {\n    return classifyIPv4(normalized);\n  }\n\n  // Literal IPv6 loopback (::1), link-local (fe80::/10), unique-local (fc00::/7)\n  if (isIPv6(normalized)) {\n    return classifyIPv6(normalized);\n  }\n\n  // Hostname literals that resolve to loopback without needing DNS\n  if (\n    normalized === 'localhost' ||\n    normalized.endsWith('.localhost') ||\n    normalized.endsWith('.local') // mDNS\n  ) {\n    return {\n      reason: 'loopback',\n      message: `hostname \"${hostname}\" resolves to loopback/mDNS`,\n    };\n  }\n\n  return null;\n}\n\n/** IPv4 ranges the SSRF guard rejects, in order of specificity. */\nconst IPV4_RULES: ReadonlyArray<{\n  readonly match: (a: number, b: number) => boolean;\n  readonly reason: BaseUrlRejectionReason;\n  readonly label: string;\n}> = [\n  { match: (a) => a === 127, reason: 'loopback', label: 'IPv4 loopback' },\n  { match: (a) => a === 10, reason: 'private_range', label: 'IPv4 private (10/8)' },\n  {\n    match: (a, b) => a === 172 && b >= 16 && b <= 31,\n    reason: 'private_range',\n    label: 'IPv4 private (172.16/12)',\n  },\n  {\n    match: (a, b) => a === 192 && b === 168,\n    reason: 'private_range',\n    label: 'IPv4 private (192.168/16)',\n  },\n  {\n    match: (a, b) => a === 169 && b === 254,\n    reason: 'link_local',\n    label: 'IPv4 link-local (169.254/16 — AWS IMDS)',\n  },\n  { match: (a) => a === 0, reason: 'reserved', label: 'IPv4 reserved (0/8)' },\n];\n\nfunction classifyIPv4(ip: string): RejectionDetail | null {\n  const parts = ip.split('.').map((p) => Number.parseInt(p, 10));\n  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return null;\n  const [a, b] = parts as [number, number, number, number];\n  for (const rule of IPV4_RULES) {\n    if (rule.match(a, b)) {\n      return { reason: rule.reason, message: `${rule.label} (${ip})` };\n    }\n  }\n  return null;\n}\n\nfunction classifyIPv6(ip: string): RejectionDetail | null {\n  const lower = ip.toLowerCase();\n  if (lower === '::1') return { reason: 'loopback', message: `IPv6 loopback (${ip})` };\n  if (lower.startsWith('fe80:'))\n    return { reason: 'link_local', message: `IPv6 link-local (${ip})` };\n  // Unique-local: fc00::/7 → first byte has high bit set and second-high bit set\n  if (/^fc|^fd/.test(lower)) {\n    return { reason: 'private_range', message: `IPv6 unique-local (${ip}, fc00::/7)` };\n  }\n  return null;\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -50,6 +50,7 @@ interface ParsedCliArgs {
         version: boolean;
         verbose: boolean;
         interactive: boolean;
+        all: boolean;
         mode: ServerMode;
         output?: string;
         force: boolean;
@@ -98,6 +99,9 @@ interface ParsedCliArgs {
         skipGemini: boolean;
         skipCodex: boolean;
         scope?: 'user' | 'project';
+        customApi?: string;
+        customApiKey?: string;
+        customModel?: string;
         mock: boolean;
         deep: boolean;
     };
@@ -119,8 +123,12 @@ interface ParsedCliArgs {
 
 /**
  * Prints help text to stdout.
+ *
+ * Default output hides maintainer commands (benchmarks, release tooling, deep
+ * diagnostics). Pass `--all` to include them. See `cli-command-catalog.ts` for
+ * the audience classification.
  */
-declare function printHelp(): void;
+declare function printHelp(args?: ParsedCliArgs): void;
 /**
  * Prints version information to stdout.
  */