chapter 8: production readiness

interface AccessConfigInput<
  TActions extends readonly string[],
  TResources extends readonly string[],
  TScopes extends readonly string[] = readonly string[],
  TRoles extends readonly string[] = readonly string[],
> {
  readonly actions: TActions
  readonly resources: TResources
  readonly scopes?: TScopes     // optional -- defaults to string (unconstrained)
  readonly roles?: TRoles       // optional -- defaults to string (unconstrained)
}

const access = defineIam({
  actions: ['read', 'write', 'delete'] as const,
  resources: ['post', 'comment'] as const,
  // no scopes -- single-tenant app
})

import type { InferAction, InferResource, InferScope } from '@gentleduck/iam'

const config = {
  actions: ['create', 'read', 'update', 'delete'] as const,
  resources: ['post', 'comment', 'user'] as const,
  scopes: ['acme', 'globex'] as const,
}

type Action = InferAction<typeof config>
// 'create' | 'read' | 'update' | 'delete'

type Resource = InferResource<typeof config>
// 'post' | 'comment' | 'user'

type Scope = InferScope<typeof config>
// 'acme' | 'globex'

// Type definitions
type InferAction<S extends { actions: readonly string[] }> = S['actions'][number]
type InferResource<S extends { resources: readonly string[] }> = S['resources'][number]
type InferScope<S extends { scopes: readonly string[] }> = S['scopes'][number]

interface Adapter<TAction, TResource, TRole, TScope>
  extends PolicyStore<TAction, TResource, TRole>,
    RoleStore<TAction, TResource, TRole, TScope>,
    SubjectStore<TRole, TScope> {}

interface PolicyStore<TAction, TResource, TRole> {
  listPolicies(): Promise<Policy<TAction, TResource, TRole>[]>
  getPolicy(id: string): Promise<Policy<TAction, TResource, TRole> | null>
  savePolicy(policy: Policy<TAction, TResource, TRole>): Promise<void>
  deletePolicy(id: string): Promise<void>
}

interface RoleStore<TAction, TResource, TRole, TScope> {
  listRoles(): Promise<Role<TAction, TResource, TRole, TScope>[]>
  getRole(id: string): Promise<Role<TAction, TResource, TRole, TScope> | null>
  saveRole(role: Role<TAction, TResource, TRole, TScope>): Promise<void>
  deleteRole(id: string): Promise<void>
}

interface SubjectStore<TRole, TScope> {
  getSubjectRoles(subjectId: string): Promise<TRole[]>
  getSubjectScopedRoles?(subjectId: string): Promise<ScopedRole<TRole, TScope>[]>
  assignRole(subjectId: string, roleId: TRole, scope?: TScope): Promise<void>
  revokeRole(subjectId: string, roleId: TRole, scope?: TScope): Promise<void>
  getSubjectAttributes(subjectId: string): Promise<Attributes>
  setSubjectAttributes(subjectId: string, attrs: Attributes): Promise<void>
}

const [assignedRoles, attributes, allRoles] = await Promise.all([
  this.adapter.getSubjectRoles(subjectId),
  this.adapter.getSubjectAttributes(subjectId),
  this.loadRoles(),   // cached separately
])

const roles = resolveEffectiveRoles(assignedRoles, allRoles)

const scopedRoles = this.adapter.getSubjectScopedRoles
  ? await this.adapter.getSubjectScopedRoles(subjectId)
  : undefined

const subject: Subject = { id: subjectId, roles, scopedRoles, attributes }

import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'

const adapter = new IamMemoryAdapter({
  policies: [ownerPolicy],
  roles: [viewer, editor, admin],
  assignments: {
    'alice': ['viewer'],
    'bob': ['editor'],
    'charlie': ['admin'],
  },
  attributes: {
    'alice': { department: 'engineering' },
  },
})

interface MemoryAdapterInit<TAction, TResource, TRole, TScope> {
  policies?: Policy<TAction, TResource, TRole>[]
  roles?: Role<TAction, TResource, TRole, TScope>[]
  assignments?: Record<string, TRole[]>         // subjectId -> base roles
  attributes?: Record<string, Attributes>        // subjectId -> attributes
}

import { IamPrismaAdapter } from '@gentleduck/iam/adapters/prisma'
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()
const adapter = new IamPrismaAdapter(prisma)

model accessPolicy {
  id          String  @id
  name        String
  description String?
  version     Int     @default(1)
  algorithm   String
  rules       Json
  targets     Json?
}

model accessRole {
  id          String  @id
  name        String
  description String?
  permissions Json
  inherits    Json    @default("[]")
  scope       String?
  metadata    Json?
}

model accessAssignment {
  subjectId String
  roleId    String
  scope     String?

  @@id([subjectId, roleId, scope])
}

model accessSubjectAttr {
  subjectId String @id
  data      Json
}

import { IamDrizzleAdapter } from '@gentleduck/iam/adapters/drizzle'
import { db } from './db'
import { eq, and } from 'drizzle-orm'
import * as tables from './schema'

