@opensaas/stack-core 0.24.0 → 0.25.0

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

@@ -1,5 +1,25 @@
 import { describe, it, expect } from 'vitest'
 import { filterWritableFields } from './field-access.js'
+import { ValidationError } from '../hooks/index.js'
+
+// A non-sudo access context. The cast is localized to test setup (mirrors the
+// existing sudo-context casts in this file): the runtime AccessContext carries
+// Prisma plumbing the unit under test never touches.
+function nonSudoContext() {
+  return {
+    session: null,
+    _isSudo: false,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any
+}
+
+function sudoContext() {
+  return {
+    session: null,
+    _isSudo: true,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any
+}
 
 describe('filterWritableFields', () => {
   it('should filter out foreign key fields when their corresponding relationship field exists', async () => {
@@ -146,4 +166,239 @@ describe('filterWritableFields', () => {
     // authorId is a foreign key for author relationship, so it should be filtered
     expect(filtered).not.toHaveProperty('authorId')
   })
+
+  // ── #564: undeclared data keys must fail CLOSED (throw) for non-sudo writes ──
+
+  it('throws on an undeclared data key for a non-sudo create', async () => {
+    const fieldConfigs = { title: { type: 'text' } }
+    const data = {
+      title: 'Test',
+      // Not a declared field — e.g. a Prisma back-relation the config never
+      // exposed (`from_Enrolment_student`). Must be rejected, not passed through.
+      from_Enrolment_student: { disconnect: [{ id: 'e1' }] },
+    }
+
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'create', {
+        session: null,
+        context: nonSudoContext(),
+        inputData: data,
+      }),
+    ).rejects.toThrow(ValidationError)
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'create', {
+        session: null,
+        context: nonSudoContext(),
+        inputData: data,
+      }),
+    ).rejects.toThrow(/from_Enrolment_student/)
+  })
+
+  it('throws on an undeclared data key for a non-sudo update', async () => {
+    const fieldConfigs = { title: { type: 'text' } }
+    const data = {
+      title: 'Updated',
+      bogusKey: 'value',
+    }
+
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'update', {
+        session: null,
+        item: { id: 'post-1' },
+        context: nonSudoContext(),
+        inputData: data,
+      }),
+    ).rejects.toThrow(/bogusKey/)
+  })
+
+  it('passes undeclared data keys through under sudo (the single trusted bypass)', async () => {
+    const fieldConfigs = { title: { type: 'text' } }
+    const data = {
+      title: 'Test',
+      from_Enrolment_student: { disconnect: [{ id: 'e1' }] },
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: sudoContext(),
+      inputData: data,
+    })
+
+    expect(filtered).toHaveProperty('title', 'Test')
+    expect(filtered).toHaveProperty('from_Enrolment_student')
+  })
+
+  it('still skips system fields and relationship FK fields cleanly for a non-sudo write', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+      author: { type: 'relationship', many: false },
+    }
+    const data = {
+      id: 'post-1',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      title: 'Test',
+      authorId: 'user-1', // FK skipped, not rejected
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: nonSudoContext(),
+      inputData: data,
+    })
+
+    expect(filtered).not.toHaveProperty('id')
+    expect(filtered).not.toHaveProperty('createdAt')
+    expect(filtered).not.toHaveProperty('updatedAt')
+    expect(filtered).not.toHaveProperty('authorId')
+    expect(filtered).toHaveProperty('title', 'Test')
+  })
+
+  it('passes through raw per-part columns from a multi-column field whose write access ALLOWS (non-sudo)', async () => {
+    // Multi-column fields inject raw columns (e.g. m_url/m_size) that are not
+    // declared in fieldConfigs; they must not trip the undeclared-key reject.
+    // With no field-level access (allow), they pass through.
+    const fieldConfigs = {
+      media: {
+        type: 'image',
+        getColumnNames: (fieldName: string) => [`${fieldName}_url`, `${fieldName}_size`],
+      },
+    }
+    const data = {
+      media_url: 'https://x/y.jpg',
+      media_size: 99,
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: nonSudoContext(),
+      inputData: data,
+    })
+
+    expect(filtered).toHaveProperty('media_url', 'https://x/y.jpg')
+    expect(filtered).toHaveProperty('media_size', 99)
+  })
+
+  it('THROWS when raw split columns are supplied for a field whose write access is DENIED (non-sudo)', async () => {
+    // Security (#568): a non-sudo caller who supplies the raw per-part columns
+    // DIRECTLY must not bypass the owning field's write-access gate. The
+    // logical-key gate in the hooks layer never fires here (no `media` key), so
+    // this filter is the only enforcement point — it must throw.
+    const fieldConfigs = {
+      media: {
+        type: 'image',
+        access: { create: () => false, update: () => false },
+        getColumnNames: (fieldName: string) => [`${fieldName}_url`, `${fieldName}_size`],
+      },
+    }
+    const data = {
+      media_url: 'https://evil/x.jpg',
+      media_size: 1,
+    }
+
+    // Throws ValidationError, and the message names the owning field.
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'create', {
+        session: null,
+        context: nonSudoContext(),
+        inputData: data,
+      }),
+    ).rejects.toThrow(ValidationError)
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'update', {
+        session: null,
+        item: { id: 'item-1' },
+        context: nonSudoContext(),
+        inputData: data,
+      }),
+    ).rejects.toThrow(/media/)
+  })
+
+  it('passes raw split columns through under sudo regardless of denied owning-field access', async () => {
+    // sudo is the single trusted bypass; `checkFieldAccess` returns true under
+    // sudo, so even a would-be-denied multi-column field passes through.
+    const fieldConfigs = {
+      media: {
+        type: 'image',
+        access: { create: () => false, update: () => false },
+        getColumnNames: (fieldName: string) => [`${fieldName}_url`, `${fieldName}_size`],
+      },
+    }
+    const data = {
+      media_url: 'https://x/y.jpg',
+      media_size: 99,
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: sudoContext(),
+      inputData: data,
+    })
+
+    expect(filtered).toHaveProperty('media_url', 'https://x/y.jpg')
+    expect(filtered).toHaveProperty('media_size', 99)
+  })
+
+  // ── #568: field-access-denied keys must THROW, not be silently stripped ──────
+
+  it('throws when a declared field is denied by field-level access (non-sudo)', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+      status: {
+        type: 'text',
+        access: { update: () => false, create: () => false },
+      },
+    }
+    const data = { title: 'Test', status: 'published' }
+
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'update', {
+        session: null,
+        item: { id: 'post-1' },
+        context: nonSudoContext(),
+        inputData: data,
+      }),
+    ).rejects.toThrow(/status/)
+  })
+
+  it('does NOT throw on a would-be-denied field under sudo', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+      status: {
+        type: 'text',
+        access: { update: () => false, create: () => false },
+      },
+    }
+    const data = { title: 'Test', status: 'published' }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'update', {
+      session: null,
+      item: { id: 'post-1' },
+      context: sudoContext(),
+      inputData: data,
+    })
+
+    expect(filtered).toHaveProperty('title', 'Test')
+    expect(filtered).toHaveProperty('status', 'published')
+  })
+
+  it('passes a declared relationship field through to nested operations (non-sudo)', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+      author: { type: 'relationship', many: false },
+    }
+    const data = {
+      title: 'Test',
+      author: { connect: { id: 'user-1' } },
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: nonSudoContext(),
+      inputData: data,
+    })
+
+    expect(filtered).toHaveProperty('author')
+    expect(filtered.author).toEqual({ connect: { id: 'user-1' } })
+  })
 })

