@koalarx/nest 3.1.49 → 4.0.1

package/koala-nest/src/host/security/guards/profiles.guard.ts

@@ -0,0 +1,32 @@
+import { AuthProfile } from '@/core/auth/auth-profile.enum';
+import { AuthenticatedUser } from '@/core/auth/jwt-claims';
+import { PROFILES_KEY } from '@/host/decorators/restriction-by-profile.decorator';
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+
+@Injectable()
+export class ProfilesGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext) {
+    const profiles = this.reflector.getAllAndOverride<AuthProfile[]>(
+      PROFILES_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!profiles?.length) {
+      return true;
+    }
+
+    const request = context
+      .switchToHttp()
+      .getRequest<{ user?: AuthenticatedUser }>();
+    const profile = request.user?.profile;
+
+    if (!profile) {
+      return false;
+    }
+
+    return profiles.includes(profile);
+  }
+}

package/koala-nest/src/host/security/security.module.ts

@@ -0,0 +1,62 @@
+import { AuthHttp } from '@/core/auth/auth.constants';
+import { Env } from '@/core/env';
+import { OAuthProviderRegistry } from '@/core/auth/oauth-provider.registry';
+import {
+  IJwtTokenService,
+  IOAuth2Service,
+} from '@/domain/auth/services/iauth.service';
+import { JwtTokenService } from '@/infra/auth/jwt-token.service';
+import { OAuth2AuthService } from '@/infra/auth/oauth2-auth.service';
+import { InfraModule } from '@/infra/infra.module';
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { JwtModule } from '@nestjs/jwt';
+import { PassportModule } from '@nestjs/passport';
+import { JwtStrategy } from './strategies/jwt.strategy';
+import { AuthGuard } from './guards/auth.guard';
+import { ProfilesGuard } from './guards/profiles.guard';
+
+@Module({
+  imports: [
+    InfraModule,
+    PassportModule.register({ defaultStrategy: 'jwt' }),
+    JwtModule.registerAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      global: true,
+      useFactory(config: ConfigService<Env, true>) {
+        const privateKey = config.get('JWT_PRIVATE_KEY', { infer: true });
+        const publicKey = config.get('JWT_PUBLIC_KEY', { infer: true });
+
+        if (!privateKey || !publicKey) {
+          throw new Error(
+            'JWT_PRIVATE_KEY e JWT_PUBLIC_KEY são obrigatórios quando o módulo de autenticação está ativo',
+          );
+        }
+
+        return {
+          signOptions: { algorithm: AuthHttp.JWT_ALGORITHM },
+          privateKey: Buffer.from(privateKey, 'base64'),
+          publicKey: Buffer.from(publicKey, 'base64'),
+        };
+      },
+    }),
+  ],
+  providers: [
+    OAuthProviderRegistry,
+    JwtStrategy,
+    AuthGuard,
+    ProfilesGuard,
+    { provide: IJwtTokenService, useClass: JwtTokenService },
+    { provide: IOAuth2Service, useClass: OAuth2AuthService },
+  ],
+  exports: [
+    IJwtTokenService,
+    IOAuth2Service,
+    OAuthProviderRegistry,
+    JwtModule,
+    AuthGuard,
+    ProfilesGuard,
+  ],
+})
+export class SecurityModule {}

package/koala-nest/src/host/security/strategies/jwt.strategy.ts

@@ -0,0 +1,61 @@
+import { AuthHttp } from '@/core/auth/auth.constants';
+import { isAuthRefreshRoute } from '@/core/auth/auth-routes';
+import { jwtPayloadSchema } from '@/core/auth/jwt-claims';
+import { parseJwtExpiresInToSeconds } from '@/core/auth/parse-jwt-expires-in';
+import { EnvService } from '@/infra/common/env.service';
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { Request } from 'express';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
+  private readonly accessTokenTtlSeconds: number;
+
+  constructor(env: EnvService) {
+    const publicKey = env.get('JWT_PUBLIC_KEY');
+
+    if (!publicKey) {
+      throw new Error(
+        'JWT_PUBLIC_KEY é obrigatório quando o módulo de autenticação está ativo',
+      );
+    }
+
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKey: Buffer.from(publicKey, 'base64'),
+      algorithms: [AuthHttp.JWT_ALGORITHM],
+      passReqToCallback: true,
+    });
+
+    this.accessTokenTtlSeconds = parseJwtExpiresInToSeconds(
+      env.get('JWT_ACCESS_TOKEN_EXPIRES_IN'),
+    );
+  }
+
+  private isLongLivedToken(payload: { exp?: number; iat?: number }): boolean {
+    if (!payload.exp || !payload.iat) {
+      return false;
+    }
+
+    return payload.exp - payload.iat > this.accessTokenTtlSeconds;
+  }
+
+  validate(req: Request, payload: { sub: string; exp?: number; iat?: number }) {
+    const isRefreshRoute = isAuthRefreshRoute(req.url);
+    const parsed = jwtPayloadSchema.parse(payload);
+
+    if (this.isLongLivedToken(payload) && !isRefreshRoute) {
+      throw new UnauthorizedException(
+        'Refresh token não pode ser usado como access token',
+      );
+    }
+
+    const token = req
+      .get('Authorization')
+      ?.replace(AuthHttp.BEARER_PREFIX, '')
+      .trim();
+
+    return { sub: parsed.sub, refreshToken: token };
+  }
+}

