@tsdevstack/nest-common 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tsdevstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @tsdevstack/nest-common
+
+Shared NestJS modules for tsdevstack microservices. Provides auth, rate limiting, secrets management, observability, notifications, database connectivity, and application bootstrap — so every service starts with production-ready infrastructure.
+
+## Features
+
+- **Authentication** — Kong JWT validation guard with public/partner route decorators
+- **Rate Limiting** — Redis-backed rate limiting with per-route configuration
+- **Email Rate Limiting** — Dedicated rate limiter for email-sending endpoints
+- **Secrets Management** — Multi-provider secrets (GCP Secret Manager, AWS Secrets Manager, Azure Key Vault)
+- **Observability** — Logging (Pino), metrics (Prometheus/OpenTelemetry), tracing (OTLP), health checks
+- **Database** — Prisma connection pooling with `pg` adapter and SSL support
+- **Notifications** — Email (Resend), SMS, and push notification service
+- **Background Jobs** — BullMQ configuration and scheduler guard
+- **Service Client** — Type-safe HTTP client for inter-service communication
+- **Bootstrap** — `startApp()` and `startWorker()` for consistent app initialization
+
+## Installation
+
+```bash
+npm install @tsdevstack/nest-common
+```
+
+## Quick Start
+
+### Bootstrap a service
+
+```typescript
+import { startApp } from '@tsdevstack/nest-common';
+import { AppModule } from './app.module';
+
+startApp(AppModule, {
+  serviceName: 'my-service',
+  port: 3000,
+});
+```
+
+### Import modules
+
+```typescript
+import {
+  AuthModule,
+  RedisModule,
+  RateLimitModule,
+  ObservabilityModule,
+  SecretsModule,
+} from '@tsdevstack/nest-common';
+
+@Module({
+  imports: [
+    ObservabilityModule.register({ serviceName: 'my-service' }),
+    SecretsModule,
+    AuthModule,
+    RedisModule,
+    RateLimitModule,
+  ],
+})
+export class AppModule {}
+```
+
+### Protect routes
+
+```typescript
+import { AuthGuard, Public, RateLimit } from '@tsdevstack/nest-common';
+
+@Controller('users')
+@UseGuards(AuthGuard)
+export class UsersController {
+  @Public()
+  @Get('health')
+  health() {
+    return { status: 'ok' };
+  }
+
+  @RateLimit({ points: 10, duration: 60 })
+  @Get('profile')
+  getProfile(@Req() req: AuthenticatedRequest) {
+    return req.user;
+  }
+}
+```
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `AuthModule` | Kong JWT validation, `@Public()` and `@PartnerApi()` decorators |
+| `RedisModule` | Redis connection with retry and health checks |
+| `RateLimitModule` | Redis-backed rate limiting with `@RateLimit()` decorator |
+| `EmailRateLimitModule` | Dedicated email rate limiting |
+| `SecretsModule` | Multi-cloud secrets loading (GCP, AWS, Azure) |
+| `ObservabilityModule` | Logging, metrics, tracing, and health endpoints |
+| `NotificationModule` | Email (Resend), SMS, and push notifications |
+| `BullConfigModule` | BullMQ queue configuration |
+
+## Utilities
+
+| Export | Description |
+|--------|-------------|
+| `startApp()` | Bootstrap a NestJS application with standard middleware |
+| `startWorker()` | Bootstrap a background worker process |
+| `createPrismaConnection()` | Prisma client with `pg` adapter and SSL |
+| `BaseServiceClient` | HTTP client for service-to-service calls |
+| `filterForwardHeaders()` | Header filtering for inter-service requests |
+| `generateSwaggerDocs()` | OpenAPI documentation setup |
+| `LoggerService` | Pino-based structured logging |
+| `MetricsService` | Custom Prometheus metrics |
+
+## License
+
+MIT

package/dist/auth/auth-user.interface.d.ts

