plugin-ai-api 1.0.21 → 1.0.23

package/src/server/plugin.ts

@@ -8,13 +8,16 @@
  */
 
 import { Plugin } from '@nocobase/server';
+import type { Transactionable } from '@nocobase/database';
 import { createAiLlmRouter, AI_LLM_PREFIX } from './routes/router';
 import aiApiConfigResource from './resource/ai-api-config';
 import aiApiUsageMonitorResource from './resource/ai-api-usage-monitor';
+import aiApiUserPermissionsResource from './resource/ai-api-user-permissions';
 import { RateLimiter } from './utils/rate-limiter';
 import { invalidateRolePermissionCache } from './middleware/role-permission';
+import { invalidateUserPermissionCache } from './utils/user-permissions';
 import { validateModelPrice, validateModelMetadata, validateQuotaPolicy } from './validation';
-import { AI_API_ACL_SNIPPET } from '../constants';
+import { AI_API_ACL_SNIPPET, AI_API_USER_PERMISSIONS_SNIPPET } from '../constants';
 
 // Ensure dayjs timezone + utc plugins are loaded.
 // Some Docker builds ship an older @nocobase/utils whose dayjs.js does not
@@ -77,6 +80,7 @@ export class PluginAiApiServer extends Plugin {
     // 2. Register admin config resource
     this.app.resourceManager.define(aiApiConfigResource);
     this.app.resourceManager.define(aiApiUsageMonitorResource);
+    this.app.resourceManager.define(aiApiUserPermissionsResource);
 
     this.app.db.on('aiApiRolePermissions.afterSave', (model) => {
       invalidateRolePermissionCache(model.get('roleName'));
@@ -85,6 +89,13 @@ export class PluginAiApiServer extends Plugin {
       invalidateRolePermissionCache(model.get('roleName'));
     });
 
+    this.app.db.on('aiApiUserPermissions.afterSave', (model, options) => {
+      this.revokeUserPermissions(model.get('userId'), options?.transaction);
+    });
+    this.app.db.on('aiApiUserPermissions.afterDestroy', (model, options) => {
+      this.revokeUserPermissions(model.get('userId'), options?.transaction);
+    });
+
     // 3. Set ACL permissions for admin config + role permissions management
     this.app.acl.registerSnippet({
       name: AI_API_ACL_SNIPPET,
@@ -102,12 +113,42 @@ export class PluginAiApiServer extends Plugin {
       ],
     });
 
+    // Per-user LLM grants are a separate child permission: handing out model access is a
+    // stronger capability than editing gateway settings, so it ticks independently.
+    // The wildcard also covers `listUsers`, which backs the page's user picker — without it
+    // the page would depend on `pm.plugin-users` and break for a role holding only this snippet.
+    this.app.acl.registerSnippet({
+      name: AI_API_USER_PERMISSIONS_SNIPPET,
+      actions: ['aiApiUserPermissions:*'],
+    });
+
     // 4. GC the rate limiter every 5 minutes to evict stale user entries.
     //    .unref() prevents this timer from keeping the process alive on shutdown.
     this.gcInterval = setInterval(() => this.rateLimiter.gc(), 5 * 60 * 1000);
     this.gcInterval.unref();
   }
 
+  /**
+   * Drop a user's cached LLM scope on every node.
+   *
+   * The local call is not redundant: syncMessageManager hardcodes skipSelf, so the publishing
+   * node never receives its own message. Passing the transaction defers the broadcast until
+   * the write commits, so other nodes cannot re-read the old row and re-cache it.
+   */
+  private revokeUserPermissions(userId: unknown, transaction?: Transactionable['transaction']) {
+    invalidateUserPermissionCache(userId as string | number | bigint);
+    this.sendSyncMessage({ type: 'invalidateUserPermissions', userId }, { transaction });
+  }
+
+  /**
+   * Received only on the *other* nodes (skipSelf), so this must not re-broadcast.
+   */
+  async handleSyncMessage(message: { type?: string; userId?: unknown }) {
+    if (message?.type === 'invalidateUserPermissions') {
+      invalidateUserPermissionCache(message.userId as string | number | bigint);
+    }
+  }
+
   async install() {
     // Create default config record on first install
     const existing = await this.db.getRepository('aiApiConfig').findOne();

package/src/server/resource/ai-api-user-permissions.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 type { ResourceOptions } from '@nocobase/resourcer';
+
+const MAX_PAGE_SIZE = 100;
+
+/**
+ * Minimal user directory for the permission page's user picker.
+ *
+ * The page is gated by AI_API_USER_PERMISSIONS_SNIPPET, but `users:list` belongs to
+ * `pm.plugin-users`. Calling it would force every permission admin to also be a user admin,
+ * so this action exposes only the identity fields the picker renders — never password hashes,
+ * roles or any other user column.
+ */
+const aiApiUserPermissionsResource: ResourceOptions = {
+  name: 'aiApiUserPermissions',
+  actions: {
+    async listUsers(ctx, next) {
+      const params = ctx.action.params || {};
+      const keyword = typeof params.keyword === 'string' ? params.keyword.trim() : '';
+      const page = Math.max(1, Number(params.page) || 1);
+      const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, Number(params.pageSize) || 50));
+
+      const filter: Record<string, unknown> = keyword
+        ? {
+            $or: [
+              { nickname: { $includes: keyword } },
+              { username: { $includes: keyword } },
+              { email: { $includes: keyword } },
+            ],
+          }
+        : {};
+
+      // A user already holding a grant is excluded so the picker cannot produce a duplicate
+      // that the unique index on userId would reject at save time.
+      if (params.excludeGranted) {
+        const granted = await ctx.db.getRepository('aiApiUserPermissions').find({ fields: ['userId'] });
+        const ids = granted.map((row) => row.get('userId')).filter((id) => id !== null && id !== undefined);
+        if (ids.length) filter.id = { $notIn: ids };
+      }
+
+      const [rows, count] = await ctx.db.getRepository('users').findAndCount({
+        filter,
+        fields: ['id', 'nickname', 'username', 'email'],
+        sort: ['nickname', 'id'],
+        offset: (page - 1) * pageSize,
+        limit: pageSize,
+      });
+
+      // Use the canonical { rows, ...meta } action shape. NocoBase's dataWrapping
+      // middleware turns this into { data, meta } on the wire; returning that wire
+      // shape here would make it wrap a second time.
+      ctx.body = {
+        rows: rows.map((row) => ({
+          id: row.get('id'),
+          nickname: row.get('nickname'),
+          username: row.get('username'),
+          email: row.get('email'),
+        })),
+        count,
+        page,
+        pageSize,
+      };
+      await next();
+    },
+  },
+};
+
+export default aiApiUserPermissionsResource;

