@opensaas/stack-core 0.24.0 → 0.26.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
@@ -163,6 +230,91 @@ function parsePrismaError(error: unknown, listConfig: ListConfig<any>): Error {
   return new Error('An unknown error occurred')
 }
 
+/**
+ * Database transaction isolation levels.
+ *
+ * Mirrors Prisma's `TransactionIsolationLevel`. The level passed to
+ * {@link StackContext.transaction} is forwarded to the underlying interactive
+ * transaction; provider support varies (e.g. `Serializable` is supported by
+ * PostgreSQL — required for the concurrency-sensitive capacity-gate pattern).
+ */
+export type TransactionIsolationLevel =
+  | 'ReadUncommitted'
+  | 'ReadCommitted'
+  | 'RepeatableRead'
+  | 'Serializable'
+  | 'Snapshot'
+
+/**
+ * Options for {@link StackContext.transaction}, forwarded verbatim to the
+ * underlying Prisma interactive transaction.
+ */
+export interface TransactionOptions {
+  /** Max ms to wait to acquire a transaction from the pool. */
+  maxWait?: number
+  /** Max ms the interactive transaction may run before timing out. */
+  timeout?: number
+  /** Isolation level for the transaction (e.g. `'Serializable'`). */
+  isolationLevel?: TransactionIsolationLevel
+}
+
+/**
+ * Minimal shape of a Prisma client that can open an interactive transaction.
+ * A Prisma transaction client (the `tx` handed to the callback) intentionally
+ * does NOT expose `$transaction`, which is how nested writes detect they are
+ * already inside a transaction and join it rather than opening another.
+ */
+interface TransactionCapable<TPrisma> {
+  $transaction?: (
+    fn: (tx: TPrisma) => Promise<unknown>,
+    options?: TransactionOptions,
+  ) => Promise<unknown>
+}
+
+/**
+ * The access-controlled context returned by {@link getContext}.
+ *
+ * Exposes the secured `db` delegate plus the session, raw `prisma`, storage,
+ * plugin services, the generic `serverAction` handler, `sudo()` (bypasses access
+ * control but still runs hooks), and `transaction()` (interactive, hook-firing
+ * transaction). All access-checked operations run their list/field hooks.
+ */
+export interface StackContext<TPrisma extends PrismaClientLike = PrismaClientLike> {
+  db: AccessControlledDB<TPrisma>
+  session: Session | null
+  prisma: TPrisma
+  storage: StorageUtils
+  plugins: Record<string, unknown>
+  serverAction: (props: ServerActionProps) => Promise<unknown>
+  /**
+   * Run `fn` inside ONE interactive transaction. The `txContext` handed to `fn`
+   * is a full {@link StackContext} whose `db.*` operations are access-checked and
+   * hook-firing (identical to this context) but persist against the transaction
+   * client, so every write in the callback is atomic — a throw anywhere rolls the
+   * whole transaction back.
+   *
+   * `options` (notably `isolationLevel`) is forwarded to the underlying Prisma
+   * transaction. Serialization failures (e.g. Prisma `P2034`) propagate to the
+   * caller rather than being swallowed, so the caller can own a retry loop. If
+   * the client cannot open an interactive transaction (e.g. a plain mock, or we
+   * are already inside a transaction), `fn` runs directly against the current
+   * client with identical hook/access semantics.
+   *
+   * Caveat: plugin runtime services (`txContext.plugins`) stay bound to the
+   * top-level (non-transaction) client — they are shared services initialised
+   * once per request. Reads through a plugin service therefore won't see this
+   * transaction's uncommitted writes, and a plugin service that WRITES would
+   * escape the transaction and survive a rollback. Use `txContext.db` (not a
+   * plugin service) for writes that must be atomic with the transaction.
+   */
+  transaction: <T>(
+    fn: (txContext: StackContext<TPrisma>) => Promise<T>,
+    options?: TransactionOptions,
+  ) => Promise<T>
+  sudo: () => StackContext<TPrisma>
+  _isSudo: boolean
+}
+
 /**
  * Create an access-controlled context
  *
@@ -180,25 +332,10 @@ export function getContext<
   session: Session | null,
   storage?: StorageUtils,
   _isSudo: boolean = false,
-): {
-  db: AccessControlledDB<TPrisma>
-  session: Session | null
-  prisma: TPrisma
-  storage: StorageUtils
-  plugins: Record<string, unknown>
-  serverAction: (props: ServerActionProps) => Promise<unknown>
-  _isSudo: boolean
-  sudo: () => {
-    db: AccessControlledDB<TPrisma>
-    session: Session | null
-    prisma: TPrisma
-    storage: StorageUtils
-    plugins: Record<string, unknown>
-    serverAction: (props: ServerActionProps) => Promise<unknown>
-    sudo: () => unknown
-    _isSudo: boolean
-  }
-} {
+  // Internal: when rebuilding the context against a transaction client, reuse the
+  // already-initialised plugin services rather than re-running plugin runtimes.
+  _sharedPlugins?: Record<string, unknown>,
+): StackContext<TPrisma> {
   // Initialize db object - will be populated with access-controlled operations
   // Type is intentionally broad to allow dynamic model access
   const db: Record<string, unknown> = {}
@@ -231,56 +368,30 @@ export function getContext<
         )
       },
     },
-    plugins: {}, // Will be populated with plugin runtime services
+    // Reuse already-initialised plugin services when rebinding to a transaction
+    // client, otherwise start empty and populate via plugin runtimes below.
+    plugins: _sharedPlugins ?? {},
     _isSudo,
     _resolveOutputCounter: { depth: 0 },
   }
 
-  // Create access-controlled operations for each list
-  for (const [listName, listConfig] of Object.entries(config.lists)) {
-    const dbKey = getDbKey(listName)
+  // Create access-controlled operations for each list, populating `db` in place.
+  populateDbDelegate(db, config, prisma, context)
 
-    // 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
-  }
-
-  // Execute plugin runtime functions and populate context.plugins
+  // Execute plugin runtime functions and populate context.plugins.
+  // Skipped when reusing shared plugins (transaction rebind) so runtimes — and
+  // any side effects they carry — run exactly once per top-level context.
   // Use _plugins (sorted by dependencies) if available, otherwise fall back to plugins array
-  const pluginsToExecute = config._plugins || config.plugins || []
-  for (const plugin of pluginsToExecute) {
-    if (plugin.runtime) {
-      try {
-        context.plugins[plugin.name] = plugin.runtime(context)
-      } catch (error) {
-        console.error(`Error executing runtime for plugin "${plugin.name}":`, error)
-        // Continue with other plugins even if one fails
+  if (!_sharedPlugins) {
+    const pluginsToExecute = config._plugins || config.plugins || []
+    for (const plugin of pluginsToExecute) {
+      if (plugin.runtime) {
+        try {
+          context.plugins[plugin.name] = plugin.runtime(context)
+        } catch (error) {
+          console.error(`Error executing runtime for plugin "${plugin.name}":`, error)
+          // Continue with other plugins even if one fails
+        }
       }
     }
   }
@@ -376,11 +487,35 @@ export function getContext<
 
   // Sudo function - creates a new context that bypasses access control
   // but still executes all hooks and validation
-  function sudo() {
+  function sudo(): StackContext<TPrisma> {
     return getContext(config, prisma, session, context.storage, true)
   }
 
-  return {
+  // Interactive, hook-firing transaction (#614). Rebinds the access-controlled
+  // context to the transaction client so every `txContext.db.*` write runs its
+  // access checks + hooks but persists inside ONE transaction (atomic). The
+  // transaction `options` (e.g. `isolationLevel`) pass through to Prisma, and a
+  // serialization failure thrown inside the callback propagates to the caller
+  // for retry (it is never converted to a silent `null`).
+  function transaction<T>(
+    fn: (txContext: StackContext<TPrisma>) => Promise<T>,
+    options?: TransactionOptions,
+  ): Promise<T> {
+    const client = prisma as unknown as TransactionCapable<TPrisma>
+    if (typeof client.$transaction !== 'function') {
+      // No interactive transaction available — either a plain client/mock or we
+      // are already inside a transaction (a Prisma tx client exposes no
+      // `$transaction`). Run directly: hook/access semantics are identical and
+      // atomicity is provided by any enclosing transaction.
+      return fn(returned)
+    }
+    return client.$transaction(
+      (tx) => fn(getContext(config, tx, session, context.storage, _isSudo, context.plugins)),
+      options,
+    ) as Promise<T>
+  }
+
+  const returned: StackContext<TPrisma> = {
     db: db as AccessControlledDB<TPrisma>,
     session,
     prisma,
@@ -388,8 +523,78 @@ export function getContext<
     plugins: context.plugins,
     serverAction,
     sudo,
+    transaction,
     _isSudo,
   }
+  return returned
+}
+
+/**
+ * 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>
 }
 
 /**
@@ -404,7 +609,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 +622,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 +660,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 +674,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 +783,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 +797,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 +850,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
  */