feat(rest): REST gates consume the shared derivation resolver (#3391 PR-2)

Route every per-object exposure gate through the spec's single derivation source
of truth, so the three-state whitelist and the derived verbs are resolved
identically everywhere.

- Main gate (`apiAccessDenialFromEnable`): resolver-backed; `[]` → deny-all;
  the 405 body's `allowed` array is now the EFFECTIVE operation set (enum-
  ordered), not the raw whitelist. `enforceApiAccess` forwards writeMode /
  bulkChild opts.
- Import: two-stage gate — a coarse `create ∨ update` check 405s fully-closed
  objects before the CSV parse; a writeMode-precise second stage
  (insert→create, update→update, upsert→create∧update) after prep resolves the
  mode.
- Export: reverse-derives from `list`, and the schema-derived column header is
  projected to the FLS-readable set (union of masked-row keys) so export can
  never expose a wider column set than list. Explicit `?fields=` is honored but
  masked values stay empty.
- Bulk: all five surfaces (createMany/updateMany/deleteMany, per-object /batch,
  cross-object /batch) require `bulk ∧ child`.
- platform-objects: the four in-repo explicit-whitelist identity objects gain
  the `bulk` primitive so their Many/batch surfaces keep working.

Tests: rest exposure suite (405 allowed = effective, deny-all, bulk∧child),
new rest-api-derivation-gates suite, batch endpoint bulk cases, and two
blocking export FLS column-projection tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012L8EfEa157Pe6C73qRnaJH

Author: claude

packages/platform-objects/src/identity/sys-business-unit-member.object.ts

@@ -108,6 +108,9 @@ export const SysBusinessUnitMember = ObjectSchema.create({
     // P2 derives these from create/update|list and reclaims the explicit
     // entries. Reconcile-safe: import/export are not generic write verbs, so
     // reconcileManagedApiMethods (managedBy:'platform') never strips them.
-    apiMethods: ['get', 'list', 'create', 'update', 'delete', 'import', 'export'],
+    // `bulk` grants the createMany/updateMany/deleteMany + batch surfaces (bulk
+    // ∧ child after #3391) — memberships are imported as one bulk operation.
+    // `bulk` is a primitive — a permanent, legitimate declaration, not P2 debt.
+    apiMethods: ['get', 'list', 'create', 'update', 'delete', 'bulk', 'import', 'export'],
   },
 });

packages/platform-objects/src/identity/sys-business-unit.object.ts

@@ -219,6 +219,9 @@ export const SysBusinessUnit = ObjectSchema.create({
     // Data portability is expected for the org tree: fields like `external_ref`
     // and `effective_from/to` are designed for HRIS batch sync (#3025). Import
     // reuses the create/update affordances this object already grants.
-    apiMethods: ['get', 'list', 'create', 'update', 'delete', 'import', 'export'],
+    // `bulk` grants the createMany/updateMany/deleteMany + batch surfaces, which
+    // after #3391 require the `bulk` primitive (bulk ∧ child). `bulk` is a
+    // primitive — a permanent, legitimate declaration, not P0/P2 debt.
+    apiMethods: ['get', 'list', 'create', 'update', 'delete', 'bulk', 'import', 'export'],
   },
 });

packages/platform-objects/src/identity/sys-user-preference.object.ts

@@ -115,6 +115,9 @@ export const SysUserPreference = ObjectSchema.create({
     trackHistory: false,
     searchable: false,
     apiEnabled: true,
-    apiMethods: ['get', 'list', 'create', 'update', 'delete'],
+    // `bulk` grants the createMany/updateMany/deleteMany + batch surfaces, which
+    // after #3391 require the `bulk` primitive (bulk ∧ child). `bulk` is a
+    // primitive — a permanent, legitimate declaration.
+    apiMethods: ['get', 'list', 'create', 'update', 'delete', 'bulk'],
   },
 });

packages/platform-objects/src/identity/sys-user.object.ts

@@ -758,8 +758,11 @@ export const SysUser = ObjectSchema.create({
     // actions), so they are not exposed. `update` stays: it is the ONE
     // generic write opened on an identity table (ADR-0092 D4), server-side
     // clamped to the profile-field whitelist ({name, image}) by the guard —
-    // `userActions.edit: true` above declares the affordance.
-    apiMethods: ['get', 'list', 'update'],
+    // `userActions.edit: true` above declares the affordance. `bulk` grants the
+    // updateMany surface (bulk ∧ update after #3391); paired with the sole
+    // `update` write, only bulk-update is admitted (createMany/deleteMany still
+    // 405). `bulk` is a primitive — a permanent, legitimate declaration.
+    apiMethods: ['get', 'list', 'update', 'bulk'],
   },
 
   // Email uniqueness is enforced by the unique index above (and better-auth's

packages/rest/src/export-integration.test.ts

@@ -316,3 +316,70 @@ describe('export route — real engine + protocol integration', () => {
     expect(dataRows[0][2]).toBe('是');
   });
 });
