fix(cli): split outboundUrlGuard's DB helpers so setup-opencode packages cleanly (#7682)

changelog.d/fixes/7682-opencode-shared-alias.md

@@ -0,0 +1 @@
+- fix(cli): split `outboundUrlGuard.ts`'s DB/feature-flag helpers into `outboundUrlGuardPolicy.ts` so `omniroute setup-opencode` no longer crashes with `Cannot find package '@/shared'` on a global npm install (#7682)

src/app/api/provider-nodes/urlGuard.ts

@@ -1,11 +1,11 @@
 import { NextResponse } from "next/server";
 import {
   OutboundUrlGuardError,
-  getProviderValidationGuard,
   parseAndValidateNonMetadataUrl,
   parseAndValidatePublicUrl,
   parseOutboundUrl,
 } from "@/shared/network/outboundUrlGuard";
+import { getProviderValidationGuard } from "@/shared/network/outboundUrlGuardPolicy";
 
 function guardProviderNodeBaseUrl(baseUrl: string): void {
   const guard = getProviderValidationGuard();

src/app/api/provider-nodes/validate/route.ts

@@ -8,7 +8,7 @@ import {
   getSafeOutboundFetchErrorStatus,
   safeOutboundFetch,
 } from "@/shared/network/safeOutboundFetch";
-import { getProviderValidationGuard } from "@/shared/network/outboundUrlGuard";
+import { getProviderValidationGuard } from "@/shared/network/outboundUrlGuardPolicy";
 import { isCcCompatibleProviderEnabled } from "@/shared/utils/featureFlags";
 import { providerNodeValidateSchema } from "@/shared/validation/schemas";
 import { isValidationFailure, validateBody } from "@/shared/validation/helpers";

src/app/api/providers/[id]/models/discovery/normalizers.ts

@@ -1,5 +1,5 @@
 import { SAFE_OUTBOUND_FETCH_PRESETS, safeOutboundFetch } from "@/shared/network/safeOutboundFetch";
-import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuard";
+import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuardPolicy";
 import {
   getAntigravityModelsDiscoveryUrls,
   getAntigravityFetchAvailableModelsUrls,

src/app/api/providers/[id]/models/route.ts

@@ -25,7 +25,7 @@ import {
 import {
   getProviderOutboundGuard,
   getProviderValidationGuard,
-} from "@/shared/network/outboundUrlGuard";
+} from "@/shared/network/outboundUrlGuardPolicy";
 import { sanitizeErrorMessage } from "@omniroute/open-sse/utils/error";
 import { getStaticQoderModels } from "@omniroute/open-sse/services/qoderCli.ts";
 import { deriveConfigFromRegistryModelsUrl } from "./discoveryConfig";

src/app/api/proxy-fallback/test/route.ts

@@ -11,7 +11,8 @@ import { z } from "zod";
 import { sanitizeErrorMessage } from "@omniroute/open-sse/utils/error";
 import { validateBody, isValidationFailure } from "@/shared/validation/helpers";
 import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
-import { isPrivateHost, arePrivateProviderUrlsAllowed } from "@/shared/network/outboundUrlGuard";
+import { isPrivateHost } from "@/shared/network/outboundUrlGuard";
+import { arePrivateProviderUrlsAllowed } from "@/shared/network/outboundUrlGuardPolicy";
 import {
   testProxiesAgainstTarget,
   getProxyCandidates,

src/app/api/webhooks/[id]/route.ts

@@ -13,7 +13,7 @@ import { validateBody, isValidationFailure } from "@/shared/validation/helpers";
 import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
 import { encryptMetadata } from "@/lib/webhookDispatcher";
 import { isEncryptionEnabled } from "@/lib/db/encryption";
-import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuard";
+import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuardPolicy";
 
 const WEBHOOK_KINDS = ["slack", "telegram", "discord", "custom"] as const;
 const WEBHOOK_EVENT_VALUES = [

src/app/api/webhooks/[id]/test/route.ts

@@ -13,11 +13,8 @@ import { buildDiscordPayload } from "@/lib/webhooks/integrations/discord";
 import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
 import { insertDelivery } from "@/lib/db/webhookDeliveries";
 import { recordWebhookDelivery } from "@/lib/localDb";
-import {
-  parseAndValidateWebhookUrl,
-  isPrivateHost,
-  OutboundUrlGuardError,
-} from "@/shared/network/outboundUrlGuard";
+import { isPrivateHost, OutboundUrlGuardError } from "@/shared/network/outboundUrlGuard";
+import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuardPolicy";
 import crypto from "crypto";
 
 const MAX_RESPONSE_BODY = 2048;

src/app/api/webhooks/route.ts

@@ -12,7 +12,7 @@ import { validateBody, isValidationFailure } from "@/shared/validation/helpers";
 import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
 import { encryptMetadata } from "@/lib/webhookDispatcher";
 import { isEncryptionEnabled } from "@/lib/db/encryption";
-import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuard";
+import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuardPolicy";
 
 const WEBHOOK_KINDS = ["slack", "telegram", "discord", "custom"] as const;
 

src/app/api/webhooks/validate-url/route.ts

@@ -6,10 +6,8 @@
 import { z } from "zod";
 import { NextResponse } from "next/server";
 import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
-import {
-  parseAndValidateWebhookUrl,
-  OutboundUrlGuardError,
-} from "@/shared/network/outboundUrlGuard";
+import { OutboundUrlGuardError } from "@/shared/network/outboundUrlGuard";
+import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuardPolicy";
 import { validateBody, isValidationFailure } from "@/shared/validation/helpers";
 
 const validateUrlSchema = z.object({

src/lib/providers/imageValidation.ts

@@ -1,6 +1,6 @@
 import { getImageProvider } from "@omniroute/open-sse/config/imageRegistry";
 
-import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuard";
+import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuardPolicy";
 import {
   SAFE_OUTBOUND_FETCH_PRESETS,
   SafeOutboundFetchError,

src/lib/providers/validation.ts

@@ -11,7 +11,7 @@ import {
   WEB_COOKIE_PROVIDERS,
 } from "@/shared/constants/providers";
 import { SAFE_OUTBOUND_FETCH_PRESETS, safeOutboundFetch } from "@/shared/network/safeOutboundFetch";
-import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuard";
+import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuardPolicy";
 import { resolveNvidiaValidationModel } from "@/lib/providers/nvidiaValidationModel";
 import { MODAL_DEFAULT_VALIDATION_MODEL_ID } from "@/shared/constants/modal";
 import { validateQoderCliPat } from "@omniroute/open-sse/services/qoderCli.ts";

src/lib/providers/validation/headers.ts

@@ -2,7 +2,7 @@
 // from validation.ts (god-file decomposition). Pure header construction except directHttpsRequest,
 // which delegates to safeOutboundFetch with bypassProxyPatch. Behavior is byte-identical.
 import { safeOutboundFetch } from "@/shared/network/safeOutboundFetch";
-import { getProviderValidationGuard } from "@/shared/network/outboundUrlGuard";
+import { getProviderValidationGuard } from "@/shared/network/outboundUrlGuardPolicy";
 
 // Standardized desktop Chrome UA for web-cookie/no-auth session probes (minimizes anti-bot detection).
 export const STANDARD_USER_AGENT =

src/lib/providers/validation/searchProviders.ts

@@ -2,7 +2,7 @@
 // …). Extracted from validation.ts (god-file decomposition) — top-level functions/data with no
 // dispatcher-state captures; behavior is byte-identical to the original inline defs.
 import { SAFE_OUTBOUND_FETCH_PRESETS, safeOutboundFetch } from "@/shared/network/safeOutboundFetch";
-import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuard";
+import { getProviderOutboundGuard } from "@/shared/network/outboundUrlGuardPolicy";
 import { withCustomUserAgent } from "./headers";
 import { toValidationErrorResult, validationWrite } from "./transport";
 

src/lib/providers/validation/transport.ts

@@ -7,7 +7,8 @@ import {
   getSafeOutboundFetchErrorStatus,
   safeOutboundFetch,
 } from "@/shared/network/safeOutboundFetch";
-import { getProviderValidationGuard, isPrivateHost } from "@/shared/network/outboundUrlGuard";
+import { isPrivateHost } from "@/shared/network/outboundUrlGuard";
+import { getProviderValidationGuard } from "@/shared/network/outboundUrlGuardPolicy";
 import { selectProxyForValidation } from "@omniroute/open-sse/services/proxyAutoSelector.ts";
 
 /**

src/lib/webhookDispatcher.ts

@@ -6,7 +6,7 @@
 
 import crypto from "crypto";
 import { encrypt, decrypt } from "./db/encryption";
-import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuard";
+import { parseAndValidateWebhookUrl } from "@/shared/network/outboundUrlGuardPolicy";
 import type { WebhookEvent } from "./webhooks/eventDescriptions";
 
 export type { WebhookEvent };

src/shared/network/outboundUrlGuard.ts

@@ -1,16 +1,7 @@
 import { isIP } from "node:net";
-import { resolveFeatureFlag } from "@/shared/utils/featureFlags";
-
-const TRUE_ENV_VALUES = new Set(["1", "true", "yes", "on"]);
 
 export const PROVIDER_URL_BLOCKED_MESSAGE = "Blocked private or local provider URL";
 export const CLOUD_METADATA_BLOCKED_MESSAGE = "Blocked cloud-metadata endpoint";
-export const PRIVATE_PROVIDER_URLS_ENV = "OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS";
-// #5066: scoped to provider validation/use. Allows local/private provider endpoints
-// (127.0.0.1, localhost, LAN) so local-first OpenAI-compatible providers validate, while
-// cloud-metadata endpoints stay blocked. Defaults ON (OmniRoute is local-first); operators
-// who only use public providers can disable it to restore strict SSRF blocking.
-export const LOCAL_PROVIDER_URLS_ENV = "OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS";
 
 // "block-metadata": allow private/LAN hosts but still reject cloud-metadata / link-local
 // endpoints (the SSRF→IAM-credential pivot). Used by the provider-validation path under the
@@ -175,102 +166,11 @@ export function parseAndValidateNonMetadataUrl(input: string | URL) {
   return url;
 }
 
-/**
- * Webhook variant of {@link parseAndValidatePublicUrl}. Webhooks legitimately point at
- * internal services (n8n, Home Assistant, a LAN box) in Docker/self-hosted deployments,
- * so the private-host block is gated behind the same explicit opt-in used for private
- * provider URLs (`OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`, default OFF). Protocol and
- * embedded-credential checks in {@link parseOutboundUrl} remain unconditional. (#3269)
- */
-export function parseAndValidateWebhookUrl(input: string | URL) {
-  const url = parseOutboundUrl(input);
-
-  // Cloud-metadata / link-local endpoints are NEVER a valid webhook target — block them
-  // even when the private opt-in is enabled (SSRF→IAM-credential pivot). (#3269)
-  if (isCloudMetadataHost(url.hostname)) {
-    throw new OutboundUrlGuardError(PROVIDER_URL_BLOCKED_MESSAGE, {
-      code: "OUTBOUND_URL_GUARD_BLOCKED",
-      url: url.toString(),
-      hostname: url.hostname || null,
-    });
-  }
-
-  if (!arePrivateProviderUrlsAllowed() && isPrivateHost(url.hostname)) {
-    throw new OutboundUrlGuardError(PROVIDER_URL_BLOCKED_MESSAGE, {
-      code: "OUTBOUND_URL_GUARD_BLOCKED",
-      url: url.toString(),
-      hostname: url.hostname || null,
-    });
-  }
-
-  return url;
-}
-
-function isTrueValue(raw: unknown): boolean {
-  if (typeof raw !== "string") return false;
-  return TRUE_ENV_VALUES.has(raw.trim().toLowerCase());
-}
-
-export function arePrivateProviderUrlsAllowed() {
-  // 1) DB override takes precedence — it represents an explicit user toggle in
-  //    the dashboard ("Allow Private Provider URLs"). This is critical for the
-  //    Electron build (#2575) where the server is spawned with the env value
-  //    captured at boot, so subsequent UI toggles only land in the DB and the
-  //    env-first ordering would otherwise mask them.
-  try {
-    const dbValue = resolveFeatureFlag(PRIVATE_PROVIDER_URLS_ENV);
-    if (isTrueValue(dbValue)) return true;
-  } catch {
-    // DB not initialized yet — fall through to env-only check.
-  }
-
-  // 2) Explicit env opt-in (for headless/Docker users who set it before boot).
-  if (isTrueValue(process.env[PRIVATE_PROVIDER_URLS_ENV])) return true;
-
-  // 3) Legacy escape hatch — disabling the outbound guard implies allowing
-  //    private URLs.
-  const legacyValue = process.env["OUTBOUND_SSRF_GUARD_ENABLED"];
-  if (
-    typeof legacyValue === "string" &&
-    ["false", "0", "no", "off"].includes(legacyValue.trim().toLowerCase())
-  ) {
-    return true;
-  }
-
-  return false;
-}
-
-export function getProviderOutboundGuard(): OutboundUrlGuardMode {
-  return arePrivateProviderUrlsAllowed() ? "none" : "public-only";
-}
-
-/**
- * #5066: whether provider endpoints on local/private addresses are permitted. Defaults ON
- * (OmniRoute is local-first — local OpenAI-compatible providers should validate out of the
- * box). Disable via the `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` flag (DB toggle or env) to
- * restore strict public-only SSRF blocking. Cloud-metadata stays blocked regardless.
- */
-export function areLocalProviderUrlsAllowed(): boolean {
-  try {
-    const dbValue = resolveFeatureFlag(LOCAL_PROVIDER_URLS_ENV);
-    if (dbValue !== undefined && dbValue !== "") return isTrueValue(dbValue);
-  } catch {
-    // DB not initialized yet — fall through to env / default.
-  }
-  const envValue = process.env[LOCAL_PROVIDER_URLS_ENV];
-  if (typeof envValue === "string" && envValue !== "") return isTrueValue(envValue);
-  // Default ON.
-  return true;
-}
-
-/**
- * Guard mode for the provider VALIDATION/use path (not webhooks or remote images). Precedence:
- *  1. explicit full opt-in (`arePrivateProviderUrlsAllowed`) → "none" (no checks; power users).
- *  2. local-first default (`areLocalProviderUrlsAllowed`) → "block-metadata" (allow LAN, block IMDS).
- *  3. otherwise → "public-only" (strict).
- */
-export function getProviderValidationGuard(): OutboundUrlGuardMode {
-  if (arePrivateProviderUrlsAllowed()) return "none";
-  if (areLocalProviderUrlsAllowed()) return "block-metadata";
-  return "public-only";
-}
+// NOTE (#7682): `arePrivateProviderUrlsAllowed`, `areLocalProviderUrlsAllowed`,
+// `getProviderOutboundGuard`, `getProviderValidationGuard`, and `parseAndValidateWebhookUrl`
+// live in the sibling `./outboundUrlGuardPolicy.ts` module, NOT here. Those helpers need
+// `@/shared/utils/featureFlags` (which transitively pulls in the DB layer), and this file is
+// loaded by the packaged CLI (`omniroute setup-opencode` → cli-helper/config-generator/
+// opencode.ts) where no `tsconfig.json` is present to resolve the `@/*` path alias. Keeping
+// this module free of ANY `@/`-aliased import is what makes it safe to load from the CLI.
+// Do not add a `@/`-aliased import here — see docs/security/… (packaging) and #7682.