Chapter 4: the engine in depth

import type { IamRequest } from '@gentleduck/iam'

const request: IamRequest.IAccessRequest = {
  subject: { id: 'bob', roles: ['editor', 'viewer'], attributes: { department: 'engineering' } },
  action: 'update',
  resource: { type: 'document', id: 'doc-2', attributes: { ownerId: 'alice', status: 'published' } },
  environment: { ip: '203.0.113.7' },
}

const decision = await engine.authorize(request)

const dev = new IamEngine({ adapter, mode: 'development' })
const prod = new IamEngine({ adapter })                       // mode defaults to 'production'

interface IHooks {
  beforeEvaluate?(request): IAccessRequest | Promise<IAccessRequest>
  afterEvaluate?(request, decision): void | Promise<void>
  onDeny?(request, decision): void | Promise<void>
  onError?(error: Error, request): void | Promise<void>
  onPolicyError?(error: Error, policyId: string): void
  onMetrics?(event: IamEngineTypes.IMetricsEvent): void
  onMutation?(event: IamEngineTypes.IMutationEvent): void | Promise<void>
}

interface IMetricsEvent {
  readonly subjectId: string
  readonly action: string
  readonly resource: string
  readonly allowed: boolean
  readonly durationMs: number
  readonly mode: 'development' | 'production'
  readonly failOpen: boolean
}

import type { IamPrimitives } from '@gentleduck/iam'

export interface Document {
  readonly id: string
  readonly ownerId: string
  readonly teamId: string
  readonly status: 'draft' | 'published' | 'archived'
}

const store = new Map<string, Document>([
  ['doc-1', { id: 'doc-1', ownerId: 'bob', teamId: 'team-acme', status: 'published' }],
  ['doc-2', { id: 'doc-2', ownerId: 'alice', teamId: 'team-acme', status: 'published' }],
  ['doc-3', { id: 'doc-3', ownerId: 'alice', teamId: 'team-acme', status: 'draft' }],
  ['doc-4', { id: 'doc-4', ownerId: 'bob', teamId: 'team-globex', status: 'archived' }],
])

export async function findDocument(id: string): Promise<Document | undefined> {
  return store.get(id)
}

export function documentAttributes(doc: Document): IamPrimitives.Attributes {
  return { ownerId: doc.ownerId, teamId: doc.teamId, status: doc.status }
}

async beforeEvaluate(request) {
  if (request.resource.type !== 'document' || !request.resource.id) return request
  const doc = await findDocument(request.resource.id)
  if (!doc) return request
  return {
    ...request,
    resource: {
      ...request.resource,
      attributes: { ...documentAttributes(doc), ...request.resource.attributes },
    },
  }
}

const s = engine.stats.get()
// {
//   policies:       { hits: 0, misses: 1, size: 1 },
//   roles:          { hits: 3, misses: 1, size: 1 },
//   rbacPolicy:     { hits: 0, misses: 1, size: 1 },
//   mergedPolicies: { hits: 8, misses: 1, size: 1 },
//   subjects:       { hits: 6, misses: 3, size: 3 },
// }
engine.stats.reset()

const perms = await engine.permissions('bob', [
  { action: 'read', resource: 'document', resourceId: 'doc-2' },
  { action: 'update', resource: 'document', resourceId: 'doc-2' },
  { action: 'delete', resource: 'document', resourceId: 'doc-1' },
  { action: 'manage', resource: 'team' },
])
// {
//   'read:document:doc-2': true,
//   'update:document:doc-2': false,
//   'delete:document:doc-1': false,
//   'manage:team': false,
// }

interface IPermissionCheck {
  readonly action: string
  readonly resource: string
  readonly resourceId?: string
  readonly scope?: string
}

const trace = await engine.explain('bob', 'update', { type: 'document', id: 'doc-2', attributes: {} })
console.log(trace.summary)

DENIED: "bob" attempting update on document
  Roles: [editor, viewer]
  __rbac__ [allow-overrides]: Allowed by rule "__rbac__#5" (1/16 rules matched)
  document-ownership [deny-overrides]: Denied by rule "deny-non-owner-write" (2/2 rules matched)
  document-lifecycle [deny-overrides]: Allowed by rule "allow-otherwise" (1/3 rules matched)
  Result: Denied by rule "deny-non-owner-write"

interface IResult {
  readonly decision: AccessControl.IDecision
  readonly request: { action: string; resourceType: string; resourceId?: string; scope?: string }
  readonly subject: {
    id: string
    roles: readonly string[]
    scopedRolesApplied: readonly string[]
    attributes: Readonly<Record<string, IamPrimitives.AttributeValue>>
  }
  readonly policies: readonly Explain.IPolicyTrace[]
  readonly summary: string
}