+
+// ===========================================================================
+// #3391 blocking test: export column projection ≡ list's field-level security.
+// The derivation contract opens export from `list`, so export MUST NOT expose a
+// wider column set than list. The read middleware DELETES unreadable keys, so a
+// schema-derived export header would otherwise leak the *names* of FLS-hidden
+// columns as empty cells. These two tests are the "阻塞性测试" — they fail
+// (red) against the pre-#3391 header (= full schema) and pass after the fix.
+// ===========================================================================
+describe('export route — FLS column projection (#3391 blocking)', () => {
+  // Simulate field-level security with the exact delete-key semantics the
+  // security FieldMasker uses: strip `title` from every task row on read.
+  const maskTitle = (engine: any) =>
+    engine.registerHook(
+      'afterFind',
+      (ctx: any) => { if (Array.isArray(ctx.result)) for (const r of ctx.result) { if (r) delete r.title; } },
+      { object: 'task' },
+    );
+
+  it('schema-derived header is narrowed to the masked-readable column set (CSV + JSON)', async () => {
+    const { engine, protocol, route } = await boot();
+    maskTitle(engine);
+
+    // The list key set under the SAME read path (afterFind runs on find too).
+    const listRes: any = await protocol.findData({ object: 'task', query: {} });
+    const listRows: any[] = listRes.records ?? listRes.data ?? [];
+    const listKeys = new Set<string>();
+    for (const r of listRows) for (const k of Object.keys(r)) listKeys.add(k);
+    expect(listKeys.has('title')).toBe(false); // masked out of list too
+
+    // CSV: the masked column's header (标题) must be gone — no empty leak column.
+    const csv = makeRes();
+    await route.handler({ params: { object: 'task' }, query: { format: 'csv' } } as any, csv.res);
+    const header = parseCsv(csv.chunks.join(''))[0];
+    expect(header).not.toContain('标题');
+    expect(header).toEqual(['ID', '完成', '优先级', '截止', '负责人']);
+
+    // JSON: every exported row's key set ⊆ the list key set; title never present.
+    const json = makeRes();
+    await route.handler({ params: { object: 'task' }, query: { format: 'json' } } as any, json.res);
+    const arr = JSON.parse(json.chunks.join(''));
+    expect(arr.length).toBe(2);
+    for (const row of arr) {
+      for (const k of Object.keys(row)) expect(listKeys.has(k)).toBe(true);
+      expect('title' in row).toBe(false);
+    }
+  });
+
+  it('explicit ?fields= keeps a requested masked column but never emits its value', async () => {
+    const { engine, route } = await boot();
+    maskTitle(engine);
+
+    // An explicit request is honored (projection does NOT narrow it), but the
+    // masked value must always render as an empty cell — same as list `$select`.
+    const csv = makeRes();
+    await route.handler(
+      { params: { object: 'task' }, query: { format: 'csv', fields: 'id,title' } } as any,
+      csv.res,
+    );
+    const rows = parseCsv(csv.chunks.join(''));
+    expect(rows[0]).toEqual(['ID', '标题']); // header kept as requested
+    for (const r of rows.slice(1)) {
+      expect(r[0]).not.toBe('');    // id present
+      expect(r[1] ?? '').toBe('');  // title masked → always empty, never a value
+    }
+  });
+});

packages/rest/src/rest-api-derivation-gates.test.ts

