@stjoseph/prumo 0.2.0 → 0.4.0

package/templates/api/test/infra/oauth/https-client-metadata.adapter.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { InvalidClientError } from '@/domain/oauth/errors/invalid-client.error'
+import { HttpsClientMetadata, isPrivateAddress } from '@/infra/oauth/https-client-metadata.adapter'
+
+describe('HttpsClientMetadata', () => {
+  it('refuses a client_id that is not a canonical https URL with a path', async () => {
+    const source = new HttpsClientMetadata()
+
+    for (const clientId of [
+      'not a url',
+      'http://client.example.com/client.json',
+      'https://client.example.com',
+      'https://client.example.com/',
+      'https://client.example.com/client.json?x=1',
+      'https://client.example.com/client.json#top',
+      'https://user:pass@client.example.com/client.json',
+      'https://client.example.com/a/../client.json',
+      'https://CLIENT.example.com/client.json',
+    ]) {
+      await expect(source.read(clientId), clientId).rejects.toBeInstanceOf(InvalidClientError)
+    }
+  })
+
+  it('refuses to fetch from this machine or its network, whatever the name says', async () => {
+    const source = new HttpsClientMetadata()
+
+    for (const clientId of [
+      'https://localhost/client.json',
+      'https://127.0.0.1/client.json',
+      'https://10.0.0.1/client.json',
+      'https://[::1]/client.json',
+    ]) {
+      await expect(source.read(clientId), clientId).rejects.toThrow(
+        /private address|could not be read/,
+      )
+    }
+  })
+
+  it('knows the private, loopback, link-local and mapped ranges from public ones', () => {
+    for (const address of [
+      '127.0.0.1',
+      '10.1.2.3',
+      '172.16.0.1',
+      '192.168.1.1',
+      '169.254.169.254',
+      '::1',
+      'fe80::1',
+      'fd00::1',
+      '::ffff:127.0.0.1',
+    ]) {
+      expect(isPrivateAddress(address), address).toBe(true)
+    }
+
+    for (const address of ['8.8.8.8', '1.1.1.1', '2606:4700:4700::1111']) {
+      expect(isPrivateAddress(address), address).toBe(false)
+    }
+  })
+})

package/templates/api/test/infra/social/openid-identity-providers.adapter.spec.ts

