@opensaas/stack-core 0.40.0 → 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.ts

@@ -94,6 +94,34 @@ export function resolveSyntheticReverseRelation(
   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: {

package/src/access/errors.ts

@@ -99,6 +99,61 @@ export class RelationFilterAccessDeniedError extends Error {
   }
 }
 
+/**
+ * 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'

package/src/access/field-visibility.ts

@@ -1,14 +1,18 @@
 import type { Session, AccessContext } from './types.js'
-import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
-import { getRelatedListConfig } from './engine.js'
+import type { OpenSaasConfig, FieldConfig, ListConfig } from '../config/types.js'
+import { getRelatedListConfig, resolveSyntheticReverseRelation } from './engine.js'
 import { checkFieldAccess } from './field-access.js'
 import { RESOLVE_CHAIN_MAX_LENGTH } from './depth-limits.js'
 import { ResolveOutputCycleError } from './errors.js'
 import type { DeclaredOnlyTree } from './declared-dependencies.js'
 import { emptyDeclaredOnlyTree } from './declared-dependencies.js'
 import type { FieldSelectionScope } from '../query/index.js'
-import type { ToOneAccessVisibilityTree } from './access-filter.js'
-import { emptyToOneAccessVisibilityTree } from './access-filter.js'
+import type { ToOneAccessVisibilityTree, CountAccessDenialTree } from './access-filter.js'
+import {
+  emptyToOneAccessVisibilityTree,
+  isToOneRelationship,
+  emptyCountAccessDenialTree,
+} from './access-filter.js'
 // NOTE: `context/index.ts` imports `filterReadableFields` from this module
 // (via the `access/index.ts` barrel) — this is an intentional cyclic
 // dependency, the same shape and for the same reason as the one documented in
@@ -54,6 +58,26 @@ import { buildDbDelegate } from '../context/index.js'
  * before any field-level access check or `resolveOutput` hook runs, so the
  * rest of the pipeline sees exactly what a denied to-one read has always
  * meant elsewhere: `null`, never a thrown error.
+ *
+ * **A denied to-many relation is forced to `[]`, the same way (issue
+ * #1103).** `buildAccessScopedInclude` drops a to-many relation from
+ * `include` on the same outright `query` denial as a to-one one, and records
+ * the same `kind: 'denied'` entry for it. The key is therefore just as absent
+ * from `workingItem` as a denied to-one key, and the fix is the same fixup
+ * loop — it now forces the key present using the field's own declared
+ * arity: `null` for a to-one relation (unchanged), `[]` for a to-many one,
+ * rather than leaving a to-many key silently missing where the fragment
+ * API's `ResultOf` type (`query/index.ts`) promises an array.
+ *
+ * **`_count` denial injection (issue #1087).** A caller-supplied `_count.select`
+ * key whose related list denies `query` access outright is omitted from the
+ * select `buildAccessScopedInclude` sends to Prisma — there is no way to ask
+ * Prisma for a guaranteed `0`, and no query is needed to know one (unlike the
+ * to-one existence check above). This module is where that becomes the
+ * caller-visible `0`: every key in a `CountAccessDenialTree` at this level is
+ * written into `filtered._count` as `0`, whether or not `_count` came back
+ * from the database at all — a count is a session-relative value, and `0` is
+ * what "no visible rows" means for it, never an absent key.
  */
 
 type ResolveOutputHookRuntime = (args: {
@@ -216,6 +240,10 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   // regardless of that relation's own arity, since a filtered to-one can sit
   // beneath a to-many hop.
   toOneVisibility: ToOneAccessVisibilityTree = emptyToOneAccessVisibilityTree(),
+  // `_count.select` keys denied outright at THIS level (issue #1087, see
+  // module doc above), and the same tree one level down for each nested
+  // relation whose own nested include named a further `_count`.
+  countDenials: CountAccessDenialTree = emptyCountAccessDenialTree(),
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
@@ -279,25 +307,49 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
     // cap used to let a relation be scoped correctly at the DB level while
     // still returning with unfiltered fields past this function's own,
     // separately-tracked limit (issue #830).
+    const isDeclaredRelationshipField =
+      fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && !!fieldConfig.ref
+    // A synthetic back-relation (#1082) — no declared field of its own on
+    // this list, so resolved by name against the owning list's relationship
+    // field instead. `undefined` (not `fieldConfig`) is the signal it's
+    // worth trying: a declared-but-non-relationship field (e.g. a scalar or
+    // virtual) must fall through to the generic path below, unchanged.
+    const synthetic =
+      !isDeclaredRelationshipField && fieldConfig === undefined && config && listKey
+        ? resolveSyntheticReverseRelation(fieldName, listKey, config)
+        : null
+
     if (
       config &&
-      fieldConfig?.type === 'relationship' &&
-      'ref' in fieldConfig &&
-      fieldConfig.ref &&
+      (isDeclaredRelationshipField || synthetic) &&
       value !== null &&
       value !== undefined
     ) {
-      const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
-        ...args,
-        item: workingItem,
-      })
-
-      if (!canRead) {
-        accessDeniedKeys.add(fieldName)
-        continue
-      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+      let relatedConfig: { listName: string; listConfig: ListConfig<any> } | null = null
+
+      if (isDeclaredRelationshipField) {
+        const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
+          ...args,
+          item: workingItem,
+        })
+
+        if (!canRead) {
+          accessDeniedKeys.add(fieldName)
+          continue
+        }
 
-      const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
+        relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
+      } else if (synthetic) {
+        // No declared field means no field-level `read` gate of its own to
+        // check here — the owning list's OWN field-level access is enforced
+        // by the recursive `filterReadableFields` call below, exactly as it
+        // would be for a declared relationship's related rows.
+        relatedConfig = {
+          listName: synthetic.sourceListName,
+          listConfig: synthetic.sourceListConfig,
+        }
+      }
       // The declared-only tree for whatever THIS relation's own list computes,
       // e.g. a field on the related list that declares its own `needs`. Falls
       // back to an empty tree when this relation isn't declaration-related at
@@ -318,6 +370,11 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       // This key's OWN to-one existence check, if `fieldName` itself is a
       // filtered to-one relation (as opposed to one further down its tree).
       const toOneEntry = toOneVisibility.filters[fieldName]
+      // This relation's own denied `_count` keys, if `buildAccessScopedInclude`
+      // flagged any beneath it (issue #1087). Falls back to empty — the
+      // common case for a relation with no denied `_count` anywhere in its
+      // own nested include.
+      const nestedCountDenials = countDenials.nested[fieldName] ?? emptyCountAccessDenialTree()
 
       if (relatedConfig) {
         if (Array.isArray(value)) {
@@ -333,6 +390,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
                 nestedDeclaredOnly,
                 nestedSelection,
                 nestedToOneVisibility,
+                nestedCountDenials,
               ),
             ),
           )
