@opensaas/stack-core 0.37.0 → 0.39.0

package/src/access/access-filter.ts

@@ -1,8 +1,14 @@
 import type { Session, AccessContext, PrismaFilter } from './types.js'
-import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+import type { OpenSaasConfig, FieldConfig, ListConfig } from '../config/types.js'
 import { checkAccess, getRelatedListConfig } from './engine.js'
 import { READ_INCLUDE_MAX_DEPTH } from './depth-limits.js'
-import { AccessScopeDepthExceededError } from './errors.js'
+import { AccessScopeDepthExceededError, RelationFilterAccessDeniedError } from './errors.js'
+import {
+  LOGICAL_OPERATORS,
+  RELATION_QUANTIFIERS,
+  resolveQueryField,
+  walkWhereReadAccess,
+} from './query-validation.js'
 
 /**
  * Access Filter — phase 1 of the two-phase read (pre-query).
@@ -18,199 +24,44 @@ import { AccessScopeDepthExceededError } from './errors.js'
  * the fetched row, neither of which is expressible in SQL. See
  * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
  * glossary in `CONTEXT.md`.
- */
-
-/** A single relation entry in a Prisma `include` object (see below). */
-type IncludeEntry = boolean | { where?: PrismaFilter; include?: IncludeObject; take?: number }
-type IncludeObject = Record<string, IncludeEntry>
-
-/**
- * The result of trying to compute an access-controlled include for a list's
- * fields. `buildIncludeWithAccessControl` used to collapse three unrelated
- * outcomes into a single overloaded `undefined`: "inside a resolveOutput
- * context", "hit the depth cap", and "no relationships to scope" all looked
- * identical to callers, which is what let a depth-capped relation pass
- * through unscoped (issue #830). This discriminated result keeps them
- * distinguishable all the way to `mergeIncludeWithAccessControl`, which is the
- * only place that knows whether a caller actually asked for the part that
- * couldn't be scoped.
- *
- * - `scoped`: relationships were found and (to the extent depth allows)
- *   access-controlled; `include` is the resulting tree.
- * - `nothing-to-scope`: the list genuinely has no relationships to scope, OR
- *   we are inside a resolveOutput/virtual-field context and deliberately did
- *   not descend into a relation's own nested relations. Passing the caller's
- *   include through unchanged here is correct, not a leak.
- * - `depth-exceeded`: we could not evaluate this level at all because it sits
- *   at or past `READ_INCLUDE_MAX_DEPTH`. This is a denial: a caller `include`
- *   that reaches here must be rejected, not passed through.
- */
-export type AccessIncludeResult =
-  | { kind: 'scoped'; include: RichIncludeObject }
-  | { kind: 'nothing-to-scope' }
-  | { kind: 'depth-exceeded' }
-
-/** A relation entry in the rich, provenance-carrying tree `buildIncludeWithAccessControl` builds internally. */
-type RichIncludeEntry = { where?: PrismaFilter; nested: AccessIncludeResult }
-type RichIncludeObject = Record<string, RichIncludeEntry>
-
-/**
- * Collapse a rich, provenance-carrying include entry down to the plain
- * Prisma-shaped form. A `nested` result that is `depth-exceeded` or
- * `nothing-to-scope` contributes no `include` key — this is the AUTO-include
- * silently stopping, which is correct when no caller asked for anything past
- * this point (see `AccessIncludeResult` doc comment).
- */
-function toPrismaEntry(entry: RichIncludeEntry): IncludeEntry {
-  const result: { where?: PrismaFilter; include?: IncludeObject } = {}
-  if (entry.where) result.where = entry.where
-  if (entry.nested.kind === 'scoped') {
-    const nestedInclude = toPrismaInclude(entry.nested)
-    if (nestedInclude && Object.keys(nestedInclude).length > 0) {
-      result.include = nestedInclude
-    }
-  }
-  return Object.keys(result).length > 0 ? result : true
-}
-
-/**
- * Collapse an `AccessIncludeResult` to the plain Prisma `include` shape used
- * when there is no caller-supplied include to merge against (the direct
- * auto-include path). `nothing-to-scope` and `depth-exceeded` both become
- * `undefined` here — at this call site nothing was explicitly requested past
- * either boundary, so there is nothing to deny.
- */
-export function toPrismaInclude(result: AccessIncludeResult): IncludeObject | undefined {
-  if (result.kind !== 'scoped') return undefined
-  const out: IncludeObject = {}
-  for (const [key, entry] of Object.entries(result.include)) {
-    out[key] = toPrismaEntry(entry)
-  }
-  return out
-}
-
-/**
- * Build the access-controlled include for a list's fields.
  *
- * This allows us to filter relationships at the database level instead of in
- * memory. Returns an {@link AccessIncludeResult} rather than a plain include
- * object so that `mergeIncludeWithAccessControl` can tell a genuine "nothing
- * to scope" apart from "the engine hit its depth cap" (see that type's doc
- * comment and ADR-0022).
+ * **Caller-directed (ADR-0026).** `buildAccessScopedInclude` walks only the
+ * branches `requestedInclude` names — the caller's own `include`, a fragment
+ * `query`'s projection, or `foldDeclaredDependencies`'s fold of a field's
+ * `needs` (`declared-dependencies.ts`), all resolved before this module ever
+ * runs. Naming a relation fetches that relation's own columns and stops
+ * (the "One hop" rule, see `CONTEXT.md`); reaching further means the request
+ * named a nested `include` there too. A relation nobody named never has its
+ * list's `query` access evaluated at all — there is no separate "build the
+ * whole tree, then reconcile against what was asked for" pass to walk it.
  */
