ddd-ts-kit 0.14.0 → 0.15.0

package/templates/presets/identity/context/domain/value-objects/display-name.vo.ts.tpl

@@ -0,0 +1,29 @@
+import { ValueObject } from '@ddd-ts-kit/kernel';
+import { AccountError } from '{{alias.context}}/domain/errors/account.error{{alias.ext}}';
+
+const LONGEST = 100;
+
+export type DisplayNameProps = {
+  readonly value: string;
+};
+
+/** How a person is shown to the others, as they or their identity provider wrote it, spaces at the ends removed. */
+export class DisplayName extends ValueObject<DisplayNameProps> {
+  private constructor(props: DisplayNameProps) {
+    super(props);
+  }
+
+  static create(raw: string): DisplayName {
+    const value = raw.trim();
+
+    if (value.length === 0 || value.length > LONGEST) {
+      throw AccountError.invalidDisplayName(raw);
+    }
+
+    return new DisplayName({ value });
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}

package/templates/presets/identity/context/domain/value-objects/email-address.vo.ts.tpl

@@ -0,0 +1,31 @@
+import { ValueObject } from '@ddd-ts-kit/kernel';
+import { AccountError } from '{{alias.context}}/domain/errors/account.error{{alias.ext}}';
+
+/** The longest address the standards allow (RFC 5321, a path of 256 characters and its two brackets). */
+const LONGEST = 254;
+const SHAPE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export type EmailAddressProps = {
+  readonly value: string;
+};
+
+/** Where a person is reached, compared without case: `Ada@Example.org` and `ada@example.org` are one address. */
+export class EmailAddress extends ValueObject<EmailAddressProps> {
+  private constructor(props: EmailAddressProps) {
+    super(props);
+  }
+
+  static create(raw: string): EmailAddress {
+    const value = raw.trim().toLowerCase();
+
+    if (value.length > LONGEST || !SHAPE.test(value)) {
+      throw AccountError.invalidEmailAddress(raw);
+    }
+
+    return new EmailAddress({ value });
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}

package/templates/presets/identity/context/domain/value-objects/organisation-name.vo.ts.tpl

@@ -0,0 +1,29 @@
+import { ValueObject } from '@ddd-ts-kit/kernel';
+import { OrganisationError } from '{{alias.context}}/domain/errors/organisation.error{{alias.ext}}';
+
+const LONGEST = 100;
+
+export type OrganisationNameProps = {
+  readonly value: string;
+};
+
+/** The name an organisation is shown under: free text, unlike its slug. */
+export class OrganisationName extends ValueObject<OrganisationNameProps> {
+  private constructor(props: OrganisationNameProps) {
+    super(props);
+  }
+
+  static create(raw: string): OrganisationName {
+    const value = raw.trim();
+
+    if (value.length === 0 || value.length > LONGEST) {
+      throw OrganisationError.invalidOrganisationName(raw);
+    }
+
+    return new OrganisationName({ value });
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}

package/templates/presets/identity/context/domain/value-objects/organisation-rights.vo.ts.tpl

@@ -0,0 +1,43 @@
+import { ValueObject } from '@ddd-ts-kit/kernel';
+import type { MemberRight } from '{{alias.context}}/domain/vocabularies/member-right.vocabulary{{alias.ext}}';
+
+export type OrganisationRightsProps = {
+  readonly organisationId: string;
+  readonly accountId: string;
+  readonly rights: readonly MemberRight[];
+};
+
+/**
+ * What one account may do in one organisation at one instant: the rights of its role, and those
+ * an active delegation lends it. The policies of the context decide on it; the platform authorizer
+ * is asked about the resource it names, the context, as for every use case of the context.
+ */
+export class OrganisationRights extends ValueObject<OrganisationRightsProps> {
+  readonly type = 'context';
+
+  readonly id = '{{context.kebab}}';
+
+  private constructor(props: OrganisationRightsProps) {
+    super(props);
+  }
+
+  static of(organisationId: string, accountId: string, rights: readonly MemberRight[]): OrganisationRights {
+    return new OrganisationRights({ organisationId, accountId, rights: [...new Set(rights)].sort() });
+  }
+
+  includes(right: MemberRight): boolean {
+    return this.props.rights.includes(right);
+  }
+
+  get organisationId(): string {
+    return this.props.organisationId;
+  }
+
+  get accountId(): string {
+    return this.props.accountId;
+  }
+
+  get rights(): readonly MemberRight[] {
+    return this.props.rights;
+  }
+}

package/templates/presets/identity/context/domain/value-objects/organisation-slug.vo.ts.tpl

@@ -0,0 +1,30 @@
+import { ValueObject } from '@ddd-ts-kit/kernel';
+import { OrganisationError } from '{{alias.context}}/domain/errors/organisation.error{{alias.ext}}';
+
+/** Lower-case letters, digits and hyphens, at most 63: a slug is also a valid tenant id and a valid alias of the identity provider. */
+const SHAPE = /^[a-z0-9][a-z0-9-]{1,62}$/;
+
+export type OrganisationSlugProps = {
+  readonly value: string;
+};
+
+/** The identifier of an organisation, chosen when it opens and never changed: in addresses, in tokens, as its tenant. */
+export class OrganisationSlug extends ValueObject<OrganisationSlugProps> {
+  private constructor(props: OrganisationSlugProps) {
+    super(props);
+  }
+
+  static create(raw: string): OrganisationSlug {
+    const value = raw.trim().toLowerCase();
+
+    if (!SHAPE.test(value)) {
+      throw OrganisationError.invalidOrganisationSlug(raw);
+    }
+
+    return new OrganisationSlug({ value });
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+}

package/templates/presets/identity/context/domain/vocabularies/account-status.vocabulary.ts.tpl

@@ -0,0 +1,7 @@
+/** Whether an account may still act: a deactivated account keeps its history and signs in no more. */
+export const AccountStatus = {
+  Active: 'active',
+  Deactivated: 'deactivated',
+} as const;
+
+export type AccountStatus = (typeof AccountStatus)[keyof typeof AccountStatus];

package/templates/presets/identity/context/domain/vocabularies/invitation-status.vocabulary.ts.tpl

@@ -0,0 +1,9 @@
+/** Where an invitation stands: pending until the person it is addressed to answers, or the organisation takes it back. */
+export const InvitationStatus = {
+  Pending: 'pending',
+  Accepted: 'accepted',
+  Declined: 'declined',
+  Revoked: 'revoked',
+} as const;
+
+export type InvitationStatus = (typeof InvitationStatus)[keyof typeof InvitationStatus];

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,
+    };
+  },
+};