@stjoseph/prumo 0.2.0 → 0.4.0

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

@@ -0,0 +1,55 @@
+import { inject, injectable } from 'tsyringe'
+import { type Grant, Session } from '@/domain/auth/entities/session.entity'
+import {
+  ACCESS_TOKEN_LIFETIME_MS,
+  ACCESS_TOKENS,
+  type AccessTokens,
+  type IssuedToken,
+} 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'
+
+export type SessionTokens = {
+  sessionId: string
+  accessToken: IssuedToken
+  refreshToken: string
+  refreshExpiresAt: Date
+  // What an OAuth client's tokens may do; null for the application's own sessions, which may do everything.
+  scope: string | null
+}
+
+@injectable()
+export class StartSessionUseCase {
+  constructor(
+    @inject(SESSION_REPOSITORY) private readonly sessions: SessionRepository,
+    @inject(ACCESS_TOKENS) private readonly tokens: AccessTokens,
+    @inject(OPAQUE_TOKENS) private readonly opaque: OpaqueTokens,
+  ) {}
+
+  async execute(userId: string, grant?: Grant): Promise<SessionTokens> {
+    const now = new Date()
+    const secret = this.opaque.create()
+    const session = new Session(userId, this.opaque.digest(secret), now, grant)
+
+    await this.sessions.save(session)
+
+    return {
+      sessionId: session.id,
+      accessToken: await this.tokens.issue(
+        {
+          userId,
+          sessionId: session.id,
+          ...(grant && { clientId: grant.clientId, scope: grant.scope }),
+        },
+        new Date(now.getTime() + ACCESS_TOKEN_LIFETIME_MS),
+        grant?.resource,
+      ),
+      refreshToken: session.refreshToken(secret),
+      refreshExpiresAt: session.expiresAt,
+      scope: session.scope,
+    }
+  }
+}

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

@@ -0,0 +1,54 @@
+import { inject, injectable } from 'tsyringe'
+import { type SocialClient, SocialSignIn } from '@/domain/auth/entities/social-sign-in.entity'
+import { ProviderNotConfiguredError } from '@/domain/auth/errors/provider-not-configured.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'
+
+export type SocialStart = { provider: ProviderName; client: SocialClient; returnTo: string }
+
+@injectable()
+export class StartSocialSignInUseCase {
+  constructor(
+    @inject(IDENTITY_PROVIDERS) private readonly providers: IdentityProviders,
+    @inject(SOCIAL_SIGN_IN_REPOSITORY) private readonly signIns: SocialSignInRepository,
+    @inject(OPAQUE_TOKENS) private readonly opaque: OpaqueTokens,
+  ) {}
+
+  // Returns where to send the browser, and the token the browser keeps to prove, on the way back, that it started.
+  async execute({
+    provider,
+    client,
+    returnTo,
+  }: SocialStart): Promise<{ url: string; browserToken: string }> {
+    if (!this.providers.isConfigured(provider)) {
+      throw new ProviderNotConfiguredError(provider)
+    }
+
+    const secret = this.opaque.create()
+    const signIn = new SocialSignIn(
+      provider,
+      client,
+      returnTo,
+      this.opaque.digest(secret),
+      new Date(),
+    )
+
+    // Saved first: its id is the state the provider sends back.
+    await this.signIns.save(signIn)
+
+    const redirect = await this.providers.redirect(provider, signIn.id)
+
+    signIn.prepare(redirect.codeVerifier, redirect.nonce)
+    await this.signIns.save(signIn)
+
+    return { url: redirect.url, browserToken: signIn.token(secret) }
+  }
+}

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