package/src/access/field-access.ts

@@ -1,5 +1,9 @@
 import type { Session, AccessContext } from './types.js'
 import type { FieldAccess } from './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'
 
 /**
  * Shared field-level access evaluation.
@@ -100,7 +104,14 @@ function matchesFilter(item: Record<string, unknown>, filter: Record<string, unk
  */
 export async function filterWritableFields<T extends Record<string, unknown>>(
   data: T,
-  fieldConfigs: Record<string, { access?: FieldAccess; type?: string }>,
+  fieldConfigs: Record<
+    string,
+    {
+      access?: FieldAccess
+      type?: string
+      getColumnNames?: (fieldName: string) => string[]
+    }
+  >,
   operation: 'create' | 'update',
   args: {
     session: Session | null
@@ -114,6 +125,23 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
   // Build a set of foreign key field names to exclude
   // Foreign keys should not be in the data when using Prisma's relation syntax
   const foreignKeyFields = new Set<string>()
+  // Map each raw per-part column name contributed by a multi-column field
+  // (e.g. storage image()/file() in Keystone-parity mode) back to its OWNING
+  // declared field. These columns are injected into the write payload by the
+  // field's `splitColumns` AFTER resolveInput and are intentionally NOT declared
+  // as their own entries in `fieldConfigs`, so without this map they would trip
+  // the #564 undeclared-key reject below.
+  //
+  // SECURITY (#568): a raw column must NOT be blanket-passed through. The hooks
+  // layer (`executeFieldResolveInputHooks`) only gates the owning field when the
+  // LOGICAL key (e.g. `media`) is present, because it iterates declared fields,
+  // not data keys. A non-sudo caller who supplies the raw columns DIRECTLY
+  // (`data: { media_url, media_size }`) never produces that logical key, so that
+  // gate never fires. We therefore gate each raw column HERE by its owning
+  // field's write access — denied (non-sudo) throws, allowed (or sudo) passes
+  // through — so the legitimate multi-column write path is preserved while the
+  // direct-raw-column bypass is closed.
+  const splitColumnOwners = new Map<string, { fieldName: string; access?: FieldAccess }>()
   for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
     if (fieldConfig.type === 'relationship') {
       // For non-many relationships, Prisma creates a foreign key field named `${fieldName}Id`
@@ -122,8 +150,15 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
         foreignKeyFields.add(`${fieldName}Id`)
       }
     }
+    if (typeof fieldConfig.getColumnNames === 'function') {
+      for (const column of fieldConfig.getColumnNames(fieldName)) {
+        splitColumnOwners.set(column, { fieldName, access: fieldConfig.access })
+      }
+    }
   }
 
