From 2180ad2f623dd74a0eba75fbee6306cda622cd42 Mon Sep 17 00:00:00 2001
From: Bryandero98 <bryandero98@gmail.com>
Date: Wed, 2 Sep 2026 07:42:11 -0700
Subject: [PATCH] fix: move the endpoint guard to aiToolkit's public root so
 services stop deep-importing internal/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`evaluateSecretEndpoint`/`assertSecretEndpoint` — the SSRF/key-exfiltration
guard that decides whether a paid API key may be attached to a provider
`endpoint` — lived at `aiToolkit/internal/endpointGuard.js`, yet PortOS
service modules imported it from that private path. Any toolkit resync or
internal reshuffle would have required a manual multi-service migration,
with a runtime import failure as the failure mode.

Move it to `aiToolkit/endpointGuard.js`, a public peer of
`errorDetection.js` — the module that already establishes the "pure toolkit
root module, direct-importable and barrel re-exported" shape. `index.js`
adds the matching `export *`, so the barrel advertises the surface without
any consumer paying for the composition root's route/provider/runner graph
to reach one pure URL check.

Guard logic and its test are byte-identical to before: same allow/block
decisions, same evaluate-vs-assert split, same keyless local-LLM behavior,
same `allowCustomEndpoint` opt-in.

Fixes #5619
---
 server/lib/README.md                                      | 2 +-
 server/lib/aiToolkit/{internal => }/endpointGuard.js      | 7 +++++--
 server/lib/aiToolkit/{internal => }/endpointGuard.test.js | 0
 server/lib/aiToolkit/index.js                             | 1 +
 server/lib/aiToolkit/providers.js                         | 4 ++--
 server/lib/aiToolkit/runner.js                            | 2 +-
 server/lib/aiToolkit/validation.js                        | 2 +-
 server/lib/validation.js                                  | 2 +-
 server/services/aiProvider.js                             | 2 +-
 server/services/askService.js                             | 2 +-
 server/services/localLlmPlayground.js                     | 2 +-
 server/services/visionTest.frameGuard.test.js             | 2 +-
 server/services/visionTest.js                             | 2 +-
 server/services/voice/llm.js                              | 2 +-
 14 files changed, 18 insertions(+), 14 deletions(-)
 rename server/lib/aiToolkit/{internal => }/endpointGuard.js (95%)
 rename server/lib/aiToolkit/{internal => }/endpointGuard.test.js (100%)

diff --git a/server/lib/README.md b/server/lib/README.md
index f752a63726..22a4cd33f9 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -136,7 +136,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
 
 | Module | Purpose |
 |---|---|
-| `aiToolkit/` | Vendored toolkit (providers + runner + prompts + status). See `aiToolkit/index.js`. |
+| `aiToolkit/` | Vendored toolkit (providers + runner + prompts + status). See `aiToolkit/index.js`. `aiToolkit/endpointGuard.js` — a peer of `aiToolkit/errorDetection.js`, not under `internal/` — publicly exports `evaluateSecretEndpoint`/`assertSecretEndpoint`, the SSRF/key-exfiltration guard for provider `endpoint` URLs; PortOS's own `server/services/*` should import both directly from there (also re-exported through `aiToolkit/index.js` for barrel completeness, but that pulls the toolkit's much larger route/provider/runner graph — not worth it for just this guard). |
 | `aiToolkitState.js` | Module-level singleton for the toolkit instance shared by the `providers`/`runner`/`promptService` shims — `setAIToolkitInstance` / `requireToolkit` (throws `AI_TOOLKIT_NOT_INITIALIZED`) / `getAIToolkitInstance` (no-throw for cleanup paths). |
 | `antigravity.js` | Antigravity (`agy`) CLI provider helpers — id/sentinel constants (`ANTIGRAVITY_CLI_ID`, `ANTIGRAVITY_CONFIGURED_DEFAULT`, `LEGACY_GEMINI_*`), `isAntigravityCommand`/`isAntigravityCliProvider` predicates, and `ensureAntigravityPrintArgs(args, {model, effort})`/`ensureAntigravityTuiArgs(args, {model, effort})`/`stripAntigravityUnsupportedArgs` argv normalizers. `parseAntigravityModelList(stdout)` parses `agy models` rows — accepts both the modern `<id>\t<Label>` shape and the older bare-id-per-line one, deduped, sentinel dropped (mirrored in the vendored toolkit's `internal/antigravity.js`; used by both the provider-catalog refresh and Image Gen's agy model picker). `isAntigravityModelId(id)` is the same id shape as a bare predicate, for spawn sites building an `agy --model` argv from a value no route schema bounded. The strip drops legacy Gemini `--yolo`/`-m`/`--output-format` but PRESERVES the long `--model` (agy accepts it as a per-session flag, so a user-baked pin is a real selection and suppresses the injected one); the two builders inject `--model`/`--effort` from the per-run overrides, always ahead of the trailing `--print` marker whose value is the prompt. |
 | `llmText.js` | Pure LLM-output text helpers — `stripCodeFences` (unfence a model reply) and `parseLLMJSON` (unfence then JSON.parse with a descriptive throw). Below the provider layer, so lib can clean model output without importing provider orchestration. |
