From d4b790fd86c6ed4dc4def9483b91989e2bdfb771 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=B0=95=EB=8B=A4=ED=98=84=20=28Dahyeon=20Park=29?= Date: Sun, 12 Apr 2026 22:17:00 +0900 Subject: [PATCH] feat(api): add auth guards --- .../auth/allow-public-access.decorator.ts | 7 ++ apps/api/src/modules/auth/auth-request.ts | 16 +++ apps/api/src/modules/auth/auth.middleware.ts | 18 ++++ apps/api/src/modules/auth/auth.module.ts | 33 ++++++ apps/api/src/modules/auth/auth.service.ts | 62 +++++++++++ .../auth/current-identity.decorator.ts | 11 ++ .../modules/auth/current-user.decorator.ts | 11 ++ .../modules/auth/identity-resolver.guard.ts | 38 +++++++ apps/api/src/modules/auth/identity.service.ts | 39 +++++++ apps/api/src/modules/auth/jwt.guard.ts | 91 ++++++++++++++++ apps/api/src/modules/auth/jwt.service.ts | 100 ++++++++++++++++++ apps/api/src/modules/auth/permissions.ts | 35 ++++++ apps/api/src/modules/auth/roles.decorator.ts | 7 ++ apps/api/src/modules/auth/roles.guard.ts | 36 +++++++ .../modules/auth/user-resolver.guard.spec.ts | 55 ++++++++++ .../src/modules/auth/user-resolver.guard.ts | 33 ++++++ 16 files changed, 592 insertions(+) create mode 100644 apps/api/src/modules/auth/allow-public-access.decorator.ts create mode 100644 apps/api/src/modules/auth/auth-request.ts create mode 100644 apps/api/src/modules/auth/auth.middleware.ts create mode 100644 apps/api/src/modules/auth/auth.module.ts create mode 100644 apps/api/src/modules/auth/auth.service.ts create mode 100644 apps/api/src/modules/auth/current-identity.decorator.ts create mode 100644 apps/api/src/modules/auth/current-user.decorator.ts create mode 100644 apps/api/src/modules/auth/identity-resolver.guard.ts create mode 100644 apps/api/src/modules/auth/identity.service.ts create mode 100644 apps/api/src/modules/auth/jwt.guard.ts create mode 100644 apps/api/src/modules/auth/jwt.service.ts create mode 100644 apps/api/src/modules/auth/permissions.ts create mode 100644 apps/api/src/modules/auth/roles.decorator.ts create mode 100644 apps/api/src/modules/auth/roles.guard.ts create mode 100644 apps/api/src/modules/auth/user-resolver.guard.spec.ts create mode 100644 apps/api/src/modules/auth/user-resolver.guard.ts diff --git a/apps/api/src/modules/auth/allow-public-access.decorator.ts b/apps/api/src/modules/auth/allow-public-access.decorator.ts new file mode 100644 index 00000000..230f3604 --- /dev/null +++ b/apps/api/src/modules/auth/allow-public-access.decorator.ts @@ -0,0 +1,7 @@ +import { SetMetadata } from '@nestjs/common'; + +export const METADATA_KEY_IS_PUBLIC_ACCESS_ALLOWED = + 'lolympus:allow_public_access'; + +export const AllowPublicAccess = () => + SetMetadata(METADATA_KEY_IS_PUBLIC_ACCESS_ALLOWED, true); diff --git a/apps/api/src/modules/auth/auth-request.ts b/apps/api/src/modules/auth/auth-request.ts new file mode 100644 index 00000000..678677d9 --- /dev/null +++ b/apps/api/src/modules/auth/auth-request.ts @@ -0,0 +1,16 @@ +import type { JWTHeaderParameters, JWTPayload } from 'jose'; +import type { + IdentityDocument, + UserDocument, +} from '../global/database/schema'; +import type { IdentityProviderName } from './jwt.service'; + +declare module 'express' { + interface Request { + tokenPayload?: JWTPayload; + tokenHeader?: JWTHeaderParameters; + identityProvider?: IdentityProviderName; + identity?: IdentityDocument; + user?: UserDocument; + } +} diff --git a/apps/api/src/modules/auth/auth.middleware.ts b/apps/api/src/modules/auth/auth.middleware.ts new file mode 100644 index 00000000..ff8f5e58 --- /dev/null +++ b/apps/api/src/modules/auth/auth.middleware.ts @@ -0,0 +1,18 @@ +import { Injectable, NestMiddleware } from '@nestjs/common'; +import type { NextFunction, Request, Response } from 'express'; +import { AuthService } from './auth.service'; +import './auth-request'; + +@Injectable() +export class AuthMiddleware implements NestMiddleware { + constructor(private readonly authService: AuthService) {} + + public async use(req: Request, _res: Response, next: NextFunction) { + const fallback = await this.authService.resolveDevFallbackFromRequest(req); + if (fallback) { + req.user = fallback.user; + req.identity = fallback.identity; + } + next(); + } +} diff --git a/apps/api/src/modules/auth/auth.module.ts b/apps/api/src/modules/auth/auth.module.ts new file mode 100644 index 00000000..58d7ff02 --- /dev/null +++ b/apps/api/src/modules/auth/auth.module.ts @@ -0,0 +1,33 @@ +import { Global, Module } from '@nestjs/common'; +import { APP_GUARD } from '@nestjs/core'; +import { AuthService } from './auth.service'; +import { IdentityResolverGuard } from './identity-resolver.guard'; +import { IdentityService } from './identity.service'; +import { JwtAuthGuard } from './jwt.guard'; +import { JwtService } from './jwt.service'; +import { RolesGuard } from './roles.guard'; +import { UserResolverGuard } from './user-resolver.guard'; + +@Global() +@Module({ + providers: [ + AuthService, + JwtService, + IdentityService, + JwtAuthGuard, + IdentityResolverGuard, + UserResolverGuard, + RolesGuard, + { provide: APP_GUARD, useClass: JwtAuthGuard }, + { provide: APP_GUARD, useClass: IdentityResolverGuard }, + { provide: APP_GUARD, useClass: UserResolverGuard }, + ], + exports: [ + AuthService, + JwtService, + IdentityService, + UserResolverGuard, + RolesGuard, + ], +}) +export class AuthModule {} diff --git a/apps/api/src/modules/auth/auth.service.ts b/apps/api/src/modules/auth/auth.service.ts new file mode 100644 index 00000000..373aa71f --- /dev/null +++ b/apps/api/src/modules/auth/auth.service.ts @@ -0,0 +1,62 @@ +import { Injectable } from '@nestjs/common'; +import type { Request } from 'express'; +import mongoose from 'mongoose'; +import { ConnectionService } from '../global/database/connection.service'; +import { + IdentityDocument, + UserDocument, +} from '../global/database/schema'; +import { SecretService } from '../global/secret/secret.service'; +import './auth-request'; + +interface DevFallbackResult { + user: UserDocument; + identity?: IdentityDocument; +} + +@Injectable() +export class AuthService { + constructor( + private readonly connectionService: ConnectionService, + private readonly secretService: SecretService, + ) {} + + public async resolveDevFallbackFromRequest( + req: Request, + ): Promise { + if (!(await this.isDevHeaderEnabled())) return null; + const header = req.headers['x-auth-user-id']; + const userId = Array.isArray(header) ? header[0] : header; + return this.resolveDevUserById(userId); + } + + public async resolveDevUserById( + userId: unknown, + ): Promise { + if (!(await this.isDevHeaderEnabled())) return null; + if (typeof userId !== 'string' || !mongoose.isValidObjectId(userId)) { + return null; + } + + const UserModel = await this.connectionService.getModel('user'); + const user = await UserModel.findById(userId).exec(); + if (!user) return null; + + const result: DevFallbackResult = { user }; + if (user.identityId) { + const IdentityModel = await this.connectionService.getModel('identity'); + const identity = await IdentityModel.findById(user.identityId).exec(); + if (identity) result.identity = identity; + } + return result; + } + + private async isDevHeaderEnabled(): Promise { + if (process.env.NODE_ENV === 'prod') return false; + const value = await this.secretService.get( + 'AUTH_DEV_HEADER_ENABLED', + process.env.AUTH_DEV_HEADER_ENABLED ?? 'false', + ); + return value === 'true'; + } +} diff --git a/apps/api/src/modules/auth/current-identity.decorator.ts b/apps/api/src/modules/auth/current-identity.decorator.ts new file mode 100644 index 00000000..e3d0829b --- /dev/null +++ b/apps/api/src/modules/auth/current-identity.decorator.ts @@ -0,0 +1,11 @@ +import { createParamDecorator, ExecutionContext } from '@nestjs/common'; +import type { Request } from 'express'; +import { IdentityDocument } from '../global/database/schema'; +import './auth-request'; + +export const CurrentIdentity = createParamDecorator( + (_data: unknown, ctx: ExecutionContext): IdentityDocument | undefined => { + const req = ctx.switchToHttp().getRequest(); + return req.identity; + }, +); diff --git a/apps/api/src/modules/auth/current-user.decorator.ts b/apps/api/src/modules/auth/current-user.decorator.ts new file mode 100644 index 00000000..faac9965 --- /dev/null +++ b/apps/api/src/modules/auth/current-user.decorator.ts @@ -0,0 +1,11 @@ +import { createParamDecorator, ExecutionContext } from '@nestjs/common'; +import type { Request } from 'express'; +import { UserDocument } from '../global/database/schema'; +import './auth-request'; + +export const CurrentUser = createParamDecorator( + (_data: unknown, ctx: ExecutionContext): UserDocument | undefined => { + const req = ctx.switchToHttp().getRequest(); + return req.user; + }, +); diff --git a/apps/api/src/modules/auth/identity-resolver.guard.ts b/apps/api/src/modules/auth/identity-resolver.guard.ts new file mode 100644 index 00000000..2e343ba5 --- /dev/null +++ b/apps/api/src/modules/auth/identity-resolver.guard.ts @@ -0,0 +1,38 @@ +import { + CanActivate, + ExecutionContext, + Injectable, + UnauthorizedException, +} from '@nestjs/common'; +import type { Request } from 'express'; +import { IdentityService } from './identity.service'; +import './auth-request'; + +@Injectable() +export class IdentityResolverGuard implements CanActivate { + constructor(private readonly identityService: IdentityService) {} + + public async canActivate(context: ExecutionContext): Promise { + const request = context.switchToHttp().getRequest(); + if (request.identity || !request.tokenPayload) return true; + + const entraOid = stringClaim(request.tokenPayload.oid); + if (!entraOid) { + throw new UnauthorizedException('Token is missing oid claim.'); + } + + request.identity = await this.identityService.findOrCreateByOid({ + entraOid, + tenantId: stringClaim(request.tokenPayload.tid), + email: + stringClaim(request.tokenPayload.preferred_username) ?? + stringClaim(request.tokenPayload.email), + displayName: stringClaim(request.tokenPayload.name), + }); + return true; + } +} + +function stringClaim(value: unknown): string | undefined { + return typeof value === 'string' && value.length > 0 ? value : undefined; +} diff --git a/apps/api/src/modules/auth/identity.service.ts b/apps/api/src/modules/auth/identity.service.ts new file mode 100644 index 00000000..2504f5a1 --- /dev/null +++ b/apps/api/src/modules/auth/identity.service.ts @@ -0,0 +1,39 @@ +import { Injectable, InternalServerErrorException } from '@nestjs/common'; +import { ConnectionService } from '../global/database/connection.service'; +import { IdentityDocument } from '../global/database/schema'; + +interface IdentityInput { + entraOid: string; + tenantId?: string; + email?: string; + displayName?: string; +} + +@Injectable() +export class IdentityService { + constructor(private readonly connectionService: ConnectionService) {} + + public async findOrCreateByOid( + input: IdentityInput, + ): Promise { + const IdentityModel = await this.connectionService.getModel('identity'); + const identity = await IdentityModel.findOneAndUpdate( + { entraOid: input.entraOid }, + { + $set: { + tenantId: input.tenantId, + email: input.email, + displayName: input.displayName, + lastSignInAt: new Date(), + }, + $setOnInsert: { entraOid: input.entraOid }, + }, + { upsert: true, returnDocument: 'after', setDefaultsOnInsert: true }, + ).exec(); + + if (!identity) { + throw new InternalServerErrorException('Failed to resolve identity.'); + } + return identity; + } +} diff --git a/apps/api/src/modules/auth/jwt.guard.ts b/apps/api/src/modules/auth/jwt.guard.ts new file mode 100644 index 00000000..e3d405a1 --- /dev/null +++ b/apps/api/src/modules/auth/jwt.guard.ts @@ -0,0 +1,91 @@ +import { + CanActivate, + ExecutionContext, + Injectable, + UnauthorizedException, +} from '@nestjs/common'; +import { Reflector } from '@nestjs/core'; +import { decodeJwt } from 'jose'; +import type { Request } from 'express'; +import { METADATA_KEY_IS_PUBLIC_ACCESS_ALLOWED } from './allow-public-access.decorator'; +import { AuthService } from './auth.service'; +import { IdentityProviderName, JwtService } from './jwt.service'; +import './auth-request'; + +@Injectable() +export class JwtAuthGuard implements CanActivate { + constructor( + private readonly reflector: Reflector, + private readonly jwtService: JwtService, + private readonly authService: AuthService, + ) {} + + public async canActivate(context: ExecutionContext): Promise { + const request = context.switchToHttp().getRequest(); + const isPublicAccessAllowed = this.reflector.getAllAndOverride( + METADATA_KEY_IS_PUBLIC_ACCESS_ALLOWED, + [context.getHandler(), context.getClass()], + ); + const authz = request.headers?.authorization; + const authzHeader = Array.isArray(authz) ? authz[0] : authz; + + if (!authzHeader) { + const fallback = + await this.authService.resolveDevFallbackFromRequest(request); + if (fallback) { + request.user = fallback.user; + request.identity = fallback.identity; + return true; + } + if (isPublicAccessAllowed) return true; + throw new UnauthorizedException( + 'Missing or invalid Authorization header', + ); + } + + if (!authzHeader.startsWith('Bearer ')) { + throw new UnauthorizedException( + 'Missing or invalid Authorization header', + ); + } + + const token = authzHeader.slice('Bearer '.length).trim(); + if (!token) { + throw new UnauthorizedException('Empty bearer token'); + } + + const identityProvider = this.pickIdPFromToken(token); + + try { + const verifyResult = await this.jwtService.verify( + token, + identityProvider, + ); + request.tokenPayload = verifyResult.payload; + request.tokenHeader = verifyResult.protectedHeader; + request.identityProvider = identityProvider; + return true; + } catch (err) { + const message = + err instanceof Error ? err.message : 'JWT verification failed'; + throw new UnauthorizedException(message); + } + } + + private pickIdPFromToken(token: string): IdentityProviderName { + try { + const { iss } = decodeJwt(token) as { iss?: string }; + if (!iss) { + throw new Error('Token has no issuer (iss) claim'); + } + const lower = iss.toLowerCase(); + if (lower.includes('login.microsoftonline.com')) { + return 'MICROSOFT_ENTRAID'; + } + throw new Error(`Unknown issuer: ${iss}`); + } catch (err) { + const message = err instanceof Error ? err.message : 'Unable to decode token'; + throw new UnauthorizedException(message); + } + } +} diff --git a/apps/api/src/modules/auth/jwt.service.ts b/apps/api/src/modules/auth/jwt.service.ts new file mode 100644 index 00000000..166ca211 --- /dev/null +++ b/apps/api/src/modules/auth/jwt.service.ts @@ -0,0 +1,100 @@ +import { Injectable } from '@nestjs/common'; +import { + createRemoteJWKSet, + jwtVerify, + JWTPayload, + JWTVerifyGetKey, + JWTVerifyResult, +} from 'jose'; +import { SecretService } from '../global/secret/secret.service'; + +export type IdentityProviderName = 'MICROSOFT_ENTRAID'; + +interface EntraConfig { + tenantId: string; + audience: string; + issuer: string; + allowedAlgs: string[]; + jwks: JWTVerifyGetKey; +} + +@Injectable() +export class JwtService { + private entraConfig?: EntraConfig; + private readonly clockTolerance = Number( + process.env.JWT_CLOCK_TOLERANCE || 5, + ); + + constructor(private readonly secretService: SecretService) {} + + public async verify( + token: string, + identityProvider: IdentityProviderName, + ): Promise> { + if (!token) { + throw new Error('Empty token'); + } + + if (identityProvider !== 'MICROSOFT_ENTRAID') { + throw new Error(`Identity provider not configured: ${identityProvider}`); + } + + const provider = await this.getEntraConfig(); + const result = await jwtVerify(token, provider.jwks, { + issuer: provider.issuer, + audience: provider.audience, + algorithms: provider.allowedAlgs, + clockTolerance: this.clockTolerance, + }); + + const { payload, protectedHeader } = result; + if (!provider.allowedAlgs.includes(protectedHeader.alg as string)) { + throw new Error(`Unexpected alg: ${protectedHeader.alg}`); + } + if (payload.ver && payload.ver !== '2.0') { + throw new Error(`Unsupported Entra token version: ${payload.ver}`); + } + if (payload.tid && payload.tid !== provider.tenantId) { + throw new Error(`Unexpected tenant: ${payload.tid}`); + } + + return result; + } + + private async getEntraConfig(): Promise { + if (this.entraConfig) return this.entraConfig; + + await this.secretService.ready(); + const [audience, tenantId, allowedAlgsRaw] = await Promise.all([ + this.secretService.get('JWT_CLAIM_AUDIENCE'), + this.secretService.get('MICROSOFT_ENTRAID_TENANT_ID'), + this.secretService.get('MICROSOFT_ENTRAID_ALLOWED_ALGS', 'RS256'), + ]); + + const allowedAlgs = allowedAlgsRaw + .split(',') + .map((alg) => alg.trim()) + .filter(Boolean); + if (allowedAlgs.length === 0) { + allowedAlgs.push('RS256'); + } + + const issuer = `https://login.microsoftonline.com/${tenantId}/v2.0`; + const jwks = createRemoteJWKSet( + new URL('https://login.microsoftonline.com/common/discovery/v2.0/keys'), + { + cooldownDuration: 30_000, + timeoutDuration: 10_000, + }, + ); + + this.entraConfig = { + tenantId, + audience, + issuer, + allowedAlgs, + jwks, + }; + return this.entraConfig; + } +} diff --git a/apps/api/src/modules/auth/permissions.ts b/apps/api/src/modules/auth/permissions.ts new file mode 100644 index 00000000..7e7f7800 --- /dev/null +++ b/apps/api/src/modules/auth/permissions.ts @@ -0,0 +1,35 @@ +import { CommunityRole } from '../global/database/schema'; + +export type Permission = + | 'community:edit' + | 'community:delete' + | 'community:transfer' + | 'user:role:manage' + | 'match:create' + | 'match:edit' + | 'match:delete' + | 'auction:manage'; + +type PermissionSet = readonly Permission[] | readonly ['*']; + +export const ROLE_PERMISSIONS: Record = { + owner: ['*'] as const, + admin: [ + 'community:edit', + 'user:role:manage', + 'match:create', + 'match:edit', + 'match:delete', + 'auction:manage', + ] as const, + member: [] as const, +}; + +export function roleHasPermission( + role: CommunityRole, + permission: Permission, +): boolean { + const perms = ROLE_PERMISSIONS[role]; + if (perms.length === 1 && perms[0] === '*') return true; + return (perms as readonly Permission[]).includes(permission); +} diff --git a/apps/api/src/modules/auth/roles.decorator.ts b/apps/api/src/modules/auth/roles.decorator.ts new file mode 100644 index 00000000..819cbb3a --- /dev/null +++ b/apps/api/src/modules/auth/roles.decorator.ts @@ -0,0 +1,7 @@ +import { SetMetadata } from '@nestjs/common'; +import { CommunityRole } from '../global/database/schema'; + +export const ROLES_KEY = 'lolympus:roles'; + +export const Roles = (...roles: CommunityRole[]) => + SetMetadata(ROLES_KEY, roles); diff --git a/apps/api/src/modules/auth/roles.guard.ts b/apps/api/src/modules/auth/roles.guard.ts new file mode 100644 index 00000000..6e76e87d --- /dev/null +++ b/apps/api/src/modules/auth/roles.guard.ts @@ -0,0 +1,36 @@ +import { + CanActivate, + ExecutionContext, + ForbiddenException, + Injectable, + UnauthorizedException, +} from '@nestjs/common'; +import { Reflector } from '@nestjs/core'; +import type { Request } from 'express'; +import { CommunityRole, UserDocument } from '../global/database/schema'; +import { ROLES_KEY } from './roles.decorator'; +import './auth-request'; + +@Injectable() +export class RolesGuard implements CanActivate { + constructor(private readonly reflector: Reflector) {} + + public canActivate(context: ExecutionContext): boolean { + const requiredRoles = this.reflector.getAllAndOverride( + ROLES_KEY, + [context.getHandler(), context.getClass()], + ); + if (!requiredRoles || requiredRoles.length === 0) return true; + + const req = context.switchToHttp().getRequest(); + const user = req.user as UserDocument | undefined; + if (!user && req.identity) { + throw new ForbiddenException('No membership in this community.'); + } + if (!user) throw new UnauthorizedException('Authentication required.'); + if (!requiredRoles.includes(user.role)) { + throw new ForbiddenException('Insufficient role.'); + } + return true; + } +} diff --git a/apps/api/src/modules/auth/user-resolver.guard.spec.ts b/apps/api/src/modules/auth/user-resolver.guard.spec.ts new file mode 100644 index 00000000..559a054f --- /dev/null +++ b/apps/api/src/modules/auth/user-resolver.guard.spec.ts @@ -0,0 +1,55 @@ +import { ExecutionContext } from '@nestjs/common'; +import mongoose from 'mongoose'; +import { ConnectionService } from '../global/database/connection.service'; +import { IdentityDocument, UserDocument } from '../global/database/schema'; +import { UserResolverGuard } from './user-resolver.guard'; +import './auth-request'; + +function createContext(request: Record): ExecutionContext { + return { + switchToHttp: () => ({ + getRequest: () => request, + }), + } as ExecutionContext; +} + +describe('UserResolverGuard', () => { + it('resolves the community membership before role guards run', async () => { + const communityId = new mongoose.Types.ObjectId(); + const identityId = new mongoose.Types.ObjectId(); + const user = { _id: new mongoose.Types.ObjectId() } as UserDocument; + const findOne = jest.fn().mockReturnValue({ + exec: jest.fn().mockResolvedValue(user), + }); + const connectionService = { + getModel: jest.fn().mockResolvedValue({ findOne }), + } as unknown as ConnectionService; + const request = { + params: { communityId: communityId.toString() }, + identity: { _id: identityId } as IdentityDocument, + }; + const guard = new UserResolverGuard(connectionService); + + await expect(guard.canActivate(createContext(request))).resolves.toBe(true); + + expect(findOne).toHaveBeenCalledWith({ + communityId, + identityId, + }); + expect(request.user).toBe(user); + }); + + it('skips lookup when there is no resolved identity', async () => { + const connectionService = { + getModel: jest.fn(), + } as unknown as ConnectionService; + const request = { + params: { communityId: new mongoose.Types.ObjectId().toString() }, + }; + const guard = new UserResolverGuard(connectionService); + + await expect(guard.canActivate(createContext(request))).resolves.toBe(true); + + expect(connectionService.getModel).not.toHaveBeenCalled(); + }); +}); diff --git a/apps/api/src/modules/auth/user-resolver.guard.ts b/apps/api/src/modules/auth/user-resolver.guard.ts new file mode 100644 index 00000000..56eac35a --- /dev/null +++ b/apps/api/src/modules/auth/user-resolver.guard.ts @@ -0,0 +1,33 @@ +import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common'; +import type { Request } from 'express'; +import mongoose from 'mongoose'; +import { ConnectionService } from '../global/database/connection.service'; +import './auth-request'; + +@Injectable() +export class UserResolverGuard implements CanActivate { + constructor(private readonly connectionService: ConnectionService) {} + + public async canActivate(context: ExecutionContext): Promise { + const request = context.switchToHttp().getRequest(); + const communityId = request.params?.communityId; + + if ( + request.user || + !request.identity || + typeof communityId !== 'string' || + !mongoose.isValidObjectId(communityId) + ) { + return true; + } + + const UserModel = await this.connectionService.getModel('user'); + const user = await UserModel.findOne({ + communityId: new mongoose.Types.ObjectId(communityId), + identityId: request.identity._id, + }).exec(); + + if (user) request.user = user; + return true; + } +}