@seifer-webapp-factory/authorization 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @seifer-webapp-factory/authorization
+
+Tweede **capability-module**: verticale, pluggable full-stack autorisatie-feature (RBAC + rol-hiërarchie,
+rol-toewijzing, default-deny-enforcement via een PDP-guard, optionele ReBAC-ownership, en een admin-UI
+voor rollen/permissies/toewijzingen) die de `@seifer-webapp-factory/kits` samenbindt via één contract.
+
+De **eerste module met een module→module-afhankelijkheid**: `requires.modules: ['authentication']`. Ze
+consumeert het geauthenticeerde `Subject` uit de auth-sessie (via de `SubjectProvider`-port) en levert de
+effectieve permissies terug die de sessie draagt.
+
+- Mechanisme (pinned dependency): `@seifer-webapp-factory/authorization/{contract,backend,frontend,manifest,scaffolder}`.
+- Surface (gematerialiseerd, project-eigendom): `backend/templates`, `frontend/templates`.
+- Composeert de `access-control`-kit (RBAC/hiërarchie/enforcement/ReBAC/PDP) — voegt **geen** nieuw
+  mechanisme toe.
+
+Zie `../authorization.md` (plan, met de gelockte best-practice-beslissingen) en `./` (backlog: 10 epics,
+22 features, 44 user stories) in de monorepo.

package/backend/templates/cache/ttl-cache.ts

@@ -0,0 +1,41 @@
+/**
+ * US-Z0402 — Een in-memory {@link PermissionCache} met een korte TTL per entry. De resolver
+ * invalideert expliciet bij elke mutatie (grant/revoke/role-change); de TTL is enkel een vangnet zodat
+ * een gemiste invalidatie nooit langer dan `ttlSeconds` stale blijft. De klok wordt geïnjecteerd zodat
+ * de vervaltijd deterministisch te testen is (geen `Date.now()` in de cache zelf).
+ */
+import type { Clock, PermissionCache, ResolvedAccess } from '../../src/index.js';
+
+interface CacheEntry {
+  value: ResolvedAccess;
+  /** Absolute vervaltijd in ms sinds epoch (via de geïnjecteerde klok). */
+  expiresAt: number;
+}
+
+/** Bouwt een TTL-cache; `ttlSeconds` komt uit de config (`cacheTtlSeconds`). */
+export function ttlPermissionCache(ttlSeconds: number, clock: Clock): PermissionCache {
+  const store = new Map<string, CacheEntry>();
+  const nowMs = (): number => clock.now().getTime();
+
+  return {
+    async get(subjectId: string): Promise<ResolvedAccess | null> {
+      const entry = store.get(subjectId);
+      if (entry === undefined) return null;
+      // Verlopen entries worden lui opgeruimd bij het lezen.
+      if (entry.expiresAt <= nowMs()) {
+        store.delete(subjectId);
+        return null;
+      }
+      return entry.value;
+    },
+    async set(subjectId: string, value: ResolvedAccess): Promise<void> {
+      store.set(subjectId, { value, expiresAt: nowMs() + ttlSeconds * 1000 });
+    },
+    async invalidate(subjectId: string): Promise<void> {
+      store.delete(subjectId);
+    },
+    async clear(): Promise<void> {
+      store.clear();
+    },
+  };
+}

package/backend/templates/config/config-fragment.ts