@@ -0,0 +1,154 @@
+import { fakeOidcServer } from '@test/support/fake-oidc-server'
+import { testEnv } from '@test/support/setup'
+// One line, so its marker takes all of it.
+import * as jose from 'jose' // prumo:apple
+import { afterEach, describe, expect, it } from 'vitest'
+import { SocialSignInFailedError } from '@/domain/auth/errors/social-sign-in-failed.error' // prumo:google
+import { OpenIdIdentityProviders } from '@/infra/social/openid-identity-providers.adapter'
+
+let server: Awaited<ReturnType<typeof fakeOidcServer>>
+
+afterEach(async () => {
+  await server.close()
+})
+
+function callback(provider: string, code: string, state: string): URL {
+  return new URL(
+    `http://localhost:3000/api/auth/social/${provider}/callback?code=${code}&state=${state}`,
+  )
+}
+
+// prumo:google
+describe('OpenIdIdentityProviders with Google', () => {
+  async function google() {
+    server = await fakeOidcServer({ pkce: true })
+
+    return new OpenIdIdentityProviders(
+      { ...testEnv(), GOOGLE_CLIENT_ID: 'google-client', GOOGLE_CLIENT_SECRET: 'google-secret' },
+      { issuers: { google: server.issuer }, insecure: true },
+    )
+  }
+
+  it('sends PKCE, state and nonce, and reads the verified profile back', async () => {
+    const providers = await google()
+    const redirect = await providers.redirect('google', 'state-1')
+    const url = new URL(redirect.url)
+    const code = server.authorize(redirect.url, {
+      sub: 'g-1',
+      email: 'ana@example.com',
+      email_verified: true,
+      name: 'Ana',
+    })
+
+    expect(url.searchParams.get('code_challenge_method')).toBe('S256')
+    expect(url.searchParams.get('redirect_uri')).toBe(
+      'http://localhost:3000/api/auth/social/google/callback',
+    )
+
+    const profile = await providers.profile('google', {
+      callbackUrl: callback('google', code, 'state-1'),
+      state: 'state-1',
+      codeVerifier: redirect.codeVerifier,
+      nonce: redirect.nonce,
+      name: null,
+    })
+
+    expect(profile).toEqual({
+      subject: 'g-1',
+      email: 'ana@example.com',
+      emailVerified: true,
+      name: 'Ana',
+    })
+    expect(server.tokenRequests[0]?.get('client_secret')).toBe('google-secret')
+  })
+
+  it('refuses another state, another nonce and a code it did not issue', async () => {
+    const providers = await google()
+    const redirect = await providers.redirect('google', 'state-1')
+    const base = {
+      state: 'state-1',
+      codeVerifier: redirect.codeVerifier,
+      nonce: redirect.nonce,
+      name: null,
+    }
+    const claims = { sub: 'g-1', email: 'ana@example.com', email_verified: true }
+
+    await expect(
+      providers.profile('google', {
+        ...base,
+        callbackUrl: callback('google', server.authorize(redirect.url, claims), 'other-state'),
+      }),
+    ).rejects.toBeInstanceOf(SocialSignInFailedError)
+    await expect(
+      providers.profile('google', {
+        ...base,
+        nonce: 'other-nonce',
+        callbackUrl: callback('google', server.authorize(redirect.url, claims), 'state-1'),
+      }),
+    ).rejects.toBeInstanceOf(SocialSignInFailedError)
+    await expect(
+      providers.profile('google', {
+        ...base,
+        callbackUrl: callback('google', 'forged', 'state-1'),
+      }),
+    ).rejects.toBeInstanceOf(SocialSignInFailedError)
+  })
+
+  it('is not configured without its client id and secret', () => {
+    expect(new OpenIdIdentityProviders(testEnv()).isConfigured('google')).toBe(false)
+  })
+})
+
+// prumo:end-google
+// prumo:apple
+describe('OpenIdIdentityProviders with Apple', () => {
+  it('signs its client secret with the .p8 key, asks for a form post, and reads "true" as verified', async () => {
+    server = await fakeOidcServer({ pkce: false })
+    const { privateKey, publicKey } = await jose.generateKeyPair('ES256', { extractable: true })
+    const providers = new OpenIdIdentityProviders(
+      {
+        ...testEnv(),
+        APPLE_CLIENT_ID: 'com.example.web',
+        APPLE_TEAM_ID: 'TEAM123456',
+        APPLE_KEY_ID: 'KEY1234567',
+        // As it sits in .env: one line, its breaks written as \n.
+        APPLE_PRIVATE_KEY: (await jose.exportPKCS8(privateKey)).replaceAll('\n', '\\n'),
+      },
+      { issuers: { apple: server.issuer }, insecure: true },
+    )
+    const redirect = await providers.redirect('apple', 'state-1')
+    const url = new URL(redirect.url)
+    const code = server.authorize(redirect.url, {
+      sub: 'a-1',
+      email: 'ana@privaterelay.appleid.com',
+      email_verified: 'true',
+    })
+
+    expect(url.searchParams.get('response_mode')).toBe('form_post')
+    expect(url.searchParams.get('code_challenge')).toBeNull()
+    expect(redirect.codeVerifier).toBeNull()
+
+    const profile = await providers.profile('apple', {
+      callbackUrl: callback('apple', code, 'state-1'),
+      state: 'state-1',
+      codeVerifier: null,
+      nonce: redirect.nonce,
+      name: 'Ana Apple',
+    })
+    const secret = server.tokenRequests[0]?.get('client_secret') ?? ''
+    const { payload } = await jose.jwtVerify(
+      secret,
+      await jose.importSPKI(await jose.exportSPKI(publicKey), 'ES256'),
+      {
+        issuer: 'TEAM123456',
+        subject: 'com.example.web',
+        audience: 'https://appleid.apple.com',
+      },
+    )
+
+    expect(profile).toMatchObject({ subject: 'a-1', emailVerified: true, name: 'Ana Apple' })
+    expect(jose.decodeProtectedHeader(secret)).toMatchObject({ alg: 'ES256', kid: 'KEY1234567' })
+    expect(payload.exp).toBeGreaterThan(Date.now() / 1000)
+  })
+})
+// prumo:end-apple