@@ -0,0 +1,129 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #3391 — the REST per-object exposure gate consumes the spec's single
+// derivation source of truth (`resolveEffectiveApiMethods` /
+// `isApiOperationAllowed`). This suite pins the gate DECISION
+// (`apiAccessDenialFromEnable`) against the derivation contract: reverse-derived
+// import/export, writeMode-precise import, deny-all, bulk∧child, and the
+// explicit-legacy compatibility path. Route-level plumbing (createMany/batch,
+// import two-stage, export projection) is covered by rest.test.ts,
+// rest-batch-endpoint.test.ts, and export-integration.test.ts.
+
+import { describe, it, expect } from 'vitest';
+import { apiAccessDenialFromEnable } from './rest-server';
+
+/** True when the gate allows the operation (no denial object). */
+function allowed(enable: any, op: string, opts?: any): boolean {
+  return apiAccessDenialFromEnable(enable, 'obj', op, opts) === null;
+}
+/** The denial (status/body) or null. */
+function denial(enable: any, op: string, opts?: any) {
+  return apiAccessDenialFromEnable(enable, 'obj', op, opts);
+}
+
+describe('REST gate — three-state (#3391)', () => {
+  it('no enable / unrestricted → everything allowed', () => {
+    expect(allowed(undefined, 'create')).toBe(true);
+    expect(allowed({}, 'delete')).toBe(true);
+    expect(allowed({ apiEnabled: true }, 'export')).toBe(true);
+  });
+
+  it('apiEnabled:false → 404', () => {
+    const d = denial({ apiEnabled: false }, 'get');
+    expect(d?.status).toBe(404);
+    expect(d?.body.code).toBe('OBJECT_API_DISABLED');
+  });
+
+  it('empty whitelist [] → deny-all 405', () => {
+    const d = denial({ apiMethods: [] }, 'get');
+    expect(d?.status).toBe(405);
+    expect(d?.body.allowed).toEqual([]);
+    expect(allowed({ apiMethods: [] }, 'list')).toBe(false);
+  });
+});
+
+describe('REST gate — reverse-derived import/export (#3391)', () => {
+  // The sys_business_unit shape: a plain CRUD whitelist with NO explicit
+  // import/export must still admit import (⊆ create∨update) and export (⊆ list).
+  const crud = { apiMethods: ['get', 'list', 'create', 'update', 'delete'] };
+
+  it('CRUD whitelist admits import (reverse-derived from create/update)', () => {
+    expect(allowed(crud, 'import')).toBe(true);
+    expect(allowed(crud, 'import', { writeMode: 'insert' })).toBe(true);
+    expect(allowed(crud, 'import', { writeMode: 'update' })).toBe(true);
+    expect(allowed(crud, 'import', { writeMode: 'upsert' })).toBe(true);
+  });
+
+  it('CRUD whitelist admits export (reverse-derived from list)', () => {
+    expect(allowed(crud, 'export')).toBe(true);
+  });
+
+  it("['get','list'] admits export but not import", () => {
+    const ro = { apiMethods: ['get', 'list'] };
+    expect(allowed(ro, 'export')).toBe(true);
+    const d = denial(ro, 'import');
+    expect(d?.status).toBe(405);
+    // 405 body carries the effective set (list-derived reads), never `import`.
+    expect(d?.body.allowed).toContain('export');
+    expect(d?.body.allowed).not.toContain('import');
+  });
+});
+
+describe('REST gate — import writeMode precision (#3391)', () => {
+  it("['create'] admits insert-mode import, rejects update-mode", () => {
+    const createOnly = { apiMethods: ['get', 'list', 'create'] };
+    expect(allowed(createOnly, 'import', { writeMode: 'insert' })).toBe(true);
+    expect(allowed(createOnly, 'import', { writeMode: 'update' })).toBe(false);
+    // upsert needs create ∧ update → rejected
+    expect(allowed(createOnly, 'import', { writeMode: 'upsert' })).toBe(false);
+  });
+
+  it("['update'] admits update-mode import, rejects insert-mode", () => {
+    const updateOnly = { apiMethods: ['get', 'list', 'update'] };
+    expect(allowed(updateOnly, 'import', { writeMode: 'update' })).toBe(true);
+    expect(allowed(updateOnly, 'import', { writeMode: 'insert' })).toBe(false);
+  });
+
+  it('upsert-mode import needs both create and update', () => {
+    expect(allowed({ apiMethods: ['create', 'update'] }, 'import', { writeMode: 'upsert' })).toBe(true);
+    expect(allowed({ apiMethods: ['create'] }, 'import', { writeMode: 'upsert' })).toBe(false);
+  });
+});
+
+describe('REST gate — explicit legacy wins (deprecated, #3391)', () => {
+  it("explicit ['import'] admits import in every writeMode", () => {
+    const e = { apiMethods: ['import'] };
+    expect(allowed(e, 'import')).toBe(true);
+    expect(allowed(e, 'import', { writeMode: 'insert' })).toBe(true);
+    expect(allowed(e, 'import', { writeMode: 'update' })).toBe(true);
+  });
+});
+
+describe('REST gate — bulk ∧ child (#3391)', () => {
+  it("['create'] (no bulk) → createMany child gate rejects", () => {
+    expect(allowed({ apiMethods: ['create'] }, 'bulk', { bulkChild: 'create' })).toBe(false);
+  });
+
+  it("['create','bulk'] → createMany child gate admits", () => {
+    expect(allowed({ apiMethods: ['create', 'bulk'] }, 'bulk', { bulkChild: 'create' })).toBe(true);
+  });
+
+  it("['bulk'] (no create) → createMany child gate rejects (child op missing)", () => {
+    const d = denial({ apiMethods: ['bulk'] }, 'bulk', { bulkChild: 'create' });
+    expect(d?.status).toBe(405);
+  });
+
+  it('batch upsert child needs bulk ∧ create ∧ update', () => {
+    expect(allowed({ apiMethods: ['bulk', 'create', 'update'] }, 'bulk', { bulkChild: 'upsert' })).toBe(true);
+    expect(allowed({ apiMethods: ['bulk', 'create'] }, 'bulk', { bulkChild: 'upsert' })).toBe(false);
+  });
+});
+
+describe('REST gate — action alias normalization (#3391)', () => {
+  it('runtime action names map onto canonical operations', () => {
+    const ro = { apiMethods: ['get', 'list'] };
+    expect(allowed(ro, 'query')).toBe(true); // query → list
+    expect(allowed(ro, 'find')).toBe(true);  // find → list
+    expect(allowed(ro, 'batch', { bulkChild: 'create' })).toBe(false); // batch → bulk
+  });
+});