package/koala-nest/src/infra/auth/jwt-token.service.ts

@@ -0,0 +1,48 @@
+import { JwtClaims } from '@/core/auth/jwt-claims';
+import { IJwtTokenService } from '@/domain/auth/services/iauth.service';
+import { Injectable } from '@nestjs/common';
+import { JwtService, type JwtSignOptions } from '@nestjs/jwt';
+import { randomUUID } from 'node:crypto';
+import { EnvService } from '@/infra/common/env.service';
+
+@Injectable()
+export class JwtTokenService implements IJwtTokenService {
+  constructor(
+    private readonly jwtService: JwtService,
+    private readonly env: EnvService,
+  ) {}
+
+  private signOptions(
+    key: 'JWT_ACCESS_TOKEN_EXPIRES_IN' | 'JWT_REFRESH_TOKEN_EXPIRES_IN',
+  ): JwtSignOptions {
+    return {
+      expiresIn: this.env.get(key) as JwtSignOptions['expiresIn'],
+    };
+  }
+
+  signAccessToken(claims: JwtClaims): string {
+    return this.jwtService.sign(
+      { ...claims, jti: randomUUID() },
+      this.signOptions('JWT_ACCESS_TOKEN_EXPIRES_IN'),
+    );
+  }
+
+  signRefreshToken(claims: JwtClaims): string {
+    return this.jwtService.sign(
+      { ...claims, jti: randomUUID() },
+      this.signOptions('JWT_REFRESH_TOKEN_EXPIRES_IN'),
+    );
+  }
+
+  signTokenPair(claims: JwtClaims) {
+    const accessToken = this.signAccessToken(claims);
+    const refreshToken = this.signRefreshToken(claims);
+
+    return {
+      accessToken,
+      access_token: accessToken,
+      refreshToken,
+      refresh_token: refreshToken,
+    };
+  }
+}

package/koala-nest/src/infra/auth/oauth2-auth.service.ts