package/templates/api/test/support/factories/user.factory.ts

@@ -1,21 +1,19 @@
-import { randomUUID } from 'node:crypto'
 import type { EntityManager } from '@mikro-orm/postgresql'
+import { User } from '@/domain/auth/entities/user.entity'
 
-type UserOverrides = Partial<{ name: string; email: string }>
+type UserOverrides = Partial<{ email: string; passwordHash: string }>
 
+// The hash is not a real one: a test that signs in goes through the sign-up route instead.
 export async function createUser(
   em: EntityManager,
   overrides: UserOverrides = {},
 ): Promise<string> {
-  const id = randomUUID()
+  const user = new User(
+    overrides.email ?? `${crypto.randomUUID()}@example.com`,
+    overrides.passwordHash ?? 'not-a-real-hash',
+  )
 
-  // auth.user belongs to Better Auth, and the ORM maps only its id, so the row is written in SQL.
-  await em
-    .getConnection()
-    .execute(
-      'insert into auth."user" (id, name, email, "emailVerified", "createdAt", "updatedAt") values (?, ?, ?, false, now(), now())',
-      [id, overrides.name ?? 'Test Person', overrides.email ?? `${id}@example.com`],
-    )
+  await em.persist(user).flush()
 
-  return id
+  return user.id
 }

package/templates/api/test/support/fake-oidc-server.ts

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto'
+import { createServer, type Server } from 'node:http'
+import { exportJWK, generateKeyPair, SignJWT } from 'jose'
+
+type Grant = { nonce: string; challenge: string | null; claims: Record<string, unknown> }
+
+// A minimal OpenID Connect provider on localhost: discovery, keys, and a token endpoint that signs an ID token for
+// the code it handed out. Enough to run the real adapter end to end, which no test can do against Google or Apple.
+export async function fakeOidcServer({ pkce }: { pkce: boolean }) {
+  const { privateKey, publicKey } = await generateKeyPair('RS256')
+  const jwk = { ...(await exportJWK(publicKey)), kid: 'k1', alg: 'RS256', use: 'sig' }
+  const grants = new Map<string, Grant>()
+  const tokenRequests: URLSearchParams[] = []
+  let issuer = ''
+
+  const server: Server = createServer(async (request, response) => {
+    const url = new URL(request.url ?? '/', issuer)
+    const json = (status: number, body: unknown) => {
+      response.writeHead(status, { 'content-type': 'application/json' })
+      response.end(JSON.stringify(body))
+    }
+
+    if (url.pathname === '/.well-known/openid-configuration') {
+      return json(200, {
+        issuer,
+        authorization_endpoint: `${issuer}/authorize`,
+        token_endpoint: `${issuer}/token`,
+        jwks_uri: `${issuer}/jwks`,
+        response_types_supported: ['code'],
+        subject_types_supported: ['public'],
+        id_token_signing_alg_values_supported: ['RS256'],
+        token_endpoint_auth_methods_supported: ['client_secret_post'],
+        ...(pkce && { code_challenge_methods_supported: ['S256'] }),
+      })
+    }
+
+    if (url.pathname === '/jwks') {
+      return json(200, { keys: [jwk] })
+    }
+
+    if (url.pathname === '/token') {
+      let body = ''
+      for await (const chunk of request) body += chunk
+      const form = new URLSearchParams(body)
+      tokenRequests.push(form)
+
+      const grant = grants.get(form.get('code') ?? '')
+      const verifier = form.get('code_verifier')
+
+      if (
+        grant === undefined ||
+        (grant.challenge !== null &&
+          createHash('sha256')
+            .update(verifier ?? '')
+            .digest('base64url') !== grant.challenge)
+      ) {
+        return json(400, { error: 'invalid_grant' })
+      }
+
+      grants.delete(form.get('code') ?? '')
+
+      const idToken = await new SignJWT({ nonce: grant.nonce, ...grant.claims })
+        .setProtectedHeader({ alg: 'RS256', kid: 'k1' })
+        .setIssuer(issuer)
+        .setAudience(form.get('client_id') ?? '')
+        .setIssuedAt()
+        .setExpirationTime('5m')
+        .sign(privateKey)
+
+      return json(200, { access_token: 'access', token_type: 'Bearer', id_token: idToken })
+    }
+
+    json(404, {})
+  })
+
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  issuer = `http://127.0.0.1:${(server.address() as { port: number }).port}`
+
+  return {
+    issuer: new URL(issuer),
+    tokenRequests,
+    // What the provider would do after the user signs in: remember the request and hand back a code.
+    authorize(authorizationUrl: string, claims: Record<string, unknown>): string {
+      const params = new URL(authorizationUrl).searchParams
+      const code = crypto.randomUUID()
+
+      grants.set(code, {
+        nonce: params.get('nonce') ?? '',
+        challenge: params.get('code_challenge'),
+        claims,
+      })
+      return code
+    },
+    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+  }
+}

