@avelonjs/core 0.1.0

package/src/runtime/requests.ts

@@ -0,0 +1,77 @@
+import type { HttpRequest } from '../adapter'
+import { Forbidden, Invalid } from '../errors'
+import type { GateActor } from './gate'
+import { Gate } from './gate'
+
+/** Minimal Zod-like schema surface used by request validation. */
+export interface RequestSchema<TOutput> {
+  /** Parses unknown input into a typed value or throws. */
+  parse(input: unknown): TOutput
+}
+
+/** Optional authorize hook evaluated before schema parsing. */
+export interface FormRequestDefinition<TOutput> {
+  /** Zod (or Zod-compatible) schema. */
+  schema: RequestSchema<TOutput>
+  /** When it returns false, validation throws `Forbidden`. */
+  authorize?: (request: HttpRequest, actor: GateActor) => boolean | Promise<boolean>
+}
+
+function extractFields(error: unknown): Record<string, readonly string[]> {
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'issues' in error &&
+    Array.isArray((error as { issues: unknown }).issues)
+  ) {
+    const fields: Record<string, string[]> = {}
+    for (const issue of (error as { issues: Array<{ path?: unknown[]; message?: string }> })
+      .issues) {
+      const key = Array.isArray(issue.path) ? issue.path.map(String).join('.') || '_form' : '_form'
+      const bucket = fields[key] ?? []
+      bucket.push(issue.message ?? 'Invalid')
+      fields[key] = bucket
+    }
+    return fields
+  }
+  return { _form: ['Invalid'] }
+}
+
+/** Validation helper that maps schema failures to `Invalid`. */
+export function validateRequest<TOutput>(
+  request: HttpRequest,
+  schema: RequestSchema<TOutput>,
+): TOutput {
+  try {
+    return schema.parse(request.body)
+  } catch (error) {
+    throw new Invalid('The given data was invalid.', {
+      metadata: { fields: extractFields(error) },
+      cause: error,
+    })
+  }
+}
+
+/** Form request with Zod parsing and an optional authorize hook. */
+export interface FormRequest<TOutput> {
+  validate(request: HttpRequest, actor?: GateActor): Promise<TOutput>
+}
+
+/** Creates a request validator matching `UpdatePostRequest.validate(request)`. */
+export function defineRequest<TOutput>(
+  definition: FormRequestDefinition<TOutput>,
+): FormRequest<TOutput> {
+  return {
+    async validate(request, actor = Gate.actor()) {
+      if (definition.authorize !== undefined) {
+        const allowed = await definition.authorize(request, actor)
+        if (!allowed) {
+          throw new Forbidden('This action is unauthorized.', {
+            metadata: { ability: 'request', resource: 'form' },
+          })
+        }
+      }
+      return validateRequest(request, definition.schema)
+    },
+  }
+}

package/src/runtime/transaction.ts

@@ -0,0 +1,45 @@
+type HeldTask = () => Promise<void>
+
+let depth = 0
+const held: HeldTask[] = []
+
+/** Reports whether an enclosing transaction boundary is open. */
+export function isInTransaction(): boolean {
+  return depth > 0
+}
+
+/** Holds a task until the outermost transaction commits; drops it on rollback. */
+export function holdUntilCommit(task: HeldTask): void {
+  held.push(task)
+}
+
+/**
+ * Runs `callback` inside a commit boundary used by `afterCommit` event dispatch.
+ *
+ * Nested calls share one boundary. Tasks held with {@link holdUntilCommit} run after the outermost
+ * callback resolves, and are discarded if it throws.
+ */
+export async function runInTransaction<TResult>(
+  callback: () => Promise<TResult>,
+): Promise<TResult> {
+  depth += 1
+  try {
+    const result = await callback()
+    depth -= 1
+    if (depth === 0) {
+      const tasks = held.splice(0, held.length)
+      for (const task of tasks) await task()
+    }
+    return result
+  } catch (error) {
+    depth -= 1
+    if (depth === 0) held.length = 0
+    throw error
+  }
+}
+
+/** Clears transaction state. Intended for tests. */
+export function resetTransaction(): void {
+  depth = 0
+  held.length = 0
+}

package/src/runtime/wards.ts

