fix(security): address self-review findings on the requireAuth flip + destructive-op gates

Correctness (record-level enforcement for the pre-mapped destructive ops):
- security-plugin middleware: extend the write-scope stash, the #1994
  pre-image RLS check, and the ADR-0055 controlled-by-parent write gate to
  cover transfer/restore/purge — the object-level RBAC bit was gated but the
  row-level defenses only listed update/delete/insert, so a granted user
  could have destroyed out-of-scope rows by id when the M2 ops ship. purge
  maps onto the delete RLS class, transfer/restore onto update. New unit
  test proves a not-owned purge is denied by the pre-image check.

Callsite coverage for the default flip:
- cli serve: carve-out now keys on (tierEnabled('auth') || hasAuthPlugin) —
  a stack mounting AuthPlugin explicitly under a minimal tier no longer gets
  an accidental fail-open override.
- plugin-dev: mirror the serve carve-out — an auth-less dev stack gets an
  explicit requireAuth:false so the local data API isn't bricked.
- spec: declare ObjectStackDefinitionSchema.api so the documented opt-out
  (and the enableProjectScoping/projectResolution/enforceProjectMembership
  knobs serve.ts already reads) survives defineStack strict parsing instead
  of being silently stripped. Verified: defineStack now returns the api key.
- rest-api-plugin: warn only on an explicit opt-out; add a misplaced-key
  guard for a flat api.requireAuth (silently ignored under the deny default).
- fix two in-tree tests that passed requireAuth at the wrong nesting.

Cleanup:
- derive the modifyAllRecords write-bypass key set from OPERATION_TO_PERMISSION
  + DESTRUCTIVE_OPERATIONS (module-level Set, no per-call array) so a future
  destructive op is covered automatically.

Docs / provenance:
- regenerate the auto-gen references (requireAuth + allow*{Transfer,Restore,
  Purge} describe text); CHANGELOG entry for the breaking flip; changeset
  migration note updated to the defineStack-level api opt-out + scope note.

Pre-existing anonymous-posture gap on /meta, dispatcher /graphql, and raw
hono /data (surfaces that never call enforceAuth) filed as #2567 — out of
scope for this flip.

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

Author: claude

.changeset/require-auth-secure-by-default.md

@@ -10,18 +10,28 @@ feat(security)!: `api.requireAuth` now defaults to `true` — anonymous access t
 **BREAKING.** The global `requireAuth` default flipped FROM `false` TO `true`
 (`RestApiConfigSchema.requireAuth` in `@objectstack/spec`, mirrored by
 `RestServer.normalizeConfig` in `@objectstack/rest`). Anonymous requests to
-`/data/*` CRUD + batch endpoints are now rejected with HTTP 401 unless the
-deployment explicitly opts out.
+the `/data/*` CRUD + batch endpoints are now rejected with HTTP 401 unless the
+deployment explicitly opts out. (Scope note: this gate covers the REST
+`/data/*` surface — the metadata read/write endpoints and the dispatcher
+GraphQL route have their own pre-existing anonymous posture, tracked
+separately; this flip does not change them.)
 
 **Migration (one line):** a deployment that intentionally serves data publicly
-(demo / playground / kiosk) must set the flag explicitly:
+(demo / playground / kiosk) sets the flag on the stack config — now a declared
+`ObjectStackDefinitionSchema.api` field, so it survives `defineStack` strict
+parsing (previously an undeclared top-level `api` key was silently stripped):
 
 ```ts
-api: { requireAuth: false }
+export default defineStack({
+  // …
+  api: { requireAuth: false },
+});
 ```
 
 The REST plugin logs a boot warning for the explicit opt-out so a fail-open
