@seifer-webapp-factory/authentication 0.1.0

package/README.md

@@ -0,0 +1,8 @@
+# @seifer-webapp-factory/authentication
+
+Eerste **capability-module**: verticale, pluggable full-stack auth-feature (register/login/logout/verify/refresh/reset) die de `@seifer-webapp-factory/kits` samenbindt via één contract.
+
+- Mechanisme (pinned dependency): `@seifer-webapp-factory/authentication/{contract,backend,frontend,manifest,scaffolder}`.
+- Surface (gematerialiseerd, project-eigendom): `backend/templates`, `frontend/templates`.
+
+Zie `../authentication.md` (plan) en `./` (backlog) in de monorepo.

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

@@ -0,0 +1,73 @@
+/**
+ * US-A0603 — Config-fragment voor de authentication-capability. Dit is een Zod-schema dat de host in
+ * zijn eigen app-config-schema mengt (config-kit). Het bevat GEEN secrets rechtstreeks: het
+ * signing-key-materiaal wordt via een *referentie* (`signingKeyRef`) uit de secret-store geladen, zodat
+ * het nooit in gewone config-dumps belandt (US-A0704).
+ */
+import { z } from 'zod';
+
+/** Wachtwoord-beleid (lengte); details buiten het contract-schema (US-A0603). */
+export const passwordPolicySchema = z.object({
+  minLength: z.number().int().min(8).default(8),
+  maxLength: z.number().int().max(1024).default(200),
+});
+
+/** Token-bucket-drempel per beschermde route (US-A0701). */
+export const rateLimitThresholdSchema = z.object({
+  /** Maximale burst (aantal pogingen). */
+  capacity: z.number().int().positive().default(5),
+  /** Bijvul-rate in pogingen per seconde. */
+  refillPerSecond: z.number().positive().default(0.2),
+});
+
+/** Het volledige auth-config-fragment. */
+export const authConfigFragment = z.object({
+  /** Referentie (naam) naar de JWT-signing-key in de secret-store — NIET de sleutel zelf. */
+  signingKeyRef: z.string().min(1).default('AUTH_SIGNING_KEY'),
+  /** Levensduur van het access-token (JWT) in seconden. Default 15 min. */
+  accessTtlSeconds: z.number().int().positive().default(15 * 60),
+  /** Levensduur van het roterende refresh-token in seconden. Default 14 dagen. */
+  refreshTtlSeconds: z.number().int().positive().default(14 * 24 * 60 * 60),
+  /** Issuer-claim (bv. app-naam). */
+  issuer: z.string().min(1).default('webapp-factory'),
+  /** Wachtwoord-beleid. */
+  password: passwordPolicySchema.default({}),
+  /** Feature-toggles. */
+  toggles: z
+    .object({
+      /** Vereist e-mailverificatie vóór login (US-A0203/US-A0301). */
+      emailVerification: z.boolean().default(true),
+      /** Sta open zelfregistratie toe (US-A0201). */
+      selfRegistration: z.boolean().default(true),
+    })
+    .default({}),
+  /** Redirect-doelen die de frontend na verify/reset gebruikt. */
+  redirects: z
+    .object({
+      afterVerify: z.string().default('/login?verified=1'),
+      afterReset: z.string().default('/login?reset=1'),
+    })
+    .default({}),
+  /** Rate-limit-drempels voor de misbruikgevoelige routes (US-A0701). */
+  rateLimit: z
+    .object({
+      login: rateLimitThresholdSchema.default({}),
+      forgot: rateLimitThresholdSchema.default({}),
+    })
+    .default({}),
+  /** Cookie-gedrag (US-A0703). `secure` hoort in productie `true` te zijn. */
+  cookie: z
+    .object({
+      secure: z.boolean().default(true),
+      sameSite: z.enum(['Strict', 'Lax', 'None']).default('Strict'),
+    })
+    .default({}),
+});
+
+/** Het afgeleide, gevalideerde config-type. */
+export type AuthConfig = z.infer<typeof authConfigFragment>;
+
+/** Parse (met defaults) een ruwe config-invoer tot een `AuthConfig`. */
+export function parseAuthConfig(input: unknown = {}): AuthConfig {
+  return authConfigFragment.parse(input);
+}