@@ -0,0 +1,62 @@
+import { inject, injectable } from 'tsyringe'
+import type { VerifyEmailDto } from '@/domain/auth/dto/verify-email.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 {
+  EMAIL_CODE_REPOSITORY,
+  type EmailCodeRepository,
+} from '@/domain/auth/repositories/email-code.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 VerifyEmailUseCase {
+  constructor(
+    @inject(USER_REPOSITORY) private readonly users: UserRepository,
+    @inject(EMAIL_CODE_REPOSITORY) private readonly codes: EmailCodeRepository,
+    @inject(ONE_TIME_CODES) private readonly oneTimeCodes: OneTimeCodes,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+    private readonly startSession: StartSessionUseCase,
+  ) {}
+
+  // A confirmed address signs the user in: they proved the inbox and already chose a password.
+  async execute({ email, code }: VerifyEmailDto): Promise<SessionTokens> {
+    // The spent attempt is committed before the error is thrown, or a wrong guess would cost nothing.
+    const verified = 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, 'verify-email')
+
+      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
+      }
+
+      user.verifyEmail(now)
+      await this.users.save(user)
+
+      return user
+    })
+
+    if (verified === null) {
+      throw new InvalidCodeError()
+    }
+
+    return this.startSession.execute(verified.id)
+  }
+}

package/templates/api/src/domain/oauth/dto/authorization-decision.dto.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+export const authorizationDecisionSchema = z.strictObject({ accept: z.boolean() })
+
+export type AuthorizationDecisionDto = z.infer<typeof authorizationDecisionSchema>
+
+export const authorizationRedirectSchema = z.object({ redirectTo: z.string() })

package/templates/api/src/domain/oauth/dto/authorization-view.dto.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+// What the consent page shows. The hosts come first: a name is whatever the client chose to write.
+export const authorizationViewSchema = z.object({
+  clientId: z.string(),
+  clientName: z.string(),
+  clientHost: z.string(),
+  redirectHost: z.string(),
+  // A localhost redirect cannot prove which program is listening there, so the page warns about it.
+  redirectsToThisDevice: z.boolean(),
+  scopes: z.array(z.object({ scope: z.string(), description: z.string() })),
+})
+
+export type AuthorizationViewDto = z.infer<typeof authorizationViewSchema>

package/templates/api/src/domain/oauth/entities/authorization.entity.ts

@@ -0,0 +1,87 @@
+// Long enough to sign in and read the consent page; the code that follows is spent within a minute.
+export const AUTHORIZATION_REQUEST_LIFETIME_MS = 10 * 60 * 1000
+export const AUTHORIZATION_CODE_LIFETIME_MS = 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 AuthorizationStatus = 'pending' | 'approved' | 'denied' | 'exchanged'
+
+export type AuthorizationRequest = {
+  clientId: string
+  clientName: string
+  redirectUri: string
+  codeChallenge: string
+  clientState: string | null
+  resource: string
+  // The scopes the client asked for and the user is shown, space-separated.
+  scope: string
+}
+
+// One OAuth authorization, from the client's request through the user's answer to the code it is exchanged for.
+export class Authorization {
+  id: string
+  clientId: string
+  clientName: string
+  redirectUri: string
+  codeChallenge: string
+  clientState: string | null
+  resource: string
+  scope: string
+  status: AuthorizationStatus = 'pending'
+  userId: string | null = null
+  codeHash: string | null = null
+  sessionId: string | null = null
+  expiresAt: Date
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(request: AuthorizationRequest, now: Date) {
+    this.clientId = request.clientId
+    this.clientName = request.clientName
+    this.redirectUri = request.redirectUri
+    this.codeChallenge = request.codeChallenge
+    this.clientState = request.clientState
+    this.resource = request.resource
+    this.scope = request.scope
+    this.expiresAt = new Date(now.getTime() + AUTHORIZATION_REQUEST_LIFETIME_MS)
+  }
+
+  // The code names its authorization, as a refresh token names its session.
+  static parseCode(code: string): { authorizationId: string; secret: string } | null {
+    const dot = code.indexOf('.')
+    const authorizationId = code.slice(0, dot)
+    const secret = code.slice(dot + 1)
+
+    return dot === -1 || !UUID.test(authorizationId) || secret === ''
+      ? null
+      : { authorizationId, secret }
+  }
+
+  code(secret: string): string {
+    return `${this.id}.${secret}`
+  }
+
+  isPending(now: Date): boolean {
+    return this.status === 'pending' && this.expiresAt > now
+  }
+
+  approve(userId: string, codeHash: string, now: Date): void {
+    this.status = 'approved'
+    this.userId = userId
+    this.codeHash = codeHash
+    this.expiresAt = new Date(now.getTime() + AUTHORIZATION_CODE_LIFETIME_MS)
+  }
+
+  deny(): void {
+    this.status = 'denied'
+  }
+
+  isRedeemable(now: Date): boolean {
+    return this.status === 'approved' && this.expiresAt > now
+  }
+
+  exchange(sessionId: string): void {
+    this.status = 'exchanged'
+    this.sessionId = sessionId
+  }
+}