@@ -352,6 +410,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
                 nestedDeclaredOnly,
                 nestedSelection,
                 nestedToOneVisibility,
+                nestedCountDenials,
               )
             : null
         }
@@ -381,12 +440,14 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
     }
   }
 
-  // To-one relations `buildAccessScopedInclude` denied outright (issue #974)
-  // were never asked of Prisma at all, so `fieldName` has no entry in
-  // `workingItem` and the loop above never visits it. Force it present as an
-  // explicit `null` here — matching what a denied single-record read means
-  // everywhere else in the context — rather than leaving the key silently
-  // absent.
+  // Relations `buildAccessScopedInclude` denied outright (to-one: issue #974,
+  // to-many: issue #1103) were never asked of Prisma at all, so `fieldName`
+  // has no entry in `workingItem` and the loop above never visits it. Force
+  // it present here — matching what a denied read means everywhere else in
+  // the context — rather than leaving the key silently absent: `null` for a
+  // to-one relation, `[]` for a to-many one. A synthetic back-relation
+  // (`fieldConfig` undefined — #1082) is always to-many, the same arity
+  // `buildAccessScopedInclude` assumes for it.
   for (const [fieldName, entry] of Object.entries(toOneVisibility.filters)) {
     if (entry.kind !== 'denied') continue
     if (fieldName in filtered || fieldName in workingItem) continue
@@ -403,7 +464,27 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       continue
     }
 
