@stjoseph/prumo 0.2.0 → 0.4.0

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
 }
 
@@ -31,6 +32,7 @@ const TITLES: Record<number, string> = {
   413: 'Payload Too Large',
   415: 'Unsupported Media Type',
   422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
   500: 'Internal Server Error',
   503: 'Service Unavailable',
 }
@@ -103,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 }),
     })
   })

package/templates/api/src/infra/http/fastify.d.ts

@@ -1,5 +1,4 @@
 import type { DependencyContainer } from 'tsyringe'
-import type { AuthSession, AuthUser } from '@/infra/auth/auth.factory'
 
 declare module 'fastify' {
   interface FastifyInstance {
@@ -11,7 +10,7 @@ declare module 'fastify' {
   }
 
   interface FastifyRequest {
-    user?: AuthUser
-    session?: NonNullable<AuthSession>['session']
+    user?: { id: string }
+    sessionId?: string
   }
 }

package/templates/api/src/infra/http/fetch-bridge.ts

@@ -1,6 +1,19 @@
-import { fromNodeHeaders } from 'better-auth/node'
 import type { FastifyReply, FastifyRequest } from 'fastify'
 
+function headersOf(request: FastifyRequest): Headers {
+  const headers = new Headers()
+
+  for (const [name, value] of Object.entries(request.headers)) {
+    for (const each of [value].flat()) {
+      if (each !== undefined) {
+        headers.append(name, each)
+      }
+    }
+  }
+
+  return headers
+}
+
 function bodyOf(body: unknown): string | undefined {
   if (body === undefined) {
     return undefined
@@ -9,15 +22,14 @@ function bodyOf(body: unknown): string | undefined {
   return typeof body === 'string' ? body : JSON.stringify(body)
 }
 
-// Better Auth and the MCP handler answer Fetch requests. Fastify has already parsed a JSON body, so the
-// request is rebuilt rather than handed over raw, as Better Auth's Fastify guide does; a body kept as a
-// string, such as a form, passes unchanged.
+// The MCP handler answers Fetch requests. Fastify has already parsed a JSON body, so the request is rebuilt
+// rather than handed over raw; a body kept as a string, such as a form, passes unchanged.
 export function toFetchRequest(request: FastifyRequest): Request {
   const body = bodyOf(request.body)
 
   return new Request(new URL(request.url, `${request.protocol}://${request.host}`), {
     method: request.method,
-    headers: fromNodeHeaders(request.headers),
+    headers: headersOf(request),
     ...(body === undefined ? {} : { body }),
   })
 }

package/templates/api/src/infra/http/hooks/auth.hook.ts

@@ -1,10 +1,18 @@
-import { fromNodeHeaders } from 'better-auth/node'
 import type { FastifyInstance, FastifyRequest } from 'fastify'
-import { AUTH, type Auth, type AuthUser } from '@/infra/auth/auth.factory'
+import { ACCESS_TOKENS, type AccessTokens } from '@/domain/auth/ports/access-tokens.port'
 import { HttpError } from '@/infra/http/errors/http-error'
 
+export const ACCESS_COOKIE = 'access_token'
+
+// The web sends a cookie the browser keeps; a native app and an MCP client send a bearer token.
+function tokenOf(request: FastifyRequest): string | undefined {
+  const bearer = /^Bearer (.+)$/i.exec(request.headers.authorization ?? '')?.[1]
+
+  return bearer ?? request.cookies[ACCESS_COOKIE]
+}
+
 export function registerAuthHook(app: FastifyInstance): void {
-  const auth = app.container.resolve<Auth>(AUTH)
+  const tokens = app.container.resolve<AccessTokens>(ACCESS_TOKENS)
 
   app.addHook('preHandler', async (request) => {
     // An unknown route answers 404, not 401: there is nothing there to protect.
@@ -12,21 +20,30 @@ export function registerAuthHook(app: FastifyInstance): void {
       return
     }
 
-    const session = await auth.api.getSession({ headers: fromNodeHeaders(request.headers) })
+    const token = tokenOf(request)
+    const claims = token === undefined ? null : await tokens.verify(token)
 
-    request.user = session?.user
-    request.session = session?.session
+    request.user = claims === null ? undefined : { id: claims.userId }
+    request.sessionId = claims?.sessionId
 
-    if (request.routeOptions.config.public !== true && session === null) {
+    if (request.routeOptions.config.public !== true && claims === null) {
       throw new HttpError(401, 'Unauthorized')
     }
   })
 }
 
-export function currentUser(request: FastifyRequest): AuthUser {
+export function currentUser(request: FastifyRequest): { id: string } {
   if (request.user === undefined) {
     throw new HttpError(401, 'Unauthorized')
   }
 
   return request.user
 }
+
+export function currentSession(request: FastifyRequest): string {
+  if (request.sessionId === undefined) {
+    throw new HttpError(401, 'Unauthorized')
+  }
+
+  return request.sessionId
+}

package/templates/api/src/infra/http/hooks/origin.hook.ts

@@ -0,0 +1,22 @@
+import type { FastifyInstance } from 'fastify'
+import { HttpError } from '@/infra/http/errors/http-error'
+
+const SAFE = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+// A cookie is sent by the browser whoever wrote the page, so a request that changes something and leans on one must
+// come from the web app. Without a cookie there is nothing for another site to borrow: a native app and an MCP
+// client send a bearer, and pass.
+export function registerOriginCheck(app: FastifyInstance, webOrigin: string): void {
+  app.addHook('onRequest', async (request) => {
+    const leansOnCookie =
+      request.headers.cookie !== undefined && request.headers.authorization === undefined
+
+    if (SAFE.has(request.method) || !leansOnCookie) {
+      return
+    }
+
+    if (request.headers.origin !== webOrigin) {
+      throw new HttpError(403, 'Cross-origin request refused')
+    }
+  })
+}

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

@@ -1,8 +1,6 @@
 // tsyringe reads decorator metadata as each class is loaded, so this must come before any other import.
 import 'reflect-metadata'
 import { MikroORM } from '@mikro-orm/postgresql'
-import type { Pool } from 'pg'
-import { AUTH, type Auth } from '@/infra/auth/auth.factory'
 import { loadEnv } from '@/infra/config/env'
 import { createOrmConfig } from '@/infra/database/mikroorm/mikro-orm.factory'
 import { createContainer } from '@/infra/di'
@@ -18,10 +16,9 @@ async function main(): Promise<void> {
   const container = createContainer({ env, orm })
   const app = await buildApp(container)
 
-  // Handling the signals takes away Node's default exit, so every open pool must close for the process to end.
+  // Handling the signals takes away Node's default exit, so the pool must close for the process to end.
   app.addHook('onClose', async () => {
     await orm.close()
-    await (container.resolve<Auth>(AUTH).options.database as Pool).end()
   })
 
   for (const signal of ['SIGINT', 'SIGTERM'] as const) {

package/templates/api/src/infra/http/session-delivery.ts

@@ -0,0 +1,69 @@
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import type { TokensResponseDto } from '@/domain/auth/dto/tokens-response.dto'
+import type { SessionTokens } from '@/domain/auth/use-cases/start-session.use-case'
+import type { Env } from '@/infra/config/env'
+import { ACCESS_COOKIE } from '@/infra/http/hooks/auth.hook'
+
+export 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'
+
+// 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.
+export 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),
+  }
+}
+
+// How a started session reaches the client, wherever it was started: sign-in, a confirmed email, a provider.
+export function sessionDelivery(env: Pick<Env, 'API_URL'>) {
+  const cookie = {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: env.API_URL.startsWith('https://'),
+  } as const
+
+  function clearCookies(reply: FastifyReply): void {
+    reply.clearCookie(ACCESS_COOKIE, { ...cookie, path: '/' })
+    reply.clearCookie(REFRESH_COOKIE, { ...cookie, path: REFRESH_PATH })
+  }
+
+  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,
+    })
+  }
+
+  // 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: 200 | 201,
+  ) {
+    if (wantsBearer(request)) {
+      return reply.code(status).send(asBody(tokens))
+    }
+
+    setCookies(reply, tokens)
+
+    return reply.code(status === 201 ? 201 : 204).send()
+  }
+
+  return { deliver, setCookies, clearCookies }
+}

