ddd-ts-kit 0.13.0 → 0.15.0

package/templates/presets/identity/context/domain/vocabularies/member-right.vocabulary.ts.tpl

@@ -0,0 +1,9 @@
+/** What a member may do in an organisation, granted by a role or lent by a delegation. */
+export const MemberRight = {
+  ReadMembers: 'read-members',
+  InviteMembers: 'invite-members',
+  ManageMembers: 'manage-members',
+  GrantDelegations: 'grant-delegations',
+} as const;
+
+export type MemberRight = (typeof MemberRight)[keyof typeof MemberRight];

package/templates/presets/identity/context/domain/vocabularies/member-role.vocabulary.ts.tpl

@@ -0,0 +1,8 @@
+/** The role of a member in an organisation: what the member may do there follows from it (`RoleRightsService`). */
+export const MemberRole = {
+  Owner: 'owner',
+  Admin: 'admin',
+  Member: 'member',
+} as const;
+
+export type MemberRole = (typeof MemberRole)[keyof typeof MemberRole];

package/templates/presets/identity/context/infrastructure/external/crypto-invitation-tokens.adapter.ts.tpl

@@ -0,0 +1,20 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { Adapter } from '@ddd-ts-kit/kernel/declarations';
+import { InvitationTokens } from '{{alias.context}}/application/ports/invitation-tokens.port{{alias.ext}}';
+
+/** 256 bits: a token is never guessed, and never stored. */
+const TOKEN_BYTES = 32;
+
+/** Tokens drawn from the random source of the platform, kept as their SHA-256 digest. */
+@Adapter(InvitationTokens, { kind: 'external' })
+export class CryptoInvitationTokens implements InvitationTokens {
+  issue(): { token: string; digest: string } {
+    const token = randomBytes(TOKEN_BYTES).toString('base64url');
+
+    return { token, digest: this.digestOf(token) };
+  }
+
+  digestOf(token: string): string {
+    return createHash('sha256').update(token).digest('hex');
+  }
+}

package/templates/presets/identity/context/infrastructure/external/environment-identity-provider-connection.adapter.ts.tpl

@@ -0,0 +1,37 @@
+import { Adapter } from '@ddd-ts-kit/kernel/declarations';
+import { IdentityProviderConnection } from '{{alias.context}}/application/ports/identity-provider-connection.port{{alias.ext}}';
+
+/** The variables read, and what each one holds. */
+const VARIABLES = {
+  baseUrl: 'KEYCLOAK_URL',
+  realm: 'KEYCLOAK_REALM',
+  clientId: 'IDENTITY_PROVIDER_ADMIN_CLIENT_ID',
+  clientSecret: 'IDENTITY_PROVIDER_ADMIN_CLIENT_SECRET',
+} as const;
+
+/**
+ * The connection to the administration API of the provider, read from the environment when a call
+ * is made: an application that never calls it starts without it. A missing variable fails the
+ * call that needed it, with its name; its value is never written.
+ */
+@Adapter(IdentityProviderConnection, { kind: 'external' })
+export class EnvironmentIdentityProviderConnection implements IdentityProviderConnection {
+  async settings(): Promise<{ baseUrl: string; realm: string; clientId: string; clientSecret: string }> {
+    return {
+      baseUrl: variable(VARIABLES.baseUrl).replace(/\/+$/, ''),
+      realm: variable(VARIABLES.realm),
+      clientId: variable(VARIABLES.clientId),
+      clientSecret: variable(VARIABLES.clientSecret),
+    };
+  }
+}
+
+function variable(name: string): string {
+  const value = process.env[name] ?? '';
+
+  if (value.trim() === '') {
+    throw new Error(`${name} is not set: the administration API of the identity provider is out of reach.`);
+  }
+
+  return value;
+}

package/templates/presets/identity/context/infrastructure/external/keycloak-identity-provider-admin.adapter.ts.tpl