-    filtered[fieldName] = null
+    const isToMany = !fieldConfig || !isToOneRelationship(fieldConfig)
+    filtered[fieldName] = isToMany ? [] : null
+  }
+
+  // `_count.select` keys `buildAccessScopedInclude` denied outright (issue
+  // #1087) were omitted from the select sent to Prisma, so `_count` may be
+  // absent from `workingItem` entirely, or present but missing exactly these
+  // keys. Write each denied key in as `0` — matching what a denied count has
+  // always meant for the admin list view's own scoped counts — unless a
+  // fragment's own selection excluded `_count` altogether, in which case
+  // there is nothing to inject it into.
+  if (countDenials.keys.size > 0 && !(selection?.fields && !selection.fields.has('_count'))) {
+    const existingCount =
+      filtered._count && typeof filtered._count === 'object'
+        ? (filtered._count as Record<string, unknown>)
+        : {}
+    const mergedCount = { ...existingCount }
+    for (const key of countDenials.keys) {
+      mergedCount[key] = 0
+    }
+    filtered._count = mergedCount
   }
 
   // The item a virtual field's hook sees: stored columns and fetched

package/src/access/index.ts

@@ -20,6 +20,7 @@ export {
   isPrismaFilter,
   getRelatedListConfig,
   resolveSyntheticReverseRelation,
+  listSyntheticReverseRelationNames,
 } from './engine.js'
 export type { SyntheticReverseRelation } from './engine.js'
 // Canonical field-level access evaluation (shared by read and write paths).
@@ -42,13 +43,19 @@ export {
   resolveToOneAccessVisibility,
   emptyToOneAccessFilterTree,
   emptyToOneAccessVisibilityTree,
+  emptyCountAccessDenialTree,
 } from './access-filter.js'
 export type {
   ToOneAccessFilterTree,
   ToOneAccessFilterEntry,
   ToOneAccessVisibilityTree,
   ToOneVisibility,
+  CountAccessDenialTree,
 } from './access-filter.js'
+// Access-scoped to-many relationship counts (admin list view, issue #732)
+// and the shared per-relation resolver `_count` scoping (issue #1087) reuses.
+export { isToManyRelationshipField, resolveCountAccessEntryForList } from './relationship-count.js'
+export type { CountAccessEntry } from './relationship-count.js'
 // Phase 2 — Field Visibility (post-query field stripping + resolveOutput).
 export { filterReadableFields } from './field-visibility.js'
 // Declared Dependencies — folding `needs` into an include without widening
@@ -69,3 +76,7 @@ export { InvalidFieldAccessResultError } from './errors.js'
 export { InvalidCreateAccessResultError } from './errors.js'
 // Thrown when a relation filter's related list denies query access outright (#916).
 export { RelationFilterAccessDeniedError } from './errors.js'
+// Thrown when a caller `include` names a key that is neither declared, synthetic, nor `_count` (#1082).
+export { UndeclaredIncludeKeyError } from './errors.js'
+// Thrown when a caller `_count.select` names a key that is not a countable to-many relation (#1087).
+export { UndeclaredCountKeyError } from './errors.js'

package/src/access/multi-column-read-write.test.ts

@@ -2,7 +2,8 @@ import { describe, it, expect } from 'vitest'
 import { filterReadableFields } from './field-visibility.js'
 import { executeFieldResolveInputHooks, splitMultiColumnFields } from '../hooks/index.js'
 import type { FieldConfig } from '../config/types.js'
-import type { AccessContext, FieldAccess } from './types.js'
+import type { FieldAccess } from './types.js'
+import type { StackContext } from '../context/index.js'
 
 /**
  * Generic core wiring for multi-column fields (the contract storage
@@ -48,7 +49,7 @@ function multiColumnField(access?: FieldAccess): FieldConfig {
   } as unknown as FieldConfig
 }
 
-function makeContext(overrides: { isSudo?: boolean } = {}): AccessContext {
+function makeContext(overrides: { isSudo?: boolean } = {}): StackContext {
   return {
     session: null,
     _isSudo: overrides.isSudo ?? false,