-export async function buildIncludeWithAccessControl(
-  fieldConfigs: Record<string, FieldConfig>,
-  args: {
-    session: Session | null
-    context: AccessContext
-  },
-  config: OpenSaasConfig,
-  depth: number = 0,
-  // List names already on the path from the root to here. Used to detect
-  // relationship cycles (A → B → … → A) and stop the auto-include from
-  // re-descending them. Seed it with the root list name at the call site.
-  visitedLists: readonly string[] = [],
-): Promise<AccessIncludeResult> {
-  if (depth >= READ_INCLUDE_MAX_DEPTH) {
-    return { kind: 'depth-exceeded' }
-  }
-
-  // Inside a resolveOutput/virtual-field context we still scope each immediate
-  // relation (its own access `where`), but do not auto-expand INTO its nested
-  // relations — this keeps a single hook-issued read's include from growing
-  // depth-first. Correction (ADR-0023): this does NOT by itself terminate a
-  // cycle, despite what an earlier version of this comment claimed. A
-  // self-referential relation read from inside a hook is a NEW top-level
-  // read, invisible to this function's own recursion — the loop runs through
-  // the hook↔read boundary, not through repeated calls to
-  // `buildIncludeWithAccessControl`. Loop termination is the resolve chain's
-  // job: `field-visibility.ts`'s `resolveReadableFieldValue` refuses to
-  // re-enter a `(list, field)` pair already on the chain. What this check
-  // still does correctly is row-scope the immediate relation rather than
-  // skipping scoping altogether (issue #830's second trigger).
-  const insideResolveOutput = args.context._resolveOutputChain.length > 0
-
-  const include: RichIncludeObject = {}
-  let hasRelationships = false
-
-  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
-    if (fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && fieldConfig.ref) {
-      hasRelationships = true
-      const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
-
-      if (relatedConfig) {
-        // Check query access for the related list
-        const queryAccess = relatedConfig.listConfig.access?.operation?.query
-        const accessResult = await checkAccess(queryAccess, {
-          session: args.session,
-          context: args.context,
-        })
-
-        // If access is completely denied, exclude this relationship
-        if (accessResult === false) {
-          continue
-        }
-
-        const where = typeof accessResult === 'object' ? accessResult : undefined
-
-        // Cycle guard: if the related list already appears on the path from the
-        // root, DO NOT auto-include its relationships again. On a cyclic
-        // readable-relationship graph (A → B → … → A) the depth-first walk would
-        // otherwise re-descend the cycle on every branch, and — combined with the
-        // bare-`true` leaf re-expansion in `mergeIncludeWithAccessControl` — build
-        // an include tree deep/large enough to overflow the call stack in
-        // downstream processing (the RSC serializer's recursive `Map.set`). This
-        // extends the SF-20 (#566) fix: a bare-`true` leaf must resolve to a
-        // genuine single-level fetch, not a re-expansion of the full auto-include.
-        // The relation itself is still included (as a FLAT fetch of its own
-        // columns); only its onward relationships are pruned at the back-edge.
-        let nested: AccessIncludeResult = { kind: 'nothing-to-scope' }
-        const relatedListName = relatedConfig.listName
-        if (!insideResolveOutput && !visitedLists.includes(relatedListName)) {
-          nested = await buildIncludeWithAccessControl(
-            relatedConfig.listConfig.fields,
-            args,
-            config,
-            depth + 1,
-            [...visitedLists, relatedListName],
-          )
-        }
 
-        include[fieldName] = { where, nested }
-      }
-    }
-  }
+/** The structured (object) form of a relation include entry — caller/fold-supplied or produced by this module. */
+type IncludeEntryObject = { where?: PrismaFilter; include?: Record<string, unknown>; take?: number }
 