-posture is always visible.
+posture is always visible. A misplaced `api.requireAuth` at the plugin level
+(one nesting short) is now also called out with a boot warning instead of
+being silently ignored.
 
 **What keeps working with no action:**
 

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed — Security: anonymous access denied by default (BREAKING) + destructive-op RBAC gates
+
+- **`api.requireAuth` now defaults to `true`** (ADR-0056 D2 flip): anonymous
+  requests to `/data/*` CRUD + batch endpoints are rejected with HTTP 401
+  unless the deployment explicitly opts out with `api: { requireAuth: false }`
+  (the REST plugin logs a boot warning for the explicit opt-out). Share-links,
+  public forms (via the declaration-derived `publicFormGrant`), and the
+  control plane (`/auth`, `/health`, `/discovery`) keep working with no
+  action. `objectstack serve` passes an explicit `false` only for stacks with
+  no `auth` tier (nothing could authenticate against them). Conformance row
+  `requireAuth-default-flip` → `enforced`.
+- **`transfer` / `restore` / `purge` are RBAC-gated ahead of the ops** (#1883):
+  the permission evaluator maps them to `allowTransfer` / `allowRestore` /
+  `allowPurge` (with the `modifyAllRecords` super-user bypass), so when the
+  M2 operations ship there is no ungated window. Unmapped destructive
+  operations keep failing closed (ADR-0049).
+
 ### Added — ObjectUI one-month frontend scan + backend alignment summary
 
 Scanning `../objectui` from 2026-05-08 through 2026-06-08 shows a broad Studio

content/docs/references/api/rest-server.mdx

@@ -192,7 +192,7 @@ const result = BatchEndpointsConfig.parse(data);
 | **enableOpenApi** | `boolean` | ✅ | Enable OpenAPI 3.1 spec & docs viewer endpoints |
 | **enableProjectScoping** | `boolean` | ✅ | Enable project-scoped routing for data/meta/AI APIs |
 | **projectResolution** | `Enum<'required' \| 'optional' \| 'auto'>` | ✅ | Project ID resolution strategy |
-| **requireAuth** | `boolean` | ✅ | Reject anonymous requests on /data/* with HTTP 401 |
+| **requireAuth** | `boolean` | ✅ | Reject anonymous requests on /data/* with HTTP 401 (secure-by-default; set false to serve data publicly) |
 | **documentation** | `Object` | optional | OpenAPI/Swagger documentation config |
 | **responseFormat** | `Object` | optional | Response format options |
 

content/docs/references/security/permission.mdx

@@ -68,9 +68,9 @@ const result = FieldPermission.parse(data);
 | **allowRead** | `boolean` | ✅ | Read permission |
 | **allowEdit** | `boolean` | ✅ | Edit permission |
 | **allowDelete** | `boolean` | ✅ | Delete permission |
-| **allowTransfer** | `boolean` | ✅ | [EXPERIMENTAL — not enforced] Change record ownership |
-| **allowRestore** | `boolean` | ✅ | [EXPERIMENTAL — not enforced] Restore from trash (Undelete) |
-| **allowPurge** | `boolean` | ✅ | [EXPERIMENTAL — not enforced] Permanently delete (Hard Delete/GDPR) |
+| **allowTransfer** | `boolean` | ✅ | [RBAC-gated; operation pending M2] Change record ownership |
+| **allowRestore** | `boolean` | ✅ | [RBAC-gated; operation pending M2] Restore from trash (Undelete) |
+| **allowPurge** | `boolean` | ✅ | [RBAC-gated; operation pending M2] Permanently delete (Hard Delete/GDPR) |
 | **viewAllRecords** | `boolean` | ✅ | View All Data (Bypass Sharing) |
 | **modifyAllRecords** | `boolean` | ✅ | Modify All Data (Bypass Sharing) |
 | **readScope** | `Enum<'own' \| 'own_and_reports' \| 'unit' \| 'unit_and_below' \| 'org'>` | optional | [ADR-0057 D1] Read depth: own|unit|unit_and_below|org |

packages/cli/src/commands/serve.ts

@@ -1388,7 +1388,13 @@ export default class Serve extends Command {
         // entirely; such auth-less playgrounds get an EXPLICIT `false`
         // (fail-open), which the REST plugin surfaces with a boot warning.
         // Apps can always override via stack `api.requireAuth`.
-        const requireAuth = apiConfig.requireAuth ?? (tierEnabled('auth') ? true : false);
+        // Auth availability = tier auto-registers it OR the stack mounts
+        // AuthPlugin explicitly (hasAuthPlugin, computed above). Keying only on
+        // the tier would hand an explicit fail-open to a stack that ships auth
+        // via `plugins:` under a minimal tier set — re-opening the very hole
+        // the flip closes. Only a stack with NO auth at all gets the carve-out.
+        const requireAuth = apiConfig.requireAuth
+          ?? ((tierEnabled('auth') || hasAuthPlugin) ? true : false);
 
         try {
           const { createRestApiPlugin } = await import('@objectstack/rest');

packages/plugins/plugin-dev/src/dev-plugin.ts

@@ -528,6 +528,7 @@ export class DevPlugin implements Plugin {
     //     as part of its manifest), so no separate child plugin is needed.
 
     // 4. Auth Plugin
+    let authMounted = false;
     if (enabled('auth')) {
       try {
         const { AuthPlugin } = await import('@objectstack/plugin-auth') as any;
@@ -536,6 +537,7 @@ export class DevPlugin implements Plugin {
           baseUrl: this.options.authBaseUrl,
         });
         this.childPlugins.push(authPlugin);
+        authMounted = true;
         ctx.logger.info('  ✔ Auth plugin enabled (dev credentials)');
       } catch {
         ctx.logger.warn('  ✘ @objectstack/plugin-auth not installed — skipping auth');
@@ -601,9 +603,21 @@ export class DevPlugin implements Plugin {
     if (enabled('rest')) {
       try {
         const { createRestApiPlugin } = await import('@objectstack/rest') as any;
-        const restPlugin = createRestApiPlugin();
+        // Secure-by-default carve-out (mirrors `objectstack serve`, ADR-0056
+        // D2): when NO auth mounted in this dev stack (service disabled or
+        // plugin-auth not installed), nobody could ever authenticate — the
+        // deny default would brick the local playground's data API. Pass an
+        // EXPLICIT fail-open for that case; the REST plugin's boot warning
+        // keeps the posture visible.
+        const restPlugin = authMounted
+          ? createRestApiPlugin()
+          : createRestApiPlugin({ api: { api: { requireAuth: false } } as any });
         this.childPlugins.push(restPlugin);
-        ctx.logger.info('  ✔ REST API endpoints enabled (CRUD + metadata)');
+        ctx.logger.info(
+          authMounted
+            ? '  ✔ REST API endpoints enabled (CRUD + metadata)'
+            : '  ✔ REST API endpoints enabled (CRUD + metadata; anonymous ALLOWED — no auth mounted)',
+        );
       } catch {
         ctx.logger.debug('  ℹ @objectstack/rest not installed — skipping REST endpoints');
       }

packages/plugins/plugin-security/src/permission-evaluator.ts

@@ -36,6 +36,22 @@ const OPERATION_TO_PERMISSION: Record<string, keyof ObjectPermission> = {
  */
 const DESTRUCTIVE_OPERATIONS = new Set<string>(['transfer', 'restore', 'purge']);
 
+/**
+ * Permission keys covered by the `modifyAllRecords` super-user WRITE bypass:
+ * edit/delete plus the destructive lifecycle class, DERIVED from the two
+ * constants above so a future destructive op added to the map+set is covered
+ * automatically (hand-listing it inline is how bypass gaps happen — #1883).
+ * NOTE this means "Modify All Data" grants (incl. the wildcard on
+ * organization_admin / admin_full_access defaults) will cover
+ * transfer/restore/purge the moment the M2 ops ship — Salesforce semantics,
+ * confirmed in the #1883 disposition; revisit per-op when M2 lands.
+ */
+const MODIFY_ALL_WRITE_KEYS = new Set<keyof ObjectPermission>([
+  'allowEdit',
+  'allowDelete',
+  ...[...DESTRUCTIVE_OPERATIONS].map((op) => OPERATION_TO_PERMISSION[op]),
+]);
+
 /**
  * [ADR-0066 D2] Resolve the object permission a permission set contributes for
  * `objectName`, honouring the secure-by-default posture:
@@ -92,13 +108,9 @@ export class PermissionEvaluator {
       // but a `private` object is excluded from a non-super-user wildcard.
       const objPerm = resolveObjectPermission(ps, objectName, opts.isPrivate ?? false);
       if (objPerm) {
-        // Check if modifyAllRecords is set (super-user bypass for write ops,
-        // including the destructive lifecycle class — transfer/restore/purge —
-        // so a "Modify All Data" grant is not bricked by the #1883 gate)
-        if (
-          ['allowEdit', 'allowDelete', 'allowTransfer', 'allowRestore', 'allowPurge'].includes(permKey) &&
-          objPerm.modifyAllRecords
-        ) {
+        // Super-user WRITE bypass ("Modify All Data") — covers edit/delete and
+        // the destructive lifecycle class (see MODIFY_ALL_WRITE_KEYS).
+        if (MODIFY_ALL_WRITE_KEYS.has(permKey) && objPerm.modifyAllRecords) {
           return true;
         }
         // Check if viewAllRecords is set (super-user bypass for read ops)

packages/plugins/plugin-security/src/security-plugin.test.ts

@@ -292,6 +292,36 @@ describe('SecurityPlugin', () => {
       expect(harness.findOne).toHaveBeenCalledTimes(1);
     });
 
+    it('DENIES a purge of a not-owned row via the pre-image check (#1883 — destructive ops inherit row-level gating)', async () => {
+      // The destructive lifecycle class (transfer/restore/purge) is pre-wired
+      // into OPERATION_TO_PERMISSION, so it clears the object-level RBAC gate.
+      // The record-level pre-image RLS check must therefore ALSO cover it —
+      // otherwise a grant-holder could destroy out-of-scope rows by id. purge
+      // maps onto the `delete` RLS class.
+      const purgerSet: PermissionSet = {
+        name: 'purger', label: 'Purger', isProfile: true,
+        objects: { '*': { allowRead: true, allowPurge: true } },
+        rowLevelSecurity: [
+          { name: 'owner_only_deletes', object: '*', operation: 'delete', using: 'created_by = current_user.id' },
+        ],
+      } as any;
+      const plugin = new SecurityPlugin({ fallbackPermissionSet: 'purger' });
+      const harness = makeMiddlewareCtx({
+        permissionSets: [purgerSet],
+        objectFields: ownerFields,
+        findOneImpl: () => null, // row exists but not owned → filtered out → deny
+      });
+      await plugin.init(harness.ctx);
+      await plugin.start(harness.ctx);
+      const opCtx: any = {
+        object: 'task', operation: 'purge',
+        options: { where: { id: 'r1' } },
+        context: memberCtx,
+      };
+      await expect(harness.run(opCtx)).rejects.toMatchObject({ name: 'PermissionDeniedError' });
+      expect(harness.findOne).toHaveBeenCalledTimes(1);
+    });
+
     it('SKIPS the check when no RLS policy applies (e.g. modifyAllRecords / admin) — no extra read', async () => {
       const adminSet: PermissionSet = {
         name: 'admin_full_access', label: 'Admin', isProfile: true,

packages/plugins/plugin-security/src/security-plugin.ts

@@ -433,7 +433,7 @@ export class SecurityPlugin implements Plugin {
         const sc: any = opCtx.context;
         if (['find', 'findOne', 'count', 'aggregate'].includes(opCtx.operation)) {
           sc.__readScope = this.permissionEvaluator.getEffectiveScope('read', opCtx.object, permissionSets, { isPrivate: secMeta.isPrivate });
-        } else if (opCtx.operation === 'update' || opCtx.operation === 'delete') {
+        } else if (['update', 'delete', 'transfer', 'restore', 'purge'].includes(opCtx.operation)) {
           sc.__writeScope = this.permissionEvaluator.getEffectiveScope('write', opCtx.object, permissionSets, { isPrivate: secMeta.isPrivate });
         }
       }
@@ -457,17 +457,28 @@ export class SecurityPlugin implements Plugin {
       // applies — e.g. an admin set with no RLS, or `modifyAllRecords`) the
       // check is skipped and behaviour is unchanged.
       if (
-        (opCtx.operation === 'update' || opCtx.operation === 'delete') &&
+        // update/delete today; transfer/restore/purge are pre-wired (#1883) so
+        // the M2 ops inherit the pre-image check the moment they dispatch —
+        // the CRUD bit alone must never be the only row-level defense.
+        ['update', 'delete', 'transfer', 'restore', 'purge'].includes(opCtx.operation) &&
         permissionSets.length > 0 &&
         !!opCtx.context?.userId &&
         this.ql
       ) {
         const targetId = this.extractSingleId(opCtx);
         if (targetId != null) {
+          // RLS policies declare select/insert/update/delete — map the
+          // destructive lifecycle class onto its nearest write class so
+          // authored policies apply (purge destroys like delete;
+          // transfer/restore mutate like update).
+          const rlsOperation =
+            opCtx.operation === 'purge' ? 'delete'
+            : opCtx.operation === 'transfer' || opCtx.operation === 'restore' ? 'update'
+            : opCtx.operation;
           const writeFilter = await this.computeRlsFilter(
             permissionSets,
             opCtx.object,
-            opCtx.operation,
+            rlsOperation,
             opCtx.context,
           );
           if (writeFilter) {
@@ -504,7 +515,7 @@ export class SecurityPlugin implements Plugin {
       // authored RLS, so the #1994 pre-image check above is a no-op for it; this
       // closes the by-id write path by checking the master instead.
       if (
-        (opCtx.operation === 'insert' || opCtx.operation === 'update' || opCtx.operation === 'delete') &&
+        ['insert', 'update', 'delete', 'transfer', 'restore', 'purge'].includes(opCtx.operation) &&
         permissionSets.length > 0 &&
         !!opCtx.context?.userId &&
         this.ql

packages/rest/src/rest-api-plugin.ts

@@ -215,20 +215,28 @@ export function createRestApiPlugin(config: RestApiPluginConfig = {}): Plugin {
                 ctx.logger.info('REST API successfully registered');
 
                 // ADR-0056 D2 (warn → enforce, ENFORCED): the global default is
-                // now secure-by-default — anonymous requests to /data/* are
-                // denied unless the deployment explicitly opts out. The warning
-                // remains for that explicit opt-out so a fail-open posture is
-                // always visible in the boot log. (Reads the nested
-                // `api.api.requireAuth` — the flat read here previously warned
-                // even when requireAuth was on.)
-                const effectiveRequireAuth = (config.api as any)?.api?.requireAuth ?? true;
-                if (!effectiveRequireAuth) {
+                // secure-by-default — anonymous /data/* is denied unless the
+                // deployment explicitly opts out. The warning remains for that
+                // explicit opt-out so a fail-open posture is always visible.
+                if ((config.api as any)?.api?.requireAuth === false) {
                     ctx.logger.warn(
                         '[security] anonymous access to the data API is ALLOWED (api.requireAuth=false, explicit opt-out) — ' +
                         'objects without OWD/RLS are world-readable. Remove the opt-out for secure-by-default and ' +
                         'expose public records via share-links / publicSharing / public forms (ADR-0056 D2).',
                     );
                 }
+                // Misplaced-key guard: the effective key is `api.api.requireAuth`
+                // (RestApiPluginConfig.api is the full RestServerConfig). A flat
+                // `api.requireAuth` is silently ignored by normalizeConfig — under
+                // the deny default that turns an INTENDED public deployment into a
+                // 401 outage with no diagnostic, so name the mistake loudly.
+                if ((config.api as any)?.requireAuth !== undefined) {
+                    ctx.logger.warn(
+                        '[security] `api.requireAuth` is set at the WRONG nesting level and has NO effect — ' +
+                        'move it to `api.api.requireAuth` (RestServerConfig.api.requireAuth). ' +
+                        `The effective value this boot is ${(config.api as any)?.api?.requireAuth ?? true}.`,
+                    );
+                }
             } catch (err: any) {
                 ctx.logger.error('Failed to register REST API routes', { error: err.message } as any);
                 throw err;