packages/rest/src/rest-batch-endpoint.test.ts

@@ -186,14 +186,39 @@ describe('POST {basePath}/batch — cross-object transactional batch', () => {
     expect(ql.transaction).not.toHaveBeenCalled();
   });
 
-  it('allows an operation that IS in the apiMethods whitelist', async () => {
+  it('allows an operation that IS in the apiMethods whitelist (with bulk)', async () => {
+    // #3391: the cross-object batch is a bulk surface — the object must grant the
+    // `bulk` primitive AND the child write (bulk ∧ create).
     const ql = makeQl();
-    const { route } = buildServer({ ql, objects: [{ name: 'ledger', enable: { apiMethods: ['create', 'read'] } }] });
+    const { route } = buildServer({ ql, objects: [{ name: 'ledger', enable: { apiMethods: ['create', 'bulk'] } }] });
     const res = await post(route, { operations: [{ object: 'ledger', action: 'create', data: { amount: 1 } }] });
     expect(res.statusCode).toBe(200);
     expect(ql.transaction).toHaveBeenCalledTimes(1);
   });
 
+  it('blocks a batch write when the object grants the child but not the bulk primitive (405, #3391)', async () => {
+    // create is whitelisted but `bulk` is not → the batch/Many surface is closed.
+    const ql = makeQl();
+    const { route } = buildServer({ ql, objects: [{ name: 'ledger', enable: { apiMethods: ['create'] } }] });
+    const res = await post(route, { operations: [{ object: 'ledger', action: 'create', data: { amount: 1 } }] });
+    expect(res.statusCode).toBe(405);
+    expect(res.body.code).toBe('OBJECT_API_METHOD_NOT_ALLOWED');
+    // the 405 body carries the EFFECTIVE operation set, not the raw whitelist
+    expect(res.body.allowed).toContain('create');
+    expect(res.body.allowed).not.toContain('bulk');
+    expect(ql.transaction).not.toHaveBeenCalled();
+  });
+
+  it('blocks a batch write when the object grants bulk but not the child (405, #3391)', async () => {
+    // bulk is present but the object cannot create → bulk ∧ create fails.
+    const ql = makeQl();
+    const { route } = buildServer({ ql, objects: [{ name: 'ledger', enable: { apiMethods: ['bulk', 'update'] } }] });
+    const res = await post(route, { operations: [{ object: 'ledger', action: 'create', data: { amount: 1 } }] });
+    expect(res.statusCode).toBe(405);
+    expect(res.body.code).toBe('OBJECT_API_METHOD_NOT_ALLOWED');
+    expect(ql.transaction).not.toHaveBeenCalled();
+  });
+
   // ── request validation ────────────────────────────────────────────────────
 
   it('rejects a non-atomic request (this endpoint is always atomic)', async () => {