package/backend/templates/mail/templates.ts

@@ -0,0 +1,84 @@
+/**
+ * US-A0202 — E-mailtemplates voor de auth-keten (verificatie + wachtwoord-reset). Data-gedreven en
+ * i18n-klaar: per taal een `subject` + `body` met `{token}`/`{link}`-placeholders. De mechanism-laag
+ * roept `mailer.send({ to, subject, data: { token, purpose } })` aan; deze module vertaalt een
+ * `purpose` naar een gerenderd bericht. NL is de projectdefault; EN is meegeleverd als voorbeeld.
+ */
+import type { MailMessage } from '@seifer-webapp-factory/kits/backend/auth';
+
+/** De twee purposes die de mechanism-laag uitgeeft (sluiten aan op de kit-defaults). */
+export const MAIL_PURPOSES = {
+  emailVerify: 'email-verify',
+  passwordReset: 'password-reset',
+} as const;
+
+export type Locale = 'nl' | 'en';
+
+interface MailTemplate {
+  subject: string;
+  /** `{token}` en `{link}` worden ingevuld bij het renderen. */
+  body: string;
+}
+
+/** Templatecatalogus per purpose per taal. */
+export const MAIL_TEMPLATES: Record<string, Record<Locale, MailTemplate>> = {
+  [MAIL_PURPOSES.emailVerify]: {
+    nl: {
+      subject: 'Bevestig je account',
+      body:
+        'Welkom!\n\nBevestig je account met deze code:\n\n{token}\n\n' +
+        'Of open de link: {link}\n\nHeb je dit niet aangevraagd? Negeer deze e-mail.',
+    },
+    en: {
+      subject: 'Confirm your account',
+      body:
+        'Welcome!\n\nConfirm your account with this code:\n\n{token}\n\n' +
+        'Or open the link: {link}\n\nDidn’t request this? Ignore this email.',
+    },
+  },
+  [MAIL_PURPOSES.passwordReset]: {
+    nl: {
+      subject: 'Reset je wachtwoord',
+      body:
+        'Je hebt een wachtwoord-reset aangevraagd.\n\nGebruik deze code:\n\n{token}\n\n' +
+        'Of open de link: {link}\n\nHeb je dit niet aangevraagd? Negeer deze e-mail.',
+    },
+    en: {
+      subject: 'Reset your password',
+      body:
+        'You requested a password reset.\n\nUse this code:\n\n{token}\n\n' +
+        'Or open the link: {link}\n\nDidn’t request this? Ignore this email.',
+    },
+  },
+};
+
+export interface RenderOptions {
+  locale?: Locale;
+  /** Basis-URL om een klikbare `{link}` te bouwen (bv. `https://app/verify?token=`). */
+  linkBaseByPurpose?: Record<string, string>;
+}
+
+export interface RenderedMail {
+  subject: string;
+  text: string;
+}
+
+/**
+ * Render een `MailMessage` (met `data.token` + `data.purpose`) tot een concreet bericht. Onbekende
+ * purposes vallen terug op het meegegeven `subject` + de kale token-tekst (geen stille lege body).
+ */
+export function renderAuthMail(message: MailMessage, options: RenderOptions = {}): RenderedMail {
+  const locale = options.locale ?? 'nl';
+  const purpose = String(message.data?.['purpose'] ?? '');
+  const token = String(message.data?.['token'] ?? '');
+  const template = MAIL_TEMPLATES[purpose]?.[locale];
+
+  if (!template) {
+    return { subject: message.subject, text: message.text ?? token };
+  }
+
+  const base = options.linkBaseByPurpose?.[purpose];
+  const link = base ? `${base}${encodeURIComponent(token)}` : '';
+  const text = template.body.replaceAll('{token}', token).replaceAll('{link}', link);
+  return { subject: template.subject, text };
+}

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

