prime-sdk 3.0.7 → 3.0.8-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prime-sdk",
-  "version": "3.0.7",
+  "version": "3.0.8-beta.0",
   "description": "swiss army knife",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,6 +37,8 @@
     "@nestjs/platform-express": "^11.1.17",
     "@smithy/node-http-handler": "^3.3.1",
     "ioredis": "^5.4.1",
+    "jsonwebtoken": "^9.0.3",
+    "jwks-rsa": "^4.0.1",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.1"
   },
@@ -50,6 +52,7 @@
     "@nestjs/testing": "^11.1.17",
     "@types/express": "^4.17.17",
     "@types/jest": "^29.5.2",
+    "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^20.3.1",
     "@types/supertest": "^6.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",

package/src/index.ts

@@ -33,6 +33,28 @@ import {
   TypeRedis,
   PubSubRedis,
 } from './external/redis/types/ioredis.types';
+import { EntraIDModule, ENTRA_ID_CONFIG } from './lib/entraID/entraID.module';
+import type { EntraIDModuleOptions } from './lib/entraID/entraID.module';
+import { EntraIDService } from './lib/entraID/entraID.service';
+import { EntraAuthGuard } from './lib/entraID/guards/entra-auth.guard';
+import { RolesGuard } from './lib/entraID/guards/roles.guard';
+import { InternalTokenService } from './lib/entraID/internal-token/internal-token.service';
+import { CurrentUser } from './lib/entraID/decorators/current-user.decorator';
+import { Public } from './lib/entraID/decorators/public.decorator';
+import { Roles } from './lib/entraID/decorators/roles.decorator';
+import { CookieUtils, TokenUtils } from './lib/entraID/utils';
+import { SecurityService } from './lib/entraID/security/security.service';
+import { EntraIDException } from './lib/entraID/customError/entraID.exception';
+import type {
+  EntraUser,
+  AuthResult,
+  CallbackParams,
+  TokenEnrichmentContext,
+} from './lib/entraID/types/entraID.type';
+import type {
+  EntraIDSetup,
+  EntraIDAsyncOptions,
+} from './lib/entraID/types/entraID-module-init.types';
 
 import { SNSSetup } from './external/aws/sns/sns.provider';
 
@@ -64,4 +86,24 @@ export {
   ClusterRedisSetup,
   TypeRedis,
   PubSubRedis,
+  EntraIDModule,
+  EntraIDModuleOptions,
+  ENTRA_ID_CONFIG,
+  EntraIDService,
+  EntraAuthGuard,
+  RolesGuard,
+  InternalTokenService,
+  CurrentUser,
+  Public,
+  Roles,
+  CookieUtils,
+  TokenUtils,
+  SecurityService,
+  EntraIDException,
+  EntraIDSetup,
+  EntraIDAsyncOptions,
+  EntraUser,
+  AuthResult,
+  CallbackParams,
+  TokenEnrichmentContext,
 };

package/src/lib/entraID/customError/entraID.exception.ts

@@ -0,0 +1,43 @@
+const entraIDErrorMessages: Record<string, string> = {
+  INVALID_CONFIG: 'Configuração inválida do módulo EntraID',
+  TENANT_NOT_FOUND: 'Tenant não encontrado na configuração do EntraID',
+  INVALID_SECRET: 'Em Produção é necessário um secret válido',
+  STATE_MISMATCH: 'State OAuth inválido ou expirado',
+  TOKEN_INVALID_HEADER: 'Header da chave publica inválido',
+  PAYLOAD_ID_TOKEN_INVALID: 'Payload decodificado é inválido',
+  INVALID_NONCE: 'Nonce retornado é diferente do esperado',
+  CODE_EXCHANGE_FAILED: 'Falha ao trocar o código de autorização pelo token',
+  TOKEN_EXPIRED: 'Token de acesso expirado',
+  TOKEN_INVALID: 'Token de acesso inválido',
+  RESERVED_CLAIM_OVERRIDE:
+    'enrichTokenPayload tentou sobrescrever um claim reservado (sub/iss/aud/exp/iat/nbf/jti/groups)',
+  TOKEN_AUDIENCE_INVALID: 'Audience do token não corresponde ao esperado',
+  JWKS_FETCH_FAILED: 'Falha ao buscar chaves públicas do Azure',
+  JWKS_KEY_NOT_FOUND: 'Chave pública não encontrada no JWKS',
+  GRAPH_FETCH_FAILED: 'Falha ao buscar dados do usuário no Microsoft Graph',
+  GRAPH_USER_NOT_FOUND: 'Usuário não encontrado no Microsoft Entra ID',
+  SECURITY_PATH_TRAVERSAL: 'Tentativa de path traversal detectada',
+  SECURITY_NULL_BYTE: 'Caractere nulo detectado na entrada',
+  SECURITY_INVALID_CHARS: 'Caracteres inválidos ou perigosos na entrada',
+  SECURITY_OPEN_REDIRECT: 'Redirecionamento para URL não autorizada',
+  SECURITY_INVALID_URL: 'URL inválida',
+  OAUTH_PROVIDER_ERROR: 'Erro retornado pelo provedor OAuth',
+  OAUTH_MISSING_PARAMS: 'Parâmetros obrigatórios ausentes no callback OAuth',
+  REFRESH_TOKEN_FAILED: 'Falha ao renovar o token de acesso',
+  REVOKE_SESSIONS_FAILED:
+    'Falha ao revogar sessões do usuário no Microsoft Entra ID',
+  UNKNOWN_ERROR: 'Erro desconhecido',
+};
+
+export class EntraIDException extends Error {
+  public readonly message: string;
+
+  constructor(public readonly code: string) {
+    const message =
+      entraIDErrorMessages[code] ?? entraIDErrorMessages['UNKNOWN_ERROR'];
+    super(message);
+    this.message = message;
+    this.name = 'EntraIDException';
+    Object.setPrototypeOf(this, EntraIDException.prototype);
+  }
+}

