@stjoseph/prumo 0.3.0 → 0.4.1

package/templates/api/src/infra/di/email.di.ts

@@ -0,0 +1,23 @@
+import type { DependencyContainer } from 'tsyringe'
+import { MAILER } from '@/domain/auth/ports/mailer.port'
+import { ONE_TIME_CODES } from '@/domain/auth/ports/one-time-codes.port'
+import { EMAIL_CODE_REPOSITORY } from '@/domain/auth/repositories/email-code.repository'
+import { ENV, type Env } from '@/infra/config/env'
+import { MikroOrmEmailCodeRepository } from '@/infra/database/mikroorm/repositories/mikroorm-email-code.repository'
+import { HmacOneTimeCodes } from '@/infra/email/hmac-one-time-codes.adapter'
+import { LogMailer } from '@/infra/email/log-mailer.adapter'
+
+export function registerEmail(container: DependencyContainer): void {
+  const env = container.resolve<Env>(ENV)
+
+  container.register(EMAIL_CODE_REPOSITORY, { useClass: MikroOrmEmailCodeRepository })
+  container.register(ONE_TIME_CODES, { useValue: new HmacOneTimeCodes(env) })
+  // Silent under test, where a test registers its own Mailer to read what was sent.
+  container.register(MAILER, {
+    useValue: new LogMailer((line) => {
+      if (env.NODE_ENV !== 'test') {
+        console.info(line)
+      }
+    }),
+  })
+}

package/templates/api/src/infra/di/index.ts

@@ -4,7 +4,9 @@ import { TRANSACTION_MANAGER } from '@/domain/shared/transactions/transaction-ma
 import { ENV, type Env } from '@/infra/config/env'
 import { MikroOrmTransactionManager } from '@/infra/database/mikroorm/transactions/mikroorm-transaction-manager'
 import { registerAuth } from './auth.di'
+import { registerEmail } from './email.di' // prumo:email
 import { registerOauth } from './oauth.di' // prumo:mcp
+import { registerSocial } from './social.di' // prumo:social
 import { registerUsers } from './users.di'
 
 export type Dependencies = { env: Env; orm: MikroORM }
@@ -21,6 +23,8 @@ export function createContainer({ env, orm }: Dependencies): DependencyContainer
   registerAuth(container)
   registerUsers(container)
   registerOauth(container) // prumo:mcp
+  registerEmail(container) // prumo:email
+  registerSocial(container) // prumo:social
 
   return container
 }

package/templates/api/src/infra/di/social.di.ts

@@ -0,0 +1,17 @@
+import type { DependencyContainer } from 'tsyringe'
+import { IDENTITY_PROVIDERS } from '@/domain/auth/ports/identity-providers.port'
+import { IDENTITY_REPOSITORY } from '@/domain/auth/repositories/identity.repository'
+import { SOCIAL_SIGN_IN_REPOSITORY } from '@/domain/auth/repositories/social-sign-in.repository'
+import { ENV, type Env } from '@/infra/config/env'
+import { MikroOrmIdentityRepository } from '@/infra/database/mikroorm/repositories/mikroorm-identity.repository'
+import { MikroOrmSocialSignInRepository } from '@/infra/database/mikroorm/repositories/mikroorm-social-sign-in.repository'
+import { OpenIdIdentityProviders } from '@/infra/social/openid-identity-providers.adapter'
+
+export function registerSocial(container: DependencyContainer): void {
+  container.register(IDENTITY_REPOSITORY, { useClass: MikroOrmIdentityRepository })
+  container.register(SOCIAL_SIGN_IN_REPOSITORY, { useClass: MikroOrmSocialSignInRepository })
+  // One instance, so each provider's discovery document is fetched once.
+  container.register(IDENTITY_PROVIDERS, {
+    useValue: new OpenIdIdentityProviders(container.resolve<Env>(ENV)),
+  })
+}

package/templates/api/src/infra/email/hmac-one-time-codes.adapter.ts

