@opensaas/stack-core 0.40.0 → 0.42.0

package/src/context/index.ts

@@ -12,8 +12,13 @@ import {
   validateQueryFieldReadAccess,
   resolveToOneAccessVisibility,
   emptyToOneAccessFilterTree,
+  emptyCountAccessDenialTree,
+} from '../access/index.js'
+import type {
+  DeclaredOnlyTree,
+  ToOneAccessFilterTree,
+  CountAccessDenialTree,
 } from '../access/index.js'
-import type { DeclaredOnlyTree, ToOneAccessFilterTree } from '../access/index.js'
 import { ValidationError, DatabaseError } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
 import { uniqueConstraintOf } from '../lib/prisma-errors.js'
@@ -359,6 +364,15 @@ export interface StackContext<TPrisma extends PrismaClientLike = PrismaClientLik
    */
   withSession: (session: Session | null) => StackContext<TPrisma>
   _isSudo: boolean
+  /**
+   * @internal Present so a hook-bound `StackContext` (issue #1176) satisfies
+   * {@link AccessContext} and can be threaded through the same internal
+   * write-pipeline/access plumbing that a plain `AccessContext` is — see
+   * `_resolveOutputChain` on `AccessContext` for what this tracks.
+   */
+  _resolveOutputChain: readonly { listKey: string; fieldKey: string }[]
+  /** @internal See `_transactionOwner` on `AccessContext`. */
+  _transactionOwner?: TransactionRegistry
 }
 
 /**
@@ -406,6 +420,11 @@ export function getContext<
   // owner's callback body, carry the deferral registry so writes reached
   // through this context join it instead of firing afterTransaction eagerly.
   _transactionOwner?: TransactionRegistry,
+  // Internal (ADR-0023, issue #1176): when rebuilding the context for a
+  // hook-bound write (or a derived `sudo()`/`withSession()` of one), carry the
+  // resolve chain forward so a write issued from inside a `resolveOutput` hook
+  // keeps that hook's cycle-guard chain instead of resetting to empty.
+  _resolveOutputChain?: readonly { listKey: string; fieldKey: string }[],
 ): StackContext<TPrisma> {
   // Broad type to allow dynamic model access; populated by populateDbDelegate below.
   const db: Record<string, unknown> = {}
@@ -440,7 +459,7 @@ export function getContext<
     // client, otherwise start empty and populate via plugin runtimes below.
     plugins: _sharedPlugins ?? {},
     _isSudo,
-    _resolveOutputChain: [],
+    _resolveOutputChain: _resolveOutputChain ?? [],
     _transactionOwner,
   }
 
@@ -791,6 +810,10 @@ export function getContext<
       // ADR-0028: a sudo write issued from inside an owned transaction (e.g.
       // `tx.sudo().db.x.create()`) must still defer to that owner.
       context._transactionOwner,
+      // #1176: carry the resolve chain forward so a `context.sudo()` called
+      // from inside a `resolveOutput` hook keeps that hook's cycle-guard
+      // chain (ADR-0023) rather than resetting to empty.
+      context._resolveOutputChain,
     )
   }
 
@@ -807,6 +830,8 @@ export function getContext<
       // ADR-0028: a write issued from inside an owned transaction (e.g.
       // `tx.withSession(s).db.x.create()`) must still defer to that owner.
       context._transactionOwner,
+      // #1176: see the identical comment in `sudo()` above.
+      context._resolveOutputChain,
     )
   }
 
@@ -847,6 +872,7 @@ export function getContext<
               _isSudo,
               context.plugins,
               registry,
+              context._resolveOutputChain,
             ),
           )
         : (client.$transaction(
@@ -860,6 +886,7 @@ export function getContext<
                   _isSudo,
                   context.plugins,
                   registry,
+                  context._resolveOutputChain,
                 ),
               ),
             options,
@@ -879,6 +906,12 @@ export function getContext<
     withSession,
     transaction,
     _isSudo,
+    // #1176: carried so a `StackContext` structurally satisfies `AccessContext`
+    // and can be handed, unchanged, to the internal write-pipeline/hook
+    // plumbing that a plain `AccessContext` was built for — see
+    // `bindContextToTransaction` in `write-pipeline.ts`.
+    _resolveOutputChain: context._resolveOutputChain,
+    _transactionOwner: context._transactionOwner,
   }
   return returned
 }
@@ -955,11 +988,12 @@ export function buildDbDelegate<TPrisma extends PrismaClientLike>(
  * caller include / bare (ADR-0024) — while folding declared dependencies
  * (`needs`, ADR-0025) into whichever of those the read is already using.
  *
- * A fragment's own `include` and a sudo caller's `include` are folded and
- * used as-is, matching their existing (unmerged) treatment. A non-sudo
- * caller include is folded and then scoped by `buildAccessScopedInclude`
- * (ADR-0026) — caller-directed, so a relation named nowhere in the folded
- * tree never has its list's `query` access evaluated at all. A bare read
+ * A non-sudo fragment's own `include` and a non-sudo caller's `include` are
+ * both folded and then scoped by `buildAccessScopedInclude` (ADR-0026) —
+ * caller-directed, so a relation named nowhere in the folded tree never has
+ * its list's `query` access evaluated at all (issue #1088: a fragment read
+ * used to skip this walk entirely). A sudo caller's `include` (fragment or
+ * not) is folded and used as-is, unscoped — sudo is unaffected. A bare read
  * stays on the exact ADR-0024 path — `include: undefined`, no related
  * `query` access evaluated — unless folding actually added something, which
  * only happens when a field on this list declares `needs`.
@@ -973,9 +1007,10 @@ export function buildDbDelegate<TPrisma extends PrismaClientLike>(
  *
  * Also returns `toOneAccessFilters` — the to-one relations `buildAccessScopedInclude`
  * flagged as needing a post-query existence check rather than a Prisma-side
- * `where` (issue #974). Only the non-sudo caller-include path can produce a
- * non-empty tree: it's the only path that evaluates a related list's `query`
- * access at all. The fragment and sudo paths always return an empty tree.
+ * `where` (issue #974). Only a non-sudo fragment or caller-include read can
+ * produce a non-empty tree: those are the only paths that evaluate a related
+ * list's `query` access at all. A sudo read and a bare read always return an
+ * empty tree.
  */
 async function resolveReadInclude(
   callerInclude: Record<string, unknown> | undefined,
@@ -990,6 +1025,7 @@ async function resolveReadInclude(
   declaredOnly: DeclaredOnlyTree
   selection: FieldSelectionScope | undefined
   toOneAccessFilters: ToOneAccessFilterTree
+  countDenials: CountAccessDenialTree
 }> {
   if (fragmentFields !== undefined) {
     const fragmentInclude = buildInclude(fragmentFields) ?? undefined
@@ -1002,27 +1038,66 @@ async function resolveReadInclude(
       [listName],
       selection,
     )
-    return { ...folded, selection, toOneAccessFilters: emptyToOneAccessFilterTree() }
+
+    if (context._isSudo || !folded.include) {
+      return {
+        ...folded,
+        selection,
+        toOneAccessFilters: emptyToOneAccessFilterTree(),
+        countDenials: emptyCountAccessDenialTree(),
+      }
+    }
+
+    const { include, toOneAccessFilters, countDenials } = await buildAccessScopedInclude(
+      folded.include,
+      listConfig.fields,
+      { session: context.session, context },
+      config,
+      listName,
+    )
+    return {
+      include,
+      declaredOnly: folded.declaredOnly,
+      selection,
+      toOneAccessFilters,
+      countDenials,
+    }
   }
 
   if (context._isSudo) {
     const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
-    return { ...folded, selection: undefined, toOneAccessFilters: emptyToOneAccessFilterTree() }
+    return {
+      ...folded,
+      selection: undefined,
+      toOneAccessFilters: emptyToOneAccessFilterTree(),
+      countDenials: emptyCountAccessDenialTree(),
+    }
   }
 
   const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
   if (!folded.include) {
-    return { ...folded, selection: undefined, toOneAccessFilters: emptyToOneAccessFilterTree() }
+    return {
+      ...folded,
+      selection: undefined,
+      toOneAccessFilters: emptyToOneAccessFilterTree(),
+      countDenials: emptyCountAccessDenialTree(),
+    }
   }
 
-  const { include, toOneAccessFilters } = await buildAccessScopedInclude(
+  const { include, toOneAccessFilters, countDenials } = await buildAccessScopedInclude(
     folded.include,
     listConfig.fields,
     { session: context.session, context },
     config,
     listName,
   )
-  return { include, declaredOnly: folded.declaredOnly, selection: undefined, toOneAccessFilters }
+  return {
+    include,
+    declaredOnly: folded.declaredOnly,
+    selection: undefined,
+    toOneAccessFilters,
+    countDenials,
+  }
 }
 
 function createFindUnique<TPrisma extends PrismaClientLike>(
@@ -1079,14 +1154,15 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection, toOneAccessFilters } = await resolveReadInclude(
-      args.include,
-      fragment ? fragment._fields : undefined,
-      listName,
-      listConfig,
-      context,
-      config,
-    )
+    let { include, declaredOnly, selection, toOneAccessFilters, countDenials } =
+      await resolveReadInclude(
+        args.include,
+        fragment ? fragment._fields : undefined,
+        listName,
+        listConfig,
+        context,
+        config,
+      )
 
     // Virtual fields have no database column. Whichever path produced
     // `include` (fragment, access-controlled merge, or sudo passthrough), a
@@ -1131,6 +1207,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       declaredOnly,
       selection,
       toOneVisibility,
+      countDenials,
     )
 
     if (fragment) {
@@ -1240,14 +1317,15 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection, toOneAccessFilters } = await resolveReadInclude(
-      args?.include,
-      fragment ? fragment._fields : undefined,
-      listName,
-      listConfig,
-      context,
-      config,
-    )
+    let { include, declaredOnly, selection, toOneAccessFilters, countDenials } =
+      await resolveReadInclude(
+        args?.include,
+        fragment ? fragment._fields : undefined,
+        listName,
+        listConfig,
+        context,
+        config,
+      )
 
     // Strips virtual keys from `include` before the Prisma call — see the
     // `createFindUnique` comment above for why (#628, ADR-0027).
@@ -1289,6 +1367,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
           declaredOnly,
           selection,
           toOneVisibility,
+          countDenials,
         ),
       ),
     )