package/src/lib/entraID/decorators/current-user.decorator.ts

@@ -0,0 +1,8 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const CurrentUser = createParamDecorator(
+  <T = Record<string, unknown>>(_data: unknown, ctx: ExecutionContext): T => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.user as T;
+  },
+);

package/src/lib/entraID/decorators/public.decorator.ts

@@ -0,0 +1,5 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

package/src/lib/entraID/decorators/roles.decorator.ts

@@ -0,0 +1,5 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const ROLES_KEY = 'roles';
+
+export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);

package/src/lib/entraID/entraID.constants.ts

@@ -0,0 +1,2 @@
+export const ENTRA_ID_CONFIG = 'ENTRA_ID_CONFIG';
+export const MICROSOFT_AUTHORITY_URL = 'https://login.microsoftonline.com';

package/src/lib/entraID/entraID.module.ts

@@ -0,0 +1,78 @@
+import {
+  DynamicModule,
+  Module,
+  ModuleMetadata,
+  Provider,
+  Type,
+} from '@nestjs/common';
+import { EntraIDService } from './entraID.service';
+import { EntraAuthGuard } from './guards/entra-auth.guard';
+import { InternalTokenService } from './internal-token/internal-token.service';
+import { MicrosoftModule } from './microsoft/microsoft.module';
+import { SecurityModule } from './security/security.module';
+import { ENTRA_ID_CONFIG } from './entraID.constants';
+import {
+  EntraIDAsyncOptions,
+  EntraIDSetup,
+} from './types/entraID-module-init.types';
+
+export { ENTRA_ID_CONFIG };
+
+export type EntraIDModuleOptions = {
+  internalTokenService?: Type<InternalTokenService>;
+  imports?: ModuleMetadata['imports'];
+};
+
+@Module({})
+export class EntraIDModule {
+  private static buildModule(
+    configProvider: Provider,
+    imports: ModuleMetadata['imports'] = [],
+    options: EntraIDModuleOptions = {},
+  ): DynamicModule {
+    const tokenServiceClass =
+      options.internalTokenService ?? InternalTokenService;
+
+    return {
+      global: true,
+      module: EntraIDModule,
+      imports: [...imports, ...(options.imports ?? []), MicrosoftModule, SecurityModule],
+      providers: [
+        configProvider,
+        tokenServiceClass,
+        { provide: InternalTokenService, useExisting: tokenServiceClass },
+        EntraIDService,
+        EntraAuthGuard,
+      ],
+      exports: [
+        ENTRA_ID_CONFIG,
+        InternalTokenService,
+        EntraIDService,
+        EntraAuthGuard,
+      ],
+    };
+  }
+
+  static forRoot(params: EntraIDSetup, options?: EntraIDModuleOptions): DynamicModule {
+    return this.buildModule(
+      { provide: ENTRA_ID_CONFIG, useValue: params },
+      [],
+      options,
+    );
+  }
+
+  static forRootAsync(
+    paramsAsync: EntraIDAsyncOptions,
+    options?: EntraIDModuleOptions,
+  ): DynamicModule {
+    return this.buildModule(
+      {
+        provide: ENTRA_ID_CONFIG,
+        useFactory: paramsAsync.useFactory,
+        inject: paramsAsync.inject ?? [],
+      },
+      paramsAsync.imports ?? [],
+      options,
+    );
+  }
+}

