@opensaas/stack-core 0.24.0 → 0.25.0

package/src/context/index.ts

@@ -5,6 +5,7 @@ import {
   mergeFilters,
   filterReadableFields,
   buildIncludeWithAccessControl,
+  mergeIncludeWithAccessControl,
 } from '../access/index.js'
 import { ValidationError, DatabaseError } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
@@ -65,6 +66,72 @@ function isSingletonList(listConfig: ListConfig<any>): boolean {
   return !!listConfig.isSingleton
 }
 
+/**
+ * Compute the set of single-field unique selectors a `findUnique` `where` may be
+ * keyed by, derived from what the list config exposes at runtime.
+ *
+ * The set is:
+ * - `id` — always a unique identifier on every list.
+ * - Any field declared `isIndexed: 'unique'` in the config (e.g. `text({ isIndexed: 'unique' })`).
+ * - For a `relationship` field declared `isIndexed: 'unique'`, the foreign-key
+ *   column name (`<field>Id`) — that is the column Prisma marks `@unique`, so the
+ *   unique `where` is keyed by `<field>Id`, not the relation field itself.
+ *
+ * Chosen rule (documented intentionally): the config does NOT expose compound
+ * (`@@unique`) keys at runtime — there is no list-level unique declaration in the
+ * config API — so we cannot validate compound `<Model>_<a>_<b>` selectors. We
+ * therefore enforce the tractable subset: `where` must contain EXACTLY ONE
+ * recognised single-field unique key and NO other keys. This rejects non-unique
+ * filters (the bug in #567) and rejects extra non-unique keys alongside a unique
+ * one, while never falsely rejecting a valid single-field unique lookup. If a
+ * project legitimately needs a compound-unique lookup, that path is not covered
+ * here and would need explicit config support; the safe escape hatch for any
+ * non-unique single-row lookup is `findFirst` (see #565).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+function getUniqueWhereKeys(listConfig: ListConfig<any>): Set<string> {
+  const keys = new Set<string>(['id'])
+
+  for (const [fieldKey, fieldConfig] of Object.entries(listConfig.fields)) {
+    if (!fieldConfig || typeof fieldConfig !== 'object') continue
+    if (!('isIndexed' in fieldConfig) || fieldConfig.isIndexed !== 'unique') continue
+
+    if (fieldConfig.type === 'relationship') {
+      // A unique relationship's `@unique` lives on the FK column `<field>Id`.
+      keys.add(`${fieldKey}Id`)
+    } else {
+      keys.add(fieldKey)
+    }
+  }
+
+  return keys
+}
+
+/**
+ * Enforce Keystone `findOne` semantics for `findUnique`: the caller-supplied
+ * `where` must be a valid unique selector. A non-unique `where` is a caller-shape
+ * error (not an access denial), so this THROWS rather than silently returning
+ * `null` — consistent with the fail-loud-on-misuse stance of PRD #581. A
+ * non-unique single-row lookup should use `findFirst` instead (see #565).
+ */
+function assertUniqueWhere(
+  where: Record<string, unknown> | undefined,
+  uniqueKeys: Set<string>,
+  listName: string,
+): void {
+  const keys = where ? Object.keys(where) : []
+
+  const message =
+    `findUnique on "${listName}" requires a unique \`where\` (a single unique key such as ` +
+    `${Array.from(uniqueKeys).join(', ')}). ` +
+    `Received: ${keys.length === 0 ? '{}' : `{ ${keys.join(', ')} }`}. ` +
+    `Use \`findFirst\` for a non-unique single-row lookup.`
+
+  if (keys.length !== 1 || !uniqueKeys.has(keys[0])) {
+    throw new ValidationError([message], {})
+  }
+}
+
 /**
  * Check if auto-create is enabled for a singleton list
  * Defaults to true if not explicitly set to false
@@ -236,40 +303,8 @@ export function getContext<
     _resolveOutputCounter: { depth: 0 },
   }
 
-  // Create access-controlled operations for each list
-  for (const [listName, listConfig] of Object.entries(config.lists)) {
-    const dbKey = getDbKey(listName)
-
-    // Create base operations
-    const createOp = createCreate(listName, listConfig, prisma, context, config)
-    const findManyOp = createFindMany(listName, listConfig, prisma, context, config)
-    const updateOp = createUpdate(listName, listConfig, prisma, context, config)
-    const operations: Record<string, unknown> = {
-      findUnique: createFindUnique(listName, listConfig, prisma, context, config),
-      findMany: findManyOp,
-      create: createOp,
-      update: updateOp,
-      delete: createDelete(listName, listConfig, prisma, context, config),
-      count: createCount(listName, listConfig, prisma, context),
-      createMany: createCreateMany(listName, listConfig, prisma, context, config, createOp),
-      updateMany: createUpdateMany(
-        listName,
-        listConfig,
-        prisma,
-        context,
-        config,
-        findManyOp,
-        updateOp,
-      ),
-    }
-
-    // Add get() method for singleton lists
-    if (isSingletonList(listConfig)) {
-      operations.get = createGet(listName, listConfig, prisma, context, config, createOp)
-    }
-
-    db[dbKey] = operations
-  }
+  // Create access-controlled operations for each list, populating `db` in place.
+  populateDbDelegate(db, config, prisma, context)
 
   // Execute plugin runtime functions and populate context.plugins
   // Use _plugins (sorted by dependencies) if available, otherwise fall back to plugins array
@@ -392,6 +427,74 @@ export function getContext<
   }
 }
 
+/**
+ * Populate `target` with the access-controlled CRUD operations for every list,
+ * each bound to `prisma` and `context`. Used both by {@link getContext} (at
+ * request setup) and by the Write Pipeline to rebuild a `db` delegate against a
+ * transaction client (ADR-0010), so a hook's `context.db` write participates in
+ * the same transaction.
+ *
+ * The operations capture `prisma` at construction, so rebinding to a different
+ * client (e.g. a transaction `tx`) requires rebuilding the delegate — which is
+ * exactly what this function enables.
+ */
+export function populateDbDelegate<TPrisma extends PrismaClientLike>(
+  target: Record<string, unknown>,
+  config: OpenSaasConfig,
+  prisma: TPrisma,
+  context: AccessContext<TPrisma>,
+): void {
+  for (const [listName, listConfig] of Object.entries(config.lists)) {
+    const dbKey = getDbKey(listName)
+
+    // Create base operations
+    const createOp = createCreate(listName, listConfig, prisma, context, config)
+    const findManyOp = createFindMany(listName, listConfig, prisma, context, config)
+    const updateOp = createUpdate(listName, listConfig, prisma, context, config)
+    const operations: Record<string, unknown> = {
+      findUnique: createFindUnique(listName, listConfig, prisma, context, config),
+      findMany: findManyOp,
+      findFirst: createFindFirst(findManyOp),
+      create: createOp,
+      update: updateOp,
+      delete: createDelete(listName, listConfig, prisma, context, config),
+      count: createCount(listName, listConfig, prisma, context),
+      createMany: createCreateMany(listName, listConfig, prisma, context, config, createOp),
+      updateMany: createUpdateMany(
+        listName,
+        listConfig,
+        prisma,
+        context,
+        config,
+        findManyOp,
+        updateOp,
+      ),
+    }
+
+    // Add get() method for singleton lists
+    if (isSingletonList(listConfig)) {
+      operations.get = createGet(listName, listConfig, prisma, context, config, createOp)
+    }
+
+    target[dbKey] = operations
+  }
+}
+
+/**
+ * Build a fresh access-controlled `db` delegate bound to `prisma` and `context`.
+ * Convenience wrapper over {@link populateDbDelegate} returning a new object,
+ * used by the Write Pipeline to rebind `db` to a transaction client.
+ */
+export function buildDbDelegate<TPrisma extends PrismaClientLike>(
+  config: OpenSaasConfig,
+  prisma: TPrisma,
+  context: AccessContext<TPrisma>,
+): AccessControlledDB<TPrisma> {
+  const db: Record<string, unknown> = {}
+  populateDbDelegate(db, config, prisma, context)
+  return db as AccessControlledDB<TPrisma>
+}
+
 /**
  * Create findUnique operation with access control
  */
