plugin-ai-api 1.0.21 → 1.0.23

package/src/client-v2/pages/UserPermissionsPage.tsx

@@ -0,0 +1,322 @@
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { Alert, Button, Card, Form, Modal, Popconfirm, Select, Space, Switch, Table, Tag, message } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { useFlowContext } from '@nocobase/flow-engine';
+import { useT } from '../locale';
+import { errorMessage, unwrapData } from './api';
+import type { ApiEnvelope } from './api';
+
+interface UserSummary {
+  id: string | number;
+  nickname?: string;
+  username?: string;
+  email?: string;
+}
+
+interface EnabledLlmService {
+  llmService: string;
+  llmServiceTitle?: string;
+  enabledModels?: { label: string; value: string }[];
+}
+
+interface UserPermission {
+  id: string | number;
+  userId: string | number;
+  user?: UserSummary;
+  enabled: boolean;
+  allowedLlmServices: string[];
+  allowAllModels: boolean;
+  allowedModels: string[];
+}
+
+/** The modal edits everything except the server-assigned id. */
+type UserPermissionFormValues = Omit<UserPermission, 'id' | 'user'>;
+
+const PAGE_SIZE = 20;
+
+export default function UserPermissionsPage() {
+  const ctx = useFlowContext();
+  const t = useT();
+  const [form] = Form.useForm<UserPermissionFormValues>();
+  const selectedServices = Form.useWatch('allowedLlmServices', form);
+  const allowAllModels = Form.useWatch('allowAllModels', form);
+  const [rows, setRows] = useState<UserPermission[]>([]);
+  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const [users, setUsers] = useState<UserSummary[]>([]);
+  const [userSearch, setUserSearch] = useState('');
+  const [services, setServices] = useState<EnabledLlmService[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [editing, setEditing] = useState<UserPermission>();
+  const [open, setOpen] = useState(false);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    try {
+      const [permissionsResponse, servicesResponse] = await Promise.all([
+        ctx.api.request({
+          url: 'aiApiUserPermissions:list',
+          method: 'get',
+          params: { page, pageSize: PAGE_SIZE, appends: ['user'], sort: '-updatedAt' },
+        }),
+        ctx.api.request({ url: 'ai:listAllEnabledModels', method: 'get' }),
+      ]);
+      setRows(unwrapData<UserPermission[]>(permissionsResponse, []));
+      setTotal((permissionsResponse as ApiEnvelope<UserPermission[]>)?.data?.meta?.count ?? 0);
+      setServices(unwrapData<EnabledLlmService[]>(servicesResponse, []));
+    } catch (error) {
+      message.error(errorMessage(error));
+    } finally {
+      setLoading(false);
+    }
+  }, [ctx.api, page]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  // Served by the plugin's own action rather than `users:list`, which belongs to the
+  // pm.plugin-users snippet and would make this page unusable for a role granted only
+  // pm.plugin-ai-api.user-permissions.
+  const loadUsers = useCallback(
+    async (keyword: string) => {
+      try {
+        const response = await ctx.api.request({
+          url: 'aiApiUserPermissions:listUsers',
+          method: 'get',
+          params: { keyword, pageSize: 50, excludeGranted: !editing },
+        });
+        setUsers(unwrapData<UserSummary[]>(response, []));
+      } catch (error) {
+        message.error(errorMessage(error));
+      }
+    },
+    [ctx.api, editing],
+  );
+
+  useEffect(() => {
+    if (!open) return;
+    const timer = setTimeout(() => loadUsers(userSearch), 300);
+    return () => clearTimeout(timer);
+  }, [open, userSearch, loadUsers]);
+
+  const serviceOptions = useMemo(
+    () =>
+      services.map((service) => ({ label: service.llmServiceTitle || service.llmService, value: service.llmService })),
+    [services],
+  );
+
+  // Model IDs are "serviceName/modelId", matching what the gateway enforces and what
+  // GET /v1/models returns, so admins never have to type them by hand.
+  const modelOptions = useMemo(() => {
+    const picked = new Set(selectedServices || []);
+    return services
+      .filter((service) => picked.has(service.llmService))
+      .flatMap((service) =>
+        (service.enabledModels || []).map((model) => ({
+          label: `${service.llmServiceTitle || service.llmService} / ${model.label || model.value}`,
+          value: `${service.llmService}/${model.value}`,
+        })),
+      );
+  }, [services, selectedServices]);
+
+  const showCreate = () => {
+    setEditing(undefined);
+    setUserSearch('');
+    form.setFieldsValue({
+      enabled: true,
+      allowedLlmServices: [],
+      allowAllModels: true,
+      allowedModels: [],
+    });
+    setOpen(true);
+  };
+
+  const showEdit = (record: UserPermission) => {
+    setEditing(record);
+    setUserSearch('');
+    // Seed the picker with the granted user so the label renders before any search runs.
+    setUsers(record.user ? [record.user] : []);
+    form.setFieldsValue({
+      userId: record.userId,
+      enabled: record.enabled,
+      allowAllModels: record.allowAllModels,
+      allowedLlmServices: record.allowedLlmServices || [],
+      allowedModels: record.allowedModels || [],
+    });
+    setOpen(true);
+  };
+
+  const save = async () => {
+    const values = await form.validateFields();
+    setSaving(true);
+    try {
+      await ctx.api.request({
+        url: editing ? `aiApiUserPermissions:update/${editing.id}` : 'aiApiUserPermissions:create',
+        method: 'post',
+        data: values,
+      });
+      message.success(t('Saved successfully'));
+      setOpen(false);
+      await load();
+    } catch (error) {
+      message.error(errorMessage(error));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const remove = async (record: UserPermission) => {
+    try {
+      await ctx.api.request({ url: `aiApiUserPermissions:destroy/${record.id}`, method: 'post' });
+      message.success(t('Deleted successfully'));
+      await load();
+    } catch (error) {
+      message.error(errorMessage(error));
+    }
+  };
+
+  const userLabel = (user?: UserSummary) => user?.nickname || user?.username || user?.email || String(user?.id ?? '');
+  const serviceLabel = (name: string) => serviceOptions.find((option) => option.value === name)?.label || name;
+
+  const columns: ColumnsType<UserPermission> = [
+    {
+      title: t('User'),
+      key: 'user',
+      width: 180,
+      render: (_, record) => userLabel(record.user) || String(record.userId),
+    },
+    {
+      title: t('Allowed LLM services'),
+      dataIndex: 'allowedLlmServices',
+      key: 'allowedLlmServices',
+      render: (values: string[]) =>
+        values?.length ? (
+          <Space size={[0, 4]} wrap>
+            {values.map((value) => (
+              <Tag key={value}>{serviceLabel(value)}</Tag>
+            ))}
+          </Space>
+        ) : (
+          <Tag color="red">{t('No service allowed')}</Tag>
+        ),
+    },
+    {
+      title: t('Allowed models'),
+      key: 'allowedModels',
+      width: 220,
+      render: (_, record) =>
+        record.allowAllModels ? (
+          <Tag color="blue">{t('All models of allowed services')}</Tag>
+        ) : (
+          <Space size={[0, 4]} wrap>
+            {(record.allowedModels || []).map((value) => (
+              <Tag key={value}>{value}</Tag>
+            ))}
+          </Space>
+        ),
+    },
+    {
+      title: t('Status'),
+      dataIndex: 'enabled',
+      key: 'enabled',
+      width: 100,
+      render: (enabled: boolean) => (
+        <Tag color={enabled ? 'green' : 'default'}>{enabled ? t('Enabled') : t('Disabled')}</Tag>
+      ),
+    },
+    {
+      title: t('Actions'),
+      key: 'actions',
+      width: 150,
+      fixed: 'right',
+      render: (_, record) => (
+        <Space size={0}>
+          <Button type="link" onClick={() => showEdit(record)}>
+            {t('Edit')}
+          </Button>
+          <Popconfirm title={t('Delete this permission?')} onConfirm={() => remove(record)}>
+            <Button type="link" danger>
+              {t('Delete')}
+            </Button>
+          </Popconfirm>
+        </Space>
+      ),
+    },
+  ];
+
+  return (
+    <Card
+      title={t('User LLM permissions')}
+      extra={
+        <Button type="primary" onClick={showCreate}>
+          {t('Add permission')}
+        </Button>
+      }
+    >
+      <Alert
+        type="info"
+        showIcon
+        style={{ marginBottom: 16 }}
+        message={t(
+          'Users listed here are limited to the services selected below. Users without a record fall back to the general configuration.',
+        )}
+      />
+      <Table
+        rowKey="id"
+        columns={columns}
+        dataSource={rows}
+        loading={loading}
+        scroll={{ x: 1000 }}
+        pagination={{
+          current: page,
+          pageSize: PAGE_SIZE,
+          total,
+          showSizeChanger: false,
+          onChange: setPage,
+        }}
+      />
+      <Modal
+        title={editing ? t('Edit permission') : t('Add permission')}
+        open={open}
+        onCancel={() => setOpen(false)}
+        onOk={save}
+        confirmLoading={saving}
+        destroyOnClose
+      >
+        <Form form={form} layout="vertical" preserve={false}>
+          <Form.Item name="userId" label={t('User')} rules={[{ required: true }]}>
+            <Select
+              disabled={Boolean(editing)}
+              showSearch
+              // Matching happens on the server, so keep every returned option visible.
+              filterOption={false}
+              onSearch={setUserSearch}
+              notFoundContent={null}
+              options={users.map((user) => ({ label: userLabel(user), value: user.id }))}
+            />
+          </Form.Item>
+          <Form.Item
+            name="allowedLlmServices"
+            label={t('Allowed LLM services')}
+            extra={t('Only services also enabled in the general configuration take effect.')}
+          >
+            <Select mode="multiple" allowClear showSearch optionFilterProp="label" options={serviceOptions} />
+          </Form.Item>
+          <Form.Item name="allowAllModels" label={t('Allow all models')} valuePropName="checked">
+            <Switch />
+          </Form.Item>
+          {allowAllModels === false && (
+            <Form.Item name="allowedModels" label={t('Allowed models')}>
+              <Select mode="multiple" allowClear showSearch optionFilterProp="label" options={modelOptions} />
+            </Form.Item>
+          )}
+          <Form.Item name="enabled" label={t('Enabled')} valuePropName="checked">
+            <Switch />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </Card>
+  );
+}

package/src/client-v2/plugin.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { Plugin, Application } from '@nocobase/client-v2';
-import { AI_API_ACL_SNIPPET } from '../constants';
+import { AI_API_ACL_SNIPPET, AI_API_USER_PERMISSIONS_SNIPPET } from '../constants';
 
 interface PermissionTabOptions {
   key: string;
@@ -51,12 +51,21 @@ export class PluginAiApiClient extends Plugin<Record<string, never>, Application
       componentLoader: () => import('./pages/ModelMetadataPage'),
     });
 
+    this.pluginSettingsManager.addPageTabItem({
+      menuKey: 'ai-api',
+      key: 'user-permissions',
+      title: this.t('User LLM permissions'),
+      aclSnippet: AI_API_USER_PERMISSIONS_SNIPPET,
+      sort: 4,
+      componentLoader: () => import('./pages/UserPermissionsPage'),
+    });
+
     this.pluginSettingsManager.addPageTabItem({
       menuKey: 'ai-api',
       key: 'user-quotas',
       title: this.t('User quotas'),
       aclSnippet: AI_API_ACL_SNIPPET,
-      sort: 4,
+      sort: 5,
       componentLoader: () => import('./pages/UserQuotasPage'),
     });
 
@@ -65,7 +74,7 @@ export class PluginAiApiClient extends Plugin<Record<string, never>, Application
       key: 'usage',
       title: this.t('Usage'),
       aclSnippet: AI_API_ACL_SNIPPET,
-      sort: 5,
+      sort: 6,
       componentLoader: () => import('./pages/UsagePage'),
     });
 

