@stjoseph/prumo 0.2.0 → 0.4.0

package/templates/api/scripts/ports.mjs

@@ -25,7 +25,7 @@ const APPS = {
 // A port that moves takes these with it: the key to write, in which app, from which app's port.
 const FOLLOWERS = {
   api: [
-    { app: 'api', key: 'BETTER_AUTH_URL' },
+    { app: 'api', key: 'API_URL' },
     { app: 'web', key: 'VITE_API_URL' },
     { app: 'mobile', key: 'EXPO_PUBLIC_API_URL' },
   ],

package/templates/api/src/domain/auth/dto/email-request.dto.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod'
+
+export const emailRequestSchema = z.strictObject({ email: z.email().max(254) })
+
+export type EmailRequestDto = z.infer<typeof emailRequestSchema>

package/templates/api/src/domain/auth/dto/refresh.dto.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+// The web sends its refresh token as a cookie and no body, which Fastify hands over as null; a native client
+// sends it here.
+export const refreshSchema = z
+  .strictObject({ refreshToken: z.string().min(1).optional() })
+  .nullish()
+
+export type RefreshDto = z.infer<typeof refreshSchema>

package/templates/api/src/domain/auth/dto/reset-password.dto.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+export const resetPasswordSchema = z.strictObject({
+  email: z.email().max(254),
+  code: z.string().regex(/^\d{6}$/),
+  password: z.string().min(8).max(128),
+})
+
+export type ResetPasswordDto = z.infer<typeof resetPasswordSchema>

package/templates/api/src/domain/auth/dto/session-response.dto.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+export const sessionResponseSchema = z.object({
+  user: z.object({ id: z.uuid(), email: z.string() }),
+})
+
+export type SessionResponseDto = z.infer<typeof sessionResponseSchema>

package/templates/api/src/domain/auth/dto/sign-in.dto.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const signInSchema = z.strictObject({
+  email: z.email().max(254),
+  password: z.string().min(1).max(128),
+})
+
+export type SignInDto = z.infer<typeof signInSchema>

package/templates/api/src/domain/auth/dto/sign-up.dto.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+export const signUpSchema = z.strictObject({
+  name: z.string().trim().min(1).max(80),
+  email: z.email().max(254),
+  password: z.string().min(8).max(128),
+})
+
+export type SignUpDto = z.infer<typeof signUpSchema>

package/templates/api/src/domain/auth/dto/tokens-response.dto.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+// What a native client receives instead of cookies. `expiresIn` is in seconds, as OAuth writes it.
+export const tokensResponseSchema = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresIn: z.number().int(),
+})
+
+export type TokensResponseDto = z.infer<typeof tokensResponseSchema>

package/templates/api/src/domain/auth/dto/verify-email.dto.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const verifyEmailSchema = z.strictObject({
+  email: z.email().max(254),
+  code: z.string().regex(/^\d{6}$/),
+})
+
+export type VerifyEmailDto = z.infer<typeof verifyEmailSchema>

package/templates/api/src/domain/auth/entities/email-code.entity.ts

@@ -0,0 +1,46 @@
+// Short enough that guessing is a race against the clock, long enough to switch to the mail app and back.
+export const EMAIL_CODE_LIFETIME_MS = 15 * 60 * 1000
+export const EMAIL_CODE_ATTEMPTS = 5
+
+export type EmailCodePurpose = 'verify-email' | 'reset-password'
+
+export type CodeOutcome = 'valid' | 'wrong' | 'expired'
+
+// One live code per user and purpose: sending another replaces it, and the old one stops working.
+export class EmailCode {
+  id: string
+  userId: string
+  purpose: EmailCodePurpose
+  codeHash: string
+  attemptsLeft: number
+  expiresAt: Date
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(userId: string, purpose: EmailCodePurpose, codeHash: string, now: Date) {
+    this.userId = userId
+    this.purpose = purpose
+    this.renew(codeHash, now)
+  }
+
+  renew(codeHash: string, now: Date): void {
+    this.codeHash = codeHash
+    this.attemptsLeft = EMAIL_CODE_ATTEMPTS
+    this.expiresAt = new Date(now.getTime() + EMAIL_CODE_LIFETIME_MS)
+  }
+
+  // Five wrong guesses out of a million leave nothing to brute-force: the code dies, and a new one must be sent.
+  check(codeHash: string, now: Date): CodeOutcome {
+    if (this.attemptsLeft <= 0 || this.expiresAt <= now) {
+      return 'expired'
+    }
+
+    if (codeHash === this.codeHash) {
+      this.attemptsLeft = 0
+      return 'valid'
+    }
+
+    this.attemptsLeft -= 1
+    return this.attemptsLeft === 0 ? 'expired' : 'wrong'
+  }
+}

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

@@ -0,0 +1,18 @@
+import type { ProviderName } from '@/domain/auth/ports/identity-providers.port'
+
+// A user as a provider knows them. The provider's subject, not the email, is what recognises them next time: an
+// email can change at the provider, a subject cannot.
+export class Identity {
+  id: string
+  userId: string
+  provider: ProviderName
+  subject: string
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(userId: string, provider: ProviderName, subject: string) {
+    this.userId = userId
+    this.provider = provider
+    this.subject = subject
+  }
+}

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