await engine.admin.savePolicy(policy)          // invalidates the policy cache
await engine.admin.deletePolicy('old-policy')  // invalidates the policy cache
await engine.admin.saveRole(role)              // invalidates roles + subjects holding role.id
await engine.admin.deleteRole('reviewer')      // invalidates roles + subjects holding that ID
await engine.admin.assignRole('alice', 'editor')          // invalidates alice
await engine.admin.revokeRole('alice', 'editor')          // invalidates alice
await engine.admin.assignRole('alice', 'admin', 'team-acme')  // scoped, chapter 5
await engine.admin.updateAssignmentScope('alice', 'admin', 'team-acme', 'team-globex')
await engine.admin.setAttributes('bob', { department: 'platform' })  // merges, invalidates bob
const attrs = await engine.admin.getAttributes('bob')

const snapshot = await engine.admin.export()
// { schemaVersion: 1, exportedAt: '2026-09-02T...', policies: [...], roles: [...] }

const result = await engine.admin.import(snapshot, { mode: 'merge' })
// { policiesAdded, policiesDeleted, rolesAdded, rolesDeleted }

await engine.preload()                    // warm policies, roles, __rbac__, merged set
await engine.preload({ validator: true }) // also pull in the lazy validator chunk
const health = await engine.healthCheck() // { ok, adapter, cacheHitRate, adapterLatencyMs, lastError? }
engine.dispose()                          // release the invalidator subscription

docduck/
  src/
    roles.ts      - three roles, inheritance, startup validation
    policies.ts   - two ABAC policies
    documents.ts  - the tiny document store the hook reads
    access.ts     - adapter, hooks, engine
    main.ts       - the demo script
  package.json
  tsconfig.json

import { defineRole } from '@gentleduck/iam'
import { validateRoles } from '@gentleduck/iam/core/validate'

export const viewer = defineRole('viewer')
  .name('Viewer')
  .desc('Read-only access to documents and teams')
  .grant('read', 'document')
  .grant('read', 'team')
  .build()

export const editor = defineRole('editor')
  .name('Editor')
  .desc('Writes documents')
  .inherits('viewer')
  .grant('create', 'document')
  .grant('update', 'document')
  .grant('share', 'document')
  .build()

export const admin = defineRole('admin')
  .name('Administrator')
  .desc('Manages teams and their members')
  .inherits('editor')
  .grant('delete', 'document')
  .grant('archive', 'document')
  .grant('manage', 'team')
  .grant('manage', 'user')
  .meta({ tier: 'staff' })
  .build()

export const roles = [viewer, editor, admin]

const check = validateRoles(roles)
if (!check.valid) {
  throw new Error(check.issues.map((i) => `[${i.code}] ${i.message}`).join('; '))
}
for (const issue of check.issues) {
  if (issue.type === 'warning') console.warn(`[iam] ${issue.code}: ${issue.message}`)
}

import { definePolicy } from '@gentleduck/iam'

export const ownershipPolicy = definePolicy('document-ownership')
  .name('Document ownership')
  .desc('Writes to a document are limited to its author, unless the subject is an admin')
  .version(1)
  .algorithm('deny-overrides')
  .target({ actions: ['update', 'delete', 'share'], resources: ['document'] })
  .rule('deny-non-owner-write', (r) =>
    r
      .deny()
      .desc('Only the author may write, admins excepted')
      .priority(100)
      .on('update', 'delete', 'share')
      .of('document')
      .when((w) => w.resourceAttr('ownerId', 'neq', '$subject.id').not((n) => n.role('admin'))),
  )
  .rule('allow-owner-write', (r) =>
    r
      .allow()
      .desc('Nothing above objected, so this policy consents')
      .priority(1)
      .on('update', 'delete', 'share')
      .of('document'),
  )
  .build()

export const lifecyclePolicy = definePolicy('document-lifecycle')
  .name('Document lifecycle')
  .desc('Drafts are visible only to their author; archived documents are read-only')
  .version(1)
  .algorithm('deny-overrides')
  .target({ resources: ['document'] })
  .rule('deny-foreign-drafts', (r) =>
    r
      .deny()
      .desc('A draft is visible only to its author')
      .priority(60)
      .on('read')
      .of('document')
      .when((w) => w.resourceAttr('status', 'eq', 'draft').resourceAttr('ownerId', 'neq', '$subject.id')),
  )
  .rule('deny-archived-writes', (r) =>
    r
      .deny()
      .desc('Archived documents cannot be modified')
      .priority(60)
      .on('update', 'delete', 'share')
      .of('document')
      .when((w) => w.resourceAttr('status', 'eq', 'archived')),
  )
  .rule('allow-otherwise', (r) =>
    r.allow().desc('No lifecycle objection').priority(1).on('*').of('document'),
  )
  .build()