package/templates/api/test/support/fakes/auth-fakes.ts

@@ -0,0 +1,94 @@
+import { FakeAccessTokens } from '@test/support/fakes/fake-access-tokens'
+import { FakeMailer } from '@test/support/fakes/fake-mailer' // prumo:email
+import { FakeOneTimeCodes } from '@test/support/fakes/fake-one-time-codes' // prumo:email
+import { FakeOpaqueTokens } from '@test/support/fakes/fake-opaque-tokens'
+import { FakePasswordHasher } from '@test/support/fakes/fake-password-hasher'
+import { ImmediateTransactionManager } from '@test/support/fakes/immediate-transaction-manager'
+import { InMemoryEmailCodeRepository } from '@test/support/fakes/in-memory-email-code.repository' // prumo:email
+import { InMemoryProfileRepository } from '@test/support/fakes/in-memory-profile.repository'
+import { InMemorySessionRepository } from '@test/support/fakes/in-memory-session.repository'
+import { InMemoryUserRepository } from '@test/support/fakes/in-memory-user.repository'
+import type { SignUpDto } from '@/domain/auth/dto/sign-up.dto'
+import { IssueEmailCodeUseCase } from '@/domain/auth/use-cases/issue-email-code.use-case' // prumo:email
+import { RefreshSessionUseCase } from '@/domain/auth/use-cases/refresh-session.use-case'
+import { RequestPasswordResetUseCase } from '@/domain/auth/use-cases/request-password-reset.use-case' // prumo:email
+import { ResetPasswordUseCase } from '@/domain/auth/use-cases/reset-password.use-case' // prumo:email
+import { SignInUseCase } from '@/domain/auth/use-cases/sign-in.use-case'
+import { SignOutUseCase } from '@/domain/auth/use-cases/sign-out.use-case'
+import { SignUpUseCase } from '@/domain/auth/use-cases/sign-up.use-case'
+import {
+  type SessionTokens,
+  StartSessionUseCase,
+} from '@/domain/auth/use-cases/start-session.use-case'
+import { VerifyEmailUseCase } from '@/domain/auth/use-cases/verify-email.use-case' // prumo:email
+import { CreateProfileUseCase } from '@/domain/users/use-cases/create-profile.use-case'
+
+// Every auth use case wired to in-memory ports, sharing one set of them as the container would.
+export function authFakes() {
+  const users = new InMemoryUserRepository()
+  const sessions = new InMemorySessionRepository()
+  const profiles = new InMemoryProfileRepository()
+  const hasher = new FakePasswordHasher()
+  const tokens = new FakeAccessTokens()
+  const opaque = new FakeOpaqueTokens()
+  const transactions = new ImmediateTransactionManager()
+  const startSession = new StartSessionUseCase(sessions, tokens, opaque)
+  // prumo:email
+  const mailer = new FakeMailer()
+  const codes = new InMemoryEmailCodeRepository()
+  const oneTimeCodes = new FakeOneTimeCodes()
+  const issueEmailCode = new IssueEmailCodeUseCase(codes, oneTimeCodes, mailer, transactions)
+  const verifyEmail = new VerifyEmailUseCase(users, codes, oneTimeCodes, transactions, startSession)
+  // prumo:end-email
+  const signUp = new SignUpUseCase(
+    users,
+    hasher,
+    transactions,
+    new CreateProfileUseCase(profiles),
+    startSession,
+    issueEmailCode, // prumo:email
+  )
+
+  // Signs up and, where the email must be confirmed first, confirms it: a session either way.
+  async function register(request: SignUpDto): Promise<SessionTokens> {
+    const started = await signUp.execute(request)
+
+    // prumo:email
+    if (started === null) {
+      return verifyEmail.execute({ email: request.email, code: mailer.lastCode(request.email) })
+    }
+
+    // prumo:end-email
+    if (started === null) {
+      throw new Error('Sign-up opened no session')
+    }
+
+    return started
+  }
+
+  return {
+    users,
+    sessions,
+    profiles,
+    hasher,
+    signUp,
+    register,
+    signIn: new SignInUseCase(users, hasher, startSession),
+    refresh: new RefreshSessionUseCase(sessions, tokens, opaque, transactions),
+    signOut: new SignOutUseCase(sessions),
+    // prumo:email
+    mailer,
+    verifyEmail,
+    requestPasswordReset: new RequestPasswordResetUseCase(users, issueEmailCode),
+    resetPassword: new ResetPasswordUseCase(
+      users,
+      codes,
+      sessions,
+      oneTimeCodes,
+      hasher,
+      transactions,
+      startSession,
+    ),
+    // prumo:end-email
+  }
+}

