@opensaas/stack-core 0.1.0

package/docs/type-distribution-fix.md

@@ -0,0 +1,136 @@
+# Password Field Type Distribution Fix
+
+## Problem
+
+All fields in returned objects were being typed as `string | HashedPassword` instead of only the password field being typed as `HashedPassword`.
+
+### Example of the Bug
+
+```typescript
+const users = await context.db.user.findMany()
+// Before fix:
+// users: { name: string | HashedPassword, email: string | HashedPassword, password: string | HashedPassword, ... }
+//
+// Expected:
+// users: { name: string, email: string, password: HashedPassword, ... }
+```
+
+## Root Cause
+
+The issue was in how TypeScript's **distributive conditional types** work with union types.
+
+### The Problem Code
+
+In `packages/core/src/access/types.ts`, the `TransformObject` type was delegating to a `TransformField` helper:
+
+```typescript
+type TransformObject<TConfig, TListKey, TObj> = {
+  [K in keyof TObj]: K extends keyof TConfig['lists'][TListKey]['fields']
+    ? TransformField<TConfig['lists'][TListKey]['fields'][K], TObj[K]>
+    : //                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      //                This is a UNION of all field config types!
+      TObj[K]
+}
+```
+
+When TypeScript evaluated `TConfig['lists'][TListKey]['fields'][K]`, it couldn't narrow the type precisely, resulting in:
+
+```typescript
+TextField | IntegerField | CheckboxField | TimestampField | PasswordField | ...
+```
+
+This union type then **distributed** over the conditional type in `TransformField`:
+
+```typescript
+type TransformField<TFieldConfig, TOriginal> = TFieldConfig extends { type: infer TType }
+  ? 'password' extends TType // Distributes over the union!
+    ? HashedPassword
+    : TOriginal
+  : TOriginal
+
+// Becomes:
+// TransformField<TextField, string> | TransformField<PasswordField, string> | ...
+// = TOriginal | HashedPassword | ...
+// = string | HashedPassword
+```
+
+## Solution
+
+**Remove the `TransformField` helper and inline the logic directly in `TransformObject`.**
+
+This allows TypeScript to narrow the field config type **before** applying the conditional type, preventing distribution.
+
+### The Fix
+
+```typescript
+type TransformObject<TConfig, TListKey, TObj> =
+  TObj extends Record<string, any>
+    ? {
+        [K in keyof TObj]: K extends keyof TConfig['lists'][TListKey]['fields']
+          ? TConfig['lists'][TListKey]['fields'][K] extends { type: 'relationship', ref: infer TRef }
+            ? /* relationship logic */
+            : // Inline password check - NO helper function
+              TConfig['lists'][TListKey]['fields'][K] extends { type: 'password' }
+              ? TObj[K] extends string
+                ? HashedPassword
+                : TObj[K]
+              : TObj[K]  // Not password, preserve original type
+          : TransformIncludedRelationship<TConfig, K, TObj[K]>
+      }
+    : TObj
+```
+
+### Why This Works
+
+By inlining the logic, TypeScript can:
+
+1. **First narrow** `TConfig['lists'][TListKey]['fields'][K]` to the specific field type (e.g., `TextField`)
+2. **Then check** if it extends `{ type: 'password' }`
+3. **Return** the appropriate type without creating a union
+
+The check `TConfig['lists'][TListKey]['fields'][K] extends { type: 'password' }` evaluates to:
+
+- `TextField extends { type: 'password' }` → `false` → return `TObj[K]` (preserve original)
+- `PasswordField extends { type: 'password' }` → `true` → return `HashedPassword`
+
+No distribution occurs because we're not using a separate type alias that receives the union.
+
+## Verification
+
+### Tests
+
+Created `tests/password-type-distribution.test.ts` with 3 tests:
+
+1. Verifies non-password fields remain `string`
+2. Verifies password field becomes `HashedPassword`
+3. Verifies TypeScript narrowing works correctly
+
+All 191 tests pass ✅
+
+### Type Checks
+
+```typescript
+const users = await context.db.user.findMany()
+const user = users[0]
+
+// These now compile correctly:
+const name: string = user.name // ✅ string
+const email: string = user.email // ✅ string
+const password: HashedPassword = user.password // ✅ HashedPassword
+await password.compare('test') // ✅ Has compare method
+```
+
+## Files Changed
+
+- `packages/core/src/access/types.ts`:
+  - Modified `TransformObject` type (lines 125-160) to inline password transformation logic
+  - Removed `TransformField` helper type (was lines 175-189)
+- `packages/core/tests/password-type-distribution.test.ts`:
+  - New test file with 3 tests verifying the fix
+
+## Lessons Learned
+
+1. **Distributive conditional types** in TypeScript can cause unexpected union types
+2. **Helper type aliases** can prevent proper type narrowing
+3. **Inlining type logic** allows TypeScript to narrow types before applying conditionals
+4. **Test both runtime and compile-time behavior** when working with TypeScript transformations

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@opensaas/stack-core",
+  "version": "0.1.0",
+  "description": "Core stack for OpenSaas - schema definition, access control, and runtime utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fields": {
+      "types": "./dist/fields/index.d.ts",
+      "default": "./dist/fields/index.js"
+    }
+  },
+  "keywords": [
+    "opensaas",
+    "nextjs",
+    "prisma",
+    "admin"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "@prisma/client": "^6.17.0"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.2",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@prisma/client": "^6.17.1",
+    "@types/bcryptjs": "^3.0.0",
+    "@types/node": "^24.7.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "clean": "rm -rf .turbo dist tsconfig.tsbuildinfo"
+  }
+}