package/templates/api/src/infra/mcp/mcp.scopes.ts

@@ -0,0 +1,27 @@
+import { USER_TOOL_SCOPES } from './tools/users.tool'
+
+// Every scope this server offers, as the consent page words it. A module adds its read and write here, with its
+// tools' scopes below.
+export const SCOPES: Record<string, string> = {
+  'profile:read': 'Read your profile',
+  'profile:write': 'Change your display name, language and timezone',
+}
+
+export const TOOL_SCOPES: Record<string, string> = { ...USER_TOOL_SCOPES }
+
+// The scopes a batch of JSON-RPC messages needs and the token lacks, all of them at once: MCP asks for one
+// challenge per operation, not one per retry.
+export function missingScopes(messages: unknown, granted: readonly string[]): string[] {
+  const needed = [messages]
+    .flat()
+    .flatMap((message) => {
+      const call = message as { method?: unknown; params?: { name?: unknown } } | null
+
+      return call?.method === 'tools/call' && typeof call.params?.name === 'string'
+        ? [TOOL_SCOPES[call.params.name]]
+        : []
+    })
+    .filter((scope): scope is string => scope !== undefined)
+
+  return [...new Set(needed)].filter((scope) => !granted.includes(scope))
+}

package/templates/api/src/infra/mcp/mcp.server.ts