@@ -0,0 +1,274 @@
+/**
+ * De NestJS-surface voor de 8 contract-endpoints. Puur *plumbing*: valideert de body met de contract-
+ * Zod-schema's, roept de framework-vrije mechanism-services (backend/src) aan, en vertaalt het resultaat
+ * naar HTTP. Security-invarianten die hier (en niet in het mechanisme) horen:
+ *  - httpOnly+Secure+SameSite refresh-cookie; access-token alleen in de body (US-A0703)
+ *  - CSRF double-submit op state-changing routes (US-A0703)
+ *  - security-headers + generieke, niet-lekkende foutbodies `{ code, message, fields? }` (US-A0704)
+ *  - rate-limit op login + forgot (US-A0701)
+ *
+ * DI is EXPLICIET via `@Inject(TOKEN)` (geen type-based DI) zodat de controller onder vitest/esbuild
+ * draait zonder decorator-metadata.
+ */
+import {
+  Controller,
+  Get,
+  HttpCode,
+  HttpException,
+  Inject,
+  Post,
+  Req,
+  Res,
+} from '@nestjs/common';
+import { ZodError, type ZodTypeAny, type z } from 'zod';
+import { enforceRateLimit, type RateLimiter } from '@seifer-webapp-factory/kits/backend/rate-limit';
+import type { UserRecord } from '@seifer-webapp-factory/kits/backend/auth';
+import {
+  registerRequestSchema,
+  verifyEmailRequestSchema,
+  loginRequestSchema,
+  forgotPasswordRequestSchema,
+  resetPasswordRequestSchema,
+  AUTH_ERROR_TAXONOMY,
+  type AuthErrorCode,
+  type MeResponse,
+  type PublicUser,
+} from '../../../contract/index.js';
+import {
+  registerUser,
+  verifyEmail,
+  login,
+  refresh,
+  logout,
+  forgotPassword,
+  resetPassword,
+  AuthModuleError,
+  type AuthModuleDeps,
+} from '../../src/index.js';
+import {
+  REFRESH_COOKIE,
+  parseCookies,
+  refreshSetCookie,
+  clearRefreshSetCookie,
+  csrfSetCookie,
+  type CookieOptions,
+} from '../security/cookies.js';
+import { generateCsrfToken, isCsrfValid, csrfCookieValue } from '../security/csrf.js';
+import { applySecurityHeaders } from '../security/headers.js';
+import {
+  AUTH_MODULE_DEPS,
+  AUTH_LOGIN_LIMITER,
+  AUTH_FORGOT_LIMITER,
+  AUTH_COOKIE_OPTIONS,
+  AUTH_SURFACE_CONFIG,
+  type AuthSurfaceConfig,
+} from './tokens.js';
+
+/** Minimale express-request-vorm die de controller nodig heeft (geen harde type-dep). */
+interface AuthRequest {
+  headers: Record<string, string | string[] | undefined>;
+  body: unknown;
+}
+/** Minimale express-response-vorm (setHeader + append voor meerdere Set-Cookie's). */
+interface AuthResponse {
+  setHeader(name: string, value: string): unknown;
+  append(name: string, value: string | string[]): unknown;
+}
+
+@Controller('auth')
+export class AuthController {
+  constructor(
+    @Inject(AUTH_MODULE_DEPS) private readonly deps: AuthModuleDeps,
+    @Inject(AUTH_LOGIN_LIMITER) private readonly loginLimiter: RateLimiter,
+    @Inject(AUTH_FORGOT_LIMITER) private readonly forgotLimiter: RateLimiter,
+    @Inject(AUTH_COOKIE_OPTIONS) private readonly cookie: CookieOptions,
+    @Inject(AUTH_SURFACE_CONFIG) private readonly surface: AuthSurfaceConfig,
+  ) {}
+
+  // --- US-A0201 register ---
+  @Post('register')
+  @HttpCode(200)
+  async register(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse) {
+    try {
+      this.prepare(req, res, true);
+      const body = this.parse(registerRequestSchema, req.body);
+      return await registerUser(this.deps, body);
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-A0203 verify-email ---
+  @Post('verify-email')
+  @HttpCode(200)
+  async verifyEmail(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse) {
+    try {
+      this.prepare(req, res, true);
+      const body = this.parse(verifyEmailRequestSchema, req.body);
+      return await verifyEmail(this.deps, body.token);
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-A0301 login ---
+  @Post('login')
+  @HttpCode(200)
+  async login(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse) {
+    try {
+      this.prepare(req, res, true);
+      const body = this.parse(loginRequestSchema, req.body);
+      await this.enforce(this.loginLimiter, `login:${body.email}`, res);
+      const result = await login(this.deps, body);
+      this.setRefresh(res, result.refreshToken);
+      return result.session;
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-A0401 refresh (stille rotatie) ---
+  @Post('refresh')
+  @HttpCode(200)
+  async refresh(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse) {
+    try {
+      this.prepare(req, res, true);
+      const result = await refresh(this.deps, this.readRefresh(req));
+      this.setRefresh(res, result.refreshToken);
+      return result.session;
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-A0403 logout (idempotent) ---
+  @Post('logout')
+  @HttpCode(200)
+  async logout(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse) {
+    try {
+      this.prepare(req, res, true);
+      const ack = await logout(this.deps, this.readRefresh(req));
+      res.append('Set-Cookie', clearRefreshSetCookie(this.cookie));
+      return ack;
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-A0501 forgot-password (altijd 200, no-enumeration) ---
+  @Post('forgot-password')
+  @HttpCode(200)
+  async forgotPassword(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse) {
+    try {
+      this.prepare(req, res, true);
+      const body = this.parse(forgotPasswordRequestSchema, req.body);
+      await this.enforce(this.forgotLimiter, `forgot:${body.email}`, res);
+      return await forgotPassword(this.deps, body);
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-A0502 reset-password (verbruikt token + trekt sessies in) ---
+  @Post('reset-password')
+  @HttpCode(200)
+  async resetPassword(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse) {
+    try {
+      this.prepare(req, res, true);
+      const body = this.parse(resetPasswordRequestSchema, req.body);
+      return await resetPassword(this.deps, body);
+    } catch (err) {
+      this.toHttp(err);
+    }
+  }
+
+  // --- US-A0302 GET /auth/me ---
+  @Get('me')
+  @HttpCode(200)
+  async me(@Req() req: AuthRequest, @Res({ passthrough: true }) res: AuthResponse): Promise<MeResponse> {
+    try {
+      this.prepare(req, res, false);
+      const token = this.bearer(req);
+      if (!token) throw new AuthModuleError('unauthenticated');
+      const verified = await this.deps.tokenService.verify(token);
+      const user = await this.deps.userStore.findById(verified.subject);
+      if (!user) throw new AuthModuleError('unauthenticated');
+      return { user: toPublicUser(user), roles: [], permissions: [] };
+    } catch (err) {
+      if (err instanceof HttpException) throw err;
+      // Elke fout in de me-flow (ontbrekend/ongeldig/verlopen access-token) → generieke 401 (geen leak).
+      this.toHttp(new AuthModuleError('unauthenticated'));
+    }
+  }
+
+  // --- Interne surface-helpers ---
+
+  /** Security-headers + CSRF-seed + (optioneel) double-submit-controle op state-changing routes. */
+  private prepare(req: AuthRequest, res: AuthResponse, csrf: boolean): void {
+    applySecurityHeaders(res);
+    // Zaai een leesbare CSRF-cookie zodra er nog geen is (double-submit bootstrap, US-A0703).
+    if (csrfCookieValue(req) === undefined) {
+      res.append('Set-Cookie', csrfSetCookie(generateCsrfToken(), this.cookie));
+    }
+    if (csrf && !isCsrfValid(req)) this.fail('csrf_failed');
+  }
+
+  /** Rate-limit-enforcement (US-A0701): zet `X-RateLimit-*`-headers; bij weigering → `rate_limited`. */
+  private async enforce(limiter: RateLimiter, key: string, res: AuthResponse): Promise<void> {
+    const decision = await enforceRateLimit(key, { limiter });
+    for (const [name, value] of Object.entries(decision.headers)) res.setHeader(name, value);
+    if (!decision.allowed) this.fail('rate_limited');
+  }
+
+  private parse<S extends ZodTypeAny>(schema: S, body: unknown): z.infer<S> {
+    return schema.parse(body);
+  }
+
+  /** Zet het roterende refresh-token als httpOnly-cookie (nooit in de body). */
+  private setRefresh(res: AuthResponse, token: string): void {
+    res.append('Set-Cookie', refreshSetCookie(token, this.surface.refreshTtlSeconds, this.cookie));
+  }
+
+  private readRefresh(req: AuthRequest): string | undefined {
+    const raw = req.headers['cookie'];
+    const header = Array.isArray(raw) ? raw.join('; ') : raw;
+    return parseCookies(header)[REFRESH_COOKIE];
+  }
+
+  private bearer(req: AuthRequest): string | undefined {
+    const raw = req.headers['authorization'] ?? req.headers['Authorization'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return value?.startsWith('Bearer ') ? value.slice('Bearer '.length) : undefined;
+  }
+
+  /** Gooi een generieke, contract-conforme foutrespons voor een code (nooit secret-materiaal). */
+  private fail(code: AuthErrorCode): never {
+    throw new AuthModuleError(code);
+  }
+
+  /**
+   * Vertaal een fout naar HTTP. Zod → `validation_failed` (422, met veldpaden zonder waarden);
+   * `AuthModuleError` → `AUTH_ERROR_TAXONOMY`-status; 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: AUTH_ERROR_TAXONOMY.validation_failed.i18nKey, fields },
+        AUTH_ERROR_TAXONOMY.validation_failed.httpStatus,
+      );
+    }
+    if (err instanceof AuthModuleError) {
+      const descriptor = AUTH_ERROR_TAXONOMY[err.code];
+      throw new HttpException({ code: err.code, message: err.message }, descriptor.httpStatus);
+    }
+    throw err;
+  }
+}
+
+/** Kit-`UserRecord` → veilige contract-`PublicUser` (geen credential-materiaal). */
+function toPublicUser(user: UserRecord): PublicUser {
+  return { id: user.id, email: user.identifier, emailVerified: user.verified === true };
+}

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

@@ -0,0 +1,207 @@
+/**
+ * `AuthModule.forRoot(options)` — de NestJS-surface die de framework-vrije mechanism-laag (backend/src)
+ * samenbindt met de pg-adapters, de rate-limit-kit, de audit-log-kit en de security-helpers. 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, in de stijl van de
+ * kit-`AuthKitModule`.
+ */
+import { Module, type DynamicModule, type Provider } from '@nestjs/common';
+import {
+  TokenService,
+  SingleUseTokenService,
+  argon2idHasher,
+  type Argon2idParams,
+  type Clock,
+  type Mailer,
+} from '@seifer-webapp-factory/kits/backend/auth';
+import type { Pool } from '@seifer-webapp-factory/kits/backend/persistence';
+import {
+  tokenBucketLimiter,
+  inMemoryRateLimitStore,
+  type RateLimiter,
+} from '@seifer-webapp-factory/kits/backend/rate-limit';
+import { createAuditLog, inMemoryAuditStore, type AuditLog } from '@seifer-webapp-factory/kits/backend/audit-log';
+import { AUTH_EVENTS, type AuthEvent, type AuthEventSink } from '../../../contract/index.js';
+import type { AuthModuleConfig, AuthModuleDeps } from '../../src/index.js';
+import { pgUserStore } from '../persistence/pg-user-store.js';
+import { pgTokenStore } from '../persistence/pg-token-store.js';
+import { pgSingleUseStore } from '../persistence/pg-single-use-store.js';
+import { DEFAULT_COOKIE_OPTIONS, type CookieOptions } from '../security/cookies.js';
+import { AuthController } from './auth.controller.js';
+import {
+  AUTH_MODULE_DEPS,
+  AUTH_LOGIN_LIMITER,
+  AUTH_FORGOT_LIMITER,
+  AUTH_AUDIT_LOG,
+  AUTH_COOKIE_OPTIONS,
+  AUTH_SURFACE_CONFIG,
+  type AuthSurfaceConfig,
+  type RateLimitThreshold,
+} from './tokens.js';
+
+// Her-exporteer de tokens/typen zodat consumenten alles vanuit de module kunnen importeren.
+export {
+  AUTH_MODULE_DEPS,
+  AUTH_LOGIN_LIMITER,
+  AUTH_FORGOT_LIMITER,
+  AUTH_AUDIT_LOG,
+  AUTH_COOKIE_OPTIONS,
+  AUTH_SURFACE_CONFIG,
+  type AuthSurfaceConfig,
+  type RateLimitThreshold,
+} from './tokens.js';
+
+export interface AuthModuleOptions {
+  /** Persistence-kit-pool waarover de pg-adapters draaien (verplicht). */
+  pool: Pool;
+  /** Mailer-poort (kit) waarlangs verify/reset-mails gaan (verplicht). */
+  mailer: Mailer;
+  /** JWT-signing-secret (reeds uit de secret-store ge-`reveal()`-d) (verplicht). */
+  signingSecret: string;
+  issuer?: string;
+  accessTtlSeconds?: number;
+  refreshTtlSeconds?: number;
+  password?: { minLength: number; maxLength: number };
+  purposes?: { emailVerify: string; passwordReset: string };
+  rateLimit?: { login?: RateLimitThreshold; forgot?: RateLimitThreshold };
+  cookie?: Partial<CookieOptions>;
+  /** Argon2id-parameters (tests gebruiken lichtere kosten voor snelheid). */
+  argon2?: Argon2idParams;
+  /** Injecteerbare klok (deterministische TTL's in tests). Default `Date.now`. */
+  clock?: Clock;
+  /** Audit-log-sink (US-A0705). Default: een in-memory audit-log (query-baar in tests). */
+  auditLog?: AuditLog;
+  /** Extra event-sink naast de audit-log (host-hooks/analytics). */
+  events?: AuthEventSink;
+}
+
+const DEFAULTS = {
+  issuer: 'webapp-factory',
+  accessTtlSeconds: 15 * 60,
+  refreshTtlSeconds: 14 * 24 * 60 * 60,
+  password: { minLength: 8, maxLength: 200 },
+  purposes: { emailVerify: 'email-verify', passwordReset: 'password-reset' },
+  rateLimit: {
+    login: { capacity: 5, refillPerSecond: 0.2 },
+    forgot: { capacity: 5, refillPerSecond: 0.2 },
+  },
+};
+
+@Module({})
+export class AuthModule {
+  static forRoot(options: AuthModuleOptions): DynamicModule {
+    requireOption('pool', options.pool);
+    requireOption('mailer', options.mailer, ['send']);
+    if (!options.signingSecret || typeof options.signingSecret !== 'string') {
+      throw new Error('AuthModule.forRoot: "signingSecret" ontbreekt of is ongeldig');
+    }
+
+    const clock: Clock = options.clock ?? Date.now;
+    const issuer = options.issuer ?? DEFAULTS.issuer;
+    const accessTtlSeconds = options.accessTtlSeconds ?? DEFAULTS.accessTtlSeconds;
+    const refreshTtlSeconds = options.refreshTtlSeconds ?? DEFAULTS.refreshTtlSeconds;
+    const password = options.password ?? DEFAULTS.password;
+    const purposes = options.purposes ?? DEFAULTS.purposes;
+    const cookie: CookieOptions = { ...DEFAULT_COOKIE_OPTIONS, ...options.cookie };
+
+    // --- pg-adapters over de kit-pool ---
+    const userStore = pgUserStore(options.pool);
+    const tokenStore = pgTokenStore(options.pool);
+    const singleUseStore = pgSingleUseStore(options.pool);
+
+    // --- kit-services die de mechanism-poorten (structureel) vervullen ---
+    const tokenService = new TokenService(
+      { secret: options.signingSecret, accessTtlSeconds, refreshTtlSeconds, issuer },
+      tokenStore,
+      clock,
+    );
+    const singleUseTokenService = new SingleUseTokenService(
+      { defaultTtlSeconds: 24 * 60 * 60, ttlByPurpose: { [purposes.passwordReset]: 60 * 60 } },
+      singleUseStore,
+      clock,
+    );
+    const hasher = argon2idHasher(options.argon2);
+
+    // --- audit-log (US-A0705): auth-events → onveranderlijk logboek ---
+    const auditLog =
+      options.auditLog ?? createAuditLog(inMemoryAuditStore(), { eventTypes: [...AUTH_EVENTS], clock });
+    const events = auditEventSink(auditLog, options.events);
+
+    const config: AuthModuleConfig = { purposes, password };
+    const deps: AuthModuleDeps = {
+      userStore,
+      mailer: options.mailer,
+      hasher,
+      tokenService,
+      singleUseTokenService,
+      events,
+      clock,
+      config,
+    };
+
+    // --- rate-limiters (US-A0701) op login + forgot ---
+    const store = inMemoryRateLimitStore();
+    const loginThreshold = options.rateLimit?.login ?? DEFAULTS.rateLimit.login;
+    const forgotThreshold = options.rateLimit?.forgot ?? DEFAULTS.rateLimit.forgot;
+    const loginLimiter: RateLimiter = tokenBucketLimiter(
+      { capacity: loginThreshold.capacity, refillPerSecond: loginThreshold.refillPerSecond },
+      store,
+      clock,
+    );
+    const forgotLimiter: RateLimiter = tokenBucketLimiter(
+      { capacity: forgotThreshold.capacity, refillPerSecond: forgotThreshold.refillPerSecond },
+      store,
+      clock,
+    );
+
+    const surfaceConfig: AuthSurfaceConfig = { accessTtlSeconds, refreshTtlSeconds };
+
+    const providers: Provider[] = [
+      { provide: AUTH_MODULE_DEPS, useValue: deps },
+      { provide: AUTH_LOGIN_LIMITER, useValue: loginLimiter },
+      { provide: AUTH_FORGOT_LIMITER, useValue: forgotLimiter },
+      { provide: AUTH_AUDIT_LOG, useValue: auditLog },
+      { provide: AUTH_COOKIE_OPTIONS, useValue: cookie },
+      { provide: AUTH_SURFACE_CONFIG, useValue: surfaceConfig },
+    ];
+
+    return {
+      module: AuthModule,
+      controllers: [AuthController],
+      providers,
+      exports: [AUTH_MODULE_DEPS, AUTH_AUDIT_LOG],
+    };
+  }
+}
+
+/**
+ * Adapteert de {@link AuthEventSink} naar een audit-log-append (US-A0705). Emit is synchroon (`void`);
+ * de append draait fire-and-forget met een zwaluwstaart-catch zodat een logboek-hapering nooit de
+ * auth-flow breekt. Payloads bevatten alleen identificatie (nooit credentials/tokens).
+ */
+function auditEventSink(audit: AuditLog, extra?: AuthEventSink): AuthEventSink {
+  return {
+    emit(event: AuthEvent): void {
+      extra?.emit(event);
+      void audit
+        .append({
+          actor: event.userId,
+          action: event.name,
+          target: event.userId,
+          meta: { occurredAt: event.occurredAt },
+        })
+        .catch(() => undefined);
+    },
+  };
+}
+
+function requireOption(name: string, value: unknown, methods: string[] = []): void {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    throw new Error(`AuthModule.forRoot: "${name}" ontbreekt of is geen object`);
+  }
+  for (const method of methods) {
+    if (typeof (value as Record<string, unknown>)[method] !== 'function') {
+      throw new Error(`AuthModule.forRoot: "${name}" implementeert "${method}" niet`);
+    }
+  }
+}

package/backend/templates/nestjs/tokens.ts

@@ -0,0 +1,24 @@
+/**
+ * DI-tokens + kleine surface-config-typen voor de authentication-module. In een apart bestand zodat de
+ * controller en de module ze allebei kunnen importeren zonder circulaire import.
+ */
+import type { InjectionToken } from '@nestjs/common';
+
+export const AUTH_MODULE_DEPS: InjectionToken = Symbol.for('authentication.module-deps');
+export const AUTH_LOGIN_LIMITER: InjectionToken = Symbol.for('authentication.login-limiter');
+export const AUTH_FORGOT_LIMITER: InjectionToken = Symbol.for('authentication.forgot-limiter');
+export const AUTH_AUDIT_LOG: InjectionToken = Symbol.for('authentication.audit-log');
+export const AUTH_COOKIE_OPTIONS: InjectionToken = Symbol.for('authentication.cookie-options');
+export const AUTH_SURFACE_CONFIG: InjectionToken = Symbol.for('authentication.surface-config');
+
+/** Drempel voor een token-bucket-limiter (US-A0701). */
+export interface RateLimitThreshold {
+  capacity: number;
+  refillPerSecond: number;
+}
+
+/** Runtime-config die de surface (controller) nodig heeft naast de mechanism-`AuthModuleConfig`. */
+export interface AuthSurfaceConfig {
+  accessTtlSeconds: number;
+  refreshTtlSeconds: number;
+}