package/src/access/engine.ts

@@ -0,0 +1,360 @@
+import type { AccessControl, Session, AccessContext, PrismaFilter } from './types.js'
+import type { FieldAccess } from './types.js'
+import type { OpenSaasConfig, ListConfig, FieldConfig } from '../config/types.js'
+
+/**
+ * Check if access control result is a boolean
+ */
+export function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean'
+}
+
+/**
+ * Check if access control result is a Prisma filter
+ */
+export function isPrismaFilter(value: unknown): value is PrismaFilter {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Parse a relationship ref and get the related list configuration
+ * Relationship refs are in the format "ListName.fieldName"
+ *
+ * @param relationshipRef - The ref string (e.g., "Post.author")
+ * @param config - The OpenSaas configuration
+ * @returns The related list name and config, or null if not found
+ */
+export function getRelatedListConfig(
+  relationshipRef: string,
+  config: OpenSaasConfig,
+): { listName: string; listConfig: ListConfig } | null {
+  // Parse ref format: "ListName.fieldName"
+  const parts = relationshipRef.split('.')
+  if (parts.length !== 2) {
+    return null
+  }
+
+  const listName = parts[0]
+  const listConfig = config.lists[listName]
+
+  if (!listConfig) {
+    return null
+  }
+
+  return { listName, listConfig }
+}
+
+/**
+ * Execute an access control function
+ */
+export async function checkAccess<T = Record<string, unknown>>(
+  accessControl: AccessControl<T> | undefined,
+  args: {
+    session: Session
+    item?: T
+    context: AccessContext
+  },
+): Promise<boolean | PrismaFilter<T>> {
+  // No access control means deny by default
+  if (!accessControl) {
+    return false
+  }
+
+  // Execute the access control function
+  const result = await accessControl(args)
+
+  return result
+}
+
+/**
+ * Merge user filter with access control filter
+ */
+export function mergeFilters(
+  userFilter: PrismaFilter | undefined,
+  accessFilter: boolean | PrismaFilter,
+): PrismaFilter | null {
+  // If access is denied, return null
+  if (accessFilter === false) {
+    return null
+  }
+
+  // If access is fully granted, use user filter
+  if (accessFilter === true) {
+    return userFilter || {}
+  }
+
+  // Merge access filter with user filter
+  if (!userFilter) {
+    return accessFilter
+  }
+
+  // Combine filters with AND
+  return {
+    AND: [accessFilter, userFilter],
+  }
+}
+
+/**
+ * Check field-level access for a specific operation
+ */
+export async function checkFieldAccess(
+  fieldAccess: FieldAccess | undefined,
+  operation: 'read' | 'create' | 'update',
+  args: {
+    session: Session
+    item?: Record<string, unknown>
+    context: AccessContext
+  },
+): Promise<boolean> {
+  if (!fieldAccess) {
+    return true // No field access means allow
+  }
+
+  const accessControl = fieldAccess[operation]
+  if (!accessControl) {
+    return true // No specific access control means allow
+  }
+
+  const result = await accessControl(args)
+
+  // If result is false, deny access
+  if (result === false) {
+    return false
+  }
+
+  // If result is true, allow access
+  if (result === true) {
+    return true
+  }
+
+  // If result is a filter object, check if the item matches
+  // For field-level access, we need to evaluate the filter against the item
+  if (typeof result === 'object' && args.item) {
+    return matchesFilter(args.item, result)
+  }
+
+  // Default to allowing access if we can't determine
+  return true
+}
+
+/**
+ * Simple filter matching for field-level access
+ * Checks if an item matches a Prisma-like filter object
+ */
+function matchesFilter(item: Record<string, unknown>, filter: Record<string, unknown>): boolean {
+  for (const [key, condition] of Object.entries(filter)) {
+    if (typeof condition === 'object' && condition !== null) {
+      // Handle nested conditions like { equals: value }
+      if ('equals' in condition) {
+        if (item[key] !== condition.equals) {
+          return false
+        }
+      } else if ('not' in condition) {
+        if (item[key] === condition.not) {
+          return false
+        }
+      }
+      // Add more condition types as needed
+    } else {
+      // Direct equality check
+      if (item[key] !== condition) {
+        return false
+      }
+    }
+  }
+  return true
+}
+
+/**
+ * Build Prisma include object with access control filters
+ * This allows us to filter relationships at the database level instead of in memory
+ */
+export async function buildIncludeWithAccessControl(
+  fieldConfigs: Record<string, FieldConfig>,
+  args: {
+    session: Session
+    context: AccessContext
+  },
+  config: OpenSaasConfig,
+  depth: number = 0,
+) {
+  const MAX_DEPTH = 5
+  if (depth >= MAX_DEPTH) {
+    return undefined
+  }
+
+  type IncludeEntry = boolean | { where?: PrismaFilter; include?: Record<string, IncludeEntry> }
+
+  const include: Record<string, IncludeEntry> = {}
+  let hasRelationships = false
+
+  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+    if (fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && fieldConfig.ref) {
+      hasRelationships = true
+      const relatedConfig = getRelatedListConfig(fieldConfig.ref, config)
+
+      if (relatedConfig) {
+        // Check query access for the related list
+        const queryAccess = relatedConfig.listConfig.access?.operation?.query
+        const accessResult = await checkAccess(queryAccess, {
+          session: args.session,
+          context: args.context,
+        })
+
+        // If access is completely denied, exclude this relationship
+        if (accessResult === false) {
+          continue
+        }
+
+        // Build the include entry
+        const includeEntry: Record<string, unknown> = {}
+
+        // If access returns a filter, add it to the where clause
+        if (typeof accessResult === 'object') {
+          includeEntry.where = accessResult
+        }
+
+        // Recursively build nested includes
+        const nestedInclude = await buildIncludeWithAccessControl(
+          relatedConfig.listConfig.fields,
+          args,
+          config,
+          depth + 1,
+        )
+
+        if (nestedInclude && Object.keys(nestedInclude).length > 0) {
+          includeEntry.include = nestedInclude
+        }
+
+        // Add to include object
+        include[fieldName] = Object.keys(includeEntry).length > 0 ? includeEntry : true
+      }
+    }
+  }
+
+  return hasRelationships ? include : undefined
+}
+
+/**
+ * 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
+    context: AccessContext
+  },
+  config?: OpenSaasConfig,
+  depth: number = 0,
+): Promise<Partial<T>> {
+  const filtered: Record<string, unknown> = {}
+  const MAX_DEPTH = 5 // Prevent infinite recursion
+
+  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
+    }
+
+    // Check field access
+    const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
+      ...args,
+      item,
+    })
+
+    if (!canRead) {
+      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
+    ) {
+      const relatedConfig = getRelatedListConfig(fieldConfig.ref, config)
+
+      if (relatedConfig) {
+        // For many relationships (arrays) - recursively filter fields in each item
+        if (Array.isArray(value)) {
+          filtered[fieldName] = await Promise.all(
+            value.map((relatedItem) =>
+              filterReadableFields(
+                relatedItem,
+                relatedConfig.listConfig.fields,
+                args,
+                config,
+                depth + 1,
+              ),
+            ),
+          )
+        }
+        // For single relationships (objects) - recursively filter fields
+        else if (typeof value === 'object') {
+          filtered[fieldName] = await filterReadableFields(
+            value as Record<string, unknown>,
+            relatedConfig.listConfig.fields,
+            args,
+            config,
+            depth + 1,
+          )
+        }
+      } else {
+        // Related config not found, include the value as-is
+        filtered[fieldName] = value
+      }
+    } else {
+      // Non-relationship field or no config provided
+      filtered[fieldName] = value
+    }
+  }
+
+  return filtered as Partial<T>
+}
+
+/**
+ * Filter fields from input data based on write access (create/update)
+ */
+export async function filterWritableFields<T extends Record<string, unknown>>(
+  data: T,
+  fieldConfigs: Record<string, { access?: FieldAccess }>,
+  operation: 'create' | 'update',
+  args: {
+    session: Session
+    item?: Record<string, unknown>
+    context: AccessContext
+  },
+): Promise<Partial<T>> {
+  const filtered: Record<string, unknown> = {}
+
+  for (const [fieldName, value] of Object.entries(data)) {
+    const fieldConfig = fieldConfigs[fieldName]
+
+    // Skip system fields
+    if (['id', 'createdAt', 'updatedAt'].includes(fieldName)) {
+      continue
+    }
+
+    // Check field access
+    const canWrite = await checkFieldAccess(fieldConfig?.access, operation, {
+      ...args,
+    })
+
+    if (canWrite) {
+      filtered[fieldName] = value
+    }
+  }
+
+  return filtered as Partial<T>
+}

