@opensaas/stack-core 0.39.2 → 0.41.0

package/src/access/denied-relation-visibility.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest'
+import { filterReadableFields } from './field-visibility.js'
+import { emptyDeclaredOnlyTree } from './declared-dependencies.js'
+import type { ToOneAccessVisibilityTree } from './access-filter.js'
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+import type { AccessContext } from './types.js'
+
+/**
+ * Regression coverage for the `filterReadableFields` half of issue #1103: a
+ * relation `buildAccessScopedInclude` denied outright is absent from the raw
+ * row (Prisma never fetched it), so the main per-field loop — which only
+ * ever visits keys `Object.entries(workingItem)` contains — never sees it.
+ * The dedicated post-query pass this file exercises is what forces the key
+ * present anyway: `null` for a to-one relation (issue #974, pre-existing),
+ * `[]` for a to-many one (issue #1103, this fix) — never a silently absent
+ * key, which is what previously broke the fragment API's typed contract
+ * (`ResultOf` types a to-many relation as an array).
+ */
+
+function rel(ref: string, many = false): FieldConfig {
+  return { type: 'relationship', ref, many } as unknown as FieldConfig
+}
+
+function makeContext(): AccessContext {
+  return {
+    session: null,
+    _isSudo: false,
+    _resolveOutputChain: [],
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal context for unit test
+  } as any
+}
+
+function config(): OpenSaasConfig {
+  return {
+    db: { provider: 'sqlite' },
+    lists: {
+      Author: {
+        fields: {
+          name: { type: 'text' } as FieldConfig,
+          secrets: rel('Secret.author', true),
+          profile: rel('Profile.author', false),
+          hiddenSecrets: {
+            ...rel('Secret.author', true),
+            access: { read: () => false },
+          } as unknown as FieldConfig,
+        },
+        access: { operation: { query: () => true } },
+      },
+      Secret: {
+        fields: { value: { type: 'text' } as FieldConfig },
+        access: { operation: { query: () => false } },
+      },
+      Profile: {
+        fields: { bio: { type: 'text' } as FieldConfig },
+        access: { operation: { query: () => false } },
+      },
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+  } as any as OpenSaasConfig
+}
+
+// Term ← Bill.term (list-only ref, no field on Term) — the synthetic
+// back-relation case, always to-many (#1082).
+function syntheticConfig(): OpenSaasConfig {
+  return {
+    db: { provider: 'sqlite' },
+    lists: {
+      Term: {
+        fields: { name: { type: 'text' } as FieldConfig },
+        access: { operation: { query: () => true } },
+      },
+      Bill: {
+        fields: { amount: { type: 'integer' } as FieldConfig, term: rel('Term') },
+        access: { operation: { query: () => false } },
+      },
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+  } as any as OpenSaasConfig
+}
+
+describe('filterReadableFields — denied relations forced present (issues #974 / #1103)', () => {
+  it('forces a denied to-many relation to [], not an absent key', async () => {
+    const cfg = config()
+    const authorRow = { id: 'a1', name: 'A' } // `secrets` absent — never fetched by Prisma
+    const toOneVisibility: ToOneAccessVisibilityTree = {
+      filters: { secrets: { kind: 'denied' } },
+      nested: {},
+    }
+
+    const result = await filterReadableFields(
+      authorRow,
+      cfg.lists.Author.fields,
+      { session: null, context: makeContext() },
+      cfg,
+      0,
+      'Author',
+      emptyDeclaredOnlyTree(),
+      undefined,
+      toOneVisibility,
+    )
+
+    expect((result as Record<string, unknown>).secrets).toEqual([])
+  })
+
+  it('still forces a denied to-one relation to null (regression check, issue #974)', async () => {
+    const cfg = config()
+    const authorRow = { id: 'a1', name: 'A' } // `profile` absent — never fetched by Prisma
+    const toOneVisibility: ToOneAccessVisibilityTree = {
+      filters: { profile: { kind: 'denied' } },
+      nested: {},
+    }
+
+    const result = await filterReadableFields(
+      authorRow,
+      cfg.lists.Author.fields,
+      { session: null, context: makeContext() },
+      cfg,
+      0,
+      'Author',
+      emptyDeclaredOnlyTree(),
+      undefined,
+      toOneVisibility,
+    )
+
+    expect((result as Record<string, unknown>).profile).toBeNull()
+  })
+
+  it('forces a denied synthetic back-relation to [] — always to-many (#1082 interaction)', async () => {
+    const cfg = syntheticConfig()
+    const termRow = { id: 't1', name: 'Term 1' } // `from_Bill_term` absent — never fetched
+    const toOneVisibility: ToOneAccessVisibilityTree = {
+      filters: { from_Bill_term: { kind: 'denied' } },
+      nested: {},
+    }
+
+    const result = await filterReadableFields(
+      termRow,
+      cfg.lists.Term.fields,
+      { session: null, context: makeContext() },
+      cfg,
+      0,
+      'Term',
+      emptyDeclaredOnlyTree(),
+      undefined,
+      toOneVisibility,
+    )
+
+    expect((result as Record<string, unknown>).from_Bill_term).toEqual([])
+  })
+
+  it('omits a denied relation entirely when field-level read access also denies it, rather than forcing []', async () => {
+    const cfg = config()
+    const authorRow = { id: 'a1', name: 'A' }
+    const toOneVisibility: ToOneAccessVisibilityTree = {
+      filters: { hiddenSecrets: { kind: 'denied' } },
+      nested: {},
+    }
+
+    const result = await filterReadableFields(
+      authorRow,
+      cfg.lists.Author.fields,
+      { session: null, context: makeContext() },
+      cfg,
+      0,
+      'Author',
+      emptyDeclaredOnlyTree(),
+      undefined,
+      toOneVisibility,
+    )
+
+    expect('hiddenSecrets' in result).toBe(false)
+  })
+})

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,81 @@ 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
+}
+
+/**
+ * Enumerate every synthetic back-relation name a list-only `ref` elsewhere in
+ * the config synthesizes onto `parentListName` — the same relations
+ * `resolveSyntheticReverseRelation` resolves one at a time given a candidate
+ * key, returned here as the full set for a caller that instead needs "every
+ * relation this list carries" with no candidate to check (e.g. `_count:
+ * true`'s "count every relation" expansion in `access-filter.ts`, issue
+ * #1087 — a bare `_count: true` must include a synthetic back-relation's
+ * count exactly as it always has, not only a caller-named one).
+ */
+export function listSyntheticReverseRelationNames(
+  parentListName: string,
+  config: OpenSaasConfig,
+): string[] {
+  const names: string[] = []
+  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>
+      const refParts = rel.ref.split('.')
+      if (refParts.length !== 1 || refParts[0] !== parentListName) continue
+      names.push(getSyntheticFieldName(sourceListName, sourceFieldName))
+    }
+  }
+  return names
+}
+
 export async function checkAccess<T = Record<string, unknown>>(
   accessControl: AccessControl<T> | undefined,
   args: {
@@ -63,6 +140,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,62 @@ export class RelationFilterAccessDeniedError extends Error {
   }
 }
 
-function describeFieldAccessResult(result: unknown): string {
+/**
+ * Thrown when a caller-supplied `include` names a key that resolves to
+ * neither a declared relationship, a synthetic back-relation (a list-only
+ * `ref`'s ORM-required opposite field, which no list config declares — see
+ * `resolveSyntheticReverseRelation`), nor `_count`. Before this,
+ * `buildAccessScopedInclude`'s scoping walk passed an unrecognised key
+ * straight through unscoped — the one surface among `data`/`where`/`orderBy`/
+ * `include` that failed open rather than closed (issue #1082). `sudo` never
+ * reaches this: it skips `buildAccessScopedInclude` entirely (see
+ * `resolveReadInclude` in `context/index.ts`), matching every other
+ * access-control escape hatch.
+ */
+export class UndeclaredIncludeKeyError extends Error {
+  public listKey: string
+  public fieldKey: string
+
+  constructor(listKey: string, fieldKey: string) {
+    super(
+      `Cannot include "${listKey}.${fieldKey}" — it is not a field of this list. ` +
+        `Undeclared include keys are rejected, matching data/where/orderBy keys.`,
+    )
+    this.name = 'UndeclaredIncludeKeyError'
+    this.listKey = listKey
+    this.fieldKey = fieldKey
+  }
+}
+
+/**
+ * Thrown when a caller-supplied `_count.select` in `include` names a key that
+ * is not a countable to-many relation — undeclared, a scalar, a virtual, or a
+ * to-one relationship. Mirrors `UndeclaredIncludeKeyError`'s rejection for the
+ * ordinary `include` walk, for the one key shape that was allowlisted through
+ * unscoped rather than rejected (#1082's "Out of scope", closed here by
+ * #1087). A key naming a synthetic back-relation (#1082) is NOT rejected — it
+ * is a genuine countable to-many, resolved the same way the ordinary
+ * `include` walk resolves it. `sudo` never reaches this: it skips
+ * `buildAccessScopedInclude` entirely (see `resolveReadInclude` in
+ * `context/index.ts`), matching every other access-control escape hatch.
+ */
+export class UndeclaredCountKeyError extends Error {
+  public listKey: string
+  public fieldKey: string
+
+  constructor(listKey: string, fieldKey: string) {
+    super(
+      `Cannot count "${listKey}.${fieldKey}" — it is not a countable to-many relationship on this ` +
+        `list. A \`_count.select\` key must name a declared to-many relationship or a synthetic ` +
+        `back-relation, matching the ordinary include keys this list accepts.`,
+    )
+    this.name = 'UndeclaredCountKeyError'
+    this.listKey = listKey
+    this.fieldKey = fieldKey
+  }
+}
+
+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 +190,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 +200,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')
+  })
+})

