@koalarx/nest 3.1.49 → 4.0.1

package/koala-nest/src/host/decorators/is-public.decorator.ts

@@ -0,0 +1,82 @@
+import { applyDecorators, SetMetadata } from '@nestjs/common';
+import { OpenAPIObject } from '@nestjs/swagger';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+
+/** Marcador interno lido pelo Swagger e removido em `syncIsPublicRoutesInOpenApi`. */
+export const SWAGGER_PUBLIC_ROUTE = 'public';
+
+const OPENAPI_HTTP_METHODS = new Set([
+  'get',
+  'post',
+  'put',
+  'patch',
+  'delete',
+  'options',
+  'head',
+  'trace',
+]);
+
+/**
+ * Libera a rota na API e na documentação OpenAPI (sem cadeado no Scalar).
+ *
+ * O Nest não aplica `security: []` via decorator quando há security global;
+ * por isso o metadata `swagger/apiSecurity` é sincronizado no documento gerado.
+ */
+export const IsPublic = () =>
+  applyDecorators(
+    SetMetadata(IS_PUBLIC_KEY, true),
+    SetMetadata('swagger/apiSecurity', [SWAGGER_PUBLIC_ROUTE]),
+  );
+
+export function syncIsPublicRoutesInOpenApi(document: OpenAPIObject) {
+  for (const pathItem of Object.values(document.paths ?? {})) {
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!OPENAPI_HTTP_METHODS.has(method) || !operation?.security) {
+        continue;
+      }
+
+      const isPublicRoute = operation.security.some((requirement) =>
+        requirement === SWAGGER_PUBLIC_ROUTE
+          ? true
+          : typeof requirement === 'object' &&
+            SWAGGER_PUBLIC_ROUTE in requirement,
+      );
+
+      if (isPublicRoute) {
+        operation.security = [];
+      }
+    }
+  }
+}
+
+/** Aplica os esquemas de auth em cada operação protegida (Scalar exige `operation.security` explícito). */
+export function applyAuthSecurityToProtectedRoutes(
+  document: OpenAPIObject,
+  schemeNames: string[],
+) {
+  if (schemeNames.length === 0) {
+    return;
+  }
+
+  const securityRequirements = schemeNames.map((name) => ({ [name]: [] }));
+
+  document.security = securityRequirements;
+
+  for (const pathItem of Object.values(document.paths ?? {})) {
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!OPENAPI_HTTP_METHODS.has(method) || !operation) {
+        continue;
+      }
+
+      if (
+        Array.isArray(operation.security) &&
+        operation.security.length === 0
+      ) {
+        continue;
+      }
+
+      operation.security = securityRequirements;
+    }
+  }
+}

package/koala-nest/src/host/decorators/restriction-by-profile.decorator.ts

@@ -0,0 +1,13 @@
+import { AuthProfile } from '@/core/auth/auth-profile.enum';
+import { SetMetadata } from '@nestjs/common';
+
+export const PROFILES_KEY = 'profiles';
+
+/**
+ * Restringe o endpoint aos perfis informados.
+ * O valor de `profile` deve existir no payload JWT.
+ *
+ * @example RestrictionByProfile([AuthProfile.admin])
+ */
+export const RestrictionByProfile = (profiles: AuthProfile[]) =>
+  SetMetadata(PROFILES_KEY, profiles);

package/koala-nest/src/host/decorators/scalar-token-endpoint.decorator.ts

@@ -0,0 +1,14 @@
+import { AuthTokenResponse } from '@/application/auth/common/auth-token.response';
+import { IsPublic } from '@/host/decorators/is-public.decorator';
+import { applyDecorators, HttpCode, HttpStatus, Post } from '@nestjs/common';
+import { ApiExcludeEndpoint, ApiOkResponse } from '@nestjs/swagger';
+
+/** Rota interna do Scalar — não aparece na documentação OpenAPI. */
+export const ScalarTokenEndpoint = () =>
+  applyDecorators(
+    Post('scalar-token'),
+    IsPublic(),
+    HttpCode(HttpStatus.OK),
+    ApiExcludeEndpoint(),
+    ApiOkResponse({ type: AuthTokenResponse }),
+  );

package/koala-nest/src/host/filters/errors.filter.ts