package/templates/api/src/domain/oauth/errors/authorization-not-found.error.ts

@@ -0,0 +1,9 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+export class AuthorizationNotFoundError extends DomainError {
+  readonly kind = 'not_found'
+
+  constructor() {
+    super('This authorization request has expired or was already answered')
+  }
+}

package/templates/api/src/domain/oauth/errors/authorization-request.error.ts

@@ -0,0 +1,18 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// A request from a client already known to be who it says, with a redirect URI it registered: the error goes back
+// to that URI, in OAuth's own terms.
+export class AuthorizationRequestError extends DomainError {
+  readonly kind = 'invalid'
+
+  constructor(
+    readonly code:
+      | 'invalid_request'
+      | 'unsupported_response_type'
+      | 'invalid_target'
+      | 'invalid_scope',
+    message: string,
+  ) {
+    super(message)
+  }
+}

package/templates/api/src/domain/oauth/errors/invalid-client.error.ts

@@ -0,0 +1,6 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// The client or its redirect URI cannot be trusted, so the error is shown here and never sent to that URI.
+export class InvalidClientError extends DomainError {
+  readonly kind = 'invalid'
+}

package/templates/api/src/domain/oauth/errors/invalid-grant.error.ts

@@ -0,0 +1,6 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// OAuth's invalid_grant: the code or refresh token is wrong, spent, expired, or not this client's.
+export class InvalidGrantError extends DomainError {
+  readonly kind = 'invalid'
+}

package/templates/api/src/domain/oauth/ports/authorization-codes.port.ts

@@ -0,0 +1,8 @@
+export interface AuthorizationCodes {
+  create(): string
+  digest(code: string): string
+  // PKCE's S256: whether the verifier the client kept hashes to the challenge it sent first.
+  matchesChallenge(verifier: string, challenge: string): boolean
+}
+
+export const AUTHORIZATION_CODES = Symbol('AuthorizationCodes')

package/templates/api/src/domain/oauth/ports/client-metadata.port.ts

@@ -0,0 +1,9 @@
+export type ClientMetadata = { clientId: string; clientName: string; redirectUris: string[] }
+
+// A client identifies itself by the HTTPS URL of a document describing it. Reading one that is missing, malformed,
+// or not a public client's throws InvalidClientError.
+export interface ClientMetadataSource {
+  read(clientId: string): Promise<ClientMetadata>
+}
+
+export const CLIENT_METADATA = Symbol('ClientMetadataSource')

package/templates/api/src/domain/oauth/repositories/authorization.repository.ts

@@ -0,0 +1,10 @@
+import type { Authorization } from '@/domain/oauth/entities/authorization.entity'
+
+export interface AuthorizationRepository {
+  findById(id: string): Promise<Authorization | null>
+  // Reads the row and holds it until the surrounding transaction ends, so a code is spent once.
+  lockById(id: string): Promise<Authorization | null>
+  save(authorization: Authorization): Promise<void>
+}
+
+export const AUTHORIZATION_REPOSITORY = Symbol('AuthorizationRepository')

package/templates/api/src/domain/oauth/use-cases/decide-authorization.use-case.ts