@@ -0,0 +1,208 @@
+import { AuthHttp } from '@/core/auth/auth.constants';
+import {
+  CacheKeyPrefix,
+  CacheTtlSeconds,
+} from '@/core/constants/cache.constants';
+import { randomBytes } from 'node:crypto';
+import { AuthProfile } from '@/core/auth/auth-profile.enum';
+import { OAuthProviderRegistry } from '@/core/auth/oauth-provider.registry';
+import type { OAuthProviderEnvConfig } from '@/core/auth/oauth-provider.registry';
+import { AuthProviderConfigResponseType } from '@/core/types/auth-provider-config-response.type';
+import { AuthProviderConfigDto } from '@/domain/auth/dtos/auth-provider-config.dto';
+import { OAuthUserInfoDto } from '@/domain/auth/dtos/oauth-user-info.dto';
+import { IOAuth2Service } from '@/domain/auth/services/iauth.service';
+import { EnvService } from '@/infra/common/env.service';
+import { ICacheService } from '@/domain/common/icache.service';
+import { resolveApiHost } from '@/core/utils/resolve-api-host';
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+
+const OAUTH_STATE_TTL_SECONDS = CacheTtlSeconds.OAUTH2_STATE;
+
+@Injectable()
+export class OAuth2AuthService implements IOAuth2Service {
+  constructor(
+    private readonly env: EnvService,
+    private readonly providerRegistry: OAuthProviderRegistry,
+    private readonly cache: ICacheService,
+  ) {}
+
+  private generateState() {
+    return randomBytes(24).toString('hex');
+  }
+
+  private stateCacheKey(state: string) {
+    return `${CacheKeyPrefix.OAUTH2_STATE}${state}`;
+  }
+
+  private getApiHost() {
+    return resolveApiHost(this.env.get('API_HOST'), this.env.get('PORT'));
+  }
+
+  /** Grava o state temporariamente para validar autenticidade no POST /oauth2/token (anti-CSRF). */
+  private async rememberState(provider: string, state: string) {
+    await this.cache.set(
+      this.stateCacheKey(state),
+      JSON.stringify({ provider }),
+      OAUTH_STATE_TTL_SECONDS,
+    );
+  }
+
+  private async validateState(provider: string, state: string) {
+    const raw = await this.cache.get(this.stateCacheKey(state));
+
+    if (!raw) {
+      throw new UnauthorizedException('State OAuth2 inválido ou expirado');
+    }
+
+    const entry = JSON.parse(raw) as { provider: string };
+
+    if (entry.provider !== provider) {
+      throw new UnauthorizedException('State OAuth2 inválido ou expirado');
+    }
+
+    await this.cache.invalidate(this.stateCacheKey(state));
+  }
+
+  private async resolveProviderConfig(
+    provider: string,
+  ): Promise<AuthProviderConfigDto> {
+    const providerConfig = this.providerRegistry.getProvider(provider);
+    const endpoints = await this.resolveOAuthEndpoints(providerConfig);
+
+    return AuthProviderConfigDto.from({
+      ...endpoints,
+      clientId: providerConfig.clientId,
+      clientSecret: providerConfig.clientSecret,
+      state: '',
+      redirectUri: `${this.getApiHost()}${providerConfig.redirectPath}`,
+      scope: providerConfig.scope,
+    });
+  }
+
+  private async resolveOAuthEndpoints(providerConfig: OAuthProviderEnvConfig) {
+    if (
+      providerConfig.authorizationUrl &&
+      providerConfig.tokenUrl &&
+      providerConfig.userInfoUrl
+    ) {
+      return {
+        authorizationUrl: providerConfig.authorizationUrl,
+        tokenUrl: providerConfig.tokenUrl,
+        userInfoUrl: providerConfig.userInfoUrl,
+      };
+    }
+
+    const discovery = await fetch(
+      `${providerConfig.domain}/.well-known/openid-configuration`,
+    ).then(
+      (response) => response.json() as Promise<AuthProviderConfigResponseType>,
+    );
+
+    return {
+      authorizationUrl: discovery.authorization_endpoint,
+      tokenUrl: discovery.token_endpoint,
+      userInfoUrl: discovery.userinfo_endpoint,
+    };
+  }
+
+  private async userInfo(
+    config: AuthProviderConfigDto,
+    accessToken: string,
+  ): Promise<OAuthUserInfoDto> {
+    const data = await fetch(config.userInfoUrl, {
+      headers: { Authorization: `${AuthHttp.BEARER_PREFIX}${accessToken}` },
+    }).then((response) => response.json() as Promise<Record<string, string>>);
+
+    const email = data.email ?? data.unique_name ?? data.upn ?? '';
+    const login =
+      data.samaccountname ??
+      data.preferred_username ??
+      (email ? email.split('@')[0] : (data.sub ?? ''));
+
+    return OAuthUserInfoDto.from({
+      login,
+      email,
+      name: data.name,
+      profile: AuthProfile.user,
+    });
+  }
+
+  private async exchangeAuthorizationCode(
+    provider: string,
+    code: string,
+    redirectUri?: string,
+  ): Promise<OAuthUserInfoDto> {
+    const config = await this.resolveProviderConfig(provider);
+
+    const formData = new URLSearchParams();
+    formData.append('code', code);
+    formData.append('redirect_uri', redirectUri ?? config.redirectUri);
+    formData.append('client_id', config.clientId);
+    formData.append('client_secret', config.clientSecret);
+    formData.append('grant_type', 'authorization_code');
+
+    const tokenResponse = await fetch(config.tokenUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: formData.toString(),
+    }).then((response) => response.json() as Promise<Record<string, string>>);
+
+    if (tokenResponse.error || !tokenResponse.access_token) {
+      throw new UnauthorizedException(
+        tokenResponse.error_description ??
+          tokenResponse.error ??
+          'Falha ao trocar código OAuth2 por token',
+      );
+    }
+
+    return this.userInfo(config, tokenResponse.access_token);
+  }
+
+  async providerConfig(provider: string): Promise<AuthProviderConfigDto> {
+    const providerConfig = this.providerRegistry.getProvider(provider);
+    const config = await this.resolveProviderConfig(provider);
+    const state = this.generateState();
+    await this.rememberState(providerConfig.key, state);
+
+    return AuthProviderConfigDto.from({
+      ...config,
+      state,
+    });
+  }
+
+  async resolveScalarOAuthFlow(provider: string) {
+    const config = await this.resolveProviderConfig(provider);
+
+    return {
+      authorizationUrl: `${config.authorizationUrl}?scope=${encodeURIComponent(config.scope)}`,
+      redirectUri: config.redirectUri,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    };
+  }
+
+  async authLink(provider: string, redirectUri?: string): Promise<string> {
+    const config = await this.providerConfig(provider);
+    const targetRedirect = redirectUri ?? config.redirectUri;
+
+    return `${config.authorizationUrl}?response_type=code&client_id=${config.clientId}&state=${config.state}&redirect_uri=${encodeURIComponent(targetRedirect)}&scope=${encodeURIComponent(config.scope)}`;
+  }
+
+  async exchangeScalarCode(
+    provider: string,
+    code: string,
+    redirectUri?: string,
+  ): Promise<OAuthUserInfoDto> {
+    return this.exchangeAuthorizationCode(provider, code, redirectUri);
+  }
+
+  async exchangeCode(
+    provider: string,
+    code: string,
+    state: string,
+    redirectUri?: string,
+  ): Promise<OAuthUserInfoDto> {
+    await this.validateState(provider, state);
+    return this.exchangeAuthorizationCode(provider, code, redirectUri);
+  }
+}

