@stjoseph/prumo 0.2.0 → 0.3.0

package/templates/api/src/domain/oauth/use-cases/start-authorization.use-case.ts

@@ -0,0 +1,75 @@
+import { inject, injectable } from 'tsyringe'
+import { Authorization } from '@/domain/oauth/entities/authorization.entity'
+import { AuthorizationRequestError } from '@/domain/oauth/errors/authorization-request.error'
+import { InvalidClientError } from '@/domain/oauth/errors/invalid-client.error'
+import {
+  CLIENT_METADATA,
+  type ClientMetadataSource,
+} from '@/domain/oauth/ports/client-metadata.port'
+import {
+  AUTHORIZATION_REPOSITORY,
+  type AuthorizationRepository,
+} from '@/domain/oauth/repositories/authorization.repository'
+
+// RFC 7636: 43 to 128 characters from the unreserved set.
+const CODE_CHALLENGE = /^[A-Za-z0-9\-._~]{43,128}$/
+
+export type AuthorizeRequest = {
+  responseType: string | undefined
+  clientId: string
+  redirectUri: string
+  codeChallenge: string | undefined
+  codeChallengeMethod: string | undefined
+  clientState: string | null
+  resource: string | undefined
+}
+
+@injectable()
+export class StartAuthorizationUseCase {
+  constructor(
+    @inject(CLIENT_METADATA) private readonly clients: ClientMetadataSource,
+    @inject(AUTHORIZATION_REPOSITORY) private readonly authorizations: AuthorizationRepository,
+  ) {}
+
+  // The client and its redirect URI are checked first: until both are, no error may be sent anywhere.
+  async execute(request: AuthorizeRequest, expectedResource: string): Promise<Authorization> {
+    const client = await this.clients.read(request.clientId)
+
+    // Exact match only: a prefix or a pattern is how an authorization code ends up somewhere else.
+    if (!client.redirectUris.includes(request.redirectUri)) {
+      throw new InvalidClientError('redirect_uri is not one the client registered')
+    }
+
+    if (request.responseType !== 'code') {
+      throw new AuthorizationRequestError('unsupported_response_type', 'Only response_type=code')
+    }
+
+    if (
+      request.codeChallengeMethod !== 'S256' ||
+      !CODE_CHALLENGE.test(request.codeChallenge ?? '')
+    ) {
+      throw new AuthorizationRequestError('invalid_request', 'PKCE with S256 is required')
+    }
+
+    // RFC 8707: the token is for one resource, and this server has one.
+    if (request.resource !== expectedResource) {
+      throw new AuthorizationRequestError('invalid_target', `resource must be ${expectedResource}`)
+    }
+
+    const authorization = new Authorization(
+      {
+        clientId: request.clientId,
+        clientName: client.clientName,
+        redirectUri: request.redirectUri,
+        codeChallenge: request.codeChallenge as string,
+        clientState: request.clientState,
+        resource: expectedResource,
+      },
+      new Date(),
+    )
+
+    await this.authorizations.save(authorization)
+
+    return authorization
+  }
+}

package/templates/api/src/infra/auth/argon2-password-hasher.adapter.ts

@@ -0,0 +1,21 @@
+import { hash, verify } from '@node-rs/argon2'
+import type { PasswordHasher } from '@/domain/auth/ports/password-hasher.port'
+
+// The library's defaults are Argon2id with 19 MiB, two passes and one lane: OWASP's minimum, so none is restated.
+export class Argon2PasswordHasher implements PasswordHasher {
+  // A real hash of nothing in particular, so an unknown email costs one verification like any other.
+  private readonly decoy = hash('decoy password that nobody holds')
+
+  hash(password: string): Promise<string> {
+    return hash(password)
+  }
+
+  async verify(stored: string | undefined, password: string): Promise<boolean> {
+    if (stored === undefined) {
+      await verify(await this.decoy, password)
+      return false
+    }
+
+    return verify(stored, password)
+  }
+}

package/templates/api/src/infra/auth/crypto-opaque-tokens.adapter.ts

@@ -0,0 +1,14 @@
+import { createHash, randomBytes } from 'node:crypto'
+import type { OpaqueTokens } from '@/domain/auth/ports/opaque-tokens.port'
+
+// 256 random bits need no slow hash: nothing can be guessed, so a plain SHA-256 is enough to keep a stolen
+// database from handing out working tokens.
+export class CryptoOpaqueTokens implements OpaqueTokens {
+  create(): string {
+    return randomBytes(32).toString('base64url')
+  }
+
+  digest(token: string): string {
+    return createHash('sha256').update(token).digest('base64url')
+  }
+}