@@ -0,0 +1,41 @@
+/**
+ * US-Z0603 — Config-fragment voor de authorization-capability. Een Zod-schema dat de host in zijn eigen
+ * app-config-schema mengt (config-kit). Bevat geen secrets. De defaults maken de module direct bruikbaar:
+ * RBAC-only, harde enforcement, korte cache-TTL en een minimale set default-rollen (admin + member).
+ */
+import { z } from 'zod';
+import { AUTHZ_MANAGE } from '../../../contract/index.js';
+
+/** Eén default-rol: sleutel + weergavenaam + permissie-sleutels. */
+export const defaultRoleSchema = z.object({
+  key: z.string().min(1).max(64),
+  name: z.string().min(1).max(128),
+  permissions: z.array(z.string().min(1)).default([]),
+});
+
+/** Het volledige authorization-config-fragment. */
+export const authzConfigSchema = z.object({
+  /** Autorisatie-model: puur RBAC, of RBAC + ReBAC (ownership/relatie-checks, US-Z0501). */
+  model: z.enum(['rbac', 'rbac+rebac']).default('rbac'),
+  /** `enforce` = weiger bij ontbrekende permissie; `shadow` = log-only, laat door (US-Z0704). */
+  enforcementMode: z.enum(['enforce', 'shadow']).default('enforce'),
+  /** Korte TTL (seconden) van de opgeloste-permissies-cache (US-Z0402). */
+  cacheTtlSeconds: z.number().int().positive().default(30),
+  /** Rollen die bij een verse installatie worden geseed (US-Z0603/Z0702). */
+  defaultRoles: z
+    .array(defaultRoleSchema)
+    .default([
+      { key: 'admin', name: 'Beheerder', permissions: [AUTHZ_MANAGE] },
+      { key: 'member', name: 'Lid', permissions: [] },
+    ]),
+  /** Het subject dat de eerste beheer-rol krijgt (bootstrap, US-Z0702). Optioneel. */
+  firstAdminSubjectId: z.string().min(1).optional(),
+});
+
+/** Het afgeleide, gevalideerde config-type. */
+export type AuthzConfig = z.infer<typeof authzConfigSchema>;
+
+/** Parse (met defaults) een ruwe config-invoer tot een `AuthzConfig`. */
+export function parseAuthzConfig(input: unknown = {}): AuthzConfig {
+  return authzConfigSchema.parse(input);
+}

package/backend/templates/nestjs/authz.controller.ts