package/src/server/routes/agent-completions.ts

@@ -18,6 +18,7 @@ import {
 } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
 import { checkEmployeeAccess } from '../middleware/role-permission';
+import { enforceModelAccess } from '../utils/user-permissions';
 import { isStreamingRequested } from '../utils/streaming';
 import {
   AgentRuntimeContext,
@@ -121,6 +122,12 @@ export async function handleAgentCompletions(ctx: Context, plugin: PluginAiApiSe
     return;
   }
 
+  // ─── Check whitelist (global config ∩ per-user grant) ──────────────────────
+  const globalEnabledServices = config ? config.get('enabledLlmServices') || config.enabledLlmServices : [];
+  if (!(await enforceModelAccess(ctx, globalEnabledServices, service, modelId))) {
+    return;
+  }
+
   const employeeUsername = defaultAiEmployee;
 
   // ─── Check role is allowed to use this employee ────────────────────────────

package/src/server/routes/chat-completions.ts

@@ -12,6 +12,7 @@ import {
   generateCompletionId,
   toOpenAIResponse,
   toOpenAIStreamChunk,
+  toOpenAIUsageChunk,
   toOpenAIError,
   formatSSE,
   formatSSEDone,
@@ -26,6 +27,7 @@ import {
   writeResponse,
 } from '../utils/streaming';
 import { checkEmployeeAccess } from '../middleware/role-permission';
+import { enforceModelAccess } from '../utils/user-permissions';
 import { extractProviderRequestId, normalizeUsage, setAiApiUsageResult, type Usage } from '../usage';
 import type PluginAiApiServer from '../plugin';
 import { AiApiQuotaError, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
@@ -126,22 +128,10 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
       return;
     }
 
-    // ─── Check whitelist ───
+    // ─── Check whitelist (global config ∩ per-user grant) ───
     const config = await ctx.db.getRepository('aiApiConfig').findOne();
-    if (config?.enabledLlmServices?.length) {
-      const serviceName = service.name;
-      const serviceTitle = service.title;
-      const isAllowed = config.enabledLlmServices.some((s: string) => s === serviceName || s === serviceTitle);
-      if (!isAllowed) {
-        ctx.status = 403;
-        ctx.body = toOpenAIError(
-          403,
-          `LLM service '${service.title || service.name}' is not enabled for API access`,
-          'invalid_request_error',
-          'model_not_available',
-        );
-        return;
-      }
+    if (!(await enforceModelAccess(ctx, config?.enabledLlmServices, service, modelId))) {
+      return;
     }
 
     // ─── Create LLM provider instance ───
@@ -155,6 +145,13 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     await prepareLlmBilling(ctx, resolved);
 
     const providerRequestParameters = getProviderRequestParameters(body);
+    if (stream) {
+      const streamOptions = isRecord(body.stream_options) ? body.stream_options : {};
+      providerRequestParameters.stream_options = {
+        ...streamOptions,
+        include_usage: true,
+      };
+    }
     const modelOptions: Record<string, unknown> = {
       model: modelId,
       llmService: service.name,
@@ -380,7 +377,13 @@ async function handleStreamingCompletion(
         finishReason = 'tool_calls';
         await writeResponse(
           ctx,
-          formatSSE(toOpenAIStreamChunk({ id: completionId, model: modelName, delta: { tool_calls: toolCallChunks } })),
+          formatSSE(
+            toOpenAIStreamChunk({
+              id: completionId,
+              model: modelName,
+              delta: { tool_calls: toolCallChunks },
+            }),
+          ),
         );
       }
       if (chunk.usage_metadata) {
@@ -402,6 +405,19 @@ async function handleStreamingCompletion(
       ),
     );
 
+    if (usage) {
+      await writeResponse(
+        ctx,
+        formatSSE(
+          toOpenAIUsageChunk({
+            id: completionId,
+            model: modelName,
+            usage,
+          }),
+        ),
+      );
+    }
+
     // Send [DONE]
     await writeResponse(ctx, formatSSEDone());
     setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });

package/src/server/routes/completions.ts

@@ -8,8 +8,15 @@
  */
 
 import { Context } from '@nocobase/actions';
-import { generateCompletionId, toOpenAIError, formatSSE, formatSSEDone } from '../utils/openai-format';
+import {
+  generateCompletionId,
+  toOpenAIError,
+  formatSSE,
+  formatSSEDone,
+  toOpenAIUsageChunk,
+} from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { enforceModelAccess } from '../utils/user-permissions';
 import {
   createRequestAbortController,
   isClientDisconnected,
@@ -93,22 +100,10 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
       return;
     }
 
-    // ─── Check whitelist ───
+    // ─── Check whitelist (global config ∩ per-user grant) ───
     const config = await ctx.db.getRepository('aiApiConfig').findOne();
-    if (config?.enabledLlmServices?.length) {
-      const serviceName = service.name;
-      const serviceTitle = service.title;
-      const isAllowed = config.enabledLlmServices.some((s: string) => s === serviceName || s === serviceTitle);
-      if (!isAllowed) {
-        ctx.status = 403;
-        ctx.body = toOpenAIError(
-          403,
-          `LLM service '${service.title || service.name}' is not enabled for API access`,
-          'invalid_request_error',
-          'model_not_available',
-        );
-        return;
-      }
+    if (!(await enforceModelAccess(ctx, config?.enabledLlmServices, service, modelId))) {
+      return;
     }
 
     // ─── Create LLM provider instance ───
@@ -166,7 +161,14 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
     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);
     }
@@ -237,6 +239,7 @@ async function handleStreamingTextCompletion(
   messages: [string, string][],
   completionId: string,
   modelName: string,
+  streamOptions: Record<string, unknown> | undefined,
 ) {
   ctx.set({
     'Content-Type': 'text/event-stream',
@@ -250,7 +253,10 @@ async function handleStreamingTextCompletion(
   let usage: Usage | undefined;
   let providerRequestId: string | undefined;
   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;
@@ -280,6 +286,7 @@ async function handleStreamingTextCompletion(
                 finish_reason: null,
               },
             ],
+            usage: null,
           }),
         );
       }
