@stjoseph/prumo 0.3.0 → 0.4.0

package/templates/api/src/domain/auth/entities/social-sign-in.entity.ts

@@ -0,0 +1,82 @@
+import type { ProviderName } from '@/domain/auth/ports/identity-providers.port'
+
+// Long enough to sign in at the provider; the code a mobile app exchanges afterwards is spent within two minutes.
+export const SOCIAL_SIGN_IN_LIFETIME_MS = 10 * 60 * 1000
+export const SOCIAL_EXCHANGE_LIFETIME_MS = 2 * 60 * 1000
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export type SocialClient = 'web' | 'mobile'
+
+export type SocialSignInStatus = 'started' | 'signed-in' | 'exchanged'
+
+// One trip to a provider and back. Its id travels as OAuth's state; the browser that started it holds a secret the
+// callback must present, so a callback carrying someone else's code cannot sign this browser into their account.
+export class SocialSignIn {
+  id: string
+  provider: ProviderName
+  client: SocialClient
+  returnTo: string
+  browserHash: string
+  codeVerifier: string | null = null
+  nonce = ''
+  status: SocialSignInStatus = 'started'
+  userId: string | null = null
+  exchangeHash: string | null = null
+  expiresAt: Date
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(
+    provider: ProviderName,
+    client: SocialClient,
+    returnTo: string,
+    browserHash: string,
+    now: Date,
+  ) {
+    this.provider = provider
+    this.client = client
+    this.returnTo = returnTo
+    this.browserHash = browserHash
+    this.expiresAt = new Date(now.getTime() + SOCIAL_SIGN_IN_LIFETIME_MS)
+  }
+
+  // `<id>.<secret>`, as refresh tokens and authorization codes are written.
+  static parseToken(token: string): { id: string; secret: string } | null {
+    const dot = token.indexOf('.')
+    const id = token.slice(0, dot)
+    const secret = token.slice(dot + 1)
+
+    return dot === -1 || !UUID.test(id) || secret === '' ? null : { id, secret }
+  }
+
+  token(secret: string): string {
+    return `${this.id}.${secret}`
+  }
+
+  // What the provider's redirect requires back: the PKCE verifier, when the provider takes PKCE, and the nonce.
+  prepare(codeVerifier: string | null, nonce: string): void {
+    this.codeVerifier = codeVerifier
+    this.nonce = nonce
+  }
+
+  isStarted(now: Date): boolean {
+    return this.status === 'started' && this.expiresAt > now
+  }
+
+  // The web is signed in at once; a mobile app gets a code to exchange, so its tokens never travel in a URL.
+  signIn(userId: string, exchangeHash: string | null, now: Date): void {
+    this.status = 'signed-in'
+    this.userId = userId
+    this.exchangeHash = exchangeHash
+    this.expiresAt = new Date(now.getTime() + SOCIAL_EXCHANGE_LIFETIME_MS)
+  }
+
+  isExchangeable(now: Date): boolean {
+    return this.status === 'signed-in' && this.exchangeHash !== null && this.expiresAt > now
+  }
+
+  exchange(): void {
+    this.status = 'exchanged'
+  }
+}

package/templates/api/src/domain/auth/entities/user.entity.ts

