@opensaas/stack-core 0.20.1 → 0.21.0

package/src/access/field-visibility.ts

@@ -0,0 +1,247 @@
+import type { Session, AccessContext } from './types.js'
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+import { getRelatedListConfig } from './engine.js'
+import { checkFieldAccess } from './field-access.js'
+
+/**
+ * Field Visibility — phase 2 of the two-phase read (post-query).
+ *
+ * This module runs after the database query against the returned rows. It
+ * strips fields the session cannot read (via the canonical `checkFieldAccess`
+ * evaluator in `field-access.ts`), runs `resolveOutput` hooks, and computes
+ * virtual fields. None of this can move into phase 1: virtual fields are
+ * computed in JavaScript and field access can depend on the fetched row.
+ *
+ * Phase 1 (pre-query row/relation scoping) lives in `access-filter.ts`. See
+ * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
+ * glossary in `CONTEXT.md`.
+ */
+
+/**
+ * Runtime type for resolveOutput hooks
+ * Used when we need to call hooks generically without knowing the specific field type
+ * Supports both sync and async implementations
+ */
+type ResolveOutputHookRuntime = (args: {
+  operation: 'query'
+  value: unknown
+  item: Record<string, unknown>
+  listKey: string
+  fieldName: string
+  context: AccessContext
+}) => unknown | Promise<unknown>
+
+type FieldVisibilityArgs = {
+  session: Session | null
+  context: AccessContext & { _isSudo?: boolean }
+}
+
+/**
+ * The core Field Visibility step for a single field: check read access and, if
+ * granted, produce the output value by running any `resolveOutput` hook.
+ *
+ * This is the single place the "check read access → skip if denied →
+ * resolveOutput" sequence lives. Both the regular-field branch and the
+ * virtual-field branch of `filterReadableFields` call it, so the sequence is
+ * never duplicated. Returns `{ readable: false }` when the field must be omitted
+ * from the result.
+ *
+ * `accessItem` is the row used to evaluate field access; `hookItem` is the
+ * object passed to the hook as `item` (these differ for virtual fields, which
+ * see the already-filtered output so they can read sibling fields).
+ */
+async function resolveReadableFieldValue(params: {
+  fieldConfig: FieldConfig | undefined
+  fieldName: string
+  value: unknown
+  accessItem: Record<string, unknown>
+  hookItem: Record<string, unknown>
+  listKey: string | undefined
+  args: FieldVisibilityArgs
+}): Promise<{ readable: false } | { readable: true; value: unknown }> {
+  const { fieldConfig, fieldName, value, accessItem, hookItem, listKey, args } = params
+
+  // Check field access (checkFieldAccess already handles sudo mode)
+  const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
+    ...args,
+    item: accessItem,
+  })
+
+  if (!canRead) {
+    return { readable: false }
+  }
+
+  // Apply resolveOutput hook if present
+  if (fieldConfig?.hooks?.resolveOutput && listKey) {
+    // Cast to runtime type for generic execution
+    // At runtime, the hook will receive the correct value type for the field
+    const hook = fieldConfig.hooks.resolveOutput as unknown as ResolveOutputHookRuntime
+    // Increment depth counter to prevent infinite loops from hooks making DB queries
+    // that include relationships back to the same entity
+    args.context._resolveOutputCounter.depth++
+    try {
+      // Use Promise.resolve() to handle both sync and async hooks
+      const resolved = await Promise.resolve(
+        hook({
+          value,
+          operation: 'query',
+          fieldName,
+          listKey,
+          item: hookItem,
+          context: args.context,
+        }),
+      )
+      return { readable: true, value: resolved }
+    } finally {
+      args.context._resolveOutputCounter.depth--
+    }
+  }
+
+  return { readable: true, value }
+}
+
+/**
+ * Filter fields from an object based on read access
+ * Recursively applies access control to nested relationships
+ */
+export async function filterReadableFields<T extends Record<string, unknown>>(
+  item: T,
+  fieldConfigs: Record<string, FieldConfig>,
+  args: {
+    session: Session | null
+    context: AccessContext & { _isSudo?: boolean }
+  },
+  config?: OpenSaasConfig,
+  depth: number = 0,
+  listKey?: string,
+): Promise<Partial<T>> {
+  const filtered: Record<string, unknown> = {}
+  const MAX_DEPTH = 5 // Prevent infinite recursion
+
+  // Process existing fields from the database result
+  for (const [fieldName, value] of Object.entries(item)) {
+    const fieldConfig = fieldConfigs[fieldName]
+
+    // Always include id, createdAt, updatedAt
+    if (['id', 'createdAt', 'updatedAt'].includes(fieldName)) {
+      filtered[fieldName] = value
+      continue
+    }
+
+    // Handle relationship fields - recursively filter fields within related items
+    // Note: Access control filtering is now done at database level via buildIncludeWithAccessControl
+    // This only handles field-level access (hiding sensitive fields)
+    if (
+      config &&
+      fieldConfig?.type === 'relationship' &&
+      'ref' in fieldConfig &&
+      fieldConfig.ref &&
+      value !== null &&
+      value !== undefined &&
+      depth < MAX_DEPTH
+    ) {
+      // Gate the relationship on read access before recursing.
+      const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
+        ...args,
+        item,
+      })
+
+      if (!canRead) {
+        continue
+      }
+
+      const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
+
+      if (relatedConfig) {
+        // For many relationships (arrays) - recursively filter fields in each item
+        // The recursive call already handles applying resolveOutput hooks
+        if (Array.isArray(value)) {
+          filtered[fieldName] = await Promise.all(
+            value.map((relatedItem) =>
+              filterReadableFields(
+                relatedItem,
+                relatedConfig.listConfig.fields,
+                args,
+                config,
+                depth + 1,
+                relatedConfig.listName,
+              ),
+            ),
+          )
+        }
+        // For single relationships (objects) - recursively filter fields
+        // The recursive call already handles applying resolveOutput hooks
+        else if (typeof value === 'object') {
+          filtered[fieldName] = await filterReadableFields(
+            value as Record<string, unknown>,
+            relatedConfig.listConfig.fields,
+            args,
+            config,
+            depth + 1,
+            relatedConfig.listName,
+          )
+        }
+      } else {
+        // Related config not found, include the value as-is
+        filtered[fieldName] = value
+      }
+      continue
+    }
+
+    // Non-relationship field (or relationship without an includable value):
+    // check read access and apply resolveOutput via the shared helper.
+    const result = await resolveReadableFieldValue({
+      fieldConfig,
+      fieldName,
+      value,
+      accessItem: item,
+      hookItem: item,
+      listKey,
+      args,
+    })
+
+    if (result.readable) {
+      filtered[fieldName] = result.value
+    }
+  }
+
+  // Process virtual fields - compute values from other fields
+  // Virtual fields don't exist in the database result, so we need to compute them separately
+  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+    // Skip if already processed (from database result)
+    if (fieldName in filtered) {
+      continue
+    }
+
+    // Only process virtual fields
+    if (!fieldConfig.virtual) {
+      continue
+    }
+
+    // Virtual fields must have a resolveOutput hook to compute their value;
+    // without one there is nothing to add to the result.
+    if (!(fieldConfig.hooks?.resolveOutput && listKey)) {
+      // Still evaluate read access to preserve any access-fn side effects.
+      await checkFieldAccess(fieldConfig.access, 'read', { ...args, item })
+      continue
+    }
+
+    // Check read access and compute the value via the shared helper. Virtual
+    // fields see the already-filtered item so they can read sibling fields.
+    const result = await resolveReadableFieldValue({
+      fieldConfig,
+      fieldName,
+      value: undefined, // Virtual fields don't have a database value
+      accessItem: item,
+      hookItem: filtered,
+      listKey,
+      args,
+    })
+
+    if (result.readable) {
+      filtered[fieldName] = result.value
+    }
+  }
+
+  return filtered as Partial<T>
+}