package/koala-nest/src/infra/common/cache-service.provider.ts

@@ -0,0 +1,47 @@
+import packageJson from '../../../package.json';
+import { ICacheService } from '@/domain/common/icache.service';
+import { EnvService } from '@/infra/common/env.service';
+import { InMemoryCacheService } from '@/infra/common/in-memory-cache.service';
+import { RedisCacheService } from '@/infra/common/redis-cache.service';
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
+
+@Injectable()
+export class CacheServiceProvider implements ICacheService, OnModuleDestroy {
+  private readonly delegate: ICacheService & Partial<OnModuleDestroy>;
+
+  constructor(env: EnvService) {
+    const redisUrl = env.get('REDIS_CONNECTION_STRING');
+
+    this.delegate = redisUrl
+      ? new RedisCacheService(redisUrl, this.resolveKeyPrefix(env))
+      : new InMemoryCacheService();
+  }
+
+  private resolveKeyPrefix(env: EnvService) {
+    return env.get('CACHE_KEY_PREFIX') ?? packageJson.name;
+  }
+
+  get(key: string): Promise<string | null> {
+    return this.delegate.get(key);
+  }
+
+  set(key: string, value: string, ttl?: number): Promise<void> {
+    return this.delegate.set(key, value, ttl);
+  }
+
+  setIfNotExists(key: string, value: string, ttl: number): Promise<boolean> {
+    return this.delegate.setIfNotExists(key, value, ttl);
+  }
+
+  invalidate(key: string): Promise<void> {
+    return this.delegate.invalidate(key);
+  }
+
+  invalidateByPrefix(prefix: string): Promise<void> {
+    return this.delegate.invalidateByPrefix(prefix);
+  }
+
+  onModuleDestroy() {
+    this.delegate.onModuleDestroy?.();
+  }
+}

package/koala-nest/src/infra/common/env.service.ts

@@ -0,0 +1,12 @@
+import { Env } from '@/core/env';
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+@Injectable()
+export class EnvService {
+  constructor(private readonly configService: ConfigService<Env, true>) {}
+
+  get<T extends keyof Env>(key: T) {
+    return this.configService.get(key, { infer: true });
+  }
+}

package/koala-nest/src/infra/common/in-memory-cache.service.ts

@@ -0,0 +1,71 @@
+import { ICacheService } from '@/domain/common/icache.service';
+import { Injectable } from '@nestjs/common';
+
+type CacheEntry = {
+  value: string;
+  expiresAt?: number;
+};
+
+/**
+ * Cache em memória usado quando `REDIS_CONNECTION_STRING` não está configurado.
+ */
+@Injectable()
+export class InMemoryCacheService implements ICacheService {
+  private readonly store = new Map<string, CacheEntry>();
+
+  get(key: string): Promise<string | null> {
+    const entry = this.store.get(key);
+
+    if (!entry) {
+      return Promise.resolve(null);
+    }
+
+    if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return Promise.resolve(null);
+    }
+
+    return Promise.resolve(entry.value);
+  }
+
+  set(key: string, value: string, ttl?: number): Promise<void> {
+    this.store.set(key, {
+      value,
+      expiresAt: ttl ? Date.now() + ttl * 1000 : undefined,
+    });
+
+    return Promise.resolve();
+  }
+
+  async setIfNotExists(
+    key: string,
+    value: string,
+    ttl: number,
+  ): Promise<boolean> {
+    const existing = await this.get(key);
+
+    if (existing) {
+      return false;
+    }
+
+    await this.set(key, value, ttl);
+
+    return true;
+  }
+
+  invalidate(key: string): Promise<void> {
+    this.store.delete(key);
+
+    return Promise.resolve();
+  }
+
+  invalidateByPrefix(prefix: string): Promise<void> {
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.store.delete(key);
+      }
+    }
+
+    return Promise.resolve();
+  }
+}