@@ -0,0 +1,16 @@
+import { createHmac, randomInt } from 'node:crypto'
+import type { OneTimeCodes } from '@/domain/auth/ports/one-time-codes.port'
+import type { Env } from '@/infra/config/env'
+
+export class HmacOneTimeCodes implements OneTimeCodes {
+  constructor(private readonly env: Pick<Env, 'JWT_SECRET'>) {}
+
+  create(): string {
+    return randomInt(0, 1_000_000).toString().padStart(6, '0')
+  }
+
+  // A million codes hash in a moment, so the hash is keyed by a secret the database does not hold.
+  digest(code: string): string {
+    return createHmac('sha256', this.env.JWT_SECRET).update(code).digest('base64url')
+  }
+}

package/templates/api/src/infra/email/log-mailer.adapter.ts

@@ -0,0 +1,11 @@
+import type { Mail, Mailer } from '@/domain/auth/ports/mailer.port'
+
+// Writes each mail to the log instead of sending it: enough to develop against, and nothing to sign up for. A
+// project that sends real mail gives the Mailer port another adapter; see .prumo/email/.
+export class LogMailer implements Mailer {
+  constructor(private readonly write: (line: string) => void) {}
+
+  async send(mail: Mail): Promise<void> {
+    this.write(`[mail] to ${mail.to}: ${mail.subject}\n${mail.text}`)
+  }
+}

package/templates/api/src/infra/http/app.ts