@@ -0,0 +1,99 @@
+import { FilterRequestParams } from '@/core/utils/filter-request-params';
+import {
+  formatTypeOrmError,
+  isTypeOrmError,
+} from '@/core/utils/format-typeorm-error';
+import { formatZodError, ZodFieldError } from '@/core/utils/format-zod-error';
+import { ILoggingService } from '@/domain/common/ilogging.service';
+import { reportErrorToLogging } from '@/core/utils/report-error';
+import {
+  ArgumentsHost,
+  Catch,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { BaseExceptionFilter, AbstractHttpAdapter } from '@nestjs/core';
+import { ZodError } from 'zod';
+
+interface ErrorResponse {
+  statusCode: HttpStatus;
+  message: string;
+  errors?: ZodFieldError[];
+}
+
+@Catch()
+export class ErrorsFilter extends BaseExceptionFilter {
+  private readonly logger = new Logger(ErrorsFilter.name);
+
+  constructor(
+    httpAdapter: AbstractHttpAdapter | undefined,
+    private readonly loggingService: ILoggingService,
+  ) {
+    super(httpAdapter);
+  }
+
+  private handleZodError(exception: ZodError): ErrorResponse {
+    const formatted = formatZodError(exception);
+
+    return {
+      statusCode: HttpStatus.BAD_REQUEST,
+      message: formatted.message,
+      errors: formatted.errors,
+    };
+  }
+
+  private handleTypeOrmError(exception: Error): ErrorResponse {
+    const formatted = formatTypeOrmError(exception);
+
+    return {
+      statusCode: formatted.statusCode,
+      message: formatted.message,
+      errors: formatted.errors,
+    };
+  }
+
+  private sendErrorResponse(host: ArgumentsHost, errorResponse: ErrorResponse) {
+    return FilterRequestParams.get(host)
+      .response.status(errorResponse.statusCode)
+      .json(errorResponse);
+  }
+
+  private async reportError(error: Error, host: ArgumentsHost): Promise<void> {
+    const { loggedUserName } = FilterRequestParams.get(host);
+
+    try {
+      await reportErrorToLogging(
+        this.loggingService,
+        error,
+        loggedUserName || undefined,
+      );
+    } catch {
+      this.logger.error(error.message, error.stack);
+    }
+  }
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    if (exception instanceof ZodError) {
+      return this.sendErrorResponse(host, this.handleZodError(exception));
+    }
+
+    if (exception instanceof Error && isTypeOrmError(exception)) {
+      return this.sendErrorResponse(host, this.handleTypeOrmError(exception));
+    }
+
+    if (exception instanceof HttpException) {
+      return super.catch(exception, host);
+    }
+
+    const error =
+      exception instanceof Error ? exception : new Error(String(exception));
+
+    void this.reportError(error, host);
+
+    return this.sendErrorResponse(host, {
+      statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+      message: 'Erro interno do servidor.',
+    });
+  }
+}

package/koala-nest/src/host/jobs/jobs-bootstrap.service.ts

@@ -0,0 +1,61 @@
+import type { Env } from '@/core/env';
+import { delay } from '@koalarx/utils/KlDelay';
+import { Inject, Injectable, Logger, OnModuleInit, Type } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { ModuleRef } from '@nestjs/core';
+import { CRON_JOBS, EVENT_JOB_HANDLERS } from './jobs.tokens';
+
+type EventJobHandler = {
+  setupSubscriptions(): void;
+};
+
+type CronJobHandler = {
+  start(): Promise<void>;
+};
+
+@Injectable()
+export class JobsBootstrapService implements OnModuleInit {
+  private readonly logger = new Logger(JobsBootstrapService.name);
+
+  constructor(
+    private readonly moduleRef: ModuleRef,
+    private readonly config: ConfigService<Env, true>,
+    @Inject(EVENT_JOB_HANDLERS)
+    private readonly eventHandlers: Type<EventJobHandler>[],
+    @Inject(CRON_JOBS)
+    private readonly cronJobs: Type<CronJobHandler>[],
+  ) {}
+
+  async onModuleInit() {
+    for (const handlerType of this.eventHandlers) {
+      const handler = this.moduleRef.get(handlerType, { strict: false });
+      handler.setupSubscriptions();
+    }
+
+    if (this.cronJobs.length === 0) {
+      return;
+    }
+
+    if (!this.config.get('CRON_JOBS_ENABLED', { infer: true })) {
+      this.logger.log(
+        'Cron jobs não iniciados (CRON_JOBS_ENABLED=false). Defina true no .env para habilitar.',
+      );
+      return;
+    }
+
+    this.logger.log(`Iniciando ${this.cronJobs.length} cron job(s)...`);
+
+    const bootstrapDelayMs = this.config.get('BOOTSTRAP_DELAY_MS', {
+      infer: true,
+    });
+
+    if (bootstrapDelayMs > 0) {
+      await delay(bootstrapDelayMs);
+    }
+
+    for (const jobType of this.cronJobs) {
+      const job = this.moduleRef.get(jobType, { strict: false });
+      void job.start();
+    }
+  }
+}

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

