@stjoseph/prumo 0.3.0 → 0.4.1

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

@@ -1,15 +1,26 @@
 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 { StartSessionUseCase } from '@/domain/auth/use-cases/start-session.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.
@@ -22,21 +33,62 @@ export function authFakes() {
   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: new SignUpUseCase(
+    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,
-      new CreateProfileUseCase(profiles),
       startSession,
     ),
-    signIn: new SignInUseCase(users, hasher, startSession),
-    refresh: new RefreshSessionUseCase(sessions, tokens, opaque, transactions),
-    signOut: new SignOutUseCase(sessions),
+    // prumo:end-email
   }
 }

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

@@ -16,4 +16,12 @@ export class InMemorySessionRepository implements SessionRepository {
     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/social-fakes.ts

@@ -0,0 +1,112 @@
+import { authFakes } from '@test/support/fakes/auth-fakes'
+import { FakeOpaqueTokens } from '@test/support/fakes/fake-opaque-tokens'
+import { ImmediateTransactionManager } from '@test/support/fakes/immediate-transaction-manager'
+import type { Identity } from '@/domain/auth/entities/identity.entity'
+import type { SocialSignIn } from '@/domain/auth/entities/social-sign-in.entity'
+import type {
+  IdentityProviders,
+  ProviderCallback,
+  ProviderName,
+  ProviderProfile,
+  ProviderRedirect,
+} from '@/domain/auth/ports/identity-providers.port'
+import type { IdentityRepository } from '@/domain/auth/repositories/identity.repository'
+import type { SocialSignInRepository } from '@/domain/auth/repositories/social-sign-in.repository'
+import { CompleteSocialSignInUseCase } from '@/domain/auth/use-cases/complete-social-sign-in.use-case'
+import { ExchangeSocialCodeUseCase } from '@/domain/auth/use-cases/exchange-social-code.use-case'
+import { LinkIdentityUseCase } from '@/domain/auth/use-cases/link-identity.use-case'
+import { StartSessionUseCase } from '@/domain/auth/use-cases/start-session.use-case'
+import { StartSocialSignInUseCase } from '@/domain/auth/use-cases/start-social-sign-in.use-case'
+import { CreateProfileUseCase } from '@/domain/users/use-cases/create-profile.use-case'
+import { FakeAccessTokens } from './fake-access-tokens'
+
+export class InMemoryIdentityRepository implements IdentityRepository {
+  readonly rows: Identity[] = []
+
+  async findBySubject(provider: ProviderName, subject: string): Promise<Identity | null> {
+    return this.rows.find((row) => row.provider === provider && row.subject === subject) ?? null
+  }
+
+  async save(identity: Identity): Promise<void> {
+    identity.id ??= crypto.randomUUID()
+    this.rows.push(identity)
+  }
+}
+
+export class InMemorySocialSignInRepository implements SocialSignInRepository {
+  readonly rows = new Map<string, SocialSignIn>()
+
+  async lockById(id: string): Promise<SocialSignIn | null> {
+    return this.rows.get(id) ?? null
+  }
+
+  async save(signIn: SocialSignIn): Promise<void> {
+    signIn.id ??= crypto.randomUUID()
+    this.rows.set(signIn.id, signIn)
+  }
+}
+
+// A provider that answers what the test tells it to, and remembers what it was asked.
+export class FakeIdentityProviders implements IdentityProviders {
+  next: ProviderProfile = {
+    subject: 'google-sub-1',
+    email: 'ana@example.com',
+    emailVerified: true,
+    name: 'Ana',
+  }
+  lastCallback: ProviderCallback | undefined
+
+  constructor(private readonly configured: ProviderName[] = ['google', 'apple']) {}
+
+  isConfigured(provider: ProviderName): boolean {
+    return this.configured.includes(provider)
+  }
+
+  async redirect(provider: ProviderName, state: string): Promise<ProviderRedirect> {
+    return {
+      url: `https://${provider}.test/authorize?state=${state}`,
+      codeVerifier: 'verifier',
+      nonce: 'nonce',
+    }
+  }
+
+  async profile(_provider: ProviderName, callback: ProviderCallback): Promise<ProviderProfile> {
+    this.lastCallback = callback
+    return this.next
+  }
+}
+
+export function socialFakes() {
+  const auth = authFakes()
+  const identities = new InMemoryIdentityRepository()
+  const signIns = new InMemorySocialSignInRepository()
+  const providers = new FakeIdentityProviders()
+  const opaque = new FakeOpaqueTokens()
+  const transactions = new ImmediateTransactionManager()
+  const startSession = new StartSessionUseCase(auth.sessions, new FakeAccessTokens(), opaque)
+  const linkIdentity = new LinkIdentityUseCase(
+    auth.users,
+    identities,
+    auth.sessions,
+    transactions,
+    new CreateProfileUseCase(auth.profiles),
+  )
+
+  return {
+    ...auth,
+    identities,
+    signIns,
+    providers,
+    linkIdentity,
+    start: new StartSocialSignInUseCase(providers, signIns, opaque),
+    complete: new CompleteSocialSignInUseCase(
+      providers,
+      signIns,
+      opaque,
+      transactions,
+      linkIdentity,
+      startSession,
+    ),
+    exchange: new ExchangeSocialCodeUseCase(signIns, opaque, transactions, startSession),
+  }
+}

package/templates/api/test/support/test-app.ts

@@ -0,0 +1,65 @@
+import { FakeMailer } from '@test/support/fakes/fake-mailer' // prumo:email
+import { testEnv, testOrm } from '@test/support/setup'
+import type { DependencyContainer } from 'tsyringe'
+import { MAILER } from '@/domain/auth/ports/mailer.port' // prumo:email
+import type { Env } from '@/infra/config/env'
+import { createContainer } from '@/infra/di'
+import { buildApp } from '@/infra/http/app'
+
+export const ORIGIN = 'http://localhost:5173'
+export const PASSWORD = 'correct-horse-battery'
+
+// The application as a test meets it: the real container over the test database, with a mailer whose inbox the
+// test can read.
+export async function testApp({
+  env = testEnv(),
+  configure,
+}: {
+  env?: Env
+  configure?: (container: DependencyContainer) => void
+} = {}) {
+  const container = createContainer({ env, orm: testOrm() })
+  // prumo:email
+  const mailer = new FakeMailer()
+
+  container.register(MAILER, { useValue: mailer })
+  // prumo:end-email
+  configure?.(container)
+
+  const app = await buildApp(container)
+
+  // Signs up through the real routes and, where the email must be confirmed first, confirms it. Returns the
+  // response that delivered the session: cookies for the web, tokens in the body for a bearer client.
+  async function signUp({ bearer = false, email = `${crypto.randomUUID()}@example.com` } = {}) {
+    const headers = bearer ? { 'x-auth-transport': 'bearer' } : { origin: ORIGIN }
+    let response = await app.inject({
+      method: 'POST',
+      url: '/api/auth/sign-up',
+      headers,
+      payload: { name: 'Ana', email, password: PASSWORD },
+    })
+
+    // prumo:email
+    if (response.body.includes('verificationRequired')) {
+      response = await app.inject({
+        method: 'POST',
+        url: '/api/auth/email/verify',
+        headers,
+        payload: { email, code: mailer.lastCode(email) },
+      })
+    }
+
+    // prumo:end-email
+    return { response, email }
+  }
+
+  return {
+    app,
+    signUp,
+    mailer, // prumo:email
+  }
+}
+
+export function cookieHeader(response: { cookies: { name: string; value: string }[] }): string {
+  return response.cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join('; ')
+}

package/templates/mobile/README.md

@@ -2,16 +2,23 @@
 
 ## Requirements
 
-Node 22.18 or later, pnpm 10.26 or later, and the API running. A simulator or a device with Expo Go
-to open the app.
+Node 22.18 or later, pnpm 10.26 or later, and the API running. To open the app, a simulator or a device with a
+development build of it, made on this machine with Xcode for iOS or Android Studio for Android. Expo Go cannot open
+it, because MMKV's native code is not part of Expo Go.
 
 ## Running it
 
 ```sh
 pnpm install
-pnpm dev
+pnpm ios       # or pnpm android: builds the development build, installs it, and serves it
+pnpm dev       # afterwards, until a native dependency changes
 ```
 
+`pnpm ios` and `pnpm android` run `expo run:ios` and `expo run:android`, which generate the native project the first
+time and compile it, so the first run is the slow one. `pnpm dev` then only serves the JavaScript, and the installed
+build opens it, because `expo-dev-client` makes `expo start` target the development build rather than Expo Go.
+Build again after adding or upgrading a package with native code.
+
 `.env` comes with the generated project, copied from `.env.example`; `EXPO_PUBLIC_API_URL` points at the API. It is
 not committed, so on a fresh clone run `cp .env.example .env`.
 
@@ -26,11 +33,17 @@ Ctrl+C stops everything `pnpm dev` started, not only what the terminal signals:
 it spawned, stops them, and frees the port. Anything it did not start is named and left alone.
 
 On an Android emulator `localhost` is the emulator itself; point `EXPO_PUBLIC_API_URL` at your machine's address.
+<!-- prumo:email -->
+
+Signing up first asks for the 6-digit code that confirms the email. No mail is sent yet: the API writes it to its
+log, in a line starting `[mail] to`, and a forgotten password works the same way.
+<!-- prumo:end-email -->
 
 ## Everyday commands
 
 | Command | What it does |
 |---|---|
+| `pnpm ios` · `pnpm android` | Builds and installs the development build, then serves it. Xcode or Android Studio |
 | `pnpm test` | Jest with `jest-expo`, rendering components against a fake transport; no API needed |
 | `pnpm lint` | Biome |
 | `pnpm typecheck` | `tsc --noEmit`, also run before every push |

package/templates/mobile/package.json

@@ -6,8 +6,8 @@
   "scripts": {
     "start": "expo start",
     "dev": "node scripts/ports.mjs -- expo start",
-    "ios": "expo start --ios",
-    "android": "expo start --android",
+    "ios": "node scripts/ports.mjs -- expo run:ios",
+    "android": "node scripts/ports.mjs -- expo run:android",
     "bundle": "expo export --platform ios --platform android",
     "lint": "biome check",
     "typecheck": "tsc --noEmit",
@@ -22,6 +22,7 @@
     "class-variance-authority": "0.7.1",
     "expo": "57.0.22",
     "expo-constants": "57.0.18",
+    "expo-dev-client": "57.0.19",
     "expo-linking": "57.0.10",
     "expo-router": "57.0.21",
     "expo-secure-store": "57.0.4",

package/templates/mobile/src/api-contract/api-error.ts

@@ -5,6 +5,7 @@ type ProblemDocument = {
   status?: number
   detail?: string
   requestId?: string
+  code?: string
   errors?: FieldErrors
 }
 
@@ -15,6 +16,8 @@ export class ApiError extends Error {
     readonly detail: string | undefined,
     readonly requestId: string | undefined,
     readonly errors: FieldErrors,
+    // A stable name for a refusal the client acts on, such as `email_not_verified`.
+    readonly code?: string,
   ) {
     super(detail ?? title)
   }
@@ -35,6 +38,7 @@ export class ApiError extends Error {
       problem.detail,
       problem.requestId ?? requestId,
       problem.errors ?? {},
+      problem.code,
     )
   }
 }