@@ -0,0 +1,149 @@
+import { Adapter } from '@ddd-ts-kit/kernel/declarations';
+import { IdentityProviderAdmin } from '{{alias.context}}/application/ports/identity-provider-admin.port{{alias.ext}}';
+import type { IdentityProviderConnection } from '{{alias.context}}/application/ports/identity-provider-connection.port{{alias.ext}}';
+
+const CONFLICT = 409;
+const NOT_FOUND = 404;
+
+/** How many organizations one read of the realm lists. */
+const PAGE = 100;
+
+interface Call {
+  readonly method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  readonly path: string;
+  readonly body?: unknown;
+  /** Statuses that mean the change is already there: a retry finds it done. */
+  readonly done?: readonly number[];
+}
+
+interface KeycloakOrganisation {
+  readonly id: string;
+  readonly alias: string;
+}
+
+/** One page of the organizations of the realm: the one under the alias if it is there, and whether more may follow. */
+interface SearchedPage {
+  readonly found: KeycloakOrganisation | undefined;
+  readonly full: boolean;
+}
+
+/**
+ * A recipe for the administration REST API of Keycloak (26 and later, which has organizations):
+ * the client of `IdentityProviderConnection` takes a token by the client credentials grant, then
+ * asks. An organisation is known there under its slug as alias, so that the `organization` claim
+ * of a token names it. Every change is idempotent, since the consumers that call it are delivered
+ * at least once (`application/integration/handlers/`). Its spec runs it against a local server
+ * that answers as Keycloak does, not against Keycloak itself: run it once against your realm
+ * before relying on it (docs/guides/bootstrap-with-well-designed-contexts.md says how).
+ */
+@Adapter(IdentityProviderAdmin, { kind: 'external' })
+export class KeycloakIdentityProviderAdmin implements IdentityProviderAdmin {
+  constructor(private readonly connection: IdentityProviderConnection) {}
+
+  async openOrganisation(organisation: { readonly id: string; readonly name: string }): Promise<void> {
+    const body = { name: organisation.name, alias: organisation.id, enabled: true };
+
+    await this.send({ method: 'POST', path: 'organizations', body, done: [CONFLICT] });
+  }
+
+  async addMember(organisationId: string, accountId: string): Promise<void> {
+    const keycloakId = await this.organisationNamed(organisationId);
+
+    await this.send({ method: 'POST', path: `organizations/${keycloakId}/members`, body: accountId, done: [CONFLICT] });
+  }
+
+  async removeMember(organisationId: string, accountId: string): Promise<void> {
+    const keycloakId = await this.organisationNamed(organisationId);
+    const path = `organizations/${keycloakId}/members/${encodeURIComponent(accountId)}`;
+
+    await this.send({ method: 'DELETE', path, done: [NOT_FOUND] });
+  }
+
+  async disableAccount(accountId: string): Promise<void> {
+    await this.send({ method: 'PUT', path: `users/${encodeURIComponent(accountId)}`, body: { enabled: false } });
+  }
+
+  /** Keycloak searches organizations by name, not by alias: its pages are read until the alias is found. */
+  private async organisationNamed(alias: string): Promise<string> {
+    let first = 0;
+    let page = await this.searchPage(alias, first);
+
+    while (page.found === undefined && page.full) {
+      first += PAGE;
+      page = await this.searchPage(alias, first);
+    }
+
+    if (page.found === undefined) {
+      throw new Error(`Keycloak knows no organization under the alias ${alias}.`);
+    }
+
+    return page.found.id;
+  }
+
+  private async searchPage(alias: string, first: number): Promise<SearchedPage> {
+    const answer = await this.send({ method: 'GET', path: `organizations?briefRepresentation=true&first=${first}&max=${PAGE}` });
+    const listed: unknown = await answer.json();
+
+    if (!Array.isArray(listed)) {
+      return { found: undefined, full: false };
+    }
+
+    return { found: listed.find((candidate) => isOrganisation(candidate, alias)), full: listed.length === PAGE };
+  }
+
+  private async send(call: Call): Promise<Response> {
+    const { baseUrl, realm } = await this.connection.settings();
+    const headers = { authorization: `Bearer ${await this.token()}`, 'content-type': 'application/json' };
+    const body = call.body === undefined ? {} : { body: JSON.stringify(call.body) };
+
+    const answer = await fetch(`${baseUrl}/admin/realms/${realm}/${call.path}`, {
+      method: call.method,
+      headers,
+      ...body,
+    });
+
+    if (!answer.ok && !(call.done ?? []).includes(answer.status)) {
+      throw new Error(`Keycloak answered ${answer.status} to ${call.method} ${call.path.split('?')[0] ?? ''}.`);
+    }
+
+    return answer;
+  }
+
+  private async token(): Promise<string> {
+    const { baseUrl, realm, clientId, clientSecret } = await this.connection.settings();
+    const grant = { grant_type: 'client_credentials', client_id: clientId, client_secret: clientSecret };
+
+    const answer = await fetch(`${baseUrl}/realms/${realm}/protocol/openid-connect/token`, {
+      method: 'POST',
+      body: new URLSearchParams(grant),
+    });
+
+    const granted: unknown = await answer.json();
+
+    if (!answer.ok || !isToken(granted)) {
+      throw new Error(`Keycloak refused a token to the client ${clientId} (${answer.status}).`);
+    }
+
+    return granted.access_token;
+  }
+}
+
+function isOrganisation(candidate: unknown, alias: string): candidate is KeycloakOrganisation {
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    'id' in candidate &&
+    typeof candidate.id === 'string' &&
+    'alias' in candidate &&
+    candidate.alias === alias
+  );
+}
+
+function isToken(granted: unknown): granted is { readonly access_token: string } {
+  return (
+    typeof granted === 'object' &&
+    granted !== null &&
+    'access_token' in granted &&
+    typeof granted.access_token === 'string'
+  );
+}

