feat(api): add opt-in API-key provider quota-policy bypass scope (#5731)

Adds an opt-in per-API-key scope (policy:bypass-provider-quota) that lets a key skip provider/account-side quota cutoffs during routing. Operator USD budgets/usage limits still enforced unconditionally (fail-closed, before the bypass). Default-off; UI toggle + badge in API Manager. Integrated into release/v3.8.43.

tests/unit/api-key-provider-quota-bypass-scope.test.ts

@@ -0,0 +1,34 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  API_KEY_BYPASS_PROVIDER_QUOTA_SCOPE,
+  hasProviderQuotaBypassScope,
+} from "../../src/shared/constants/apiKeyPolicyScopes.ts";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+test("provider quota bypass scope helper is explicit and strict", () => {
+  assert.equal(API_KEY_BYPASS_PROVIDER_QUOTA_SCOPE, "policy:bypass-provider-quota");
+  assert.equal(hasProviderQuotaBypassScope([API_KEY_BYPASS_PROVIDER_QUOTA_SCOPE]), true);
+  assert.equal(hasProviderQuotaBypassScope(["policy:other"]), false);
+  assert.equal(hasProviderQuotaBypassScope(null), false);
+});
+
+test("chat handler maps API key provider quota bypass scope to auth bypass option", () => {
+  const source = fs.readFileSync(path.join(repoRoot, "src/sse/handlers/chat.ts"), "utf8");
+
+  assert.match(source, /hasProviderQuotaBypassScope\(apiKeyInfo\?\.scopes\)/);
+  assert.match(source, /bypassProviderQuotaPolicy[\s\S]*bypassQuotaPolicy: true/);
+  assert.match(source, /relayOptions[\s\S]*bypassProviderQuotaPolicy: true/);
+});
+
+test("auto combo disables hard provider quota cutoffs when relay requests bypass", () => {
+  const source = fs.readFileSync(path.join(repoRoot, "open-sse/services/combo.ts"), "utf8");
+
+  assert.match(source, /relayOptions\?\.bypassProviderQuotaPolicy === true/);
+  assert.match(source, /quotaPreflight:[\s\S]*enabled: false/);
+});

tests/unit/api-manager-scope-preservation.test.ts

@@ -9,10 +9,18 @@ import {
   SELF_ACCOUNT_QUOTA_SCOPE,
   SELF_USAGE_SCOPE,
 } from "../../src/shared/constants/selfServiceScopes.ts";
+import { API_KEY_BYPASS_PROVIDER_QUOTA_SCOPE } from "../../src/shared/constants/apiKeyPolicyScopes.ts";
 
 test("create scopes enable own usage by default without shared account quota", () => {
   assert.deepEqual(buildApiKeyCreateScopes({ manageEnabled: false }), [SELF_USAGE_SCOPE]);
   assert.deepEqual(buildApiKeyCreateScopes({ manageEnabled: true }), ["manage", SELF_USAGE_SCOPE]);
+  assert.deepEqual(
+    buildApiKeyCreateScopes({
+      manageEnabled: false,
+      bypassProviderQuotaPolicyEnabled: true,
+    }),
+    [SELF_USAGE_SCOPE, API_KEY_BYPASS_PROVIDER_QUOTA_SCOPE]
+  );
   assert.deepEqual(
     buildApiKeyCreateScopes({
       manageEnabled: false,
@@ -28,6 +36,7 @@ test("permission scope merge preserves unrelated scopes while toggling managed s
     manageEnabled: true,
     selfUsageEnabled: true,
     selfAccountQuotaEnabled: true,
+    bypassProviderQuotaPolicyEnabled: true,
   });
 
   assert.deepEqual(scopes, [
@@ -35,6 +44,7 @@ test("permission scope merge preserves unrelated scopes while toggling managed s
     SELF_USAGE_SCOPE,
     "manage",
     SELF_ACCOUNT_QUOTA_SCOPE,
+    API_KEY_BYPASS_PROVIDER_QUOTA_SCOPE,
   ]);
 });
 
@@ -45,8 +55,29 @@ test("permission scope merge removes shared quota visibility when own usage is d
       manageEnabled: false,
       selfUsageEnabled: false,
       selfAccountQuotaEnabled: true,
+      bypassProviderQuotaPolicyEnabled: false,
     }
   );
 
   assert.deepEqual(scopes, ["custom:scope"]);
 });
+
+test("permission scope merge toggles provider quota policy bypass without dropping custom scopes", () => {
+  const enabled = mergeApiKeyPermissionScopes(["custom:scope"], {
+    manageEnabled: false,
+    selfUsageEnabled: false,
+    selfAccountQuotaEnabled: false,
+    bypassProviderQuotaPolicyEnabled: true,
+  });
+
+  assert.deepEqual(enabled, ["custom:scope", API_KEY_BYPASS_PROVIDER_QUOTA_SCOPE]);
+
+  const disabled = mergeApiKeyPermissionScopes(enabled, {
+    manageEnabled: false,
+    selfUsageEnabled: false,
+    selfAccountQuotaEnabled: false,
+    bypassProviderQuotaPolicyEnabled: false,
+  });
+
+  assert.deepEqual(disabled, ["custom:scope"]);
+});