@@ -0,0 +1,62 @@
+import { Request } from 'express';
+/**
+ * User object extracted from Kong headers.
+ *
+ * Kong forwards JWT claims as `X-JWT-Claim-*` headers, which are
+ * dynamically extracted into this object. The `id` field is always
+ * present (from `X-Consumer-ID`), but all other fields are dynamic
+ * based on JWT claims.
+ *
+ * @example
+ * ```typescript
+ * // Kong headers:
+ * // X-Consumer-ID: user-123
+ * // X-JWT-Claim-Email: user@example.com
+ * // X-JWT-Claim-Roles: USER,ADMIN
+ * // X-JWT-Claim-TenantId: tenant-456
+ *
+ * // Resulting KongUser:
+ * {
+ *   id: "user-123",
+ *   email: "user@example.com",
+ *   roles: ["USER", "ADMIN"],
+ *   tenantId: "tenant-456"
+ * }
+ * ```
+ */
+export interface KongUser {
+    /** User ID from X-Consumer-ID (JWT sub claim) */
+    id: string;
+    /** Dynamic claims extracted from X-JWT-Claim-* headers */
+    [key: string]: string | string[] | number | boolean | undefined;
+}
+/**
+ * Express Request with Kong authentication populated.
+ *
+ * After KongAuthGuard processes the request, either `user` (JWT auth)
+ * or `service` (API key auth) will be populated.
+ */
+export interface AuthenticatedRequest extends Request {
+    /** User object (JWT authentication) */
+    user?: KongUser;
+    /** Service name (API key authentication) */
+    service?: string;
+}
+/**
+ * Kong header names for type safety.
+ *
+ * These are the standard headers that Kong sets after validating
+ * JWT tokens or API keys.
+ */
+export declare enum KongHeaders {
+    /** Consumer ID (JWT sub claim) */
+    CONSUMER_ID = "x-consumer-id",
+    /** Consumer username (API key service name) */
+    CONSUMER_USERNAME = "x-consumer-username",
+    /** Credential identifier (JWT sub claim from kong-oidc-v3) */
+    CREDENTIAL_IDENTIFIER = "x-credential-identifier",
+    /** JWT claims as JSON (kong-oidc-v3 plugin) */
+    USERINFO = "x-userinfo",
+    /** Prefix for JWT claim headers (legacy) */
+    JWT_CLAIM_PREFIX = "x-jwt-claim-"
+}

package/dist/auth/auth.guard.d.ts

