@stjoseph/prumo 0.1.1 → 0.3.0

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

@@ -1,40 +1,45 @@
-import { requireMcpAuth } from '@better-auth/mcp'
 import type { AuthInfo } from '@modelcontextprotocol/server'
 import type { FastifyInstance } from 'fastify'
-import { AUTH, type Auth, mcpResource } from '@/infra/auth/auth.factory'
+import { ACCESS_TOKENS, type AccessTokens } from '@/domain/auth/ports/access-tokens.port'
 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 { createMcpServerHandler } from '@/infra/mcp/mcp.server'
+import { createMcpServerHandler, mcpResource, mcpResourceMetadataUrl } from '@/infra/mcp/mcp.server'
 
-type AccessTokenClaims = Parameters<Parameters<typeof requireMcpAuth>[1]>[1]
-
-function authInfoOf(request: Request, claims: AccessTokenClaims): AuthInfo {
-  const scope = typeof claims.scope === 'string' ? claims.scope : ''
-  const clientId = claims.azp ?? claims.client_id
-
-  return {
-    token: request.headers.get('authorization')?.replace(/^\w+\s+/, '') ?? '',
-    clientId: typeof clientId === 'string' ? clientId : '',
-    scopes: scope.split(' ').filter(Boolean),
-    ...(claims.exp === undefined ? {} : { expiresAt: claims.exp }),
-    extra: { userId: claims.sub },
-  }
-}
-
-// The route answers a bearer access token, never a session cookie, so the session hook stands aside.
+// The route answers an OAuth access token issued for it, never a session cookie or a first-party token: the
+// audience decides, so the session hook stands aside.
 export async function mcpController(fastify: FastifyInstance): Promise<void> {
-  const auth = fastify.container.resolve<Auth>(AUTH)
+  const tokens = fastify.container.resolve<AccessTokens>(ACCESS_TOKENS)
   const env = fastify.container.resolve<Env>(ENV)
+  const resource = mcpResource(env)
   const mcp = createMcpServerHandler(fastify.container)
-  const handle = requireMcpAuth(
-    auth,
-    (request, claims) => mcp.fetch(request, { authInfo: authInfoOf(request, claims) }),
-    { resource: mcpResource(env) },
-  )
 
   fastify.addHook('onClose', () => mcp.close())
 
-  fastify.post('/', { config: { public: true }, schema: { hide: true } }, async (request, reply) =>
-    sendFetchResponse(reply, await handle(toFetchRequest(request))),
+  fastify.post(
+    '/',
+    { config: { public: true }, schema: { hide: true } },
+    async (request, reply) => {
+      const token = /^Bearer (.+)$/i.exec(request.headers.authorization ?? '')?.[1]
+      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.
+        reply.header(
+          'www-authenticate',
+          `Bearer resource_metadata="${mcpResourceMetadataUrl(env)}"${token === undefined ? '' : ', error="invalid_token"'}`,
+        )
+        throw new HttpError(401, 'Unauthorized')
+      }
+
+      const authInfo: AuthInfo = {
+        token,
+        clientId: claims.clientId,
+        scopes: [],
+        extra: { userId: claims.userId },
+      }
+
+      return sendFetchResponse(reply, await mcp.fetch(toFetchRequest(request), { authInfo }))
+    },
   )
 }

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

