@stjoseph/prumo 0.2.0 → 0.3.0

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

@@ -0,0 +1,9 @@
+import type { User } from '@/domain/auth/entities/user.entity'
+
+export interface UserRepository {
+  findById(id: string): Promise<User | null>
+  findByEmail(email: string): Promise<User | null>
+  save(user: User): Promise<void>
+}
+
+export const USER_REPOSITORY = Symbol('UserRepository')

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/refresh-session.use-case.ts

@@ -0,0 +1,92 @@
+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 }),
+        },
+        new Date(now.getTime() + ACCESS_TOKEN_LIFETIME_MS),
+        session.resource ?? undefined,
+      ),
+      refreshToken: session.refreshToken(next),
+      refreshExpiresAt: session.expiresAt,
+    }
+  }
+}

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

@@ -0,0 +1,30 @@
+import { inject, injectable } from 'tsyringe'
+import type { SignInDto } from '@/domain/auth/dto/sign-in.dto'
+import { User } from '@/domain/auth/entities/user.entity'
+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, password)
+
+    if (user === null || !valid) {
+      throw new InvalidCredentialsError()
+    }
+
+    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,46 @@
+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 {
+  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,
+  ) {}
+
+  async execute({ name, email, password }: SignUpDto): Promise<SessionTokens> {
+    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
+    })
+
+    return this.startSession.execute(user.id)
+  }
+}

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

@@ -0,0 +1,48 @@
+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
+}
+
+@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 }) },
+        new Date(now.getTime() + ACCESS_TOKEN_LIFETIME_MS),
+        grant?.resource,
+      ),
+      refreshToken: session.refreshToken(secret),
+      refreshExpiresAt: session.expiresAt,
+    }
+  }
+}

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,13 @@
+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(),
+})
+
+export type AuthorizationViewDto = z.infer<typeof authorizationViewSchema>

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

@@ -0,0 +1,83 @@
+// 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
+}
+
+// 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
+  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.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,14 @@
+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',
+    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,96 @@
+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,
+      })
+
+      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
+  }
+}