@@ -0,0 +1,78 @@
+// A refresh token is long-lived, so it rotates on every use and is kept only as a hash.
+export const SESSION_LIFETIME_MS = 30 * 24 * 60 * 60 * 1000
+
+// Two tabs refreshing at once both present the same token. The second, arriving within this window, is told to
+// retry instead of being treated as a stolen token.
+export const ROTATION_GRACE_MS = 10 * 1000
+
+export type RefreshOutcome = 'valid' | 'superseded' | 'reused' | 'expired'
+
+// A session the user started in this application has none of these. One an OAuth client obtained names the client,
+// the resource its access tokens are for, and the scopes the user granted it, space-separated as OAuth writes them.
+export type Grant = { clientId: string; resource: string; scope: string }
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export class Session {
+  id: string
+  userId: string
+  tokenHash: string
+  clientId: string | null = null
+  resource: string | null = null
+  scope: string | null = null
+  previousTokenHash: string | null = null
+  rotatedAt: Date | null = null
+  expiresAt: Date
+  revokedAt: Date | null = null
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(userId: string, tokenHash: string, now: Date, grant?: Grant) {
+    this.userId = userId
+    this.tokenHash = tokenHash
+    this.clientId = grant?.clientId ?? null
+    this.resource = grant?.resource ?? null
+    this.scope = grant?.scope ?? null
+    this.expiresAt = new Date(now.getTime() + SESSION_LIFETIME_MS)
+  }
+
+  // The refresh token names its session, so a token from any earlier rotation is recognised as reuse.
+  static parseRefreshToken(token: string): { sessionId: string; secret: string } | null {
+    const dot = token.indexOf('.')
+    const sessionId = token.slice(0, dot)
+    const secret = token.slice(dot + 1)
+
+    return dot === -1 || !UUID.test(sessionId) || secret === '' ? null : { sessionId, secret }
+  }
+
+  refreshToken(secret: string): string {
+    return `${this.id}.${secret}`
+  }
+
+  // A token that is neither the current one nor the one just replaced was replaced long ago: someone kept a copy.
+  check(tokenHash: string, now: Date): RefreshOutcome {
+    if (this.revokedAt !== null || this.expiresAt <= now) {
+      return 'expired'
+    }
+
+    if (tokenHash === this.tokenHash) {
+      return 'valid'
+    }
+
+    const justRotated =
+      this.rotatedAt !== null && now.getTime() - this.rotatedAt.getTime() < ROTATION_GRACE_MS
+
+    return tokenHash === this.previousTokenHash && justRotated ? 'superseded' : 'reused'
+  }
+
+  rotate(tokenHash: string, now: Date): void {
+    this.previousTokenHash = this.tokenHash
+    this.tokenHash = tokenHash
+    this.rotatedAt = now
+    this.expiresAt = new Date(now.getTime() + SESSION_LIFETIME_MS)
+  }
+
+  revoke(now: Date): void {
+    this.revokedAt ??= now
+  }
+}

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

@@ -0,0 +1,34 @@
+export class User {
+  id: string
+  email: 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 | null) {
+    this.email = User.normalizeEmail(email)
+    this.passwordHash = passwordHash
+  }
+
+  // One address, one account: `Ana@Example.com ` and `ana@example.com` are the same person.
+  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/email-taken.error.ts

@@ -0,0 +1,9 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+export class EmailTakenError extends DomainError {
+  readonly kind = 'conflict'
+
+  constructor() {
+    super('An account with this email already exists')
+  }
+}

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/invalid-credentials.error.ts

@@ -0,0 +1,10 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// One message for an unknown email and a wrong password, so the answer does not say which accounts exist.
+export class InvalidCredentialsError extends DomainError {
+  readonly kind = 'unauthorized'
+
+  constructor() {
+    super('Invalid email or password')
+  }
+}

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

@@ -0,0 +1,9 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+export class InvalidSessionError extends DomainError {
+  readonly kind = 'unauthorized'
+
+  constructor(message = 'Session expired or revoked') {
+    super(message)
+  }
+}

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/errors/superseded-token.error.ts

@@ -0,0 +1,11 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// Another request rotated this token a moment ago. The client already holds the new one, so it retries instead of
+// signing out.
+export class SupersededTokenError extends DomainError {
+  readonly kind = 'conflict'
+
+  constructor() {
+    super('Refresh token was just rotated; retry with the current one')
+  }
+}

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

@@ -0,0 +1,15 @@
+export type AccessClaims = { userId: string; sessionId: string; clientId?: string; scope?: string }
+
+export type IssuedToken = { token: string; expiresAt: Date }
+
+// Short-lived and checked by signature alone: nothing is looked up to accept one, so nothing can revoke one.
+export const ACCESS_TOKEN_LIFETIME_MS = 15 * 60 * 1000
+
+// Without an audience a token is for this API's own routes; with one, for that resource alone. Neither is accepted
+// where the other is expected.
+export interface AccessTokens {
+  issue(claims: AccessClaims, expiresAt: Date, audience?: string): Promise<IssuedToken>
+  verify(token: string, audience?: string): Promise<AccessClaims | null>
+}
+
+export const ACCESS_TOKENS = Symbol('AccessTokens')

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/ports/opaque-tokens.port.ts

@@ -0,0 +1,7 @@
+// Random values that are handed out once and stored only as a digest.
+export interface OpaqueTokens {
+  create(): string
+  digest(token: string): string
+}
+
+export const OPAQUE_TOKENS = Symbol('OpaqueTokens')

package/templates/api/src/domain/auth/ports/password-hasher.port.ts

@@ -0,0 +1,8 @@
+export interface PasswordHasher {
+  hash(password: string): Promise<string>
+  // Without a hash it still spends the time of a real check and answers false, so an unknown email and a wrong
+  // password take as long as each other.
+  verify(hash: string | undefined, password: string): Promise<boolean>
+}
+
+export const PASSWORD_HASHER = Symbol('PasswordHasher')

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

@@ -0,0 +1,12 @@
+import type { Session } from '@/domain/auth/entities/session.entity'
+
+export interface SessionRepository {
+  findById(id: string): Promise<Session | null>
+  // 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/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')