package/koala-nest/src/infra/common/logging.service.ts

@@ -0,0 +1,19 @@
+import {
+  ILoggingService,
+  LoggingReportProps,
+} from '@/domain/common/ilogging.service';
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class LoggingService implements ILoggingService {
+  private readonly logger = new Logger(LoggingService.name);
+
+  report(data: LoggingReportProps): Promise<void> {
+    this.logger.error(
+      `[${data.packageName}] ${data.loggedUsername}: ${data.error.message}`,
+      data.error.stack,
+    );
+
+    return Promise.resolve();
+  }
+}

package/koala-nest/src/infra/common/red-lock.service.ts

@@ -0,0 +1,44 @@
+import { CacheKeyPrefix } from '@/core/constants/cache.constants';
+import { ICacheService } from '@/domain/common/icache.service';
+import { IRedLockService } from '@/domain/common/ired-lock.service';
+import { EnvService } from '@/infra/common/env.service';
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class RedLockService implements IRedLockService {
+  constructor(
+    private readonly cache: ICacheService,
+    private readonly env: EnvService,
+  ) {}
+
+  private shouldBypassDistributedLock() {
+    return (
+      this.env.get('NODE_ENV') === 'test' ||
+      !this.env.get('REDIS_CONNECTION_STRING')
+    );
+  }
+
+  private getLockKey(key: string) {
+    return `${CacheKeyPrefix.RED_LOCK}${key}`;
+  }
+
+  async acquiredLock(key: string, ttlSecondsLock: number): Promise<boolean> {
+    if (this.shouldBypassDistributedLock()) {
+      return true;
+    }
+
+    return this.cache.setIfNotExists(
+      this.getLockKey(key),
+      'RedLockService',
+      ttlSecondsLock,
+    );
+  }
+
+  async releaseLock(key: string): Promise<void> {
+    if (this.shouldBypassDistributedLock()) {
+      return;
+    }
+
+    await this.cache.invalidate(this.getLockKey(key));
+  }
+}

package/koala-nest/src/infra/common/redis-cache.service.ts

@@ -0,0 +1,72 @@
+import { ICacheService } from '@/domain/common/icache.service';
+import Redis from 'ioredis';
+
+export class RedisCacheService implements ICacheService {
+  private readonly client: Redis;
+
+  constructor(
+    connectionString: string,
+    private readonly keyPrefix: string,
+    client?: Redis,
+  ) {
+    this.client =
+      client ??
+      new Redis(connectionString, {
+        maxRetriesPerRequest: 3,
+        lazyConnect: false,
+      });
+  }
+
+  private buildKey(key: string) {
+    return `${this.keyPrefix}:${key}`;
+  }
+
+  get(key: string): Promise<string | null> {
+    return this.client.get(this.buildKey(key));
+  }
+
+  async set(key: string, value: string, ttl?: number): Promise<void> {
+    const redisKey = this.buildKey(key);
+
+    if (ttl !== undefined && ttl > 0) {
+      await this.client.set(redisKey, value, 'EX', Math.ceil(ttl));
+      return;
+    }
+
+    await this.client.set(redisKey, value);
+  }
+
+  async setIfNotExists(
+    key: string,
+    value: string,
+    ttl: number,
+  ): Promise<boolean> {
+    const redisKey = this.buildKey(key);
+    const result = await this.client.set(
+      redisKey,
+      value,
+      'EX',
+      Math.ceil(ttl),
+      'NX',
+    );
+
+    return result === 'OK';
+  }
+
+  invalidate(key: string): Promise<void> {
+    return this.client.del(this.buildKey(key)).then(() => undefined);
+  }
+
+  async invalidateByPrefix(prefix: string): Promise<void> {
+    const pattern = `${this.buildKey(prefix)}*`;
+    const keys = await this.client.keys(pattern);
+
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+
+  onModuleDestroy() {
+    this.client.disconnect();
+  }
+}