feat: add configurable JWT signing and permission claims

Rebuilds #974 on top of the current wallet-auth/RBAC architecture:
centralizes JWT signing config (HS256/RS256 via JWT_ALGORITHM) into a
shared factory used by both AuthModule and UsersModule, and adds a
permissions claim derived from roles to the access token payload.

Author: Vox-d-glitch

backend/src/auth/auth.module.ts

@@ -1,13 +1,13 @@
 import { Module } from '@nestjs/common';
 import { JwtModule } from '@nestjs/jwt';
 import { PassportModule } from '@nestjs/passport';
-import { ConfigModule, ConfigService } from '@nestjs/config';
 import { AuthController } from './auth.controller';
 import { AuthService } from './auth.service';
 import { JwtStrategy } from './strategies/jwt.strategy';
 import { WalletStrategy } from './strategies/wallet.strategy';
 import { JwtAuthGuard } from './guards/jwt-auth.guard';
 import { RolesGuard } from './guards/roles.guard';
+import { jwtModuleConfig } from '../config/jwt.config.js';
 
 /**
  * #971: Self-contained Auth module.
@@ -18,16 +18,7 @@ import { RolesGuard } from './guards/roles.guard';
 @Module({
   imports: [
     PassportModule.register({ defaultStrategy: 'jwt' }),
-    JwtModule.registerAsync({
-      imports: [ConfigModule],
-      useFactory: (configService: ConfigService) => ({
-        secret: configService.get('JWT_SECRET', 'dev-secret'),
-        signOptions: {
-          expiresIn: configService.get('JWT_ACCESS_TTL', '900'),
-        },
-      }),
-      inject: [ConfigService],
-    }),
+    JwtModule.registerAsync(jwtModuleConfig),
   ],
   controllers: [AuthController],
   providers: [AuthService, JwtStrategy, WalletStrategy, JwtAuthGuard, RolesGuard],

backend/src/auth/auth.service.ts

@@ -4,6 +4,8 @@ import { ConfigService } from '@nestjs/config';
 import { v4 as uuidv4 } from 'uuid';
 import { JwtAccessTokenPayload } from '../interfaces/jwt-payload.interface';
 import { WalletStrategy } from '../strategies/wallet.strategy';
+import { AuthRole } from '../common/enums/auth-role.enum.js';
+import { ROLE_PERMISSIONS } from '../common/constants/role-permissions.constant.js';
 
 /**
  * #971-978: Auth service handling wallet login, JWT lifecycle, and session management.
@@ -106,6 +108,7 @@ export class AuthService {
     const refreshTtl = parseInt(this.configService.get('JWT_REFRESH_TTL', '604800'), 10); // 7 days
 
     const roles = await this.resolveRoles(walletAddress);
+    const permissions = this.resolvePermissions(roles);
 
     const accessPayload: JwtAccessTokenPayload = {
       sub: walletAddress,
@@ -114,6 +117,7 @@ export class AuthService {
       iat: Math.floor(Date.now() / 1000),
       exp: Math.floor(Date.now() / 1000) + accessTtl,
       roles,
+      permissions,
     };
 
     const accessToken = await this.jwtService.signAsync(accessPayload);
@@ -199,10 +203,23 @@ export class AuthService {
     // In production: persist to database via UsersService
   }
 
-  private async resolveRoles(walletAddress: string): Promise<string[]> {
+  private async resolveRoles(walletAddress: string): Promise<AuthRole[]> {
     // In production: query from database
     // Default role for all authenticated users
-    return ['MENTEE'];
+    return [AuthRole.MENTEE];
+  }
+
+  /**
+   * #974: Resolve the union of permissions granted by a set of roles.
+   */
+  private resolvePermissions(roles: AuthRole[]): string[] {
+    const permissions = new Set<string>();
+    for (const role of roles) {
+      for (const permission of ROLE_PERMISSIONS[role] ?? []) {
+        permissions.add(permission);
+      }
+    }
+    return Array.from(permissions);
   }
 
   private cleanExpiredNonces(): void {

backend/src/auth/guards/jwt-auth.guard.ts

@@ -4,7 +4,6 @@ import {
   Injectable,
   UnauthorizedException,
 } from '@nestjs/common';
-import { ConfigService } from '@nestjs/config';
 import { JwtService } from '@nestjs/jwt';
 import { Request } from 'express';
 import { JwtAccessTokenPayload } from '../interfaces/jwt-payload.interface';
@@ -25,7 +24,6 @@ export interface JwtGuardOptions {
 export class JwtAuthGuard implements CanActivate {
   constructor(
     private readonly jwtService: JwtService,
-    private readonly configService: ConfigService,
     private readonly blacklistCheck?: (jti: string) => Promise<boolean>,
   ) {}
 
@@ -41,9 +39,8 @@ export class JwtAuthGuard implements CanActivate {
     }
 
     try {
-      const payload = await this.jwtService.verifyAsync<JwtAccessTokenPayload>(token, {
-        secret: this.configService.get<string>('JWT_SECRET', 'dev-secret'),
-      });
+      const payload =
+        await this.jwtService.verifyAsync<JwtAccessTokenPayload>(token);
 
       // #981: Check Redis blacklist for revoked tokens
       if (this.blacklistCheck && payload.jti) {

backend/src/auth/interfaces/jwt-payload.interface.ts

@@ -5,4 +5,5 @@ export interface JwtAccessTokenPayload {
   iat: number;
   exp: number;
   roles?: string[];
+  permissions?: string[];
 }

backend/src/auth/strategies/jwt.strategy.ts

@@ -29,6 +29,7 @@ export class JwtStrategy extends PassportStrategy(Strategy) {
       iat: payload.iat,
       exp: payload.exp,
       roles: payload.roles || [],
+      permissions: payload.permissions || [],
     };
   }
 }

backend/src/common/constants/role-permissions.constant.ts

@@ -0,0 +1,15 @@
+import { AuthRole } from '../enums/auth-role.enum.js';
+import { Permission } from '../enums/permission.enum.js';
+
+export const ROLE_PERMISSIONS: Record<AuthRole, Permission[]> = {
+  [AuthRole.USER]: [Permission.PROFILE_READ],
+  [AuthRole.MENTEE]: [Permission.PROFILE_READ, Permission.MENTEE_PROFILE_WRITE],
+  [AuthRole.MENTOR]: [Permission.PROFILE_READ, Permission.MENTOR_PROFILE_WRITE],
+  [AuthRole.ADMIN]: [
+    Permission.PROFILE_READ,
+    Permission.PROFILE_WRITE,
+    Permission.MENTOR_PROFILE_WRITE,
+    Permission.MENTEE_PROFILE_WRITE,
+    Permission.USER_MANAGE,
+  ],
+};

backend/src/common/enums/permission.enum.ts

@@ -0,0 +1,7 @@
+export enum Permission {
+  PROFILE_READ = 'profile:read',
+  PROFILE_WRITE = 'profile:write',
+  MENTOR_PROFILE_WRITE = 'mentor_profile:write',
+  MENTEE_PROFILE_WRITE = 'mentee_profile:write',
+  USER_MANAGE = 'user:manage',
+}

backend/src/config/jwt.config.ts

@@ -0,0 +1,26 @@
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { JwtModuleOptions } from '@nestjs/jwt';
+import { Algorithm } from 'jsonwebtoken';
+
+export const jwtModuleConfig = {
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService): JwtModuleOptions => {
+    const algorithm = config.get<Algorithm>('JWT_ALGORITHM', 'HS256');
+
+    if (algorithm === 'RS256') {
+      return {
+        privateKey: config.get<string>('JWT_PRIVATE_KEY'),
+        publicKey: config.get<string>('JWT_PUBLIC_KEY'),
+        signOptions: { algorithm },
+        verifyOptions: { algorithms: [algorithm] },
+      };
+    }
+
+    return {
+      secret: config.get<string>('JWT_SECRET', 'dev-secret'),
+      signOptions: { algorithm },
+      verifyOptions: { algorithms: [algorithm] },
+    };
+  },
+};

backend/src/users/users.module.ts

@@ -1,7 +1,7 @@
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { JwtModule } from '@nestjs/jwt';
-import { ConfigModule, ConfigService } from '@nestjs/config';
+import { ConfigModule } from '@nestjs/config';
 import { UsersController } from './users.controller.js';
 import { UsersService } from './users.service.js';
 import { User } from './entities/user.entity.js';
@@ -10,18 +10,12 @@ import { MentorProfile } from './entities/mentor-profile.entity.js';
 import { MenteeProfile } from './entities/mentee-profile.entity.js';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard.js';
 import { RolesGuard } from '../auth/guards/roles.guard.js';
+import { jwtModuleConfig } from '../config/jwt.config.js';
 
 @Module({
   imports: [
     TypeOrmModule.forFeature([User, Role, MentorProfile, MenteeProfile]),
-    JwtModule.registerAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        secret: config.get<string>('JWT_SECRET'),
-        signOptions: { expiresIn: '1h' },
-      }),
-    }),
+    JwtModule.registerAsync(jwtModuleConfig),
     ConfigModule,
   ],
   controllers: [UsersController],