package/src/lib/entraID/entraID.service.ts

@@ -0,0 +1,206 @@
+import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
+import jwt, { Jwt } from 'jsonwebtoken';
+import jwksClient from 'jwks-rsa';
+import { ENTRA_ID_CONFIG, MICROSOFT_AUTHORITY_URL } from './entraID.constants';
+import { InternalTokenService } from './internal-token/internal-token.service';
+import { MicrosoftService } from './microsoft/microsoft.service';
+import { SecurityService } from './security/security.service';
+import {
+  AuthResult,
+  CallbackParams,
+  CreateStateNonce,
+  EntraUser,
+  IdTokenPayload,
+  UrlRedirectSso,
+} from './types/entraID.type';
+import { EntraIDException } from './customError/entraID.exception';
+import { EntraIDSetup } from './types/entraID-module-init.types';
+import { CryptoUtils } from './utils/crypto.utils';
+import { IEntraIDService } from './interfaces/entraID-service.interface';
+
+const STATE_TTL_MS = 600_000;
+
+@Injectable()
+export class EntraIDService implements OnModuleInit, IEntraIDService {
+  private jwksClientRsa: ReturnType<typeof jwksClient>;
+
+  constructor(
+    @Inject(ENTRA_ID_CONFIG) protected readonly config: EntraIDSetup,
+    protected readonly microsoftService: MicrosoftService,
+    protected readonly securityService: SecurityService,
+    protected readonly internalTokenService: InternalTokenService,
+  ) {}
+
+  onModuleInit() {
+    const { tenantID, clientID, clientSecret, stateSecret, redirectUri } =
+      this.config;
+
+    if (
+      !tenantID ||
+      !clientID ||
+      !clientSecret ||
+      !stateSecret ||
+      !redirectUri
+    ) {
+      throw new EntraIDException('INVALID_CONFIG');
+    }
+
+    const authorityUrl = this.config.authorityUrl ?? MICROSOFT_AUTHORITY_URL;
+
+    this.jwksClientRsa = jwksClient({
+      jwksUri: `${authorityUrl}/${tenantID}/discovery/v2.0/keys`,
+      cache: true,
+      cacheMaxAge: 10 * 60 * 1000,
+    });
+  }
+
+  async handleCallback(params: CallbackParams): Promise<AuthResult> {
+    this.securityService.validateCallbackParams(params);
+
+    const nonce = this.verifyStateAndReturnNonce(params.state!);
+    const tokens = await this.microsoftService.exchangeCode(params.code!);
+    const payload = await this.verifyIdToken(tokens.id_token, nonce);
+
+    const email = payload.preferred_username ?? payload.email ?? payload.upn;
+    if (!email) {
+      throw new EntraIDException('PAYLOAD_ID_TOKEN_INVALID');
+    }
+
+    const result = await this.buildUserJwt(
+      tokens.access_token,
+      email,
+      payload.name,
+    );
+    return { ...result, refreshToken: tokens.refresh_token };
+  }
+
+  async refresh(refreshToken: string): Promise<AuthResult> {
+    const tokens = await this.microsoftService.refreshToken(refreshToken);
+    const result = await this.buildUserJwt(tokens.access_token, '', '');
+    return { ...result, refreshToken: tokens.refresh_token };
+  }
+
+  async logout(userId: string): Promise<void> {
+    await this.microsoftService.revokeUserSessions(userId);
+  }
+
+  async initiateLogin(): Promise<UrlRedirectSso> {
+    const { state, nonce } = this.createSignedState();
+    const { clientID, redirectUri, tenantID, scope, prompt } = this.config;
+    const authorityUrl = this.config.authorityUrl ?? MICROSOFT_AUTHORITY_URL;
+
+    const params = new URLSearchParams({
+      client_id: clientID,
+      response_type: 'code',
+      redirect_uri: redirectUri,
+      response_mode: 'form_post',
+      scope: scope ?? 'openid profile email User.Read GroupMember.Read.All',
+      state,
+      nonce,
+      prompt: prompt ?? 'select_account',
+    });
+
+    return `${authorityUrl}/${tenantID}/oauth2/v2.0/authorize?${params.toString()}`;
+  }
+
+  decodeLocalToken(token: string): EntraUser {
+    return this.internalTokenService.verify(token);
+  }
+
+  protected async verifyIdToken(
+    idToken: string,
+    nonce: string,
+  ): Promise<IdTokenPayload> {
+    const decoded = jwt.decode(idToken, { complete: true }) as Jwt | null;
+
+    if (!decoded?.header) {
+      throw new EntraIDException('TOKEN_INVALID_HEADER');
+    }
+
+    const publicKey = await CryptoUtils.getPublicKeyRsa(
+      decoded.header.kid,
+      this.jwksClientRsa,
+    );
+
+    const expectedIssuers: [string, ...string[]] = [
+      `https://login.microsoftonline.com/${this.config.tenantID}/v2.0`,
+      `https://sts.windows.net/${this.config.tenantID}/`,
+    ];
+
+    const payload = jwt.verify(idToken, publicKey, {
+      algorithms: ['RS256'],
+      audience: this.config.clientID!,
+      issuer: expectedIssuers,
+    }) as unknown as IdTokenPayload;
+
+    if (payload.nonce !== nonce) {
+      throw new EntraIDException('INVALID_NONCE');
+    }
+
+    return payload;
+  }
+
+  protected async buildUserJwt(
+    accessToken: string,
+    email: string,
+    name: string,
+  ): Promise<AuthResult> {
+    const msUser = await this.microsoftService.getMe(accessToken);
+
+    let groups: { displayName: string }[] = [];
+    try {
+      const raw = await this.microsoftService.getMemberOf(accessToken);
+      groups = raw.filter((g) => !!g.displayName);
+    } catch {}
+
+    const user: EntraUser = {
+      entraId: msUser.id,
+      email: msUser.mail ?? msUser.userPrincipalName ?? email,
+      name: msUser.displayName ?? name,
+      tenantId: this.config.tenantID,
+      matricula: msUser.employeeId,
+      groups,
+    };
+
+    const token = await this.internalTokenService.sign({ user, accessToken });
+
+    return { token, user };
+  }
+
+  protected createSignedState(): CreateStateNonce {
+    const { stateSecret } = this.config;
+    const nonce = CryptoUtils.generateHash();
+    const payload = Buffer.from(
+      JSON.stringify({ nonce, ts: Date.now() }),
+    ).toString('base64url');
+    const state = CryptoUtils.createSignedPayloadWithHMAC(payload, stateSecret);
+    return { nonce, state };
+  }
+
+  protected verifyStateAndReturnNonce(state: string): string {
+    const { stateSecret } = this.config;
+    const parts = state.split('.');
+
+    CryptoUtils.verifyPayloadWithHMAC(parts, stateSecret);
+
+    const payload = parts[0];
+
+    let nonce: string;
+    let ts: number;
+    try {
+      const parsed = JSON.parse(
+        Buffer.from(payload, 'base64url').toString(),
+      ) as { nonce: string; ts: number };
+      nonce = parsed.nonce;
+      ts = parsed.ts;
+    } catch {
+      throw new EntraIDException('STATE_MISMATCH');
+    }
+
+    if (Date.now() - ts > STATE_TTL_MS) {
+      throw new EntraIDException('STATE_MISMATCH');
+    }
+
+    return nonce;
+  }
+}

