@opensaas/stack-core 0.39.2 → 0.41.0

package/dist/access/access-filter.js

@@ -1,7 +1,9 @@
-import { checkAccess, getRelatedListConfig } from './engine.js';
+import { checkAccess, getRelatedListConfig, resolveSyntheticReverseRelation, listSyntheticReverseRelationNames, } from './engine.js';
 import { READ_INCLUDE_MAX_DEPTH } from './depth-limits.js';
-import { AccessScopeDepthExceededError, RelationFilterAccessDeniedError } from './errors.js';
-import { LOGICAL_OPERATORS, RELATION_QUANTIFIERS, resolveQueryField, walkWhereReadAccess, } from './query-validation.js';
+import { AccessScopeDepthExceededError, RelationFilterAccessDeniedError, UndeclaredCountKeyError, UndeclaredIncludeKeyError, } from './errors.js';
+import { LOGICAL_OPERATORS, RELATION_QUANTIFIERS, resolveQueryField, validateQueryFieldReadAccess, validateQueryKeys, walkWhereReadAccess, } from './query-validation.js';
+import { isToManyRelationshipField, resolveCountAccessEntryForList } from './relationship-count.js';
+import { getDbKey } from '../lib/case-utils.js';
 /** A plain object — excludes `null` and arrays, which `typeof x === 'object'` alone would admit. */
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -13,13 +15,15 @@ function isPlainObject(value) {
  * 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.
+ * issue #752), and a caller-supplied `orderBy`/`skip` (#851), are carried
+ * through the same way: none of the three can ever widen the result past the
+ * access `where` — they only narrow or reorder rows the access filter already
+ * admits — so preserving them is access-neutral.
  */
 function asEntryObject(value) {
     if (!isPlainObject(value))
         return null;
-    const { where, include, take } = value;
+    const { where, include, take, orderBy, skip } = value;
     const entry = {};
     if (isPlainObject(where))
         entry.where = where;
@@ -27,6 +31,11 @@ function asEntryObject(value) {
         entry.include = include;
     if (typeof take === 'number')
         entry.take = take;
+    if (isPlainObject(orderBy) || Array.isArray(orderBy)) {
+        entry.orderBy = orderBy;
+    }
+    if (typeof skip === 'number')
+        entry.skip = skip;
     return entry;
 }
 /**
@@ -42,25 +51,229 @@ function andWhere(accessWhere, callerWhere) {
     }
     return accessWhere ?? callerWhere;
 }
+export function emptyToOneAccessFilterTree() {
+    return { filters: {}, nested: {} };
+}
+function isToOneAccessFilterTreeEmpty(tree) {
+    return Object.keys(tree.filters).length === 0 && Object.keys(tree.nested).length === 0;
+}
+/**
+ * Whether a relationship field is to-one (at most one related row) rather
+ * than to-many. Exported so `field-visibility.ts` can pick the same `null`
+ * (to-one) vs `[]` (to-many) shape for a denied relation's forced value
+ * (issue #1103) that this module used to decide whether to record the
+ * denial in the first place — one source of truth for arity, not two.
+ */
+export function isToOneRelationship(fieldConfig) {
+    return !('many' in fieldConfig && fieldConfig.many === true);
+}
+export function emptyCountAccessDenialTree() {
+    return { keys: new Set(), nested: {} };
+}
+function isCountAccessDenialTreeEmpty(tree) {
+    return tree.keys.size === 0 && Object.keys(tree.nested).length === 0;
+}
+/**
+ * Normalize a caller's `_count` include value to the `_count.select` map it
+ * names. `true` (Prisma's "count every relation" shorthand) expands to every
+ * countable relation Prisma itself carries on this model — every DECLARED
+ * to-many relationship, plus every synthetic back-relation a list-only `ref`
+ * elsewhere in the config synthesizes onto it (issue #1082): Prisma's own
+ * `_count: true` has always counted both, and dropping the synthetic ones
+ * here would silently stop counting a relation the caller used to get a
+ * (previously unscoped) count for. Returns `null` for a shape that requests
+ * nothing countable (`false`, or an object with no usable `select`).
+ */
+function normalizeCountSelect(requestedValue, fieldConfigs, listKey, config) {
+    if (requestedValue === true) {
+        const expanded = {};
+        for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+            if (isToManyRelationshipField(fieldConfig))
+                expanded[fieldName] = true;
+        }
+        for (const syntheticName of listSyntheticReverseRelationNames(listKey, config)) {
+            expanded[syntheticName] = true;
+        }
+        return expanded;
+    }
+    if (isPlainObject(requestedValue) && isPlainObject(requestedValue.select)) {
+        return requestedValue.select;
+    }
+    return null;
+}
+/**
+ * Scope a caller-supplied `_count` include value by each named relation's own
+ * `query` access — the `_count` counterpart to the rest of this module's
+ * relation scoping (issue #1087, closing the one key `buildAccessScopedInclude`
+ * used to allowlist through unscoped, #1082's "Out of scope").
+ *
+ * For each key in the caller's `_count.select` (or, for bare `_count: true`,
+ * every declared to-many relation — see `normalizeCountSelect`):
+ * - Not a declared to-many relationship and not a synthetic back-relation
+ *   (#1082 — always genuinely countable) → THROWN as
+ *   `UndeclaredCountKeyError`, matching `buildAccessScopedInclude`'s own
+ *   rejection for the ordinary walk. A declared to-many relationship whose
+ *   `ref` cannot be resolved is skipped instead, matching that same walk's
+ *   handling of a config-level dangling ref (not a caller error).
+ * - The counting list's OWN field-level `read` access on the relationship
+ *   field being counted denies it, or the related list's `query` access
+ *   denies it (`=== false`) → omitted from the select sent to Prisma and
+ *   added to the returned `deniedKeys`, so `filterReadableFields` can inject
+ *   `0` post-query (a count is session-relative; denial doesn't mean "no such
+ *   relation"). The field-level check has nothing to evaluate for a synthetic
+ *   back-relation (no field of its own on this list) and is skipped for it —
+ *   `resolveCountAccessEntryForList` (issue #1111). Both checks run BEFORE
+ *   any caller-supplied nested `where` is validated — validating first would
+ *   let a caller who cannot read a single row of the related list learn its
+ *   field names and field-level read rules from a thrown `ValidationError`
+ *   alone, reopening the exact oracle #915/ADR-0031 closed for a top-level
+ *   predicate.
+ * - Otherwise → the caller-supplied nested `where` at that key (if any) is
+ *   key- and read-access-validated against the RELATED list via the same
+ *   `validateQueryKeys`/`validateQueryFieldReadAccess` primitives
+ *   `createFindMany` already runs on a top-level `where` (#912/#915), then
+ *   run through `buildAccessScopedWhere` — the same fold `createFindMany`
+ *   applies to a top-level `where` (#916) — so a relation filter nested
+ *   inside IT (e.g. `_count.select.posts.where.comments.some`) is scoped by
+ *   THAT further list's own `query` access too, not just the counted
+ *   relation's. The result is AND-combined with the counted relation's own
+ *   access filter (if any) — reusing `andWhere`, never replacing the
+ *   caller's condition, mirroring `buildAccessScopedInclude` itself.
+ */
+async function buildAccessScopedCountSelect(requestedValue, fieldConfigs, args, config, listKey) {
+    const requestedSelect = normalizeCountSelect(requestedValue, fieldConfigs, listKey, config);
+    const deniedKeys = new Set();
+    if (!requestedSelect)
+        return { select: undefined, deniedKeys };
+    const select = {};
+    for (const [key, entryValue] of Object.entries(requestedSelect)) {
+        // A caller can explicitly exclude a key from the `true`-expanded set the
+        // same way Prisma's own `select` excludes a field.
+        if (entryValue === false)
+            continue;
+        const fieldConfig = fieldConfigs[key];
+        const isDeclaredToMany = isToManyRelationshipField(fieldConfig);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+        let relatedConfig = null;
+        if (isDeclaredToMany && fieldConfig && 'ref' in fieldConfig) {
+            relatedConfig = getRelatedListConfig(fieldConfig.ref, config);
+        }
+        if (!relatedConfig && !isDeclaredToMany) {
+            const synthetic = resolveSyntheticReverseRelation(key, listKey, config);
+            if (synthetic) {
+                relatedConfig = {
+                    listName: synthetic.sourceListName,
+                    listConfig: synthetic.sourceListConfig,
+                };
+            }
+        }
+        if (!relatedConfig) {
+            // A declared to-many field whose `ref` didn't resolve is a config
+            // issue, not a caller error — skip it exactly like the ordinary
+            // include walk does for the same case.
+            if (isDeclaredToMany)
+                continue;
+            throw new UndeclaredCountKeyError(listKey, key);
+        }
+        // `fieldConfig` is undefined for a synthetic back-relation (#1082) — it has
+        // no field of its own on THIS list, so there is no field-level `read`
+        // access to fold in; `resolveCountAccessEntryForList` treats a missing
+        // `fieldAccess` as exempt, matching the ordinary include path's own lack
+        // of a field-level gate for a synthetic key (issue #1111).
+        const accessEntry = await resolveCountAccessEntryForList(relatedConfig.listConfig, args, fieldConfig?.access);
+        // Denial is checked BEFORE the caller's nested `where` is validated —
+        // mirroring `buildAccessScopedWhere`'s own ordering below. A fully denied
+        // relation counts `0` no matter what `where` the caller supplied, so
+        // validating it first would let a caller who cannot read a single row of
+        // the related list learn its field names and field-level read rules from
+        // a `ValidationError`'s message alone — the exact oracle #915/ADR-0031
+        // closed for a top-level predicate, reopened here if this ran first.
+        if (accessEntry.kind === 'denied') {
+            deniedKeys.add(key);
+            continue;
+        }
+        const requestedWhere = isPlainObject(entryValue) && isPlainObject(entryValue.where)
+            ? entryValue.where
+            : undefined;
+        let scopedRequestedWhere;
+        if (requestedWhere) {
+            // Mirrors `buildAccessScopedInclude`'s own `resolveSyntheticRelation`
+            // closure (#1092/#916) — a synthetic back-relation (#1082) named inside
+            // this count entry's own `where` resolves against its source list
+            // rather than being rejected as undeclared, at every hop.
+            const resolveSyntheticRelation = (syntheticKey, fromListName) => {
+                const synthetic = resolveSyntheticReverseRelation(syntheticKey, fromListName, config);
+                return synthetic
+                    ? { listConfig: synthetic.sourceListConfig, listName: synthetic.sourceListName }
+                    : null;
+            };
+            validateQueryKeys({
+                where: requestedWhere,
+                listConfig: relatedConfig.listConfig,
+                listName: relatedConfig.listName,
+                config,
+                isSudo: false,
+                resolveSyntheticRelation,
+            });
+            await validateQueryFieldReadAccess({
+                where: requestedWhere,
+                listConfig: relatedConfig.listConfig,
+                listName: relatedConfig.listName,
+                session: args.session,
+                context: args.context,
+                isSudo: false,
+            });
+            // A relation filter (`some`/`every`/`none`/`is`/`isNot`) nested inside
+            // the caller's own `where` names a THIRD list one hop further out —
+            // e.g. `_count.select.posts.where.comments.some`. Validation above only
+            // checked keys against the counted relation's OWN fields; without this,
+            // that nested relation would reach Prisma unscoped by ITS list's
+            // `query` access, letting the resulting count reveal whether
+            // inaccessible rows over there exist. `buildAccessScopedWhere` is the
+            // same fold `createFindMany` runs on an ordinary top-level `where`
+            // (#916) — reused here rather than re-derived.
+            scopedRequestedWhere = (await buildAccessScopedWhere(requestedWhere, relatedConfig.listConfig, relatedConfig.listName, config, args, resolveSyntheticRelation));
+        }
+        const scopedWhere = andWhere(accessEntry.kind === 'scoped' ? accessEntry.where : undefined, scopedRequestedWhere);
+        select[key] = scopedWhere ? { where: scopedWhere } : true;
+    }
+    return { select: Object.keys(select).length > 0 ? select : undefined, deniedKeys };
+}
 /**
  * Build the access-scoped `include` for exactly the relations a read
  * requested, recursing only into branches `requestedInclude` itself names.
  *
  * 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 field that isn't a relationship (scalar, virtual, …) → access
+ *   control does not govern it; passed through unchanged (a virtual key is
+ *   stripped later by `stripVirtualFieldsFromInclude`, #628).
+ * - Not declared at all → resolved via `resolveSyntheticReverseRelation`
+ *   (the synthetic-back-relation case above); `_count` is scoped by
+ *   `buildAccessScopedCountSelect` (issue #1087 — each named relation's own
+ *   `query` access, exactly like any other relation this walk scopes; a
+ *   denied one is recorded for `filterReadableFields` to inject `0` for,
+ *   post-query, since Prisma cannot be asked for a guaranteed `0`); anything
+ *   else throws `UndeclaredIncludeKeyError` rather than reaching the
+ *   database unscoped.
  * - 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.
+ *   control chooses *whether* and *with what filter*. This denial is also
+ *   recorded in `toOneAccessFilters` (`kind: 'denied'`), for either arity, so
+ *   `filterReadableFields` can still surface an explicit `null` (to-one,
+ *   issue #974) or `[]` (to-many, issue #1103) for it rather than an absent
+ *   key.
+ * - Otherwise, for a to-**many** relation → the access `where` is
+ *   AND-combined with any caller-supplied nested `where` (never replaced —
+ *   the other half of #566), and a caller-supplied `take` rides through
+ *   unchanged (#752). For a to-**one** relation → the access filter (if any)
+ *   is recorded in `toOneAccessFilters` instead of attached as `where`,
+ *   because Prisma only accepts a nested `where` on a to-many include
+ *   (issue #974) — the entry itself never carries a `where` for a to-one key.
+ * - Either way — 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.
  *
  * **Depth is a cost limit, not a cycle guard (ADR-0026).** A `requestedInclude`
  * is always a finite literal — the caller's own object, or
@@ -77,41 +290,223 @@ export async function buildAccessScopedInclude(requestedInclude, fieldConfigs, a
         throw new AccessScopeDepthExceededError(listKey, requestedKeys[0], depth);
     }
     const result = {};
+    const toOneAccessFilters = emptyToOneAccessFilterTree();
+    const countDenials = emptyCountAccessDenialTree();
     for (const [relationName, requestedValue] of Object.entries(requestedInclude)) {
+        // A caller can explicitly opt a relation OUT of a Prisma include with
+        // `false` (its `Include` type allows a bare `boolean`), or end up with an
+        // `undefined` value from a conditionally-built object
+        // (`{ posts: cond ? true : undefined }`) — Prisma treats both the same as
+        // the key being absent. Treat them identically here too, before this key
+        // ever reaches access evaluation: an explicitly-disabled relation was
+        // never actually requested, so it must not be evaluated, dropped as
+        // "denied", or recorded as needing a post-query fixup (issue #1103 code
+        // review) — any of those would surface a value (`[]`/`null`) for a key
+        // the caller deliberately excluded.
+        if (requestedValue === false || requestedValue === undefined)
+            continue;
         const fieldConfig = fieldConfigs[relationName];
         const isDeclaredRelationship = fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && !!fieldConfig.ref;
-        if (!isDeclaredRelationship) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+        let relatedConfig;
+        let isToOne;
+        if (isDeclaredRelationship) {
+            relatedConfig = getRelatedListConfig(fieldConfig.ref, config);
+            if (!relatedConfig)
+                continue;
+            isToOne = isToOneRelationship(fieldConfig);
+        }
+        else if (fieldConfig) {
+            // A declared field that is not a relationship — access control does
+            // not govern it here; passed through unchanged.
             result[relationName] = requestedValue;
             continue;
         }
-        const relatedConfig = getRelatedListConfig(fieldConfig.ref, config);
-        if (!relatedConfig)
+        else if (relationName === '_count') {
+            const { select, deniedKeys } = await buildAccessScopedCountSelect(requestedValue, fieldConfigs, args, config, listKey);
+            if (select)
+                result[relationName] = { select };
+            if (deniedKeys.size > 0)
+                countDenials.keys = deniedKeys;
             continue;
+        }
+        else {
+            const synthetic = resolveSyntheticReverseRelation(relationName, listKey, config);
+            if (!synthetic) {
+                throw new UndeclaredIncludeKeyError(listKey, relationName);
+            }
+            relatedConfig = { listName: synthetic.sourceListName, listConfig: synthetic.sourceListConfig };
+            // Always to-many — a list-only ref has one construction site and no
+            // arity branch, and one-to-one is structurally impossible for it.
+            isToOne = false;
+        }
         const queryAccess = relatedConfig.listConfig.access?.operation?.query;
         const accessResult = await checkAccess(queryAccess, {
             session: args.session,
             context: args.context,
         });
         if (accessResult === false) {
+            // Recorded for either arity (issue #1103) — a to-many relation is
+            // dropped from `include` here exactly like a to-one one, and needs the
+            // same post-query fixup so its key comes back `[]`, not silently
+            // absent from the row.
+            toOneAccessFilters.filters[relationName] = { kind: 'denied' };
             continue;
         }
         const accessWhere = typeof accessResult === 'object' ? accessResult : undefined;
         const requestedEntry = asEntryObject(requestedValue);
-        const mergedWhere = andWhere(accessWhere, requestedEntry?.where);
+        // #1092 — a nested `where`/`orderBy` gets the same #912/#915 checks the
+        // top-level `where`/`orderBy` already gets, resolved against the RELATED
+        // list (`relatedConfig`) rather than the current one, and run only once
+        // the relation is known to be accessible at all (same ordering reason as
+        // the top-level checks: don't leak a field's name/read-gating status to a
+        // caller who has zero access to the relation to begin with).
+        const resolveSyntheticRelation = (key, fromListName) => {
+            const synthetic = resolveSyntheticReverseRelation(key, fromListName, config);
+            return synthetic
+                ? { listConfig: synthetic.sourceListConfig, listName: synthetic.sourceListName }
+                : null;
+        };
+        validateQueryKeys({
+            where: requestedEntry?.where,
+            orderBy: requestedEntry?.orderBy,
+            listConfig: relatedConfig.listConfig,
+            listName: relatedConfig.listName,
+            config,
+            isSudo: false,
+            resolveSyntheticRelation,
+        });
+        await validateQueryFieldReadAccess({
+            where: requestedEntry?.where,
+            orderBy: requestedEntry?.orderBy,
+            listConfig: relatedConfig.listConfig,
+            listName: relatedConfig.listName,
+            session: args.session,
+            context: args.context,
+            isSudo: false,
+        });
+        // The two checks above only reach the entry's own top-level keys — a
+        // relation quantifier (`some`/`every`/`none`/`is`/`isNot`) nested inside
+        // this `where` names a DEEPER related list, which needs the same
+        // treatment the top-level `where` already gets from `buildAccessScopedWhere`
+        // (#916): scope it by that deeper list's own `query` access and check ITS
+        // fields' read access, recursing through every further hop. Only for
+        // to-many — a to-one entry never carries `requestedEntry.where` through to
+        // Prisma at all (see below), so there is nothing here to scope.
+        const scopedRequestedWhere = !isToOne && requestedEntry?.where !== undefined
+            ? (await buildAccessScopedWhere(requestedEntry.where, relatedConfig.listConfig, relatedConfig.listName, config, args, resolveSyntheticRelation))
+            : requestedEntry?.where;
         let nestedInclude;
+        let nestedToOneFilters;
+        let nestedCountDenials;
         if (requestedEntry?.include) {
-            nestedInclude = await buildAccessScopedInclude(requestedEntry.include, relatedConfig.listConfig.fields, args, config, relatedConfig.listName, depth + 1);
+            const nested = await buildAccessScopedInclude(requestedEntry.include, relatedConfig.listConfig.fields, args, config, relatedConfig.listName, depth + 1);
+            nestedInclude = nested.include;
+            nestedToOneFilters = nested.toOneAccessFilters;
+            nestedCountDenials = nested.countDenials;
         }
         const entry = {};
-        if (mergedWhere)
-            entry.where = mergedWhere;
+        if (isToOne) {
+            if (accessWhere) {
+                toOneAccessFilters.filters[relationName] = {
+                    kind: 'scoped',
+                    relatedListName: relatedConfig.listName,
+                    accessWhere,
+                };
+            }
+        }
+        else {
+            const mergedWhere = andWhere(accessWhere, scopedRequestedWhere);
+            if (mergedWhere)
+                entry.where = mergedWhere;
+            if (requestedEntry?.take !== undefined)
+                entry.take = requestedEntry.take;
+            if (requestedEntry?.orderBy !== undefined)
+                entry.orderBy = requestedEntry.orderBy;
+            if (requestedEntry?.skip !== undefined)
+                entry.skip = requestedEntry.skip;
+        }
         if (nestedInclude && Object.keys(nestedInclude).length > 0)
             entry.include = nestedInclude;
-        if (requestedEntry?.take !== undefined)
-            entry.take = requestedEntry.take;
+        if (nestedToOneFilters && !isToOneAccessFilterTreeEmpty(nestedToOneFilters)) {
+            toOneAccessFilters.nested[relationName] = nestedToOneFilters;
+        }
+        if (nestedCountDenials && !isCountAccessDenialTreeEmpty(nestedCountDenials)) {
+            countDenials.nested[relationName] = nestedCountDenials;
+        }
         result[relationName] = Object.keys(entry).length > 0 ? entry : true;
     }
-    return result;
+    return { include: result, toOneAccessFilters, countDenials };
+}
+export function emptyToOneAccessVisibilityTree() {
+    return { filters: {}, nested: {} };
+}
+/**
+ * Resolve a `ToOneAccessFilterTree` against the RAW rows Prisma already
+ * fetched (unscoped for the flagged to-one relations — see
+ * `buildAccessScopedInclude`) into the set of related ids the session may
+ * actually see, one batched `id IN (...)` existence check per (relation,
+ * nesting level) across every row in `items` — never once per row.
+ *
+ * For each `filters` entry at a level:
+ * - `kind: 'denied'` → carried straight through; no query, nothing to check.
+ * - `kind: 'scoped'` → every id present at this key across ALL of `items` is
+ *   collected first (an empty set skips the query entirely — nothing to
+ *   check), then ONE `findMany` through the RAW `prisma` client (not
+ *   `context.db`, which would re-evaluate the same access-control function a
+ *   second time) asks which of those ids also satisfy `accessWhere` — the
+ *   exact `PrismaFilter` `checkAccess` already produced, handed to Prisma
+ *   unmodified rather than interpreted by hand.
+ *
+ * Recurses into `nested` by flattening the related items reached through
+ * each key across every row in `items` (a to-many hop contributes every one
+ * of its rows; a to-one hop contributes its single row, if any) into the
+ * next level's own `items` array, so a to-one relation nested arbitrarily
+ * deep is still resolved with one batched query per node, not per parent row.
+ */
+export async function resolveToOneAccessVisibility(items, tree, args) {
+    const resolved = emptyToOneAccessVisibilityTree();
+    for (const [key, entry] of Object.entries(tree.filters)) {
+        if (entry.kind === 'denied') {
+            resolved.filters[key] = { kind: 'denied' };
+            continue;
+        }
+        const ids = new Set();
+        for (const item of items) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const value = item[key];
+            if (value && typeof value === 'object' && 'id' in value) {
+                ids.add(String(value.id));
+            }
+        }
+        if (ids.size === 0) {
+            resolved.filters[key] = { kind: 'visible', ids: new Set() };
+            continue;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic model access by list name, mirroring the rest of the read pipeline
+        const model = args.context.prisma[getDbKey(entry.relatedListName)];
+        const visibleRows = await model.findMany({
+            where: { AND: [entry.accessWhere, { id: { in: [...ids] } }] },
+            select: { id: true },
+        });
+        const visibleIds = new Set(Array.isArray(visibleRows) ? visibleRows.map((row) => String(row.id)) : []);
+        resolved.filters[key] = { kind: 'visible', ids: visibleIds };
+    }
+    for (const [key, nestedTree] of Object.entries(tree.nested)) {
+        const nestedItems = [];
+        for (const item of items) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const value = item[key];
+            if (Array.isArray(value))
+                nestedItems.push(...value);
+            else if (value && typeof value === 'object')
+                nestedItems.push(value);
+        }
+        resolved.nested[key] = await resolveToOneAccessVisibility(nestedItems, nestedTree, args);
+    }
+    return resolved;
 }
 /**
  * Scope every relation filter (`some`/`every`/`none`/`is`/`isNot`) nested in a
@@ -153,32 +548,55 @@ export async function buildAccessScopedInclude(requestedInclude, fieldConfigs, 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.
+ *
+ * A quantifier's value of literal `null` (`is: null`/`isNot: null`, a to-one
+ * relation's existence check) is passed through untouched rather than folded:
+ * it names no fields to read-check or scope, and AND-folding an access filter
+ * into it would silently invert the caller's own predicate (see the inline
+ * comment at that branch).
+ *
+ * `resolveSyntheticRelation` (#1092/#1108) extends this to a key that
+ * resolves to a synthetic back-relation (#1082) rather than a declared
+ * field, recursing against its SOURCE list. Only `buildAccessScopedInclude`
+ * passes it, for the include-nested `where` position; the top-level `where`
+ * this function was originally built for (`context/index.ts`) omits it, so
+ * a synthetic key there is unaffected — matching #1092's own scope, which
+ * deliberately left the top-level checks unchanged.
  */
 export async function buildAccessScopedWhere(where, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
-listConfig, listName, config, args) {
+listConfig, listName, config, args, 
+// #1092/#1108 — the include-nested position's own addition, exactly
+// mirroring `validateQueryKeys`'s `resolveSyntheticRelation` (see that
+// module's doc comment): every top-level `where` caller omits this, so
+// top-level behavior is unchanged.
+resolveSyntheticRelation) {
     if (where === null || typeof where !== 'object')
         return where;
     if (Array.isArray(where)) {
-        return Promise.all(where.map((entry) => buildAccessScopedWhere(entry, listConfig, listName, config, args)));
+        return Promise.all(where.map((entry) => buildAccessScopedWhere(entry, listConfig, listName, config, args, resolveSyntheticRelation)));
     }
     const result = {};
     for (const [key, value] of Object.entries(where)) {
         if (LOGICAL_OPERATORS.has(key)) {
-            result[key] = await buildAccessScopedWhere(value, listConfig, listName, config, args);
+            result[key] = await buildAccessScopedWhere(value, listConfig, listName, config, args, resolveSyntheticRelation);
             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) {
+        // A synthetic back-relation (#1082) carries no `ref` of its own to
+        // follow — its "related" list for recursion is the SOURCE list it
+        // stands for, given directly by the resolver, not `getRelatedListConfig`.
+        const related = resolved?.isRelationship
+            ? getRelatedListConfig(resolved.fieldConfig.ref, config)
+            : !resolved
+                ? (() => {
+                    const synthetic = resolveSyntheticRelation?.(key, listName);
+                    return synthetic
+                        ? { listConfig: synthetic.listConfig, listName: synthetic.listName }
+                        : null;
+                })()
+                : null;
+        if (!related || value === null || typeof value !== 'object' || Array.isArray(value)) {
             result[key] = value;
             continue;
         }
@@ -200,8 +618,18 @@ listConfig, listName, config, args) {
                     nestedEntry[quantifier] = quantifierValue;
                     continue;
                 }
+                if (quantifierValue === null) {
+                    // `is: null` / `isNot: null` tests EXISTENCE of a to-one relation,
+                    // not its fields — there is nothing to read-check or scope, and
+                    // AND-folding the access filter in here would silently invert the
+                    // caller's predicate: `is: null` ("has no related row") would
+                    // become `is: <accessWhere>` ("has a related row matching the
+                    // filter"), the opposite of what was asked. Passed through as-is.
+                    nestedEntry[quantifier] = null;
+                    continue;
+                }
                 await walkWhereReadAccess(quantifierValue, related.listConfig, related.listName, args);
-                const scopedNested = await buildAccessScopedWhere(quantifierValue, related.listConfig, related.listName, config, args);
+                const scopedNested = await buildAccessScopedWhere(quantifierValue, related.listConfig, related.listName, config, args, resolveSyntheticRelation);
                 nestedEntry[quantifier] = accessWhere
                     ? andWhere(accessWhere, scopedNested)
                     : scopedNested;
@@ -215,7 +643,7 @@ listConfig, listName, config, args) {
             // (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);
+            const scopedNested = await buildAccessScopedWhere(value, related.listConfig, related.listName, config, args, resolveSyntheticRelation);
             result[key] = accessWhere
                 ? { is: andWhere(accessWhere, scopedNested) }
                 : scopedNested;