@opensaas/stack-core 0.39.2 → 0.40.0

package/src/access/access-filter.ts

@@ -9,6 +9,7 @@ import {
   resolveQueryField,
   walkWhereReadAccess,
 } from './query-validation.js'
+import { getDbKey } from '../lib/case-utils.js'
 
 /**
  * Access Filter — phase 1 of the two-phase read (pre-query).
@@ -34,10 +35,36 @@ import {
  * 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.
+ *
+ * **To-one relations are scoped after the query, not inside it (issue #974).**
+ * Prisma accepts a nested `where` on an `include` entry only for a to-**many**
+ * relation; the same shape on a to-**one** relation raises
+ * `PrismaClientValidationError`. So for a to-one relation whose related
+ * list's `query` access resolves to a filter, `buildAccessScopedInclude`
+ * does NOT attach that filter as `where` — it fetches the row unscoped and
+ * records the filter in the returned `toOneAccessFilters` tree instead.
+ * `resolveToOneAccessVisibility` (below) turns that tree into the set of
+ * related ids the session may actually see, via ONE batched `id IN (...)`
+ * existence check per (relation, nesting level) across every row in the
+ * read — never a per-row query, and never a hand-rolled evaluation of the
+ * access filter (it is handed to Prisma exactly as `checkAccess` produced
+ * it). `field-visibility.ts`'s `filterReadableFields` is where the result
+ * actually becomes `null` for a row the check excludes — see its module doc.
+ * A to-one relation whose related list's `query` access is `true` (no
+ * filter) or `false` (denied outright) needs no existence check at all: the
+ * former is left as `true` in `include`, unchanged from before; the latter
+ * is recorded as `{ kind: 'denied' }`, and `field-visibility.ts` forces the
+ * key to `null` without ever asking Prisma for it.
  */
 
 /** 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 }
+type IncludeEntryObject = {
+  where?: PrismaFilter
+  include?: Record<string, unknown>
+  take?: number
+  orderBy?: PrismaFilter | PrismaFilter[]
+  skip?: number
+}
 
 /** A plain object — excludes `null` and arrays, which `typeof x === 'object'` alone would admit. */
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -51,16 +78,22 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * 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: unknown): IncludeEntryObject | null {
   if (!isPlainObject(value)) return null
-  const { where, include, take } = value
+  const { where, include, take, orderBy, skip } = value
   const entry: IncludeEntryObject = {}
   if (isPlainObject(where)) entry.where = where
   if (isPlainObject(include)) entry.include = include
   if (typeof take === 'number') entry.take = take
+  if (isPlainObject(orderBy) || Array.isArray(orderBy)) {
+    entry.orderBy = orderBy as PrismaFilter | PrismaFilter[]
+  }
+  if (typeof skip === 'number') entry.skip = skip
   return entry
 }
 
@@ -81,6 +114,38 @@ function andWhere(
   return accessWhere ?? callerWhere
 }
 