package/templates/api/src/infra/auth/jose-access-tokens.adapter.ts

@@ -0,0 +1,62 @@
+import { jwtVerify, SignJWT } from 'jose'
+import type {
+  AccessClaims,
+  AccessTokens,
+  IssuedToken,
+} from '@/domain/auth/ports/access-tokens.port'
+import type { Env } from '@/infra/config/env'
+
+// One algorithm, named on both sides: a token that declares any other, `none` included, is refused.
+const ALGORITHM = 'HS256'
+
+export class JoseAccessTokens implements AccessTokens {
+  private readonly key: Uint8Array
+  private readonly issuer: string
+
+  constructor(env: Pick<Env, 'JWT_SECRET' | 'API_URL'>) {
+    this.key = new TextEncoder().encode(env.JWT_SECRET)
+    this.issuer = env.API_URL
+  }
+
+  async issue(
+    { userId, sessionId, clientId }: AccessClaims,
+    expiresAt: Date,
+    audience = this.issuer,
+  ): Promise<IssuedToken> {
+    const token = await new SignJWT({
+      sid: sessionId,
+      ...(clientId !== undefined && { client_id: clientId }),
+    })
+      .setProtectedHeader({ alg: ALGORITHM })
+      .setSubject(userId)
+      .setIssuer(this.issuer)
+      .setAudience(audience)
+      .setIssuedAt()
+      .setExpirationTime(Math.floor(expiresAt.getTime() / 1000))
+      .sign(this.key)
+
+    return { token, expiresAt }
+  }
+
+  async verify(token: string, audience = this.issuer): Promise<AccessClaims | null> {
+    try {
+      const { payload } = await jwtVerify(token, this.key, {
+        algorithms: [ALGORITHM],
+        issuer: this.issuer,
+        audience,
+      })
+
+      if (typeof payload.sub !== 'string' || typeof payload.sid !== 'string') {
+        return null
+      }
+
+      return {
+        userId: payload.sub,
+        sessionId: payload.sid,
+        ...(typeof payload.client_id === 'string' && { clientId: payload.client_id }),
+      }
+    } catch {
+      return null
+    }
+  }
+}

package/templates/api/src/infra/config/env.ts

@@ -5,14 +5,10 @@ const envSchema = z.object({
   NODE_ENV: z.enum(['development', 'test', 'production']),
   PORT: z.coerce.number().int().min(1).max(65535),
   DATABASE_URL: z.string().min(1),
-  AUTH_DATABASE_URL: z.string().min(1),
-  BETTER_AUTH_SECRET: z.string().min(32),
-  BETTER_AUTH_URL: z.string().min(1),
+  JWT_SECRET: z.string().min(32),
+  // Where this API is reached from outside: the issuer of its tokens, and what decides whether cookies are Secure.
+  API_URL: z.url(),
   WEB_ORIGIN: z.string().min(1),
-  MOBILE_APP_SCHEME: z
-    .string()
-    .regex(/^[a-z][a-z0-9+.-]*$/)
-    .optional(),
   LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']),
 })
 

package/templates/api/src/infra/database/mikroorm/entities/authorization.schema.ts

@@ -0,0 +1,37 @@
+import { EntitySchema } from '@mikro-orm/core'
+import { Authorization } from '@/domain/oauth/entities/authorization.entity'
+
+export const AuthorizationSchema = new EntitySchema({
+  class: Authorization,
+  properties: {
+    id: { type: 'uuid', primary: true, defaultRaw: 'uuidv7()' },
+    clientId: { type: 'text' },
+    clientName: { type: 'text' },
+    redirectUri: { type: 'text' },
+    codeChallenge: { type: 'text' },
+    clientState: { type: 'text', nullable: true },
+    resource: { type: 'text' },
+    status: { type: 'text' },
+    userId: {
+      kind: 'm:1',
+      // EntitySchema cannot type a to-one relation held as its primary key on a string property.
+      entity: () => 'User' as never,
+      mapToPk: true,
+      fieldName: 'user_id',
+      nullable: true,
+      index: true,
+      // An authorization means nothing without the user who gave it.
+      deleteRule: 'cascade',
+    },
+    codeHash: { type: 'text', nullable: true },
+    sessionId: { type: 'uuid', nullable: true },
+    expiresAt: { type: 'datetime' },
+    createdAt: { type: 'datetime', onCreate: () => new Date(), defaultRaw: 'now()' },
+    updatedAt: {
+      type: 'datetime',
+      onCreate: () => new Date(),
+      onUpdate: () => new Date(),
+      defaultRaw: 'now()',
+    },
+  },
+})

