ddd-ts-kit 0.14.0 → 0.16.0

package/templates/presets/identity/context/test/unit/remove-member.handler.spec.ts.tpl

@@ -0,0 +1,125 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { MemberRight } from '{{alias.context}}/domain/vocabularies/member-right.vocabulary{{alias.ext}}';
+import { MemberRole } from '{{alias.context}}/domain/vocabularies/member-role.vocabulary{{alias.ext}}';
+import { RemoveMemberCommand } from '{{alias.context}}/application/commands/remove-member/remove-member.command{{alias.ext}}';
+import { aDelegation } from '{{alias.context}}/test/builders/delegation.builder{{alias.ext}}';
+import { aMember } from '{{alias.context}}/test/builders/member.builder{{alias.ext}}';
+import { anOrganisation } from '{{alias.context}}/test/builders/organisation.builder{{alias.ext}}';
+import { arrangeIdentity } from '{{alias.context}}/test/unit/identity-application{{alias.ext}}';
+
+const DAY = 86_400_000;
+
+describe('Remove member', () => {
+  it('removes the member, ends every delegation they gave or received, and tells the provider and the other contexts', async () => {
+    const { application, organisations, members, delegations, identityProvider, as } = arrangeIdentity();
+    const now = application.clock.now();
+
+    await organisations.save(anOrganisation().identifiedBy('acme').build());
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Admin).build());
+    await members.save(aMember().of('acme', 'subject-alan').build());
+
+    await delegations.save(
+      aDelegation()
+        .identifiedBy('delegation-1')
+        .to('subject-alan')
+        .lending(MemberRight.InviteMembers)
+        .between(now, new Date(now.getTime() + DAY))
+        .build(),
+    );
+
+    // Started once the organisation is arranged: what the provider is asked from now on follows the removal alone.
+    await application.start();
+
+    const before = application.eventBus.published.length;
+
+    await application.commandBus.execute(new RemoveMemberCommand(as('subject-ada'), 'acme', 'subject-alan'));
+
+    expect(await members.findOf('acme', 'subject-alan')).toBeUndefined();
+    expect((await delegations.findById('delegation-1'))?.isActiveAt(now)).toBe(false);
+    expect(identityProvider.asked).toEqual(['remove subject-alan from acme']);
+
+    expect(application.eventBus.published.slice(before).map((event) => event.type)).toEqual([
+      '{{context.kebab}}.member.removed',
+      '{{context.kebab}}.delegation.revoked',
+    ]);
+  });
+
+  it('refuses a person who is not a member, and keeps the last owner', async () => {
+    const { application, organisations, members, as } = arrangeIdentity();
+
+    await organisations.save(anOrganisation().identifiedBy('acme').build());
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Owner).build());
+
+    await expect(
+      application.commandBus.execute(new RemoveMemberCommand(as('subject-ada'), 'acme', 'subject-nobody')),
+    ).rejects.toMatchObject({ code: 'MEMBER_NOT_FOUND' });
+
+    await expect(
+      application.commandBus.execute(new RemoveMemberCommand(as('subject-ada'), 'acme', 'subject-ada')),
+    ).rejects.toMatchObject({ code: 'LAST_OWNER' });
+  });
+
+  it('is refused to a member who does not manage the members', async () => {
+    const { application, organisations, members, as } = arrangeIdentity();
+
+    await organisations.save(anOrganisation().identifiedBy('acme').build());
+    await members.save(aMember().of('acme', 'subject-alan').build());
+    await members.save(aMember().of('acme', 'subject-grace').build());
+
+    await expect(
+      application.commandBus.execute(new RemoveMemberCommand(as('subject-alan'), 'acme', 'subject-grace')),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+});
+
+describe('Remove member under a delegation', () => {
+  it('removes within the role of the delegate, never above it, and names the delegation used', async () => {
+    const { application, organisations, members, delegations, as } = arrangeIdentity();
+    const now = application.clock.now();
+
+    await organisations.save(anOrganisation().identifiedBy('acme').build());
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Owner).build());
+    await members.save(aMember().of('acme', 'subject-alan').build());
+    await members.save(aMember().of('acme', 'subject-irene').build());
+    await members.save(aMember().of('acme', 'subject-linus').as(MemberRole.Admin).build());
+
+    await delegations.save(
+      aDelegation()
+        .identifiedBy('delegation-1')
+        .from('subject-ada')
+        .to('subject-alan')
+        .lending(MemberRight.ManageMembers)
+        .between(now, new Date(now.getTime() + DAY))
+        .build(),
+    );
+
+    await expect(
+      application.commandBus.execute(new RemoveMemberCommand(as('subject-alan'), 'acme', 'subject-linus')),
+    ).rejects.toMatchObject({ code: 'ABOVE_OWN_ROLE' });
+
+    await application.commandBus.execute(new RemoveMemberCommand(as('subject-alan'), 'acme', 'subject-irene'));
+
+    expect(application.eventBus.published.at(-1)).toMatchObject({
+      type: '{{context.kebab}}.member.removed',
+      payload: { accountId: 'subject-irene', delegationId: 'delegation-1' },
+    });
+  });
+});
+
+describe('Two owners who remove each other at once', () => {
+  it('cannot both commit: the organisation keeps an owner, and the second change is refused as a conflict', async () => {
+    const { application, organisations, members, as } = arrangeIdentity();
+
+    await organisations.save(anOrganisation().identifiedBy('acme').build());
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Owner).build());
+    await members.save(aMember().of('acme', 'subject-grace').as(MemberRole.Owner).build());
+
+    const outcomes = await Promise.allSettled([
+      application.commandBus.execute(new RemoveMemberCommand(as('subject-ada'), 'acme', 'subject-grace')),
+      application.commandBus.execute(new RemoveMemberCommand(as('subject-grace'), 'acme', 'subject-ada')),
+    ]);
+
+    expect(outcomes.map((outcome) => outcome.status).sort()).toEqual(['fulfilled', 'rejected']);
+    expect(await members.countOwners('acme')).toBe(1);
+  });
+});