@@ -0,0 +1,181 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { SecretsService } from '../secrets/secrets.service';
+/**
+ * Guard that validates requests came through Kong gateway and extracts user data.
+ *
+ * This guard implements the tsdevstack authentication architecture where:
+ * 1. Kong validates JWT signatures using JWKS endpoint
+ * 2. Kong forwards ALL JWT claims as JSON in `X-Userinfo` header (kong-oidc-v3)
+ * 3. Kong adds `X-Kong-Trust` header to prove requests came through gateway
+ * 4. Services validate Kong trust header for defense-in-depth security
+ * 5. Services trust Kong headers (network isolation + trust header prevents spoofing)
+ * 6. Services never validate JWT tokens themselves
+ *
+ * ## How It Works
+ *
+ * ### Kong Trust Header Verification
+ * - Kong adds `X-Kong-Trust` header with KONG_TRUST_TOKEN value to ALL requests
+ * - Guard verifies this header before processing authentication
+ * - Direct service-to-service calls with `x-api-key` bypass this check
+ * - Prevents direct access to backend services bypassing Kong
+ *
+ * ### JWT Authentication (User Requests)
+ * - Kong validates JWT and sets `X-Consumer-ID` (from JWT `sub` claim)
+ * - Kong forwards all JWT claims as JSON in `X-Userinfo` header
+ * - Guard parses the JSON and extracts ALL claims into `req.user` object
+ * - Claims preserve their original types (arrays, numbers, booleans, strings)
+ * - Falls back to legacy `X-JWT-Claim-*` headers for backward compatibility
+ *
+ * ### API Key Authentication (Service-to-Service)
+ * - Kong validates API key and sets `X-Consumer-Username` (service name)
+ * - Guard sets `req.service` to the service name
+ * - No user object is created
+ *
+ * ### Public Endpoints
+ * - Routes marked with `@Public()` decorator skip user authentication
+ * - But still require Kong trust header (unless direct service-to-service)
+ *
+ * @example Basic usage with JWT
+ * ```typescript
+ * @Controller('offers')
+ * export class OffersController {
+ *   @Post()
+ *   @UseGuards(AuthGuard)
+ *   create(@Request() req: AuthenticatedRequest) {
+ *     const { id, email, roles } = req.user;
+ *     // Access any custom claims dynamically
+ *     const tenantId = req.user.tenantId;
+ *   }
+ * }
+ * ```
+ *
+ * @example Public endpoint
+ * ```typescript
+ * @Get()
+ * @Public()
+ * list() {
+ *   // No user authentication required, but must come through Kong
+ * }
+ * ```
+ *
+ * @example Service-to-service with API key
+ * ```typescript
+ * @Get('internal')
+ * @UseGuards(AuthGuard)
+ * internal(@Request() req: AuthenticatedRequest) {
+ *   const serviceName = req.service; // e.g., "bff-service"
+ * }
+ * ```
+ */
+export declare class AuthGuard implements CanActivate {
+    private reflector;
+    private secrets;
+    private readonly logger;
+    constructor(reflector: Reflector, secrets: SecretsService);
+    /**
+     * Validates the request came through Kong and extracts authentication data.
+     *
+     * @param context - Execution context
+     * @returns true if authentication is valid or endpoint is public
+     * @throws UnauthorizedException if Kong headers are missing
+     */
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Extracts user object from Kong headers.
+     *
+     * kong-oidc-v3 forwards JWT claims as base64-encoded JSON in the `X-Userinfo` header.
+     * Falls back to legacy `X-JWT-Claim-*` headers for backward compatibility.
+     *
+     * @param headers - HTTP headers from the request
+     * @returns User object with id and all dynamic claims
+     *
+     * @example
+     * ```typescript
+     * // Input headers (kong-oidc-v3):
+     * {
+     *   'x-credential-identifier': 'user-123',
+     *   'x-userinfo': 'eyJzdWIiOiJ1c2VyLTEyMyIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsInJvbGVzIjpbIlVTRVIiLCJBRE1JTiJdLCJ0ZW5hbnRJZCI6InRlbmFudC00NTYifQ=='
+     * }
+     *
+     * // Output user object:
+     * {
+     *   id: 'user-123',
+     *   email: 'user@example.com',
+     *   roles: ['USER', 'ADMIN'],
+     *   tenantId: 'tenant-456'
+     * }
+     * ```
+     */
+    private extractUserFromHeaders;
+    /**
+     * Converts kebab-case to camelCase.
+     *
+     * @param str - Kebab-case string (e.g., "tenant-id")
+     * @returns CamelCase string (e.g., "tenantId")
+     *
+     * @example
+     * ```typescript
+     * toCamelCase('tenant-id')      // 'tenantId'
+     * toCamelCase('is-verified')    // 'isVerified'
+     * toCamelCase('email')          // 'email'
+     * ```
+     */
+    private toCamelCase;
+    /**
+     * Parses header value to appropriate JavaScript type.
+     *
+     * Kong forwards all JWT claims as strings. This method intelligently
+     * parses them back to their original types:
+     * - Arrays: "USER,ADMIN" → ["USER", "ADMIN"]
+     * - Numbers: "123" → 123
+     * - Booleans: "true" → true, "false" → false
+     * - Strings: everything else
+     *
+     * @param value - String value from header
+     * @returns Parsed value in appropriate type
+     *
+     * @example
+     * ```typescript
+     * parseValue('USER,ADMIN')     // ['USER', 'ADMIN']
+     * parseValue('123')            // 123
+     * parseValue('true')           // true
+     * parseValue('false')          // false
+     * parseValue('john@example.com') // 'john@example.com'
+     * ```
+     */
+    private parseValue;
+    /**
+     * Verifies that the request came through Kong gateway by validating the trust header.
+     * This is a defense-in-depth measure to prevent direct access to backend services.
+     *
+     * @param request - HTTP request object
+     * @throws UnauthorizedException if Kong trust header is missing or invalid
+     *
+     * @example
+     * ```typescript
+     * // Kong adds this header to all requests:
+     * // Request headers: { 'x-kong-trust': 'KONG_TRUST_TOKEN_VALUE' }
+     * // Service validates it matches the KONG_TRUST_TOKEN from secrets
+     * ```
+     */
+    private verifyKongTrustHeader;
+    /**
+     * Validates direct service-to-service API key authentication.
+     * Used when services call each other directly (bypassing Kong).
+     *
+     * @param request - HTTP request object
+     * @param apiKey - API key from x-api-key header
+     * @returns true if API key is valid
+     * @throws UnauthorizedException if API key configuration is missing
+     * @throws ForbiddenException if API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Service A calling Service B:
+     * // Request headers: { 'x-api-key': 'AUTH_SERVICE_API_KEY_VALUE' }
+     * // Service B validates against its own API_KEY from secrets
+     * ```
+     */
+    private validateServiceApiKey;
+}

