@opensaas/stack-core 0.38.0 → 0.39.0

package/tests/context.test.ts

@@ -2,7 +2,10 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { getContext } from '../src/context/index.js'
 import { defineFragment } from '../src/query/index.js'
 import { virtual } from '../src/fields/index.js'
-import { AccessScopeDepthExceededError } from '../src/access/index.js'
+import {
+  AccessScopeDepthExceededError,
+  InvalidFieldAccessResultError,
+} from '../src/access/index.js'
 import { READ_INCLUDE_MAX_DEPTH } from '../src/access/depth-limits.js'
 import type { OpenSaasConfig } from '../src/config/types.js'
 
@@ -1255,6 +1258,702 @@ describe('getContext', () => {
       })
     })
 
+    describe('read-path key validation (#912)', () => {
+      it('throws on an undeclared `where` key on findMany, naming the list and the key', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(context.db.post.findMany({ where: { bogusKey: 'x' } })).rejects.toThrow(/Post/)
+        await expect(context.db.post.findMany({ where: { bogusKey: 'x' } })).rejects.toThrow(
+          /bogusKey/,
+        )
+        expect(mockPrisma.post.findMany).not.toHaveBeenCalled()
+      })
+
+      it('throws on an undeclared `where` key on count', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(context.db.user.count({ where: { bogusKey: 'x' } })).rejects.toThrow(
+          /bogusKey/,
+        )
+        expect(mockPrisma.user.count).not.toHaveBeenCalled()
+      })
+
+      it('throws on an undeclared `orderBy` key on findMany', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(context.db.post.findMany({ orderBy: { bogusKey: 'asc' } })).rejects.toThrow(
+          /bogusKey/,
+        )
+        expect(mockPrisma.post.findMany).not.toHaveBeenCalled()
+      })
+
+      it('throws on an undeclared key nested inside a logical operator (AND/OR/NOT)', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(
+          context.db.post.findMany({
+            where: { OR: [{ title: { contains: 'a' } }, { bogusKey: 'x' }] },
+          }),
+        ).rejects.toThrow(/bogusKey/)
+
+        await expect(
+          context.db.post.findMany({
+            where: { AND: [{ NOT: { bogusKey: 'x' } }] },
+          }),
+        ).rejects.toThrow(/bogusKey/)
+      })
+
+      it('throws on an undeclared key nested inside a relation filter, naming the RELATED list', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(
+          context.db.post.findMany({ where: { author: { is: { bogusKey: 'x' } } } }),
+        ).rejects.toThrow(/User/)
+        await expect(
+          context.db.post.findMany({ where: { author: { is: { bogusKey: 'x' } } } }),
+        ).rejects.toThrow(/bogusKey/)
+      })
+
+      it("throws on an undeclared key reached via Prisma's direct-nesting to-one filter (no `is` wrapper)", async () => {
+        // Prisma's documented default for filtering a to-one relation nests the
+        // related list's fields directly, with no `is`/`isNot` wrapper at all —
+        // e.g. `{ author: { email: { contains: '...' } } }`. An undeclared key
+        // reached this way (one hop through a to-one relation, rather than at
+        // the root) must be rejected exactly like the wrapped `is` form.
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(
+          context.db.post.findMany({ where: { author: { bogusKey: 'x' } } }),
+        ).rejects.toThrow(/User/)
+        await expect(
+          context.db.post.findMany({ where: { author: { bogusKey: 'x' } } }),
+        ).rejects.toThrow(/bogusKey/)
+        expect(mockPrisma.post.findMany).not.toHaveBeenCalled()
+      })
+
+      it('accepts a declared field on the direct-nesting to-one filter form', async () => {
+        mockPrisma.post.findMany.mockResolvedValue([])
+
+        const context = await getContext(config, mockPrisma, null)
+        const where = { author: { name: { equals: 'John' } } }
+        await context.db.post.findMany({ where })
+
+        expect(mockPrisma.post.findMany).toHaveBeenCalledWith(expect.objectContaining({ where }))
+      })
+
+      it('rejects a Prisma-generated back-relation the list config never declares (the regression that matters most)', async () => {
+        // Organisation declares no relationship back to Document — mirrors a
+        // list whose Prisma model gets a `from_Document_organisation`
+        // back-relation purely because Document holds an FK pointing at it.
+        const backRelationPrisma = {
+          organisation: { findMany: vi.fn(), count: vi.fn() },
+        }
+        const backRelationConfig: OpenSaasConfig = {
+          db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+          lists: {
+            Organisation: {
+              fields: { name: { type: 'text' } },
+              access: { operation: { query: () => true } },
+            },
+          },
+        }
+
+        const context = await getContext(backRelationConfig, backRelationPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { from_Document_organisation: { some: {} } },
+          }),
+        ).rejects.toThrow(/from_Document_organisation/)
+        await expect(
+          context.db.organisation.count({
+            where: { from_Document_organisation: { some: {} } },
+          }),
+        ).rejects.toThrow(/from_Document_organisation/)
+
+        expect(backRelationPrisma.organisation.findMany).not.toHaveBeenCalled()
+        expect(backRelationPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it('never mistakes a Prisma filter operator (equals/contains/startsWith/in/is/isNot) for a field name', async () => {
+        mockPrisma.post.findMany.mockResolvedValue([
+          { id: '1', title: 'Test Post', content: 'x', authorId: 'u1' },
+        ])
+
+        const context = await getContext(config, mockPrisma, null)
+        const where = {
+          title: { equals: 'Test Post', contains: 'Test', startsWith: 'T', in: ['Test Post'] },
+          author: { is: { name: 'John' }, isNot: null },
+        }
+
+        await context.db.post.findMany({ where })
+
+        expect(mockPrisma.post.findMany).toHaveBeenCalledWith(expect.objectContaining({ where }))
+      })
+
+      it('passes all of the above through under sudo (the single trusted bypass)', async () => {
+        mockPrisma.post.findMany.mockResolvedValue([])
+
+        const context = (await getContext(config, mockPrisma, null)).sudo()
+        await context.db.post.findMany({
+          where: { bogusKey: 'x', OR: [{ alsoBogus: 'y' }] },
+          orderBy: { alsoOrderByBogus: 'asc' },
+        })
+
+        expect(mockPrisma.post.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({
+            where: { bogusKey: 'x', OR: [{ alsoBogus: 'y' }] },
+            orderBy: { alsoOrderByBogus: 'asc' },
+          }),
+        )
+      })
+
+      it('keeps an implied foreign-key scalar filterable (authorId for author: relationship(...))', async () => {
+        mockPrisma.post.findMany.mockResolvedValue([])
+
+        const context = await getContext(config, mockPrisma, null)
+        await context.db.post.findMany({ where: { authorId: 'user-1' } })
+
+        expect(mockPrisma.post.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({ where: { authorId: 'user-1' } }),
+        )
+      })
+
+      it('findFirst inherits the check through findMany, with no second copy', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(context.db.post.findFirst({ where: { bogusKey: 'x' } })).rejects.toThrow(
+          /bogusKey/,
+        )
+        expect(mockPrisma.post.findMany).not.toHaveBeenCalled()
+      })
+
+      it('updateMany inherits the check through findMany, with no second copy', async () => {
+        const context = await getContext(config, mockPrisma, null)
+
+        await expect(
+          context.db.user.updateMany({ where: { bogusKey: 'x' }, data: { name: 'y' } }),
+        ).rejects.toThrow(/bogusKey/)
+        expect(mockPrisma.user.findMany).not.toHaveBeenCalled()
+        expect(mockPrisma.user.update).not.toHaveBeenCalled()
+      })
+
+      it('an ordinary read using only declared keys is unaffected', async () => {
+        const mockUsers = [{ id: '1', name: 'John', email: 'john@example.com' }]
+        mockPrisma.user.findMany.mockResolvedValue(mockUsers)
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.db.user.findMany({
+          where: { name: 'John' },
+          orderBy: { name: 'asc' },
+        })
+
+        expect(result).toEqual(mockUsers)
+      })
+    })
+
+    describe('predicate-time field-read access (#915)', () => {
+      // The exact shape from the issue: a public `query` gate with one
+      // field-level `read` gate. Without this fix, `billingAddress`'s withheld
+      // value can be recovered one character at a time via `count()`, and its
+      // relative order leaked via `orderBy`, despite no session ever being
+      // allowed to READ it.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let orgPrisma: any
+      let orgConfig: OpenSaasConfig
+
+      beforeEach(() => {
+        orgPrisma = {
+          organisation: { findMany: vi.fn(), count: vi.fn() },
+        }
+        orgConfig = {
+          db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+          lists: {
+            Organisation: {
+              fields: {
+                name: { type: 'text' },
+                billingAddress: {
+                  type: 'text',
+                  access: { read: () => false },
+                },
+              },
+              access: { operation: { query: () => true } },
+            },
+          },
+        }
+      })
+
+      it('denies a `where` filter naming a read-denied field, on both findMany and count', async () => {
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { billingAddress: { startsWith: '12 ' } },
+          }),
+        ).rejects.toThrow(/billingAddress/)
+        await expect(
+          context.db.organisation.count({
+            where: { billingAddress: { startsWith: '12 ' } },
+          }),
+        ).rejects.toThrow(/billingAddress/)
+
+        expect(orgPrisma.organisation.findMany).not.toHaveBeenCalled()
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it('a count probe answers identically for a matching and a non-matching prefix (no oracle)', async () => {
+        // Before the fix, these two counts would differ (1 vs 0), letting the
+        // withheld value be recovered one character at a time. After the fix,
+        // both throw the SAME denial — there is no distinguishing signal left.
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        const matching = context.db.organisation
+          .count({ where: { billingAddress: { startsWith: '12 ' } } })
+          .catch((err: Error) => err.message)
+        const nonMatching = context.db.organisation
+          .count({ where: { billingAddress: { startsWith: '99 ' } } })
+          .catch((err: Error) => err.message)
+
+        expect(await matching).toEqual(await nonMatching)
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it('denies ordering by a read-denied field', async () => {
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({ orderBy: { billingAddress: 'asc' } }),
+        ).rejects.toThrow(/billingAddress/)
+        expect(orgPrisma.organisation.findMany).not.toHaveBeenCalled()
+      })
+
+      it('checks keys nested inside logical operators (AND/OR/NOT)', async () => {
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { OR: [{ name: { contains: 'a' } }, { billingAddress: { contains: 'x' } }] },
+          }),
+        ).rejects.toThrow(/billingAddress/)
+        await expect(
+          context.db.organisation.findMany({
+            where: { AND: [{ NOT: { billingAddress: { contains: 'x' } } }] },
+          }),
+        ).rejects.toThrow(/billingAddress/)
+      })
+
+      it('a row-dependent read rule resolves to a denial, not a skipped check', async () => {
+        // `item` cannot be evaluated before the query runs — there is no row
+        // yet — so a rule that depends on it (the shape `FieldAccess['read']`
+        // documents as the norm) must deny here even though, post-query, the
+        // very same rule might have allowed this session to read the field.
+        const rowDependentConfig: OpenSaasConfig = {
+          ...orgConfig,
+          lists: {
+            Organisation: {
+              ...orgConfig.lists.Organisation,
+              fields: {
+                ...orgConfig.lists.Organisation.fields,
+                billingAddress: {
+                  type: 'text',
+                  access: {
+                    read: ({ item, session }: { item: { ownerId: string }; session: unknown }) =>
+                      item.ownerId === (session as { userId?: string } | null)?.userId,
+                  },
+                },
+              },
+            },
+          },
+        }
+
+        const context = await getContext(rowDependentConfig, orgPrisma, { userId: 'user-1' })
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { billingAddress: { contains: 'x' } },
+          }),
+        ).rejects.toThrow(/billingAddress/)
+        expect(orgPrisma.organisation.findMany).not.toHaveBeenCalled()
+      })
+
+      it('propagates InvalidFieldAccessResultError (#913), never folding it into a plain denial', async () => {
+        const filterReturningConfig: OpenSaasConfig = {
+          ...orgConfig,
+          lists: {
+            Organisation: {
+              ...orgConfig.lists.Organisation,
+              fields: {
+                ...orgConfig.lists.Organisation.fields,
+                billingAddress: {
+                  type: 'text',
+                  // Bypasses the FieldAccessControl boolean-only type on purpose —
+                  // this is the exact misconfiguration #913 closed.
+                  access: { read: (() => ({ ownerId: 'x' })) as unknown as () => boolean },
+                },
+              },
+            },
+          },
+        }
+
+        const context = await getContext(filterReturningConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { billingAddress: { contains: 'x' } },
+          }),
+        ).rejects.toThrow(InvalidFieldAccessResultError)
+      })
+
+      it('leaves a readable field filterable and sortable (no regression)', async () => {
+        orgPrisma.organisation.findMany.mockResolvedValue([])
+
+        const context = await getContext(orgConfig, orgPrisma, null)
+        await context.db.organisation.findMany({
+          where: { name: { contains: 'Acme' } },
+          orderBy: { name: 'asc' },
+        })
+
+        expect(orgPrisma.organisation.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({
+            where: { name: { contains: 'Acme' } },
+            orderBy: { name: 'asc' },
+          }),
+        )
+      })
+
+      it('sudo bypasses the check entirely, matching #912', async () => {
+        orgPrisma.organisation.findMany.mockResolvedValue([])
+        orgPrisma.organisation.count.mockResolvedValue(3)
+
+        const context = (await getContext(orgConfig, orgPrisma, null)).sudo()
+        await context.db.organisation.findMany({
+          where: { billingAddress: { startsWith: '12 ' } },
+          orderBy: { billingAddress: 'asc' },
+        })
+        await context.db.organisation.count({
+          where: { billingAddress: { startsWith: '12 ' } },
+        })
+
+        expect(orgPrisma.organisation.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({
+            where: { billingAddress: { startsWith: '12 ' } },
+            orderBy: { billingAddress: 'asc' },
+          }),
+        )
+        expect(orgPrisma.organisation.count).toHaveBeenCalledWith(
+          expect.objectContaining({ where: { billingAddress: { startsWith: '12 ' } } }),
+        )
+      })
+
+      it('a caller with zero list access gets the ordinary silent denial, not a validation error naming the field (found in review of #925)', async () => {
+        // Operation-level `query` access is fully denied for this session.
+        // The #912/#915 where/orderBy validation must never run in that case
+        // — the thrown ValidationError names the offending key, which would
+        // let a caller with NO access to the list at all learn a field's
+        // name and its read-gating status purely from the error message.
+        // That is itself the kind of oracle #915 exists to close, just
+        // pointed at "does this field exist and is it read-gated" instead of
+        // "what is this field's value" — so a fully denied caller must see
+        // the SAME silent []/0 whether or not the where/orderBy names an
+        // undeclared or read-denied key.
+        const deniedConfig: OpenSaasConfig = {
+          ...orgConfig,
+          lists: {
+            Organisation: {
+              ...orgConfig.lists.Organisation,
+              access: { operation: { query: () => false } },
+            },
+          },
+        }
+        const context = await getContext(deniedConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { billingAddress: { startsWith: '12 ' } },
+          }),
+        ).resolves.toEqual([])
+        await expect(
+          context.db.organisation.findMany({ where: { bogusKey: 'x' } }),
+        ).resolves.toEqual([])
+        await expect(
+          context.db.organisation.count({
+            where: { billingAddress: { startsWith: '12 ' } },
+          }),
+        ).resolves.toBe(0)
+        await expect(context.db.organisation.count({ where: { bogusKey: 'x' } })).resolves.toBe(0)
+
+        expect(orgPrisma.organisation.findMany).not.toHaveBeenCalled()
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it('#915 itself does not recurse into a related list nested inside a relation filter, but #916 now does', async () => {
+        // #915 (`validateQueryFieldReadAccess`) checks whether THIS list's
+        // relationship field may be named at all — it does not by itself
+        // reject a field on the RELATED list reached through it. Once #916
+        // landed, that gap is closed by a SEPARATE pass
+        // (`buildAccessScopedWhere`) that scopes relation filters and applies
+        // the related list's own field-read access to keys nested inside
+        // them — so the read-denied `User.secret` field is still rejected
+        // overall, just not by #915's own top-level-only check.
+        const relPrisma = {
+          post: { findMany: vi.fn(), count: vi.fn() },
+        }
+        const relConfig: OpenSaasConfig = {
+          db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+          lists: {
+            User: {
+              fields: {
+                name: { type: 'text' },
+                secret: { type: 'text', access: { read: () => false } },
+              },
+              access: { operation: { query: () => true } },
+            },
+            Post: {
+              fields: {
+                title: { type: 'text' },
+                author: { type: 'relationship', ref: 'User.posts' },
+              },
+              access: { operation: { query: () => true } },
+            },
+          },
+        }
+        relPrisma.post.findMany.mockResolvedValue([])
+
+        const context = await getContext(relConfig, relPrisma, null)
+        // Names a field on the RELATED list (User.secret) nested inside the
+        // relation filter — not a key of Post itself, so #915's own check
+        // (which only inspects Post's own fields) does not deny it, but
+        // #916's relation-filter scoping (which checks the RELATED list's
+        // field-read access) now does.
+        await expect(
+          context.db.post.findMany({ where: { author: { is: { secret: { contains: 'x' } } } } }),
+        ).rejects.toThrow(/secret/)
+
+        expect(relPrisma.post.findMany).not.toHaveBeenCalled()
+      })
+    })
+
+    describe('relation filter access scoping (#916)', () => {
+      // The exact shape from the issue: a publicly-queryable Organisation,
+      // reachable Document/Membership/User lists each gated differently, and
+      // a two-hop chain (Organisation -> members -> user -> email) that lets
+      // an anonymous caller binary-search a field it could never read
+      // directly, unless the relation filter itself is scoped.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let orgPrisma: any
+      let orgConfig: OpenSaasConfig
+
+      beforeEach(() => {
+        orgPrisma = {
+          organisation: { findMany: vi.fn(), count: vi.fn() },
+        }
+        orgConfig = {
+          db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+          lists: {
+            Organisation: {
+              fields: {
+                name: { type: 'text' },
+                documents: { type: 'relationship', ref: 'Document.organisation', many: true },
+                members: { type: 'relationship', ref: 'Membership.organisation', many: true },
+              },
+              access: { operation: { query: () => true } },
+            },
+            // Membership-scoped: `query` denies everything for an anonymous
+            // session (no session means no membership filter can match).
+            Document: {
+              fields: {
+                organisation: { type: 'relationship', ref: 'Organisation.documents' },
+                billingAddress: { type: 'text' },
+              },
+              access: { operation: { query: () => false } },
+            },
+            Membership: {
+              fields: {
+                organisation: { type: 'relationship', ref: 'Organisation.members' },
+                user: { type: 'relationship', ref: 'User.memberships' },
+              },
+              // Readable by anyone — the hop itself isn't the leak, the
+              // identity list at the end of the chain is.
+              access: { operation: { query: () => true } },
+            },
+            User: {
+              fields: {
+                memberships: { type: 'relationship', ref: 'Membership.user', many: true },
+                email: { type: 'text' },
+              },
+              // Not queryable at all by an anonymous session.
+              access: { operation: { query: () => false } },
+            },
+          },
+        }
+      })
+
+      it('denies a single-hop relation filter through a fully denied related list, on both findMany and count', async () => {
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { documents: { some: { billingAddress: { startsWith: '12 ' } } } },
+          }),
+        ).rejects.toThrow(/Document/)
+        await expect(
+          context.db.organisation.count({
+            where: { documents: { some: { billingAddress: { startsWith: '12 ' } } } },
+          }),
+        ).rejects.toThrow(/Document/)
+
+        expect(orgPrisma.organisation.findMany).not.toHaveBeenCalled()
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it('a count probe through a denied relation answers identically for a matching and non-matching value (no oracle)', async () => {
+        // Before the fix these counts could differ (1 vs 0), letting a caller
+        // recover `billingAddress` one character at a time. After the fix
+        // both throw the SAME denial.
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        const matching = context.db.organisation
+          .count({ where: { documents: { some: { billingAddress: { startsWith: '12 ' } } } } })
+          .catch((err: Error) => err.message)
+        const nonMatching = context.db.organisation
+          .count({ where: { documents: { some: { billingAddress: { startsWith: '99 ' } } } } })
+          .catch((err: Error) => err.message)
+
+        expect(await matching).toEqual(await nonMatching)
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it('denies a two-hop chain reaching a denied identity list, the exact probe from the issue', async () => {
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.count({
+            where: {
+              members: { some: { user: { is: { email: { equals: 'ada@example.com' } } } } },
+            },
+          }),
+        ).rejects.toThrow(/User/)
+
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it('a two-hop count probe answers identically for a real and a fabricated email (no identity-confirmation oracle)', async () => {
+        const context = await getContext(orgConfig, orgPrisma, null)
+
+        const real = context.db.organisation
+          .count({
+            where: {
+              members: { some: { user: { is: { email: { equals: 'real@example.com' } } } } },
+            },
+          })
+          .catch((err: Error) => err.message)
+        const fabricated = context.db.organisation
+          .count({
+            where: {
+              members: { some: { user: { is: { email: { equals: 'nobody@example.com' } } } } },
+            },
+          })
+          .catch((err: Error) => err.message)
+
+        expect(await real).toEqual(await fabricated)
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+
+      it("folds the related list's access filter into a relation filter rather than denying or passing it through unscoped", async () => {
+        orgPrisma.organisation.findMany.mockResolvedValue([])
+        const scopedConfig: OpenSaasConfig = {
+          ...orgConfig,
+          lists: {
+            ...orgConfig.lists,
+            Document: {
+              ...orgConfig.lists.Document,
+              // A filter, not a boolean: only this org's own published docs.
+              access: { operation: { query: () => ({ published: { equals: true } }) } },
+            },
+          },
+        }
+
+        const context = await getContext(scopedConfig, orgPrisma, null)
+        await context.db.organisation.findMany({
+          where: { documents: { some: { billingAddress: { startsWith: '12 ' } } } },
+        })
+
+        expect(orgPrisma.organisation.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({
+            where: {
+              documents: {
+                some: {
+                  AND: [{ published: { equals: true } }, { billingAddress: { startsWith: '12 ' } }],
+                },
+              },
+            },
+          }),
+        )
+      })
+
+      it('leaves a relation filter through a fully readable related list unwrapped (no perturbation)', async () => {
+        orgPrisma.organisation.findMany.mockResolvedValue([])
+        const openConfig: OpenSaasConfig = {
+          ...orgConfig,
+          lists: {
+            ...orgConfig.lists,
+            Membership: {
+              ...orgConfig.lists.Membership,
+              access: { operation: { query: () => true } },
+            },
+          },
+        }
+        const context = await getContext(openConfig, orgPrisma, null)
+        const where = { members: { some: { organisation: { is: { name: { equals: 'Acme' } } } } } }
+
+        await context.db.organisation.findMany({ where })
+
+        expect(orgPrisma.organisation.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({ where }),
+        )
+      })
+
+      it('sudo bypasses relation-filter scoping entirely (#916 unaffected)', async () => {
+        orgPrisma.organisation.findMany.mockResolvedValue([])
+
+        const context = (await getContext(orgConfig, orgPrisma, null)).sudo()
+        const where = { documents: { some: { billingAddress: { startsWith: '12 ' } } } }
+        await context.db.organisation.findMany({ where })
+
+        expect(orgPrisma.organisation.findMany).toHaveBeenCalledWith(
+          expect.objectContaining({ where }),
+        )
+      })
+
+      it('a caller with zero list access gets the ordinary silent denial, never the relation-filter error', async () => {
+        const deniedConfig: OpenSaasConfig = {
+          ...orgConfig,
+          lists: {
+            ...orgConfig.lists,
+            Organisation: {
+              ...orgConfig.lists.Organisation,
+              access: { operation: { query: () => false } },
+            },
+          },
+        }
+        const context = await getContext(deniedConfig, orgPrisma, null)
+
+        await expect(
+          context.db.organisation.findMany({
+            where: { documents: { some: { billingAddress: { startsWith: '12 ' } } } },
+          }),
+        ).resolves.toEqual([])
+        await expect(
+          context.db.organisation.count({
+            where: { documents: { some: { billingAddress: { startsWith: '12 ' } } } },
+          }),
+        ).resolves.toBe(0)
+
+        expect(orgPrisma.organisation.findMany).not.toHaveBeenCalled()
+        expect(orgPrisma.organisation.count).not.toHaveBeenCalled()
+      })
+    })
+
     describe('explicit include merges with access control (#566)', () => {
       // Author has many Posts; Post.query access scopes to published posts only.
       // A caller-supplied `include` must NOT bypass that per-relation filter.