@@ -0,0 +1,253 @@
+/**
+ * De NestJS-surface voor de 12 contract-endpoints (AUTHZ_ENDPOINTS). Puur *plumbing*: (1) resolveert de
+ * identiteit via de geïnjecteerde SubjectProvider, (2) bouwt de caller-`Actor` uit zijn effectieve
+ * permissies, (3) handhaaft `requiredPermission` (default-deny; in `shadow`-mode log-only, US-Z0704),
+ * (4) valideert de body met de contract-Zod-schema's, (5) roept de mechanism-service aan en (6) vertaalt
+ * een `AuthzError` via de gedeelde taxonomie naar HTTP. Denial-reasons lekken nooit policy-interne
+ * details (no-catalog-leak, US-Z0703).
+ *
+ * DI is EXPLICIET via `@Inject(TOKEN)` (geen type-based DI) zodat de controller onder vitest/esbuild
+ * draait zonder decorator-metadata.
+ */
+import {
+  Controller,
+  Delete,
+  Get,
+  HttpException,
+  Inject,
+  Param,
+  Patch,
+  Post,
+  Req,
+} from '@nestjs/common';
+import { ZodError, type ZodTypeAny, type z } from 'zod';
+import {
+  AUTHZ_ERROR_TAXONOMY,
+  AUTHZ_MANAGE,
+  AuthzError,
+  assignmentRequestSchema,
+  checkRequestSchema,
+  createRoleRequestSchema,
+  relationRequestSchema,
+  updateRoleRequestSchema,
+} from '../../../contract/index.js';
+import type { Actor, SubjectProvider } from '../../src/index.js';
+import {
+  AUTHZ_MODULE_DEPS,
+  AUTHZ_SUBJECT_PROVIDER,
+  AUTHZ_SURFACE_CONFIG,
+  type AuthzModuleDeps,
+  type AuthzSurfaceConfig,
+} from './tokens.js';
+
+/** Minimale request-vorm die de controller nodig heeft (geen harde framework-type-dep). */
+interface AuthzRequest {
+  body: unknown;
+}
+
+@Controller()
+export class AuthzController {
+  constructor(
+    @Inject(AUTHZ_MODULE_DEPS) private readonly deps: AuthzModuleDeps,
+    @Inject(AUTHZ_SUBJECT_PROVIDER) private readonly subjects: SubjectProvider,
+    @Inject(AUTHZ_SURFACE_CONFIG) private readonly surface: AuthzSurfaceConfig,
+  ) {}
+
+  // --- US-Z0201 GET /authz/roles ---
+  @Get('authz/roles')
+  async listRoles(@Req() req: AuthzRequest) {
+    try {
+      await this.authorize(req, AUTHZ_MANAGE);
+      return { roles: await this.deps.roles.list() };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0201 POST /authz/roles ---
+  @Post('authz/roles')
+  async createRole(@Req() req: AuthzRequest) {
+    try {
+      const actor = await this.authorize(req, AUTHZ_MANAGE);
+      const body = this.parse(createRoleRequestSchema, req.body);
+      return await this.deps.roles.create(actor, body);
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0202 PATCH /authz/roles/:id ---
+  @Patch('authz/roles/:id')
+  async updateRole(@Req() req: AuthzRequest, @Param('id') id: string) {
+    try {
+      const actor = await this.authorize(req, AUTHZ_MANAGE);
+      const body = this.parse(updateRoleRequestSchema, req.body);
+      return await this.deps.roles.update(actor, id, body);
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0201 DELETE /authz/roles/:id ---
+  @Delete('authz/roles/:id')
+  async deleteRole(@Req() req: AuthzRequest, @Param('id') id: string) {
+    try {
+      const actor = await this.authorize(req, AUTHZ_MANAGE);
+      await this.deps.roles.remove(actor, id);
+      return { ok: true as const };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0203 GET /authz/permissions ---
+  @Get('authz/permissions')
+  async listPermissions(@Req() req: AuthzRequest) {
+    try {
+      await this.authorize(req, AUTHZ_MANAGE);
+      return { permissions: this.deps.roles.permissions() };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0305 GET /authz/subjects/:id/roles ---
+  @Get('authz/subjects/:id/roles')
+  async subjectRoles(@Req() req: AuthzRequest, @Param('id') id: string) {
+    try {
+      await this.authorize(req, AUTHZ_MANAGE);
+      return { subjectId: id, roles: await this.deps.assignments.subjectRoles(id) };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0301 POST /authz/assignments ---
+  @Post('authz/assignments')
+  async assignRole(@Req() req: AuthzRequest) {
+    try {
+      const actor = await this.authorize(req, AUTHZ_MANAGE);
+      const body = this.parse(assignmentRequestSchema, req.body);
+      await this.deps.assignments.assign(actor, body.subjectId, body.roleId);
+      return { ok: true as const };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0303 DELETE /authz/assignments ---
+  @Delete('authz/assignments')
+  async revokeRole(@Req() req: AuthzRequest) {
+    try {
+      const actor = await this.authorize(req, AUTHZ_MANAGE);
+      const body = this.parse(assignmentRequestSchema, req.body);
+      await this.deps.assignments.revoke(actor, body.subjectId, body.roleId);
+      return { ok: true as const };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0401 GET /authz/me/permissions (alleen auth, geen authz.manage) ---
+  @Get('authz/me/permissions')
+  async mePermissions(@Req() req: AuthzRequest) {
+    try {
+      const actor = await this.authorize(req, null);
+      const resolved = await this.deps.resolver.resolve(actor.id);
+      return { subjectId: resolved.subjectId, roles: resolved.roleKeys, permissions: resolved.permissions };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0403 POST /authz/check (alleen auth, geen authz.manage) ---
+  @Post('authz/check')
+  async check(@Req() req: AuthzRequest) {
+    try {
+      const actor = await this.authorize(req, null);
+      const body = this.parse(checkRequestSchema, req.body);
+      return await this.deps.pdp.check(actor.id, body);
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0501 POST /authz/relations ---
+  @Post('authz/relations')
+  async writeRelation(@Req() req: AuthzRequest) {
+    try {
+      await this.authorize(req, AUTHZ_MANAGE);
+      const body = this.parse(relationRequestSchema, req.body);
+      await this.deps.relations.write(body);
+      return { ok: true as const };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-Z0501 DELETE /authz/relations ---
+  @Delete('authz/relations')
+  async removeRelation(@Req() req: AuthzRequest) {
+    try {
+      await this.authorize(req, AUTHZ_MANAGE);
+      const body = this.parse(relationRequestSchema, req.body);
+      await this.deps.relations.remove(body);
+      return { ok: true as const };
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- Interne surface-helpers ---
+
+  /**
+   * Resolveert de identiteit, bouwt de `Actor` uit zijn effectieve permissies en handhaaft
+   * `requiredPermission`. Geen identiteit → `unauthenticated` (401). Ontbrekende permissie → een
+   * `access.denied`-event; in `enforce`-mode volgt een `forbidden` (403), in `shadow`-mode laat de
+   * controller de call door (log-only, US-Z0704).
+   */
+  private async authorize(req: AuthzRequest, requiredPermission: string | null): Promise<Actor> {
+    const identity = await this.subjects.current(req);
+    if (identity === null) throw new AuthzError('unauthenticated');
+
+    const resolved = await this.deps.resolver.resolve(identity.id);
+    const actor: Actor = { id: identity.id, permissions: new Set(resolved.permissions) };
+
+    if (requiredPermission !== null && !actor.permissions.has(requiredPermission)) {
+      this.deps.events.emit({
+        name: 'access.denied',
+        occurredAt: this.deps.clock.now().toISOString(),
+        actorId: actor.id,
+        requested: requiredPermission,
+      });
+      // `shadow`: niet blokkeren — enkel loggen en doorlaten (observatie-modus, US-Z0704).
+      if (this.surface.enforcementMode === 'enforce') throw new AuthzError('forbidden');
+    }
+    return actor;
+  }
+
+  private parse<S extends ZodTypeAny>(schema: S, body: unknown): z.infer<S> {
+    return schema.parse(body);
+  }
+
+  /**
+   * Vertaal een fout naar HTTP. Zod → `validation_failed` (422, met veldpaden zonder waarden);
+   * `AuthzError` → `AUTHZ_ERROR_TAXONOMY`-status + contract-body; al-gevormde `HttpException` blijft;
+   * onbekend bubbelt (Nest → 500, geen leak).
+   */
+  private toHttp(err: unknown): never {
+    if (err instanceof HttpException) throw err;
+    if (err instanceof ZodError) {
+      const fields = err.flatten().fieldErrors as Record<string, string[]>;
+      throw new HttpException(
+        { code: 'validation_failed', message: AUTHZ_ERROR_TAXONOMY.validation_failed.i18nKey, fields },
+        AUTHZ_ERROR_TAXONOMY.validation_failed.httpStatus,
+      );
+    }
+    if (err instanceof AuthzError) {
+      const descriptor = AUTHZ_ERROR_TAXONOMY[err.code];
+      throw new HttpException(err.toBody(), descriptor.httpStatus);
+    }
+    throw err;
+  }
+}

package/backend/templates/nestjs/authz.module.ts

@@ -0,0 +1,158 @@
+/**
+ * `AuthzModule.forRoot(options)` — de NestJS-surface die de framework-vrije mechanism-laag (backend/src)
+ * samenbindt met de pg-policy-store, de TTL-cache en de audit-log-kit. Alles wordt met EXPLICIETE
+ * providers (`useValue`/token) gewired — geen type-based DI — zodat de module ook onder vitest/esbuild
+ * draait (geen decorator-metadata). Fail-fast op ontbrekende poorten (pool/subjectProvider).
+ */
+import { Module, type DynamicModule, type Provider } from '@nestjs/common';
+import type { Pool } from '@seifer-webapp-factory/kits/backend/persistence';
+import { createAuditLog, inMemoryAuditStore, type AuditLog } from '@seifer-webapp-factory/kits/backend/audit-log';
+import {
+  AUTHZ_EVENTS,
+  AUTHZ_PERMISSIONS,
+  type AuthzEvent,
+  type AuthzEventSink,
+  type PermissionCatalog,
+} from '../../../contract/index.js';
+import {
+  AssignmentService,
+  AuthorizationPdp,
+  PermissionResolver,
+  RelationService,
+  RoleService,
+  type Clock,
+  type SubjectProvider,
+} from '../../src/index.js';
+import { ttlPermissionCache } from '../cache/ttl-cache.js';
+import { pgPolicyStore } from '../persistence/pg-policy-store.js';
+import { parseAuthzConfig, type AuthzConfig } from '../config/config-fragment.js';
+import { AuthzController } from './authz.controller.js';
+import {
+  AUTHZ_AUDIT_LOG,
+  AUTHZ_MODULE_DEPS,
+  AUTHZ_SUBJECT_PROVIDER,
+  AUTHZ_SURFACE_CONFIG,
+  type AuthzModuleDeps,
+  type AuthzSurfaceConfig,
+} from './tokens.js';
+
+// Her-exporteer de tokens/typen zodat consumenten alles vanuit de module kunnen importeren.
+export {
+  AUTHZ_AUDIT_LOG,
+  AUTHZ_MODULE_DEPS,
+  AUTHZ_SUBJECT_PROVIDER,
+  AUTHZ_SURFACE_CONFIG,
+  type AuthzModuleDeps,
+  type AuthzSurfaceConfig,
+} from './tokens.js';
+
+/** De default-klok: echte wandkloktijd. Tests injecteren een deterministische variant. */
+const systemClock: Clock = { now: () => new Date() };
+
+export interface AuthzModuleOptions {
+  /** Persistence-kit-pool waarover de pg-policy-store draait (verplicht). */
+  pool: Pool;
+  /** Leest het geauthenticeerde subject uit de request-context (de seam met authentication) (verplicht). */
+  subjectProvider: SubjectProvider;
+  /** Ruwe config-invoer; wordt met defaults geparsed tot een {@link AuthzConfig}. */
+  config?: unknown;
+  /** Audit-log-sink (US-Z0705). Default: een in-memory audit-log (query-baar in tests). */
+  auditLog?: AuditLog;
+  /** Extra event-sink naast de audit-log (host-hooks/analytics). */
+  events?: AuthzEventSink;
+  /** Injecteerbare klok (deterministische TTL's/timestamps in tests). Default systeemklok. */
+  clock?: Clock;
+  /** Permissie-catalogus; de host mengt hier zijn app-permissies bij. Default: `AUTHZ_PERMISSIONS`. */
+  catalog?: PermissionCatalog;
+}
+
+@Module({})
+export class AuthzModule {
+  static forRoot(options: AuthzModuleOptions): DynamicModule {
+    requireOption('pool', options.pool);
+    requireOption('subjectProvider', options.subjectProvider, ['current']);
+
+    const config: AuthzConfig = parseAuthzConfig(options.config);
+    const clock: Clock = options.clock ?? systemClock;
+    const catalog: PermissionCatalog = options.catalog ?? AUTHZ_PERMISSIONS;
+    const rebacEnabled = config.model === 'rbac+rebac';
+
+    // --- pg-adapter + TTL-cache over de kit-pool ---
+    const store = pgPolicyStore(options.pool);
+    const cache = ttlPermissionCache(config.cacheTtlSeconds, clock);
+
+    // --- audit-log (US-Z0705): authz-events → onveranderlijk logboek ---
+    const auditLog =
+      options.auditLog ??
+      createAuditLog(inMemoryAuditStore(), {
+        eventTypes: [...AUTHZ_EVENTS],
+        clock: () => clock.now().getTime(),
+      });
+    const events = auditEventSink(auditLog, options.events);
+
+    // --- mechanism-services (framework-vrij) ---
+    const roles = new RoleService({ store, catalog, events, clock });
+    const assignments = new AssignmentService({ store, cache, events, clock });
+    const resolver = new PermissionResolver({ store, cache });
+    const pdp = new AuthorizationPdp({ resolver, store, rebacEnabled });
+    const relations = new RelationService({ store, rebacEnabled });
+
+    const deps: AuthzModuleDeps = { roles, assignments, resolver, pdp, relations, events, clock };
+    const surfaceConfig: AuthzSurfaceConfig = { enforcementMode: config.enforcementMode };
+
+    const providers: Provider[] = [
+      { provide: AUTHZ_MODULE_DEPS, useValue: deps },
+      { provide: AUTHZ_SUBJECT_PROVIDER, useValue: options.subjectProvider },
+      { provide: AUTHZ_AUDIT_LOG, useValue: auditLog },
+      { provide: AUTHZ_SURFACE_CONFIG, useValue: surfaceConfig },
+    ];
+
+    return {
+      module: AuthzModule,
+      controllers: [AuthzController],
+      providers,
+      exports: [AUTHZ_MODULE_DEPS, AUTHZ_AUDIT_LOG],
+    };
+  }
+}
+
+/**
+ * Adapteert de {@link AuthzEventSink} naar een audit-log-append (US-Z0705). Emit is synchroon (`void`);
+ * de append draait fire-and-forget met een zwaluwstaart-catch zodat een logboek-hapering nooit de
+ * authz-flow breekt. Payloads bevatten alleen identificatie (nooit policy-interne details).
+ */
+function auditEventSink(audit: AuditLog, extra?: AuthzEventSink): AuthzEventSink {
+  return {
+    emit(event: AuthzEvent): void {
+      extra?.emit(event);
+      void audit
+        .append({
+          actor: event.actorId,
+          action: event.name,
+          target: targetOf(event),
+          meta: { occurredAt: event.occurredAt },
+        })
+        .catch(() => undefined);
+    },
+  };
+}
+
+/** Bepaalt een audit-`target` per event-vorm (subject, rol of gevraagde permissie). */
+function targetOf(event: AuthzEvent): string {
+  if ('subjectId' in event) return event.subjectId;
+  if ('roleId' in event) return event.roleId;
+  if ('requested' in event) return event.requested;
+  // Onbereikbaar: elke event-vorm dekt één van de bovenstaande takken. Fallback op de actor.
+  return (event as { actorId: string }).actorId;
+}
+
+function requireOption(name: string, value: unknown, methods: string[] = []): void {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    throw new Error(`AuthzModule.forRoot: "${name}" ontbreekt of is geen object`);
+  }
+  for (const method of methods) {
+    if (typeof (value as Record<string, unknown>)[method] !== 'function') {
+      throw new Error(`AuthzModule.forRoot: "${name}" implementeert "${method}" niet`);
+    }
+  }
+}

package/backend/templates/nestjs/tokens.ts

@@ -0,0 +1,41 @@
+/**
+ * DI-tokens + kleine surface-typen voor de authorization-module. In een apart bestand zodat de
+ * controller en de module ze allebei kunnen importeren zonder circulaire import. Alle DI verloopt
+ * expliciet via deze tokens (`@Inject(TOKEN)` + `useValue`) — geen type-based DI — zodat de module ook
+ * onder vitest/esbuild draait (geen decorator-metadata nodig).
+ */
+import type { InjectionToken } from '@nestjs/common';
+import type { AuthzEventSink } from '../../../contract/index.js';
+import type {
+  AuthorizationPdp,
+  AssignmentService,
+  Clock,
+  PermissionResolver,
+  RelationService,
+  RoleService,
+} from '../../src/index.js';
+
+export const AUTHZ_MODULE_DEPS: InjectionToken = Symbol.for('authorization.module-deps');
+export const AUTHZ_SUBJECT_PROVIDER: InjectionToken = Symbol.for('authorization.subject-provider');
+export const AUTHZ_AUDIT_LOG: InjectionToken = Symbol.for('authorization.audit-log');
+export const AUTHZ_SURFACE_CONFIG: InjectionToken = Symbol.for('authorization.surface-config');
+
+/**
+ * De gebundelde mechanism-services + klok/events die de controller (surface) via één token krijgt.
+ * De module bouwt dit object en registreert het met `useValue`.
+ */
+export interface AuthzModuleDeps {
+  roles: RoleService;
+  assignments: AssignmentService;
+  resolver: PermissionResolver;
+  pdp: AuthorizationPdp;
+  relations: RelationService;
+  events: AuthzEventSink;
+  clock: Clock;
+}
+
+/** Runtime-config die de surface (controller) nodig heeft naast de mechanism-services. */
+export interface AuthzSurfaceConfig {
+  /** `enforce` = weiger bij ontbrekende permissie; `shadow` = log-only, laat door (US-Z0704). */
+  enforcementMode: 'enforce' | 'shadow';
+}

package/backend/templates/persistence/migrations/0001_authz.sql

@@ -0,0 +1,45 @@
+-- US-Z0604 — authorization capability, migratie 0001_authz (raw SQL, DBA-review).
+-- Idempotent (IF NOT EXISTS). De TypeScript-variant in index.ts draagt dezelfde SQL als string en is
+-- de bron die de MigrationRunner draait. Expand-contract: de kolom `scope` wordt nu al (nullable)
+-- meegeleverd, ook al gebruikt de huidige RBAC-vorm hem nog niet.
+
+-- Rollen + rol-hiërarchie (US-Z0201/Z0202). `parent_role_id` verwijst naar de bovenliggende rol.
+CREATE TABLE IF NOT EXISTS authz_roles (
+  id             text PRIMARY KEY,
+  key            text NOT NULL UNIQUE,
+  name           text NOT NULL,
+  parent_role_id text REFERENCES authz_roles(id)
+);
+
+-- Code-declared permissie-catalogus, gesynchroniseerd naar de DB (US-Z0203).
+CREATE TABLE IF NOT EXISTS authz_permissions (
+  key         text PRIMARY KEY,
+  description text NOT NULL DEFAULT ''
+);
+
+-- Koppeling rol → permissie (genormaliseerd; geaggregeerd tot StoredRole.permissions).
+CREATE TABLE IF NOT EXISTS authz_role_permissions (
+  role_id        text NOT NULL REFERENCES authz_roles(id),
+  permission_key text NOT NULL,
+  PRIMARY KEY (role_id, permission_key)
+);
+
+-- Rol-toewijzingen aan subjects (US-Z0301). `scope` is nullable (expand-contract, nog ongebruikt).
+CREATE TABLE IF NOT EXISTS authz_role_assignments (
+  subject_id text NOT NULL,
+  role_id    text NOT NULL REFERENCES authz_roles(id),
+  scope      text,
+  granted_at timestamptz NOT NULL DEFAULT now(),
+  granted_by text,
+  PRIMARY KEY (subject_id, role_id)
+);
+CREATE INDEX IF NOT EXISTS authz_role_assignments_role_idx ON authz_role_assignments(role_id);
+
+-- ReBAC-relatietuples (US-Z0501), alleen gebruikt wanneer `model: 'rbac+rebac'`.
+CREATE TABLE IF NOT EXISTS authz_relations (
+  subject_id  text NOT NULL,
+  relation    text NOT NULL,
+  object_type text NOT NULL,
+  object_id   text NOT NULL,
+  PRIMARY KEY (subject_id, relation, object_type, object_id)
+);

package/backend/templates/persistence/migrations/index.ts

@@ -0,0 +1,84 @@
+/**
+ * US-Z0604 — Schema-migraties voor de authorization-capability. De raw SQL staat als string in dit
+ * bestand (bron die de host-migratierunner draait); een identieke, door DBA leesbare kopie ligt ernaast
+ * in `0001_authz.sql`. Elke migratie is een stabiele `id` + idempotente SQL (IF NOT EXISTS).
+ *
+ * `0001_authz` legt vast:
+ *  - `authz_roles`            — rollen + rol-hiërarchie (US-Z0201/Z0202)
+ *  - `authz_permissions`      — code-declared permissie-catalogus, DB-gesynchroniseerd (US-Z0203)
+ *  - `authz_role_permissions` — koppeling rol → permissie
+ *  - `authz_role_assignments` — rol-toewijzingen aan subjects; `scope` nullable (expand-contract)
+ *  - `authz_relations`        — ReBAC-relatietuples (US-Z0501, achter config-toggle)
+ * Ids zijn `text` (gen_random_uuid); tijd-kolommen zijn `timestamptz`.
+ */
+
+import type { Migration } from '@seifer-webapp-factory/kits/backend/persistence';
+
+/**
+ * `0001_authz` in het persistence-kit-{@link Migration}-formaat (stabiele id + idempotente up/down).
+ * Elk statement gaat via een aparte `ctx.execute` (de runner verwacht één statement per call).
+ * De MigrationRunner past de migraties in volgorde toe en houdt een ledger bij.
+ */
+const authzInit: Migration = {
+  id: '0001_authz',
+  async up(ctx) {
+    await ctx.execute(`
+      CREATE TABLE IF NOT EXISTS authz_roles (
+        id             text PRIMARY KEY,
+        key            text NOT NULL UNIQUE,
+        name           text NOT NULL,
+        parent_role_id text REFERENCES authz_roles(id)
+      )
+    `);
+    await ctx.execute(`
+      CREATE TABLE IF NOT EXISTS authz_permissions (
+        key         text PRIMARY KEY,
+        description text NOT NULL DEFAULT ''
+      )
+    `);
+    await ctx.execute(`
+      CREATE TABLE IF NOT EXISTS authz_role_permissions (
+        role_id        text NOT NULL REFERENCES authz_roles(id),
+        permission_key text NOT NULL,
+        PRIMARY KEY (role_id, permission_key)
+      )
+    `);
+    await ctx.execute(`
+      CREATE TABLE IF NOT EXISTS authz_role_assignments (
+        subject_id text NOT NULL,
+        role_id    text NOT NULL REFERENCES authz_roles(id),
+        scope      text,
+        granted_at timestamptz NOT NULL DEFAULT now(),
+        granted_by text,
+        PRIMARY KEY (subject_id, role_id)
+      )
+    `);
+    await ctx.execute('CREATE INDEX IF NOT EXISTS authz_role_assignments_role_idx ON authz_role_assignments(role_id)');
+    await ctx.execute(`
+      CREATE TABLE IF NOT EXISTS authz_relations (
+        subject_id  text NOT NULL,
+        relation    text NOT NULL,
+        object_type text NOT NULL,
+        object_id   text NOT NULL,
+        PRIMARY KEY (subject_id, relation, object_type, object_id)
+      )
+    `);
+  },
+  async down(ctx) {
+    for (const table of AUTHZ_MANAGED_TABLES) {
+      await ctx.execute(`DROP TABLE IF EXISTS ${table}`);
+    }
+  },
+};
+
+/** Alle authorization-migraties in toepassingsvolgorde. */
+export const authzMigrations: Migration[] = [authzInit];
+
+/** Tabellen die een test-reset-helper mag leegmaken (exclusief de migratie-ledger). */
+export const AUTHZ_MANAGED_TABLES = [
+  'authz_relations',
+  'authz_role_assignments',
+  'authz_role_permissions',
+  'authz_permissions',
+  'authz_roles',
+];