fix(api): enforce model permissions on gateway mirrors

changelog.d/fixes/9788-model-catalog-gateway-permissions.md

@@ -0,0 +1 @@
+- **fix(api):** Model catalogs no longer expose functional gateway mirrors unless the API key permits the mirror's final public model ID ([#9788](https://github.com/diegosouzapw/OmniRoute/pull/9788)) — thanks @xz-dev

open-sse/utils/functionalGatewayMirrors.ts

@@ -19,6 +19,8 @@
 
 export const FUNCTIONAL_GATEWAY_MIRROR_SUFFIX = " (via ";
 
+const FUNCTIONAL_GATEWAY_MIRROR = Symbol("functionalGatewayMirror");
+
 export interface FunctionalGatewayMirrorsDeps {
   /** Ordered list of passthrough gateway provider ids to consider as mirrors. */
   gatewayProviderIds: string[];
@@ -40,9 +42,14 @@ interface GatewayMirrorCatalogEntry {
   root?: unknown;
   name?: unknown;
   display_name?: unknown;
+  [FUNCTIONAL_GATEWAY_MIRROR]?: true;
   [key: string]: unknown;
 }
 
+export function isFunctionalGatewayMirror(model: GatewayMirrorCatalogEntry): boolean {
+  return model?.[FUNCTIONAL_GATEWAY_MIRROR] === true;
+}
+
 /**
  * Append `<gatewayAlias>/<originalId>` mirror entries for every eligible model.
  * Returns the original array reference unchanged when nothing is eligible.
@@ -88,14 +95,14 @@ export function appendFunctionalGatewayMirrors<T extends GatewayMirrorCatalogEnt
     // Skip if the id already starts with this gateway alias (would double-prefix).
     if (id.startsWith(`${chosenAlias}/`)) continue;
 
-    const label =
-      typeof model.name === "string" && model.name ? model.name : modelId;
+    const label = typeof model.name === "string" && model.name ? model.name : modelId;
     aliases.push({
       ...model,
       id: aliasId,
       root: id,
       owned_by: chosenProvider,
       display_name: `${label}${FUNCTIONAL_GATEWAY_MIRROR_SUFFIX}${chosenProvider})`,
+      [FUNCTIONAL_GATEWAY_MIRROR]: true,
     } as T);
   }
 

src/app/api/v1/models/catalogResponse.ts

@@ -12,7 +12,10 @@ import { appendNoThinkingVariants } from "@omniroute/open-sse/utils/noThinkingAl
 import { appendClaudeEffortVariants } from "@omniroute/open-sse/utils/claudeEffortVariants";
 import { appendSyncedEffortVariants } from "@omniroute/open-sse/utils/syncedEffortVariants";
 import { appendCcDiscoveryAliases } from "@omniroute/open-sse/utils/ccDiscoveryAliases";
-import { appendFunctionalGatewayMirrors } from "@omniroute/open-sse/utils/functionalGatewayMirrors";
+import {
+  appendFunctionalGatewayMirrors,
+  isFunctionalGatewayMirror,
+} from "@omniroute/open-sse/utils/functionalGatewayMirrors";
 import { isCcAliasGlobalEnabled, getCcAliasSettingsBulk } from "@/lib/db/ccDiscoveryAliases";
 import { buildCcAliasPredicate } from "./ccAliasPredicate";
 import {
@@ -29,6 +32,7 @@ import {
   enrichCatalogModelEntry,
 } from "@/lib/modelMetadataRegistry";
 import { isModelCatalogNamesEnabled } from "@/shared/utils/featureFlags";
+import { extractApiKey } from "@/sse/services/auth";
 import { maybeOmitCatalogModelName } from "./catalogHelpers";
 import { isCodexModelCatalogClient } from "./catalogRequest";
 
@@ -148,6 +152,31 @@ export function applyCatalogPostFilters(
   return finalModels;
 }
 
+/**
+ * Functional-gateway mirrors remain gateway-prefixed through request-time policy
+ * enforcement, so they must authorize that final public ID. Other synthetic IDs
+ * are normalized back to their base model before policy enforcement and keep the
+ * base model's permission by design.
+ */
+export async function filterUnauthorizedFunctionalGatewayMirrors(
+  models: Array<Record<string, unknown>>,
+  apiKey: string,
+  isModelAllowed: (key: string, modelId: string) => Promise<boolean>
+): Promise<Array<Record<string, unknown>>> {
+  const filtered: Array<Record<string, unknown>> = [];
+  for (const model of models) {
+    if (!isFunctionalGatewayMirror(model)) {
+      filtered.push(model);
+      continue;
+    }
+
+    if (typeof model.id === "string" && (await isModelAllowed(apiKey, model.id))) {
+      filtered.push(model);
+    }
+  }
+  return filtered;
+}
+
 /**
  * Enrich the selected models and serialise the catalog response.
  *
@@ -156,12 +185,25 @@ export function applyCatalogPostFilters(
  * context length for non-combo entries; the quota path passes a no-op because its
  * entries are all `owned_by: "combo"`, which skips enrichment entirely.
  */
-export function finalizeCatalogResponse(
+export async function finalizeCatalogResponse(
   request: Request,
   finalModels: Array<Record<string, unknown>>,
   getContextFallback: (model: Record<string, unknown>) => number | undefined,
   headers: Record<string, string>
-): Response {
+): Promise<Response> {
+  const apiKey = extractApiKey(request);
+  if (apiKey) {
+    const { getApiKeyMetadata, isModelAllowedForKey } = await import("@/lib/db/apiKeys");
+    const keyMeta = await getApiKeyMetadata(apiKey);
+    if (keyMeta && keyMeta.id !== "env-key" && !keyMeta.allowedQuotas?.length) {
+      finalModels = await filterUnauthorizedFunctionalGatewayMirrors(
+        finalModels,
+        apiKey,
+        isModelAllowedForKey
+      );
+    }
+  }
+
   const includeModelNames = isModelCatalogNamesEnabled();
   const enrichedModels = disambiguateCatalogModelNames(
     finalModels.map((model) => {

tests/unit/models-catalog-functional-gateway-permissions.test.ts

@@ -0,0 +1,118 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TEST_DATA_DIR = fs.mkdtempSync(
+  path.join(os.tmpdir(), "omniroute-model-catalog-gateway-permissions-")
+);
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.API_KEY_SECRET = process.env.API_KEY_SECRET || "catalog-gateway-test-secret";
+
+const core = await import("../../src/lib/db/core.ts");
+const providersDb = await import("../../src/lib/db/providers.ts");
+const apiKeysDb = await import("../../src/lib/db/apiKeys.ts");
+const featureFlagsDb = await import("../../src/lib/db/featureFlags.ts");
+const functionalGatewayDb = await import("../../src/lib/db/functionalGatewayMirrors.ts");
+const v1ModelsCatalog = await import("../../src/app/api/v1/models/catalog.ts");
+
+async function resetStorage() {
+  core.resetDbInstance();
+  apiKeysDb.resetApiKeyState();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+  v1ModelsCatalog.__resetCatalogBuilderRunsForTest();
+}
+
+async function seedConnection(
+  provider: string,
+  overrides: {
+    authType?: string;
+    apiKey?: string | null;
+    accessToken?: string;
+  } = {}
+) {
+  return providersDb.createProviderConnection({
+    provider,
+    authType: overrides.authType || "apikey",
+    name: `${provider}-catalog-permissions`,
+    apiKey: overrides.apiKey === undefined ? "sk-test" : overrides.apiKey,
+    accessToken: overrides.accessToken,
+    isActive: true,
+    testStatus: "active",
+    providerSpecificData: {},
+  });
+}
+
+function catalogIds(body: unknown): Set<string> {
+  if (!body || typeof body !== "object" || !("data" in body) || !Array.isArray(body.data)) {
+    return new Set();
+  }
+  return new Set(
+    body.data.flatMap((item) =>
+      item && typeof item === "object" && "id" in item && typeof item.id === "string"
+        ? [item.id]
+        : []
+    )
+  );
+}
+
+test.beforeEach(async () => {
+  await resetStorage();
+});
+
+test.after(() => {
+  core.resetDbInstance();
+  apiKeysDb.resetApiKeyState();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+});
+
+test("v1 models catalog requires independent permission for functional gateway mirrors", async () => {
+  await seedConnection("kimi-coding", {
+    authType: "oauth",
+    apiKey: null,
+    accessToken: "kimi-access",
+  });
+  await seedConnection("agentrouter");
+  featureFlagsDb.setFeatureFlagOverride("EXPOSE_FUNCTIONAL_GATEWAY_MIRRORS", "true");
+  functionalGatewayDb.setFunctionalGatewayProviderSetting("agentrouter", "on");
+
+  const restrictedKey = await apiKeysDb.createApiKey(
+    "catalog-functional-mirror",
+    "machine-functional"
+  );
+  await apiKeysDb.updateApiKeyPermissions(restrictedKey.id, {
+    allowedModels: ["kimi-coding/*"],
+  });
+
+  const restrictedResponse = await v1ModelsCatalog.getUnifiedModelsResponse(
+    new Request("http://localhost/api/v1/models", {
+      headers: { Authorization: `Bearer ${restrictedKey.key}` },
+    })
+  );
+  const restrictedIds = catalogIds(await restrictedResponse.json());
+
+  assert.equal(restrictedResponse.status, 200);
+  assert.equal(restrictedIds.has("kmc/k3"), true);
+  assert.equal(restrictedIds.has("agentrouter/kmc/k3"), false);
+
+  const gatewayKey = await apiKeysDb.createApiKey(
+    "catalog-functional-mirror-allowed",
+    "machine-functional-allowed"
+  );
+  await apiKeysDb.updateApiKeyPermissions(gatewayKey.id, {
+    allowedModels: ["kimi-coding/*", "agentrouter/*"],
+  });
+
+  const gatewayResponse = await v1ModelsCatalog.getUnifiedModelsResponse(
+    new Request("http://localhost/api/v1/models", {
+      headers: { Authorization: `Bearer ${gatewayKey.key}` },
+    })
+  );
+  const gatewayIds = catalogIds(await gatewayResponse.json());
+
+  assert.equal(gatewayResponse.status, 200);
+  assert.equal(gatewayIds.has("kmc/k3"), true);
+  assert.equal(gatewayIds.has("agentrouter/kmc/k3"), true);
+});

tests/unit/models-catalog-functional-gateway.test.ts

@@ -1,6 +1,9 @@
 import { test, after } from "node:test";
 import assert from "node:assert/strict";
-import { applyCatalogPostFilters } from "../../src/app/api/v1/models/catalogResponse.ts";
+import {
+  applyCatalogPostFilters,
+  filterUnauthorizedFunctionalGatewayMirrors,
+} from "../../src/app/api/v1/models/catalogResponse.ts";
 import {
   removeFeatureFlagOverride,
   setFeatureFlagOverride,
@@ -33,6 +36,47 @@ test("catalog post-filters do not add mirrors when gate off (default)", () => {
   assert.deepEqual(out, models);
 });
 
+test("final catalog permission filtering does not let a mirror inherit base access", async () => {
+  setFeatureFlagOverride(FLAG_KEY, "true");
+  setFunctionalGatewayProviderSetting("agentrouter", "on");
+
+  const models = [{ id: "kmc/k3", owned_by: "kimi-coding", root: "k3" }];
+  const withMirror = applyCatalogPostFilters(makeRequest(), models, {
+    connections: [
+      {
+        id: "conn-1",
+        provider: "agentrouter",
+        isActive: true,
+        providerSpecificData: {},
+      },
+    ],
+    prefixMode: "dual",
+    aliasToProviderId: {},
+  });
+  const allowed = await filterUnauthorizedFunctionalGatewayMirrors(
+    withMirror,
+    "restricted-key",
+    async (_key, modelId) => modelId === "kmc/k3"
+  );
+
+  assert.deepEqual(
+    allowed.map((model) => model.id),
+    ["kmc/k3"],
+    "a synthesized gateway mirror must authorize its own public ID"
+  );
+
+  const gatewayAllowed = await filterUnauthorizedFunctionalGatewayMirrors(
+    withMirror,
+    "gateway-key",
+    async (_key, modelId) => modelId === "agentrouter/kmc/k3"
+  );
+  assert.deepEqual(
+    gatewayAllowed.map((model) => model.id),
+    ["kmc/k3", "agentrouter/kmc/k3"],
+    "an independently authorized gateway mirror must remain visible"
+  );
+});
+
 test("catalog post-filters synthesize a gateway mirror when gate on and gateway has a connection", () => {
   setFeatureFlagOverride(FLAG_KEY, "true");
   setFunctionalGatewayProviderSetting("agentrouter", "on");