+/** One to-one relation's recorded access filter, or an outright denial — see the module doc's "To-one relations" section. */
+export type ToOneAccessFilterEntry =
+  { kind: 'scoped'; relatedListName: string; accessWhere: PrismaFilter } | { kind: 'denied' }
+
+/**
+ * Which to-one relations, at which nesting level of an `include`, need a
+ * post-query existence check rather than a Prisma-side `where` — because
+ * their related list's `query` access resolved to a filter (`kind: 'scoped'`)
+ * or a denial (`kind: 'denied'`) and Prisma cannot express either as a nested
+ * `where` on a to-one include. `resolveToOneAccessVisibility` consumes this
+ * tree; `filterReadableFields` (`field-visibility.ts`) applies its result.
+ */
+export type ToOneAccessFilterTree = {
+  /** To-one relation keys at THIS level needing a post-query check. */
+  filters: Record<string, ToOneAccessFilterEntry>
+  /** Per-key trees for relations present in the include for other reasons, whose own nested include may contain further to-one filters. */
+  nested: Record<string, ToOneAccessFilterTree>
+}
+
+export function emptyToOneAccessFilterTree(): ToOneAccessFilterTree {
+  return { filters: {}, nested: {} }
+}
+
+function isToOneAccessFilterTreeEmpty(tree: ToOneAccessFilterTree): boolean {
+  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. */
+function isToOneRelationship(fieldConfig: FieldConfig): boolean {
+  return !('many' in fieldConfig && fieldConfig.many === true)
+}
+
 /**
  * Build the access-scoped `include` for exactly the relations a read
  * requested, recursing only into branches `requestedInclude` itself names.
@@ -92,14 +157,21 @@ function andWhere(
  * - 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*. For a to-one relation
+ *   this denial is also recorded in `toOneAccessFilters` (`kind: 'denied'`),
+ *   so `filterReadableFields` can still surface an explicit `null` for it
+ *   (issue #974) 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
@@ -120,13 +192,14 @@ export async function buildAccessScopedInclude(
   config: OpenSaasConfig,
   listKey: string,
   depth: number = 0,
-): Promise<Record<string, unknown>> {
+): Promise<{ include: Record<string, unknown>; toOneAccessFilters: ToOneAccessFilterTree }> {
   const requestedKeys = Object.keys(requestedInclude)
   if (depth >= READ_INCLUDE_MAX_DEPTH && requestedKeys.length > 0) {
     throw new AccessScopeDepthExceededError(listKey, requestedKeys[0], depth)
   }
 
   const result: Record<string, unknown> = {}
+  const toOneAccessFilters = emptyToOneAccessFilterTree()
 
   for (const [relationName, requestedValue] of Object.entries(requestedInclude)) {
     const fieldConfig = fieldConfigs[relationName]
@@ -141,6 +214,8 @@ export async function buildAccessScopedInclude(
     const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
     if (!relatedConfig) continue
 
+    const isToOne = isToOneRelationship(fieldConfig)
+
     const queryAccess = relatedConfig.listConfig.access?.operation?.query
     const accessResult = await checkAccess(queryAccess, {
       session: args.session,
@@ -148,16 +223,19 @@ export async function buildAccessScopedInclude(
     })
 
     if (accessResult === false) {
+      if (isToOne) {
+        toOneAccessFilters.filters[relationName] = { kind: 'denied' }
+      }
       continue
     }
 
     const accessWhere = typeof accessResult === 'object' ? accessResult : undefined
     const requestedEntry = asEntryObject(requestedValue)
-    const mergedWhere = andWhere(accessWhere, requestedEntry?.where)
 
     let nestedInclude: Record<string, unknown> | undefined
+    let nestedToOneFilters: ToOneAccessFilterTree | undefined
     if (requestedEntry?.include) {
-      nestedInclude = await buildAccessScopedInclude(
+      const nested = await buildAccessScopedInclude(
         requestedEntry.include,
         relatedConfig.listConfig.fields,
         args,
@@ -165,17 +243,127 @@ export async function buildAccessScopedInclude(
         relatedConfig.listName,
         depth + 1,
       )
+      nestedInclude = nested.include
+      nestedToOneFilters = nested.toOneAccessFilters
     }
 
-    const entry: { where?: PrismaFilter; include?: Record<string, unknown>; take?: number } = {}
-    if (mergedWhere) entry.where = mergedWhere
+    const entry: IncludeEntryObject = {}
+    if (isToOne) {
+      if (accessWhere) {
+        toOneAccessFilters.filters[relationName] = {
+          kind: 'scoped',
+          relatedListName: relatedConfig.listName,
+          accessWhere,
+        }
+      }
+    } else {
+      const mergedWhere = andWhere(accessWhere, requestedEntry?.where)
+      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
+    }
 
     result[relationName] = Object.keys(entry).length > 0 ? entry : true
   }
 
-  return result
+  return { include: result, toOneAccessFilters }
+}
+
+/** One to-one relation's resolved post-query visibility — see `resolveToOneAccessVisibility`. */
+export type ToOneVisibility = { kind: 'denied' } | { kind: 'visible'; ids: ReadonlySet<string> }
+
+/** The resolved counterpart to {@link ToOneAccessFilterTree}, produced by `resolveToOneAccessVisibility`. */
+export type ToOneAccessVisibilityTree = {
+  filters: Record<string, ToOneVisibility>
+  nested: Record<string, ToOneAccessVisibilityTree>
+}
+
+export function emptyToOneAccessVisibilityTree(): ToOneAccessVisibilityTree {
+  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: readonly unknown[],
+  tree: ToOneAccessFilterTree,
+  args: {
+    session: Session | null
+    context: AccessContext
+  },
+): Promise<ToOneAccessVisibilityTree> {
+  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<string>()
+    for (const item of items) {
+      if (!item || typeof item !== 'object') continue
+      const value = (item as Record<string, unknown>)[key]
+      if (value && typeof value === 'object' && 'id' in value) {
+        ids.add(String((value as Record<string, unknown>).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 as any)[getDbKey(entry.relatedListName)]
+    const visibleRows = await model.findMany({
+      where: { AND: [entry.accessWhere, { id: { in: [...ids] } }] },
+      select: { id: true },
+    })
+    const visibleIds = new Set<string>(
+      Array.isArray(visibleRows) ? visibleRows.map((row: { id: unknown }) => String(row.id)) : [],
+    )
+    resolved.filters[key] = { kind: 'visible', ids: visibleIds }
+  }
+
+  for (const [key, nestedTree] of Object.entries(tree.nested)) {
+    const nestedItems: unknown[] = []
+    for (const item of items) {
+      if (!item || typeof item !== 'object') continue
+      const value = (item as Record<string, unknown>)[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
 }
 
 /**

package/src/access/engine.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest'
+import { resolveSyntheticReverseRelation } from './engine.js'
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+
+// A relationship field pointing at another list.
+function rel(ref: string, many = false): FieldConfig {
+  return { type: 'relationship', ref, many } as unknown as FieldConfig
+}
+
+/**
+ * #978: a list-only `ref` (`ref: 'ListName'`, no target field) generates a
+ * synthetic back-relation on its target — `from_<SourceList>_<sourceField>`
+ * (see `getSyntheticFieldName` in fields/index.ts). `resolveSyntheticReverseRelation`
+ * is the runtime counterpart that recognises the same name and resolves it
+ * back to the declared field that owns it, so a nested write addressed to it
+ * gets the same hook pipeline a declared relationship field gets.
+ */
+describe('resolveSyntheticReverseRelation', () => {
+  const config: OpenSaasConfig = {
+    db: { provider: 'sqlite', url: 'file:./dev.db' },
+    lists: {
+      Account: { fields: { name: { type: 'text' } as unknown as FieldConfig } },
+      ChargeRequest: {
+        fields: {
+          kind: { type: 'text' } as unknown as FieldConfig,
+          // List-only ref — no field named on Account, so a back-relation is
+          // synthesized on it as `from_ChargeRequest_account`.
+          account: rel('Account'),
+        },
+      },
+      // A bidirectional relationship — Post.author names User.posts directly,
+      // so no back-relation is synthesized anywhere for it.
+      User: { fields: { posts: rel('Post.author', true) } },
+      Post: { fields: { author: rel('User.posts') } },
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any
+
+  it('resolves the synthetic back-relation name to its owning field', () => {
+    const result = resolveSyntheticReverseRelation('from_ChargeRequest_account', 'Account', config)
+    expect(result).not.toBeNull()
+    expect(result?.sourceListName).toBe('ChargeRequest')
+    expect(result?.sourceFieldName).toBe('account')
+    expect(result?.sourceFieldConfig.ref).toBe('Account')
+  })
+
+  it('returns null for a name that does not match the synthetic construction', () => {
+    expect(
+      resolveSyntheticReverseRelation('from_ChargeRequest_amount', 'Account', config),
+    ).toBeNull()
+    expect(resolveSyntheticReverseRelation('chargeRequests', 'Account', config)).toBeNull()
+  })
+
+  it('returns null on the wrong parent list', () => {
+    expect(
+      resolveSyntheticReverseRelation('from_ChargeRequest_account', 'ChargeRequest', config),
+    ).toBeNull()
+  })
+
+  it('returns null for a bidirectional ref — its other side is a real declared field, not a synthetic one', () => {
+    expect(resolveSyntheticReverseRelation('from_Post_author', 'User', config)).toBeNull()
+  })
+
+  it('returns null for a genuinely unknown key', () => {
+    expect(resolveSyntheticReverseRelation('totallyBogusKey', 'Account', config)).toBeNull()
+  })
+})

package/src/access/engine.ts

@@ -1,5 +1,7 @@
 import type { AccessControl, Session, AccessContext, PrismaFilter } from './types.js'
-import type { OpenSaasConfig, ListConfig } from '../config/types.js'
+import type { OpenSaasConfig, ListConfig, RelationshipField } from '../config/types.js'
+import { getSyntheticFieldName } from '../fields/index.js'
+import { InvalidCreateAccessResultError } from './errors.js'
 
 /**
  * Access engine — operation-level access control and shared helpers.
@@ -45,6 +47,53 @@ export function getRelatedListConfig(
   return { listName, listConfig }
 }
 
+/** A synthetic reverse relation, resolved back to the declared field that owns it. */
+export interface SyntheticReverseRelation {
+  sourceListName: string
+  sourceFieldName: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- RelationshipField must accept any TypeInfo
+  sourceFieldConfig: RelationshipField<any>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  sourceListConfig: ListConfig<any>
+}
+
+/**
+ * Resolve a candidate data key as the synthetic back-relation a list-only
+ * `ref` (`ref: 'ListName'`, no target field) generates on its target model —
+ * Prisma requires an opposite field there, but the config never declares one,
+ * so it never appears in `parentListName`'s own `fields`. Reuses
+ * `getSyntheticFieldName` (the same construction `getPrismaRelation` emits the
+ * schema with) rather than re-deriving the `from_<List>_<field>` format by
+ * string parsing, so the two cannot drift (#978).
+ *
+ * Returns the declared relationship field that owns the relation — the write
+ * pipeline treats a resolved synthetic key exactly like a nested write through
+ * that field, so it runs the same hooks/access/recovery machinery a declared
+ * relationship field gets. Returns `null` when `fieldName` isn't one of these
+ * on `parentListName` (a genuinely unknown key, or a bidirectional relation's
+ * ref, which never synthesizes a back-relation).
+ */
+export function resolveSyntheticReverseRelation(
+  fieldName: string,
+  parentListName: string,
+  config: OpenSaasConfig,
+): SyntheticReverseRelation | null {
+  for (const [sourceListName, sourceListConfig] of Object.entries(config.lists)) {
+    for (const [sourceFieldName, sourceFieldConfig] of Object.entries(sourceListConfig.fields)) {
+      if (sourceFieldConfig.type !== 'relationship') continue
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- RelationshipField must accept any TypeInfo
+      const rel = sourceFieldConfig as RelationshipField<any>
+      // Only a list-only ref ('ListName', no '.fieldName') synthesizes a
+      // back-relation — a bidirectional ref's other side is a real field.
+      const refParts = rel.ref.split('.')
+      if (refParts.length !== 1 || refParts[0] !== parentListName) continue
+      if (getSyntheticFieldName(sourceListName, sourceFieldName) !== fieldName) continue
+      return { sourceListName, sourceFieldName, sourceFieldConfig: rel, sourceListConfig }
+    }
+  }
+  return null
+}
+
 export async function checkAccess<T = Record<string, unknown>>(
   accessControl: AccessControl<T> | undefined,
   args: {
@@ -63,6 +112,37 @@ export async function checkAccess<T = Record<string, unknown>>(
   return result
 }
 
+/**
+ * Evaluate operation-level `create` access. The single evaluator shared by the
+ * write pipeline's top-level create and the nested-create path — both must
+ * reject the same way, or the two drift again (#1009).
+ *
+ * Unlike `checkAccess` (which `query`/`update`/`delete` call directly and which
+ * legitimately returns a filter for them to re-check against a row), create
+ * has no existing row and no way to test a filter against input data. A rule
+ * that returns anything other than a strict boolean — most notably a filter,
+ * which type-checks against the shared `AccessControl` signature and reads as
+ * though it scopes the create — throws `InvalidCreateAccessResultError`
+ * rather than being silently treated as an allow. See that error's doc,
+ * ADR-0022, and ADR-0030.
+ */
+export async function checkCreateAccess<T = Record<string, unknown>>(
+  listKey: string,
+  accessControl: AccessControl<T> | undefined,
+  args: {
+    session: Session | null
+    context: AccessContext
+  },
+): Promise<boolean> {
+  const result = await checkAccess(accessControl, args)
+
+  if (isBoolean(result)) {
+    return result
+  }
+
+  throw new InvalidCreateAccessResultError(listKey, result)
+}
+
 export function mergeFilters(
   userFilter: PrismaFilter | undefined,
   accessFilter: boolean | PrismaFilter,

package/src/access/errors.ts

@@ -99,7 +99,7 @@ export class RelationFilterAccessDeniedError extends Error {
   }
 }
 
-function describeFieldAccessResult(result: unknown): string {
+function describeAccessResult(result: unknown): string {
   if (result === null) return 'null'
   if (result === undefined) return 'undefined'
   if (typeof result === 'object') return 'an object (e.g. a Prisma filter)'
@@ -135,7 +135,7 @@ export class InvalidFieldAccessResultError extends Error {
   constructor(operation: 'read' | 'create' | 'update', result: unknown) {
     super(
       `Field-level access control for operation "${operation}" returned ` +
-        `${describeFieldAccessResult(result)}, not a boolean. Field access is a per-field ` +
+        `${describeAccessResult(result)}, not a boolean. Field access is a per-field ` +
         `visibility decision — it must return true or false, and (unlike operation-level access) ` +
         `cannot scope which rows are affected. If you meant to restrict access based on the row or ` +
         `the write payload, evaluate the condition yourself and return a boolean, e.g. ` +
@@ -145,3 +145,43 @@ export class InvalidFieldAccessResultError extends Error {
     this.operation = operation
   }
 }
+
+/**
+ * Thrown when operation-level `create` access control returns anything other
+ * than a strict `boolean`. `OperationAccess['create']` is typed as
+ * `AccessControl`, which also accepts a `PrismaFilter` — the shape
+ * `query`/`update`/`delete` legitimately use to scope which rows an
+ * operation may touch (see ADR-0001). Create has none of that to scope: there
+ * is no existing row, and — unlike update/delete, which re-check a returned
+ * filter against the target via `findFirst` — no equivalent re-check is
+ * possible against data that doesn't exist in the database yet.
+ *
+ * A filter-returning `create` rule type-checks (the shared `AccessControl`
+ * type admits it) and reads as though it scopes the create. Before this it
+ * fell through a check that only tested `=== false` and was silently treated
+ * as a full allow. This is the same defect shape ADR-0030 closed for
+ * field-level access, resolved the same way per ADR-0022 (an engine that
+ * cannot compute a scope must deny, never pass through) — a loud, distinct
+ * failure rather than a wider `null`/`[]` Silent failure, because this is a
+ * config bug, not an access denial.
+ *
+ * Deliberately does not expose the offending result as a public field, for
+ * the same reason as `InvalidFieldAccessResultError`: there is no
+ * concretely-typed shape to give it, and the root CLAUDE.md forbids exposing
+ * `unknown`/`any` as part of a package's external API.
+ */
+export class InvalidCreateAccessResultError extends Error {
+  public listKey: string
+
+  constructor(listKey: string, result: unknown) {
+    super(
+      `Operation-level "create" access control for "${listKey}" returned ` +
+        `${describeAccessResult(result)}, not a boolean. Create cannot be row-scoped — there is no ` +
+        `existing row, and no input data is available to test a filter against here. Return a ` +
+        `boolean from create access, or move the ownership check into a \`resolveInput\` or ` +
+        `\`validate\` hook, where the input data is in scope.`,
+    )
+    this.name = 'InvalidCreateAccessResultError'
+    this.listKey = listKey
+  }
+}

package/src/access/field-access.test.ts

@@ -712,3 +712,81 @@ describe('filterWritableFields', () => {
     expect(filtered.author).toEqual({ connect: { id: 'user-1' } })
   })
 })
+
+// ── #978: under sudo, only a synthetic reverse-relation key is a recognised
+// undeclared key — anything else is refused, even under sudo ──────────────
+
+describe('filterWritableFields — #978 tightened sudo undeclared-key guard', () => {
+  // A minimal config: Account is the target of ChargeRequest's list-only ref
+  // (`ref: 'Account'`, no field named on Account), so the generator
+  // synthesizes `from_ChargeRequest_account` on Account.
+  const config = {
+    db: { provider: 'sqlite', url: 'file:./dev.db' },
+    lists: {
+      Account: { fields: { name: { type: 'text' } } },
+      ChargeRequest: {
+        fields: {
+          kind: { type: 'text' },
+          account: { type: 'relationship', ref: 'Account' },
+        },
+      },
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any
+
+  it('passes a synthetic reverse-relation key through under sudo, when config/listName are supplied', async () => {
+    const fieldConfigs = { name: { type: 'text' } }
+    const data = {
+      name: 'Acme',
+      from_ChargeRequest_account: { create: { kind: 'DEPOSIT' } },
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'update', {
+      session: null,
+      item: { id: 'a1' },
+      context: sudoContext(),
+      inputData: data,
+      listName: 'Account',
+      config,
+    })
+
+    expect(filtered).toHaveProperty('name', 'Acme')
+    expect(filtered).toHaveProperty('from_ChargeRequest_account')
+  })
+
+  it('throws on a genuinely unknown key under sudo, when config/listName are supplied', async () => {
+    const fieldConfigs = { name: { type: 'text' } }
+    const data = {
+      name: 'Acme',
+      totallyBogusKey: 'value',
+    }
+
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'update', {
+        session: null,
+        item: { id: 'a1' },
+        context: sudoContext(),
+        inputData: data,
+        listName: 'Account',
+        config,
+      }),
+    ).rejects.toThrow(/totallyBogusKey/)
+  })
+
+  it('keeps the pre-#978 blanket sudo passthrough when config/listName are omitted', async () => {
+    // Pins the fallback direct unit tests above (e.g. "passes undeclared data
+    // keys through under sudo") rely on: with no config to resolve a synthetic
+    // key against, any undeclared key still passes through under sudo.
+    const fieldConfigs = { name: { type: 'text' } }
+    const data = { name: 'Acme', totallyBogusKey: 'value' }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'update', {
+      session: null,
+      item: { id: 'a1' },
+      context: sudoContext(),
+      inputData: data,
+    })
+
+    expect(filtered).toHaveProperty('totallyBogusKey', 'value')
+  })
+})