package/src/access/field-access.ts

@@ -1,10 +1,12 @@
 import type { Session, AccessContext } from './types.js'
 import type { FieldAccess, FieldAccessControl } from './types.js'
+import type { OpenSaasConfig } from '../config/types.js'
 // `ValidationError` is referenced only inside function bodies (call-time), never
 // at module-evaluation time, so the field-access ⇄ hooks import cycle is safe
 // under ESM live bindings.
 import { ValidationError } from '../hooks/index.js'
 import { InvalidFieldAccessResultError } from './errors.js'
+import { resolveSyntheticReverseRelation } from './engine.js'
 
 /**
  * Marks a throw caused by touching {@link createPoisonedItem}'s `item`, as
@@ -196,6 +198,17 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
     item?: Record<string, unknown>
     context: AccessContext & { _isSudo?: boolean }
     inputData?: Record<string, unknown>
+    /**
+     * The list being written and the full config — used ONLY to recognise a
+     * synthetic reverse-relation key (`from_<List>_<field>`, #978) among the
+     * undeclared keys sudo would otherwise pass through unchecked. Both
+     * production call sites (the write pipeline, nested-operations) supply
+     * these; a direct unit test that omits them keeps the pre-#978 sudo
+     * behaviour of passing any undeclared key through, since it has no config
+     * to resolve a synthetic key against.
+     */
+    listName?: string
+    config?: OpenSaasConfig
   },
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
@@ -286,10 +299,29 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
     // declares (e.g. back-relations like `from_Enrolment_student`), so allowing
     // an undeclared key to pass through lets a non-sudo caller drive ungated
     // nested writes on undeclared back-relations. Mirror Keystone's