-  return hasRelationships ? { kind: 'scoped', include } : { kind: 'nothing-to-scope' }
+/** A plain object — excludes `null` and arrays, which `typeof x === 'object'` alone would admit. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-/** The structured (object) form of a relation include entry. */
-type IncludeEntryObject = { where?: PrismaFilter; include?: IncludeObject; take?: number }
-
 /**
  * Narrow an unknown include value to the structured object form (vs bare `true`
  * or any other primitive). Caller-supplied includes arrive untyped at the
- * runtime boundary, so we validate the shape here rather than casting.
+ * runtime boundary: narrow to a plain object first, then validate each field's
+ * own type before trusting it, rather than casting the whole value wholesale.
  *
  * A numeric `take` on a to-many relation include (a caller-supplied row bound,
  * issue #752) is carried through: it only ever NARROWS the fetched rows and can
- * never widen past the access `where`, so preserving it is access-neutral. The
- * access-controlled include never sets `take` itself — it originates solely
- * from the caller — so `mergeIncludeWithAccessControl` re-attaches it below.
+ * never widen past the access `where`, so preserving it is access-neutral.
  */
 function asEntryObject(value: unknown): IncludeEntryObject | null {
-  if (value && typeof value === 'object') {
-    const obj = value as Record<string, unknown>
-    const where = obj.where
-    const include = obj.include
-    const take = obj.take
-    const entry: IncludeEntryObject = {}
-    if (where && typeof where === 'object') entry.where = where as PrismaFilter
-    if (include && typeof include === 'object') entry.include = include as IncludeObject
-    if (typeof take === 'number') entry.take = take
-    return entry
-  }
-  return null
+  if (!isPlainObject(value)) return null
+  const { where, include, take } = value
+  const entry: IncludeEntryObject = {}
+  if (isPlainObject(where)) entry.where = where
+  if (isPlainObject(include)) entry.include = include
+  if (typeof take === 'number') entry.take = take
+  return entry
 }
 
 /**
@@ -218,8 +69,7 @@ function asEntryObject(value: unknown): IncludeEntryObject | null {
  *
  * The access filter is authoritative: the caller's filter may only NARROW the
  * result further, never widen past what access permits. We therefore wrap both
- * in a Prisma `AND` so neither can override the other. If only one side is
- * present, it is returned as-is; if neither is present, the result is undefined.
+ * in a Prisma `AND` so neither can override the other.
  */
 function andWhere(
   accessWhere: PrismaFilter | undefined,
@@ -232,128 +82,243 @@ function andWhere(
 }
 
 /**
- * Merge a caller-supplied `include` with the access-controlled include — phase-1
- * row/relation scoping for explicit caller selections.
- *
- * The caller's `include` decides WHICH relations to fetch; access control decides
- * WHETHER each relation may be fetched and WITH WHAT filter. Replacing the
- * access-controlled include with the caller's wholesale (the bug in #566) drops
- * every per-relation access `where` and denied-relation exclusion, silently
- * bypassing row-level access on any non-sudo read that passes `include`.
+ * Build the access-scoped `include` for exactly the relations a read
+ * requested, recursing only into branches `requestedInclude` itself names.
  *
- * For each relation the caller asks to include:
- * - If the relation is a config-declared relationship but is ABSENT from the
- *   access-controlled include, its `query` access returned `false` → it is DROPPED
- *   (not fetched).
- * - If it is present (allowed, possibly with a filter), the access entry is used
- *   as the base: the access `where` is AND-combined with any caller-supplied
- *   nested `where`, and nested includes are recursively merged using the related
- *   list's field configs (so deeply-nested selections are filtered at every
- *   level). A bare caller `true` becomes the access-controlled shape (filter +
- *   nested filtered include), never bare `true`.
- * - If the caller names a key that is NOT a config-declared relationship, it is
- *   passed through unchanged (access control does not govern it).
+ * For each key in `requestedInclude`:
+ * - Not a config-declared relationship → access control does not govern it;
+ *   passed through unchanged (e.g. a fragment/caller key that isn't a
+ *   relationship at all).
+ * - A declared relationship whose related list's `query` access denies it
+ *   (`=== false`) → dropped entirely, no matter what the request asked for
+ *   nested beneath it (#566): the caller chooses *which* relations, access
+ *   control chooses *whether* and *with what filter*.
+ * - Otherwise → the access `where` is AND-combined with any caller-supplied
+ *   nested `where` (never replaced — the other half of #566), a
+ *   caller-supplied `take` rides through unchanged (#752), and — the "One
+ *   hop" rule (ADR-0026) — nested relations are scoped ONLY if
+ *   `requestedInclude` itself named a nested `include` here. A bare relation
+ *   (or one with no nested `include`) fetches its own columns and stops: no
+ *   recursive call, no access evaluation on anything beneath it.
  *
- * `accessControlledInclude` is the {@link AccessIncludeResult} for THIS level:
- * - `nothing-to-scope` → nothing to merge against (the list has no
- *   relationships, or we're inside a resolveOutput context where the caller
- *   include is irrelevant to begin with). Pass the caller's include through
- *   unchanged — this is a non-denial outcome, not "every relation denied".
- * - `depth-exceeded` → the engine could not compute a scope for THIS level at
- *   all because it sits at or past `READ_INCLUDE_MAX_DEPTH`. If the caller
- *   named anything here, that is exactly the case that used to pass through
- *   unscoped (issue #830): throw `AccessScopeDepthExceededError` instead. An
- *   empty caller include at this level (nothing further requested) is not an
- *   error — there's simply nothing to do.
- * - `scoped` → the normal per-relation merge below: a declared relationship
- *   ABSENT from the access include was denied (drop it); one PRESENT is used
- *   as the base, AND-combining `where`s and recursing into nested includes.
- *
- * `listKey` and `depth` are carried only to build a useful
- * `AccessScopeDepthExceededError` message; they do not affect merge behaviour.
+ * **Depth is a cost limit, not a cycle guard (ADR-0026).** A `requestedInclude`
+ * is always a finite literal — the caller's own object, or
+ * `foldDeclaredDependencies`'s already-cycle-guarded fold — so this recursion
+ * cannot loop unboundedly on its own; nothing here walks the relationship
+ * graph unprompted. `READ_INCLUDE_MAX_DEPTH` still bounds how deep a request
+ * may reach, fail-closed per ADR-0022: a request naming anything at or past
+ * the cap throws `AccessScopeDepthExceededError` rather than silently
+ * returning less than what was asked for.
  */
-export function mergeIncludeWithAccessControl(
-  callerInclude: Record<string, unknown>,
-  accessControlledInclude: AccessIncludeResult,
+export async function buildAccessScopedInclude(
+  requestedInclude: Record<string, unknown>,
   fieldConfigs: Record<string, FieldConfig>,
+  args: {
+    session: Session | null
+    context: AccessContext
+  },
   config: OpenSaasConfig,
   listKey: string,
   depth: number = 0,
-): Record<string, unknown> {
-  if (accessControlledInclude.kind === 'nothing-to-scope') {
-    return callerInclude
+): Promise<Record<string, unknown>> {
+  const requestedKeys = Object.keys(requestedInclude)
+  if (depth >= READ_INCLUDE_MAX_DEPTH && requestedKeys.length > 0) {
+    throw new AccessScopeDepthExceededError(listKey, requestedKeys[0], depth)
   }
 
-  if (accessControlledInclude.kind === 'depth-exceeded') {
-    const [firstRelationName] = Object.keys(callerInclude)
-    if (firstRelationName !== undefined) {
-      throw new AccessScopeDepthExceededError(listKey, firstRelationName, depth)
-    }
-    return {}
-  }
-
-  const merged: Record<string, unknown> = {}
-  const accessInclude = accessControlledInclude.include
+  const result: Record<string, unknown> = {}
 
-  for (const [relationName, callerValue] of Object.entries(callerInclude)) {
+  for (const [relationName, requestedValue] of Object.entries(requestedInclude)) {
     const fieldConfig = fieldConfigs[relationName]
     const isDeclaredRelationship =
       fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && !!fieldConfig.ref
 
-    // Not a config-declared relationship → access control does not govern it; pass through unchanged.
     if (!isDeclaredRelationship) {
-      merged[relationName] = callerValue
+      result[relationName] = requestedValue
       continue
     }
 
-    const accessEntry = accessInclude[relationName]
+    const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
+    if (!relatedConfig) continue
+
+    const queryAccess = relatedConfig.listConfig.access?.operation?.query
+    const accessResult = await checkAccess(queryAccess, {
+      session: args.session,
+      context: args.context,
+    })
 
-    // Declared relationship absent from the access include → query access denied → drop it.
-    if (accessEntry === undefined) {
+    if (accessResult === false) {
       continue
     }
 
-    const callerEntry = asEntryObject(callerValue)
+    const accessWhere = typeof accessResult === 'object' ? accessResult : undefined
+    const requestedEntry = asEntryObject(requestedValue)
+    const mergedWhere = andWhere(accessWhere, requestedEntry?.where)
 
-    // Resolve the related list's field configs so nested includes merge recursively.
-    const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
-    const relatedFields = relatedConfig?.listConfig.fields
-
-    const mergedWhere = andWhere(accessEntry.where, callerEntry?.where)
-
-    let mergedNested: Record<string, unknown> | undefined
-    if (callerEntry?.include && relatedFields && relatedConfig) {
-      // Recurse: scope the caller's nested selection against the nested access
-      // result. If that result is 'depth-exceeded', the recursive call itself
-      // throws — the caller named something the engine cannot scope.
-      mergedNested = mergeIncludeWithAccessControl(
-        callerEntry.include,
-        accessEntry.nested,
-        relatedFields,
+    let nestedInclude: Record<string, unknown> | undefined
+    if (requestedEntry?.include) {
+      nestedInclude = await buildAccessScopedInclude(
+        requestedEntry.include,
+        relatedConfig.listConfig.fields,
+        args,
         config,
         relatedConfig.listName,
         depth + 1,
       )
-    } else if (accessEntry.nested.kind === 'scoped') {
-      // Caller selected the relation bare (no nested include); keep the
-      // access-controlled nested include so deeper relations stay filtered.
-      mergedNested = toPrismaInclude(accessEntry.nested)
     }
-    // If the caller's entry has no nested include, a 'depth-exceeded' nested
-    // result is silent here too — nothing was asked for past this point.
 
     const entry: { where?: PrismaFilter; include?: Record<string, unknown>; take?: number } = {}
     if (mergedWhere) entry.where = mergedWhere
-    if (mergedNested && Object.keys(mergedNested).length > 0) entry.include = mergedNested
-    // Preserve a caller-supplied row bound on the relation (issue #752). It only
-    // narrows, never widens, so it rides on top of the access `where`/include.
-    if (callerEntry?.take !== undefined) entry.take = callerEntry.take
+    if (nestedInclude && Object.keys(nestedInclude).length > 0) entry.include = nestedInclude
+    if (requestedEntry?.take !== undefined) entry.take = requestedEntry.take
+
+    result[relationName] = Object.keys(entry).length > 0 ? entry : true
+  }
+
+  return result
+}
+
+/**
+ * Scope every relation filter (`some`/`every`/`none`/`is`/`isNot`) nested in a
+ * caller's `where` by the related list's own `query` access — the `where`
+ * counterpart to `buildAccessScopedInclude` above, closing #916 (the
+ * "unclosed half of ADR-0022"). `include` and `where` are fundamentally
+ * different requests (which relations come back, vs. which parent rows
+ * match), so this is a distinct function, but it shares every primitive that
+ * matters: `checkAccess`/`getRelatedListConfig` (the same access-evaluation
+ * calls `buildAccessScopedInclude` makes), `andWhere` (the same AND-fold), and
+ * `resolveQueryField`/`LOGICAL_OPERATORS`/`RELATION_QUANTIFIERS`/
+ * `walkWhereReadAccess` (the same shape-recognition and field-read check
+ * `query-validation.ts` already uses for #912/#915) — there is no second,
+ * parallel implementation of any of those decisions.
+ *
+ * For each relationship key found (at any depth — the walk recurses through
+ * `AND`/`OR`/`NOT` and through every hop of a chain):
+ * - Not a declared relationship, or the key #912 already rejected (this walk
+ *   runs strictly after that check) → passed through unchanged.
+ * - The related list's `query` access denies it (`=== false`) → THROWS
+ *   `RelationFilterAccessDeniedError`. Unlike `buildAccessScopedInclude`'s
+ *   silent drop, this is a loud failure: a `where` predicate has no neutral
+ *   "not requested" outcome the way a missing `include` key does, so a
+ *   silently-empty match would itself be a distinguishable signal (ADR-0022).
+ * - Otherwise → the access filter (if any) is AND-combined into the relation
+ *   quantifier's nested clause (never replacing the caller's own condition,
+ *   mirroring `andWhere`'s include-side contract), keys inside that nested
+ *   clause are checked against the RELATED list's field-level `read` access
+ *   (`walkWhereReadAccess`, closing #915's stated gap for this path), and the
+ *   walk recurses into the related list's own fields for a further hop.
+ *
+ * One quantifier is deliberately conservative rather than exactly precise:
+ * folding the access filter into `every`'s nested clause with a plain AND
+ * makes `every` require every related row to be BOTH access-visible AND
+ * matching, not "every access-visible row matches" (the latter needs a
+ * `NOT`/`OR` transform this does not attempt). The conservative version can
+ * only reject a query that the precise version would allow — it never
+ * widens what a caller can learn — so it is the safe direction to ship; a
+ * caller can observe that an inaccessible related row exists (an `every`
+ * that "should" pass instead fails), but never that row's field values,
+ * which is the property this ticket exists to close.
+ */
+export async function buildAccessScopedWhere(
+  where: unknown,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  listConfig: ListConfig<any>,
+  listName: string,
+  config: OpenSaasConfig,
+  args: {
+    session: Session | null
+    context: AccessContext
+  },
+): Promise<unknown> {
+  if (where === null || typeof where !== 'object') return where
 
-    // A bare-`true` relation with no access filter, nested include, or row bound stays `true`.
-    merged[relationName] = Object.keys(entry).length > 0 ? entry : true
+  if (Array.isArray(where)) {
+    return Promise.all(
+      where.map((entry) => buildAccessScopedWhere(entry, listConfig, listName, config, args)),
+    )
   }
 
-  return merged
+  const result: Record<string, unknown> = {}
+
+  for (const [key, value] of Object.entries(where as Record<string, unknown>)) {
+    if (LOGICAL_OPERATORS.has(key)) {
+      result[key] = await buildAccessScopedWhere(value, listConfig, listName, config, args)
+      continue
+    }
+
+    const resolved = resolveQueryField(key, listConfig.fields)
+    if (
+      !resolved ||
+      !resolved.isRelationship ||
+      value === null ||
+      typeof value !== 'object' ||
+      Array.isArray(value)
+    ) {
+      result[key] = value
+      continue
+    }
+
+    const related = getRelatedListConfig(resolved.fieldConfig.ref, config)
+    if (!related) {
+      result[key] = value
+      continue
+    }
+
+    const queryAccess = related.listConfig.access?.operation?.query
+    const accessResult = await checkAccess(queryAccess, {
+      session: args.session,
+      context: args.context,
+    })
+
+    if (accessResult === false) {
+      throw new RelationFilterAccessDeniedError(listName, key, related.listName)
+    }
+
+    const accessWhere = typeof accessResult === 'object' ? accessResult : undefined
+    const relationEntries = Object.entries(value as Record<string, unknown>)
+    const hasQuantifier = relationEntries.some(([k]) => RELATION_QUANTIFIERS.has(k))
+
+    if (hasQuantifier) {
+      const nestedEntry: Record<string, unknown> = {}
+      for (const [quantifier, quantifierValue] of relationEntries) {
+        if (!RELATION_QUANTIFIERS.has(quantifier)) {
+          nestedEntry[quantifier] = quantifierValue
+          continue
+        }
+        await walkWhereReadAccess(quantifierValue, related.listConfig, related.listName, args)
+        const scopedNested = await buildAccessScopedWhere(
+          quantifierValue,
+          related.listConfig,
+          related.listName,
+          config,
+          args,
+        )
+        nestedEntry[quantifier] = accessWhere
+          ? andWhere(accessWhere, scopedNested as PrismaFilter | undefined)
+          : scopedNested
+      }
+      result[key] = nestedEntry
+    } else {
+      // Prisma's direct-nesting to-one form: the whole value IS the nested
+      // WHERE clause, with no `is` wrapper. Only wrap it in `is` when there is
+      // an access filter to fold in — an unwrapped value that needs no fold
+      // (fully-allowed related list) is returned exactly as the caller wrote
+      // it, so an already-permitted query is not perturbed by this pass.
+      await walkWhereReadAccess(value, related.listConfig, related.listName, args)
+      const scopedNested = await buildAccessScopedWhere(
+        value,
+        related.listConfig,
+        related.listName,
+        config,
+        args,
+      )
+      result[key] = accessWhere
+        ? { is: andWhere(accessWhere, scopedNested as PrismaFilter | undefined) }
+        : scopedNested
+    }
+  }
+
+  return result
 }
 
 /**
@@ -384,7 +349,6 @@ export function stripVirtualFieldsFromInclude(
   for (const [key, value] of Object.entries(include)) {
     const fieldConfig = fieldConfigs[key]
 
-    // Virtual fields have no database column — drop them from the include.
     if (fieldConfig?.virtual) continue
 
     const isDeclaredRelationship =