@stjoseph/prumo 0.2.0 → 0.4.0

package/templates/api/src/domain/auth/use-cases/complete-social-sign-in.use-case.ts

@@ -0,0 +1,103 @@
+import { inject, injectable } from 'tsyringe'
+import { SocialSignIn } from '@/domain/auth/entities/social-sign-in.entity'
+import { SocialSignInFailedError } from '@/domain/auth/errors/social-sign-in-failed.error'
+import {
+  IDENTITY_PROVIDERS,
+  type IdentityProviders,
+  type ProviderName,
+} from '@/domain/auth/ports/identity-providers.port'
+import { OPAQUE_TOKENS, type OpaqueTokens } from '@/domain/auth/ports/opaque-tokens.port'
+import {
+  SOCIAL_SIGN_IN_REPOSITORY,
+  type SocialSignInRepository,
+} from '@/domain/auth/repositories/social-sign-in.repository'
+import { LinkIdentityUseCase } from '@/domain/auth/use-cases/link-identity.use-case'
+import {
+  type SessionTokens,
+  StartSessionUseCase,
+} from '@/domain/auth/use-cases/start-session.use-case'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+
+export type SocialCallback = {
+  provider: ProviderName
+  state: string
+  browserToken: string | undefined
+  callbackUrl: URL
+  name: string | null
+}
+
+export type SocialOutcome =
+  | { client: 'web'; returnTo: string; tokens: SessionTokens }
+  | { client: 'mobile'; code: string }
+
+@injectable()
+export class CompleteSocialSignInUseCase {
+  constructor(
+    @inject(IDENTITY_PROVIDERS) private readonly providers: IdentityProviders,
+    @inject(SOCIAL_SIGN_IN_REPOSITORY) private readonly signIns: SocialSignInRepository,
+    @inject(OPAQUE_TOKENS) private readonly opaque: OpaqueTokens,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+    private readonly linkIdentity: LinkIdentityUseCase,
+    private readonly startSession: StartSessionUseCase,
+  ) {}
+
+  async execute(callback: SocialCallback): Promise<SocialOutcome> {
+    const browser =
+      callback.browserToken === undefined ? null : SocialSignIn.parseToken(callback.browserToken)
+
+    // The browser that comes back must be the one that left: a callback forwarded from elsewhere carries no token.
+    if (browser === null || browser.id !== callback.state) {
+      throw new SocialSignInFailedError('The sign-in was started in another browser. Start again.')
+    }
+
+    const started = await this.transactions.run(async () => {
+      const signIn = await this.signIns.lockById(browser.id)
+
+      return signIn !== null &&
+        signIn.provider === callback.provider &&
+        signIn.isStarted(new Date()) &&
+        signIn.browserHash === this.opaque.digest(browser.secret)
+        ? signIn
+        : null
+    })
+
+    if (started === null) {
+      throw new SocialSignInFailedError()
+    }
+
+    const profile = await this.providers.profile(callback.provider, {
+      callbackUrl: callback.callbackUrl,
+      state: started.id,
+      codeVerifier: started.codeVerifier,
+      nonce: started.nonce,
+      name: callback.name,
+    })
+    const userId = await this.linkIdentity.execute(callback.provider, profile)
+    const exchange = started.client === 'mobile' ? this.opaque.create() : null
+
+    await this.transactions.run(async () => {
+      const signIn = await this.signIns.lockById(started.id)
+
+      // Another callback for the same trip got here first.
+      if (signIn === null || !signIn.isStarted(new Date())) {
+        throw new SocialSignInFailedError()
+      }
+
+      signIn.signIn(userId, exchange === null ? null : this.opaque.digest(exchange), new Date())
+      await this.signIns.save(signIn)
+    })
+
+    if (exchange !== null) {
+      return { client: 'mobile', code: started.token(exchange) }
+    }
+
+    return {
+      client: 'web',
+      returnTo: started.returnTo,
+      tokens: await this.startSession.execute(userId),
+    }
+  }
+}

package/templates/api/src/domain/auth/use-cases/exchange-social-code.use-case.ts