@@ -0,0 +1,257 @@
+import type { FastifyInstance, FastifyReply } from 'fastify'
+import type { ZodTypeProvider } from 'fastify-type-provider-zod'
+import { z } from 'zod'
+import { InvalidSessionError } from '@/domain/auth/errors/invalid-session.error'
+import { SupersededTokenError } from '@/domain/auth/errors/superseded-token.error'
+import { RefreshSessionUseCase } from '@/domain/auth/use-cases/refresh-session.use-case'
+import type { SessionTokens } from '@/domain/auth/use-cases/start-session.use-case'
+import {
+  authorizationDecisionSchema,
+  authorizationRedirectSchema,
+} from '@/domain/oauth/dto/authorization-decision.dto'
+import { authorizationViewSchema } from '@/domain/oauth/dto/authorization-view.dto'
+import { AuthorizationRequestError } from '@/domain/oauth/errors/authorization-request.error'
+import { InvalidGrantError } from '@/domain/oauth/errors/invalid-grant.error'
+import { DecideAuthorizationUseCase } from '@/domain/oauth/use-cases/decide-authorization.use-case'
+import { ExchangeCodeUseCase } from '@/domain/oauth/use-cases/exchange-code.use-case'
+import { FindAuthorizationUseCase } from '@/domain/oauth/use-cases/find-authorization.use-case'
+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 { mcpResource } from '@/infra/mcp/mcp.server'
+
+const PUBLIC = { public: true, rateLimit: { max: 30, timeWindow: '1 minute' } }
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+const authorizeQuerySchema = z.object({
+  response_type: z.string().optional(),
+  client_id: z.string().max(2048),
+  redirect_uri: z.string().max(2048),
+  code_challenge: z.string().optional(),
+  code_challenge_method: z.string().optional(),
+  state: z.string().max(1024).optional(),
+  resource: z.string().optional(),
+  scope: z.string().optional(),
+})
+
+const idParamsSchema = z.object({ id: z.uuid() })
+
+function withParams(uri: string, params: Record<string, string | null | undefined>): string {
+  const url = new URL(uri)
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== null && value !== undefined) {
+      url.searchParams.set(key, value)
+    }
+  }
+
+  return url.toString()
+}
+
+function tokenResponse(tokens: SessionTokens) {
+  return {
+    access_token: tokens.accessToken.token,
+    token_type: 'Bearer',
+    expires_in: Math.round((tokens.accessToken.expiresAt.getTime() - Date.now()) / 1000),
+    refresh_token: tokens.refreshToken,
+  }
+}
+
+// MCP's authorization server, from discovery to the token: RFC 9728, RFC 8414, OAuth 2.1 with PKCE, RFC 8707 and
+// RFC 9207, with clients identified by their metadata document. The user signs in and consents on the web app.
+export async function oauthController(fastify: FastifyInstance): Promise<void> {
+  const app = fastify.withTypeProvider<ZodTypeProvider>()
+  const env = app.container.resolve<Env>(ENV)
+  const issuer = env.API_URL
+  const resource = mcpResource(env)
+
+  // The token endpoint takes a form, as OAuth writes it.
+  app.addContentTypeParser(
+    'application/x-www-form-urlencoded',
+    { parseAs: 'string' },
+    (_request, body, done) => done(null, Object.fromEntries(new URLSearchParams(body as string))),
+  )
+
+  const resourceMetadata = {
+    resource,
+    authorization_servers: [issuer],
+    bearer_methods_supported: ['header'],
+  }
+
+  // At the path of the resource first, then at the root: the two places an MCP client looks.
+  for (const url of [
+    '/.well-known/oauth-protected-resource/api/mcp',
+    '/.well-known/oauth-protected-resource',
+  ]) {
+    app.get(url, { config: { public: true }, schema: { hide: true } }, async () => resourceMetadata)
+  }
+
+  app.get(
+    '/.well-known/oauth-authorization-server',
+    { config: { public: true }, schema: { hide: true } },
+    async () => ({
+      issuer,
+      authorization_endpoint: `${issuer}/api/oauth/authorize`,
+      token_endpoint: `${issuer}/api/oauth/token`,
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['none'],
+      client_id_metadata_document_supported: true,
+      authorization_response_iss_parameter_supported: true,
+    }),
+  )
+
+  app.get(
+    '/api/oauth/authorize',
+    { config: PUBLIC, schema: { tags: ['oauth'], querystring: authorizeQuerySchema } },
+    async (request, reply) => {
+      const query = request.query
+
+      try {
+        const authorization = await app.container.resolve(StartAuthorizationUseCase).execute(
+          {
+            responseType: query.response_type,
+            clientId: query.client_id,
+            redirectUri: query.redirect_uri,
+            codeChallenge: query.code_challenge,
+            codeChallengeMethod: query.code_challenge_method,
+            clientState: query.state ?? null,
+            resource: query.resource,
+          },
+          resource,
+        )
+
+        // Signing in, if needed, and the consent itself happen on the web app.
+        return reply.redirect(`${env.WEB_ORIGIN}/consent?request=${authorization.id}`)
+      } catch (error) {
+        if (error instanceof AuthorizationRequestError) {
+          return reply.redirect(
+            withParams(query.redirect_uri, {
+              error: error.code,
+              error_description: error.message,
+              state: query.state,
+              iss: issuer,
+            }),
+          )
+        }
+
+        throw error
+      }
+    },
+  )
+
+  app.get(
+    '/api/oauth/authorizations/:id',
+    {
+      schema: {
+        tags: ['oauth'],
+        params: idParamsSchema,
+        response: { 200: authorizationViewSchema },
+      },
+    },
+    async (request) => {
+      const authorization = await app.container
+        .resolve(FindAuthorizationUseCase)
+        .execute(request.params.id)
+      const redirect = new URL(authorization.redirectUri)
+
+      return {
+        clientId: authorization.clientId,
+        clientName: authorization.clientName,
+        clientHost: new URL(authorization.clientId).host,
+        redirectHost: redirect.host,
+        redirectsToThisDevice: LOOPBACK.has(redirect.hostname),
+      }
+    },
+  )
+
+  app.post(
+    '/api/oauth/authorizations/:id/decision',
+    {
+      schema: {
+        tags: ['oauth'],
+        params: idParamsSchema,
+        body: authorizationDecisionSchema,
+        response: { 200: authorizationRedirectSchema },
+      },
+    },
+    async (request) => {
+      const { authorization, code } = await app.container
+        .resolve(DecideAuthorizationUseCase)
+        .execute(request.params.id, currentUser(request).id, request.body.accept)
+
+      return {
+        redirectTo: withParams(authorization.redirectUri, {
+          ...(code === null ? { error: 'access_denied' } : { code }),
+          state: authorization.clientState,
+          iss: issuer,
+        }),
+      }
+    },
+  )
+
+  // Errors here are OAuth's, not problem+json: an MCP client reads `error` and `error_description`.
+  app.post(
+    '/api/oauth/token',
+    { config: PUBLIC, schema: { tags: ['oauth'] } },
+    async (request, reply: FastifyReply) => {
+      const body = (request.body ?? {}) as Record<string, string | undefined>
+      const fail = (error: string, description: string) =>
+        reply.code(400).send({ error, error_description: description })
+
+      reply.header('cache-control', 'no-store')
+
+      if (body.resource !== undefined && body.resource !== resource) {
+        return fail('invalid_target', `resource must be ${resource}`)
+      }
+
+      try {
+        if (body.grant_type === 'authorization_code') {
+          const { code, client_id, redirect_uri, code_verifier } = body
+
+          if (!code || !client_id || !redirect_uri || !code_verifier) {
+            return fail(
+              'invalid_request',
+              'code, client_id, redirect_uri and code_verifier are required',
+            )
+          }
+
+          return tokenResponse(
+            await app.container.resolve(ExchangeCodeUseCase).execute({
+              code,
+              clientId: client_id,
+              redirectUri: redirect_uri,
+              codeVerifier: code_verifier,
+              resource,
+            }),
+          )
+        }
+
+        if (body.grant_type === 'refresh_token') {
+          if (!body.refresh_token || !body.client_id) {
+            return fail('invalid_request', 'refresh_token and client_id are required')
+          }
+
+          return tokenResponse(
+            await app.container
+              .resolve(RefreshSessionUseCase)
+              .execute(body.refresh_token, body.client_id),
+          )
+        }
+
+        return fail('unsupported_grant_type', 'Only authorization_code and refresh_token')
+      } catch (error) {
+        if (
+          error instanceof InvalidGrantError ||
+          error instanceof InvalidSessionError ||
+          error instanceof SupersededTokenError
+        ) {
+          return fail('invalid_grant', error.message)
+        }
+
+        throw error
+      }
+    },
+  )
+}

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

@@ -31,6 +31,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',
 }

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/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/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)
+  }
+}