feat(security): add multiTenant switch + cache field-name lookups

hotlong · Copilot · hotlong · commit b2552d153e28 · 2026-05-08T11:13:25.000+08:00
Single-tenant deployments shouldn't pay the cost of the multi-tenant
security pipeline. New `SecurityPlugin({ multiTenant: false })` option
(default `true`) disables:

  1. organization_id auto-injection on insert (skips a metadata lookup
     per insert; owner_id injection still runs).
  2. Wildcard `tenant_isolation` RLS policy collection — any policy
     whose USING clause references current_user.organization_id is
     stripped from the per-request policy set, so the field-existence
     safety net never has to drop them individually.

Owner-based RLS, per-object CRUD checks, and Field-Level Security are
unaffected by the flag.

Also added a positive-result cache for getObjectFieldNames so repeated
inserts/finds against the same object don't re-walk the metadata
service / ObjectQL registry on every call. Negative results are not
cached because schemas may simply not be registered yet at boot.

Wired through both runtime entry points:
  - packages/cli/src/commands/serve.ts
  - packages/plugins/plugin-dev/src/dev-plugin.ts
both reading OS_MULTI_TENANT (default true). Set OS_MULTI_TENANT=false
on the dev / serve command line to switch to single-tenant mode.

4 new tests in security-plugin.test.ts cover both modes (insert auto-
inject on/off, find tenant-policy applied/stripped). All 37 plugin
tests + 200 runtime tests pass.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`multiTenant` switch on `SecurityPlugin`** (`@objectstack/plugin-security`) — `new SecurityPlugin({ multiTenant: false })` disables the two pieces of the security pipeline that exist solely to support multi-organization deployments: the `organization_id` auto-injection on insert and the wildcard `tenant_isolation` RLS policy (`organization_id = current_user.organization_id`) shipped with the default `member_default` / `viewer_readonly` permission sets. In single-tenant mode every insert skips a metadata lookup, every find skips the field-existence safety net + RLS compile/AND-merge for the wildcard tenant policy, and the per-object schema lookup is now cached (positive results only — a `null` may simply mean the schema isn't registered yet at boot, so we let the next call retry). Owner-based RLS, per-object CRUD checks, and Field-Level Security are unaffected. Both the CLI dev server (`packages/cli/src/commands/serve.ts`) and the dev plugin (`packages/plugins/plugin-dev`) read `OS_MULTI_TENANT` (default `true`); set `OS_MULTI_TENANT=false` to switch a deployment to single-tenant. Four new tests in `security-plugin.test.ts` exercise both modes.
+
 - **Auto-injection of tenancy fields on insert** (`@objectstack/plugin-security`) — When an authenticated, non-system user inserts a record, SecurityPlugin now auto-populates `organization_id` (from `ctx.tenantId`) and `owner_id` (from `ctx.userId`) **only when the field exists on the target object** (looked up via `getObjectFieldNames(metadata, object, ql)`) **and the payload has not already specified it**. This closes the gap that previously caused logged-in users to create rows with `organization_id = NULL`, which the default `tenant_isolation` RLS policy (`organization_id = current_user.organization_id`) would then hide on subsequent reads. System contexts (`ctx.isSystem === true`) are skipped — seeds and platform-admin operations remain explicit. Caller-wins semantics: explicit `organization_id` / `owner_id` in the payload are never overwritten, so cross-org admin grants and cross-tenant link tables (e.g. `sys_user_permission_set` with `organization_id = NULL`) still work.
 - **Seed loader runs as system context** (`@objectstack/runtime`) — `SeedLoaderService.writeRecord` and the `app-plugin.ts` basic-insert fallback now pass `{ context: { isSystem: true } }` on every `engine.insert` / `engine.update` / `engine.find` call. This (a) bypasses RBAC checks so seeds can target system tables (`sys_*`) without granting wildcard permissions to a notional seed user, and (b) **disables auto-injection of tenancy fields**, ensuring seed records land exactly as authored — either with an explicit `organization_id` (org-scoped seeds) or with `organization_id = NULL` (intentionally cross-tenant / global metadata such as default permission sets). Combined with the auto-inject change above, this is the missing other half of "新增记录的时候也没有自动加上": user inserts get auto-tagged, seed inserts don't.
 
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
@@ -569,7 +569,12 @@ export default class Serve extends Command {
             try {
               const securityPkg = '@objectstack/plugin-security';
               const { SecurityPlugin } = await import(/* webpackIgnore: true */ securityPkg);
-              await kernel.use(new SecurityPlugin());
+              // `OS_MULTI_TENANT=false` disables wildcard tenant_isolation
+              // RLS policies and the `organization_id` auto-injection on
+              // insert. Keep multi-tenant on by default — most ObjectStack
+              // deployments are multi-org.
+              const multiTenant = String(process.env.OS_MULTI_TENANT ?? 'true').toLowerCase() !== 'false';
+              await kernel.use(new SecurityPlugin({ multiTenant }));
               trackPlugin('Security');
             } catch {
               // optional
diff --git a/packages/plugins/plugin-dev/src/dev-plugin.ts b/packages/plugins/plugin-dev/src/dev-plugin.ts
@@ -554,9 +554,10 @@ export class DevPlugin implements Plugin {
     if (enabled('security')) {
       try {
         const { SecurityPlugin } = await import('@objectstack/plugin-security') as any;
-        const securityPlugin = new SecurityPlugin();
+        const multiTenant = String(process.env.OS_MULTI_TENANT ?? 'true').toLowerCase() !== 'false';
+        const securityPlugin = new SecurityPlugin({ multiTenant });
         this.childPlugins.push(securityPlugin);
-        ctx.logger.info('  ✔ Security plugin enabled (RBAC, RLS, field masking)');
+        ctx.logger.info(`  ✔ Security plugin enabled (RBAC, RLS, field masking; multiTenant=${multiTenant})`);
       } catch {
         ctx.logger.debug('  ℹ @objectstack/plugin-security not installed — skipping security');
       }
diff --git a/packages/plugins/plugin-security/README.md b/packages/plugins/plugin-security/README.md
@@ -33,6 +33,32 @@ kernel.use(new SecurityPlugin());
 await kernel.bootstrap();
 ```
 
+### Multi-tenant vs single-tenant
+
+`SecurityPlugin` defaults to **multi-tenant** mode. In this mode it:
+
+- Auto-injects `organization_id = ctx.tenantId` on insert when the target object declares an `organization_id` field.
+- Honours the wildcard `tenant_isolation` RLS policy
+  (`organization_id = current_user.organization_id`) shipped with the
+  default `member_default` / `viewer_readonly` permission sets.
+
+For single-tenant deployments, switch it off:
+
+```typescript
+kernel.use(new SecurityPlugin({ multiTenant: false }));
+```
+
+This skips the per-insert metadata lookup that drives `organization_id`
+auto-injection (the `owner_id` injection still runs) and strips wildcard
+`current_user.organization_id` policies from the per-request policy
+set so the field-existence safety net never has to drop them
+individually. Field-Level Security, owner-based RLS, and per-object
+CRUD checks operate identically regardless of this flag.
+
+In CLI / dev-server mode the same switch is exposed via the
+`OS_MULTI_TENANT` environment variable (default `true`); set
+`OS_MULTI_TENANT=false` before `objectstack serve` / `pnpm dev` to disable.
+
 ## Key Exports
 
 | Export | Kind | Description |
diff --git a/packages/plugins/plugin-security/src/security-plugin.test.ts b/packages/plugins/plugin-security/src/security-plugin.test.ts
@@ -90,6 +90,112 @@ describe('SecurityPlugin', () => {
     const plugin = new SecurityPlugin();
     await expect(plugin.destroy()).resolves.toBeUndefined();
   });
+
+  // -------------------------------------------------------------------------
+  // multiTenant switch — single-tenant mode strips tenant policies and skips
+  // organization_id auto-injection.
+  // -------------------------------------------------------------------------
+  const makeMiddlewareCtx = (overrides: { permissionSets: PermissionSet[]; objectFields?: string[] }) => {
+    const fields: Record<string, any> = {};
+    for (const f of overrides.objectFields ?? ['id', 'organization_id', 'owner_id', 'name']) {
+      fields[f] = { name: f };
+    }
+    let middleware: any;
+    const ql = {
+      registerMiddleware: (mw: any) => {
+        // Capture only the FIRST middleware (the security CRUD one);
+        // ignore the secondary bootstrap-replay middleware registered
+        // later in `start()`.
+        if (!middleware) middleware = mw;
+      },
+      getSchema: () => ({ name: 'task', fields }),
+    };
+    const metadata = {
+      get: async () => ({ name: 'task', fields }),
+      list: async () => overrides.permissionSets,
+    };
+    const services: Record<string, any> = {
+      manifest: { register: vi.fn() },
+      objectql: ql,
+      metadata,
+    };
+    const ctx: any = {
+      logger: { info: vi.fn(), warn: vi.fn() },
+      registerService: vi.fn(),
+      getService: (name: string) => services[name],
+    };
+    return {
+      ctx,
+      run: async (opCtx: any) => {
+        await middleware(opCtx, async () => {});
+        return opCtx;
+      },
+    };
+  };
+
+  const tenantPolicySet: PermissionSet = {
+    name: 'member_default',
+    label: 'Member',
+    isProfile: true,
+    objects: { '*': { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true } },
+    rowLevelSecurity: [
+      { name: 'tenant_isolation', object: '*', operation: 'all', using: 'organization_id = current_user.organization_id' },
+    ],
+  } as any;
+
+  it('multiTenant: true — auto-injects organization_id on insert', async () => {
+    const plugin = new SecurityPlugin({ multiTenant: true, fallbackPermissionSet: 'member_default' });
+    const harness = makeMiddlewareCtx({ permissionSets: [tenantPolicySet] });
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    const opCtx: any = {
+      object: 'task', operation: 'insert', data: { name: 'A' },
+      context: { userId: 'u1', tenantId: 'org-1', roles: [], permissions: [] },
+    };
+    await harness.run(opCtx);
+    expect(opCtx.data.organization_id).toBe('org-1');
+    expect(opCtx.data.owner_id).toBe('u1');
+  });
+
+  it('multiTenant: false — does NOT auto-inject organization_id, still injects owner_id', async () => {
+    const plugin = new SecurityPlugin({ multiTenant: false, fallbackPermissionSet: 'member_default' });
+    const harness = makeMiddlewareCtx({ permissionSets: [tenantPolicySet] });
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    const opCtx: any = {
+      object: 'task', operation: 'insert', data: { name: 'A' },
+      context: { userId: 'u1', tenantId: 'org-1', roles: [], permissions: [] },
+    };
+    await harness.run(opCtx);
+    expect(opCtx.data.organization_id).toBeUndefined();
+    expect(opCtx.data.owner_id).toBe('u1');
+  });
+
+  it('multiTenant: false — strips tenant_isolation RLS so find applies no tenant where', async () => {
+    const plugin = new SecurityPlugin({ multiTenant: false, fallbackPermissionSet: 'member_default' });
+    const harness = makeMiddlewareCtx({ permissionSets: [tenantPolicySet] });
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    const opCtx: any = {
+      object: 'task', operation: 'find', ast: { where: undefined },
+      context: { userId: 'u1', tenantId: 'org-1', roles: [], permissions: [] },
+    };
+    await harness.run(opCtx);
+    expect(opCtx.ast.where).toBeUndefined();
+  });
+
+  it('multiTenant: true — applies tenant_isolation RLS to find', async () => {
+    const plugin = new SecurityPlugin({ multiTenant: true, fallbackPermissionSet: 'member_default' });
+    const harness = makeMiddlewareCtx({ permissionSets: [tenantPolicySet] });
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    const opCtx: any = {
+      object: 'task', operation: 'find', ast: { where: undefined },
+      context: { userId: 'u1', tenantId: 'org-1', roles: [], permissions: [] },
+    };
+    await harness.run(opCtx);
+    expect(opCtx.ast.where).toEqual({ organization_id: 'org-1' });
+  });
 });
 
 // ---------------------------------------------------------------------------
diff --git a/packages/plugins/plugin-security/src/security-plugin.ts b/packages/plugins/plugin-security/src/security-plugin.ts
@@ -30,6 +30,34 @@ export interface SecurityPluginOptions {
    * @default 'member_default'
    */
   fallbackPermissionSet?: string | null;
+  /**
+   * Whether this deployment is multi-tenant.
+   *
+   * When `true` (default), SecurityPlugin:
+   *   - Auto-injects `organization_id = ctx.tenantId` on insert when
+   *     the target object declares an `organization_id` field.
+   *   - Honours the wildcard `tenant_isolation` RLS policy
+   *     (`organization_id = current_user.organization_id`) shipped with
+   *     the default `member_default` / `viewer_readonly` permission
+   *     sets.
+   *
+   * When `false`, SecurityPlugin:
+   *   - Skips the `organization_id` auto-injection block (saves a
+   *     metadata lookup per insert; `owner_id` injection still runs).
+   *   - Strips any RLS policy whose USING expression references
+   *     `current_user.organization_id` from the per-request policy
+   *     set, so single-tenant deployments don't pay the
+   *     field-existence safety-net cost on every find.
+   *
+   * Field-Level Security, owner-based RLS, and per-object permission
+   * checks (allowRead/allowCreate/…) all operate identically regardless
+   * of this flag. Set this to `false` for single-tenant or
+   * single-organization deployments where `organization_id` carries no
+   * meaning.
+   *
+   * @default true
+   */
+  multiTenant?: boolean;
 }
 
 /**
@@ -56,6 +84,15 @@ export class SecurityPlugin implements Plugin {
   private fieldMasker = new FieldMasker();
   private readonly bootstrapPermissionSets: PermissionSet[];
   private readonly fallbackPermissionSet: string | null;
+  private readonly multiTenant: boolean;
+  /**
+   * Per-object field-name cache. Populated lazily from the metadata
+   * service / ObjectQL registry on first access per object. Schemas are
+   * effectively immutable for the lifetime of the kernel today (hot
+   * reload tears the kernel down), so we don't bother with
+   * invalidation — a kernel restart drops the cache.
+   */
+  private readonly fieldNamesCache = new Map<string, Set<string> | null>();
 
   constructor(options: SecurityPluginOptions = {}) {
     this.bootstrapPermissionSets =
@@ -64,6 +101,7 @@ export class SecurityPlugin implements Plugin {
       options.fallbackPermissionSet === undefined
         ? 'member_default'
         : options.fallbackPermissionSet;
+    this.multiTenant = options.multiTenant !== false;
   }
 
   async init(ctx: PluginContext): Promise<void> {
@@ -173,7 +211,7 @@ export class SecurityPlugin implements Plugin {
         }
       }
 
-      // 3.5. Auto-inject tenancy fields on insert.
+      // 3.5. Auto-inject tenancy/ownership fields on insert.
       //
       // When an authenticated user inserts a record, the canonical
       // tenant column (`organization_id`) and ownership column
@@ -189,28 +227,36 @@ export class SecurityPlugin implements Plugin {
       //     untouched)
       //   - aren't already set in the payload (caller wins)
       //   - have a corresponding value on the execution context.
+      //
+      // The `organization_id` half is gated on `multiTenant`; in
+      // single-tenant deployments it's pure overhead.
       if (
         opCtx.operation === 'insert' &&
         opCtx.data &&
         typeof opCtx.data === 'object' &&
         !Array.isArray(opCtx.data)
       ) {
-        const fields = await this.getObjectFieldNames(metadata, opCtx.object, ql);
-        if (fields) {
-          const data = opCtx.data as Record<string, unknown>;
-          if (
-            opCtx.context?.tenantId &&
-            fields.has('organization_id') &&
-            (data.organization_id == null || data.organization_id === '')
-          ) {
-            data.organization_id = opCtx.context.tenantId;
-          }
-          if (
-            opCtx.context?.userId &&
-            fields.has('owner_id') &&
-            (data.owner_id == null || data.owner_id === '')
-          ) {
-            data.owner_id = opCtx.context.userId;
+        const needsTenant =
+          this.multiTenant && !!opCtx.context?.tenantId;
+        const needsOwner = !!opCtx.context?.userId;
+        if (needsTenant || needsOwner) {
+          const fields = await this.getObjectFieldNames(metadata, opCtx.object, ql);
+          if (fields) {
+            const data = opCtx.data as Record<string, unknown>;
+            if (
+              needsTenant &&
+              fields.has('organization_id') &&
+              (data.organization_id == null || data.organization_id === '')
+            ) {
+              data.organization_id = opCtx.context!.tenantId;
+            }
+            if (
+              needsOwner &&
+              fields.has('owner_id') &&
+              (data.owner_id == null || data.owner_id === '')
+            ) {
+              data.owner_id = opCtx.context!.userId;
+            }
           }
         }
       }
@@ -324,7 +370,25 @@ export class SecurityPlugin implements Plugin {
 
     for (const ps of permissionSets) {
       if (ps.rowLevelSecurity) {
-        allPolicies.push(...ps.rowLevelSecurity);
+        for (const policy of ps.rowLevelSecurity) {
+          // In single-tenant mode, strip any policy that filters on
+          // `current_user.organization_id` — there is no meaningful
+          // tenant to compare against, so the policy would either drop
+          // every row (when the field exists on the object) or be
+          // dropped by the field-existence safety net. Either way it's
+          // pure overhead. Substring match is sufficient: every
+          // wildcard tenant policy in the default permission sets uses
+          // exactly this token, and authors who want a different
+          // multi-tenant story should turn `multiTenant: false` off.
+          if (
+            !this.multiTenant &&
+            policy.using &&
+            policy.using.includes('current_user.organization_id')
+          ) {
+            continue;
+          }
+          allPolicies.push(policy);
+        }
       }
     }
 
@@ -339,6 +403,24 @@ export class SecurityPlugin implements Plugin {
     metadata: any,
     objectName: string,
     ql?: any,
+  ): Promise<Set<string> | null> {
+    if (this.fieldNamesCache.has(objectName)) {
+      return this.fieldNamesCache.get(objectName) ?? null;
+    }
+    const result = await this.loadObjectFieldNames(metadata, objectName, ql);
+    // Only cache positive resolutions — a `null` may simply mean the
+    // schema isn't registered yet at boot, and we want subsequent calls
+    // to retry rather than be permanently denied.
+    if (result) {
+      this.fieldNamesCache.set(objectName, result);
+    }
+    return result;
+  }
+
+  private async loadObjectFieldNames(
+    metadata: any,
+    objectName: string,
+    ql?: any,
   ): Promise<Set<string> | null> {
     try {
       let obj = await metadata?.get?.('object', objectName);