@@ -1573,14 +1652,15 @@ function createGet<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection, toOneAccessFilters } = await resolveReadInclude(
-      args?.include,
-      fragment ? fragment._fields : undefined,
-      listName,
-      listConfig,
-      context,
-      config,
-    )
+    let { include, declaredOnly, selection, toOneAccessFilters, countDenials } =
+      await resolveReadInclude(
+        args?.include,
+        fragment ? fragment._fields : undefined,
+        listName,
+        listConfig,
+        context,
+        config,
+      )
 
     // Virtual fields have no database column and must never reach Prisma (#628).
     include = stripVirtualFieldsFromInclude(include, listConfig.fields, config)
@@ -1611,6 +1691,7 @@ function createGet<TPrisma extends PrismaClientLike>(
         declaredOnly,
         selection,
         toOneVisibility,
+        countDenials,
       )
       if (fragment) {
         return pickFields(filtered, fragment._fields)

package/src/context/nested-operations.ts

@@ -1,10 +1,12 @@
 import type { OpenSaasConfig, ListConfig, FieldConfig } from '../config/types.js'
-import type { AccessContext, FieldAccess } from '../access/types.js'
+import type { FieldAccess, PrismaFilter } from '../access/types.js'
+import type { StackContext } from './index.js'
 import {
   checkAccess,
   checkCreateAccess,
   filterWritableFields,
   getRelatedListConfig,
+  mergeFilters,
   resolveSyntheticReverseRelation,
 } from '../access/index.js'
 import { checkFieldAccess } from '../access/field-access.js'
@@ -199,7 +201,7 @@ async function processNestedCreate(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   config: OpenSaasConfig,
   prisma: unknown,
   afterTasks: AfterTask[],
@@ -391,7 +393,7 @@ async function verifyConnectReachable(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   prisma: unknown,
   owningFieldAccess: FieldAccess | undefined,
   enclosingOperation: 'create' | 'update',
@@ -456,7 +458,7 @@ async function processNestedConnect(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   prisma: unknown,
   owningFieldAccess: FieldAccess | undefined,
   enclosingOperation: 'create' | 'update',
@@ -484,6 +486,28 @@ async function processNestedConnect(
   return connections
 }
 
+/**
+ * Re-check a nested update/delete access result against the target row,
+ * mirroring the Write Pipeline's `resolveExistingTarget` (#1081): `false`
+ * denies, `true` allows outright (the row's existence is already established
+ * by the caller's own `findUnique`), and a returned PrismaFilter must
+ * additionally match the row, re-checked in the DATABASE via
+ * `findFirst(mergeFilters(where, accessResult))` rather than in memory — the
+ * same requirement `connect`'s reachability check already applies (#578), so
+ * nested-relation predicates and boolean combinators are honoured correctly.
+ */
+async function isExistingTargetAccessible(
+  model: { findFirst: (args: { where: Record<string, unknown> }) => Promise<unknown> },
+  where: Record<string, unknown>,
+  accessResult: boolean | PrismaFilter,
+): Promise<boolean> {
+  if (accessResult === false) return false
+  if (accessResult === true) return true
+
+  const matchesFilter = await model.findFirst({ where: mergeFilters(where, accessResult) ?? {} })
+  return matchesFilter !== null
+}
+
 /**
  * Process nested update operations.
  *
@@ -497,7 +521,7 @@ async function processNestedUpdate(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   config: OpenSaasConfig,
   prisma: unknown,
   afterTasks: AfterTask[],
@@ -529,7 +553,7 @@ async function processNestedUpdate(
           context,
         })
 
-        if (accessResult === false) {
+        if (!(await isExistingTargetAccessible(model, where, accessResult))) {
           throw new Error('Access denied: Cannot update related item')
         }
       }
@@ -693,7 +717,7 @@ async function processNestedDelete(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   prisma: unknown,
   afterTasks: AfterTask[],
 ): Promise<Record<string, unknown> | Array<Record<string, unknown>> | boolean> {
@@ -726,7 +750,7 @@ async function processNestedDelete(
           context,
         })
 
-        if (accessResult === false) {
+        if (!(await isExistingTargetAccessible(model, where, accessResult))) {
           throw new Error('Access denied: Cannot delete related item')
         }
       }
@@ -801,7 +825,7 @@ async function processNestedConnectOrCreate(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   config: OpenSaasConfig,
   prisma: unknown,
   afterTasks: AfterTask[],
@@ -922,7 +946,7 @@ interface NestedOpHandlerArgs {
   enclosingItem: Record<string, unknown> | undefined
   /** The enclosing write's input data, passed to the owning-field gate for the same reason as `enclosingItem`. */
   enclosingInputData: Record<string, unknown> | undefined
-  context: AccessContext
+  context: StackContext
   config: OpenSaasConfig
   /** Prisma client used for dynamic model access during access checks. */
   prisma: unknown
@@ -1190,7 +1214,7 @@ export async function processNestedOperations(
   data: Record<string, unknown>,
   fieldConfigs: Record<string, FieldConfig>,
   config: OpenSaasConfig,
-  context: AccessContext & { prisma: unknown },
+  context: StackContext & { prisma: unknown },
   operation: 'create' | 'update',
   parentListName: string,
   parentOriginalItem: Record<string, unknown> | undefined,

package/src/context/write-pipeline.ts

@@ -23,10 +23,11 @@ import { enumerateInvolvedLists, runWithTransactionBoundary } from './transactio
 import { TransactionRegistry } from '../access/transaction-registry.js'
 import { getDbKey } from '../lib/case-utils.js'
 // NOTE: `index.ts` imports from this module too — this is an intentional cyclic
-// dependency. It is safe because `buildDbDelegate` is only INVOKED at write
-// time (never during module evaluation), so by the time it runs the export is
-// fully initialised.
-import { buildDbDelegate } from './index.js'
+// dependency. It is safe because `getContext` is only INVOKED at write time
+// (never during module evaluation), so by the time it runs the export is fully
+// initialised.
+import { getContext } from './index.js'
+import type { StackContext } from './index.js'
 
 /**
  * Write Pipeline — runs the canonical, secured write sequence for one
@@ -166,6 +167,22 @@ export interface WritePipelineArgs<TPrisma extends PrismaClientLike> {
   preResolvedTarget?: TargetResolution
 }
 
+/**
+ * {@link WritePipelineArgs} narrowed to the in-transaction phase: `context` is
+ * the full {@link StackContext} `bindContextToTransaction` rebuilds (issue
+ * #1176), not the plain {@link AccessContext} the pre-transaction gate and the
+ * transaction-boundary hooks use. `StackContext` is a structural superset of
+ * `AccessContext` (it carries `_resolveOutputChain`/`_transactionOwner` too),
+ * so nothing downstream of {@link runWriteInTransaction} that only needs
+ * `AccessContext` requires any change.
+ */
+type WriteInTransactionArgs<TPrisma extends PrismaClientLike> = Omit<
+  WritePipelineArgs<TPrisma>,
+  'context'
+> & {
+  context: StackContext<TPrisma>
+}
+
 /**
  * Run the canonical secured write sequence once. Phase order matches the
  * "Write Pipeline" glossary entry in CONTEXT.md.
@@ -242,41 +259,44 @@ export async function runWritePipeline<TPrisma extends PrismaClientLike>(
 }
 
 /**
- * Build an {@link AccessContext} whose `db`/`prisma` target the transaction
- * client `tx`, so a `context.db` write a hook performs runs inside — and rolls
- * back with — this write's transaction (ADR-0010).
+ * Build the full {@link StackContext} a hook's `context` is (issue #1176):
+ * bound to the transaction client `tx`, so a `context.db` write a hook
+ * performs runs inside — and rolls back with — this write's transaction
+ * (ADR-0010), and carrying `sudo()`/`withSession()`/`transaction()` so a hook
+ * can reach an elevated or substituted read/write that stays on the SAME
+ * transaction client rather than escaping to the base one.
  *
- * The access-controlled `db` delegates capture their Prisma client at
- * construction, so swapping `context.prisma` alone would not rebind `db` — we
- * rebuild the delegates against `tx` via {@link buildDbDelegate}, reusing the
- * request context's `session`, `storage`, `plugins`, `_isSudo`, and
- * `_resolveOutputChain` as-is (so a write from inside a `resolveOutput` hook
- * keeps that hook's chain). Plugin runtimes are NOT re-executed.
+ * Goes through the same {@link getContext} factory `context.transaction()`
+ * already rebuilds through (ADR-0012), rather than hand-assembling a plain
+ * object literal — reusing the request context's `session`, `storage`,
+ * `_isSudo`, `plugins` (as `_sharedPlugins`, so plugin `runtime()` is NOT
+ * re-executed on the rebind), and `_resolveOutputChain` (so a write issued
+ * from inside a `resolveOutput` hook keeps that hook's cycle-guard chain,
+ * ADR-0023) as-is.
  *
  * `transactionOwner` (ADR-0028) is carried onto the rebuilt context so a hook's
- * own `context.db` write defers its transaction-boundary bracket to that owner
- * instead of firing eagerly.
+ * own `context.db` write — and any write reached through its `sudo()`/
+ * `withSession()` — defers its transaction-boundary bracket to that owner
+ * instead of firing eagerly; `context.transaction()` called from a hook joins
+ * this same owner rather than opening a nested transaction, for the same
+ * reason.
  */
 function bindContextToTransaction<TPrisma extends PrismaClientLike>(
   args: WritePipelineArgs<TPrisma>,
   tx: TPrisma,
   transactionOwner: TransactionRegistry | undefined,
-): AccessContext<TPrisma> {
+): StackContext<TPrisma> {
   const { context, config } = args
-  const txContext: AccessContext<TPrisma> = {
-    session: context.session,
-    prisma: tx,
-    db: context.db,
-    storage: context.storage,
-    plugins: context.plugins,
-    _isSudo: context._isSudo,
-    _resolveOutputChain: context._resolveOutputChain,
-    _transactionOwner: transactionOwner,
-  }
-  // Rebuild `db` against `tx`, referencing `txContext` itself so hooks reached
-  // through it see the transactional context.
-  txContext.db = buildDbDelegate(config, tx, txContext)
-  return txContext
+  return getContext(
+    config,
+    tx,
+    context.session,
+    context.storage,
+    context._isSudo,
+    context.plugins,
+    transactionOwner,
+    context._resolveOutputChain,
+  )
 }
 
 /**
@@ -286,7 +306,7 @@ function bindContextToTransaction<TPrisma extends PrismaClientLike>(
  * `runInTransaction` and rolls the transaction back.
  */
 async function runWriteInTransaction<TPrisma extends PrismaClientLike>(
-  args: WritePipelineArgs<TPrisma>,
+  args: WriteInTransactionArgs<TPrisma>,
 ): Promise<Record<string, unknown> | null> {
   const { listName, listConfig, prisma: tx, context, config, inputData, strategy } = args
   const { operation } = strategy
@@ -485,7 +505,7 @@ async function runDeletePath(args: {
   listName: string
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   listConfig: ListConfig<any>
-  context: AccessContext
+  context: StackContext
   originalItem: Record<string, unknown> | undefined
   model: PrismaModel
   strategy: WriteStrategy