package/templates/presets/identity/context/infrastructure/persistence/__context__.schema.drizzle.ts.tpl

@@ -0,0 +1,102 @@
+// ddd-ts-kit:imports
+import { sql } from 'drizzle-orm';
+import { index, integer, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
+import { auditColumns, contextSchema } from '@ddd-ts-kit/drizzle/postgres';
+import type { AccountStatus } from '{{alias.context}}/domain/vocabularies/account-status.vocabulary{{alias.ext}}';
+import type { InvitationStatus } from '{{alias.context}}/domain/vocabularies/invitation-status.vocabulary{{alias.ext}}';
+import type { MemberRole } from '{{alias.context}}/domain/vocabularies/member-role.vocabulary{{alias.ext}}';
+// /ddd-ts-kit:imports
+
+/**
+ * The tables of {{context.kebab}}: what the provider authenticates stays with it, no password is stored.
+{{#if tenancy.any}}
+ * They hold no tenant column: the organisations are the tenants, and this context decides who
+ * belongs to which ({{preset.adr}}).
+{{/if}}
+ */
+export const {{context.camel}}Schema = contextSchema('{{context.kebab}}');
+
+const instant = (name: string) => timestamp(name, { withTimezone: true, mode: 'date' });
+
+// ddd-ts-kit:tables
+/** Keyed by the subject the identity provider gives the person. */
+export const accounts = {{context.camel}}Schema.table('accounts', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull(),
+  displayName: text('display_name').notNull(),
+  status: text('status').$type<AccountStatus>().notNull(),
+  provisionedAt: instant('provisioned_at').notNull(),
+  deactivatedAt: instant('deactivated_at'),
+  version: integer('version').notNull(),
+  ...auditColumns(),
+});
+
+/** Keyed by the slug, which is also the tenant id when the project has tenants. */
+export const organisations = {{context.camel}}Schema.table('organisations', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  openedBy: text('opened_by').notNull(),
+  openedAt: instant('opened_at').notNull(),
+  version: integer('version').notNull(),
+  ...auditColumns(),
+});
+
+/** One current membership per account and organisation: the partial unique index is the guard. */
+export const members = {{context.camel}}Schema.table(
+  'members',
+  {
+    id: text('id').primaryKey(),
+    organisationId: text('organisation_id').notNull(),
+    accountId: text('account_id').notNull(),
+    role: text('role').$type<MemberRole>().notNull(),
+    joinedAt: instant('joined_at').notNull(),
+    removedAt: instant('removed_at'),
+    version: integer('version').notNull(),
+    ...auditColumns(),
+  },
+  (table) => [
+    uniqueIndex('members_current_idx').on(table.organisationId, table.accountId).where(sql`removed_at is null`),
+    index('members_account_idx').on(table.accountId),
+  ],
+);
+
+export const invitations = {{context.camel}}Schema.table(
+  'invitations',
+  {
+    id: text('id').primaryKey(),
+    organisationId: text('organisation_id').notNull(),
+    email: text('email').notNull(),
+    role: text('role').$type<MemberRole>().notNull(),
+    tokenHash: text('token_hash').notNull().unique(),
+    invitedBy: text('invited_by').notNull(),
+    issuedAt: instant('issued_at').notNull(),
+    expiresAt: instant('expires_at').notNull(),
+    status: text('status').$type<InvitationStatus>().notNull(),
+    answeredAt: instant('answered_at'),
+    version: integer('version').notNull(),
+    ...auditColumns(),
+  },
+  (table) => [index('invitations_organisation_idx').on(table.organisationId, table.status)],
+);
+
+export const delegations = {{context.camel}}Schema.table(
+  'delegations',
+  {
+    id: text('id').primaryKey(),
+    organisationId: text('organisation_id').notNull(),
+    delegatorId: text('delegator_id').notNull(),
+    delegateId: text('delegate_id').notNull(),
+    /** The rights lent, separated by commas: a right is a word of `MemberRight`, which holds none. */
+    rights: text('rights').notNull(),
+    startsAt: instant('starts_at').notNull(),
+    endsAt: instant('ends_at').notNull(),
+    endedAt: instant('ended_at'),
+    version: integer('version').notNull(),
+    ...auditColumns(),
+  },
+  (table) => [
+    index('delegations_delegate_idx').on(table.organisationId, table.delegateId),
+    index('delegations_delegator_idx').on(table.organisationId, table.delegatorId),
+  ],
+);
+// /ddd-ts-kit:tables