export const policies = [ownershipPolicy, lifecyclePolicy]

import type { IamPrimitives } from '@gentleduck/iam'

export interface Document {
  readonly id: string
  readonly ownerId: string
  readonly teamId: string
  readonly status: 'draft' | 'published' | 'archived'
}

const store = new Map<string, Document>([
  ['doc-1', { id: 'doc-1', ownerId: 'bob', teamId: 'team-acme', status: 'published' }],
  ['doc-2', { id: 'doc-2', ownerId: 'alice', teamId: 'team-acme', status: 'published' }],
  ['doc-3', { id: 'doc-3', ownerId: 'alice', teamId: 'team-acme', status: 'draft' }],
  ['doc-4', { id: 'doc-4', ownerId: 'bob', teamId: 'team-globex', status: 'archived' }],
])

export async function findDocument(id: string): Promise<Document | undefined> {
  return store.get(id)
}

export function documentAttributes(doc: Document): IamPrimitives.Attributes {
  return { ownerId: doc.ownerId, teamId: doc.teamId, status: doc.status }
}

import { IamEngine, type IamEngineTypes } from '@gentleduck/iam'
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { documentAttributes, findDocument } from './documents'
import { policies } from './policies'
import { roles } from './roles'

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

const hooks: IamEngineTypes.IHooks = {
  async beforeEvaluate(request) {
    if (request.resource.type !== 'document' || !request.resource.id) return request
    const doc = await findDocument(request.resource.id)
    if (!doc) return request
    return {
      ...request,
      resource: {
        ...request.resource,
        attributes: { ...documentAttributes(doc), ...request.resource.attributes },
      },
    }
  },
  afterEvaluate(request, decision) {
    console.log(
      `[audit] ${request.subject.id} ${decision.effect} ${request.action} on ${request.resource.type}:${request.resource.id ?? '*'}`,
    )
  },
  onDeny(request, decision) {
    console.warn(`[denied] ${request.subject.id} ${request.action} ${request.resource.type}: ${decision.reason}`)
  },
  onError(error, request) {
    console.error(`[iam:error] ${request.subject.id} ${request.action}: ${error.message}`)
  },
  onPolicyError(error, policyId) {
    console.error(`[iam:policy] "${policyId}" threw and was skipped: ${error.message}`)
  },
  onMetrics(event) {
    if (event.failOpen) console.error('[iam:fail-open]', event)
    if (event.durationMs > 5) console.warn(`[iam:slow] ${event.action}:${event.resource} ${event.durationMs}ms`)
  },
}

export const engine = new IamEngine({
  adapter,
  hooks,
  defaultEffect: 'deny',
  mode: 'development',
  cacheTTL: 60,
  maxCacheSize: 1000,
  policyCombine: 'and',
  adapterTimeoutMs: 5_000,
})

import { engine } from './access'

const doc = (id: string) => ({ type: 'document', id, attributes: {} })

async function main() {
  await engine.preload()

  console.log(await engine.can('bob', 'update', doc('doc-1')))    // true
  console.log(await engine.can('bob', 'update', doc('doc-2')))    // false
  console.log(await engine.can('carol', 'update', doc('doc-2')))  // true
  console.log(await engine.can('bob', 'read', doc('doc-3')))      // false
  console.log(await engine.can('bob', 'update', doc('doc-4')))    // false

  const perms = await engine.permissions('bob', [
    { action: 'read', resource: 'document', resourceId: 'doc-2' },
    { action: 'update', resource: 'document', resourceId: 'doc-2' },
    { action: 'delete', resource: 'document', resourceId: 'doc-1' },
    { action: 'manage', resource: 'team' },
  ])
  console.log(perms)
  // { 'read:document:doc-2': true, 'update:document:doc-2': false,
  //   'delete:document:doc-1': false, 'manage:team': false }

  const trace = await engine.explain('bob', 'update', doc('doc-2'))
  console.log(trace.summary)

  await engine.admin.assignRole('alice', 'editor')
  console.log(await engine.getEffectiveRoles('alice'))            // [ 'viewer', 'editor' ]
  console.log(await engine.can('alice', 'update', doc('doc-2')))  // true

  console.log(engine.stats.get().subjects)
  console.log(await engine.healthCheck())

  engine.dispose()
}

void main()