package/src/lib/entraID/guards/entra-auth.guard.ts

@@ -0,0 +1,77 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import type { Request } from 'express';
+import { InternalTokenService } from '../internal-token/internal-token.service';
+import { EntraIDException } from '../customError/entraID.exception';
+import { EntraUser } from '../types/entraID.type';
+import { Reflector } from '@nestjs/core';
+import { IS_PUBLIC_KEY } from '../decorators/public.decorator';
+
+@Injectable()
+export class EntraAuthGuard implements CanActivate {
+  constructor(
+    private readonly internalTokenService: InternalTokenService,
+    private readonly reflector: Reflector,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isPublic) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const token = this.extractToken(request);
+
+    if (!token) throw new UnauthorizedException();
+
+    let payload: EntraUser;
+    try {
+      payload = this.internalTokenService.verify(token);
+    } catch (error) {
+      if (error instanceof EntraIDException) {
+        throw new UnauthorizedException(error.message);
+      }
+      throw error;
+    }
+
+    const revoke = await this.isTokenRevoked(payload, request);
+
+    if (revoke) {
+      throw new UnauthorizedException('TOKEN_REVOKED');
+    }
+
+    request.user = await this.transformPayload(payload);
+
+    return true;
+  }
+
+  protected async isTokenRevoked(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _payload: EntraUser,
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _request: Request,
+  ): Promise<boolean> {
+    return false;
+  }
+
+  protected async transformPayload(payload: EntraUser): Promise<unknown> {
+    return payload;
+  }
+
+  protected extractToken(request: {
+    headers: { authorization?: string };
+    cookies?: { auth_token?: string };
+  }): string | undefined {
+    const auth = request.headers.authorization;
+    if (auth?.startsWith('Bearer ')) return auth.slice(7);
+    return request.cookies?.auth_token;
+  }
+}