package/templates/presets/identity/context/test/unit/revoke-delegation.controller.spec.ts.tpl

@@ -0,0 +1,44 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { controllerRoute, executeRoute } from '@ddd-ts-kit/http';
+import { InMemoryCommandBus, type Actor } from '@ddd-ts-kit/kernel';
+import { RevokeDelegationCommand } from '{{alias.context}}/application/commands/revoke-delegation/revoke-delegation.command{{alias.ext}}';
+import { RevokeDelegationController } from '{{alias.context}}/presentation/http/organisations/revoke-delegation/revoke-delegation.controller{{alias.ext}}';
+
+/** Who calls, as the authenticator of the platform makes them from the token. */
+const caller: Actor = {
+  id: 'subject-ada',
+  type: 'user',
+  roles: [],
+  attributes: { email: 'ada@example.test', username: 'ada' },
+};
+
+describe('DELETE /organisations/:organisationId/delegations/:delegationId', () => {
+  it('answers 200 with what the use case answered, and sends it what the request says', async () => {
+    const { route, sent } = arrange();
+
+    const response = await executeRoute(
+      route,
+      { params: { organisationId: 'acme', delegationId: 'delegation-1' }, query: {}, headers: {}, body: {}, raw: undefined },
+      { validateResponses: true, resolvePrincipal: () => caller },
+    );
+
+    expect(route.path).toBe('/organisations/:organisationId/delegations/:delegationId');
+    expect([response.status, response.body]).toEqual([200, { id: 'delegation-1' }]);
+    expect(sent).toMatchObject([{ organisationId: 'acme', delegationId: 'delegation-1' }]);
+  });
+});
+
+/** The route, on a bus that keeps what it was sent and answers as the use case would. */
+function arrange() {
+  const sent: RevokeDelegationCommand[] = [];
+
+  const commands = new InMemoryCommandBus().register(RevokeDelegationCommand, {
+    execute: async (command) => {
+      sent.push(command);
+
+      return 'delegation-1';
+    },
+  });
+
+  return { route: controllerRoute(new RevokeDelegationController(commands)), sent };
+}

package/templates/presets/identity/context/test/unit/revoke-delegation.handler.spec.ts.tpl