package/src/constants.ts

@@ -19,3 +19,10 @@
  * Shared by both client runtimes so a rename cannot silently desynchronise them.
  */
 export const AI_API_ACL_SNIPPET = 'pm.plugin-ai-api.configuration';
+
+/**
+ * Child snippet for the per-user LLM permission surface, deliberately separate from
+ * AI_API_ACL_SNIPPET so granting someone the gateway settings does not also let them
+ * hand out model access. Same `plugin-ai-api` prefix constraint as above applies.
+ */
+export const AI_API_USER_PERMISSIONS_SNIPPET = 'pm.plugin-ai-api.user-permissions';

package/src/locale/en-US.json

@@ -101,5 +101,16 @@
   "Select which AI Employees this role may use:": "Select which AI Employees this role may use:",
   "Select allowed AI Employees": "Select allowed AI Employees",
   "Max request body size (MB)": "Max request body size (MB)",
-  "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.": "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size."
+  "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.": "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.",
+  "User LLM permissions": "User LLM permissions",
+  "Add permission": "Add permission",
+  "Edit permission": "Edit permission",
+  "Delete this permission?": "Delete this permission?",
+  "Allowed LLM services": "Allowed LLM services",
+  "Allow all models": "Allow all models",
+  "Allowed models": "Allowed models",
+  "No service allowed": "No service allowed",
+  "All models of allowed services": "All models of allowed services",
+  "Users listed here are limited to the services selected below. Users without a record fall back to the general configuration.": "Users listed here are limited to the services selected below. Users without a record fall back to the general configuration.",
+  "Only services also enabled in the general configuration take effect.": "Only services also enabled in the general configuration take effect."
 }

