@opensaas/stack-core 0.37.0 → 0.39.0

package/src/access/errors.ts

@@ -2,15 +2,19 @@ import { READ_INCLUDE_MAX_DEPTH } from './depth-limits.js'
 
 /**
  * Thrown when a caller-supplied `include` names a relation nested deeper than
- * the Access Filter can scope (see `READ_INCLUDE_MAX_DEPTH`). Deliberately
- * distinct from `ValidationError`: this is not bad user input, it is the
- * engine refusing to return data it cannot prove is row/field scoped. Code
- * that catches `ValidationError` to report form errors must not silently
- * swallow this.
+ * `READ_INCLUDE_MAX_DEPTH`. Deliberately distinct from `ValidationError`: this
+ * is not bad user input, it is the engine declining to serve a tree this
+ * expensive. Code that catches `ValidationError` to report form errors must
+ * not silently swallow this.
  *
- * Only an explicit caller selection past the depth cap triggers this — the
- * auto-include silently stopping at the cap (no caller `include` involved)
- * never throws. See ADR-0022 and issue #830.
+ * Only an explicit request naming something at or past the cap triggers this
+ * — a read that simply doesn't reach this deep never throws. Before
+ * ADR-0026 made the read pipeline caller-directed, this cap was the engine's
+ * last line of defense against returning a relation it could not prove was
+ * row/field scoped (ADR-0022, issue #830); a request naming anything at this
+ * depth is now scoped exactly like every other named relation; the cap
+ * exists solely to bound how deep a request may cost the engine to serve. See
+ * ADR-0026 and `docs/adr/0022-access-control-fails-closed-when-it-cannot-scope.md`.
  */
 export class AccessScopeDepthExceededError extends Error {
   public listKey: string
@@ -19,10 +23,10 @@ export class AccessScopeDepthExceededError extends Error {
 
   constructor(listKey: string, fieldKey: string, depth: number) {
     super(
-      `Cannot compute an access scope for "${listKey}.${fieldKey}" at include depth ${depth}: ` +
-        `this exceeds the Access Filter's maximum read-include depth (${READ_INCLUDE_MAX_DEPTH}). ` +
-        `A caller-supplied include this deep cannot be row- and field-scoped, so the read is denied ` +
-        `rather than returned unscoped. Restructure the query to fetch this relation separately.`,
+      `Cannot include "${listKey}.${fieldKey}" at include depth ${depth}: this exceeds the read ` +
+        `pipeline's maximum include depth (${READ_INCLUDE_MAX_DEPTH}). This is a cost limit, not an ` +
+        `inability to scope — the engine declines to serve a tree this deep rather than returning ` +
+        `it. Restructure the query to fetch this relation separately.`,
     )
     this.name = 'AccessScopeDepthExceededError'
     this.listKey = listKey
@@ -60,3 +64,84 @@ export class ResolveOutputCycleError extends Error {
     this.chain = chain
   }
 }
+
+/**
+ * Thrown when a relation filter in a caller's `where` (`some`/`every`/`none`/
+ * `is`/`isNot`) names a relationship whose related list denies operation-level
+ * `query` access outright (`=== false`). Deliberately a loud failure, not a
+ * silently narrowed `{ id: { in: [] } }` or a pass-through: ADR-0022 requires
+ * an engine that cannot compute a scope to deny, never pass through, and here
+ * the engine CAN compute the scope (denied) — passing that through as a
+ * silently-empty match would itself be a distinguishable signal for a caller
+ * probing which relations they may filter on. `include`'s equivalent case
+ * (`buildAccessScopedInclude`) drops the relation silently instead, because a
+ * `null`/missing key in a response is indistinguishable from "not requested";
+ * a `where` predicate has no such neutral outcome, so a relation filter on a
+ * fully denied relation is refused instead. `sudo` bypasses this check
+ * entirely, matching every other access-control escape hatch. See #916 and
+ * `docs/adr/0022-access-control-fails-closed-when-it-cannot-scope.md`.
+ */
+export class RelationFilterAccessDeniedError extends Error {
+  public listKey: string
+  public fieldKey: string
+  public relatedListKey: string
+
+  constructor(listKey: string, fieldKey: string, relatedListKey: string) {
+    super(
+      `Cannot filter "${listKey}.${fieldKey}" — the related list "${relatedListKey}" denies ` +
+        `query access to this session, so this relation filter cannot be scoped. Denial is loud ` +
+        `rather than silently narrowed to match nothing (ADR-0022). Use sudo to bypass.`,
+    )
+    this.name = 'RelationFilterAccessDeniedError'
+    this.listKey = listKey
+    this.fieldKey = fieldKey
+    this.relatedListKey = relatedListKey
+  }
+}
+
+function describeFieldAccessResult(result: unknown): string {
+  if (result === null) return 'null'
+  if (result === undefined) return 'undefined'
+  if (typeof result === 'object') return 'an object (e.g. a Prisma filter)'
+  return `a ${typeof result}`
+}
+
+/**
+ * Thrown when a field-level access control function returns anything other
+ * than a strict `boolean`. `FieldAccessControl` is typed to return `boolean`
+ * only: field access is a single per-field visibility decision, not a row
+ * filter, and a denied field is removed rather than used to scope rows (see
+ * the "Field-level access" glossary entry in `CONTEXT.md`, ADR-0001, and
+ * ADR-0030).
+ *
+ * A rule that type-checks can never reach this — the only way here is a
+ * caller that bypasses the type (an untyped JS config, or a value forced past
+ * the checker), most notably a Prisma filter, which is the shape
+ * operation-level `AccessControl` accepts but `FieldAccessControl` does not.
+ * Before #913 this fell through to an unconditional `return true`, silently
+ * granting the field blanket access; it now fails loudly and closed instead,
+ * for `read`, `create`, and `update` alike.
+ *
+ * Deliberately does not expose the offending result as a public field: unlike
+ * `AccessScopeDepthExceededError`/`ResolveOutputCycleError`'s fields, there is
+ * no concretely-typed shape to give it (the whole problem is that it isn't
+ * the `boolean` the caller's rule promised), and the root CLAUDE.md forbids
+ * exposing `unknown`/`any` as part of a package's external API. A description
+ * of what was returned instead is folded into the message text.
+ */
+export class InvalidFieldAccessResultError extends Error {
+  public operation: 'read' | 'create' | 'update'
+
+  constructor(operation: 'read' | 'create' | 'update', result: unknown) {
+    super(
+      `Field-level access control for operation "${operation}" returned ` +
+        `${describeFieldAccessResult(result)}, not a boolean. Field access is a per-field ` +
+        `visibility decision — it must return true or false, and (unlike operation-level access) ` +
+        `cannot scope which rows are affected. If you meant to restrict access based on the row or ` +
+        `the write payload, evaluate the condition yourself and return a boolean, e.g. ` +
+        `\`({ item, session }) => item?.ownerId === session?.userId\`.`,
+    )
+    this.name = 'InvalidFieldAccessResultError'
+    this.operation = operation
+  }
+}

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

@@ -1,6 +1,12 @@
-import { describe, it, expect } from 'vitest'
-import { filterWritableFields } from './field-access.js'
+import { describe, it, expect, expectTypeOf } from 'vitest'
+import {
+  checkFieldAccess,
+  filterWritableFields,
+  isFieldReadableForPredicate,
+} from './field-access.js'
+import { InvalidFieldAccessResultError } from './errors.js'
 import { ValidationError } from '../hooks/index.js'
+import type { FieldAccess, FieldAccessControl } from './types.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
@@ -21,6 +27,283 @@ function sudoContext() {
   } as any
 }
 
+// ── #914: `FieldAccess['read']`'s `item` must type as present, matching what
+// Field Visibility (field-visibility.ts) actually passes ──
+
+describe("FieldAccess['read'] item typing (issue #914)", () => {
+  type Item = { ownerId: string }
+
+  it('types item as present for a read rule that reads a property off it — no cast, no `any`', () => {
+    const fieldAccess: FieldAccess<Item> = {
+      read: ({ session, item }) => item.ownerId === session?.userId,
+    }
+    expect(typeof fieldAccess.read).toBe('function')
+  })
+
+  it('still compiles a read rule that ignores item entirely', () => {
+    const fieldAccess: FieldAccess<Item> = {
+      read: () => true,
+    }
+    expect(typeof fieldAccess.read).toBe('function')
+  })
+
+  it('leaves the create branch unchanged — item is still absent, there genuinely is no row yet', () => {
+    // Pinned against `FieldAccessControl`'s discriminated union directly
+    // (rather than `FieldAccess['create']`'s destructured callback), because
+    // `create`/`update` — unlike `read` — are untouched by this fix and keep
+    // accepting the full `FieldAccessControl` union in `FieldAccess`.
+    type CreateArgs = Extract<Parameters<FieldAccessControl<Item>>[0], { operation: 'create' }>
+    expectTypeOf<CreateArgs['item']>().toEqualTypeOf<undefined>()
+  })
+
+  // Type-level pin: `resolveReadableFieldValue` (field-visibility.ts) is the
+  // sole caller of `checkFieldAccess` for `operation: 'read'`, and always
+  // supplies `item: accessItem` — a full row, never `undefined`. This
+  // assertion has no runtime effect (`expectTypeOf` is a no-op outside
+  // `vitest --typecheck`); its value is that `pnpm build`/`tsc` fails on this
+  // file the moment `FieldAccess['read']`'s `item` type drifts back to
+  // optional/absent, so the declared type and the call site cannot silently
+  // diverge again.
+  it("pins FieldAccess['read']'s item type against the field-visibility.ts call site", () => {
+    type ReadArgs = Parameters<NonNullable<FieldAccess<Item>['read']>>[0]
+    expectTypeOf<ReadArgs['item']>().toEqualTypeOf<Item>()
+    expectTypeOf<ReadArgs['operation']>().toEqualTypeOf<'read'>()
+  })
+})
+
+// ── #913: a field rule returning a filter must not be granted blanket access ──
+
+describe('checkFieldAccess', () => {
+  it('allows when the rule returns true', async () => {
+    const allowed = await checkFieldAccess({ read: () => true }, 'read', {
+      session: null,
+      item: { ownerId: 'someone-else' },
+      context: nonSudoContext(),
+    })
+    expect(allowed).toBe(true)
+  })
+
+  it('denies when the rule returns false', async () => {
+    const allowed = await checkFieldAccess({ read: () => false }, 'read', {
+      session: null,
+      item: { ownerId: 'someone-else' },
+      context: nonSudoContext(),
+    })
+    expect(allowed).toBe(false)
+  })
+
+  it('allows when no field access is configured', async () => {
+    const allowed = await checkFieldAccess(undefined, 'read', {
+      session: null,
+      context: nonSudoContext(),
+    })
+    expect(allowed).toBe(true)
+  })
+
+  it('allows when no rule is configured for the operation', async () => {
+    const allowed = await checkFieldAccess({ update: () => false }, 'read', {
+      session: null,
+      context: nonSudoContext(),
+    })
+    expect(allowed).toBe(true)
+  })
+
+  it('throws InvalidFieldAccessResultError, not allow, when a read rule returns a filter', async () => {
+    // The exact reproduction from the issue: a rule written to scope a field
+    // by row, which the previous fail-open default granted full access to.
+    const fieldAccess = {
+      read: () => ({ ownerId: { equals: 'someone-else' } }),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+
+    await expect(
+      checkFieldAccess(fieldAccess, 'read', {
+        session: null,
+        item: { ownerId: 'the-owner' },
+        context: nonSudoContext(),
+      }),
+    ).rejects.toThrow(InvalidFieldAccessResultError)
+  })
+
+  it('throws for a filter-returning rule on create, where there is no item to test it against', async () => {
+    const fieldAccess = {
+      create: () => ({ ownerId: { equals: 'someone-else' } }),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+
+    await expect(
+      checkFieldAccess(fieldAccess, 'create', {
+        session: null,
+        context: nonSudoContext(),
+        inputData: { ownerId: 'the-owner' },
+      }),
+    ).rejects.toThrow(InvalidFieldAccessResultError)
+  })
+
+  it('throws for a filter-returning rule on update', async () => {
+    const fieldAccess = {
+      update: () => ({ ownerId: { equals: 'someone-else' } }),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+
+    await expect(
+      checkFieldAccess(fieldAccess, 'update', {
+        session: null,
+        item: { ownerId: 'the-owner' },
+        context: nonSudoContext(),
+        inputData: { ownerId: 'someone-else' },
+      }),
+    ).rejects.toThrow(InvalidFieldAccessResultError)
+  })
+
+  it('throws for a non-boolean, non-filter result too (e.g. undefined)', async () => {
+    const fieldAccess = {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      read: () => undefined as any,
+    }
+
+    await expect(
+      checkFieldAccess(fieldAccess, 'read', {
+        session: null,
+        item: {},
+        context: nonSudoContext(),
+      }),
+    ).rejects.toThrow(InvalidFieldAccessResultError)
+  })
+
+  it('throws with a descriptive message for null, and for other primitive results', async () => {
+    const nullAccess = {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      read: () => null as any,
+    }
+    await expect(
+      checkFieldAccess(nullAccess, 'read', {
+        session: null,
+        item: {},
+        context: nonSudoContext(),
+      }),
+    ).rejects.toThrow(/returned null, not a boolean/)
+
+    const numberAccess = {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      read: () => 42 as any,
+    }
+    await expect(
+      checkFieldAccess(numberAccess, 'read', {
+        session: null,
+        item: {},
+        context: nonSudoContext(),
+      }),
+    ).rejects.toThrow(/returned a number, not a boolean/)
+  })
+
+  it('sudo bypasses the rule entirely, so a filter-returning rule never reaches the throw', async () => {
+    const fieldAccess = {
+      read: () => ({ ownerId: { equals: 'someone-else' } }),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+
+    const allowed = await checkFieldAccess(fieldAccess, 'read', {
+      session: null,
+      item: { ownerId: 'the-owner' },
+      context: sudoContext(),
+    })
+    expect(allowed).toBe(true)
+  })
+})
+
+describe('isFieldReadableForPredicate (#915)', () => {
+  it('allows when there is no field access configured', async () => {
+    const readable = await isFieldReadableForPredicate(undefined, {
+      session: null,
+      context: nonSudoContext(),
+    })
+    expect(readable).toBe(true)
+  })
+
+  it('allows when the rule only inspects session (never touches item)', async () => {
+    const readable = await isFieldReadableForPredicate(
+      { read: ({ session }) => session?.userId === 'admin' },
+      { session: { userId: 'admin' }, context: nonSudoContext() },
+    )
+    expect(readable).toBe(true)
+  })
+
+  it('denies when the rule returns false', async () => {
+    const readable = await isFieldReadableForPredicate(
+      { read: () => false },
+      { session: null, context: nonSudoContext() },
+    )
+    expect(readable).toBe(false)
+  })
+
+  it('denies a row-dependent rule that dereferences `item` directly', async () => {
+    const readable = await isFieldReadableForPredicate(
+      { read: ({ item, session }) => item.ownerId === session?.userId },
+      { session: { userId: 'user-1' }, context: nonSudoContext() },
+    )
+    expect(readable).toBe(false)
+  })
+
+  it('denies a row-dependent rule even when it reads `item` via optional chaining', async () => {
+    // This is the exact idiom `InvalidFieldAccessResultError`'s own message
+    // recommends (`item?.ownerId === session?.userId`) — it must still deny,
+    // not silently misevaluate `undefined === session?.userId` against a
+    // poisoned `item`.
+    const readable = await isFieldReadableForPredicate(
+      { read: ({ item, session }) => item?.ownerId === session?.userId },
+      { session: null, context: nonSudoContext() },
+    )
+    expect(readable).toBe(false)
+  })
+
+  it('denies a row-dependent rule that only enumerates `item`s keys', async () => {
+    const readable = await isFieldReadableForPredicate(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      { read: ({ item }) => Object.keys(item as any).length > 0 },
+      { session: null, context: nonSudoContext() },
+    )
+    expect(readable).toBe(false)
+  })
+
+  it('propagates InvalidFieldAccessResultError instead of folding it into a denial', async () => {
+    const fieldAccess = {
+      read: () => ({ ownerId: { equals: 'someone-else' } }),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+
+    await expect(
+      isFieldReadableForPredicate(fieldAccess, { session: null, context: nonSudoContext() }),
+    ).rejects.toThrow(InvalidFieldAccessResultError)
+  })
+
+  it('propagates a genuine error the rule throws for its own reasons, not just non-boolean results', async () => {
+    // The rule never touches `item` — it throws for a reason of its own.
+    // This must NOT be folded into an ordinary `false` denial (that would
+    // mask a real bug in the rule as "field not readable"), matching how the
+    // post-query path (`filterReadableFields`) already lets such a throw
+    // propagate unchanged.
+    const fieldAccess: FieldAccess = {
+      read: ({ session }) => {
+        if (session === null) throw new Error('unexpected anonymous access')
+        return true
+      },
+    }
+
+    await expect(
+      isFieldReadableForPredicate(fieldAccess, { session: null, context: nonSudoContext() }),
+    ).rejects.toThrow('unexpected anonymous access')
+  })
+
+  it('sudo bypasses the rule entirely, so a row-dependent rule never denies', async () => {
+    const readable = await isFieldReadableForPredicate(
+      { read: ({ item, session }) => item.ownerId === session?.userId },
+      { session: null, context: sudoContext() },
+    )
+    expect(readable).toBe(true)
+  })
+})
+
 describe('filterWritableFields', () => {
   it('should filter out foreign key fields when their corresponding relationship field exists', async () => {
     // Setup: Define field configs with a relationship field
@@ -361,6 +644,33 @@ describe('filterWritableFields', () => {
     ).rejects.toThrow(/status/)
   })
 
+  // ── #913: a field rule returning a filter must not grant blanket write access ──
+
+  it('throws InvalidFieldAccessResultError, not a blanket write, when field access returns a filter (non-sudo)', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+      status: {
+        type: 'text',
+        access: {
+          // Written as a row-scoping rule; field access does not honour filters.
+          update: () => ({ status: { equals: 'draft' } }),
+          create: () => ({ status: { equals: 'draft' } }),
+        },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const data = { title: 'Test', status: 'published' }
+
+    await expect(
+      filterWritableFields(data, fieldConfigs, 'update', {
+        session: null,
+        item: { id: 'post-1', status: 'draft' },
+        context: nonSudoContext(),
+        inputData: data,
+      }),
+    ).rejects.toThrow(InvalidFieldAccessResultError)
+  })
+
   it('does NOT throw on a would-be-denied field under sudo', async () => {
     const fieldConfigs = {
       title: { type: 'text' },