ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/init/platform/audit/create-audit.ts.tpl

@@ -0,0 +1,111 @@
+{{#if audit.sql}}
+import {
+  auditDecisions,
+  auditIntegrationEvents,
+  auditMiddleware,
+  type AuditReader,
+  type AuditSource,
+  type AuditTrail,
+} from '@ddd-ts-kit/audit';
+{{/if}}
+{{#if audit.memory}}
+import {
+  InMemoryAuditTrail,
+  auditDecisions,
+  auditIntegrationEvents,
+  auditMiddleware,
+  type AuditReader,
+  type AuditSource,
+  type AuditTrail,
+} from '@ddd-ts-kit/audit';
+{{/if}}
+{{#if audit.knex}}
+import { KnexAuditTrail } from '@ddd-ts-kit/audit/knex';
+{{/if}}
+{{#if audit.drizzle}}
+import { DrizzleAuditTrail } from '@ddd-ts-kit/audit/drizzle';
+{{/if}}
+import type { OnDecision } from '@ddd-ts-kit/auth';
+import type { EventSubscription } from '@ddd-ts-kit/events';
+import type { BusMiddleware } from '@ddd-ts-kit/kernel';
+import type { Persistence } from '{{alias.platform}}/database/persistence.js';
+{{#if audit.sql}}
+import { AUDIT_SCHEMA } from '{{alias.platform}}/database/schema.js';
+{{/if}}
+{{#if audit.route}}
+import { auditPermissions } from '{{alias.platform}}/audit/audit.permissions.js';
+{{/if}}
+import { auditedEvents } from '{{alias.platform}}/audit/audited-events.js';
+{{#if audit.route}}
+import { SearchAuditEntriesQuery } from '{{alias.platform}}/audit/search-audit-entries.query.js';
+{{/if}}
+
+/** The name the audit trail consumes integration events under: its idempotency scope, and its queues behind a broker. */
+const consumer = 'audit';
+
+/**
+ * The audit trail and its three sources. No use case writes to it: the entries come from the
+ * authorization hook, from the buses and from a subscription to every integration event, and
+ * each one carries the correlation id, the actor and the tenant of the execution scope.
+ */
+export interface Audit {
+  readonly trail: AuditTrail & AuditReader;
+  /** The `onDecision` hook of the authorization: who was allowed or refused what. */
+  readonly decisions: OnDecision;
+  /** On the command bus, before the unit of work: which command ran and how it ended. */
+  readonly commands: BusMiddleware;
+  /** On the query bus: whoever reads the trail leaves an entry in it. */
+  readonly queries: BusMiddleware;
+  /** One subscription per declared integration event: that it occurred, never its payload. */
+  readonly subscriptions: readonly EventSubscription[];
+  /** The name those subscriptions listen under. */
+  readonly consumer: string;
+}
+
+export function createAudit(persistence: Persistence, source: AuditSource): Audit {
+  const trail = createAuditTrail({{#if audit.sql}}persistence{{/if}});
+  const { unitOfWork, processedEvents } = persistence;
+
+  return {
+    trail,
+{{#if audit.route}}
+    decisions: auditDecisions(trail, { ...source, sensitivePermissions: [auditPermissions['trail.read'].id] }),
+    // TODO(platform): declare what may go into `changes` with `fields: [auditedFields(SomeCommand, ['status'])]`; by default an entry carries identifiers and codes only.
+    commands: auditMiddleware(trail, { ...source, unitOfWork }),
+    queries: auditMiddleware(trail, { ...source, queries: [SearchAuditEntriesQuery] }),
+{{/if}}
+{{#unless audit.route}}
+    decisions: auditDecisions(trail, source),
+    // TODO(platform): declare what may go into `changes` with `fields: [auditedFields(SomeCommand, ['status'])]`; by default an entry carries identifiers and codes only.
+    commands: auditMiddleware(trail, { ...source, unitOfWork }),
+    queries: auditMiddleware(trail, source),
+{{/unless}}
+    subscriptions: auditIntegrationEvents(trail, {
+      registry: auditedEvents,
+      clock: source.clock,
+      ids: source.ids,
+      processed: processedEvents,
+      unitOfWork,
+      scope: source.scope,
+      consumer,
+    }),
+    consumer,
+  };
+}
+
+{{#if audit.knex}}
+function createAuditTrail(persistence: Persistence): AuditTrail & AuditReader {
+  return new KnexAuditTrail(persistence.database, { schema: AUDIT_SCHEMA });
+}
+{{/if}}
+{{#if audit.drizzle}}
+function createAuditTrail(persistence: Persistence): AuditTrail & AuditReader {
+  return new DrizzleAuditTrail(persistence.database, { schema: AUDIT_SCHEMA });
+}
+{{/if}}
+{{#if audit.memory}}
+// TODO(platform): the audit package stores on knex and drizzle only: write an adapter of AuditTrail and AuditReader for your storage, hold it to `auditTrailContract` of @ddd-ts-kit/audit/testing and answer it here. Until then the entries live in the memory of the process and are lost when it stops.
+function createAuditTrail(): AuditTrail & AuditReader {
+  return new InMemoryAuditTrail();
+}
+{{/if}}

package/templates/init/platform/audit/search-audit-entries.handler.ts.tpl

@@ -0,0 +1,18 @@
+import type { AuditEntry, AuditReader } from '@ddd-ts-kit/audit';
+import type { Page, QueryHandler } from '@ddd-ts-kit/kernel';
+import type { SearchAuditEntriesQuery } from '{{alias.platform}}/audit/search-audit-entries.query.js';
+
+export class SearchAuditEntriesHandler implements QueryHandler<SearchAuditEntriesQuery> {
+  constructor(private readonly reader: AuditReader) {}
+
+  /**
+   * The permission was decided by the guard of the bus. The tenant of the actor then bounds the
+   * read itself, in the statement and never in memory: a tenant lists its own chain, and only an
+   * actor that belongs to no tenant (an operator of the platform) lists them all.
+   */
+  async execute(query: SearchAuditEntriesQuery): Promise<Page<AuditEntry>> {
+    const { tenantId } = query.actor;
+
+    return this.reader.search({ ...query.filter, ...(tenantId === undefined ? {} : { tenantId }) }, query.page);
+  }
+}

package/templates/init/platform/audit/search-audit-entries.query.ts.tpl

@@ -0,0 +1,16 @@
+import type { AuditEntry, AuditFilter, AuditSortField } from '@ddd-ts-kit/audit';
+import { AuthorizedQuery, type Actor, type Page, type PageRequest } from '@ddd-ts-kit/kernel';
+
+/** What a reader of the trail may narrow the search by. The tenant is not among them: it is the one of the actor. */
+export type AuditEntriesFilter = Pick<AuditFilter, 'actorId' | 'action' | 'outcome' | 'correlationId'>;
+
+/** A page of the audit trail, for whoever holds `audit:trail.read`. */
+export class SearchAuditEntriesQuery extends AuthorizedQuery<Page<AuditEntry>> {
+  constructor(
+    actor: Actor,
+    readonly page: PageRequest<AuditSortField>,
+    readonly filter: AuditEntriesFilter = {},
+  ) {
+    super(actor);
+  }
+}

package/templates/init/platform/audit/search-audit-entries.route.ts.tpl

@@ -0,0 +1,197 @@
+import type { AuditEntry } from '@ddd-ts-kit/audit';
+import { actorOf } from '@ddd-ts-kit/auth';
+import {
+  defineRoute,
+  pageRequestFrom,
+  pageRequestParameters,
+  pageResponse,
+  pageSchemaOf,
+  type Route,
+} from '@ddd-ts-kit/http';
+import { err, ok, type QueryBus } from '@ddd-ts-kit/kernel';
+import { customSchema, type JsonSchema } from '@ddd-ts-kit/validation';
+import { SearchAuditEntriesQuery, type AuditEntriesFilter } from '{{alias.platform}}/audit/search-audit-entries.query.js';
+
+/** Newest first unless asked otherwise, by cursor: the trail only grows, an offset would shift under the reader. */
+const pageLimits = { sortable: ['occurredAt', 'sequence'], maxSize: 100, kind: 'cursor' } as const;
+const outcomes = ['allowed', 'denied', 'succeeded', 'failed'] as const;
+
+type Parameters = Readonly<Record<string, unknown>>;
+
+const query = customSchema<Parameters>(
+  (input) =>
+    isRecord(input) ? ok(input) : err([{ path: '', code: 'invalid_type', message: 'Expected query parameters.' }]),
+  {
+    type: 'object',
+    properties: {
+      ...propertiesOf(pageRequestParameters(pageLimits)),
+      actorId: { type: 'string', description: 'Entries about what this actor did.' },
+      action: { type: 'string', description: 'A permission id, a command name or an event type.' },
+      outcome: { type: 'string', enum: [...outcomes] },
+      correlationId: { type: 'string', description: 'Everything one request or event caused.' },
+    },
+  },
+);
+
+/** What leaves the process: identifiers and codes, as the trail holds them. `changes` and `extensions` stay inside. */
+interface AuditEntryView {
+  readonly id: string;
+  readonly chain: string;
+  readonly sequence: number;
+  readonly occurredAt: string;
+  readonly category: string;
+  readonly action: string;
+  readonly outcome: string;
+  readonly reason?: string;
+  readonly actorId: string;
+  readonly actorType: string;
+  readonly tenantId?: string;
+  readonly resourceType?: string;
+  readonly resourceId?: string;
+  readonly context?: string;
+  readonly correlationId: string;
+  readonly causationId?: string;
+  readonly origin: string;
+  readonly previousHash: string;
+  readonly hash: string;
+}
+
+const text = { type: 'string' } as const;
+
+const entry = customSchema<AuditEntryView>(
+  (input) =>
+    isEntryView(input) ? ok(input) : err([{ path: '', code: 'invalid_type', message: 'Expected an audit entry.' }]),
+  {
+    type: 'object',
+    required: [
+      'id',
+      'chain',
+      'sequence',
+      'occurredAt',
+      'category',
+      'action',
+      'outcome',
+      'actorId',
+      'actorType',
+      'correlationId',
+      'origin',
+      'previousHash',
+      'hash',
+    ],
+    properties: {
+      id: text,
+      chain: text,
+      sequence: { type: 'integer', minimum: 1 },
+      occurredAt: { type: 'string', format: 'date-time' },
+      category: text,
+      action: text,
+      outcome: { type: 'string', enum: [...outcomes] },
+      reason: text,
+      actorId: text,
+      actorType: text,
+      tenantId: text,
+      resourceType: text,
+      resourceId: text,
+      context: text,
+      correlationId: text,
+      causationId: text,
+      origin: text,
+      previousHash: text,
+      hash: text,
+    },
+  },
+);
+
+/** The audit trail as a protected read: a use case like any other, so reading it is authorized and recorded. */
+export function searchAuditEntriesRoute(queries: QueryBus): Route {
+  return defineRoute(
+    {
+      method: 'GET',
+      path: '/audit/entries',
+      operationId: 'searchAuditEntries',
+      summary: 'Search the entries of the audit trail',
+      tags: ['audit'],
+      request: { query },
+      responses: { 200: { description: 'A page of entries.', body: pageSchemaOf(entry) } },
+      errors: ['UNAUTHORIZED', 'FORBIDDEN'],
+      security: ['{{authn.scheme}}'],
+    },
+    async (input) => {
+      const page = await queries.execute(
+        new SearchAuditEntriesQuery(
+          actorOf(input.context.principal),
+          pageRequestFrom(input.query, pageLimits),
+          filterOf(input.query),
+        ),
+      );
+
+      return { status: 200, body: pageResponse(page, toView) };
+    },
+  );
+}
+
+function filterOf(parameters: Parameters): AuditEntriesFilter {
+  const outcome = outcomes.find((candidate) => candidate === parameters['outcome']);
+
+  return {
+    ...textOf(parameters, 'actorId'),
+    ...textOf(parameters, 'action'),
+    ...textOf(parameters, 'correlationId'),
+    ...(outcome === undefined ? {} : { outcome }),
+  };
+}
+
+function textOf<Key extends string>(parameters: Parameters, key: Key): Partial<Record<Key, string>> {
+  const value = parameters[key];
+  const found: Partial<Record<Key, string>> = {};
+
+  if (typeof value === 'string' && value !== '') {
+    found[key] = value;
+  }
+
+  return found;
+}
+
+function toView(source: AuditEntry): AuditEntryView {
+  const { actor, resource } = source;
+
+  return {
+    id: source.id,
+    chain: source.chain,
+    sequence: source.sequence,
+    occurredAt: source.occurredAt.toISOString(),
+    category: source.category,
+    action: source.action,
+    outcome: source.outcome,
+    ...(source.reason === undefined ? {} : { reason: source.reason }),
+    actorId: actor.id,
+    actorType: actor.type,
+    ...(source.tenantId === undefined ? {} : { tenantId: source.tenantId }),
+    ...(resource === undefined ? {} : { resourceType: resource.type, resourceId: resource.id }),
+    ...(source.context === undefined ? {} : { context: source.context }),
+    correlationId: source.correlationId,
+    ...(source.causationId === undefined ? {} : { causationId: source.causationId }),
+    origin: source.origin,
+    previousHash: source.previousHash,
+    hash: source.hash,
+  };
+}
+
+function propertiesOf(schema: JsonSchema): JsonSchema {
+  const { properties } = schema;
+
+  return typeof properties === 'object' && properties !== null ? { ...properties } : {};
+}
+
+function isRecord(input: unknown): input is Parameters {
+  return typeof input === 'object' && input !== null && !Array.isArray(input);
+}
+
+function isEntryView(input: unknown): input is AuditEntryView {
+  return (
+    isRecord(input) &&
+    typeof input['id'] === 'string' &&
+    typeof input['hash'] === 'string' &&
+    typeof input['sequence'] === 'number'
+  );
+}

package/templates/init/platform/auth/access-policies.ts.tpl

@@ -0,0 +1,9 @@
+import type { Policy } from '@ddd-ts-kit/auth';
+// ddd-ts-kit:imports
+// /ddd-ts-kit:imports
+
+/** The rules about one element that `Access.authorize` asks before the authorizer, from every context. */
+export const accessPolicies: readonly Policy<unknown>[] = [
+  // ddd-ts-kit:policies
+  // /ddd-ts-kit:policies
+];

package/templates/init/platform/auth/attribute-policies.ts.tpl

@@ -0,0 +1,16 @@
+import { permit, type AttributePolicy, type Condition } from '@ddd-ts-kit/auth';
+
+const isAdministrator: Condition = ({ actor }) => actor.roles.includes('admin');
+
+/**
+ * The rules, over `{ actor, permission, resource, attributes, context, now }`. A matching `forbid`
+ * wins over every `permit`; with no matching `permit` the answer is no. Rules that read the
+ * resource need a `ResourceAttributes` port given to the authorizer as `attributes`. A scheduled
+ * job acts as a system actor of its own: `generate job` adds the rule that permits it its command.
+ */
+// TODO(platform): replace this starting point by the rules of the organisation.
+export const attributePolicies: readonly AttributePolicy[] = [
+  permit('administrators-do-everything', ['*'], isAdministrator),
+  // ddd-ts-kit:system-grants
+  // /ddd-ts-kit:system-grants
+];

package/templates/init/platform/auth/authorization.tsyringe.ts.tpl

@@ -0,0 +1,25 @@
+{{#if http.any}}
+import type { Authenticator, OnDecision } from '@ddd-ts-kit/auth';
+{{/if}}
+{{#unless http.any}}
+import type { OnDecision } from '@ddd-ts-kit/auth';
+{{/unless}}
+import { authorizationModule } from '@ddd-ts-kit/auth/di';
+import type { ContextModule } from '@ddd-ts-kit/di';
+import { accessPolicies } from '{{alias.platform}}/auth/access-policies.js';
+import { createAuthorizer } from '{{alias.platform}}/auth/create-authorizer.js';
+
+/**
+ * Binds `Authorizer`, the guard both buses ask before any handler, the `Access` of the policies{{#if http.any}} and
+ * the `Authenticator` of the HTTP boundary{{/if}}; `onDecision` is told every decision, allowed or refused.
+ */
+{{#if http.any}}
+export function authorization(onDecision: OnDecision, authenticator: Authenticator): ContextModule {
+  return authorizationModule({ authorizer: createAuthorizer(), authenticator, policies: accessPolicies, onDecision });
+}
+{{/if}}
+{{#unless http.any}}
+export function authorization(onDecision: OnDecision): ContextModule {
+  return authorizationModule({ authorizer: createAuthorizer(), policies: accessPolicies, onDecision });
+}
+{{/unless}}

package/templates/init/platform/auth/create-authenticator.jwt.ts.tpl

@@ -0,0 +1,12 @@
+import type { Authenticator } from '@ddd-ts-kit/auth';
+import { JwtAuthenticator } from '@ddd-ts-kit/auth/jwt';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+
+/** Verifies the bearer token against the keys the issuer publishes. The session keeps nothing of the token. */
+export function createAuthenticator(config: AppConfig): Authenticator {
+  return new JwtAuthenticator({
+    issuer: config.auth.issuer,
+    audience: config.auth.audience,
+    jwksUri: config.auth.jwksUri,
+  });
+}

package/templates/init/platform/auth/create-authenticator.keycloak.ts.tpl

@@ -0,0 +1,15 @@
+import type { Authenticator } from '@ddd-ts-kit/auth';
+import { keycloakAuthenticator } from '@ddd-ts-kit/auth/jwt';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+
+/**
+ * Verifies the access tokens of the Keycloak realm against the keys it publishes. The actor takes
+ * its roles from the realm roles (and from the client roles of `KEYCLOAK_CLIENT_ID` when set), its
+ * tenant from the `tenant_id` claim; the session keeps nothing of the token. The realm needs an
+ * audience mapper naming this API: docker/keycloak holds a realm that has one, for local use.
+ */
+export function createAuthenticator(config: AppConfig): Authenticator {
+  const { baseUrl, realm, audience, clientId } = config.keycloak;
+
+  return keycloakAuthenticator({ baseUrl, realm, audience, ...(clientId === undefined ? {} : { clientId }) });
+}

package/templates/init/platform/auth/create-authenticator.none.ts.tpl

@@ -0,0 +1,8 @@
+import type { Authenticator } from '@ddd-ts-kit/auth';
+import type { AppConfig } from '{{alias.platform}}/config/app-config.js';
+import { DevelopmentHeaderAuthenticator } from '{{alias.platform}}/auth/development-header-authenticator.js';
+
+// TODO(platform): replace the development authenticator by a real adapter of Authenticator (a JWT verifier, your identity provider) before the first deployment.
+export function createAuthenticator(config: AppConfig): Authenticator {
+  return new DevelopmentHeaderAuthenticator(config.environment);
+}

package/templates/init/platform/auth/create-authorizer.abac.ts.tpl

@@ -0,0 +1,8 @@
+import { PolicyBasedAuthorizer, type Authorizer } from '@ddd-ts-kit/auth';
+import { SystemClock } from '@ddd-ts-kit/kernel';
+import { attributePolicies } from '{{alias.platform}}/auth/attribute-policies.js';
+
+/** Attribute policies: do the attributes of the actor, the resource and the moment satisfy a rule? */
+export function createAuthorizer(): Authorizer {
+  return new PolicyBasedAuthorizer({ clock: new SystemClock(), policies: attributePolicies });
+}

package/templates/init/platform/auth/create-authorizer.custom.ts.tpl

@@ -0,0 +1,8 @@
+import type { Authorizer } from '@ddd-ts-kit/auth';
+import { CustomAuthorizer } from '{{alias.platform}}/auth/custom-authorizer.js';
+import { permissions } from '{{alias.platform}}/auth/permissions.js';
+
+// TODO(platform): give the adapter what your model needs (a client of the service that decides, its mapping) instead of this table granting everything to the role "admin".
+export function createAuthorizer(): Authorizer {
+  return new CustomAuthorizer({ admin: permissions.all().map((permission) => permission.id) });
+}

package/templates/init/platform/auth/create-authorizer.rbac.ts.tpl

@@ -0,0 +1,7 @@
+import { RoleBasedAuthorizer, type Authorizer } from '@ddd-ts-kit/auth';
+import { roles } from '{{alias.platform}}/auth/roles.js';
+
+/** Roles: does one of the actor's roles grant this action? Another model is another adapter of the same port. */
+export function createAuthorizer(): Authorizer {
+  return new RoleBasedAuthorizer({ roles, systemRole: 'system' });
+}

package/templates/init/platform/auth/create-authorizer.rebac.ts.tpl

@@ -0,0 +1,14 @@
+import type { Authorizer } from '@ddd-ts-kit/auth';
+import { RelationBasedAuthorizer } from '@ddd-ts-kit/auth/rebac';
+import { permissionMapping } from '{{alias.platform}}/auth/permission-mapping.js';
+import { relationTuples } from '{{alias.platform}}/auth/relation-tuples.js';
+import { relationshipSchema } from '{{alias.platform}}/auth/relationship-schema.js';
+
+/** Relationships: is there a path of stored tuples from this element to the actor? */
+export function createAuthorizer(): Authorizer {
+  return new RelationBasedAuthorizer({
+    schema: relationshipSchema,
+    store: relationTuples,
+    mapping: permissionMapping(),
+  });
+}

package/templates/init/platform/auth/create-tuple-store.contract.spec.ts.tpl

@@ -0,0 +1,8 @@
+import { beforeEach, describe, expect, it } from '{{tests.module}}';
+import { relationTupleStoreContract } from '@ddd-ts-kit/auth/testing';
+import { createTupleStore } from '{{alias.platform}}/auth/create-tuple-store.js';
+
+relationTupleStoreContract(
+  { describe, it, expect, beforeEach },
+  { name: 'The relation tuple store of the platform', create: createTupleStore },
+);

package/templates/init/platform/auth/create-tuple-store.ts.tpl

@@ -0,0 +1,6 @@
+import { InMemoryRelationTupleStore, type RelationTupleStore } from '@ddd-ts-kit/auth/rebac';
+
+// TODO(platform): answer a persistent store (a table written in the transaction of the change it describes) and hold it to relationTupleStoreContract, as create-tuple-store.contract.spec.ts does for this one.
+export function createTupleStore(): RelationTupleStore {
+  return new InMemoryRelationTupleStore();
+}

package/templates/init/platform/auth/custom-authorizer.contract.spec.ts.tpl

@@ -0,0 +1,25 @@
+import { beforeEach, describe, expect, it } from '{{tests.module}}';
+import { definePermissions } from '@ddd-ts-kit/auth';
+import { anActor, authorizerContract } from '@ddd-ts-kit/auth/testing';
+import { CustomAuthorizer } from '{{alias.platform}}/auth/custom-authorizer.js';
+
+const permissions = definePermissions('contract', {
+  'element.read': { description: 'Read an element' },
+  'element.write': { description: 'Write an element' },
+});
+
+authorizerContract(
+  { describe, it, expect, beforeEach },
+  {
+    name: 'The custom authorizer',
+    create: () => {
+      const reader = anActor().named('ada').withRole('reader').build();
+
+      return {
+        authorizer: new CustomAuthorizer({ reader: [permissions['element.read'].id] }),
+        granted: { actor: reader, permission: permissions['element.read'] },
+        refused: { actor: reader, permission: permissions['element.write'] },
+      };
+    },
+  },
+);

package/templates/init/platform/auth/custom-authorizer.ts.tpl

@@ -0,0 +1,40 @@
+import {
+  ALLOWED,
+  DenialReason,
+  deny,
+  type AccessScope,
+  type Authorizer,
+  type CheckRequest,
+  type Decision,
+  type ListRequest,
+} from '@ddd-ts-kit/auth';
+import { isAnonymous, type Actor } from '@ddd-ts-kit/kernel';
+
+const notGranted = 'NOT_GRANTED';
+
+/**
+ * The adapter of the `Authorizer` port for a model of your own, or for a service that decides
+ * (OpenFGA, SpiceDB, a policy engine). This stub reads a table of permission ids by role, so
+ * that the application runs; custom-authorizer.contract.spec.ts holds whatever replaces it to
+ * what the middleware and the handlers rely on.
+ */
+// TODO(platform): replace the table by calls to your model, keeping the reasons as stable machine codes.
+export class CustomAuthorizer implements Authorizer {
+  constructor(private readonly grants: Readonly<Record<string, readonly string[]>>) {}
+
+  async check({ actor, permission }: CheckRequest): Promise<Decision> {
+    if (isAnonymous(actor)) {
+      return deny(DenialReason.anonymous);
+    }
+
+    return this.granted(actor, permission.id) ? ALLOWED : deny(notGranted);
+  }
+
+  async listAccessible({ actor, permission }: ListRequest): Promise<AccessScope> {
+    return !isAnonymous(actor) && this.granted(actor, permission.id) ? { kind: 'all' } : { kind: 'none' };
+  }
+
+  private granted(actor: Actor, permissionId: string): boolean {
+    return actor.roles.some((role) => this.grants[role]?.includes(permissionId) === true);
+  }
+}

package/templates/init/platform/auth/development-actor-header.ts.tpl

@@ -0,0 +1,2 @@
+/** The header the development authenticator trusts: `<id>`, `<id>;roles=<a>,<b>` or `<id>;roles=<a>;tenant=<t>`. */
+export const developmentActorHeader = 'x-development-actor';

package/templates/init/platform/auth/development-header-authenticator.ts.tpl

@@ -0,0 +1,37 @@
+import { InvalidCredentialError, type Authenticator } from '@ddd-ts-kit/auth';
+import { anonymousActor, type Actor } from '@ddd-ts-kit/kernel';
+
+/**
+ * Development only: trusts a header instead of verifying a credential. The header reads
+ * `<id>`, `<id>;roles=<a>,<b>` or `<id>;roles=<a>;tenant=<t>`. It refuses to exist in production.
+ */
+export class DevelopmentHeaderAuthenticator implements Authenticator {
+  constructor(environment: string) {
+    if (environment === 'production') {
+      throw new Error(
+        'DevelopmentHeaderAuthenticator must never run in production: bind a real adapter of Authenticator',
+      );
+    }
+  }
+
+  async authenticate(credential: string | undefined): Promise<Actor> {
+    if (credential === undefined) {
+      return anonymousActor();
+    }
+
+    const [id = '', ...settings] = credential.split(';').map((part) => part.trim());
+
+    if (id === '') {
+      throw new InvalidCredentialError('MALFORMED_DEVELOPMENT_ACTOR');
+    }
+
+    const tenantId = valueOf(settings, 'tenant');
+    const roles = (valueOf(settings, 'roles') ?? '').split(',').filter((role) => role !== '');
+
+    return { id, type: 'user', roles, attributes: {}, ...(tenantId === undefined ? {} : { tenantId }) };
+  }
+}
+
+function valueOf(settings: readonly string[], key: string): string | undefined {
+  return settings.find((setting) => setting.startsWith(key + '='))?.slice(key.length + 1);
+}