@@ -0,0 +1,53 @@
+import { inject, injectable } from 'tsyringe'
+import type { Authorization } from '@/domain/oauth/entities/authorization.entity'
+import { AuthorizationNotFoundError } from '@/domain/oauth/errors/authorization-not-found.error'
+import {
+  AUTHORIZATION_CODES,
+  type AuthorizationCodes,
+} from '@/domain/oauth/ports/authorization-codes.port'
+import {
+  AUTHORIZATION_REPOSITORY,
+  type AuthorizationRepository,
+} from '@/domain/oauth/repositories/authorization.repository'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+
+export type Decision = { authorization: Authorization; code: string | null }
+
+@injectable()
+export class DecideAuthorizationUseCase {
+  constructor(
+    @inject(AUTHORIZATION_REPOSITORY) private readonly authorizations: AuthorizationRepository,
+    @inject(AUTHORIZATION_CODES) private readonly codes: AuthorizationCodes,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+  ) {}
+
+  // The user who answers is the user the client will act for.
+  execute(id: string, userId: string, accept: boolean): Promise<Decision> {
+    return this.transactions.run(async () => {
+      const now = new Date()
+      const authorization = await this.authorizations.lockById(id)
+
+      if (authorization === null || !authorization.isPending(now)) {
+        throw new AuthorizationNotFoundError()
+      }
+
+      let code: string | null = null
+
+      if (accept) {
+        const secret = this.codes.create()
+
+        authorization.approve(userId, this.codes.digest(secret), now)
+        code = authorization.code(secret)
+      } else {
+        authorization.deny()
+      }
+
+      await this.authorizations.save(authorization)
+
+      return { authorization, code }
+    })
+  }
+}

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

@@ -0,0 +1,97 @@
+import { inject, injectable } from 'tsyringe'
+import { SignOutUseCase } from '@/domain/auth/use-cases/sign-out.use-case'
+import type { SessionTokens } from '@/domain/auth/use-cases/start-session.use-case'
+import { StartSessionUseCase } from '@/domain/auth/use-cases/start-session.use-case'
+import { Authorization } from '@/domain/oauth/entities/authorization.entity'
+import { InvalidGrantError } from '@/domain/oauth/errors/invalid-grant.error'
+import {
+  AUTHORIZATION_CODES,
+  type AuthorizationCodes,
+} from '@/domain/oauth/ports/authorization-codes.port'
+import {
+  AUTHORIZATION_REPOSITORY,
+  type AuthorizationRepository,
+} from '@/domain/oauth/repositories/authorization.repository'
+import {
+  TRANSACTION_MANAGER,
+  type TransactionManager,
+} from '@/domain/shared/transactions/transaction-manager'
+
+export type CodeExchange = {
+  code: string
+  clientId: string
+  redirectUri: string
+  codeVerifier: string
+  resource: string
+}
+
+@injectable()
+export class ExchangeCodeUseCase {
+  constructor(
+    @inject(AUTHORIZATION_REPOSITORY) private readonly authorizations: AuthorizationRepository,
+    @inject(AUTHORIZATION_CODES) private readonly codes: AuthorizationCodes,
+    @inject(TRANSACTION_MANAGER) private readonly transactions: TransactionManager,
+    private readonly startSession: StartSessionUseCase,
+    private readonly signOut: SignOutUseCase,
+  ) {}
+
+  async execute(request: CodeExchange): Promise<SessionTokens> {
+    const parsed = Authorization.parseCode(request.code)
+
+    if (parsed === null) {
+      throw new InvalidGrantError('Unknown authorization code')
+    }
+
+    const outcome = await this.transactions.run(async () => {
+      const now = new Date()
+      const authorization = await this.authorizations.lockById(parsed.authorizationId)
+
+      if (authorization === null || authorization.codeHash !== this.codes.digest(parsed.secret)) {
+        return { error: 'Unknown authorization code' }
+      }
+
+      // A code presented twice was copied: the tokens the first use obtained are no longer trusted either.
+      if (authorization.status === 'exchanged' && authorization.userId !== null) {
+        if (authorization.sessionId !== null) {
+          await this.signOut.execute(authorization.userId, authorization.sessionId)
+        }
+
+        return { error: 'Authorization code already used' }
+      }
+
+      if (!authorization.isRedeemable(now) || authorization.userId === null) {
+        return { error: 'Authorization code expired' }
+      }
+
+      if (
+        authorization.clientId !== request.clientId ||
+        authorization.redirectUri !== request.redirectUri ||
+        authorization.resource !== request.resource
+      ) {
+        return { error: 'The code was issued for another client, redirect URI or resource' }
+      }
+
+      if (!this.codes.matchesChallenge(request.codeVerifier, authorization.codeChallenge)) {
+        return { error: 'code_verifier does not match the code_challenge' }
+      }
+
+      const tokens = await this.startSession.execute(authorization.userId, {
+        clientId: authorization.clientId,
+        resource: authorization.resource,
+        scope: authorization.scope,
+      })
+
+      authorization.exchange(tokens.sessionId)
+      await this.authorizations.save(authorization)
+
+      return { tokens }
+    })
+
+    // Thrown after the transaction, so revoking a copied code's session is committed and not rolled back.
+    if ('error' in outcome) {
+      throw new InvalidGrantError(outcome.error)
+    }
+
+    return outcome.tokens
+  }
+}