@@ -14,9 +14,11 @@ import {
 import type { DependencyContainer } from 'tsyringe'
 import { ENV, type Env } from '@/infra/config/env'
 import { authController } from '@/infra/http/controllers/auth.controller'
+import { authEmailController } from '@/infra/http/controllers/auth-email.controller' // prumo:email
 import { healthController } from '@/infra/http/controllers/health.controller'
 import { mcpController } from '@/infra/http/controllers/mcp.controller' // prumo:mcp
 import { oauthController } from '@/infra/http/controllers/oauth.controller' // prumo:mcp
+import { socialController } from '@/infra/http/controllers/social.controller' // prumo:social
 import { usersController } from '@/infra/http/controllers/users.controller'
 import { registerErrorHandler } from '@/infra/http/errors/error-handler'
 import { registerAuthHook } from '@/infra/http/hooks/auth.hook'
@@ -98,6 +100,8 @@ export async function buildApp(container: DependencyContainer): Promise<FastifyI
   registerAuthHook(app)
 
   await app.register(authController, { prefix: '/api/auth' })
+  await app.register(authEmailController, { prefix: '/api/auth' }) // prumo:email
+  await app.register(socialController, { prefix: '/api/auth/social' }) // prumo:social
   await app.register(healthController, { prefix: '/api/health' })
   await app.register(usersController, { prefix: '/api/v1/users' })
   // prumo:mcp

package/templates/api/src/infra/http/controllers/auth-email.controller.ts

@@ -0,0 +1,73 @@
+import type { FastifyInstance } from 'fastify'
+import type { ZodTypeProvider } from 'fastify-type-provider-zod'
+import { emailRequestSchema } from '@/domain/auth/dto/email-request.dto'
+import { resetPasswordSchema } from '@/domain/auth/dto/reset-password.dto'
+import { tokensResponseSchema } from '@/domain/auth/dto/tokens-response.dto'
+import { verifyEmailSchema } from '@/domain/auth/dto/verify-email.dto'
+import { RequestEmailVerificationUseCase } from '@/domain/auth/use-cases/request-email-verification.use-case'
+import { RequestPasswordResetUseCase } from '@/domain/auth/use-cases/request-password-reset.use-case'
+import { ResetPasswordUseCase } from '@/domain/auth/use-cases/reset-password.use-case'
+import { VerifyEmailUseCase } from '@/domain/auth/use-cases/verify-email.use-case'
+import { ENV, type Env } from '@/infra/config/env'
+import { ATTEMPTS } from '@/infra/http/controllers/auth.controller'
+import { sessionDelivery } from '@/infra/http/session-delivery'
+
+// Every route answers alike whether or not the email has an account: none of them can be used to find out.
+export async function authEmailController(fastify: FastifyInstance): Promise<void> {
+  const app = fastify.withTypeProvider<ZodTypeProvider>()
+  const { deliver } = sessionDelivery(app.container.resolve<Env>(ENV))
+
+  app.post(
+    '/email/verification',
+    { config: { public: true, ...ATTEMPTS }, schema: { tags: ['auth'], body: emailRequestSchema } },
+    async (request, reply) => {
+      await app.container.resolve(RequestEmailVerificationUseCase).execute(request.body.email)
+
+      return reply.code(204).send()
+    },
+  )
+
+  app.post(
+    '/email/verify',
+    {
+      config: { public: true, ...ATTEMPTS },
+      schema: { tags: ['auth'], body: verifyEmailSchema, response: { 200: tokensResponseSchema } },
+    },
+    async (request, reply) =>
+      deliver(
+        request,
+        reply,
+        await app.container.resolve(VerifyEmailUseCase).execute(request.body),
+        200,
+      ),
+  )
+
+  app.post(
+    '/password/forgot',
+    { config: { public: true, ...ATTEMPTS }, schema: { tags: ['auth'], body: emailRequestSchema } },
+    async (request, reply) => {
+      await app.container.resolve(RequestPasswordResetUseCase).execute(request.body.email)
+
+      return reply.code(204).send()
+    },
+  )
+
+  app.post(
+    '/password/reset',
+    {
+      config: { public: true, ...ATTEMPTS },
+      schema: {
+        tags: ['auth'],
+        body: resetPasswordSchema,
+        response: { 200: tokensResponseSchema },
+      },
+    },
+    async (request, reply) =>
+      deliver(
+        request,
+        reply,
+        await app.container.resolve(ResetPasswordUseCase).execute(request.body),
+        200,
+      ),
+  )
+}

package/templates/api/src/infra/http/controllers/auth.controller.ts

@@ -1,95 +1,51 @@
-import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import type { FastifyInstance } from 'fastify'
 import type { ZodTypeProvider } from 'fastify-type-provider-zod'
+import { z } from 'zod'
 import { refreshSchema } from '@/domain/auth/dto/refresh.dto'
 import { sessionResponseSchema } from '@/domain/auth/dto/session-response.dto'
 import { signInSchema } from '@/domain/auth/dto/sign-in.dto'
 import { signUpSchema } from '@/domain/auth/dto/sign-up.dto'
-import { type TokensResponseDto, tokensResponseSchema } from '@/domain/auth/dto/tokens-response.dto'
+import { tokensResponseSchema } from '@/domain/auth/dto/tokens-response.dto'
 import { InvalidSessionError } from '@/domain/auth/errors/invalid-session.error'
 import { FindUserUseCase } from '@/domain/auth/use-cases/find-user.use-case'
 import { RefreshSessionUseCase } from '@/domain/auth/use-cases/refresh-session.use-case'
 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 } from '@/domain/auth/use-cases/start-session.use-case'
 import { ENV, type Env } from '@/infra/config/env'
-import { ACCESS_COOKIE, currentSession, currentUser } from '@/infra/http/hooks/auth.hook'
-
-const REFRESH_COOKIE = 'refresh_token'
-
-// The refresh cookie travels only to the one route that reads it, never with an ordinary request.
-const REFRESH_PATH = '/api/auth/refresh'
+import { currentSession, currentUser } from '@/infra/http/hooks/auth.hook'
+import { REFRESH_COOKIE, sessionDelivery, wantsBearer } from '@/infra/http/session-delivery'
 
 // Repeated guessing is slowed down per address; a refresh happens every quarter hour per tab, so it gets more room.
-const ATTEMPTS = { rateLimit: { max: 10, timeWindow: '1 minute' } }
+export const ATTEMPTS = { rateLimit: { max: 10, timeWindow: '1 minute' } }
 const REFRESHES = { rateLimit: { max: 60, timeWindow: '1 minute' } }
 