package/src/access/field-transforms.ts

@@ -0,0 +1,99 @@
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+import type { HashedPassword } from '../utils/password.js'
+
+/**
+ * Extract the return type of a field's afterOperation hook
+ * If the field has an afterOperation hook, infer its return type
+ * Otherwise, use the original type
+ */
+export type InferFieldReadType<TField extends FieldConfig, TOriginal> = TField extends {
+  // Generic `any` is required here for TypeScript's conditional type inference to work correctly
+  // This allows us to infer the exact return type `R` from hooks of any signature
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  hooks?: { afterOperation?: (...args: any[]) => infer R }
+}
+  ? R extends never
+    ? TOriginal // No hook defined
+    : R // Hook return type
+  : TOriginal // No hooks at all
+
+/**
+ * Transform a Prisma model's field types based on OpenSaas field configs
+ * This applies afterOperation hook transformations to field types
+ */
+export type TransformModelFields<
+  // Generic constraint requires `any` to allow indexing by string keys from Prisma models
+  // This is necessary for mapped types to work with Prisma's generated model types
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TModel extends Record<string, any>,
+  TFields extends Record<string, FieldConfig>,
+> = {
+  [K in keyof TModel]: K extends keyof TFields
+    ? InferFieldReadType<TFields[K], TModel[K]>
+    : TModel[K]
+}
+
+/**
+ * Get the field configs for a specific list from the OpenSaas config
+ */
+export type GetListFields<
+  TConfig extends OpenSaasConfig,
+  TListKey extends keyof TConfig['lists'],
+> = TConfig['lists'][TListKey]['fields']
+
+/**
+ * Transform a Prisma model result based on OpenSaas config
+ * Applies field hooks transformations
+ */
+export type TransformResult<
+  TConfig extends OpenSaasConfig,
+  TListKey extends keyof TConfig['lists'],
+  TResult,
+> =
+  // Generic constraint requires `any` to check if TResult is an object type that can be transformed
+  // This pattern is standard in TypeScript for conditional types on object shapes
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TResult extends Record<string, any>
+    ? TransformModelFields<TResult, GetListFields<TConfig, TListKey>>
+    : TResult
+
+/**
+ * Transform a Prisma operation's return type
+ * Handles single results, arrays, and null cases
+ */
+export type TransformOperationResult<
+  TConfig extends OpenSaasConfig,
+  TListKey extends keyof TConfig['lists'],
+  TResult,
+> =
+  TResult extends Promise<infer R>
+    ? Promise<
+        R extends Array<infer Item>
+          ? Array<TransformResult<TConfig, TListKey, Item>>
+          : R extends null
+            ? null
+            : TransformResult<TConfig, TListKey, R>
+      >
+    : never
+
+/**
+ * Known field type mappings for afterOperation hooks
+ * These provide concrete type hints for common field transformations
+ */
+export interface FieldTypeTransforms {
+  password: HashedPassword
+  // Future field types can be added here
+  // richText: TiptapContent
+  // json: JSONValue
+}
+
+/**
+ * Helper to infer field type based on field config type
+ */
+export type InferFieldTypeTransform<TField extends FieldConfig> = TField extends {
+  type: infer TType
+}
+  ? TType extends keyof FieldTypeTransforms
+    ? FieldTypeTransforms[TType]
+    : never
+  : never

package/src/access/index.ts

@@ -0,0 +1,20 @@
+export type {
+  AccessControl,
+  FieldAccess,
+  Session,
+  AccessContext,
+  PrismaFilter,
+  AccessControlledDB,
+  PrismaClientLike,
+} from './types.js'
+export {
+  checkAccess,
+  mergeFilters,
+  checkFieldAccess,
+  filterReadableFields,
+  filterWritableFields,
+  isBoolean,
+  isPrismaFilter,
+  getRelatedListConfig,
+  buildIncludeWithAccessControl,
+} from './engine.js'