package/templates/api/src/infra/database/mikroorm/entities/profile.schema.ts

@@ -8,7 +8,7 @@ export const ProfileSchema = new EntitySchema({
     userId: {
       kind: 'm:1',
       // EntitySchema cannot type a to-one relation held as its primary key on a string property.
-      entity: () => 'AuthUser' as never,
+      entity: () => 'User' as never,
       mapToPk: true,
       fieldName: 'user_id',
       unique: true,

package/templates/api/src/infra/database/mikroorm/entities/session.schema.ts

@@ -0,0 +1,33 @@
+import { EntitySchema } from '@mikro-orm/core'
+import { Session } from '@/domain/auth/entities/session.entity'
+
+export const SessionSchema = new EntitySchema({
+  class: Session,
+  properties: {
+    id: { type: 'uuid', primary: true, defaultRaw: 'uuidv7()' },
+    userId: {
+      kind: 'm:1',
+      // EntitySchema cannot type a to-one relation held as its primary key on a string property.
+      entity: () => 'User' as never,
+      mapToPk: true,
+      fieldName: 'user_id',
+      index: true,
+      // A session means nothing without its user.
+      deleteRule: 'cascade',
+    },
+    tokenHash: { type: 'text' },
+    clientId: { type: 'text', nullable: true },
+    resource: { type: 'text', nullable: true },
+    previousTokenHash: { type: 'text', nullable: true },
+    rotatedAt: { type: 'datetime', nullable: true },
+    expiresAt: { type: 'datetime' },
+    revokedAt: { type: 'datetime', nullable: true },
+    createdAt: { type: 'datetime', onCreate: () => new Date(), defaultRaw: 'now()' },
+    updatedAt: {
+      type: 'datetime',
+      onCreate: () => new Date(),
+      onUpdate: () => new Date(),
+      defaultRaw: 'now()',
+    },
+  },
+})

package/templates/api/src/infra/database/mikroorm/entities/user.schema.ts

@@ -0,0 +1,18 @@
+import { EntitySchema } from '@mikro-orm/core'
+import { User } from '@/domain/auth/entities/user.entity'
+
+export const UserSchema = new EntitySchema({
+  class: User,
+  properties: {
+    id: { type: 'uuid', primary: true, defaultRaw: 'uuidv7()' },
+    email: { type: 'text', unique: true },
+    passwordHash: { type: 'text' },
+    createdAt: { type: 'datetime', onCreate: () => new Date(), defaultRaw: 'now()' },
+    updatedAt: {
+      type: 'datetime',
+      onCreate: () => new Date(),
+      onUpdate: () => new Date(),
+      defaultRaw: 'now()',
+    },
+  },
+})

package/templates/api/src/infra/database/mikroorm/mikro-orm.factory.ts

@@ -1,17 +1,22 @@
 import { Migrator } from '@mikro-orm/migrations'
 import { defineConfig } from '@mikro-orm/postgresql'
 import type { Env } from '@/infra/config/env'
-import { AuthUserSchema } from './entities/auth-user.schema'
+import { AuthorizationSchema } from './entities/authorization.schema' // prumo:mcp
 import { ProfileSchema } from './entities/profile.schema'
+import { SessionSchema } from './entities/session.schema'
+import { UserSchema } from './entities/user.schema'
 
 export function createOrmConfig(env: Pick<Env, 'DATABASE_URL' | 'NODE_ENV'>) {
   return defineConfig({
     clientUrl: env.DATABASE_URL,
-    entities: [ProfileSchema, AuthUserSchema],
+    entities: [
+      UserSchema,
+      ProfileSchema,
+      SessionSchema,
+      AuthorizationSchema, // prumo:mcp
+    ],
     extensions: [Migrator],
     migrations: { path: './migrations', snapshot: false },
-    // Better Auth migrates its own schema; without this, every generated migration drops it.
-    schemaGenerator: { ignoreSchema: ['auth'], skipTables: ['auth.user'] },
     debug: env.NODE_ENV === 'development',
   })
 }

package/templates/api/src/infra/database/mikroorm/repositories/mikroorm-authorization.repository.ts

@@ -0,0 +1,21 @@
+import { EntityManager, LockMode } from '@mikro-orm/postgresql'
+import { injectable } from 'tsyringe'
+import { Authorization } from '@/domain/oauth/entities/authorization.entity'
+import type { AuthorizationRepository } from '@/domain/oauth/repositories/authorization.repository'
+
+@injectable()
+export class MikroOrmAuthorizationRepository implements AuthorizationRepository {
+  constructor(private readonly em: EntityManager) {}
+
+  findById(id: string): Promise<Authorization | null> {
+    return this.em.findOne(Authorization, { id })
+  }
+
+  lockById(id: string): Promise<Authorization | null> {
+    return this.em.findOne(Authorization, { id }, { lockMode: LockMode.PESSIMISTIC_WRITE })
+  }
+
+  async save(authorization: Authorization): Promise<void> {
+    await this.em.persist(authorization).flush()
+  }
+}

package/templates/api/src/infra/database/mikroorm/repositories/mikroorm-session.repository.ts

@@ -0,0 +1,21 @@
+import { EntityManager, LockMode } from '@mikro-orm/postgresql'
+import { injectable } from 'tsyringe'
+import { Session } from '@/domain/auth/entities/session.entity'
+import type { SessionRepository } from '@/domain/auth/repositories/session.repository'
+
+@injectable()
+export class MikroOrmSessionRepository implements SessionRepository {
+  constructor(private readonly em: EntityManager) {}
+
+  findById(id: string): Promise<Session | null> {
+    return this.em.findOne(Session, { id })
+  }
+
+  lockById(id: string): Promise<Session | null> {
+    return this.em.findOne(Session, { id }, { lockMode: LockMode.PESSIMISTIC_WRITE })
+  }
+
+  async save(session: Session): Promise<void> {
+    await this.em.persist(session).flush()
+  }
+}

package/templates/api/src/infra/database/mikroorm/repositories/mikroorm-user.repository.ts

@@ -0,0 +1,31 @@
+import { EntityManager, UniqueConstraintViolationException } from '@mikro-orm/postgresql'
+import { injectable } from 'tsyringe'
+import { User } from '@/domain/auth/entities/user.entity'
+import { EmailTakenError } from '@/domain/auth/errors/email-taken.error'
+import type { UserRepository } from '@/domain/auth/repositories/user.repository'
+
+@injectable()
+export class MikroOrmUserRepository implements UserRepository {
+  constructor(private readonly em: EntityManager) {}
+
+  findById(id: string): Promise<User | null> {
+    return this.em.findOne(User, { id })
+  }
+
+  findByEmail(email: string): Promise<User | null> {
+    return this.em.findOne(User, { email })
+  }
+
+  async save(user: User): Promise<void> {
+    try {
+      await this.em.persist(user).flush()
+    } catch (error) {
+      // Two sign-ups with one email can both pass the check; the unique index settles which one exists.
+      if (error instanceof UniqueConstraintViolationException) {
+        throw new EmailTakenError()
+      }
+
+      throw error
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+import type { DependencyContainer } from 'tsyringe'
+import { ACCESS_TOKENS } from '@/domain/auth/ports/access-tokens.port'
+import { OPAQUE_TOKENS } from '@/domain/auth/ports/opaque-tokens.port'
+import { PASSWORD_HASHER } from '@/domain/auth/ports/password-hasher.port'
+import { SESSION_REPOSITORY } from '@/domain/auth/repositories/session.repository'
+import { USER_REPOSITORY } from '@/domain/auth/repositories/user.repository'
+import { Argon2PasswordHasher } from '@/infra/auth/argon2-password-hasher.adapter'
+import { CryptoOpaqueTokens } from '@/infra/auth/crypto-opaque-tokens.adapter'
+import { JoseAccessTokens } from '@/infra/auth/jose-access-tokens.adapter'
+import { ENV, type Env } from '@/infra/config/env'
+import { MikroOrmSessionRepository } from '@/infra/database/mikroorm/repositories/mikroorm-session.repository'
+import { MikroOrmUserRepository } from '@/infra/database/mikroorm/repositories/mikroorm-user.repository'
+
+export function registerAuth(container: DependencyContainer): void {
+  container.register(USER_REPOSITORY, { useClass: MikroOrmUserRepository })
+  container.register(SESSION_REPOSITORY, { useClass: MikroOrmSessionRepository })
+  // One instance each: the hasher keeps its decoy hash, the signer its key.
+  container.register(PASSWORD_HASHER, { useValue: new Argon2PasswordHasher() })
+  container.register(ACCESS_TOKENS, { useValue: new JoseAccessTokens(container.resolve<Env>(ENV)) })
+  container.register(OPAQUE_TOKENS, { useValue: new CryptoOpaqueTokens() })
+}

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

@@ -1,10 +1,10 @@
 import { EntityManager, MikroORM } from '@mikro-orm/postgresql'
 import { type DependencyContainer, container as root } from 'tsyringe'
 import { TRANSACTION_MANAGER } from '@/domain/shared/transactions/transaction-manager'
-import { CreateProfileUseCase } from '@/domain/users/use-cases/create-profile.use-case'
-import { AUTH, createAuth } from '@/infra/auth/auth.factory'
 import { ENV, type Env } from '@/infra/config/env'
 import { MikroOrmTransactionManager } from '@/infra/database/mikroorm/transactions/mikroorm-transaction-manager'
+import { registerAuth } from './auth.di'
+import { registerOauth } from './oauth.di' // prumo:mcp
 import { registerUsers } from './users.di'
 
 export type Dependencies = { env: Env; orm: MikroORM }
@@ -18,15 +18,9 @@ export function createContainer({ env, orm }: Dependencies): DependencyContainer
   container.register(EntityManager, { useValue: orm.em })
   container.register(TRANSACTION_MANAGER, { useClass: MikroOrmTransactionManager })
 
+  registerAuth(container)
   registerUsers(container)
-
-  container.register(AUTH, {
-    useValue: createAuth(env, {
-      onUserCreated: async (user) => {
-        await container.resolve(CreateProfileUseCase).execute(user.id, user.name)
-      },
-    }),
-  })
+  registerOauth(container) // prumo:mcp
 
   return container
 }

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

@@ -0,0 +1,14 @@
+import type { DependencyContainer } from 'tsyringe'
+import { AUTHORIZATION_CODES } from '@/domain/oauth/ports/authorization-codes.port'
+import { CLIENT_METADATA } from '@/domain/oauth/ports/client-metadata.port'
+import { AUTHORIZATION_REPOSITORY } from '@/domain/oauth/repositories/authorization.repository'
+import { MikroOrmAuthorizationRepository } from '@/infra/database/mikroorm/repositories/mikroorm-authorization.repository'
+import { CryptoAuthorizationCodes } from '@/infra/oauth/crypto-authorization-codes.adapter'
+import { HttpsClientMetadata } from '@/infra/oauth/https-client-metadata.adapter'
+
+export function registerOauth(container: DependencyContainer): void {
+  container.register(AUTHORIZATION_REPOSITORY, { useClass: MikroOrmAuthorizationRepository })
+  container.register(AUTHORIZATION_CODES, { useValue: new CryptoAuthorizationCodes() })
+  // One instance, so its cache of client documents outlives a request.
+  container.register(CLIENT_METADATA, { useValue: new HttpsClientMetadata() })
+}

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

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto'
+import cookie from '@fastify/cookie'
 import cors from '@fastify/cors'
+import rateLimit from '@fastify/rate-limit'
 import swagger from '@fastify/swagger'
 import swaggerUi from '@fastify/swagger-ui'
 import { EntityManager } from '@mikro-orm/postgresql'
@@ -14,9 +16,11 @@ import { ENV, type Env } from '@/infra/config/env'
 import { authController } from '@/infra/http/controllers/auth.controller'
 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 { usersController } from '@/infra/http/controllers/users.controller'
 import { registerErrorHandler } from '@/infra/http/errors/error-handler'
 import { registerAuthHook } from '@/infra/http/hooks/auth.hook'
+import { registerOriginCheck } from '@/infra/http/hooks/origin.hook'
 import { registerRequestContext } from '@/infra/http/hooks/request-context.hook'
 
 const DOCS = '/api/docs'
@@ -82,16 +86,22 @@ export async function buildApp(container: DependencyContainer): Promise<FastifyI
     exposedHeaders: ['X-Request-Id'],
   })
 
+  await app.register(cookie)
+  // Off by default: a route opts in through its config, so only the routes that take a password are limited.
+  await app.register(rateLimit, { global: false })
+  registerOriginCheck(app, env.WEB_ORIGIN)
+
   if (env.NODE_ENV !== 'production') {
     await registerDocs(app)
   }
 
   registerAuthHook(app)
 
-  await app.register(authController)
+  await app.register(authController, { prefix: '/api/auth' })
   await app.register(healthController, { prefix: '/api/health' })
   await app.register(usersController, { prefix: '/api/v1/users' })
   // prumo:mcp
+  await app.register(oauthController)
   await app.register(mcpController, { prefix: '/api/mcp' })
   // prumo:end-mcp