package/src/locale/vi-VN.json

@@ -101,5 +101,16 @@
   "Select which AI Employees this role may use:": "Chọn AI Employee mà vai trò này được dùng:",
   "Select allowed AI Employees": "Chọn AI Employee được phép",
   "Max request body size (MB)": "Giới hạn kích thước request body (MB)",
-  "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.": "Tăng giá trị này để nhận ảnh base64 gửi trực tiếp. Base64 làm tăng khoảng 33% so với kích thước tệp gốc."
+  "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.": "Tăng giá trị này để nhận ảnh base64 gửi trực tiếp. Base64 làm tăng khoảng 33% so với kích thước tệp gốc.",
+  "User LLM permissions": "Phân quyền LLM theo người dùng",
+  "Add permission": "Thêm phân quyền",
+  "Edit permission": "Sửa phân quyền",
+  "Delete this permission?": "Xoá phân quyền này?",
+  "Allowed LLM services": "Dịch vụ LLM được phép",
+  "Allow all models": "Cho phép tất cả model",
+  "Allowed models": "Model được phép",
+  "No service allowed": "Không được phép dịch vụ nào",
+  "All models of allowed services": "Tất cả model của các dịch vụ được phép",
+  "Users listed here are limited to the services selected below. Users without a record fall back to the general configuration.": "Người dùng có trong danh sách này chỉ được dùng các dịch vụ được chọn bên dưới. Người dùng không có bản ghi sẽ dùng theo cấu hình chung.",
+  "Only services also enabled in the general configuration take effect.": "Chỉ những dịch vụ đồng thời được bật trong cấu hình chung mới có hiệu lực."
 }