@@ -0,0 +1,56 @@
+import { inject, injectable } from 'tsyringe'
+import { SocialSignIn } from '@/domain/auth/entities/social-sign-in.entity'
+import { SocialSignInFailedError } from '@/domain/auth/errors/social-sign-in-failed.error'
+import { OPAQUE_TOKENS, type OpaqueTokens } from '@/domain/auth/ports/opaque-tokens.port'
+import {
+  SOCIAL_SIGN_IN_REPOSITORY,
+  type SocialSignInRepository,
+} from '@/domain/auth/repositories/social-sign-in.repository'
+import {
+  type SessionTokens,
+  StartSessionUseCase,
+} from '@/domain/auth/use-cases/start-session.use-case'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+
+// The mobile app's half: the browser brought back a code, the app trades it once for its own tokens.
+@injectable()
+export class ExchangeSocialCodeUseCase {
+  constructor(
+    @inject(SOCIAL_SIGN_IN_REPOSITORY) private readonly signIns: SocialSignInRepository,
+    @inject(OPAQUE_TOKENS) private readonly opaque: OpaqueTokens,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+    private readonly startSession: StartSessionUseCase,
+  ) {}
+
+  async execute(code: string): Promise<SessionTokens> {
+    const parsed = SocialSignIn.parseToken(code)
+
+    const userId = await this.transactions.run(async () => {
+      const signIn = parsed === null ? null : await this.signIns.lockById(parsed.id)
+
+      if (
+        parsed === null ||
+        signIn === null ||
+        signIn.userId === null ||
+        !signIn.isExchangeable(new Date()) ||
+        signIn.exchangeHash !== this.opaque.digest(parsed.secret)
+      ) {
+        return null
+      }
+
+      signIn.exchange()
+      await this.signIns.save(signIn)
+
+      return signIn.userId
+    })
+
+    if (userId === null) {
+      throw new SocialSignInFailedError()
+    }
+
+    return this.startSession.execute(userId)
+  }
+}

package/templates/api/src/domain/auth/use-cases/find-user.use-case.ts

@@ -0,0 +1,20 @@
+import { inject, injectable } from 'tsyringe'
+import type { User } from '@/domain/auth/entities/user.entity'
+import { InvalidSessionError } from '@/domain/auth/errors/invalid-session.error'
+import { USER_REPOSITORY, type UserRepository } from '@/domain/auth/repositories/user.repository'
+
+@injectable()
+export class FindUserUseCase {
+  constructor(@inject(USER_REPOSITORY) private readonly users: UserRepository) {}
+
+  async execute(userId: string): Promise<User> {
+    const user = await this.users.findById(userId)
+
+    // A valid token for a user who no longer exists is a session that should have ended.
+    if (user === null) {
+      throw new InvalidSessionError()
+    }
+
+    return user
+  }
+}

package/templates/api/src/domain/auth/use-cases/issue-email-code.use-case.ts

@@ -0,0 +1,55 @@
+import { inject, injectable } from 'tsyringe'
+import { EmailCode, type EmailCodePurpose } from '@/domain/auth/entities/email-code.entity'
+import type { User } from '@/domain/auth/entities/user.entity'
+import { MAILER, type Mail, type Mailer } from '@/domain/auth/ports/mailer.port'
+import { ONE_TIME_CODES, type OneTimeCodes } from '@/domain/auth/ports/one-time-codes.port'
+import {
+  EMAIL_CODE_REPOSITORY,
+  type EmailCodeRepository,
+} from '@/domain/auth/repositories/email-code.repository'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+
+const MAILS: Record<EmailCodePurpose, (to: string, code: string) => Mail> = {
+  'verify-email': (to, code) => ({
+    to,
+    subject: `${code} is your verification code`,
+    text: `Enter ${code} to confirm this email address. The code expires in 15 minutes.`,
+  }),
+  'reset-password': (to, code) => ({
+    to,
+    subject: `${code} is your password reset code`,
+    text: `Enter ${code} to choose a new password. The code expires in 15 minutes. If you did not ask for it, ignore this email: your password stays as it is.`,
+  }),
+}
+
+@injectable()
+export class IssueEmailCodeUseCase {
+  constructor(
+    @inject(EMAIL_CODE_REPOSITORY) private readonly codes: EmailCodeRepository,
+    @inject(ONE_TIME_CODES) private readonly oneTimeCodes: OneTimeCodes,
+    @inject(MAILER) private readonly mailer: Mailer,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+  ) {}
+
+  async execute(user: User, purpose: EmailCodePurpose): Promise<void> {
+    const code = this.oneTimeCodes.create()
+    const codeHash = this.oneTimeCodes.digest(code)
+
+    await this.transactions.run(async () => {
+      const now = new Date()
+      const existing = await this.codes.lockFor(user.id, purpose)
+
+      if (existing === null) {
+        await this.codes.save(new EmailCode(user.id, purpose, codeHash, now))
+      } else {
+        existing.renew(codeHash, now)
+        await this.codes.save(existing)
+      }
+    })
+
+    await this.mailer.send(MAILS[purpose](user.email, code))
+  }
+}