@@ -1,7 +1,17 @@
 import { createMcpHandler, type McpHttpHandler, McpServer } from '@modelcontextprotocol/server'
 import type { DependencyContainer } from 'tsyringe'
+import type { Env } from '@/infra/config/env'
 import { registerUserTools } from './tools/users.tool'
 
+// The protected resource MCP clients ask a token for; its access tokens carry it as their audience.
+export function mcpResource(env: Pick<Env, 'API_URL'>): string {
+  return `${env.API_URL}/api/mcp`
+}
+
+export function mcpResourceMetadataUrl(env: Pick<Env, 'API_URL'>): string {
+  return `${env.API_URL}/.well-known/oauth-protected-resource/api/mcp`
+}
+
 // One server per request: the protocol is stateless, and each instance knows only its caller.
 export function createMcpServerHandler(container: DependencyContainer): McpHttpHandler {
   return createMcpHandler(

package/templates/api/src/infra/mcp/tools/users.tool.ts

@@ -16,6 +16,12 @@ function asResult(profile: Profile) {
   }
 }
 
+// The scope each tool needs: reading a module's data is `<module>:read`, changing it `<module>:write`.
+export const USER_TOOL_SCOPES = {
+  get_profile: 'profile:read',
+  update_profile: 'profile:write',
+} as const
+
 export function registerUserTools(
   server: McpServer,
   container: DependencyContainer,

package/templates/api/src/infra/oauth/crypto-authorization-codes.adapter.ts

@@ -0,0 +1,21 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import type { AuthorizationCodes } from '@/domain/oauth/ports/authorization-codes.port'
+
+const sha256 = (value: string) => createHash('sha256').update(value).digest('base64url')
+
+export class CryptoAuthorizationCodes implements AuthorizationCodes {
+  create(): string {
+    return randomBytes(32).toString('base64url')
+  }
+
+  digest(code: string): string {
+    return sha256(code)
+  }
+
+  matchesChallenge(verifier: string, challenge: string): boolean {
+    const expected = Buffer.from(sha256(verifier))
+    const given = Buffer.from(challenge)
+
+    return expected.length === given.length && timingSafeEqual(expected, given)
+  }
+}