diff --git a/server/lib/aiToolkit/internal/endpointGuard.js b/server/lib/aiToolkit/endpointGuard.js
similarity index 95%
rename from server/lib/aiToolkit/internal/endpointGuard.js
rename to server/lib/aiToolkit/endpointGuard.js
index 5650a5a588..7a9bd80213 100644
--- a/server/lib/aiToolkit/internal/endpointGuard.js
+++ b/server/lib/aiToolkit/endpointGuard.js
@@ -24,8 +24,11 @@
  * — a bearer token has no business going there and it's the canonical SSRF
  * credential-theft target.
  *
- * Kept in `aiToolkit/internal/` (pure, no imports) so the toolkit stays
- * self-contained; `server/services/aiProvider.js` imports it from here too.
+ * Pure (no imports), and lives at the toolkit's own root — a peer of
+ * `errorDetection.js` — rather than under `internal/`, so PortOS's own
+ * `server/services/*` (six modules, at #5619) can import it directly
+ * without pulling the full toolkit barrel's much larger graph (routes,
+ * providers, runner) just for this one guard (#5625).
  *
  * NOTE: checks are performed on the URL's literal host. We do not resolve DNS,
  * so a user-supplied hostname that resolves to a private/metadata IP is treated
diff --git a/server/lib/aiToolkit/internal/endpointGuard.test.js b/server/lib/aiToolkit/endpointGuard.test.js
similarity index 100%
rename from server/lib/aiToolkit/internal/endpointGuard.test.js
rename to server/lib/aiToolkit/endpointGuard.test.js
diff --git a/server/lib/aiToolkit/index.js b/server/lib/aiToolkit/index.js
index 93f7b3f399..071eb6a16e 100644
--- a/server/lib/aiToolkit/index.js
+++ b/server/lib/aiToolkit/index.js
@@ -28,6 +28,7 @@ export const DEFAULT_PROVIDERS_SAMPLE = join(__dirname, 'defaults/providers.samp
 
 export * from './validation.js';
 export * from './errorDetection.js';
+export * from './endpointGuard.js';
 export * from './constants.js';
 export { createProviderService, createRunnerService, createPromptsService, createProviderStatusService };
 export { isOllamaBackedProvider, canRefreshModels, ollamaRefreshGroupKey };
diff --git a/server/lib/aiToolkit/providers.js b/server/lib/aiToolkit/providers.js
index a5815ac221..c313689740 100644
--- a/server/lib/aiToolkit/providers.js
+++ b/server/lib/aiToolkit/providers.js
@@ -2,7 +2,7 @@ import { readFile, rename } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join, dirname, delimiter, isAbsolute } from 'path';
 import { atomicWrite } from './internal/atomicWrite.js';
-import { assertSecretEndpoint, evaluateSecretEndpoint } from './internal/endpointGuard.js';
+import { assertSecretEndpoint, evaluateSecretEndpoint } from './endpointGuard.js';
 import { fileURLToPath } from 'url';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
@@ -663,7 +663,7 @@ export function createProviderService(config = {}) {
           ? { gatewayBacked: providerData.gatewayBacked } : {}),
         ...(providerData.orcarouterBacked === true ? { orcarouterBacked: true } : {}),
         // Explicit opt-in to send the API key to an arbitrary (non-local,
-        // non-allowlisted) endpoint — see internal/endpointGuard.js. Only
+        // non-allowlisted) endpoint — see endpointGuard.js. Only
         // persisted when true so existing keyless/local providers stay clean.
         ...(providerData.allowCustomEndpoint === true ? { allowCustomEndpoint: true } : {}),
         envVars: providerData.envVars || {},
diff --git a/server/lib/aiToolkit/runner.js b/server/lib/aiToolkit/runner.js
index b52ea43867..377b1f7c57 100644
--- a/server/lib/aiToolkit/runner.js
+++ b/server/lib/aiToolkit/runner.js
@@ -1,6 +1,6 @@
 import { mkdir, readFile, readdir, rm } from 'fs/promises';
 import { atomicWrite } from './internal/atomicWrite.js';
-import { evaluateSecretEndpoint } from './internal/endpointGuard.js';
+import { evaluateSecretEndpoint } from './endpointGuard.js';
 import { existsSync } from 'fs';
 import { join, extname, basename, isAbsolute, delimiter } from 'path';
 import { spawn, ChildProcess } from 'child_process';
diff --git a/server/lib/aiToolkit/validation.js b/server/lib/aiToolkit/validation.js
index 440d02015f..3e8b31d8d5 100644
--- a/server/lib/aiToolkit/validation.js
+++ b/server/lib/aiToolkit/validation.js
@@ -176,7 +176,7 @@ export const providerSchema = z.object({
   // Explicit opt-in to attach the provider's API key to an arbitrary
   // (non-local, non-allowlisted) endpoint. Guards against SSRF / key
   // exfiltration to a hostile or mistyped host — see
-  // internal/endpointGuard.js. Metadata endpoints stay blocked even when true.
+  // endpointGuard.js. Metadata endpoints stay blocked even when true.
   allowCustomEndpoint: z.boolean().optional(),
   envVars: z.record(z.string()).optional(),
   secretEnvVars: z.array(z.string()).optional(),
diff --git a/server/lib/validation.js b/server/lib/validation.js
index 7d5dd501a0..30edfa153a 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -536,7 +536,7 @@ export const providerSchema = z.object({
   orcarouterBacked: z.boolean().optional(),
   // Explicit opt-in to attach the API key to an arbitrary (non-local,
   // non-allowlisted) endpoint — mirrors the aiToolkit providerSchema. Guards
-  // SSRF / key exfiltration (server/lib/aiToolkit/internal/endpointGuard.js).
+  // SSRF / key exfiltration (server/lib/aiToolkit/endpointGuard.js).
   allowCustomEndpoint: z.boolean().optional(),
   envVars: z.record(z.string()).optional(),
   headlessArgs: z.array(z.string()).optional(),
diff --git a/server/services/aiProvider.js b/server/services/aiProvider.js
index 3f120a5d38..f9b821fbfb 100644
--- a/server/services/aiProvider.js
+++ b/server/services/aiProvider.js
@@ -19,7 +19,7 @@ import { readResponseJson } from '../lib/readResponseJson.js';
 import { classifyCodexTransportError, isCodexTextTransportEnabled } from '../lib/codexTurn.js';
 import { resolveBenchWaitMs, resolveProviderBench } from '../lib/providerCooldown.js';
 import { ERROR_CATEGORIES } from '../lib/aiToolkit/errorDetection.js';
-import { evaluateSecretEndpoint } from '../lib/aiToolkit/internal/endpointGuard.js';
+import { evaluateSecretEndpoint } from '../lib/aiToolkit/endpointGuard.js';
 import { withCreativeLatitude } from '../lib/creativeLatitude.js';
 
 const isAPI = (p) => p && p.type === 'api' && p.enabled !== false;
diff --git a/server/services/askService.js b/server/services/askService.js
index 22cc51c984..315823f89c 100644
--- a/server/services/askService.js
+++ b/server/services/askService.js
@@ -38,7 +38,7 @@ import { prepareCliPrompt } from '../lib/cliProviderArgs.js';
 import { prepareCliSpawn } from '../lib/bufferedSpawn.js';
 import { buildCliChildEnv } from '../lib/cliChildEnv.js';
 import { ensureProviderReady as ensureOllamaProviderReady } from './ollamaManager.js';
-import { evaluateSecretEndpoint } from '../lib/aiToolkit/internal/endpointGuard.js';
+import { evaluateSecretEndpoint } from '../lib/aiToolkit/endpointGuard.js';
 import { iterateOpenAiChat } from '../lib/openAiChatStream.js';
 
 // Re-export so the route can keep importing modes via askService — but
diff --git a/server/services/localLlmPlayground.js b/server/services/localLlmPlayground.js
index 9d9177fb7c..ecadc40be3 100644
--- a/server/services/localLlmPlayground.js
+++ b/server/services/localLlmPlayground.js
@@ -8,7 +8,7 @@ import { anyAbortSignal } from '../lib/requestAbort.js';
 // The SSE read loop lives in `lib/openAiChatStream.js` so the assessments
 // service can measure a bare loopback daemon that has no provider record.
 import { buildMessages, streamOllamaChat, streamOpenAiChat } from '../lib/openAiChatStream.js';
-import { assertSecretEndpoint } from '../lib/aiToolkit/internal/endpointGuard.js';
+import { assertSecretEndpoint } from '../lib/aiToolkit/endpointGuard.js';
 
 const PROVIDER_BY_BACKEND = { ollama: 'ollama', lmstudio: 'lmstudio' };
 
diff --git a/server/services/visionTest.frameGuard.test.js b/server/services/visionTest.frameGuard.test.js
index 71bafcb60d..a2a5c99493 100644
--- a/server/services/visionTest.frameGuard.test.js
+++ b/server/services/visionTest.frameGuard.test.js
@@ -19,7 +19,7 @@ vi.mock('./providers.js', () => ({
 vi.mock('../lib/fetchWithTimeout.js', () => ({ fetchWithTimeout: vi.fn() }));
 vi.mock('./ollamaManager.js', () => ({ ensureProviderReady: vi.fn(async () => ({ success: true })) }));
 vi.mock('./visionCli.js', () => ({ describeImageViaCli: vi.fn() }));
-vi.mock('../lib/aiToolkit/internal/endpointGuard.js', () => ({
+vi.mock('../lib/aiToolkit/endpointGuard.js', () => ({
   assertSecretEndpoint: vi.fn(),
   evaluateSecretEndpoint: vi.fn(() => ({ ok: true })),
 }));
diff --git a/server/services/visionTest.js b/server/services/visionTest.js
index 2536d3de01..7517fb22e7 100644
--- a/server/services/visionTest.js
+++ b/server/services/visionTest.js
@@ -13,7 +13,7 @@ import { describeFrameStats, isDegenerateFrame } from '../lib/imageFrameStats.js
 import { fetchWithTimeout } from '../lib/fetchWithTimeout.js';
 import { ensureProviderReady as ensureOllamaProviderReady } from './ollamaManager.js';
 import { describeImageViaCli } from './visionCli.js';
-import { assertSecretEndpoint, evaluateSecretEndpoint } from '../lib/aiToolkit/internal/endpointGuard.js';
+import { assertSecretEndpoint, evaluateSecretEndpoint } from '../lib/aiToolkit/endpointGuard.js';
 
 const SCREENSHOTS_DIR = PATHS.screenshots;
 const DEFAULT_VISION_TIMEOUT_MS = 60000;
diff --git a/server/services/voice/llm.js b/server/services/voice/llm.js
index db31c3df77..3899ad23d9 100644
--- a/server/services/voice/llm.js
+++ b/server/services/voice/llm.js
@@ -7,7 +7,7 @@
 // provider is missing, not API-type, or the toolkit hasn't warmed yet.
 
 import { getProviderById } from '../providers.js';
-import { assertSecretEndpoint } from '../../lib/aiToolkit/internal/endpointGuard.js';
+import { assertSecretEndpoint } from '../../lib/aiToolkit/endpointGuard.js';
 
 // Legacy env-based LM Studio default. Returns the OpenAI-compatible API base
 // INCLUDING the version path, so callers append `/models` / `/chat/completions`.