@@ -404,7 +507,10 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
   config: OpenSaasConfig,
 ) {
   return async (args: {
-    where: { id: string }
+    // Accepts any unique selector at the delegate level (the generated
+    // `<List>FindUniqueArgs` type narrows `where` to Prisma's `WhereUniqueInput`).
+    // The runtime guard below rejects non-unique shapes.
+    where: Record<string, unknown>
     include?: Record<string, unknown>
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     query?: any
@@ -414,6 +520,15 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     // `select` is a visible no-op: warn, then proceed with include/query narrowing.
     warnIfSelectIgnored(args, listName, 'findUnique')
 
+    // Enforce unique-`where` (Keystone `findOne` parity). This is a caller-shape
+    // check independent of access, so it runs first and THROWS on misuse — it is
+    // not an access denial and must not be masked as a silent `null`. The
+    // type-level constraint already lives on the generated delegate: the custom
+    // `<List>FindUniqueArgs` only Omits `select`/`include` from
+    // `Prisma.<List>FindUniqueArgs`, so its `where` stays Prisma's
+    // `<List>WhereUniqueInput` — this runtime guard backstops untyped callers.
+    assertUniqueWhere(args.where, getUniqueWhereKeys(listConfig), listName)
+
     // Check query access (skip if sudo mode)
     let where: Record<string, unknown> = args.where
     if (!context._isSudo) {
@@ -443,6 +558,10 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
 
     if (fragment) {
       include = buildInclude(fragment._fields) ?? undefined
+    } else if (context._isSudo) {
+      // Sudo bypasses access control entirely — the caller's include is trusted
+      // and used as-is (matching the prior behaviour); no per-relation filtering.
+      include = args.include
     } else {
       // Build include with access control filters
       const accessControlledInclude = await buildIncludeWithAccessControl(
@@ -453,7 +572,18 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
         },
         config,
       )
-      include = args.include || accessControlledInclude
+      // MERGE (not replace) a caller-supplied include with the access-controlled
+      // include: the caller selects WHICH relations to fetch, access control
+      // decides WHETHER and WITH WHAT filter (#566). A bare auto-include (no
+      // caller include) still uses the access-controlled include directly.
+      include = args.include
+        ? mergeIncludeWithAccessControl(
+            args.include,
+            accessControlledInclude,
+            listConfig.fields,
+            config,
+          )
+        : accessControlledInclude
     }
 
     // Execute query with optimized includes
@@ -551,6 +681,10 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     let include: Record<string, unknown> | undefined
     if (fragment) {
       include = buildInclude(fragment._fields) ?? undefined
+    } else if (context._isSudo) {
+      // Sudo bypasses access control entirely — the caller's include is trusted
+      // and used as-is (matching the prior behaviour); no per-relation filtering.
+      include = args?.include
     } else {
       // Build include with access control filters
       const accessControlledInclude = await buildIncludeWithAccessControl(
@@ -561,7 +695,18 @@ function createFindMany<TPrisma extends PrismaClientLike>(
         },
         config,
       )
-      include = args?.include || accessControlledInclude
+      // MERGE (not replace) a caller-supplied include with the access-controlled
+      // include: the caller selects WHICH relations to fetch, access control
+      // decides WHETHER and WITH WHAT filter (#566). A bare auto-include (no
+      // caller include) still uses the access-controlled include directly.
+      include = args?.include
+        ? mergeIncludeWithAccessControl(
+            args.include,
+            accessControlledInclude,
+            listConfig.fields,
+            config,
+          )
+        : accessControlledInclude
     }
 
     // Execute query with optimized includes
@@ -603,6 +748,31 @@ function createFindMany<TPrisma extends PrismaClientLike>(
   }
 }
 
+/**
+ * Create findFirst operation with access control.
+ *
+ * findFirst is sugar over the access-controlled findMany: it runs the exact same
+ * query-access checks and access-controlled include building as findMany, then
+ * returns the first matching row (or null when nothing matches). This introduces
+ * no new access surface — it inherits findMany's silent-failure contract (an
+ * access-denied query yields `[]`, which becomes `null` here).
+ */
+function createFindFirst(findManyOp: ReturnType<typeof createFindMany>) {
+  return async (args?: {
+    where?: Record<string, unknown>
+    orderBy?: Record<string, 'asc' | 'desc'> | Array<Record<string, 'asc' | 'desc'>>
+    skip?: number
+    include?: Record<string, unknown>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    query?: any
+    // `select` is not honoured — accepted only so the no-op can be made visible.
+    select?: Record<string, unknown>
+  }) => {
+    const result = await findManyOp({ ...args, take: 1 })
+    return result[0] ?? null
+  }
+}
+
 /**
  * Create create operation with access control and hooks
  */