@@ -306,9 +313,24 @@ async function handleStreamingTextCompletion(
             finish_reason: 'stop',
           },
         ],
+        usage: null,
       }),
     );
 
+    if (usage) {
+      await writeResponse(
+        ctx,
+        formatSSE(
+          toOpenAIUsageChunk({
+            id: completionId,
+            model: modelName,
+            object: 'text_completion',
+            usage,
+          }),
+        ),
+      );
+    }
+
     await writeResponse(ctx, formatSSEDone());
     setAiApiUsageResult(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
     ctx.state.aiApiStreamResult = { succeeded: true, id: completionId };

package/src/server/routes/embeddings.ts

@@ -10,6 +10,7 @@
 import { Context } from '@nocobase/actions';
 import { toOpenAIError, toOpenAIEmbeddingsResponse } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { enforceModelAccess } from '../utils/user-permissions';
 import { setAiApiUsageUnavailable } from '../usage';
 import type PluginAiApiServer from '../plugin';
 
@@ -112,24 +113,18 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
     return;
   }
 
-  // ─── Check service whitelist ──────────────────────────────────────────────
+  // ─── Check service whitelist (global config ∩ per-user grant) ─────────────
+  // A config read failure falls open on the global list, but the per-user grant is
+  // still enforced: an explicit deny must never be bypassed by an unreadable config.
+  let globalEnabledServices: unknown = [];
   try {
     const config = await ctx.db.getRepository('aiApiConfig').findOne();
-    if (config?.enabledLlmServices?.length) {
-      const allowed = config.enabledLlmServices.some((s: string) => s === service.name || s === service.title);
-      if (!allowed) {
-        ctx.status = 403;
-        ctx.body = toOpenAIError(
-          403,
-          `LLM service '${service.title || service.name}' is not enabled for API access`,
-          'invalid_request_error',
-          'model_not_available',
-        );
-        return;
-      }
-    }
+    globalEnabledServices = config?.enabledLlmServices ?? [];
   } catch {
-    // Config read failure: fail open
+    // Config read failure: fail open on the global whitelist only.
+  }
+  if (!(await enforceModelAccess(ctx, globalEnabledServices, service, modelId))) {
+    return;
   }
 
   // ─── Get embedding provider ───────────────────────────────────────────────