@@ -0,0 +1,41 @@
+import { DynamicModule, ForwardReference, Module, Type } from '@nestjs/common';
+import { JobsBootstrapService } from './jobs-bootstrap.service';
+import { CRON_JOBS, EVENT_JOB_HANDLERS } from './jobs.tokens';
+
+type JobsModuleImport =
+  | Type<unknown>
+  | DynamicModule
+  | ForwardReference
+  | Promise<DynamicModule>;
+
+export type JobsModuleOptions = {
+  imports?: JobsModuleImport[];
+  eventHandlers?: Type<unknown>[];
+  cronJobs?: Type<unknown>[];
+};
+
+@Module({})
+export class JobsModule {
+  static register(options: JobsModuleOptions = {}): DynamicModule {
+    const eventHandlers = options.eventHandlers ?? [];
+    const cronJobs = options.cronJobs ?? [];
+
+    return {
+      module: JobsModule,
+      imports: options.imports ?? [],
+      providers: [
+        {
+          provide: EVENT_JOB_HANDLERS,
+          useValue: eventHandlers,
+        },
+        {
+          provide: CRON_JOBS,
+          useValue: cronJobs,
+        },
+        ...eventHandlers,
+        ...cronJobs,
+        JobsBootstrapService,
+      ],
+    };
+  }
+}

package/koala-nest/src/host/jobs/jobs.tokens.ts

@@ -0,0 +1,2 @@
+export const EVENT_JOB_HANDLERS = Symbol('EVENT_JOB_HANDLERS');
+export const CRON_JOBS = Symbol('CRON_JOBS');

package/koala-nest/src/host/main.ts

@@ -0,0 +1,43 @@
+import 'dotenv/config';
+
+import { NestFactory } from '@nestjs/core';
+import cookieParser from 'cookie-parser';
+import { AppModule } from './app.module';
+import { defineDocumentation } from './open-api/define-documentation';
+import { ErrorsFilter } from './filters/errors.filter';
+import { HttpAdapterHost } from '@nestjs/core';
+import { AuthGuard } from './security/guards/auth.guard';
+import { ProfilesGuard } from './security/guards/profiles.guard';
+import { ILoggingService } from '@/domain/common/ilogging.service';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.use(cookieParser());
+
+  app.enableCors({
+    credentials: true,
+    origin: true,
+    optionsSuccessStatus: 200,
+  });
+
+  await defineDocumentation(app);
+
+  const { httpAdapter } = app.get(HttpAdapterHost);
+  const loggingService = app.get(ILoggingService);
+  app.useGlobalFilters(new ErrorsFilter(httpAdapter, loggingService));
+
+  app.useGlobalGuards(
+    await app.resolve(AuthGuard),
+    await app.resolve(ProfilesGuard),
+  );
+
+  await app.listen(process.env.PORT || 3000);
+
+  console.log(`Server is running on port ${process.env.PORT || 3000}`);
+  console.log(
+    `Documentation is available at http://localhost:${process.env.PORT || 3000}/doc`,
+  );
+}
+
+bootstrap();

package/koala-nest/src/host/open-api/define-documentation.ts