package/templates/api/src/domain/auth/use-cases/link-identity.use-case.ts

@@ -0,0 +1,77 @@
+import { inject, injectable } from 'tsyringe'
+import { Identity } from '@/domain/auth/entities/identity.entity'
+import { User } from '@/domain/auth/entities/user.entity'
+import { ProviderEmailUnverifiedError } from '@/domain/auth/errors/provider-email-unverified.error'
+import type { ProviderName, ProviderProfile } from '@/domain/auth/ports/identity-providers.port'
+import {
+  IDENTITY_REPOSITORY,
+  type IdentityRepository,
+} from '@/domain/auth/repositories/identity.repository'
+import {
+  SESSION_REPOSITORY,
+  type SessionRepository,
+} from '@/domain/auth/repositories/session.repository'
+import { USER_REPOSITORY, type UserRepository } from '@/domain/auth/repositories/user.repository'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+import { CreateProfileUseCase } from '@/domain/users/use-cases/create-profile.use-case'
+
+const DISPLAY_NAME_MAX = 80
+
+@injectable()
+export class LinkIdentityUseCase {
+  constructor(
+    @inject(USER_REPOSITORY) private readonly users: UserRepository,
+    @inject(IDENTITY_REPOSITORY) private readonly identities: IdentityRepository,
+    @inject(SESSION_REPOSITORY) private readonly sessions: SessionRepository,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+    private readonly createProfile: CreateProfileUseCase,
+  ) {}
+
+  // Returns the id of the user the provider's account belongs to, creating or linking it as the rules say.
+  execute(provider: ProviderName, profile: ProviderProfile): Promise<string> {
+    return this.transactions.run(async () => {
+      const known = await this.identities.findBySubject(provider, profile.subject)
+
+      if (known !== null) {
+        return known.userId
+      }
+
+      if (!profile.emailVerified) {
+        throw new ProviderEmailUnverifiedError()
+      }
+
+      const now = new Date()
+      const existing = await this.users.findByEmail(User.normalizeEmail(profile.email))
+
+      if (existing !== null) {
+        // Nobody had shown this inbox was theirs, and the provider just did: whoever chose the password, possibly
+        // to wait for the real owner, loses it and every session it opened.
+        if (existing.emailVerifiedAt === null) {
+          existing.removePassword()
+          existing.verifyEmail(now)
+          await this.users.save(existing)
+          await this.sessions.revokeAllFor(existing.id, now)
+        }
+
+        await this.identities.save(new Identity(existing.id, provider, profile.subject))
+
+        return existing.id
+      }
+
+      const user = new User(profile.email, null)
+
+      user.verifyEmail(now)
+      await this.users.save(user)
+      await this.createProfile.execute(
+        user.id,
+        (profile.name ?? profile.email.split('@')[0] ?? profile.email).slice(0, DISPLAY_NAME_MAX),
+      )
+      await this.identities.save(new Identity(user.id, provider, profile.subject))
+
+      return user.id
+    })
+  }
+}

package/templates/api/src/domain/auth/use-cases/refresh-session.use-case.ts