package/templates/presets/identity/context/infrastructure/persistence/account-row.schema.knex.ts.tpl

@@ -0,0 +1,15 @@
+import type { AuditRow } from '@ddd-ts-kit/knex';
+import type { AccountStatus } from '{{alias.context}}/domain/vocabularies/account-status.vocabulary{{alias.ext}}';
+
+export interface AccountColumns {
+  readonly id: string;
+  readonly email: string;
+  readonly display_name: string;
+  readonly status: AccountStatus;
+  readonly provisioned_at: Date;
+  readonly deactivated_at: Date | null;
+}
+
+export interface AccountRow extends AccountColumns, AuditRow {
+  readonly version: number;
+}

package/templates/presets/identity/context/infrastructure/persistence/account.mapper.drizzle.ts.tpl

@@ -0,0 +1,38 @@
+import type { AuditStamp } from '@ddd-ts-kit/kernel';
+import { Account } from '{{alias.context}}/domain/aggregates/account.aggregate{{alias.ext}}';
+import { DisplayName } from '{{alias.context}}/domain/value-objects/display-name.vo{{alias.ext}}';
+import { EmailAddress } from '{{alias.context}}/domain/value-objects/email-address.vo{{alias.ext}}';
+import type { accounts } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema{{alias.ext}}';
+
+type AccountRow = typeof accounts.$inferSelect;
+
+export type AccountColumns = Omit<AccountRow, 'version' | keyof AuditStamp>;
+
+export const AccountMapper = {
+  toDomain(row: AccountRow): Account {
+    const loaded = Account.rehydrate(row.id, {
+      email: EmailAddress.create(row.email),
+      displayName: DisplayName.create(row.displayName),
+      status: row.status,
+      provisionedAt: row.provisionedAt,
+      deactivatedAt: row.deactivatedAt ?? undefined,
+    });
+
+    loaded.version = row.version;
+
+    return loaded;
+  },
+
+  toRow(saved: Account): AccountColumns {
+    const state = saved.toState();
+
+    return {
+      id: saved.id,
+      email: state.email.value,
+      displayName: state.displayName.value,
+      status: state.status,
+      provisionedAt: state.provisionedAt,
+      deactivatedAt: state.deactivatedAt ?? null,
+    };
+  },
+};