package/templates/api/test/support/fakes/fake-access-tokens.ts

@@ -0,0 +1,19 @@
+import type {
+  AccessClaims,
+  AccessTokens,
+  IssuedToken,
+} from '@/domain/auth/ports/access-tokens.port'
+
+export class FakeAccessTokens implements AccessTokens {
+  async issue({ userId, sessionId }: AccessClaims, expiresAt: Date): Promise<IssuedToken> {
+    return { token: `access:${userId}:${sessionId}`, expiresAt }
+  }
+
+  async verify(token: string): Promise<AccessClaims | null> {
+    const [kind, userId, sessionId] = token.split(':')
+
+    return kind === 'access' && userId !== undefined && sessionId !== undefined
+      ? { userId, sessionId }
+      : null
+  }
+}

package/templates/api/test/support/fakes/fake-mailer.ts

@@ -0,0 +1,21 @@
+import type { Mail, Mailer } from '@/domain/auth/ports/mailer.port'
+
+// Keeps what would have been sent, so a test reads the code the way a person reads their inbox.
+export class FakeMailer implements Mailer {
+  readonly sent: Mail[] = []
+
+  async send(mail: Mail): Promise<void> {
+    this.sent.push(mail)
+  }
+
+  lastCode(to: string): string {
+    const mail = this.sent.findLast((each) => each.to === to)
+    const code = mail === undefined ? undefined : /\b\d{6}\b/.exec(mail.text)?.[0]
+
+    if (code === undefined) {
+      throw new Error(`No code was sent to ${to}`)
+    }
+
+    return code
+  }
+}

package/templates/api/test/support/fakes/fake-one-time-codes.ts

@@ -0,0 +1,14 @@
+import type { OneTimeCodes } from '@/domain/auth/ports/one-time-codes.port'
+
+export class FakeOneTimeCodes implements OneTimeCodes {
+  private next = 100000
+
+  create(): string {
+    this.next += 1
+    return String(this.next)
+  }
+
+  digest(code: string): string {
+    return `digest:${code}`
+  }
+}