@@ -0,0 +1,94 @@
+import { inject, injectable } from 'tsyringe'
+import { Session } from '@/domain/auth/entities/session.entity'
+import { InvalidSessionError } from '@/domain/auth/errors/invalid-session.error'
+import { SupersededTokenError } from '@/domain/auth/errors/superseded-token.error'
+import {
+  ACCESS_TOKEN_LIFETIME_MS,
+  ACCESS_TOKENS,
+  type AccessTokens,
+} from '@/domain/auth/ports/access-tokens.port'
+import { OPAQUE_TOKENS, type OpaqueTokens } from '@/domain/auth/ports/opaque-tokens.port'
+import {
+  SESSION_REPOSITORY,
+  type SessionRepository,
+} from '@/domain/auth/repositories/session.repository'
+import type { SessionTokens } from '@/domain/auth/use-cases/start-session.use-case'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+
+@injectable()
+export class RefreshSessionUseCase {
+  constructor(
+    @inject(SESSION_REPOSITORY) private readonly sessions: SessionRepository,
+    @inject(ACCESS_TOKENS) private readonly tokens: AccessTokens,
+    @inject(OPAQUE_TOKENS) private readonly opaque: OpaqueTokens,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+  ) {}
+
+  // A first-party refresh passes no client; an OAuth client passes its own id, and neither can use the other's token.
+  async execute(refreshToken: string, clientId: string | null = null): Promise<SessionTokens> {
+    const parsed = Session.parseRefreshToken(refreshToken)
+
+    if (parsed === null) {
+      throw new InvalidSessionError()
+    }
+
+    const { sessionId, secret } = parsed
+    const now = new Date()
+    const rotated = await this.transactions.run(async () => {
+      const session = await this.sessions.lockById(sessionId)
+
+      if (session === null || session.clientId !== clientId) {
+        return 'missing' as const
+      }
+
+      const outcome = session.check(this.opaque.digest(secret), now)
+
+      if (outcome === 'reused') {
+        // An old token came back: whoever holds it is not the client that rotated it. End the session for both.
+        session.revoke(now)
+        await this.sessions.save(session)
+      }
+
+      if (outcome !== 'valid') {
+        return outcome
+      }
+
+      const next = this.opaque.create()
+
+      session.rotate(this.opaque.digest(next), now)
+      await this.sessions.save(session)
+
+      return { session, next }
+    })
+
+    if (rotated === 'superseded') {
+      throw new SupersededTokenError()
+    }
+
+    if (typeof rotated === 'string') {
+      throw new InvalidSessionError()
+    }
+
+    const { session, next } = rotated
+
+    return {
+      sessionId: session.id,
+      accessToken: await this.tokens.issue(
+        {
+          userId: session.userId,
+          sessionId: session.id,
+          ...(session.clientId !== null && { clientId: session.clientId }),
+          ...(session.scope !== null && { scope: session.scope }),
+        },
+        new Date(now.getTime() + ACCESS_TOKEN_LIFETIME_MS),
+        session.resource ?? undefined,
+      ),
+      refreshToken: session.refreshToken(next),
+      refreshExpiresAt: session.expiresAt,
+      scope: session.scope,
+    }
+  }
+}

package/templates/api/src/domain/auth/use-cases/request-email-verification.use-case.ts

@@ -0,0 +1,21 @@
+import { inject, injectable } from 'tsyringe'
+import { User } from '@/domain/auth/entities/user.entity'
+import { USER_REPOSITORY, type UserRepository } from '@/domain/auth/repositories/user.repository'
+import { IssueEmailCodeUseCase } from '@/domain/auth/use-cases/issue-email-code.use-case'
+
+@injectable()
+export class RequestEmailVerificationUseCase {
+  constructor(
+    @inject(USER_REPOSITORY) private readonly users: UserRepository,
+    private readonly issueEmailCode: IssueEmailCodeUseCase,
+  ) {}
+
+  // Answers the same whether the account exists, is verified, or neither: the caller learns nothing about who signed up.
+  async execute(email: string): Promise<void> {
+    const user = await this.users.findByEmail(User.normalizeEmail(email))
+
+    if (user !== null && user.emailVerifiedAt === null) {
+      await this.issueEmailCode.execute(user, 'verify-email')
+    }
+  }
+}

package/templates/api/src/domain/auth/use-cases/request-password-reset.use-case.ts