+  const isSudo = args.context._isSudo === true
+
   for (const [fieldName, value] of Object.entries(data)) {
     const fieldConfig = fieldConfigs[fieldName]
 
@@ -144,15 +179,66 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
       continue
     }
 
-    // Check field access (checkFieldAccess already handles sudo mode)
-    const canWrite = await checkFieldAccess(fieldConfig?.access, operation, {
+    // Raw per-part columns produced by a multi-column field's `splitColumns`.
+    // They are undeclared by design, so they must not trip the #564 reject — but
+    // they must NOT be blanket-passed through either: gate each one by its
+    // OWNING field's write access (see the SECURITY note where the map is built).
+    // This is the real gate for callers who supply the raw columns directly,
+    // because the logical-key gate in `executeFieldResolveInputHooks` never fires
+    // for them. Denied (non-sudo) throws — same fail-loud behaviour as a denied
+    // declared field (#568); allowed (or sudo, via `checkFieldAccess`) passes
+    // through, preserving the legitimate multi-column write path.
+    const splitColumnOwner = splitColumnOwners.get(fieldName)
+    if (splitColumnOwner) {
+      const canWrite = await checkFieldAccess(splitColumnOwner.access, operation, {
+        ...args,
+        inputData: args.inputData,
+      })
+      if (!canWrite) {
+        throw new ValidationError([
+          `Cannot ${operation} "${splitColumnOwner.fieldName}" (via column "${fieldName}"): ` +
+            `field-level access denied.`,
+        ])
+      }
+      filtered[fieldName] = value
+      continue
+    }
+
+    // #564 — undeclared data keys must fail CLOSED.
+    // A key with no entry in `fieldConfigs` is not a field the list config
+    // exposes. The generated Prisma model has MORE fields than the config
+    // 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.
+    if (!fieldConfig) {
+      if (isSudo) {
+        filtered[fieldName] = value
+        continue
+      }
+      throw new ValidationError([
+        `Cannot ${operation} "${fieldName}": it is not a field of this list. ` +
+          `Undeclared data keys are rejected (use sudo to bypass).`,
+      ])
+    }
+
+    // #568 — fields denied by field-level access must THROW, not be silently
+    // dropped. Keystone threw a GraphQL access error for the same situation;
+    // silently stripping the field lets a write "succeed" while doing less than
+    // asked (and skips any hook side effects gated on that field).
+    // `checkFieldAccess` already returns `true` under sudo, so sudo writes never
+    // reach the throw below — no parallel sudo path is needed here.
+    const canWrite = await checkFieldAccess(fieldConfig.access, operation, {
       ...args,
       inputData: args.inputData,
     })
 
-    if (canWrite) {
-      filtered[fieldName] = value
+    if (!canWrite) {
+      throw new ValidationError([`Cannot ${operation} "${fieldName}": field-level access denied.`])
     }
+
+    filtered[fieldName] = value
   }
 
   return filtered as Partial<T>

package/src/access/index.ts

@@ -22,6 +22,6 @@ export {
 // Canonical field-level access evaluation (shared by read and write paths).
 export { checkFieldAccess, filterWritableFields } from './field-access.js'
 // Phase 1 — Access Filter (pre-query row/relation scoping).
-export { buildIncludeWithAccessControl } from './access-filter.js'
+export { buildIncludeWithAccessControl, mergeIncludeWithAccessControl } from './access-filter.js'
 // Phase 2 — Field Visibility (post-query field stripping + resolveOutput).
 export { filterReadableFields } from './field-visibility.js'

package/src/access/types.ts

@@ -110,6 +110,48 @@ export interface AugmentedFindMany<TOriginal extends (...args: any[]) => any> {
   (...args: Parameters<TOriginal>): ReturnType<TOriginal>
 }
 
+/**
+ * Extra query arguments accepted when a `query` Fragment is provided alongside
+ * `context.db.<list>.findFirst({ query: myFragment, ... })`.
+ */
+export type FindFirstQueryArgs = {
+  where?: Record<string, unknown>
+  orderBy?: Record<string, 'asc' | 'desc'> | Array<Record<string, 'asc' | 'desc'>>
+  skip?: number
+}
+
+/**
+ * Overloaded `findFirst` that accepts an optional `query` Fragment.
+ *
+ * `findFirst` is sugar over the access-controlled `findMany` (`take: 1`), so it
+ * applies the exact same query-access checks and access-controlled include
+ * building, then returns the first matching record or `null`.
+ *
+ * - **With `query`**: builds the Prisma `include` from the fragment, executes the
+ *   query, applies access control, and returns a record shaped to `ResultOf<fragment>`
+ *   or `null`.
+ * - **Without `query`**: behaves exactly like the original Prisma `findFirst`.
+ *
+ * @example
+ * ```ts
+ * const post = await context.db.post.findFirst({
+ *   where:   { published: true },
+ *   orderBy: { createdAt: 'desc' },
+ *   query:   postFragment,
+ * })
+ * // post: ResultOf<typeof postFragment> | null
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface AugmentedFindFirst<TOriginal extends (...args: any[]) => any> {
+  // Overload 1: with query fragment — return type narrows to ResultOf<fragment> | null
+  <TItem, TFields extends FieldSelection<TItem>>(
+    args: FindFirstQueryArgs & { query: Fragment<TItem, TFields> },
+  ): Promise<ResultOf<Fragment<TItem, TFields>> | null>
+  // Overload 2: original Prisma behaviour
+  (...args: Parameters<TOriginal>): ReturnType<TOriginal>
+}
+
 /**
  * Overloaded `findUnique` that accepts an optional `query` Fragment.
  *
@@ -149,6 +191,8 @@ export type AccessControlledDB<TPrisma extends PrismaClientLike> = {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     findUnique: any
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findFirst: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     findMany: any
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     create: any
@@ -161,6 +205,7 @@ export type AccessControlledDB<TPrisma extends PrismaClientLike> = {
   }
     ? {
         findUnique: AugmentedFindUnique<TPrisma[K]['findUnique']>
+        findFirst: AugmentedFindFirst<TPrisma[K]['findFirst']>
         findMany: AugmentedFindMany<TPrisma[K]['findMany']>
         create: TPrisma[K]['create']
         update: TPrisma[K]['update']