package/src/locale/zh-CN.json

@@ -101,5 +101,16 @@
   "Select which AI Employees this role may use:": "选择此角色可使用的 AI 员工：",
   "Select allowed AI Employees": "选择允许的 AI 员工",
   "Max request body size (MB)": "请求体大小上限（MB）",
-  "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.": "调高此值以接收内联 base64 图片。base64 编码会使体积增加约 33%。"
+  "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.": "调高此值以接收内联 base64 图片。base64 编码会使体积增加约 33%。",
+  "User LLM permissions": "用户 LLM 权限",
+  "Add permission": "添加权限",
+  "Edit permission": "编辑权限",
+  "Delete this permission?": "确定删除此权限？",
+  "Allowed LLM services": "允许的 LLM 服务",
+  "Allow all models": "允许所有模型",
+  "Allowed models": "允许的模型",
+  "No service allowed": "未允许任何服务",
+  "All models of allowed services": "允许服务下的所有模型",
+  "Users listed here are limited to the services selected below. Users without a record fall back to the general configuration.": "此处列出的用户仅能使用下方所选的服务；没有记录的用户按通用配置处理。",
+  "Only services also enabled in the general configuration take effect.": "仅当服务同时在通用配置中启用时才会生效。"
 }

package/src/server/__tests__/models.test.ts

@@ -7,11 +7,33 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, expect, it } from 'vitest';
-import { buildModelObject } from '../routes/models';
+import { Context } from '@nocobase/actions';
+import { describe, expect, it, vi } from 'vitest';
+import { buildModelObject, handleGetModel, handleListModels } from '../routes/models';
 
 const CREATED = 1_700_000_000;
 