@@ -1,11 +1,13 @@
 export class User {
   id: string
   email: string
-  passwordHash: string
+  // Null for an account that only ever signed in through a provider, or whose password a provider's proof voided.
+  passwordHash: string | null
+  emailVerifiedAt: Date | null = null
   createdAt: Date
   updatedAt: Date
 
-  constructor(email: string, passwordHash: string) {
+  constructor(email: string, passwordHash: string | null) {
     this.email = User.normalizeEmail(email)
     this.passwordHash = passwordHash
   }
@@ -14,4 +16,19 @@ export class User {
   static normalizeEmail(email: string): string {
     return email.trim().toLowerCase()
   }
+
+  verifyEmail(now: Date): void {
+    this.emailVerifiedAt ??= now
+  }
+
+  changePassword(passwordHash: string): void {
+    this.passwordHash = passwordHash
+  }
+
+  // prumo:social
+  // A provider proved the address belongs to someone else than whoever chose this password.
+  removePassword(): void {
+    this.passwordHash = null
+  }
+  // prumo:end-social
 }

package/templates/api/src/domain/auth/errors/email-not-verified.error.ts

@@ -0,0 +1,10 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+export class EmailNotVerifiedError extends DomainError {
+  readonly kind = 'forbidden'
+  override readonly code = 'email_not_verified'
+
+  constructor() {
+    super('Confirm your email before signing in')
+  }
+}

package/templates/api/src/domain/auth/errors/invalid-code.error.ts

@@ -0,0 +1,11 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// One answer for a wrong code, a dead one and an unknown email, so the form does not say which accounts exist.
+export class InvalidCodeError extends DomainError {
+  readonly kind = 'invalid'
+  override readonly code = 'invalid_code'
+
+  constructor() {
+    super('The code is wrong or has expired')
+  }
+}

package/templates/api/src/domain/auth/errors/provider-email-unverified.error.ts

@@ -0,0 +1,11 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// Without the provider's word that the address is theirs, an email cannot be trusted to name an account.
+export class ProviderEmailUnverifiedError extends DomainError {
+  readonly kind = 'forbidden'
+  override readonly code = 'provider_email_unverified'
+
+  constructor() {
+    super('The provider has not verified this email address')
+  }
+}

package/templates/api/src/domain/auth/errors/provider-not-configured.error.ts

@@ -0,0 +1,10 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+export class ProviderNotConfiguredError extends DomainError {
+  readonly kind = 'invalid'
+  override readonly code = 'provider_not_configured'
+
+  constructor(provider: string) {
+    super(`Sign-in with ${provider} is not configured: set its variables in .env`)
+  }
+}

package/templates/api/src/domain/auth/errors/social-sign-in-failed.error.ts

@@ -0,0 +1,11 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// Expired, already used, started in another browser, or refused by the provider: the user starts again.
+export class SocialSignInFailedError extends DomainError {
+  readonly kind = 'unauthorized'
+  override readonly code = 'social_sign_in_failed'
+
+  constructor(message = 'The sign-in did not complete. Start again.') {
+    super(message)
+  }
+}

package/templates/api/src/domain/auth/ports/access-tokens.port.ts

@@ -1,4 +1,4 @@
-export type AccessClaims = { userId: string; sessionId: string; clientId?: string }
+export type AccessClaims = { userId: string; sessionId: string; clientId?: string; scope?: string }
 
 export type IssuedToken = { token: string; expiresAt: Date }
 

package/templates/api/src/domain/auth/ports/identity-providers.port.ts

@@ -0,0 +1,29 @@
+export type ProviderName = 'google' | 'apple'
+
+export type ProviderProfile = {
+  subject: string
+  email: string
+  emailVerified: boolean
+  name: string | null
+}
+
+export type ProviderRedirect = { url: string; codeVerifier: string | null; nonce: string }
+
+export type ProviderCallback = {
+  callbackUrl: URL
+  state: string
+  codeVerifier: string | null
+  nonce: string
+  // Apple sends the user's name once, beside the code, and never inside the ID token.
+  name: string | null
+}
+
+// Google and Apple speak OpenID Connect: the adapter builds the provider's URL and, on the way back, validates the
+// ID token (signature, issuer, audience, nonce) before anything here reads it.
+export interface IdentityProviders {
+  isConfigured(provider: ProviderName): boolean
+  redirect(provider: ProviderName, state: string): Promise<ProviderRedirect>
+  profile(provider: ProviderName, callback: ProviderCallback): Promise<ProviderProfile>
+}
+
+export const IDENTITY_PROVIDERS = Symbol('IdentityProviders')

package/templates/api/src/domain/auth/ports/mailer.port.ts

@@ -0,0 +1,8 @@
+export type Mail = { to: string; subject: string; text: string }
+
+// The template writes mail to the log; a project that sends real mail replaces the adapter, not the callers.
+export interface Mailer {
+  send(mail: Mail): Promise<void>
+}
+
+export const MAILER = Symbol('Mailer')

package/templates/api/src/domain/auth/ports/one-time-codes.port.ts

@@ -0,0 +1,7 @@
+// Six digits a person can type. The digest is keyed, so a copy of the table alone cannot try the million codes.
+export interface OneTimeCodes {
+  create(): string
+  digest(code: string): string
+}
+
+export const ONE_TIME_CODES = Symbol('OneTimeCodes')

package/templates/api/src/domain/auth/repositories/email-code.repository.ts

@@ -0,0 +1,9 @@
+import type { EmailCode, EmailCodePurpose } from '@/domain/auth/entities/email-code.entity'
+
+export interface EmailCodeRepository {
+  // Reads the row and holds it until the surrounding transaction ends, so two guesses cannot both spend one attempt.
+  lockFor(userId: string, purpose: EmailCodePurpose): Promise<EmailCode | null>
+  save(code: EmailCode): Promise<void>
+}
+
+export const EMAIL_CODE_REPOSITORY = Symbol('EmailCodeRepository')

package/templates/api/src/domain/auth/repositories/identity.repository.ts

@@ -0,0 +1,9 @@
+import type { Identity } from '@/domain/auth/entities/identity.entity'
+import type { ProviderName } from '@/domain/auth/ports/identity-providers.port'
+
+export interface IdentityRepository {
+  findBySubject(provider: ProviderName, subject: string): Promise<Identity | null>
+  save(identity: Identity): Promise<void>
+}
+
+export const IDENTITY_REPOSITORY = Symbol('IdentityRepository')

package/templates/api/src/domain/auth/repositories/session.repository.ts

@@ -5,6 +5,8 @@ export interface SessionRepository {
   // Reads the row and holds it until the surrounding transaction ends, so two rotations cannot interleave.
   lockById(id: string): Promise<Session | null>
   save(session: Session): Promise<void>
+  // Every session of the user, at once: a new password ends whatever the old one opened.
+  revokeAllFor(userId: string, now: Date): Promise<void>
 }
 
 export const SESSION_REPOSITORY = Symbol('SessionRepository')

package/templates/api/src/domain/auth/repositories/social-sign-in.repository.ts

@@ -0,0 +1,9 @@
+import type { SocialSignIn } from '@/domain/auth/entities/social-sign-in.entity'
+
+export interface SocialSignInRepository {
+  // Reads the row and holds it until the surrounding transaction ends, so a callback or a code is used once.
+  lockById(id: string): Promise<SocialSignIn | null>
+  save(signIn: SocialSignIn): Promise<void>
+}
+
+export const SOCIAL_SIGN_IN_REPOSITORY = Symbol('SocialSignInRepository')

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/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

@@ -81,12 +81,14 @@ export class RefreshSessionUseCase {
           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')
+    }
+  }
+}