const adapter = new IamDrizzleAdapter({
  db,
  tables: {
    policies: tables.iamPolicies,
    roles: tables.iamRoles,
    assignments: tables.iamAssignments,
    attrs: tables.iamSubjectAttrs,
  },
  ops: { eq, and },
})

interface IamDrizzle.IConfig {
  db: {
    select: () => { from: (table: unknown) => DrizzleQuery }
    insert: (table: unknown) => { values: (data: Record<string, unknown>) => DrizzleInsert }
    delete: (table: unknown) => { where: (condition: unknown) => Promise<unknown> }
  }
  tables: {
    policies: DrizzleTable
    roles: DrizzleTable
    assignments: DrizzleTable
    attrs: DrizzleTable
  }
  ops: {
    eq: (col: unknown, val: unknown) => unknown
    and: (...conditions: unknown[]) => unknown
  }
}

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'

export const iamPolicies = sqliteTable('access_policies', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  description: text('description'),
  version: integer('version').notNull().default(1),
  algorithm: text('algorithm').notNull(),
  rules: text('rules').notNull(),        // JSON string
  targets: text('targets'),              // JSON string or null
})

export const iamRoles = sqliteTable('access_roles', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  description: text('description'),
  permissions: text('permissions').notNull(),  // JSON string
  inherits: text('inherits').notNull().default('[]'),
  scope: text('scope'),
  metadata: text('metadata'),
})

export const iamAssignments = sqliteTable('access_assignments', {
  subjectId: text('subject_id').notNull(),
  roleId: text('role_id').notNull(),
  scope: text('scope'),
}, (t) => ({
  pk: primaryKey(t.subjectId, t.roleId, t.scope),
}))

export const iamSubjectAttrs = sqliteTable('access_subject_attrs', {
  subjectId: text('subject_id').primaryKey(),
  data: text('data').notNull(),   // JSON string
})

import { IamHttpAdapter } from '@gentleduck/iam/adapters/http'

const adapter = new IamHttpAdapter({
  baseUrl: 'https://auth.internal.company.com/access',
  headers: () => ({
    Authorization: `Bearer ${getServiceToken()}`,
  }),
})

interface HttpAdapterConfig {
  /** Base URL of your duck-iam API, e.g. "https://api.example.com/access" */
  baseUrl: string
  /** Custom fetch function (defaults to globalThis.fetch) */
  fetch?: typeof globalThis.fetch
  /** Headers to include -- static object or async function */
  headers?: Record<string, string>
    | (() => Record<string, string> | Promise<Record<string, string>>)
}

import type { IamAdapter, Attributes, Policy, Role, ScopedRole } from '@gentleduck/iam'

export class MongoAdapter implements Adapter {
  constructor(private db: Db) {}

  // PolicyStore
  async listPolicies(): Promise<Policy[]> {
    return this.db.collection('policies').find().toArray()
  }
  async getPolicy(id: string): Promise<Policy | null> {
    return this.db.collection('policies').findOne({ id })
  }
  async savePolicy(p: Policy): Promise<void> {
    await this.db.collection('policies').updateOne(
      { id: p.id }, { $set: p }, { upsert: true }
    )
  }
  async deletePolicy(id: string): Promise<void> {
    await this.db.collection('policies').deleteOne({ id })
  }

  // RoleStore
  async listRoles(): Promise<Role[]> {
    return this.db.collection('roles').find().toArray()
  }
  async getRole(id: string): Promise<Role | null> {
    return this.db.collection('roles').findOne({ id })
  }
  async saveRole(r: Role): Promise<void> {
    await this.db.collection('roles').updateOne(
      { id: r.id }, { $set: r }, { upsert: true }
    )
  }
  async deleteRole(id: string): Promise<void> {
    await this.db.collection('roles').deleteOne({ id })
  }

  // SubjectStore
  async getSubjectRoles(subjectId: string): Promise<string[]> {
    const rows = await this.db.collection('assignments')
      .find({ subjectId, scope: null }).toArray()
    return rows.map(r => r.roleId)
  }
  async getSubjectScopedRoles(subjectId: string): Promise<ScopedRole[]> {
    const rows = await this.db.collection('assignments')
      .find({ subjectId, scope: { $ne: null } }).toArray()
    return rows.map(r => ({ role: r.roleId, scope: r.scope }))
  }
  async assignRole(subjectId: string, roleId: string, scope?: string): Promise<void> {
    await this.db.collection('assignments').updateOne(
      { subjectId, roleId, scope: scope ?? null },
      { $set: { subjectId, roleId, scope: scope ?? null } },
      { upsert: true }
    )
  }
  async revokeRole(subjectId: string, roleId: string, scope?: string): Promise<void> {
    await this.db.collection('assignments').deleteOne({
      subjectId, roleId, scope: scope ?? null,
    })
  }
  async getSubjectAttributes(subjectId: string): Promise<Attributes> {
    const doc = await this.db.collection('subject_attrs').findOne({ subjectId })
    return doc?.data ?? {}
  }
  async setSubjectAttributes(subjectId: string, attrs: Attributes): Promise<void> {
    const existing = await this.getSubjectAttributes(subjectId)
    const merged = { ...existing, ...attrs }
    await this.db.collection('subject_attrs').updateOne(
      { subjectId },
      { $set: { subjectId, data: merged } },
      { upsert: true }
    )
  }
}