@@ -0,0 +1,210 @@
+import { OAuthProviderRegistry } from '@/core/auth/oauth-provider.registry';
+import { EnvConfig } from '@/core/utils/env.config';
+import {
+  isProviderRegistered,
+  resolveAppProvider,
+} from '@/core/utils/is-provider-registered';
+import { resolveApiHost } from '@/core/utils/resolve-api-host';
+import {
+  IJwtTokenService,
+  IOAuth2Service,
+} from '@/domain/auth/services/iauth.service';
+import {
+  applyAuthSecurityToProtectedRoutes,
+  syncIsPublicRoutesInOpenApi,
+} from '@/host/decorators/is-public.decorator';
+import { SecurityModule } from '@/host/security/security.module';
+import { EnvService } from '@/infra/common/env.service';
+import { INestApplication } from '@nestjs/common';
+import { ModulesContainer } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { apiReference } from '@scalar/nestjs-api-reference';
+import packageJson from '../../../package.json';
+
+const DOC_ENDPOINT = '/doc';
+const ACCESS_TOKEN_FIELD = 'accessToken';
+
+type DocAuthorization = {
+  name: string;
+  config: Record<string, unknown>;
+};
+
+function capitalizeProvider(key: string) {
+  return key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+function hasController(app: INestApplication, controllerName: string) {
+  const modulesContainer = app.get(ModulesContainer);
+
+  for (const moduleRef of modulesContainer.values()) {
+    for (const wrapper of moduleRef.controllers.values()) {
+      if (wrapper.metatype?.name === controllerName) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function resolveOAuthProviderRegistry(app: INestApplication) {
+  const fromContainer = resolveAppProvider<OAuthProviderRegistry>(
+    app,
+    OAuthProviderRegistry,
+  );
+
+  if (fromContainer) {
+    return fromContainer;
+  }
+
+  try {
+    return app.select(SecurityModule).get(OAuthProviderRegistry, {
+      strict: false,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+async function buildDocAuthorizations(
+  app: INestApplication,
+): Promise<DocAuthorization[]> {
+  if (!isProviderRegistered(app, IJwtTokenService)) {
+    return [];
+  }
+
+  const env = app.get(EnvService);
+  const hostAddress = resolveApiHost(env.get('API_HOST'), env.get('PORT'));
+  const isDevelop = EnvConfig.isEnvDevelop;
+  const refreshUrl = `${hostAddress}/auth/refresh`;
+  const authorizations: DocAuthorization[] = [];
+
+  if (hasController(app, 'LoginController')) {
+    authorizations.push({
+      name: 'JWT',
+      config: {
+        type: 'oauth2',
+        flows: {
+          password: {
+            tokenUrl: `${hostAddress}/auth/login`,
+            refreshUrl,
+            username: isDevelop ? 'admin@example.com' : '',
+            password: isDevelop ? 'admin123' : '',
+            'x-tokenName': ACCESS_TOKEN_FIELD,
+          },
+        },
+      },
+    });
+  }
+
+  if (
+    isProviderRegistered(app, IOAuth2Service) &&
+    hasController(app, 'OAuthExchangeCodeController')
+  ) {
+    const oauth2Service = app.get(IOAuth2Service);
+    const providerRegistry = resolveOAuthProviderRegistry(app);
+
+    if (providerRegistry) {
+      for (const providerKey of providerRegistry.listConfiguredProviders()) {
+        const flow = await oauth2Service.resolveScalarOAuthFlow(providerKey);
+
+        authorizations.push({
+          name: capitalizeProvider(providerKey),
+          config: {
+            type: 'oauth2',
+            flows: {
+              authorizationCode: {
+                authorizationUrl: flow.authorizationUrl,
+                tokenUrl: `${hostAddress}/oauth2/scalar-token`,
+                refreshUrl,
+                'x-tokenName': ACCESS_TOKEN_FIELD,
+                'x-usePkce': 'no',
+                'x-scalar-redirect-uri': flow.redirectUri,
+                'x-scalar-security-body': {
+                  audience: 'code',
+                  provider: providerKey,
+                },
+                ...(isDevelop
+                  ? {
+                      'x-scalar-client-id': flow.clientId,
+                      clientSecret: flow.clientSecret,
+                    }
+                  : {}),
+              },
+            },
+          },
+        });
+      }
+    }
+  }
+
+  return authorizations;
+}
+
+export async function defineDocumentation(app: INestApplication) {
+  const authorizations = await buildDocAuthorizations(app);
+
+  const documentBuilder = new DocumentBuilder()
+    .setTitle(packageJson.name)
+    .setVersion(packageJson.version);
+
+  for (const authorization of authorizations) {
+    documentBuilder.addBearerAuth(
+      authorization.config as never,
+      authorization.name,
+    );
+    documentBuilder.addSecurityRequirements(authorization.name);
+  }
+
+  const document = SwaggerModule.createDocument(app, documentBuilder.build());
+
+  if (authorizations.length > 0) {
+    syncIsPublicRoutesInOpenApi(document);
+    applyAuthSecurityToProtectedRoutes(
+      document,
+      authorizations.map((authorization) => authorization.name),
+    );
+  }
+
+  SwaggerModule.setup(DOC_ENDPOINT, app, document, { swaggerUiEnabled: false });
+
+  app.use(
+    DOC_ENDPOINT,
+    apiReference({
+      darkMode: true,
+      spec: { content: document },
+      metaData: {
+        title: packageJson.name,
+        version: packageJson.version,
+      },
+      hideModels: true,
+      hideDownloadButton: true,
+      hideClientButton: true,
+      hiddenClients: [
+        'libcurl',
+        'clj_http',
+        'restsharp',
+        'native',
+        'http1.1',
+        'asynchttp',
+        'nethttp',
+        'okhttp',
+        'unirest',
+        'xhr',
+        'request',
+        'nsurlsession',
+        'cohttp',
+        'guzzle',
+        'http1',
+        'http2',
+        'webrequest',
+        'restmethod',
+        'requests',
+        'httr',
+        'httpie',
+        'wget',
+        'undici',
+      ],
+    }),
+  );
+}

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

@@ -0,0 +1,107 @@
+import { AuthenticatedUser } from '@/core/auth/jwt-claims';
+import { assertUserIsActive } from '@/core/auth/assert-user-active';
+import { applyRefreshTokenForRefreshRoute } from '@/core/auth/resolve-refresh-token';
+import { IUserRepository } from '@/domain/repositories/iuser.repository';
+import { IS_PUBLIC_KEY } from '@/host/decorators/is-public.decorator';
+import {
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { AuthGuard as NestAuthGuard } from '@nestjs/passport';
+import { isObservable, lastValueFrom, Observable } from 'rxjs';
+
+type TokenUser = Pick<AuthenticatedUser, 'sub' | 'refreshToken'>;
+
+type AuthRequest = Parameters<typeof applyRefreshTokenForRefreshRoute>[0] & {
+  user?: AuthenticatedUser | TokenUser;
+};
+
+@Injectable()
+export class AuthGuard extends NestAuthGuard('jwt') {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly userRepository: IUserRepository,
+  ) {
+    super();
+  }
+
+  private resolveCanActivate(
+    result: boolean | Promise<boolean> | Observable<boolean>,
+  ): Promise<boolean> {
+    if (typeof result === 'boolean') {
+      return Promise.resolve(result);
+    }
+
+    if (isObservable(result)) {
+      return lastValueFrom(result);
+    }
+
+    return result;
+  }
+
+  private async loadUserFromDatabase(request: AuthRequest) {
+    const tokenUser = request.user;
+
+    if (!tokenUser?.sub) {
+      return;
+    }
+
+    if ('name' in tokenUser && tokenUser.name !== undefined) {
+      return;
+    }
+
+    const user = await this.userRepository.getById(tokenUser.sub);
+
+    if (!user) {
+      throw new UnauthorizedException();
+    }
+
+    assertUserIsActive(user);
+
+    request.user = {
+      sub: user.id,
+      name: user.name,
+      profile: user.profile,
+      login: user.login,
+      email: user.email,
+      refreshToken: tokenUser.refreshToken,
+    };
+  }
+
+  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<AuthRequest>();
+
+    applyRefreshTokenForRefreshRoute(request);
+
+    const activated = await this.resolveCanActivate(super.canActivate(context));
+
+    if (!activated) {
+      return false;
+    }
+
+    await this.loadUserFromDatabase(request);
+    return true;
+  }
+
+  handleRequest<TUser = AuthenticatedUser>(
+    err: Error | null,
+    user: TUser | false,
+  ): TUser {
+    if (err || !user) {
+      throw err ?? new UnauthorizedException();
+    }
+
+    return user;
+  }
+}