-// A native client asks for its tokens in the body. The web never does: a token JavaScript can read is a token an
-// injected script can take.
-function wantsBearer(request: FastifyRequest): boolean {
-  return request.headers['x-auth-transport'] === 'bearer'
-}
-
-function asBody(tokens: SessionTokens): TokensResponseDto {
-  return {
-    accessToken: tokens.accessToken.token,
-    refreshToken: tokens.refreshToken,
-    expiresIn: Math.round((tokens.accessToken.expiresAt.getTime() - Date.now()) / 1000),
-  }
-}
+const verificationRequiredSchema = z.object({ verificationRequired: z.literal(true) })
 
 export async function authController(fastify: FastifyInstance): Promise<void> {
   const app = fastify.withTypeProvider<ZodTypeProvider>()
-  const env = app.container.resolve<Env>(ENV)
-  const secure = env.API_URL.startsWith('https://')
-  const cookie = { httpOnly: true, sameSite: 'lax', secure } as const
-
-  function setCookies(reply: FastifyReply, tokens: SessionTokens): void {
-    reply.setCookie(ACCESS_COOKIE, tokens.accessToken.token, {
-      ...cookie,
-      path: '/',
-      expires: tokens.accessToken.expiresAt,
-    })
-    reply.setCookie(REFRESH_COOKIE, tokens.refreshToken, {
-      ...cookie,
-      path: REFRESH_PATH,
-      expires: tokens.refreshExpiresAt,
-    })
-  }
-
-  function clearCookies(reply: FastifyReply): void {
-    reply.clearCookie(ACCESS_COOKIE, { ...cookie, path: '/' })
-    reply.clearCookie(REFRESH_COOKIE, { ...cookie, path: REFRESH_PATH })
-  }
-
-  // The web gets cookies and an empty body; a native client gets the tokens and no cookie.
-  function deliver(
-    request: FastifyRequest,
-    reply: FastifyReply,
-    tokens: SessionTokens,
-    status: number,
-  ) {
-    if (wantsBearer(request)) {
-      return reply.code(status).send(asBody(tokens))
-    }
-
-    setCookies(reply, tokens)
-    return reply.code(status === 201 ? 201 : 204).send()
-  }
+  const { deliver, clearCookies } = sessionDelivery(app.container.resolve<Env>(ENV))
 
   app.post(
     '/sign-up',
     {
       config: { public: true, ...ATTEMPTS },
-      schema: { tags: ['auth'], body: signUpSchema, response: { 201: tokensResponseSchema } },
+      schema: {
+        tags: ['auth'],
+        body: signUpSchema,
+        response: { 201: z.union([tokensResponseSchema, verificationRequiredSchema]) },
+      },
+    },
+    async (request, reply) => {
+      const tokens = await app.container.resolve(SignUpUseCase).execute(request.body)
+
+      // No session until the address is confirmed: the client asks for the code next.
+      if (tokens === null) {
+        return reply.code(201).send({ verificationRequired: true })
+      }
+
+      return deliver(request, reply, tokens, 201)
     },
-    async (request, reply) =>
-      deliver(
-        request,
-        reply,
-        await app.container.resolve(SignUpUseCase).execute(request.body),
-        201,
-      ),
   )
 
   app.post(

package/templates/api/src/infra/http/controllers/mcp.controller.ts

@@ -4,6 +4,7 @@ import { ACCESS_TOKENS, type AccessTokens } from '@/domain/auth/ports/access-tok
 import { ENV, type Env } from '@/infra/config/env'
 import { HttpError } from '@/infra/http/errors/http-error'
 import { sendFetchResponse, toFetchRequest } from '@/infra/http/fetch-bridge'
+import { missingScopes, SCOPES } from '@/infra/mcp/mcp.scopes'
 import { createMcpServerHandler, mcpResource, mcpResourceMetadataUrl } from '@/infra/mcp/mcp.server'
 
 // The route answers an OAuth access token issued for it, never a session cookie or a first-party token: the
@@ -24,18 +25,31 @@ export async function mcpController(fastify: FastifyInstance): Promise<void> {
       const claims = token === undefined ? null : await tokens.verify(token, resource)
 
       if (token === undefined || claims === null || claims.clientId === undefined) {
-        // RFC 9728: the 401 names the document that says where to obtain a token.
+        // RFC 9728: the 401 names the document that says where to obtain a token, and the scopes worth asking for.
         reply.header(
           'www-authenticate',
-          `Bearer resource_metadata="${mcpResourceMetadataUrl(env)}"${token === undefined ? '' : ', error="invalid_token"'}`,
+          `Bearer resource_metadata="${mcpResourceMetadataUrl(env)}", scope="${Object.keys(SCOPES).join(' ')}"${token === undefined ? '' : ', error="invalid_token"'}`,
         )
         throw new HttpError(401, 'Unauthorized')
       }
 
+      const scopes = (claims.scope ?? '').split(' ').filter(Boolean)
+      const missing = missingScopes(request.body, scopes)
+
+      // Checked before the server runs the call: a tool the user did not grant is refused with the scopes it needs,
+      // so the client can ask the user for them and come back.
+      if (missing.length > 0) {
+        reply.header(
+          'www-authenticate',
+          `Bearer error="insufficient_scope", scope="${missing.join(' ')}", resource_metadata="${mcpResourceMetadataUrl(env)}"`,
+        )
+        throw new HttpError(403, `This token lacks ${missing.join(' ')}`)
+      }
+
       const authInfo: AuthInfo = {
         token,
         clientId: claims.clientId,
-        scopes: [],
+        scopes,
         extra: { userId: claims.userId },
       }
 

package/templates/api/src/infra/http/controllers/oauth.controller.ts

@@ -18,6 +18,7 @@ import { FindAuthorizationUseCase } from '@/domain/oauth/use-cases/find-authoriz
 import { StartAuthorizationUseCase } from '@/domain/oauth/use-cases/start-authorization.use-case'
 import { ENV, type Env } from '@/infra/config/env'
 import { currentUser } from '@/infra/http/hooks/auth.hook'
+import { SCOPES } from '@/infra/mcp/mcp.scopes'
 import { mcpResource } from '@/infra/mcp/mcp.server'
 
 const PUBLIC = { public: true, rateLimit: { max: 30, timeWindow: '1 minute' } }
@@ -54,6 +55,7 @@ function tokenResponse(tokens: SessionTokens) {
     token_type: 'Bearer',
     expires_in: Math.round((tokens.accessToken.expiresAt.getTime() - Date.now()) / 1000),
     refresh_token: tokens.refreshToken,
+    scope: tokens.scope ?? '',
   }
 }
 
@@ -72,10 +74,12 @@ export async function oauthController(fastify: FastifyInstance): Promise<void> {
     (_request, body, done) => done(null, Object.fromEntries(new URLSearchParams(body as string))),
   )
 
+  const scopesSupported = Object.keys(SCOPES)
   const resourceMetadata = {
     resource,
     authorization_servers: [issuer],
     bearer_methods_supported: ['header'],
+    scopes_supported: scopesSupported,
   }
 
   // At the path of the resource first, then at the root: the two places an MCP client looks.
@@ -98,6 +102,7 @@ export async function oauthController(fastify: FastifyInstance): Promise<void> {
       code_challenge_methods_supported: ['S256'],
       token_endpoint_auth_methods_supported: ['none'],
       client_id_metadata_document_supported: true,
+      scopes_supported: scopesSupported,
       authorization_response_iss_parameter_supported: true,
     }),
   )