package/dist/auth/auth.guard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/auth.module.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Kong Authentication Module.
+ *
+ * Provides the AuthGuard globally to all modules in the application.
+ * Import this module once in your root AppModule to make AuthGuard
+ * available throughout your application.
+ *
+ * ## Features
+ * - Dynamic JWT claim extraction from Kong headers
+ * - Service-to-service API key authentication
+ * - @Public() decorator for public endpoints
+ * - Network isolation security (trusts Kong headers only)
+ *
+ * @example
+ * ```typescript
+ * // app.module.ts
+ * @Module({
+ *   imports: [
+ *     AuthModule,
+ *     // ... other modules
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example Usage in controllers
+ * ```typescript
+ * @Controller('offers')
+ * export class OffersController {
+ *   @Get()
+ *   @Public()
+ *   list() {
+ *     // Public endpoint
+ *   }
+ *
+ *   @Post()
+ *   @UseGuards(AuthGuard)
+ *   create(@Request() req: AuthenticatedRequest) {
+ *     const { id, email, roles } = req.user;
+ *   }
+ * }
+ * ```
+ */
+export declare class AuthModule {
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Authentication Module
+ *
+ * Provides authentication for tsdevstack applications including:
+ * - Kong gateway JWT authentication
+ * - Kong API key authentication
+ * - Direct service-to-service API key authentication
+ *
+ * @packageDocumentation
+ */
+export { AuthModule } from './auth.module';
+export { AuthGuard } from './auth.guard';
+export { Public, IS_PUBLIC_KEY } from './public.decorator';
+export { PartnerApi, IS_PARTNER_API_KEY } from './partner-api.decorator';
+export { Partner } from './partner.decorator';
+export type { KongUser, AuthenticatedRequest } from './auth-user.interface';
+export { KongHeaders } from './auth-user.interface';

package/dist/auth/partner-api.decorator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Metadata key for the @PartnerApi() decorator.
+ */
+export declare const IS_PARTNER_API_KEY = "isPartnerApi";
+/**
+ * Decorator to mark routes as accessible via Partner API (requires API key).
+ *
+ * Routes marked with this decorator will be exposed under the /api prefix
+ * in Kong Gateway and require a valid API key for access.
+ *
+ * This decorator is ADDITIVE, not exclusive:
+ * - Can be used alone for partner-only access
+ * - Can be combined with @ApiBearerAuth() for dual access (JWT + Partner API)
+ *
+ * @example Partner-only endpoint
+ * ```typescript
+ * @Controller('offers')
+ * export class OffersController {
+ *   @Get('current-plan')
+ *   @PartnerApi()
+ *   getCurrentPlan() {
+ *     // Accessible only via /api/offers/current-plan with API key
+ *   }
+ * }
+ * ```
+ *
+ * @example Dual-access endpoint (JWT + Partner API)
+ * ```typescript
+ * @Controller('data')
+ * export class DataController {
+ *   @Get('export')
+ *   @ApiBearerAuth()
+ *   @PartnerApi()
+ *   exportData() {
+ *     // Accessible via:
+ *     // - /data/export with JWT token (for users)
+ *     // - /api/data/export with API key (for partners)
+ *   }
+ * }
+ * ```
+ */
+export declare const PartnerApi: () => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/dist/auth/partner.decorator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Extracts partner identifier from Kong's X-Consumer-Username header.
+ *
+ * Kong automatically adds this header when a valid API key is used.
+ * The value is the partner's username as defined in .secrets.user.json.
+ *
+ * @returns Partner username string, or undefined if not present
+ *
+ * @example Basic usage
+ * ```typescript
+ * @Controller('webhooks')
+ * export class WebhooksController {
+ *   @PartnerApi()
+ *   @Post('data')
+ *   async receiveData(@Partner() partner: string) {
+ *     // partner = "acme-corp" (from X-Consumer-Username header)
+ *     this.logger.info('Partner API call', { partner });
+ *     return this.processData();
+ *   }
+ * }
+ * ```
+ *
+ * @example With optional typing (dual JWT + Partner access)
+ * ```typescript
+ * @Controller('exports')
+ * export class ExportsController {
+ *   @ApiBearerAuth()
+ *   @PartnerApi()
+ *   @Get('data')
+ *   async exportData(
+ *     @User() user?: AuthUser,
+ *     @Partner() partner?: string,
+ *   ) {
+ *     if (partner) {
+ *       // Called via /api/exports/data with API key
+ *       this.logger.info('Partner export', { partner });
+ *     } else if (user) {
+ *       // Called via /exports/data with JWT
+ *       this.logger.info('User export', { userId: user.id });
+ *     }
+ *     return this.getExportData();
+ *   }
+ * }
+ * ```
+ *
+ * @example With logging and tracking
+ * ```typescript
+ * @PartnerApi()
+ * @Post('webhook')
+ * async handleWebhook(
+ *   @Partner() partner: string,
+ *   @Body() data: WebhookDto,
+ * ) {
+ *   await this.analytics.trackPartnerUsage(partner, '/webhook');
+ *   await this.webhookService.process(partner, data);
+ *   return { success: true };
+ * }
+ * ```
+ */
+export declare const Partner: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/auth/partner.decorator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/public.decorator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Metadata key for the @Public() decorator.
+ */
+export declare const IS_PUBLIC_KEY = "isPublic";
+/**
+ * Decorator to mark routes as public (no authentication required).
+ *
+ * When applied to a controller method or class, KongAuthGuard will
+ * skip authentication checks for those routes.
+ *
+ * @example Method-level (specific endpoint is public)
+ * ```typescript
+ * @Controller('auth')
+ * export class AuthController {
+ *   @Post('login')
+ *   @Public()
+ *   async login(@Body() dto: LoginDto) {
+ *     // No authentication required for login
+ *   }
+ *
+ *   @Get('profile')
+ *   @UseGuards(KongAuthGuard)
+ *   async getProfile(@Request() req: AuthenticatedRequest) {
+ *     // Authentication required
+ *     const user = req.user;
+ *   }
+ * }
+ * ```
+ *
+ * @example Class-level (all endpoints are public)
+ * ```typescript
+ * @Controller('health')
+ * @Public()
+ * export class HealthController {
+ *   @Get()
+ *   check() {
+ *     return { status: 'ok' };
+ *   }
+ * }
+ * ```
+ */
+export declare const Public: () => import("@nestjs/common").CustomDecorator<string>;

package/dist/auth/public.decorator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/utils/extract-user-from-headers.d.ts

@@ -0,0 +1,45 @@
+import { KongUser } from '../auth-user.interface';
+/**
+ * Extracts user object from Kong headers.
+ *
+ * Dynamically extracts ALL JWT claims from headers that start with
+ * `X-JWT-Claim-*`. This makes the authentication future-proof - any
+ * new claims added to the JWT will automatically flow through without
+ * code changes.
+ *
+ * @param headers - HTTP headers from the request
+ * @returns User object with id and all dynamic claims
+ *
+ * @example Basic extraction
+ * ```typescript
+ * const headers = {
+ *   'x-consumer-id': 'user-123',
+ *   'x-jwt-claim-email': 'user@example.com',
+ *   'x-jwt-claim-roles': 'USER,ADMIN',
+ * };
+ *
+ * extractUserFromHeaders(headers);
+ * // {
+ * //   id: 'user-123',
+ * //   email: 'user@example.com',
+ * //   roles: ['USER', 'ADMIN']
+ * // }
+ * ```
+ *
+ * @example With camelCase conversion
+ * ```typescript
+ * const headers = {
+ *   'x-consumer-id': 'user-123',
+ *   'x-jwt-claim-tenant-id': 'tenant-456',
+ *   'x-jwt-claim-is-verified': 'true',
+ * };
+ *
+ * extractUserFromHeaders(headers);
+ * // {
+ * //   id: 'user-123',
+ * //   tenantId: 'tenant-456',
+ * //   isVerified: true
+ * // }
+ * ```
+ */
+export declare function extractUserFromHeaders(headers: Record<string, string>): KongUser;

package/dist/auth/utils/extract-user-from-headers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility functions for Kong authentication.
+ *
+ * @packageDocumentation
+ */
+export { toCamelCase } from './to-camel-case';
+export { parseHeaderValue } from './parse-header-value';
+export { extractUserFromHeaders } from './extract-user-from-headers';