package/templates/presets/identity/context/infrastructure/persistence/account.mapper.knex.ts.tpl

@@ -0,0 +1,33 @@
+import { Account } from '{{alias.context}}/domain/aggregates/account.aggregate{{alias.ext}}';
+import { DisplayName } from '{{alias.context}}/domain/value-objects/display-name.vo{{alias.ext}}';
+import { EmailAddress } from '{{alias.context}}/domain/value-objects/email-address.vo{{alias.ext}}';
+import type { AccountColumns, AccountRow } from '{{alias.context}}/infrastructure/persistence/account-row.schema{{alias.ext}}';
+
+export const AccountMapper = {
+  toDomain(row: AccountRow): Account {
+    const loaded = Account.rehydrate(row.id, {
+      email: EmailAddress.create(row.email),
+      displayName: DisplayName.create(row.display_name),
+      status: row.status,
+      provisionedAt: row.provisioned_at,
+      deactivatedAt: row.deactivated_at ?? undefined,
+    });
+
+    loaded.version = row.version;
+
+    return loaded;
+  },
+
+  toRow(saved: Account): AccountColumns {
+    const state = saved.toState();
+
+    return {
+      id: saved.id,
+      email: state.email.value,
+      display_name: state.displayName.value,
+      status: state.status,
+      provisioned_at: state.provisionedAt,
+      deactivated_at: state.deactivatedAt ?? null,
+    };
+  },
+};

package/templates/presets/identity/context/infrastructure/persistence/create-__context__-tables.schema.knex.ts.tpl

