plugin-ai-api 1.0.21 → 1.0.23

package/dist/server/routes/completions.js

@@ -31,12 +31,12 @@ __export(completions_exports, {
 module.exports = __toCommonJS(completions_exports);
 var import_openai_format = require("../utils/openai-format");
 var import_resolve_service = require("../utils/resolve-service");
+var import_user_permissions = require("../utils/user-permissions");
 var import_streaming = require("../utils/streaming");
 var import_usage = require("../usage");
 var import_billing = require("../billing");
 var import_app_observability = require("../utils/app-observability");
 async function handleCompletions(ctx, plugin) {
-  var _a;
   const body = ctx.request.body;
   if (!(body == null ? void 0 : body.model)) {
     ctx.status = 400;
@@ -89,20 +89,8 @@ async function handleCompletions(ctx, plugin) {
       return;
     }
     const config = await ctx.db.getRepository("aiApiConfig").findOne();
-    if ((_a = config == null ? void 0 : config.enabledLlmServices) == null ? void 0 : _a.length) {
-      const serviceName = service.name;
-      const serviceTitle = service.title;
-      const isAllowed = config.enabledLlmServices.some((s) => s === serviceName || s === serviceTitle);
-      if (!isAllowed) {
-        ctx.status = 403;
-        ctx.body = (0, import_openai_format.toOpenAIError)(
-          403,
-          `LLM service '${service.title || service.name}' is not enabled for API access`,
-          "invalid_request_error",
-          "model_not_available"
-        );
-        return;
-      }
+    if (!await (0, import_user_permissions.enforceModelAccess)(ctx, config == null ? void 0 : config.enabledLlmServices, service, modelId)) {
+      return;
     }
     const providerMeta = aiPlugin.aiManager.llmProviders.get(service.provider);
     if (!providerMeta) {
@@ -143,7 +131,14 @@ async function handleCompletions(ctx, plugin) {
     const chatModel = provider.createModel();
     (0, import_billing.markLlmProviderAttempted)(ctx);
     if (stream) {
-      await handleStreamingTextCompletion(ctx, chatModel, langchainMessages, completionId, body.model);
+      await handleStreamingTextCompletion(
+        ctx,
+        chatModel,
+        langchainMessages,
+        completionId,
+        body.model,
+        body.stream_options
+      );
     } else {
       await handleNonStreamingTextCompletion(ctx, chatModel, langchainMessages, completionId, body.model);
     }
@@ -193,7 +188,7 @@ async function handleNonStreamingTextCompletion(ctx, chatModel, messages, comple
     usage: usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
   };
 }
-async function handleStreamingTextCompletion(ctx, chatModel, messages, completionId, modelName) {
+async function handleStreamingTextCompletion(ctx, chatModel, messages, completionId, modelName, streamOptions) {
   ctx.set({
     "Content-Type": "text/event-stream",
     "Cache-Control": "no-cache",
@@ -205,7 +200,10 @@ async function handleStreamingTextCompletion(ctx, chatModel, messages, completio
   let usage;
   let providerRequestId;
   try {
-    const stream = await chatModel.stream(messages, { signal: requestAbort.signal });
+    const stream = await chatModel.stream(messages, {
+      stream_options: { ...streamOptions, include_usage: true },
+      signal: requestAbort.signal
+    });
     for await (const chunk of stream) {
       if (requestAbort.signal.aborted) throw requestAbort.signal.reason;
       let text = "";
@@ -232,7 +230,8 @@ async function handleStreamingTextCompletion(ctx, chatModel, messages, completio
                 logprobs: null,
                 finish_reason: null
               }
-            ]
+            ],
+            usage: null
           })
         );
       }
@@ -256,9 +255,23 @@ async function handleStreamingTextCompletion(ctx, chatModel, messages, completio
             logprobs: null,
             finish_reason: "stop"
           }
-        ]
+        ],
+        usage: null
       })
     );
+    if (usage) {
+      await (0, import_streaming.writeResponse)(
+        ctx,
+        (0, import_openai_format.formatSSE)(
+          (0, import_openai_format.toOpenAIUsageChunk)({
+            id: completionId,
+            model: modelName,
+            object: "text_completion",
+            usage
+          })
+        )
+      );
+    }
     await (0, import_streaming.writeResponse)(ctx, (0, import_openai_format.formatSSEDone)());
     (0, import_usage.setAiApiUsageResult)(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
     ctx.state.aiApiStreamResult = { succeeded: true, id: completionId };

package/dist/server/routes/embeddings.js

@@ -31,9 +31,9 @@ __export(embeddings_exports, {
 module.exports = __toCommonJS(embeddings_exports);
 var import_openai_format = require("../utils/openai-format");
 var import_resolve_service = require("../utils/resolve-service");
+var import_user_permissions = require("../utils/user-permissions");
 var import_usage = require("../usage");
 async function handleEmbeddings(ctx, plugin) {
-  var _a;
   const body = ctx.request.body;
   if (!(body == null ? void 0 : body.model)) {
     ctx.status = 400;
@@ -102,23 +102,15 @@ async function handleEmbeddings(ctx, plugin) {
     );
     return;
   }
+  let globalEnabledServices = [];
   try {
     const config = await ctx.db.getRepository("aiApiConfig").findOne();
-    if ((_a = config == null ? void 0 : config.enabledLlmServices) == null ? void 0 : _a.length) {
-      const allowed = config.enabledLlmServices.some((s) => s === service.name || s === service.title);
-      if (!allowed) {
-        ctx.status = 403;
-        ctx.body = (0, import_openai_format.toOpenAIError)(
-          403,
-          `LLM service '${service.title || service.name}' is not enabled for API access`,
-          "invalid_request_error",
-          "model_not_available"
-        );
-        return;
-      }
-    }
+    globalEnabledServices = (config == null ? void 0 : config.enabledLlmServices) ?? [];
   } catch {
   }
+  if (!await (0, import_user_permissions.enforceModelAccess)(ctx, globalEnabledServices, service, modelId)) {
+    return;
+  }
   const aiPlugin = ctx.app.pm.get("ai");
   if (!aiPlugin) {
     ctx.status = 500;

package/dist/server/routes/models.js

@@ -32,6 +32,7 @@ __export(models_exports, {
 });
 module.exports = __toCommonJS(models_exports);
 var import_openai_format = require("../utils/openai-format");
+var import_user_permissions = require("../utils/user-permissions");
 async function handleListModels(ctx, plugin) {
   var _a;
   try {
@@ -50,15 +51,22 @@ async function handleListModels(ctx, plugin) {
       filter,
       sort: "sort"
     });
+    const scope = await (0, import_user_permissions.resolveUserAccessScope)(ctx);
+    if (scope.lookupFailed) {
+      respondPermissionCheckFailed(ctx);
+      return;
+    }
     const metadataMap = await loadModelMetadata(ctx);
     const now = Math.floor(Date.now() / 1e3);
     const models = [];
     for (const service of services) {
       if (service.enabled === false) continue;
+      if (!(0, import_user_permissions.isServiceAllowed)(scope, config == null ? void 0 : config.enabledLlmServices, service)) continue;
       const enabledModels = resolveEnabledModels(service);
       const serviceLabel = service.title || service.name;
       for (const model of enabledModels) {
         const fullId = `${service.name}/${model.value}`;
+        if (!(0, import_user_permissions.isModelAllowed)(scope, fullId)) continue;
         const meta = metadataMap.get(fullId);
         if (meta && meta.enabled === false) continue;
         models.push(buildModelObject(fullId, now, serviceLabel, meta));
@@ -87,16 +95,23 @@ async function handleGetModel(ctx, modelId, plugin) {
       filter,
       sort: "sort"
     });
+    const scope = await (0, import_user_permissions.resolveUserAccessScope)(ctx);
+    if (scope.lookupFailed) {
+      respondPermissionCheckFailed(ctx);
+      return;
+    }
     const metadataMap = await loadModelMetadata(ctx);
     const now = Math.floor(Date.now() / 1e3);
     let found = null;
     for (const service of services) {
       if (service.enabled === false) continue;
+      if (!(0, import_user_permissions.isServiceAllowed)(scope, config == null ? void 0 : config.enabledLlmServices, service)) continue;
       const enabledModels = resolveEnabledModels(service);
       const serviceLabel = service.title || service.name;
       for (const model of enabledModels) {
         const fullId = `${service.name}/${model.value}`;
         if (fullId === modelId || model.value === modelId) {
+          if (!(0, import_user_permissions.isModelAllowed)(scope, fullId)) continue;
           const meta = metadataMap.get(fullId);
           if (meta && meta.enabled === false) continue;
           found = buildModelObject(fullId, now, serviceLabel, meta);
@@ -118,6 +133,15 @@ async function handleGetModel(ctx, modelId, plugin) {
     ctx.body = (0, import_openai_format.toOpenAIError)(500, "Failed to retrieve model", "server_error");
   }
 }
+function respondPermissionCheckFailed(ctx) {
+  ctx.status = 503;
+  ctx.body = (0, import_openai_format.toOpenAIError)(
+    503,
+    "Unable to verify LLM permissions for this user. Please retry shortly.",
+    "service_unavailable",
+    "permission_check_failed"
+  );
+}
 async function loadModelMetadata(ctx) {
   var _a, _b;
   const map = /* @__PURE__ */ new Map();

package/dist/server/utils/openai-format.js

@@ -43,7 +43,8 @@ __export(openai_format_exports, {
   toOpenAIEmbeddingsResponse: () => toOpenAIEmbeddingsResponse,
   toOpenAIError: () => toOpenAIError,
   toOpenAIResponse: () => toOpenAIResponse,
-  toOpenAIStreamChunk: () => toOpenAIStreamChunk
+  toOpenAIStreamChunk: () => toOpenAIStreamChunk,
+  toOpenAIUsageChunk: () => toOpenAIUsageChunk
 });
 module.exports = __toCommonJS(openai_format_exports);
 var import_crypto = __toESM(require("crypto"));
@@ -116,7 +117,19 @@ function toOpenAIStreamChunk(options) {
         logprobs: null,
         finish_reason: finishReason
       }
-    ]
+    ],
+    usage: null
+  };
+}
+function toOpenAIUsageChunk(options) {
+  const { id, model, usage, object = "chat.completion.chunk" } = options;
+  return {
+    id,
+    object,
+    created: Math.floor(Date.now() / 1e3),
+    model,
+    choices: [],
+    usage
   };
 }
 function toOpenAIEmbeddingsResponse(options) {
@@ -154,5 +167,6 @@ function formatSSEDone() {
   toOpenAIEmbeddingsResponse,
   toOpenAIError,
   toOpenAIResponse,
-  toOpenAIStreamChunk
+  toOpenAIStreamChunk,
+  toOpenAIUsageChunk
 });

package/dist/server/utils/user-permissions.js

@@ -0,0 +1,160 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var user_permissions_exports = {};
+__export(user_permissions_exports, {
+  buildAccessScope: () => buildAccessScope,
+  enforceModelAccess: () => enforceModelAccess,
+  invalidateUserPermissionCache: () => invalidateUserPermissionCache,
+  isModelAllowed: () => isModelAllowed,
+  isServiceAllowed: () => isServiceAllowed,
+  resolveUserAccessScope: () => resolveUserAccessScope
+});
+module.exports = __toCommonJS(user_permissions_exports);
+var import_openai_format = require("./openai-format");
+const SCOPE_TTL_MS = 15e3;
+const scopeCache = /* @__PURE__ */ new Map();
+const NO_RECORD_SCOPE = {
+  hasUserRecord: false,
+  denyAll: false,
+  allowedServices: null,
+  allowAllModels: true,
+  allowedModels: /* @__PURE__ */ new Set(),
+  lookupFailed: false
+};
+const LOOKUP_FAILED_SCOPE = { ...NO_RECORD_SCOPE, denyAll: true, lookupFailed: true };
+function invalidateUserPermissionCache(userId) {
+  if (userId === void 0 || userId === null) {
+    scopeCache.clear();
+    return;
+  }
+  const suffix = `:${userId}`;
+  for (const key of scopeCache.keys()) {
+    if (key.endsWith(suffix)) scopeCache.delete(key);
+  }
+}
+function valueOf(row, name) {
+  if (!row) return void 0;
+  const candidate = row;
+  if (typeof candidate.get === "function") return candidate.get(name);
+  return row[name];
+}
+function toStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item) => typeof item === "string" && item.length > 0);
+}
+function buildAccessScope(row) {
+  if (!row) return NO_RECORD_SCOPE;
+  if (valueOf(row, "enabled") === false) {
+    return { ...NO_RECORD_SCOPE, hasUserRecord: true, denyAll: true, allowedServices: [] };
+  }
+  return {
+    hasUserRecord: true,
+    denyAll: false,
+    allowedServices: toStringArray(valueOf(row, "allowedLlmServices")),
+    allowAllModels: valueOf(row, "allowAllModels") !== false,
+    allowedModels: new Set(toStringArray(valueOf(row, "allowedModels"))),
+    lookupFailed: false
+  };
+}
+async function resolveUserAccessScope(ctx) {
+  var _a, _b, _c, _d;
+  const userId = (_a = ctx.state.currentUser) == null ? void 0 : _a.id;
+  if (userId === void 0 || userId === null) return NO_RECORD_SCOPE;
+  const key = `${((_b = ctx.app) == null ? void 0 : _b.name) ?? "main"}:${userId}`;
+  const cached = scopeCache.get(key);
+  if (cached && cached.expiresAt > Date.now()) return cached.scope;
+  let scope;
+  try {
+    const row = await ctx.db.getRepository("aiApiUserPermissions").findOne({ filter: { userId } });
+    scope = buildAccessScope(row);
+  } catch (err) {
+    (_d = (_c = ctx.log) == null ? void 0 : _c.error) == null ? void 0 : _d.call(_c, "AI API user permissions lookup failed, denying access:", err);
+    return LOOKUP_FAILED_SCOPE;
+  }
+  scopeCache.set(key, { scope, expiresAt: Date.now() + SCOPE_TTL_MS });
+  return scope;
+}
+function matchesService(list, serviceName, serviceTitle) {
+  return list.some((entry) => entry === serviceName || entry === serviceTitle);
+}
+function isServiceAllowed(scope, globalEnabledServices, service) {
+  if (scope.denyAll) return false;
+  const globalList = toStringArray(globalEnabledServices);
+  if (globalList.length && !matchesService(globalList, service.name, service.title)) return false;
+  if (!scope.hasUserRecord) return true;
+  return matchesService(scope.allowedServices ?? [], service.name, service.title);
+}
+function isModelAllowed(scope, fullModelId) {
+  if (scope.denyAll) return false;
+  if (!scope.hasUserRecord) return true;
+  if (scope.allowAllModels) return true;
+  return scope.allowedModels.has(fullModelId);
+}
+async function enforceModelAccess(ctx, globalEnabledServices, service, modelId) {
+  const scope = await resolveUserAccessScope(ctx);
+  const serviceLabel = service.title || service.name;
+  if (scope.lookupFailed) {
+    ctx.status = 503;
+    ctx.body = (0, import_openai_format.toOpenAIError)(
+      503,
+      "Unable to verify LLM permissions for this user. Please retry shortly.",
+      "service_unavailable",
+      "permission_check_failed"
+    );
+    return false;
+  }
+  if (!isServiceAllowed(scope, globalEnabledServices, service)) {
+    ctx.status = 403;
+    ctx.body = (0, import_openai_format.toOpenAIError)(
+      403,
+      `LLM service '${serviceLabel}' is not enabled for API access`,
+      "permission_denied",
+      "model_not_available"
+    );
+    return false;
+  }
+  if (!isModelAllowed(scope, `${service.name}/${modelId}`)) {
+    ctx.status = 403;
+    ctx.body = (0, import_openai_format.toOpenAIError)(
+      403,
+      `Model '${service.name}/${modelId}' is not permitted for this user. Use GET /v1/models to see available models.`,
+      "permission_denied",
+      "model_not_available"
+    );
+    return false;
+  }
+  return true;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildAccessScope,
+  enforceModelAccess,
+  invalidateUserPermissionCache,
+  isModelAllowed,
+  isServiceAllowed,
+  resolveUserAccessScope
+});

package/dist/swagger.js

@@ -78,7 +78,7 @@ var swagger_default = {
       get: {
         tags: ["ai-llm"],
         summary: "List available models",
-        description: "Returns all LLM models available across registered services. Model IDs are formatted as `serviceName/modelId`.",
+        description: "Returns the LLM models available to the authenticated caller across registered services. Model IDs are formatted as `serviceName/modelId`.\n\nThe catalog is user-scoped: it starts from `enabledLlmServices` in the AI API configuration, then narrows to the caller's `aiApiUserPermissions` record when one exists. A user grant can only narrow the global whitelist, never widen it, so two users may receive different lists from the same request.",
         security: [{ BearerAuth: [] }],
         responses: {
           200: {
@@ -105,6 +105,7 @@ var swagger_default = {
       get: {
         tags: ["ai-llm"],
         summary: "Get model details",
+        description: "User-scoped in the same way as `GET /v1/models`: a model the caller is not granted is reported as not found rather than disclosed.",
         security: [{ BearerAuth: [] }],
         parameters: [
           {
@@ -124,7 +125,7 @@ var swagger_default = {
               }
             }
           },
-          404: { description: "Model not found" }
+          404: { description: "Model not found, or not available to this user" }
         }
       }
     },
@@ -272,7 +273,7 @@ var swagger_default = {
           enabledLlmServices: {
             type: "array",
             items: { type: "string" },
-            description: "List of enabled LLM service names"
+            description: "List of enabled LLM service names. This is the outer bound for every caller; per-user `aiApiUserPermissions` records can only narrow it further."
           },
           rateLimitPerMinute: {
             type: "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-ai-api",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "main": "dist/server/index.js",
   "dependencies": {},
   "peerDependencies": {
@@ -30,4 +30,4 @@
     "server.d.ts"
   ],
   "license": "Apache-2.0"
-}
+}

package/src/client/__tests__/settings-registration.test.tsx

@@ -0,0 +1,69 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Application } from '@nocobase/client';
+import { describe, expect, it } from 'vitest';
+import { AI_API_ACL_SNIPPET, AI_API_USER_PERMISSIONS_SNIPPET } from '../../constants';
+import { PluginAiApiClient } from '../plugin';
+
+describe('AI API v1 settings registration', () => {
+  async function loadPlugin() {
+    const app = new Application({});
+    await new PluginAiApiClient({}, app).load();
+    return app;
+  }
+
+  it('registers the same ordered settings tabs and ACL boundaries as v2', async () => {
+    const app = await loadPlugin();
+    app.pluginSettingsManager.setAclSnippets([]);
+
+    const menu = app.pluginSettingsManager.get('ai-api');
+
+    expect(menu?.children?.map((item) => item.name)).toEqual([
+      'ai-api.config',
+      'ai-api.model-pricing',
+      'ai-api.model-metadata',
+      'ai-api.user-permissions',
+      'ai-api.user-quotas',
+      'ai-api.usage',
+    ]);
+    expect(app.pluginSettingsManager.getAclSnippet('ai-api.user-permissions')).toBe(AI_API_USER_PERMISSIONS_SNIPPET);
+    expect(app.pluginSettingsManager.getRoutePath('ai-api.user-permissions')).toBe(
+      '/admin/settings/ai-api/user-permissions',
+    );
+    expect(app.pluginSettingsManager.getList().map((item) => item.name)).not.toContain('ai-api-user-permissions');
+  });
+
+  it('requires access to the legacy parent before exposing the user permissions tab', async () => {
+    const app = await loadPlugin();
+    app.pluginSettingsManager.setAclSnippets([`!${AI_API_ACL_SNIPPET}`]);
+
+    expect(app.pluginSettingsManager.getList()).toEqual([]);
+  });
+
+  it('hides only the user permissions tab when its own snippet is denied', async () => {
+    const app = await loadPlugin();
+    app.pluginSettingsManager.setAclSnippets([`!${AI_API_USER_PERMISSIONS_SNIPPET}`]);
+
+    expect(app.pluginSettingsManager.get('ai-api')?.children?.map((item) => item.name)).toEqual([
+      'ai-api.config',
+      'ai-api.model-pricing',
+      'ai-api.model-metadata',
+      'ai-api.user-quotas',
+      'ai-api.usage',
+    ]);
+  });
+
+  it('hides both settings surfaces when both snippets are denied', async () => {
+    const app = await loadPlugin();
+    app.pluginSettingsManager.setAclSnippets([`!${AI_API_ACL_SNIPPET}`, `!${AI_API_USER_PERMISSIONS_SNIPPET}`]);
+
+    expect(app.pluginSettingsManager.getList()).toEqual([]);
+  });
+});

package/src/client/plugin.tsx

@@ -9,12 +9,13 @@
 
 import { Plugin, lazy } from '@nocobase/client';
 import PluginACLClient from '@nocobase/plugin-acl/client';
-import { AI_API_ACL_SNIPPET } from '../constants';
+import { AI_API_ACL_SNIPPET, AI_API_USER_PERMISSIONS_SNIPPET } from '../constants';
 import React from 'react';
 
 const AiApiConfigPage = React.lazy(() => import('../client-v2/pages/GeneralPage'));
 const AiApiModelPricingPage = React.lazy(() => import('../client-v2/pages/ModelPricingPage'));
 const AiApiModelMetadataPage = React.lazy(() => import('../client-v2/pages/ModelMetadataPage'));
+const AiApiUserPermissionsPage = React.lazy(() => import('../client-v2/pages/UserPermissionsPage'));
 const AiApiUserQuotasPage = React.lazy(() => import('../client-v2/pages/UserQuotasPage'));
 const AiApiUsagePage = React.lazy(() => import('../client-v2/pages/UsagePage'));
 const { AiApiRolePermissions } = lazy(() => import('./components/AiApiRolePermissions'), 'AiApiRolePermissions');
@@ -48,18 +49,28 @@ export class PluginAiApiClient extends Plugin {
       sort: 3,
     });
 
+    // Keep the legacy settings layout aligned with client-v2. The v1 settings
+    // manager evaluates the parent ACL first, so this tab additionally requires
+    // access to the AI API settings parent even though it keeps its own snippet.
+    this.app.pluginSettingsManager.add('ai-api.user-permissions', {
+      title: this.t('User LLM permissions'),
+      Component: AiApiUserPermissionsPage,
+      aclSnippet: AI_API_USER_PERMISSIONS_SNIPPET,
+      sort: 4,
+    });
+
     this.app.pluginSettingsManager.add('ai-api.user-quotas', {
       title: this.t('User quotas'),
       Component: AiApiUserQuotasPage,
       aclSnippet: AI_API_ACL_SNIPPET,
-      sort: 4,
+      sort: 5,
     });
 
     this.app.pluginSettingsManager.add('ai-api.usage', {
       title: this.t('Usage'),
       Component: AiApiUsagePage,
       aclSnippet: AI_API_ACL_SNIPPET,
-      sort: 5,
+      sort: 6,
     });
 
     // Add "AI API" tab in Settings → Users & Permissions → [Role]

package/src/client-v2/__tests__/settings-registration.test.tsx

@@ -8,7 +8,7 @@
  */
 
 import { createMockClient } from '@nocobase/client-v2';
-import { AI_API_ACL_SNIPPET } from '../../constants';
+import { AI_API_ACL_SNIPPET, AI_API_USER_PERMISSIONS_SNIPPET } from '../../constants';
 import { PluginAiApiClient } from '../plugin';
 
 /**
@@ -17,6 +17,11 @@ import { PluginAiApiClient } from '../plugin';
  * Two regressions are cheap to reintroduce and invisible until a non-admin logs in:
  * omitting `aclSnippet` makes addPageTabItem default to `pm.ai-api.<key>`, a snippet the
  * server never registers, and omitting `sort` silently reorders the tabs alphabetically.
+ *
+ * The tabs deliberately span two snippets: everything sits under AI_API_ACL_SNIPPET except
+ * user permissions, which is gated separately so granting it does not also grant gateway
+ * configuration. Each snippet is evaluated independently, so denying one leaves the other's
+ * tabs — and therefore the menu — reachable.
  */
 describe('AI API v2 settings registration', () => {
   async function loadPlugin() {
@@ -25,24 +30,47 @@ describe('AI API v2 settings registration', () => {
     return app;
   }
 
-  it('registers every page under the one snippet the server exposes', async () => {
+  it('registers every page under a snippet the server exposes', async () => {
     const app = await loadPlugin();
     const menu = app.pluginSettingsManager.get('ai-api', false);
 
     expect(menu?.aclSnippet).toBe(AI_API_ACL_SNIPPET);
     for (const child of menu?.children ?? []) {
-      expect(app.pluginSettingsManager.getAclSnippet(child.name), child.name).toBe(AI_API_ACL_SNIPPET);
+      expect(app.pluginSettingsManager.getAclSnippet(child.name), child.name).toBe(
+        child.name === 'ai-api.user-permissions' ? AI_API_USER_PERMISSIONS_SNIPPET : AI_API_ACL_SNIPPET,
+      );
     }
   });
 
-  it('hides the menu and every tab when the role denies that snippet', async () => {
+  it('leaves only the separately-gated tab when the main snippet is denied', async () => {
     const app = await loadPlugin();
     app.pluginSettingsManager.setAclSnippets([`!${AI_API_ACL_SNIPPET}`]);
 
+    // User permissions carries its own snippet, so it survives on its own merit and keeps the
+    // menu reachable. That separation is the point: a role can be allowed to hand out model
+    // access without also being allowed to reconfigure the gateway.
+    expect(app.pluginSettingsManager.get('ai-api')?.children?.map((item) => item.name)).toEqual([
+      'ai-api.user-permissions',
+    ]);
+  });
+
+  it('hides the menu and every tab when both snippets are denied', async () => {
+    const app = await loadPlugin();
+    app.pluginSettingsManager.setAclSnippets([`!${AI_API_ACL_SNIPPET}`, `!${AI_API_USER_PERMISSIONS_SNIPPET}`]);
+
     expect(app.pluginSettingsManager.get('ai-api')).toBeNull();
     expect(app.pluginSettingsManager.getList().map((item) => item.name)).not.toContain('ai-api');
   });
 
+  it('hides only the user permissions tab when its own snippet is denied', async () => {
+    const app = await loadPlugin();
+    app.pluginSettingsManager.setAclSnippets([`!${AI_API_USER_PERMISSIONS_SNIPPET}`]);
+
+    const children = app.pluginSettingsManager.get('ai-api')?.children?.map((item) => item.name) ?? [];
+    expect(children).not.toContain('ai-api.user-permissions');
+    expect(children).toContain('ai-api.user-quotas');
+  });
+
   it('keeps registration order instead of sorting tabs by name', async () => {
     const app = await loadPlugin();
     app.pluginSettingsManager.setAclSnippets([]);
@@ -51,6 +79,7 @@ describe('AI API v2 settings registration', () => {
       'ai-api.index',
       'ai-api.model-pricing',
       'ai-api.model-metadata',
+      'ai-api.user-permissions',
       'ai-api.user-quotas',
       'ai-api.usage',
     ]);