class IamLRUCache<V> {
  private map = new Map<string, { value: V; expiresAt: number }>()
  private maxSize: number
  private ttl: number

  constructor(maxSize: number, ttlMs: number) { ... }
  get(key: string): V | undefined { ... }
  set(key: string, value: V): void { ... }
  delete(key: string): boolean { ... }
  clear(): void { ... }
  get size(): number { ... }
}

const ttl = (config.cacheTTL ?? 60) * 1000  // config is in seconds, stored in ms

// Clear everything (nuclear option)
engine.cache.invalidate()

// Clear only one user's cache (after external change)
engine.cache.invalidateSubject('alice')

// Clear policy cache (after external DB update)
engine.cache.invalidatePolicies()

// Clear role caches + all subjects (after external role change)
engine.cache.invalidateRoles()

// Validate roles
const roleCheck = access.validateRoles([viewer, editor, admin])
if (!roleCheck.valid) {
  throw new Error(
    'Role config error: ' +
    roleCheck.issues.map(i => `[${i.type}] ${i.message}`).join(', ')
  )
}

// Validate policies
const policyCheck = access.validatePolicy(ownerPolicy)
if (!policyCheck.valid) {
  throw new Error(
    'Policy config error: ' +
    policyCheck.issues.map(i => `[${i.type}] ${i.message}`).join(', ')
  )
}

interface ValidationResult {
  readonly valid: boolean                   // true if no errors (warnings are OK)
  readonly issues: readonly ValidationIssue[]
}

interface ValidationIssue {
  readonly type: 'error' | 'warning'
  readonly code: string                    // machine-readable code
  readonly message: string                 // human-readable description
  readonly roleId?: string                 // which role (for role validation)
  readonly path?: string                   // JSON path (for policy validation)
}

// If beforeEvaluate throws, or the adapter fails, result is deny
const result = await engine.can('user', 'read', { type: 'post', attributes: {} })
// result === false (on error)

// Inside engine.authorize():
catch (error) {
  if (this.hooks.onError) {
    await this.hooks.onError(error as Error, req)
  }
  return {
    allowed: false,
    effect: 'deny',
    reason: `Evaluation error: ${error.message}`,
    duration: 0,
    timestamp: Date.now(),
  }
}

const ALLOWED_ROOTS = new Set(['subject', 'resource', 'environment'])
const BLOCKED_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype'])

// These paths are blocked and return null:
// __proto__.constructor     -- blocked root
// subject.__proto__.pollute -- blocked segment
// constructor.prototype     -- blocked root AND segment
// resource.attributes.constructor -- blocked segment

if (path === 'action') return request.action
if (path === 'scope') return request.scope ?? null

const MAX_REGEX_LENGTH = 512
const REGEX_CACHE_MAX = 256

function getCachedRegex(pattern: string): RegExp | null {
  const cached = iamRegexCache.get(pattern)
  if (cached) return cached
  try {
    const re = new RegExp(pattern)
    if (iamRegexCache.size >= REGEX_CACHE_MAX) {
      const first = iamRegexCache.keys().next().value
      if (first !== undefined) iamRegexCache.delete(first)
    }
    iamRegexCache.set(pattern, re)
    return re
  } catch {
    return null   // invalid regex -> fail closed
  }
}

const MAX_CONDITION_DEPTH = 10

function evalConditionGroup(req, group, depth = 0): boolean {
  if (depth >= MAX_CONDITION_DEPTH) {
    return false  // Deny when nesting is too deep
  }
  // ...evaluate children with depth + 1
}

function resolveValue(req: AccessRequest, value: AttributeValue): AttributeValue {
  if (typeof value === 'string' && value.startsWith('$')) {
    return resolve(req, value.slice(1))  // strip '$' and resolve
  }
  return value
}

export const engine = access.createEngine({
  adapter,
  mode: 'production',   // ~2x faster, no Decision objects
  cacheTTL: 60,
  maxCacheSize: 1000,
})

// This throws in production mode
const trace = await engine.explain('alice', 'read', {
  type: 'post', attributes: {},
})
// Error: explain() is unavailable in production mode

import { evaluateFast } from '@gentleduck/iam'

const allowed = evaluateFast(
  [ownerPolicy, rbacPolicy],
  {
    subject: { id: 'bob', roles: ['editor'], attributes: {} },
    action: 'update',
    resource: { type: 'post', id: 'post-1', attributes: { ownerId: 'bob' } },
  }
)
// allowed: boolean