+function permissionLookupFailureContext() {
+  const ctx = {
+    app: { name: 'main', pm: { get: () => ({}) } },
+    state: { currentUser: { id: 1 } },
+    db: {
+      getRepository: (name: string) => {
+        if (name === 'aiApiConfig') return { findOne: vi.fn(async () => null) };
+        if (name === 'llmServices') return { find: vi.fn(async () => []) };
+        if (name === 'aiApiUserPermissions') {
+          return { findOne: vi.fn(async () => Promise.reject(new Error('permission database unavailable'))) };
+        }
+        return { find: vi.fn(async () => []) };
+      },
+    },
+    log: { error: vi.fn(), warn: vi.fn() },
+    status: 0,
+    body: undefined,
+  } as unknown as Context;
+  return ctx;
+}
+
 describe('buildModelObject', () => {
   it('returns the base OpenAI model shape with no override', () => {
     const model = buildModelObject('svc/gpt-4o', CREATED, 'My Service');
@@ -72,3 +94,23 @@ describe('buildModelObject', () => {
     expect(buildModelObject('svc/m', CREATED, 'Svc', { contextWindow: 10 }).active).toBe(true);
   });
 });
+
+describe('model catalog permission lookup failures', () => {
+  it('returns a retryable 503 when listing models', async () => {
+    const ctx = permissionLookupFailureContext();
+
+    await handleListModels(ctx, undefined as never);
+
+    expect(ctx.status).toBe(503);
+    expect(ctx.body).toMatchObject({ error: { code: 'permission_check_failed' } });
+  });
+
+  it('returns a retryable 503 when retrieving a model', async () => {
+    const ctx = permissionLookupFailureContext();
+
+    await handleGetModel(ctx, 'openai/gpt-4o', undefined as never);
+
+    expect(ctx.status).toBe(503);
+    expect(ctx.body).toMatchObject({ error: { code: 'permission_check_failed' } });
+  });
+});

package/src/server/__tests__/openai-format.test.ts

@@ -1,4 +1,4 @@
-import { toOpenAIResponse, toOpenAIStreamChunk } from '../utils/openai-format';
+import { toOpenAIResponse, toOpenAIStreamChunk, toOpenAIUsageChunk } from '../utils/openai-format';
 import { isStreamingRequested } from '../utils/streaming';
 import { applyProviderRequestParameters, getProviderRequestParameters } from '../routes/chat-completions';
 
@@ -52,6 +52,57 @@ describe('AI API OpenAI tool-call formatting', () => {
   });
 });
 