package/templates/api/src/domain/oauth/use-cases/find-authorization.use-case.ts

@@ -0,0 +1,24 @@
+import { inject, injectable } from 'tsyringe'
+import type { Authorization } from '@/domain/oauth/entities/authorization.entity'
+import { AuthorizationNotFoundError } from '@/domain/oauth/errors/authorization-not-found.error'
+import {
+  AUTHORIZATION_REPOSITORY,
+  type AuthorizationRepository,
+} from '@/domain/oauth/repositories/authorization.repository'
+
+@injectable()
+export class FindAuthorizationUseCase {
+  constructor(
+    @inject(AUTHORIZATION_REPOSITORY) private readonly authorizations: AuthorizationRepository,
+  ) {}
+
+  async execute(id: string): Promise<Authorization> {
+    const authorization = await this.authorizations.findById(id)
+
+    if (authorization === null || !authorization.isPending(new Date())) {
+      throw new AuthorizationNotFoundError()
+    }
+
+    return authorization
+  }
+}

package/templates/api/src/domain/oauth/use-cases/start-authorization.use-case.ts

@@ -0,0 +1,89 @@
+import { inject, injectable } from 'tsyringe'
+import { Authorization } from '@/domain/oauth/entities/authorization.entity'
+import { AuthorizationRequestError } from '@/domain/oauth/errors/authorization-request.error'
+import { InvalidClientError } from '@/domain/oauth/errors/invalid-client.error'
+import {
+  CLIENT_METADATA,
+  type ClientMetadataSource,
+} from '@/domain/oauth/ports/client-metadata.port'
+import {
+  AUTHORIZATION_REPOSITORY,
+  type AuthorizationRepository,
+} from '@/domain/oauth/repositories/authorization.repository'
+
+// RFC 7636: 43 to 128 characters from the unreserved set.
+const CODE_CHALLENGE = /^[A-Za-z0-9\-._~]{43,128}$/
+
+export type AuthorizeRequest = {
+  responseType: string | undefined
+  clientId: string
+  redirectUri: string
+  codeChallenge: string | undefined
+  codeChallengeMethod: string | undefined
+  clientState: string | null
+  resource: string | undefined
+  scope: string | undefined
+}
+
+@injectable()
+export class StartAuthorizationUseCase {
+  constructor(
+    @inject(CLIENT_METADATA) private readonly clients: ClientMetadataSource,
+    @inject(AUTHORIZATION_REPOSITORY) private readonly authorizations: AuthorizationRepository,
+  ) {}
+
+  // The client and its redirect URI are checked first: until both are, no error may be sent anywhere.
+  async execute(
+    request: AuthorizeRequest,
+    expectedResource: string,
+    supportedScopes: readonly string[],
+  ): Promise<Authorization> {
+    const client = await this.clients.read(request.clientId)
+
+    // Exact match only: a prefix or a pattern is how an authorization code ends up somewhere else.
+    if (!client.redirectUris.includes(request.redirectUri)) {
+      throw new InvalidClientError('redirect_uri is not one the client registered')
+    }
+
+    if (request.responseType !== 'code') {
+      throw new AuthorizationRequestError('unsupported_response_type', 'Only response_type=code')
+    }
+
+    if (
+      request.codeChallengeMethod !== 'S256' ||
+      !CODE_CHALLENGE.test(request.codeChallenge ?? '')
+    ) {
+      throw new AuthorizationRequestError('invalid_request', 'PKCE with S256 is required')
+    }
+
+    // RFC 8707: the token is for one resource, and this server has one.
+    if (request.resource !== expectedResource) {
+      throw new AuthorizationRequestError('invalid_target', `resource must be ${expectedResource}`)
+    }
+
+    // A client that asks for nothing gets everything this server offers, and the consent page says so.
+    const requested = (request.scope ?? '').split(' ').filter(Boolean)
+    const unknown = requested.filter((scope) => !supportedScopes.includes(scope))
+
+    if (unknown.length > 0) {
+      throw new AuthorizationRequestError('invalid_scope', `Unknown scope: ${unknown.join(' ')}`)
+    }
+
+    const authorization = new Authorization(
+      {
+        clientId: request.clientId,
+        clientName: client.clientName,
+        redirectUri: request.redirectUri,
+        codeChallenge: request.codeChallenge as string,
+        clientState: request.clientState,
+        resource: expectedResource,
+        scope: (requested.length > 0 ? requested : supportedScopes).join(' '),
+      },
+      new Date(),
+    )
+
+    await this.authorizations.save(authorization)
+
+    return authorization
+  }
+}