package/src/server/routes/models.ts

@@ -9,6 +9,7 @@
 
 import { Context } from '@nocobase/actions';
 import { toOpenAIError } from '../utils/openai-format';
+import { isModelAllowed, isServiceAllowed, resolveUserAccessScope } from '../utils/user-permissions';
 import type PluginAiApiServer from '../plugin';
 
 /**
@@ -19,6 +20,9 @@ import type PluginAiApiServer from '../plugin';
  * so clients can copy-paste the ID directly into POST /v1/chat/completions
  * without needing to configure a defaultLlmService.
  *
+ * The catalog is scoped to the caller: a user with an aiApiUserPermissions row only
+ * sees the intersection of the global whitelist and their own grant.
+ *
  * Backward compatibility: resolveModelString() in resolve-service.ts still
  * accepts bare model IDs via its 3-tier fallback (defaultLlmService / single service).
  */
@@ -44,18 +48,25 @@ export async function handleListModels(ctx: Context, plugin: PluginAiApiServer)
       sort: 'sort',
     });
 
+    const scope = await resolveUserAccessScope(ctx);
+    if (scope.lookupFailed) {
+      respondPermissionCheckFailed(ctx);
+      return;
+    }
     const metadataMap = await loadModelMetadata(ctx);
     const now = Math.floor(Date.now() / 1000);
     const models: any[] = [];
 
     for (const service of services) {
       if (service.enabled === false) continue;
+      if (!isServiceAllowed(scope, 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 (!isModelAllowed(scope, fullId)) continue;
         const meta = metadataMap.get(fullId);
         // An override row with enabled=false hides the model from the catalog.
         if (meta && meta.enabled === false) continue;
@@ -95,12 +106,18 @@ export async function handleGetModel(ctx: Context, modelId: string, plugin: Plug
       sort: 'sort',
     });
 
+    const scope = await resolveUserAccessScope(ctx);
+    if (scope.lookupFailed) {
+      respondPermissionCheckFailed(ctx);
+      return;
+    }
     const metadataMap = await loadModelMetadata(ctx);
     const now = Math.floor(Date.now() / 1000);
     let found: any = null;
 
     for (const service of services) {
       if (service.enabled === false) continue;
+      if (!isServiceAllowed(scope, config?.enabledLlmServices, service)) continue;
       const enabledModels = resolveEnabledModels(service);
       const serviceLabel = service.title || service.name;
 
@@ -108,6 +125,7 @@ export async function handleGetModel(ctx: Context, modelId: string, plugin: Plug
         const fullId = `${service.name}/${model.value}`;
         // Accept both new "serviceName/modelId" format AND bare model ID (backward compat)
         if (fullId === modelId || model.value === modelId) {
+          if (!isModelAllowed(scope, fullId)) continue;
           const meta = metadataMap.get(fullId);
           // A disabled override hides the model — treat as not found.
           if (meta && meta.enabled === false) continue;
@@ -135,6 +153,16 @@ export async function handleGetModel(ctx: Context, modelId: string, plugin: Plug
 
 // ─── Helpers ───
 
+function respondPermissionCheckFailed(ctx: Context): void {
+  ctx.status = 503;
+  ctx.body = toOpenAIError(
+    503,
+    'Unable to verify LLM permissions for this user. Please retry shortly.',
+    'service_unavailable',
+    'permission_check_failed',
+  );
+}
+
 export interface ModelMetadataOverride {
   contextWindow?: number | null;
   maxCompletionTokens?: number | null;

package/src/server/utils/openai-format.ts

@@ -97,6 +97,14 @@ export function toOpenAIResponse(options: {
 
 // ─── OpenAI Streaming chunk format ───
 
+export type OpenAIUsage = {
+  prompt_tokens: number | null;
+  completion_tokens: number | null;
+  total_tokens: number | null;
+};
+
+export type OpenAIStreamObject = 'chat.completion.chunk' | 'text_completion';
+
 export function toOpenAIStreamChunk(options: {
   id: string;
   model: string;
@@ -118,6 +126,24 @@ export function toOpenAIStreamChunk(options: {
         finish_reason: finishReason,
       },
     ],
+    usage: null,
+  };
+}
+
+export function toOpenAIUsageChunk(options: {
+  id: string;
+  model: string;
+  usage: OpenAIUsage;
+  object?: OpenAIStreamObject;
+}) {
+  const { id, model, usage, object = 'chat.completion.chunk' } = options;
+  return {
+    id,
+    object,
+    created: Math.floor(Date.now() / 1000),
+    model,
+    choices: [],
+    usage,
   };
 }