-    // GraphQL-schema behaviour and reject it. `sudo` is the single trusted
-    // bypass, so undeclared keys still pass through under sudo.
+    // GraphQL-schema behaviour and reject it.
     if (!fieldConfig) {
       if (isSudo) {
+        // #978 — sudo bypasses ACCESS CONTROL, not the hooks/validation a
+        // recognised relation is entitled to. A synthetic reverse-relation key
+        // (a list-only ref's back-relation) is handed to the caller unchanged
+        // so processNestedOperations can run its target list's full pipeline,
+        // exactly as it would for a declared relationship field. Any other
+        // undeclared key has no such route to hooks — passing it straight to
+        // Prisma is the same silent-bypass shape this issue closed for
+        // relations, so it is refused even under sudo. `listName`/`config`
+        // are omitted only by direct unit tests of this function, which keep
+        // the pre-#978 blanket sudo passthrough since they have no config to
+        // resolve a synthetic key against.
+        if (args.listName && args.config) {
+          const synthetic = resolveSyntheticReverseRelation(fieldName, args.listName, args.config)
+          if (!synthetic) {
+            throw new ValidationError([
+              `Cannot ${operation} "${fieldName}": it is not a field of this list. ` +
+                `Undeclared data keys are rejected, even under sudo.`,
+            ])
+          }
+        }
         filtered[fieldName] = value
         continue
       }