@@ -0,0 +1,107 @@
+// ddd-ts-kit:imports
+import type { Knex } from 'knex';
+import { {{context.constant}}_SCHEMA } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema{{alias.ext}}';
+import { auditColumns } from '@ddd-ts-kit/knex';
+// /ddd-ts-kit:imports
+
+/**
+ * The tables of {{context.kebab}}: what the provider authenticates stays with it, no password is stored.
+{{#if tenancy.any}}
+ * They hold no tenant column: the organisations are the tenants, and this context decides who
+ * belongs to which ({{preset.adr}}).
+{{/if}}
+ */
+export async function create{{context.pascal}}Tables(knex: Knex): Promise<void> {
+  await knex.schema.createSchemaIfNotExists({{context.constant}}_SCHEMA);
+  // ddd-ts-kit:tables
+  await createAccountTable(knex);
+  await createOrganisationTable(knex);
+  await createMemberTable(knex);
+  await createInvitationTable(knex);
+  await createDelegationTable(knex);
+  // /ddd-ts-kit:tables
+}
+
+// ddd-ts-kit:definitions
+/** Keyed by the subject the identity provider gives the person. */
+function createAccountTable(knex: Knex): Promise<void> {
+  return knex.schema.withSchema({{context.constant}}_SCHEMA).createTable('accounts', (table) => {
+    table.text('id').primary();
+    table.text('email').notNullable();
+    table.text('display_name').notNullable();
+    table.text('status').notNullable();
+    table.timestamp('provisioned_at', { useTz: true }).notNullable();
+    table.timestamp('deactivated_at', { useTz: true });
+    table.integer('version').notNullable();
+    auditColumns(table);
+  });
+}
+
+/** Keyed by the slug, which is also the tenant id when the project has tenants. */
+function createOrganisationTable(knex: Knex): Promise<void> {
+  return knex.schema.withSchema({{context.constant}}_SCHEMA).createTable('organisations', (table) => {
+    table.text('id').primary();
+    table.text('name').notNullable();
+    table.text('opened_by').notNullable();
+    table.timestamp('opened_at', { useTz: true }).notNullable();
+    table.integer('version').notNullable();
+    auditColumns(table);
+  });
+}
+
+/** One current membership per account and organisation: the partial unique index is the guard. */
+function createMemberTable(knex: Knex): Promise<void> {
+  return knex.schema.withSchema({{context.constant}}_SCHEMA).createTable('members', (table) => {
+    table.text('id').primary();
+    table.text('organisation_id').notNullable();
+    table.text('account_id').notNullable();
+    table.text('role').notNullable();
+    table.timestamp('joined_at', { useTz: true }).notNullable();
+    table.timestamp('removed_at', { useTz: true });
+
+    table.unique(['organisation_id', 'account_id'], {
+      indexName: 'members_current_idx',
+      predicate: knex.whereNull('removed_at'),
+    });
+
+    table.index(['account_id']);
+    table.integer('version').notNullable();
+    auditColumns(table);
+  });
+}
+
+function createInvitationTable(knex: Knex): Promise<void> {
+  return knex.schema.withSchema({{context.constant}}_SCHEMA).createTable('invitations', (table) => {
+    table.text('id').primary();
+    table.text('organisation_id').notNullable();
+    table.text('email').notNullable();
+    table.text('role').notNullable();
+    table.text('token_hash').notNullable().unique();
+    table.text('invited_by').notNullable();
+    table.timestamp('issued_at', { useTz: true }).notNullable();
+    table.timestamp('expires_at', { useTz: true }).notNullable();
+    table.text('status').notNullable();
+    table.timestamp('answered_at', { useTz: true });
+    table.index(['organisation_id', 'status']);
+    table.integer('version').notNullable();
+    auditColumns(table);
+  });
+}
+
+function createDelegationTable(knex: Knex): Promise<void> {
+  return knex.schema.withSchema({{context.constant}}_SCHEMA).createTable('delegations', (table) => {
+    table.text('id').primary();
+    table.text('organisation_id').notNullable();
+    table.text('delegator_id').notNullable();
+    table.text('delegate_id').notNullable();
+    table.text('rights').notNullable();
+    table.timestamp('starts_at', { useTz: true }).notNullable();
+    table.timestamp('ends_at', { useTz: true }).notNullable();
+    table.timestamp('ended_at', { useTz: true });
+    table.index(['organisation_id', 'delegate_id']);
+    table.index(['organisation_id', 'delegator_id']);
+    table.integer('version').notNullable();
+    auditColumns(table);
+  });
+}
+// /ddd-ts-kit:definitions

package/templates/presets/identity/context/infrastructure/persistence/delegation-row.schema.knex.ts.tpl

@@ -0,0 +1,17 @@
+import type { AuditRow } from '@ddd-ts-kit/knex';
+
+export interface DelegationColumns {
+  readonly id: string;
+  readonly organisation_id: string;
+  readonly delegator_id: string;
+  readonly delegate_id: string;
+  /** The rights lent, separated by commas: a right is a word of `MemberRight`, which holds none. */
+  readonly rights: string;
+  readonly starts_at: Date;
+  readonly ends_at: Date;
+  readonly ended_at: Date | null;
+}
+
+export interface DelegationRow extends DelegationColumns, AuditRow {
+  readonly version: number;
+}

package/templates/presets/identity/context/infrastructure/persistence/delegation.mapper.drizzle.ts.tpl