package/src/access/index.ts

@@ -11,14 +11,17 @@ export type {
   AugmentedFindUnique,
   FindManyQueryArgs,
 } from './types.js'
+// Operation-level access primitives and shared ref-parsing helper.
 export {
   checkAccess,
   mergeFilters,
-  checkFieldAccess,
-  filterReadableFields,
-  filterWritableFields,
   isBoolean,
   isPrismaFilter,
   getRelatedListConfig,
-  buildIncludeWithAccessControl,
 } from './engine.js'
+// Canonical field-level access evaluation (shared by read and write paths).
+export { checkFieldAccess, filterWritableFields } from './field-access.js'
+// Phase 1 — Access Filter (pre-query row/relation scoping).
+export { buildIncludeWithAccessControl } from './access-filter.js'
+// Phase 2 — Field Visibility (post-query field stripping + resolveOutput).
+export { filterReadableFields } from './field-visibility.js'

package/src/config/index.ts

@@ -134,6 +134,7 @@ export type {
   PasswordField,
   SelectField,
   RelationshipField,
+  PrismaRelationResult,
   JsonField,
   VirtualField,
   TypeDescriptor,

package/src/config/types.ts

@@ -723,7 +723,56 @@ export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
     ui?: {
       displayMode?: 'select' | 'cards'
     }
+    /**
+     * Get the complete Prisma schema contribution for this relationship field.
+     *
+     * Relationships are special: unlike scalar fields (which return a single
+     * type via `getPrismaType`), a relationship can contribute a foreign key
+     * line, a relation line on the owning model, and a synthetic back-relation
+     * line on the target model. This method encapsulates all of that logic so
+     * the generator can remain a neutral coordinator.
+     *
+     * @param fieldName - The name of this relationship field
+     * @param allFields - All fields on the list this relationship belongs to
+     * @param listKey - The name of the list this relationship belongs to
+     * @param config - The full OpenSaas config (used to resolve the target list/field)
+     */
+    getPrismaRelation?: (
+      fieldName: string,
+      allFields: Record<string, FieldConfig>,
+      listKey: string,
+      config: OpenSaasConfig,
+    ) => PrismaRelationResult
+  }
+
+/**
+ * The complete Prisma schema contribution of a relationship field.
+ */
+export type PrismaRelationResult = {
+  /**
+   * Lines to add to the owning model.
+   * For an FK-owning single relationship this is `[fkLine, relationLine]`;
+   * for the many side or the non-FK side it is `[relationLine]`.
+   */
+  modelLines: string[]
+  /**
+   * Foreign key index to add to the owning model, if this side owns an
+   * indexed foreign key.
+   */
+  foreignKeyIndex?: {
+    foreignKeyField: string
+    indexType: boolean | 'unique'
   }
+  /**
+   * Synthetic back-relation field to add to the target model. Only present
+   * for list-only refs (e.g., `ref: 'Category'`), where the target model
+   * needs an opposite relation field for Prisma to validate the relation.
+   */
+  backRelation?: {
+    targetList: string
+    line: string
+  }
+}
 
 export type JsonField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'json'