@@ -0,0 +1,21 @@
+import { inject, injectable } from 'tsyringe'
+import { User } from '@/domain/auth/entities/user.entity'
+import { USER_REPOSITORY, type UserRepository } from '@/domain/auth/repositories/user.repository'
+import { IssueEmailCodeUseCase } from '@/domain/auth/use-cases/issue-email-code.use-case'
+
+@injectable()
+export class RequestPasswordResetUseCase {
+  constructor(
+    @inject(USER_REPOSITORY) private readonly users: UserRepository,
+    private readonly issueEmailCode: IssueEmailCodeUseCase,
+  ) {}
+
+  // Answers the same for an unknown email: the caller learns nothing about who has an account.
+  async execute(email: string): Promise<void> {
+    const user = await this.users.findByEmail(User.normalizeEmail(email))
+
+    if (user !== null) {
+      await this.issueEmailCode.execute(user, 'reset-password')
+    }
+  }
+}

package/templates/api/src/domain/auth/use-cases/reset-password.use-case.ts

@@ -0,0 +1,73 @@
+import { inject, injectable } from 'tsyringe'
+import type { ResetPasswordDto } from '@/domain/auth/dto/reset-password.dto'
+import { User } from '@/domain/auth/entities/user.entity'
+import { InvalidCodeError } from '@/domain/auth/errors/invalid-code.error'
+import { ONE_TIME_CODES, type OneTimeCodes } from '@/domain/auth/ports/one-time-codes.port'
+import { PASSWORD_HASHER, type PasswordHasher } from '@/domain/auth/ports/password-hasher.port'
+import {
+  EMAIL_CODE_REPOSITORY,
+  type EmailCodeRepository,
+} from '@/domain/auth/repositories/email-code.repository'
+import {
+  SESSION_REPOSITORY,
+  type SessionRepository,
+} from '@/domain/auth/repositories/session.repository'
+import { USER_REPOSITORY, type UserRepository } from '@/domain/auth/repositories/user.repository'
+import {
+  type SessionTokens,
+  StartSessionUseCase,
+} from '@/domain/auth/use-cases/start-session.use-case'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+
+@injectable()
+export class ResetPasswordUseCase {
+  constructor(
+    @inject(USER_REPOSITORY) private readonly users: UserRepository,
+    @inject(EMAIL_CODE_REPOSITORY) private readonly codes: EmailCodeRepository,
+    @inject(SESSION_REPOSITORY) private readonly sessions: SessionRepository,
+    @inject(ONE_TIME_CODES) private readonly oneTimeCodes: OneTimeCodes,
+    @inject(PASSWORD_HASHER) private readonly hasher: PasswordHasher,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+    private readonly startSession: StartSessionUseCase,
+  ) {}
+
+  async execute({ email, code, password }: ResetPasswordDto): Promise<SessionTokens> {
+    const passwordHash = await this.hasher.hash(password)
+
+    const reset = await this.transactions.run(async () => {
+      const now = new Date()
+      const user = await this.users.findByEmail(User.normalizeEmail(email))
+      const stored = user === null ? null : await this.codes.lockFor(user.id, 'reset-password')
+
+      if (user === null || stored === null) {
+        return null
+      }
+
+      const outcome = stored.check(this.oneTimeCodes.digest(code), now)
+
+      await this.codes.save(stored)
+
+      if (outcome !== 'valid') {
+        return null
+      }
+
+      // The code arrived in the inbox, which is the proof verification asks for.
+      user.changePassword(passwordHash)
+      user.verifyEmail(now)
+      await this.users.save(user)
+      // Whoever knew the old password may still hold a session it opened.
+      await this.sessions.revokeAllFor(user.id, now)
+
+      return user
+    })
+
+    if (reset === null) {
+      throw new InvalidCodeError()
+    }
+
+    return this.startSession.execute(reset.id)
+  }
+}

package/templates/api/src/domain/auth/use-cases/sign-in.use-case.ts