@@ -0,0 +1,362 @@
+import type { Predicate, QueryIR } from '../query'
+import { Invalid } from '../errors'
+import type { GateActor } from './gate'
+
+/** Value a ward ability may return: IR predicate, boolean, or object shorthand. */
+export type WardInput = Predicate | boolean | WardShorthand
+
+/** Object shorthand compiled into a portable predicate. */
+export interface WardShorthand {
+  readonly or?: readonly WardInput[]
+  readonly and?: readonly WardInput[]
+  readonly not?: WardInput
+  readonly [column: string]: unknown
+}
+
+/** Ward abilities declared once and enforced as IR injection plus SQL policy. */
+export interface WardAbilities {
+  read: (actor: GateActor) => WardInput
+  insert: (actor: GateActor) => WardInput
+  update: (actor: GateActor) => WardInput
+  delete: (actor: GateActor) => WardInput
+}
+
+export type WardAction = keyof WardAbilities
+
+type ResourceKey = string | { readonly name: string; readonly table?: string }
+
+const wards = new Map<string, { table: string; abilities: WardAbilities }>()
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+const REFUSED = [
+  'empty objects',
+  'objects that mix `kind` with shorthand keys',
+  'objects that mix `or`/`and`/`not` with column compares',
+  'non-identifier column names',
+  'arrays, functions, and symbols as predicates',
+] as const
+
+/** Predicate shapes the compiler refuses rather than approximating. */
+export const refusedWardShapes: readonly string[] = REFUSED
+
+function resourceName(resource: ResourceKey): string {
+  return typeof resource === 'string' ? resource : resource.name
+}
+
+function resourceTable(resource: ResourceKey): string {
+  if (typeof resource === 'string') return resource
+  return resource.table ?? resource.name
+}
+
+function isPredicate(value: unknown): value is Predicate {
+  return typeof value === 'object' && value !== null && 'kind' in value
+}
+
+/**
+ * Compiles a ward return value into a portable predicate.
+ *
+ * `{ published: true }` becomes a compare. `{ or: [...] }` becomes an `or` node. `true`/`false`
+ * become `const`. Already-portable predicates pass through.
+ */
+export function compileWardShorthand(input: WardInput): Predicate {
+  if (typeof input === 'boolean') return { kind: 'const', value: input }
+  if (isPredicate(input)) return input
+  if (input === null || typeof input !== 'object') {
+    throw refused('arrays, functions, and symbols as predicates')
+  }
+  const keys = Object.keys(input)
+  if (keys.length === 0) throw refused('empty objects')
+  if ('kind' in input) {
+    throw refused('objects that mix `kind` with shorthand keys')
+  }
+  const combinators = keys.filter((key) => key === 'or' || key === 'and' || key === 'not')
+  if (combinators.length > 0 && combinators.length !== keys.length) {
+    throw refused('objects that mix `or`/`and`/`not` with column compares')
+  }
+  if (keys.length === 1 && keys[0] === 'or') {
+    const branches = Reflect.get(input, 'or')
+    if (!Array.isArray(branches))
+      throw refused('objects that mix `or`/`and`/`not` with column compares')
+    return {
+      kind: 'or',
+      predicates: branches.map((branch) => compileWardShorthand(branch as WardInput)),
+    }
+  }
+  if (keys.length === 1 && keys[0] === 'and') {
+    const branches = Reflect.get(input, 'and')
+    if (!Array.isArray(branches))
+      throw refused('objects that mix `or`/`and`/`not` with column compares')
+    return {
+      kind: 'and',
+      predicates: branches.map((branch) => compileWardShorthand(branch as WardInput)),
+    }
+  }
+  if (keys.length === 1 && keys[0] === 'not') {
+    return { kind: 'not', predicate: compileWardShorthand((input as { not: WardInput }).not) }
+  }
+  const compares: Predicate[] = []
+  for (const [column, value] of Object.entries(input)) {
+    if (!IDENTIFIER.test(column)) throw refused('non-identifier column names')
+    compares.push({ kind: 'compare', column, op: '=', value })
+  }
+  return compares.length === 1 ? (compares[0] as Predicate) : { kind: 'and', predicates: compares }
+}
+
+function refused(shape: (typeof REFUSED)[number]): never {
+  throw new Invalid(`The ward compiler refuses ${shape}.`, {
+    metadata: { fields: { ward: [`Refused shape: ${shape}`] } },
+  })
+}
+
+/** Registers a ward for a model class or table name. */
+export function defineWard(resource: ResourceKey, abilities: WardAbilities): void {
+  wards.set(resourceName(resource), { table: resourceTable(resource), abilities })
+}
+
+/** Clears registered wards. Intended for tests. */
+export function resetWards(): void {
+  wards.clear()
+}
+
+/** Resolves a registered ward ability for an actor into a portable predicate. */
+export function resolveWard(
+  resource: ResourceKey,
+  action: WardAction,
+  actor: GateActor,
+): Predicate {
+  const entry = wards.get(resourceName(resource))
+  if (entry === undefined) {
+    throw new Invalid(`No ward is registered for ${resourceName(resource)}.`, {
+      metadata: { fields: { ward: [`Missing ward for ${resourceName(resource)}.`] } },
+    })
+  }
+  return compileWardShorthand(entry.abilities[action](actor))
+}
+
+/** Injects a ward predicate into a query IR without mutating the original. */
+export function injectWard(query: QueryIR, ward: WardInput): QueryIR {
+  return { ...query, ward: compileWardShorthand(ward) }
+}
+
+/** Alias matching the earlier runtime name. */
+export const withWard = injectWard
+
+type TruthValue = boolean | null
+
+function not(value: TruthValue): TruthValue {
+  return value === null ? null : !value
+}
+
+function and(values: readonly TruthValue[]): TruthValue {
+  if (values.includes(false)) return false
+  if (values.includes(null)) return null
+  return true
+}
+
+function or(values: readonly TruthValue[]): TruthValue {
+  if (values.includes(true)) return true
+  if (values.includes(null)) return null
+  return false
+}
+
+function like(left: unknown, right: unknown, insensitive: boolean): boolean {
+  if (typeof left !== 'string' || typeof right !== 'string') return false
+  const escaped = right.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = `^${escaped.replaceAll('%', '.*').replaceAll('_', '.')}$`
+  return new RegExp(pattern, insensitive ? 'i' : undefined).test(left)
+}
+
+function compare(
+  left: unknown,
+  op: Extract<Predicate, { kind: 'compare' }>['op'],
+  right: unknown,
+): TruthValue {
+  if (left === null || left === undefined || right === null || right === undefined) return null
+  switch (op) {
+    case '=':
+      return left === right
+    case '!=':
+      return left !== right
+    case '<':
+    case '<=':
+    case '>':
+    case '>=': {
+      if (typeof left === 'number' && typeof right === 'number') {
+        const diff = left - right
+        if (op === '<') return diff < 0
+        if (op === '<=') return diff <= 0
+        if (op === '>') return diff > 0
+        return diff >= 0
+      }
+      if (typeof left === 'string' && typeof right === 'string') {
+        const diff = left.localeCompare(right)
+        if (op === '<') return diff < 0
+        if (op === '<=') return diff <= 0
+        if (op === '>') return diff > 0
+        return diff >= 0
+      }
+      return false
+    }
+    case 'like':
+      return like(left, right, false)
+    case 'ilike':
+      return like(left, right, true)
+  }
+}
+
+/**
+ * Evaluates a predicate against a row using SQL three-valued logic.
+ *
+ * `true` means the row matches. `false` means it does not. `null` is unknown, which row security
+ * and `WHERE` treat as not visible.
+ */
+export function evaluatePredicate(
+  predicate: Predicate,
+  row: Readonly<Record<string, unknown>>,
+): TruthValue {
+  switch (predicate.kind) {
+    case 'const':
+      return predicate.value
+    case 'compare':
+      return compare(row[predicate.column], predicate.op, predicate.value)
+    case 'null': {
+      const result = row[predicate.column] === null || row[predicate.column] === undefined
+      return predicate.negated ? !result : result
+    }
+    case 'in': {
+      if (predicate.values.length === 0) return predicate.negated
+      const value = row[predicate.column]
+      if (value === null || value === undefined) return null
+      if (predicate.values.some((candidate) => candidate === value)) return !predicate.negated
+      const result: TruthValue = predicate.values.some((candidate) => candidate === null)
+        ? null
+        : false
+      return predicate.negated ? not(result) : result
+    }
+    case 'and':
+      return and(predicate.predicates.map((entry) => evaluatePredicate(entry, row)))
+    case 'or':
+      return or(predicate.predicates.map((entry) => evaluatePredicate(entry, row)))
+    case 'not':
+      return not(evaluatePredicate(predicate.predicate, row))
+  }
+}
+
+/** Whether a row is visible under a ward. Unknown (`null`) is not visible. */
+export function rowAllowedByWard(
+  predicate: Predicate,
+  row: Readonly<Record<string, unknown>>,
+): boolean {
+  return evaluatePredicate(predicate, row) === true
+}
+
+export interface CompiledSql {
+  /** Parameterized SQL boolean expression. */
+  sql: string
+  /** Ordered parameter values referenced as `$1`, `$2`, ... */
+  params: readonly unknown[]
+}
+
+function quoteIdent(identifier: string): string {
+  if (!IDENTIFIER.test(identifier)) throw refused('non-identifier column names')
+  return `"${identifier}"`
+}
+
+function emit(predicate: Predicate, params: unknown[]): string {
+  switch (predicate.kind) {
+    case 'const':
+      return predicate.value ? 'TRUE' : 'FALSE'
+    case 'compare': {
+      params.push(predicate.value)
+      const placeholder = `$${params.length}`
+      const op =
+        predicate.op === 'ilike' ? 'ILIKE' : predicate.op === 'like' ? 'LIKE' : predicate.op
+      return `${quoteIdent(predicate.column)} ${op} ${placeholder}`
+    }
+    case 'null':
+      return `${quoteIdent(predicate.column)} IS${predicate.negated ? ' NOT' : ''} NULL`
+    case 'in': {
+      if (predicate.values.length === 0) return predicate.negated ? 'TRUE' : 'FALSE'
+      const placeholders = predicate.values.map((value) => {
+        params.push(value)
+        return `$${params.length}`
+      })
+      const expr = `${quoteIdent(predicate.column)} IN (${placeholders.join(', ')})`
+      return predicate.negated ? `NOT (${expr})` : expr
+    }
+    case 'and': {
+      if (predicate.predicates.length === 0) return 'TRUE'
+      return `(${predicate.predicates.map((entry) => emit(entry, params)).join(' AND ')})`
+    }
+    case 'or': {
+      if (predicate.predicates.length === 0) return 'FALSE'
+      return `(${predicate.predicates.map((entry) => emit(entry, params)).join(' OR ')})`
+    }
+    case 'not':
+      return `(NOT ${emit(predicate.predicate, params)})`
+  }
+}
+
+/** Compiles a portable predicate to a parameterized SQL boolean expression. */
+export function compilePredicateToSql(predicate: Predicate): CompiledSql {
+  const params: unknown[] = []
+  return { sql: emit(predicate, params), params }
+}
+
+const ACTION_TO_SQL = {
+  read: 'SELECT',
+  insert: 'INSERT',
+  update: 'UPDATE',
+  delete: 'DELETE',
+} as const
+
+/** Compiles one ward ability into a Postgres RLS policy statement. */
+export function compileWardPolicy(
+  resource: ResourceKey,
+  action: WardAction,
+  actor: GateActor,
+  role = 'authenticated',
+): { statement: string; params: readonly unknown[] } {
+  const table = wards.get(resourceName(resource))?.table ?? resourceTable(resource)
+  const predicate = resolveWard(resource, action, actor)
+  const compiled = compilePredicateToSql(predicate)
+  const command = ACTION_TO_SQL[action]
+  const policyName = `${table}_${action}`
+  const clause = action === 'insert' ? 'WITH CHECK' : 'USING'
+  const statement = `CREATE POLICY ${quoteIdent(policyName)} ON ${quoteIdent(table)} AS PERMISSIVE FOR ${command} TO ${quoteIdent(role)} ${clause} (${compiled.sql})`
+  return { statement, params: compiled.params }
+}
+
+export interface WardFixture {
+  /** Row offered to the client-side evaluator. */
+  row: Readonly<Record<string, unknown>>
+  /** Whether the row must be visible. */
+  allowed: boolean
+}
+
+export interface WardDrift {
+  row: Readonly<Record<string, unknown>>
+  expected: boolean
+  actual: boolean
+}
+
+/**
+ * Compares client-side evaluation against a fixture set. A mismatch is a drift failure, which is
+ * how `ward:check` will later fail CI.
+ */
+export function detectWardDrift(
+  predicate: Predicate,
+  fixtures: readonly WardFixture[],
+): readonly WardDrift[] {
+  return fixtures.flatMap((fixture) => {
+    const actual = rowAllowedByWard(predicate, fixture.row)
+    if (actual === fixture.allowed) return []
+    return [{ row: fixture.row, expected: fixture.allowed, actual }]
+  })
+}
+
+/** Compares a freshly compiled policy statement to a previously recorded one. */
+export function detectPolicyDrift(currentSql: string, recordedSql: string): boolean {
+  return currentSql !== recordedSql
+}