@@ -1221,12 +1270,10 @@ export type DatabaseConfig = {
    *
    * @example SQLite with better-sqlite3
    * ```typescript
-   * import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3'
-   * import Database from 'better-sqlite3'
+   * import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
    *
    * prismaClientConstructor: (PrismaClient) => {
-   *   const db = new Database(process.env.DATABASE_URL || './dev.db')
-   *   const adapter = new PrismaBetterSQLite3(db)
+   *   const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL || 'file:./dev.db' })
    *   return new PrismaClient({ adapter })
    * }
    * ```

package/src/context/hook-pipeline.ts

@@ -0,0 +1,160 @@
+import type { ListConfig } from '../config/types.js'
+import type { AccessContext } from '../access/types.js'
+import {
+  executeResolveInput,
+  executeValidate,
+  executeFieldResolveInputHooks,
+  executeFieldValidateHooks,
+  validateFieldRules,
+  ValidationError,
+} from '../hooks/index.js'
+
+/**
+ * Hook Pipeline — the single module that runs the transform+validate span of a
+ * write: list `resolveInput` → field `resolveInput` → list `validate` → field
+ * `validate` → built-in field rules (`validateFieldRules`). It owns the order of
+ * these phases and the threading of `resolvedData` through them, in one place.
+ *
+ * It is THE place where input is shaped and validated; it throws
+ * {@link ValidationError} on failure exactly as before (validate hooks via
+ * `addValidationError`, then `validateFieldRules`) — validation is never silent.
+ *
+ * Side-effect hooks (`beforeOperation`/`afterOperation`), operation-level access,
+ * writable-field filtering, nested operations, persistence and Field Visibility
+ * are deliberately OUT of this span — they stay in the Write Pipeline. See the
+ * "Hook Pipeline" and "Write Pipeline" glossary terms in CONTEXT.md.
+ */
+
+/**
+ * Arguments for one transform+validate span. Only the create/update operations
+ * run this span (delete skips the input-shaping phases entirely).
+ */
+export interface HookPipelineArgs {
+  operation: 'create' | 'update'
+  listName: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  listConfig: ListConfig<any>
+  /** The original input data for the write. */
+  inputData: Record<string, unknown>
+  /** The existing row for update; `undefined` for create. */
+  item: Record<string, unknown> | undefined
+  context: AccessContext
+}
+
+/**
+ * Result of a transform+validate span: the fully-resolved write data after the
+ * resolveInput hooks have run and all validation has passed.
+ */
+export interface HookPipelineResult {
+  resolvedData: Record<string, unknown>
+}
+
+/**
+ * The transform+validate span, owning order + `resolvedData` threading.
+ */
+export interface HookPipeline {
+  run(args: HookPipelineArgs): Promise<HookPipelineResult>
+}
+
+/**
+ * Run the transform+validate span once.
+ *
+ * Phase order (owned here, in one place):
+ *   list `resolveInput`
+ *     → field `resolveInput`
+ *     → list `validate`
+ *     → field `validate`
+ *     → built-in field rules (`validateFieldRules`)
+ *
+ * Contract preserved exactly:
+ *   - `resolvedData` starts as `inputData` and is threaded through each phase;
+ *   - validate hooks report failures via `addValidationError` → THROW
+ *     `ValidationError` (never silent);
+ *   - built-in field rule failures THROW `ValidationError`;
+ *   - on success returns the transformed `resolvedData`.
+ */
+async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResult> {
+  const { operation, listName, listConfig, inputData, item, context } = args
+
+  // ── Phase 1: list-level resolveInput ──────────────────────────────────────
+  let resolvedData = await executeResolveInput(
+    listConfig.hooks,
+    operation === 'create'
+      ? {
+          listKey: listName,
+          operation: 'create',
+          inputData,
+          resolvedData: inputData,
+          item: undefined,
+          context,
+        }
+      : {
+          listKey: listName,
+          operation: 'update',
+          inputData,
+          resolvedData: inputData,
+          item,
+          context,
+        },
+  )
+
+  // ── Phase 1.5: field-level resolveInput (e.g. hash passwords) ──────────────
+  resolvedData = await executeFieldResolveInputHooks(
+    inputData,
+    resolvedData,
+    listConfig.fields,
+    operation,
+    context,
+    listName,
+    item,
+  )
+
+  // ── Phase 2: list-level validate ──────────────────────────────────────────
+  await executeValidate(
+    listConfig.hooks,
+    operation === 'create'
+      ? {
+          listKey: listName,
+          operation: 'create',
+          inputData,
+          resolvedData,
+          item: undefined,
+          context,
+        }
+      : {
+          listKey: listName,
+          operation: 'update',
+          inputData,
+          resolvedData,
+          item,
+          context,
+        },
+  )
+
+  // ── Phase 2.5: field-level validate ───────────────────────────────────────
+  await executeFieldValidateHooks(
+    inputData,
+    resolvedData,
+    listConfig.fields,
+    operation,
+    context,
+    listName,
+    item,
+  )
+
+  // ── Phase 3: built-in field rules (isRequired, length, etc.) ──────────────
+  // Validation failures THROW (validation is not silent).
+  const validation = validateFieldRules(resolvedData, listConfig.fields, operation)
+  if (validation.errors.length > 0) {
+    throw new ValidationError(validation.errors, validation.fieldErrors)
+  }
+
+  return { resolvedData }
+}
+
+/**
+ * The default Hook Pipeline instance used by the Write Pipeline.
+ */
+export const hookPipeline: HookPipeline = {
+  run: runHookPipeline,
+}