@@ -0,0 +1,38 @@
+import { inject, injectable } from 'tsyringe'
+import type { SignInDto } from '@/domain/auth/dto/sign-in.dto'
+import { User } from '@/domain/auth/entities/user.entity'
+import { EmailNotVerifiedError } from '@/domain/auth/errors/email-not-verified.error' // prumo:email
+import { InvalidCredentialsError } from '@/domain/auth/errors/invalid-credentials.error'
+import { PASSWORD_HASHER, type PasswordHasher } from '@/domain/auth/ports/password-hasher.port'
+import { USER_REPOSITORY, type UserRepository } from '@/domain/auth/repositories/user.repository'
+import {
+  type SessionTokens,
+  StartSessionUseCase,
+} from '@/domain/auth/use-cases/start-session.use-case'
+
+@injectable()
+export class SignInUseCase {
+  constructor(
+    @inject(USER_REPOSITORY) private readonly users: UserRepository,
+    @inject(PASSWORD_HASHER) private readonly hasher: PasswordHasher,
+    private readonly startSession: StartSessionUseCase,
+  ) {}
+
+  async execute({ email, password }: SignInDto): Promise<SessionTokens> {
+    const user = await this.users.findByEmail(User.normalizeEmail(email))
+    const valid = await this.hasher.verify(user?.passwordHash ?? undefined, password)
+
+    if (user === null || !valid) {
+      throw new InvalidCredentialsError()
+    }
+
+    // prumo:email
+    // Asked only after the password matched, so the answer says nothing to someone who does not know it.
+    if (user.emailVerifiedAt === null) {
+      throw new EmailNotVerifiedError()
+    }
+
+    // prumo:end-email
+    return this.startSession.execute(user.id)
+  }
+}

package/templates/api/src/domain/auth/use-cases/sign-out.use-case.ts

@@ -0,0 +1,22 @@
+import { inject, injectable } from 'tsyringe'
+import {
+  SESSION_REPOSITORY,
+  type SessionRepository,
+} from '@/domain/auth/repositories/session.repository'
+
+@injectable()
+export class SignOutUseCase {
+  constructor(@inject(SESSION_REPOSITORY) private readonly sessions: SessionRepository) {}
+
+  // Signing out twice, or out of a session already gone, is not an error: the outcome is the same.
+  async execute(userId: string, sessionId: string): Promise<void> {
+    const session = await this.sessions.findById(sessionId)
+
+    if (session === null || session.userId !== userId) {
+      return
+    }
+
+    session.revoke(new Date())
+    await this.sessions.save(session)
+  }
+}

package/templates/api/src/domain/auth/use-cases/sign-up.use-case.ts

@@ -0,0 +1,57 @@
+import { inject, injectable } from 'tsyringe'
+import type { SignUpDto } from '@/domain/auth/dto/sign-up.dto'
+import { User } from '@/domain/auth/entities/user.entity'
+import { EmailTakenError } from '@/domain/auth/errors/email-taken.error'
+import { PASSWORD_HASHER, type PasswordHasher } from '@/domain/auth/ports/password-hasher.port'
+import { USER_REPOSITORY, type UserRepository } from '@/domain/auth/repositories/user.repository'
+import { IssueEmailCodeUseCase } from '@/domain/auth/use-cases/issue-email-code.use-case' // prumo:email
+import {
+  type SessionTokens,
+  StartSessionUseCase,
+} from '@/domain/auth/use-cases/start-session.use-case'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+import { CreateProfileUseCase } from '@/domain/users/use-cases/create-profile.use-case'
+
+@injectable()
+export class SignUpUseCase {
+  constructor(
+    @inject(USER_REPOSITORY) private readonly users: UserRepository,
+    @inject(PASSWORD_HASHER) private readonly hasher: PasswordHasher,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+    private readonly createProfile: CreateProfileUseCase,
+    private readonly startSession: StartSessionUseCase,
+    private readonly issueEmailCode: IssueEmailCodeUseCase, // prumo:email
+  ) {}
+
+  // Null when the account must confirm its email before it may sign in.
+  async execute({ name, email, password }: SignUpDto): Promise<SessionTokens | null> {
+    const passwordHash = await this.hasher.hash(password)
+
+    // The account and its profile exist together or not at all.
+    const user = await this.transactions.run(async () => {
+      if ((await this.users.findByEmail(User.normalizeEmail(email))) !== null) {
+        throw new EmailTakenError()
+      }
+
+      const user = new User(email, passwordHash)
+
+      await this.users.save(user)
+      await this.createProfile.execute(user.id, name)
+
+      return user
+    })
+
+    // prumo:email
+    // Until the address is confirmed the account cannot sign in, so it opens no session either.
+    if (user.emailVerifiedAt === null) {
+      await this.issueEmailCode.execute(user, 'verify-email')
+      return null
+    }
+
+    // prumo:end-email
+    return this.startSession.execute(user.id)
+  }
+}