@@ -0,0 +1,50 @@
+import type { AuditStamp } from '@ddd-ts-kit/kernel';
+import { Delegation } from '{{alias.context}}/domain/aggregates/delegation.aggregate{{alias.ext}}';
+import { DelegationPeriod } from '{{alias.context}}/domain/value-objects/delegation-period.vo{{alias.ext}}';
+import { MemberRight } from '{{alias.context}}/domain/vocabularies/member-right.vocabulary{{alias.ext}}';
+import type { delegations } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema{{alias.ext}}';
+
+const SEPARATOR = ',';
+
+type DelegationRow = typeof delegations.$inferSelect;
+
+export type DelegationColumns = Omit<DelegationRow, 'version' | keyof AuditStamp>;
+
+export const DelegationMapper = {
+  toDomain(row: DelegationRow): Delegation {
+    const loaded = Delegation.rehydrate(row.id, {
+      organisationId: row.organisationId,
+      delegatorId: row.delegatorId,
+      delegateId: row.delegateId,
+      rights: rightsOf(row.rights),
+      period: DelegationPeriod.create(row.startsAt, row.endsAt),
+      endedAt: row.endedAt ?? undefined,
+    });
+
+    loaded.version = row.version;
+
+    return loaded;
+  },
+
+  toRow(saved: Delegation): DelegationColumns {
+    const state = saved.toState();
+
+    return {
+      id: saved.id,
+      organisationId: state.organisationId,
+      delegatorId: state.delegatorId,
+      delegateId: state.delegateId,
+      rights: state.rights.join(SEPARATOR),
+      startsAt: state.period.startsAt,
+      endsAt: state.period.endsAt,
+      endedAt: state.endedAt ?? null,
+    };
+  },
+};
+
+/** The rights of a stored delegation, those the vocabulary no longer names left out. */
+function rightsOf(stored: string): MemberRight[] {
+  const lent = stored.split(SEPARATOR);
+
+  return Object.values(MemberRight).filter((right) => lent.includes(right));
+}

package/templates/presets/identity/context/infrastructure/persistence/delegation.mapper.knex.ts.tpl

@@ -0,0 +1,45 @@
+import { Delegation } from '{{alias.context}}/domain/aggregates/delegation.aggregate{{alias.ext}}';
+import { DelegationPeriod } from '{{alias.context}}/domain/value-objects/delegation-period.vo{{alias.ext}}';
+import { MemberRight } from '{{alias.context}}/domain/vocabularies/member-right.vocabulary{{alias.ext}}';
+import type { DelegationColumns, DelegationRow } from '{{alias.context}}/infrastructure/persistence/delegation-row.schema{{alias.ext}}';
+
+const SEPARATOR = ',';
+
+export const DelegationMapper = {
+  toDomain(row: DelegationRow): Delegation {
+    const loaded = Delegation.rehydrate(row.id, {
+      organisationId: row.organisation_id,
+      delegatorId: row.delegator_id,
+      delegateId: row.delegate_id,
+      rights: rightsOf(row.rights),
+      period: DelegationPeriod.create(row.starts_at, row.ends_at),
+      endedAt: row.ended_at ?? undefined,
+    });
+
+    loaded.version = row.version;
+
+    return loaded;
+  },
+
+  toRow(saved: Delegation): DelegationColumns {
+    const state = saved.toState();
+
+    return {
+      id: saved.id,
+      organisation_id: state.organisationId,
+      delegator_id: state.delegatorId,
+      delegate_id: state.delegateId,
+      rights: state.rights.join(SEPARATOR),
+      starts_at: state.period.startsAt,
+      ends_at: state.period.endsAt,
+      ended_at: state.endedAt ?? null,
+    };
+  },
+};
+
+/** The rights of a stored delegation, those the vocabulary no longer names left out. */
+function rightsOf(stored: string): MemberRight[] {
+  const lent = stored.split(SEPARATOR);
+
+  return Object.values(MemberRight).filter((right) => lent.includes(right));
+}