package/templates/api/src/domain/shared/errors/domain-error.ts

@@ -2,4 +2,6 @@ export type DomainErrorKind = 'not_found' | 'conflict' | 'invalid' | 'forbidden'
 
 export abstract class DomainError extends Error {
   abstract readonly kind: DomainErrorKind
+  // A stable name a client can act on, when the status alone does not say what to do next.
+  readonly code?: string
 }

package/templates/api/src/infra/auth/argon2-password-hasher.adapter.ts

@@ -0,0 +1,21 @@
+import { hash, verify } from '@node-rs/argon2'
+import type { PasswordHasher } from '@/domain/auth/ports/password-hasher.port'
+
+// The library's defaults are Argon2id with 19 MiB, two passes and one lane: OWASP's minimum, so none is restated.
+export class Argon2PasswordHasher implements PasswordHasher {
+  // A real hash of nothing in particular, so an unknown email costs one verification like any other.
+  private readonly decoy = hash('decoy password that nobody holds')
+
+  hash(password: string): Promise<string> {
+    return hash(password)
+  }
+
+  async verify(stored: string | undefined, password: string): Promise<boolean> {
+    if (stored === undefined) {
+      await verify(await this.decoy, password)
+      return false
+    }
+
+    return verify(stored, password)
+  }
+}

package/templates/api/src/infra/auth/crypto-opaque-tokens.adapter.ts

@@ -0,0 +1,14 @@
+import { createHash, randomBytes } from 'node:crypto'
+import type { OpaqueTokens } from '@/domain/auth/ports/opaque-tokens.port'
+
+// 256 random bits need no slow hash: nothing can be guessed, so a plain SHA-256 is enough to keep a stolen
+// database from handing out working tokens.
+export class CryptoOpaqueTokens implements OpaqueTokens {
+  create(): string {
+    return randomBytes(32).toString('base64url')
+  }
+
+  digest(token: string): string {
+    return createHash('sha256').update(token).digest('base64url')
+  }
+}