@@ -118,8 +123,10 @@ export async function oauthController(fastify: FastifyInstance): Promise<void> {
             codeChallengeMethod: query.code_challenge_method,
             clientState: query.state ?? null,
             resource: query.resource,
+            scope: query.scope,
           },
           resource,
+          scopesSupported,
         )
 
         // Signing in, if needed, and the consent itself happen on the web app.
@@ -162,6 +169,9 @@ export async function oauthController(fastify: FastifyInstance): Promise<void> {
         clientHost: new URL(authorization.clientId).host,
         redirectHost: redirect.host,
         redirectsToThisDevice: LOOPBACK.has(redirect.hostname),
+        scopes: authorization.scope
+          .split(' ')
+          .map((scope) => ({ scope, description: SCOPES[scope] ?? scope })),
       }
     },
   )

package/templates/api/src/infra/http/controllers/social.controller.ts

@@ -0,0 +1,192 @@
+import type { FastifyInstance } from 'fastify'
+import type { ZodTypeProvider } from 'fastify-type-provider-zod'
+import { z } from 'zod'
+import { tokensResponseSchema } from '@/domain/auth/dto/tokens-response.dto'
+import type { SocialClient } from '@/domain/auth/entities/social-sign-in.entity'
+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 { StartSocialSignInUseCase } from '@/domain/auth/use-cases/start-social-sign-in.use-case'
+import { DomainError } from '@/domain/shared/errors/domain-error'
+import { ENV, type Env } from '@/infra/config/env'
+import { ATTEMPTS } from '@/infra/http/controllers/auth.controller'
+import { HttpError } from '@/infra/http/errors/http-error'
+import { sessionDelivery } from '@/infra/http/session-delivery'
+
+const BROWSER_COOKIE = 'social_sign_in'
+const BROWSER_COOKIE_MAX_AGE_S = 10 * 60
+
+const PROVIDERS = [
+  'google', // prumo:google
+  'apple', // prumo:apple
+] as const
+
+const providerParams = z.object({ provider: z.enum(PROVIDERS) })
+
+// Only a path on the web app: an absolute URL here would turn sign-in into an open redirect.
+function safePath(path: string | undefined): string {
+  return path?.startsWith('/') && !path.startsWith('//') ? path : '/'
+}
+
+// Apple sends the name it shares once, as JSON beside the code.
+function appleName(user: string | undefined): string | null {
+  try {
+    const name = (JSON.parse(user ?? '') as { name?: { firstName?: string; lastName?: string } })
+      .name
+    const full = [name?.firstName, name?.lastName].filter(Boolean).join(' ')
+
+    return full === '' ? null : full
+  } catch {
+    return null
+  }
+}
+
+export async function socialController(fastify: FastifyInstance): Promise<void> {
+  const app = fastify.withTypeProvider<ZodTypeProvider>()
+  const env = app.container.resolve<Env>(ENV)
+  const { deliver, setCookies } = sessionDelivery(env)
+  const cookie = {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: env.API_URL.startsWith('https://'),
+    path: '/api/auth/social',
+  } as const
+
+  const back = (client: SocialClient, query: Record<string, string>) =>
+    client === 'mobile'
+      ? `${env.MOBILE_APP_SCHEME}://social?${new URLSearchParams(query)}`
+      : `${env.WEB_ORIGIN}/sign-in?${new URLSearchParams(query)}`
+
+  // Apple's answer is a form.
+  app.addContentTypeParser(
+    'application/x-www-form-urlencoded',
+    { parseAs: 'string' },
+    (_request, body, done) => done(null, Object.fromEntries(new URLSearchParams(body as string))),
+  )
+
+  app.get(
+    '/:provider',
+    {
+      config: { public: true, ...ATTEMPTS },
+      schema: {
+        tags: ['auth'],
+        params: providerParams,
+        querystring: z.object({
+          client: z.enum(['web', 'mobile']).default('web'),
+          returnTo: z.string().max(512).optional(),
+        }),
+      },
+    },
+    async (request, reply) => {
+      const { client, returnTo } = request.query
+
+      if (client === 'mobile' && env.MOBILE_APP_SCHEME === undefined) {
+        throw new HttpError(
+          422,
+          'MOBILE_APP_SCHEME is not set, so a mobile app cannot be sent back',
+        )
+      }
+
+      const started = await app.container.resolve(StartSocialSignInUseCase).execute({
+        provider: request.params.provider,
+        client,
+        returnTo: safePath(returnTo),
+      })
+
+      // The client rides beside the token, so an error found before the flow is read still goes to the right place.
+      reply.setCookie(BROWSER_COOKIE, `${client}~${started.browserToken}`, {
+        ...cookie,
+        maxAge: BROWSER_COOKIE_MAX_AGE_S,
+      })
+
+      return reply.redirect(started.url)
+    },
+  )
+
+  // A cross-site POST carries no SameSite=Lax cookie, and a top-level GET does: Apple's form is turned into a
+  // redirect to the same address, so the browser's token comes with it.
+  app.post(
+    '/:provider/callback',
+    { config: { public: true }, schema: { hide: true, params: providerParams } },
+    async (request, reply) => {
+      const form = new URLSearchParams(request.body as Record<string, string>)
+
+      return reply
+        .code(303)
+        .redirect(`${env.API_URL}/api/auth/social/${request.params.provider}/callback?${form}`)
+    },
+  )
+
+  app.get(
+    '/:provider/callback',
+    {
+      config: { public: true },
+      schema: {
+        hide: true,
+        params: providerParams,
+        querystring: z.object({
+          state: z.string().optional(),
+          code: z.string().optional(),
+          error: z.string().optional(),
+          user: z.string().optional(),
+        }),
+      },
+    },
+    async (request, reply) => {
+      const [client, browserToken] = (request.cookies[BROWSER_COOKIE] ?? 'web~').split('~') as [
+        SocialClient,
+        string,
+      ]
+      const { state, code, error } = request.query
+
+      reply.clearCookie(BROWSER_COOKIE, cookie)
+
+      if (error !== undefined || state === undefined || code === undefined) {
+        return reply.redirect(back(client, { error: 'social_sign_in_failed' }))
+      }
+
+      try {
+        const outcome = await app.container.resolve(CompleteSocialSignInUseCase).execute({
+          provider: request.params.provider,
+          state,
+          browserToken: browserToken === '' ? undefined : browserToken,
+          callbackUrl: new URL(request.url, env.API_URL),
+          name: appleName(request.query.user),
+        })
+
+        if (outcome.client === 'mobile') {
+          return reply.redirect(back('mobile', { code: outcome.code }))
+        }
+
+        setCookies(reply, outcome.tokens)
+
+        return reply.redirect(`${env.WEB_ORIGIN}${outcome.returnTo}`)
+      } catch (caught) {
+        if (caught instanceof DomainError) {
+          return reply.redirect(back(client, { error: caught.code ?? 'social_sign_in_failed' }))
+        }
+
+        throw caught
+      }
+    },
+  )
+
+  // The mobile app trades the code it was sent back with for its tokens, once.
+  app.post(
+    '/exchange',
+    {
+      config: { public: true, ...ATTEMPTS },
+      schema: {
+        tags: ['auth'],
+        body: z.strictObject({ code: z.string().min(1).max(512) }),
+        response: { 200: tokensResponseSchema },
+      },
+    },
+    async (request, reply) =>
+      deliver(
+        request,
+        reply,
+        await app.container.resolve(ExchangeSocialCodeUseCase).execute(request.body.code),
+        200,
+      ),
+  )
+}

package/templates/api/src/infra/http/errors/error-handler.ts

@@ -11,6 +11,7 @@ type ProblemDocument = {
   detail: string
   instance: string
   requestId: string
+  code?: string
   errors?: FieldErrors
 }
 
@@ -104,9 +105,12 @@ export function registerErrorHandler(app: FastifyInstance): void {
       request.log.error(error)
     }
 
+    const code = error instanceof DomainError ? error.code : undefined
+
     return send(request, reply, {
       status,
       detail: detailOf(error, status, errors),
+      ...(code === undefined ? {} : { code }),
       ...(errors === undefined ? {} : { errors }),
     })
   })