package/templates/api/test/support/fakes/fake-opaque-tokens.ts

@@ -0,0 +1,14 @@
+import type { OpaqueTokens } from '@/domain/auth/ports/opaque-tokens.port'
+
+export class FakeOpaqueTokens implements OpaqueTokens {
+  private next = 0
+
+  create(): string {
+    this.next += 1
+    return `secret-${this.next}`
+  }
+
+  digest(token: string): string {
+    return `digest:${token}`
+  }
+}

package/templates/api/test/support/fakes/fake-password-hasher.ts

@@ -0,0 +1,15 @@
+import type { PasswordHasher } from '@/domain/auth/ports/password-hasher.port'
+
+// Reversible on purpose, so a test can read what was stored. Argon2 itself is proved in its adapter's test.
+export class FakePasswordHasher implements PasswordHasher {
+  verifications = 0
+
+  async hash(password: string): Promise<string> {
+    return `hashed:${password}`
+  }
+
+  async verify(hash: string | undefined, password: string): Promise<boolean> {
+    this.verifications += 1
+    return hash === `hashed:${password}`
+  }
+}

package/templates/api/test/support/fakes/immediate-transaction-manager.ts

@@ -0,0 +1,8 @@
+import type { TransactionManager } from '@/domain/shared/transactions/transaction-manager'
+
+// Runs the work and nothing else: atomicity is the adapter's to prove, against a real database.
+export class ImmediateTransactionManager implements TransactionManager {
+  run<T>(work: () => Promise<T>): Promise<T> {
+    return work()
+  }
+}

package/templates/api/test/support/fakes/in-memory-email-code.repository.ts

@@ -0,0 +1,15 @@
+import type { EmailCode, EmailCodePurpose } from '@/domain/auth/entities/email-code.entity'
+import type { EmailCodeRepository } from '@/domain/auth/repositories/email-code.repository'
+
+export class InMemoryEmailCodeRepository implements EmailCodeRepository {
+  readonly rows = new Map<string, EmailCode>()
+
+  async lockFor(userId: string, purpose: EmailCodePurpose): Promise<EmailCode | null> {
+    return this.rows.get(`${userId}:${purpose}`) ?? null
+  }
+
+  async save(code: EmailCode): Promise<void> {
+    code.id ??= crypto.randomUUID()
+    this.rows.set(`${code.userId}:${code.purpose}`, code)
+  }
+}

package/templates/api/test/support/fakes/in-memory-session.repository.ts

@@ -0,0 +1,27 @@
+import type { Session } from '@/domain/auth/entities/session.entity'
+import type { SessionRepository } from '@/domain/auth/repositories/session.repository'
+
+export class InMemorySessionRepository implements SessionRepository {
+  readonly rows = new Map<string, Session>()
+
+  async findById(id: string): Promise<Session | null> {
+    return this.rows.get(id) ?? null
+  }
+
+  lockById(id: string): Promise<Session | null> {
+    return this.findById(id)
+  }
+
+  async save(session: Session): Promise<void> {
+    session.id ??= crypto.randomUUID()
+    this.rows.set(session.id, session)
+  }
+
+  async revokeAllFor(userId: string, now: Date): Promise<void> {
+    for (const session of this.rows.values()) {
+      if (session.userId === userId) {
+        session.revoke(now)
+      }
+    }
+  }
+}

package/templates/api/test/support/fakes/in-memory-user.repository.ts

@@ -0,0 +1,20 @@
+import type { User } from '@/domain/auth/entities/user.entity'
+import type { UserRepository } from '@/domain/auth/repositories/user.repository'
+
+export class InMemoryUserRepository implements UserRepository {
+  readonly rows = new Map<string, User>()
+
+  async findById(id: string): Promise<User | null> {
+    return this.rows.get(id) ?? null
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return [...this.rows.values()].find((user) => user.email === email) ?? null
+  }
+
+  async save(user: User): Promise<void> {
+    // The database assigns the id; here the first save does.
+    user.id ??= crypto.randomUUID()
+    this.rows.set(user.id, user)
+  }
+}