@@ -0,0 +1,51 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { MemberRole } from '{{alias.context}}/domain/vocabularies/member-role.vocabulary{{alias.ext}}';
+import { RevokeDelegationCommand } from '{{alias.context}}/application/commands/revoke-delegation/revoke-delegation.command{{alias.ext}}';
+import { aDelegation } from '{{alias.context}}/test/builders/delegation.builder{{alias.ext}}';
+import { aMember } from '{{alias.context}}/test/builders/member.builder{{alias.ext}}';
+import { arrangeIdentity } from '{{alias.context}}/test/unit/identity-application{{alias.ext}}';
+
+describe('Revoke delegation', () => {
+  it('ends a delegation of the organisation while it holds, and tells the other contexts', async () => {
+    const { application, members, delegations, as } = arrangeIdentity();
+    const now = application.clock.now();
+
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Owner).build());
+
+    await delegations.save(
+      aDelegation()
+        .identifiedBy('delegation-1')
+        .between(now, new Date(now.getTime() + 86_400_000))
+        .build(),
+    );
+
+    const before = application.eventBus.published.length;
+
+    await application.commandBus.execute(new RevokeDelegationCommand(as('subject-ada'), 'acme', 'delegation-1'));
+
+    expect((await delegations.findById('delegation-1'))?.isActiveAt(now)).toBe(false);
+    expect(application.eventBus.published.slice(before)).toMatchObject([{ type: '{{context.kebab}}.delegation.revoked' }]);
+  });
+
+  it('finds no delegation of another organisation', async () => {
+    const { application, members, delegations, as } = arrangeIdentity();
+
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Owner).build());
+    await delegations.save(aDelegation().identifiedBy('delegation-1').in('globex').build());
+
+    await expect(
+      application.commandBus.execute(new RevokeDelegationCommand(as('subject-ada'), 'acme', 'delegation-1')),
+    ).rejects.toMatchObject({ code: 'DELEGATION_NOT_FOUND' });
+  });
+
+  it('is refused to a member whose role does not delegate', async () => {
+    const { application, members, delegations, as } = arrangeIdentity();
+
+    await members.save(aMember().of('acme', 'subject-alan').build());
+    await delegations.save(aDelegation().identifiedBy('delegation-1').build());
+
+    await expect(
+      application.commandBus.execute(new RevokeDelegationCommand(as('subject-alan'), 'acme', 'delegation-1')),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+});

package/templates/presets/identity/context/test/unit/revoke-invitation.controller.spec.ts.tpl

@@ -0,0 +1,44 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { controllerRoute, executeRoute } from '@ddd-ts-kit/http';
+import { InMemoryCommandBus, type Actor } from '@ddd-ts-kit/kernel';
+import { RevokeInvitationCommand } from '{{alias.context}}/application/commands/revoke-invitation/revoke-invitation.command{{alias.ext}}';
+import { RevokeInvitationController } from '{{alias.context}}/presentation/http/organisations/revoke-invitation/revoke-invitation.controller{{alias.ext}}';
+
+/** Who calls, as the authenticator of the platform makes them from the token. */
+const caller: Actor = {
+  id: 'subject-ada',
+  type: 'user',
+  roles: [],
+  attributes: { email: 'ada@example.test', username: 'ada' },
+};
+
+describe('DELETE /organisations/:organisationId/invitations/:invitationId', () => {
+  it('answers 200 with what the use case answered, and sends it what the request says', async () => {
+    const { route, sent } = arrange();
+
+    const response = await executeRoute(
+      route,
+      { params: { organisationId: 'acme', invitationId: 'invitation-1' }, query: {}, headers: {}, body: {}, raw: undefined },
+      { validateResponses: true, resolvePrincipal: () => caller },
+    );
+
+    expect(route.path).toBe('/organisations/:organisationId/invitations/:invitationId');
+    expect([response.status, response.body]).toEqual([200, { id: 'invitation-1' }]);
+    expect(sent).toMatchObject([{ organisationId: 'acme', invitationId: 'invitation-1' }]);
+  });
+});
+
+/** The route, on a bus that keeps what it was sent and answers as the use case would. */
+function arrange() {
+  const sent: RevokeInvitationCommand[] = [];
+
+  const commands = new InMemoryCommandBus().register(RevokeInvitationCommand, {
+    execute: async (command) => {
+      sent.push(command);
+
+      return 'invitation-1';
+    },
+  });
+
+  return { route: controllerRoute(new RevokeInvitationController(commands)), sent };
+}

package/templates/presets/identity/context/test/unit/revoke-invitation.handler.spec.ts.tpl

@@ -0,0 +1,44 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { InvitationStatus } from '{{alias.context}}/domain/vocabularies/invitation-status.vocabulary{{alias.ext}}';
+import { MemberRole } from '{{alias.context}}/domain/vocabularies/member-role.vocabulary{{alias.ext}}';
+import { RevokeInvitationCommand } from '{{alias.context}}/application/commands/revoke-invitation/revoke-invitation.command{{alias.ext}}';
+import { anInvitation } from '{{alias.context}}/test/builders/invitation.builder{{alias.ext}}';
+import { aMember } from '{{alias.context}}/test/builders/member.builder{{alias.ext}}';
+import { arrangeIdentity } from '{{alias.context}}/test/unit/identity-application{{alias.ext}}';
+
+describe('Revoke invitation', () => {
+  it('takes back an invitation of the organisation', async () => {
+    const { application, members, invitations, as } = arrangeIdentity();
+
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Admin).build());
+    await invitations.save(anInvitation().identifiedBy('invitation-1').to('acme').build());
+
+    await application.commandBus.execute(new RevokeInvitationCommand(as('subject-ada'), 'acme', 'invitation-1'));
+
+    expect((await invitations.findById('invitation-1'))?.status).toBe(InvitationStatus.Revoked);
+  });
+
+  it('finds no invitation of another organisation, and none that does not exist', async () => {
+    const { application, members, invitations, as } = arrangeIdentity();
+
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Admin).build());
+    await invitations.save(anInvitation().identifiedBy('invitation-1').to('globex').build());
+
+    for (const invitationId of ['invitation-1', 'invitation-9']) {
+      await expect(
+        application.commandBus.execute(new RevokeInvitationCommand(as('subject-ada'), 'acme', invitationId)),
+      ).rejects.toMatchObject({ code: 'INVITATION_NOT_FOUND' });
+    }
+  });
+
+  it('is refused to a member whose role does not invite', async () => {
+    const { application, members, invitations, as } = arrangeIdentity();
+
+    await members.save(aMember().of('acme', 'subject-alan').build());
+    await invitations.save(anInvitation().identifiedBy('invitation-1').to('acme').build());
+
+    await expect(
+      application.commandBus.execute(new RevokeInvitationCommand(as('subject-alan'), 'acme', 'invitation-1')),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+});

package/templates/presets/identity/context/test/unit/role-rights.service.spec.ts.tpl

@@ -0,0 +1,54 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { RoleRightsService } from '{{alias.context}}/domain/services/role-rights.service{{alias.ext}}';
+import { MemberRight } from '{{alias.context}}/domain/vocabularies/member-right.vocabulary{{alias.ext}}';
+import { MemberRole } from '{{alias.context}}/domain/vocabularies/member-role.vocabulary{{alias.ext}}';
+import { aDelegation } from '{{alias.context}}/test/builders/delegation.builder{{alias.ext}}';
+import { aMember } from '{{alias.context}}/test/builders/member.builder{{alias.ext}}';
+
+const now = new Date('2026-01-10T00:00:00.000Z');
+
+describe('RoleRightsService', () => {
+  it('grants every right to an owner, all but delegation to an admin, the reading of members to a member', () => {
+    expect(new RoleRightsService().rightsOf(MemberRole.Owner)).toEqual(Object.values(MemberRight));
+    expect(new RoleRightsService().rightsOf(MemberRole.Admin)).not.toContain(MemberRight.GrantDelegations);
+    expect(new RoleRightsService().rightsOf(MemberRole.Member)).toEqual([MemberRight.ReadMembers]);
+  });
+
+  it('gives an account no right in an organisation it is not, or no longer, a member of', () => {
+    const removed = aMember().of('acme', 'account-ada').as(MemberRole.Owner).removedAt(now).build();
+
+    expect(
+      new RoleRightsService().rightsIn('acme', 'account-ada', { member: undefined, lent: [], now }).rights,
+    ).toEqual([]);
+
+    expect(new RoleRightsService().rightsIn('acme', 'account-ada', { member: removed, lent: [], now }).rights).toEqual(
+      [],
+    );
+  });
+
+  it('adds to the rights of the role those an active delegation lends, and nothing of one that ended', () => {
+    const member = aMember().of('acme', 'account-deputy').build();
+    const active = aDelegation().to('account-deputy').lending(MemberRight.InviteMembers).build();
+
+    const ended = aDelegation()
+      .to('account-deputy')
+      .lending(MemberRight.ManageMembers)
+      .between(new Date('2025-12-01T00:00:00.000Z'), new Date('2026-01-05T00:00:00.000Z'))
+      .build();
+
+    const rights = new RoleRightsService().rightsIn('acme', 'account-deputy', { member, lent: [active, ended], now });
+
+    expect(rights.rights).toEqual([MemberRight.InviteMembers, MemberRight.ReadMembers]);
+  });
+
+  it('names the delegation a right is used under when the role does not grant it, and none otherwise', () => {
+    const deputy = aMember().of('acme', 'account-deputy').build();
+    const admin = aMember().of('acme', 'account-admin').as(MemberRole.Admin).build();
+    const lent = [aDelegation().identifiedBy('delegation-1').lending(MemberRight.InviteMembers).build()];
+    const rights = new RoleRightsService();
+
+    expect(rights.delegationUsedFor(MemberRight.InviteMembers, { member: deputy, lent, now })).toBe('delegation-1');
+    expect(rights.delegationUsedFor(MemberRight.InviteMembers, { member: admin, lent, now })).toBeUndefined();
+    expect(rights.delegationUsedFor(MemberRight.ManageMembers, { member: deputy, lent, now })).toBeUndefined();
+  });
+});

package/templates/presets/identity/context/test/unit/search-members.controller.spec.ts.tpl

@@ -0,0 +1,43 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { controllerRoute, executeRoute } from '@ddd-ts-kit/http';
+import { InMemoryQueryBus, pageOf, type Actor } from '@ddd-ts-kit/kernel';
+import { SearchMembersQuery } from '{{alias.context}}/application/queries/search-members/search-members.query{{alias.ext}}';
+import { MemberRole } from '{{alias.context}}/domain/vocabularies/member-role.vocabulary{{alias.ext}}';
+import { SearchMembersController } from '{{alias.context}}/presentation/http/organisations/search-members/search-members.controller{{alias.ext}}';
+
+const caller: Actor = { id: 'subject-ada', type: 'user', roles: [], attributes: {} };
+
+const ada = {
+  memberId: 'member-1',
+  accountId: 'subject-ada',
+  displayName: 'Ada Lovelace',
+  email: 'ada@example.test',
+  role: MemberRole.Owner,
+  joinedAt: new Date('2026-01-01T00:00:00.000Z'),
+};
+
+describe('GET /organisations/:organisationId/members', () => {
+  it('answers 200 with a page of the members, each instant written as ISO 8601', async () => {
+    const asked: SearchMembersQuery[] = [];
+
+    const queries = new InMemoryQueryBus().register(SearchMembersQuery, {
+      execute: async (query) => {
+        asked.push(query);
+
+        return pageOf([ada], { total: 1 });
+      },
+    });
+
+    const route = controllerRoute(new SearchMembersController(queries));
+
+    const response = await executeRoute(
+      route,
+      { params: { organisationId: 'acme' }, query: { limit: '10' }, headers: {}, body: {}, raw: undefined },
+      { validateResponses: true, resolvePrincipal: () => caller },
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.body).toMatchObject({ items: [{ ...ada, joinedAt: '2026-01-01T00:00:00.000Z' }], total: 1 });
+    expect(asked).toMatchObject([{ organisationId: 'acme', page: { kind: 'offset', limit: 10 } }]);
+  });
+});

package/templates/presets/identity/context/test/unit/search-members.handler.spec.ts.tpl

@@ -0,0 +1,38 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { offsetPage } from '@ddd-ts-kit/kernel';
+import { MemberRole } from '{{alias.context}}/domain/vocabularies/member-role.vocabulary{{alias.ext}}';
+import { SearchMembersQuery } from '{{alias.context}}/application/queries/search-members/search-members.query{{alias.ext}}';
+import { aMember } from '{{alias.context}}/test/builders/member.builder{{alias.ext}}';
+import { arrangeIdentity } from '{{alias.context}}/test/unit/identity-application{{alias.ext}}';
+
+const ada = {
+  memberId: 'member-1',
+  accountId: 'subject-ada',
+  displayName: 'Ada Lovelace',
+  email: 'ada@example.test',
+  role: MemberRole.Owner,
+  joinedAt: new Date('2026-01-01T00:00:00.000Z'),
+};
+
+describe('Search members', () => {
+  it('answers a page of the members of the organisation to one of its members', async () => {
+    const { application, members, reader, as } = arrangeIdentity();
+
+    await members.save(aMember().of('acme', 'subject-ada').as(MemberRole.Owner).build());
+    reader.given('acme', ada);
+
+    const page = await application.queryBus.execute(new SearchMembersQuery(as('subject-ada'), 'acme', offsetPage({ limit: 20 })));
+
+    expect(page.items).toEqual([ada]);
+  });
+
+  it('answers nothing to a person who is not a member of the organisation', async () => {
+    const { application, reader, as } = arrangeIdentity();
+
+    reader.given('acme', ada);
+
+    await expect(
+      application.queryBus.execute(new SearchMembersQuery(as('subject-mallory'), 'acme', offsetPage({ limit: 20 }))),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+});

package/templates/presets/identity/decision.md.tpl

@@ -0,0 +1,37 @@
+# ADR-{{adr.number}}: {{context.kebab}} is the control plane of the tenants
+
+- Status: accepted
+- Date: {{adr.date}}
+
+## Context
+
+The project keeps the data of each organisation apart (`"stack.tenancy"`): every statement of a
+repository is confined to the tenant of the work, and `tenancy/scoped-statement` reports one that
+is not. The organisations of `{{context.kebab}}` are those tenants, and this context decides who
+belongs to which: a person signs in once and lists their organisations, an invitation is answered
+by a person who belongs to none yet, a membership is written for an organisation that is not the
+one the request runs in.
+
+## Decision
+
+The tables of `{{context.kebab}}` (accounts, organisations, members, invitations, delegations)
+belong to no tenant: they hold no tenant column, and each statement of their adapters carries a
+suppression of `tenancy/scoped-statement` that names this record. What one organisation may read
+of another is decided per use case instead: every use case of an organisation authorizes the
+actor on the rights of their membership in it (the policies of
+`application/authorization/`), and every read names that organisation.
+
+## Consequences
+
+- Easier: a person, their memberships and their invitations are one model, whatever the tenant
+  of the request; the provider is told of every change, so that tokens name the organisations.
+- Harder: isolation between the organisations of this context rests on its policies and on the
+  organisation each statement names, not on the storage. A new statement names its organisation.
+- The integration events of an organisation carry it as their tenant, so that the consumers of the
+  other contexts run in it.
+
+## Alternatives considered
+
+- **A tenant column on these tables.** Refused: the membership of a person in an organisation is
+  written by work that does not run in that organisation (opening it, accepting an invitation),
+  and an elevation widens reads only, never writes.

package/templates/presets/identity/design.md.tpl

@@ -0,0 +1,71 @@
+## Design
+
+Written by the identity preset of ddd-ts-kit (`--preset identity`); from now on it is the code of
+this project, to change like any other.
+
+**The identity provider authenticates, this context authorizes.** An account is a person under
+the subject their provider gives them (`actor.id`): it is provisioned at their first sign-in from
+what their token says (`PUT /accounts/me`) and refreshed at each later one. No password, no secret
+of the provider is stored here. The email address of an account is always the one of the token,
+never one a client sends, and one the provider verified (`email_verified`): an invitation is
+matched on it. A deactivated account leaves every organisation and ends every delegation in the
+same unit of work, so that it holds no right anywhere while its last token lives; the last owner
+of an organisation appoints another owner before deactivating.
+
+**Organisations, members and roles.** An organisation is opened under its slug, which is its
+identity for good, and its opener is its first owner. A member holds one role, `owner`, `admin`
+or `member`; what a role grants is one table, `RoleRightsService`. Nobody changes their own role,
+and nobody appoints, invites, changes or removes anyone above their own role (only an owner makes
+an owner), whatever a delegation lends them. An organisation keeps one owner at least: every
+change of a member saves the organisation with it, so that its version orders the changes of its
+owners and two owners who remove each other at once cannot both commit.
+
+**Invitations.** An invitation is issued to an email address, in a role, for a week. Its token
+is answered to the inviter once (`POST /organisations/:organisationId/invitations`) and only its
+SHA-256 digest is stored: send it to the person (a notification context, a link), who accepts or
+declines it signed in, with the address it was sent to.
+
+**Delegations.** A member lends some of the rights of their role to another member of the
+organisation, for ninety days at most: the delegate acts in their own name, with those rights, and
+the audit trail of the project records every use case either way; the facts a change leads to
+name the delegation it was decided under (`delegationId`). A delegation lends nothing beyond the
+role of its delegator, never what was lent to them, never the power to act above the delegate's
+own role, and it ends when one of its two members leaves or when its delegator changes role.
+
+**Who may do what.** Every use case requires a permission of `{{context.camel}}Permissions`, which
+the platform grants to every signed-in person whatever its access model (roles, attribute
+policies, relationships, OpenFGA or an adapter of the project): the grant `'{{context.kebab}}:*'`
+of `signed-in-grants.ts`, which `createAuthorizer` answers before it asks the model
+(`SignedInGrantsAuthorizer` of `@ddd-ts-kit/auth`). Systems, services and anonymous callers get
+nothing from it.
+
+Inside an organisation, the policies of `application/authorization/` decide on the rights the
+actor holds there (`OrganisationRights`): their role, and the rights an active delegation lends
+them. The integration events (`member.joined`, `member.role-changed`, `member.removed`,
+`delegation.granted`, `delegation.revoked`) let another context write the relationships of its
+own model, or the tuples of OpenFGA, from these facts.
+{{#if tenancy.any}}
+
+**Tenants.** Each organisation is a tenant: its slug is the tenant id, the integration events of
+an organisation carry it as their tenant, and the consumers of the other contexts run in it. The
+tables of this context belong to no tenant, since it decides who belongs to which ({{preset.adr}}).
+The token names the organisations of the person: with Keycloak, the `organization` claim, which
+`createAuthenticator` reads (`tenantClaim: 'organization'`). One organisation is the tenant of
+every request; several are the `tenants` of the actor, and a request names the one it works in
+(`x-tenant-id`), refused if the person is not a member of it.
+{{/if}}
+
+**The identity provider follows, at least once.** The consumers of `application/integration/handlers/`
+read the facts the context publishes through its outbox and tell the provider
+(`IdentityProviderAdmin`): it knows the organisation under its slug, adds or removes its members,
+and disables a deactivated account. A provider that is down is asked again by whoever delivers the
+fact (the outbox relay, the broker) until it answers, so a removal or a deactivation is never
+lost; each consumer brings the provider in line with what the context holds now, so that a late
+retry never gives a removed person their organisation back. `KeycloakIdentityProviderAdmin` is a
+recipe for the administration API of Keycloak 26 or later (organizations enabled in the realm), as
+a confidential client holding `manage-users` and `manage-realm` of `realm-management`; it reads
+`KEYCLOAK_URL`, `KEYCLOAK_REALM`, `IDENTITY_PROVIDER_ADMIN_CLIENT_ID` and
+`IDENTITY_PROVIDER_ADMIN_CLIENT_SECRET` when a call is made. Its spec runs it against a local
+server that answers as Keycloak does: run it once against your realm before relying on it. Another
+provider is another adapter of the same port.
+

package/templates/presets/signed-in-grants.ts.tpl

@@ -0,0 +1,12 @@
+import type { Grant } from '@ddd-ts-kit/auth';
+
+/**
+ * What every signed-in person may do, whatever the access model of the platform decides for the
+ * rest: the permissions of a context that serves each person for themselves, such as their
+ * account and the organisations they belong to, whose own policies decide on the element.
+ * `createAuthorizer` grants them before it asks the model.
+ */
+export const signedInGrants: readonly Grant[] = [
+  // ddd-ts-kit:signed-in-grants
+  // /ddd-ts-kit:signed-in-grants
+];