feat(permissions): allow opting out of implicit READ via READ: false (#469)

Every `PermissionsBlock` previously emitted an implicit READ chain — the
short-circuit `action === 'READ' || action in block` in both
`generatePermissions` and `addPermissions` always pushed READ regardless
of whether the block declared one. That made it impossible to declare a
mutation-only sub-block (e.g. `user: { UPDATE: true }`) without also
contributing a READ chain to the OR'd EXISTS subtree on the linked type.

This adds an explicit opt-out: set `READ: false` on any block to suppress
the implicit READ-chain emission while keeping the other action grants
intact. Default behavior is unchanged (omit READ ⇒ READ emitted as
before; `READ: true` ⇒ same).

- `PermissionsBlock` type widens `READ?: boolean` (other actions stay
  `true`-only).
- Generated per-model `${Model}Permissions` type widens `READ?: boolean`
  to match.
- Both READ short-circuits switch to `block.READ !== false`.

Unblocks consumer-side cleanup of redundant implicit READ chains where
the same path is already covered by a flatter grant on the same role —
shrinks the OR'd EXISTS subtree on heavily-joined types like User.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nicola-smartive

src/bin/gqm/permissions.ts

@@ -48,7 +48,7 @@ export const generatePermissionTypes = (models: Models) => {
     sourceFile.addStatements((writer) =>
       writer.write(`export type ${model.name}Permissions = `).inlineBlock(() => {
         for (const action of ACTIONS) {
-          writer.writeLine(`${action}?: true,`);
+          writer.writeLine(`${action}?: ${action === 'READ' ? 'boolean' : 'true'},`);
         }
         writer.writeLine(`WHERE?: ${model.name}Where,`);
         const relations = [...model.relations, ...model.reverseRelations];

src/permissions/generate.ts

@@ -10,7 +10,14 @@ export const ACTIONS: PermissionAction[] = ['READ', 'CREATE', 'UPDATE', 'DELETE'
  */
 export type PermissionsConfig = Record<string, true | Record<string, PermissionsBlock>>;
 
-export type PermissionsBlock = Partial<Record<PermissionAction, true>> & {
+export type PermissionsBlock = Partial<Record<Exclude<PermissionAction, 'READ'>, true>> & {
+  /**
+   * READ is implicit by default (any block emits a READ chain). Set `READ: false`
+   * on a block to opt out — useful when the same READ path is already covered by
+   * a flatter grant on the same role and the block exists only to declare
+   * mutation actions (UPDATE / DELETE / RESTORE / LINK / CREATE).
+   */
+  READ?: boolean;
   WHERE?: Record<string, any>;
   RELATIONS?: Record<string, PermissionsBlock>;
 };
@@ -53,7 +60,7 @@ export const generatePermissions = (models: Models, config: PermissionsConfig) =
       if (key !== 'me' && !('WHERE' in block)) {
         rolePermissions[type] = {};
         for (const action of ACTIONS) {
-          if (action === 'READ' || action in block) {
+          if (action === 'READ' ? block.READ !== false : action in block) {
             rolePermissions[type][action] = true;
           }
         }
@@ -82,7 +89,7 @@ const addPermissions = (models: Models, permissions: RolePermissions, links: Per
   const model = models.getModel(type, 'entity');
 
   for (const action of ACTIONS) {
-    if (action === 'READ' || action in block) {
+    if (action === 'READ' ? block.READ !== false : action in block) {
       if (!permissions[type]) {
         permissions[type] = {};
       }

tests/unit/generate-permissions.spec.ts

@@ -0,0 +1,116 @@
+import { type ModelDefinitions, Models } from '../../src/models';
+import { generatePermissions, type PermissionsConfig, type Permissions } from '../../src/permissions/generate';
+
+const modelDefinitions: ModelDefinitions = [
+  { name: 'Role', kind: 'enum', values: ['ADMIN', 'EXPERT'] },
+  {
+    kind: 'entity',
+    name: 'User',
+    fields: [{ name: 'role', kind: 'enum', type: 'Role', nonNull: true }],
+  },
+  {
+    kind: 'entity',
+    name: 'Expert',
+    fields: [
+      { name: 'user', kind: 'relation', type: 'User', toOne: true, reverse: 'experts' },
+    ],
+  },
+];
+
+const models = new Models(modelDefinitions);
+
+const getRole = (permissions: Permissions, role: string) => {
+  const rolePermissions = permissions[role];
+  if (rolePermissions === true || rolePermissions === undefined) {
+    throw new Error(`expected per-type permissions for role ${role}`);
+  }
+  return rolePermissions;
+};
+
+describe('generatePermissions — implicit READ', () => {
+  it('emits an implicit READ chain on a relation sub-block by default', () => {
+    const config: PermissionsConfig = {
+      WOP_ADMIN: {
+        Expert: { RELATIONS: { user: { UPDATE: true } } },
+      },
+    };
+
+    const role = getRole(generatePermissions(models, config), 'WOP_ADMIN');
+
+    expect(role.User?.READ).toEqual([
+      [
+        { type: 'Expert' },
+        { type: 'User', foreignKey: 'userId', reverse: true },
+      ],
+    ]);
+    expect(role.User?.UPDATE).toEqual([
+      [
+        { type: 'Expert' },
+        { type: 'User', foreignKey: 'userId', reverse: true },
+      ],
+    ]);
+  });
+
+  it('skips the implicit READ chain when READ: false is set on a sub-block', () => {
+    const config: PermissionsConfig = {
+      WOP_ADMIN: {
+        Expert: { RELATIONS: { user: { READ: false, UPDATE: true } } },
+      },
+    };
+
+    const role = getRole(generatePermissions(models, config), 'WOP_ADMIN');
+
+    expect(role.User?.READ).toBeUndefined();
+    expect(role.User?.UPDATE).toEqual([
+      [
+        { type: 'Expert' },
+        { type: 'User', foreignKey: 'userId', reverse: true },
+      ],
+    ]);
+  });
+
+  it('skips the unconditional READ grant when READ: false is set on a top-level block', () => {
+    const config: PermissionsConfig = {
+      WOP_ADMIN: {
+        User: { READ: false, UPDATE: true },
+      },
+    };
+
+    const role = getRole(generatePermissions(models, config), 'WOP_ADMIN');
+
+    expect(role.User?.READ).toBeUndefined();
+    expect(role.User?.UPDATE).toBe(true);
+  });
+
+  it('treats READ: true as equivalent to omitting READ', () => {
+    const withExplicit = generatePermissions(models, {
+      WOP_ADMIN: { Expert: { RELATIONS: { user: { READ: true, UPDATE: true } } } },
+    });
+    const withImplicit = generatePermissions(models, {
+      WOP_ADMIN: { Expert: { RELATIONS: { user: { UPDATE: true } } } },
+    });
+
+    expect(withExplicit).toEqual(withImplicit);
+  });
+
+  it('READ: false on one sub-block does not suppress sibling READ chains on the same type', () => {
+    const config: PermissionsConfig = {
+      WOP_ADMIN: {
+        User: { WHERE: { role: 'EXPERT' } },
+        Expert: { RELATIONS: { user: { READ: false, UPDATE: true } } },
+      },
+    };
+
+    const role = getRole(generatePermissions(models, config), 'WOP_ADMIN');
+
+    expect(role.User?.READ).toEqual([
+      [{ type: 'User', where: { role: 'EXPERT' } }],
+    ]);
+    expect(role.User?.UPDATE).toEqual([
+      [
+        { type: 'Expert' },
+        { type: 'User', foreignKey: 'userId', reverse: true },
+      ],
+    ]);
+  });
+});