package/src/lib/entraID/guards/roles.guard.ts

@@ -0,0 +1,34 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ROLES_KEY } from '../decorators/roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const required = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (!required?.length) return true;
+
+    const { user } = context.switchToHttp().getRequest();
+    const userGroups: string[] = (user?.groups ?? []).map(
+      (g: { displayName: string }) => g.displayName,
+    );
+
+    const allowed = required.some((role) => userGroups.includes(role));
+    if (!allowed) {
+      throw new ForbiddenException('INVALID_GROUP');
+    }
+
+    return true;
+  }
+}

package/src/lib/entraID/interfaces/entraID-service.interface.ts

@@ -0,0 +1,12 @@
+import {
+  AuthResult,
+  CallbackParams,
+  UrlRedirectSso,
+} from '../types/entraID.type';
+
+export interface IEntraIDService {
+  handleCallback(params: CallbackParams): Promise<AuthResult>;
+  initiateLogin(): Promise<UrlRedirectSso>;
+  refresh(refreshToken: string): Promise<AuthResult>;
+  logout(userId: string): Promise<void>;
+}

package/src/lib/entraID/internal-token/internal-token.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { InternalTokenService } from './internal-token.service';
+
+@Module({
+  providers: [InternalTokenService],
+  exports: [InternalTokenService],
+})
+export class InternalTokenModule {}

package/src/lib/entraID/internal-token/internal-token.service.ts

@@ -0,0 +1,66 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import jwt from 'jsonwebtoken';
+import { ENTRA_ID_CONFIG } from '../entraID.constants';
+import { EntraIDException } from '../customError/entraID.exception';
+import { EntraIDSetup } from '../types/entraID-module-init.types';
+import { EntraUser, TokenEnrichmentContext } from '../types/entraID.type';
+
+@Injectable()
+export class InternalTokenService {
+  constructor(@Inject(ENTRA_ID_CONFIG) private readonly config: EntraIDSetup) {}
+
+  async sign(context: TokenEnrichmentContext): Promise<string> {
+    const customClaims = await this.enrichTokenPayload(context);
+
+    this.assertNoReservedClaimCollision(customClaims);
+
+    return jwt.sign(
+      { jti: randomUUID(), ...context.user, ...customClaims },
+      this.config.jwtSecret,
+      {
+        algorithm: 'HS256',
+        expiresIn: (this.config.jwtExpiresIn ??
+          '8h') as jwt.SignOptions['expiresIn'],
+      },
+    );
+  }
+
+  protected async enrichTokenPayload(
+    _context: TokenEnrichmentContext,
+  ): Promise<Record<string, unknown>> {
+    return {};
+  }
+
+  verify(token: string): EntraUser {
+    try {
+      return jwt.verify(token, this.config.jwtSecret, {
+        algorithms: ['HS256'],
+      }) as unknown as EntraUser;
+    } catch (err) {
+      if (err instanceof jwt.TokenExpiredError) {
+        throw new EntraIDException('TOKEN_EXPIRED');
+      }
+      throw new EntraIDException('TOKEN_INVALID');
+    }
+  }
+
+  private assertNoReservedClaimCollision(
+    customClaims: Record<string, unknown>,
+  ) {
+    const reserved = [
+      'sub',
+      'iss',
+      'aud',
+      'exp',
+      'iat',
+      'nbf',
+      'jti',
+      'groups',
+    ];
+    const collision = reserved.find((claim) => claim in customClaims);
+    if (collision) {
+      throw new EntraIDException('RESERVED_CLAIM_OVERRIDE');
+    }
+  }
+}

package/src/lib/entraID/microsoft/microsoft.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { MicrosoftService } from './microsoft.service';
+
+@Module({
+  providers: [MicrosoftService],
+  exports: [MicrosoftService],
+})
+export class MicrosoftModule {}