+describe('AI API OpenAI usage-only streaming chunks', () => {
+  it('includes a null usage field for normal chunks', () => {
+    const chunk = toOpenAIStreamChunk({
+      id: 'chatcmpl-1',
+      model: 'service/model',
+      delta: { content: 'Hello' },
+    });
+
+    expect(chunk.choices).toHaveLength(1);
+    expect(chunk).toHaveProperty('usage', null);
+  });
+
+  it('includes a null usage field for finish chunks', () => {
+    const chunk = toOpenAIStreamChunk({
+      id: 'chatcmpl-1',
+      model: 'service/model',
+      delta: {},
+      finishReason: 'stop',
+    });
+
+    expect(chunk.choices[0].finish_reason).toBe('stop');
+    expect(chunk).toHaveProperty('usage', null);
+  });
+
+  it('formats a usage-only chat completion chunk with an empty choices array', () => {
+    const chunk = toOpenAIUsageChunk({
+      id: 'chatcmpl-1',
+      model: 'service/model',
+      usage: { prompt_tokens: 8, completion_tokens: 3, total_tokens: 11 },
+      object: 'chat.completion.chunk',
+    });
+
+    expect(chunk.object).toBe('chat.completion.chunk');
+    expect(chunk.choices).toEqual([]);
+    expect(chunk.usage).toEqual({ prompt_tokens: 8, completion_tokens: 3, total_tokens: 11 });
+  });
+
+  it('formats a usage-only legacy text completion chunk', () => {
+    const chunk = toOpenAIUsageChunk({
+      id: 'cmpl-1',
+      model: 'service/model',
+      usage: { prompt_tokens: 2, completion_tokens: 5, total_tokens: 7 },
+      object: 'text_completion',
+    });
+
+    expect(chunk.object).toBe('text_completion');
+    expect(chunk.choices).toEqual([]);
+    expect(chunk.usage).toEqual({ prompt_tokens: 2, completion_tokens: 5, total_tokens: 7 });
+  });
+});
+
 describe('AI API provider parameter forwarding', () => {
   it('forwards model and tool-call parameters not managed by the gateway', () => {
     const parameters = getProviderRequestParameters({

package/src/server/__tests__/permission-sync.test.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 { Context } from '@nocobase/actions';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { PluginAiApiServer } from '../plugin';
+import { invalidateUserPermissionCache, resolveUserAccessScope } from '../utils/user-permissions';
+
+/**
+ * Covers the cross-node half of permission revocation.
+ *
+ * syncMessageManager hardcodes `skipSelf: true` (sync-message-manager.ts:59,73), so the node
+ * that writes the change never receives its own broadcast. That makes two things load-bearing
+ * and easy to regress: the writer must invalidate its own cache locally, and every other node
+ * must invalidate on receipt. Neither is observable from a single-node test of the cache alone.
+ */
+function mockContext(userId: number, row: unknown) {
+  const findOne = vi.fn(async () => row);
+  const ctx = {
+    state: { currentUser: { id: userId } },
+    db: { getRepository: () => ({ findOne }) },
+    app: { name: 'main' },
+    log: { warn: vi.fn(), error: vi.fn() },
+  } as unknown as Context;
+  return { ctx, findOne };
+}
+
+function row(values: Record<string, unknown>) {
+  return { get: (key: string) => values[key] };
+}
+
+beforeEach(() => {
+  invalidateUserPermissionCache();
+});
+
+describe('cross-node permission invalidation', () => {
+  it("drops the receiving node's cached scope", async () => {
+    const plugin = Object.create(PluginAiApiServer.prototype) as PluginAiApiServer;
+    const { ctx, findOne } = mockContext(1, row({ allowedLlmServices: ['openai'] }));
+
+    await resolveUserAccessScope(ctx);
+    await resolveUserAccessScope(ctx);
+    expect(findOne).toHaveBeenCalledTimes(1);
+
+    await plugin.handleSyncMessage({ type: 'invalidateUserPermissions', userId: 1 });
+
+    await resolveUserAccessScope(ctx);
+    expect(findOne).toHaveBeenCalledTimes(2);
+  });
+
+  it('ignores unrelated message types and other users', async () => {
+    const plugin = Object.create(PluginAiApiServer.prototype) as PluginAiApiServer;
+    const { ctx, findOne } = mockContext(1, row({ allowedLlmServices: ['openai'] }));
+    await resolveUserAccessScope(ctx);
+
+    await plugin.handleSyncMessage({ type: 'somethingElse', userId: 1 });
+    await plugin.handleSyncMessage({ type: 'invalidateUserPermissions', userId: 2 });
+
+    await resolveUserAccessScope(ctx);
+    expect(findOne).toHaveBeenCalledTimes(1);
+  });
+
+  it('tolerates a malformed message instead of throwing into the subscriber', async () => {
+    const plugin = Object.create(PluginAiApiServer.prototype) as PluginAiApiServer;
+    await expect(plugin.handleSyncMessage(undefined as never)).resolves.toBeUndefined();
+    await expect(plugin.handleSyncMessage({} as never)).resolves.toBeUndefined();
+  });
+
+  it('invalidates locally as well as broadcasting, since the publisher is skipped', async () => {
+    const plugin = Object.create(PluginAiApiServer.prototype) as PluginAiApiServer;
+    const sendSyncMessage = vi.fn(async () => undefined);
+    Object.assign(plugin, { sendSyncMessage });
+
+    const { ctx, findOne } = mockContext(1, row({ allowedLlmServices: ['openai'] }));
+    await resolveUserAccessScope(ctx);
+    expect(findOne).toHaveBeenCalledTimes(1);
+
+    // revokeUserPermissions is private; reach it the way the db hook does.
+    (plugin as unknown as { revokeUserPermissions: (id: unknown, tx?: unknown) => void }).revokeUserPermissions(1);
+
+    // Local cache cleared without any message coming back to us.
+    await resolveUserAccessScope(ctx);
+    expect(findOne).toHaveBeenCalledTimes(2);
+    expect(sendSyncMessage).toHaveBeenCalledWith(
+      { type: 'invalidateUserPermissions', userId: 1 },
+      { transaction: undefined },
+    );
+  });
+
+  it('defers the broadcast to the transaction so other nodes cannot re-cache the old row', async () => {
+    const plugin = Object.create(PluginAiApiServer.prototype) as PluginAiApiServer;
+    const sendSyncMessage = vi.fn(async () => undefined);
+    Object.assign(plugin, { sendSyncMessage });
+    const transaction = { id: 'tx-1' };
+
+    (plugin as unknown as { revokeUserPermissions: (id: unknown, tx?: unknown) => void }).revokeUserPermissions(
+      7,
+      transaction,
+    );
+
+    expect(sendSyncMessage).toHaveBeenCalledWith({ type: 'invalidateUserPermissions', userId: 7 }, { transaction });
+  });
+});