@vritti/api-sdk 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -10,6 +10,183 @@ import { FastifyRequest, FastifyReply } from 'fastify';
 import { Observable } from 'rxjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
+/**
+ * api-sdk Configuration System
+ *
+ * Similar to quantum-ui's config pattern - provides a type-safe configuration system
+ *
+ * @example
+ * ```typescript
+ * // In vritti-api-nexus/src/main.ts
+ * import { configureApiSdk } from '@vritti/api-sdk';
+ *
+ * configureApiSdk({
+ *   cookie: {
+ *     refreshCookieName: 'vritti_refresh',
+ *     refreshCookieMaxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
+ *   },
+ *   jwt: {
+ *     accessTokenExpiry: '15m',
+ *     refreshTokenExpiry: '30d',
+ *     validateTokenBinding: true,
+ *   },
+ *   guard: {
+ *     tenantHeaderName: 'x-tenant-id',
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Cookie configuration options
+ */
+interface CookieConfig {
+    /**
+     * The name of the httpOnly cookie containing the refresh token
+     * @default 'vritti_refresh'
+     */
+    refreshCookieName: string;
+    /**
+     * Max age of the refresh cookie in milliseconds
+     * @default 2592000000 (30 days)
+     */
+    refreshCookieMaxAge: number;
+    /**
+     * Cookie path
+     * @default '/'
+     */
+    refreshCookiePath: string;
+    /**
+     * Whether the cookie is secure (HTTPS only)
+     * @default true in production
+     */
+    refreshCookieSecure: boolean;
+    /**
+     * SameSite attribute for the cookie
+     * @default 'strict'
+     */
+    refreshCookieSameSite: 'strict' | 'lax' | 'none';
+}
+/**
+ * JWT token configuration options
+ */
+interface JwtConfig {
+    /**
+     * Access token expiry time
+     * @default '15m'
+     */
+    accessTokenExpiry: string;
+    /**
+     * Refresh token expiry time
+     * @default '30d'
+     */
+    refreshTokenExpiry: string;
+    /**
+     * Onboarding token expiry time
+     * @default '24h'
+     */
+    onboardingTokenExpiry: string;
+    /**
+     * Whether to validate refresh token binding (hash in access token)
+     * @default true
+     */
+    validateTokenBinding: boolean;
+}
+/**
+ * Auth guard configuration options
+ */
+interface GuardConfig {
+    /**
+     * Header name for tenant ID
+     * @default 'x-tenant-id'
+     */
+    tenantHeaderName: string;
+    /**
+     * Header name for authorization
+     * @default 'authorization'
+     */
+    authHeaderName: string;
+    /**
+     * Token prefix (e.g., 'Bearer')
+     * @default 'Bearer'
+     */
+    tokenPrefix: string;
+}
+/**
+ * Complete api-sdk configuration interface
+ */
+interface ApiSdkConfig {
+    /**
+     * Cookie configuration
+     */
+    cookie?: Partial<CookieConfig>;
+    /**
+     * JWT token configuration
+     */
+    jwt?: Partial<JwtConfig>;
+    /**
+     * Auth guard configuration
+     */
+    guard?: Partial<GuardConfig>;
+}
+/**
+ * Full configuration type with all properties required
+ */
+interface FullConfig {
+    cookie: CookieConfig;
+    jwt: JwtConfig;
+    guard: GuardConfig;
+}
+/**
+ * Helper function to define configuration with type safety
+ * Similar to Tailwind's defineConfig()
+ */
+declare function defineConfig(config: ApiSdkConfig): ApiSdkConfig;
+/**
+ * Configure api-sdk with user settings
+ * This should be called once in the application's bootstrap (main.ts)
+ */
+declare function configureApiSdk(userConfig: ApiSdkConfig): void;
+/**
+ * Get the current configuration
+ */
+declare function getConfig(): FullConfig;
+/**
+ * Reset configuration to defaults (for testing)
+ */
+declare function resetConfig(): void;
+/**
+ * Get refresh cookie options (convenience method)
+ */
+declare function getRefreshCookieOptions(): {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "strict" | "lax" | "none";
+    path: string;
+    maxAge: number;
+};
+/**
+ * Get JWT expiry settings (convenience method)
+ */
+declare function getJwtExpiry(): {
+    access: string;
+    refresh: string;
+    onboarding: string;
+};
+
+/**
+ * Hash a token using SHA-256
+ * @param token The token to hash
+ * @returns The hex-encoded SHA-256 hash
+ */
+declare function hashToken(token: string): string;
+/**
+ * Verify a token against its expected hash using constant-time comparison
+ * @param token The token to verify
+ * @param expectedHash The expected SHA-256 hash
+ * @returns true if the token matches the hash
+ */
+declare function verifyTokenHash(token: string, expectedHash: string): boolean;
+
 /**
  * Global authentication configuration module
  *
@@ -151,11 +328,17 @@ interface DatabaseModuleOptions {
      */
     primaryDb: PrimaryDbConfig;
     /**
-     * Drizzle schema object containing all tables and relations
+     * Drizzle schema object containing all tables
      * Import your schema from db/schema/index.ts and pass it here
      * @example import * as schema from '@/db/schema'
      */
     drizzleSchema: RegisteredSchema;
+    /**
+     * Drizzle relations object from defineRelations()
+     * Required for relational queries (db.query.*.findFirst/findMany)
+     * @example import { relations } from '@/db/schema'
+     */
+    drizzleRelations?: Record<string, any>;
     /**
      * Connection cache TTL in milliseconds
      * Idle connections will be closed after this period
@@ -556,22 +739,46 @@ declare class PrimaryDatabaseService implements OnModuleInit, OnModuleDestroy {
 }
 
 /**
- * Type-safe wrapper for Drizzle's RelationalQueryBuilder.
+ * Drizzle ORM v2 object-based where filter type.
+ * Supports simple equality, operators, AND/OR/NOT, and RAW SQL.
+ *
+ * @example
+ * ```typescript
+ * // Simple equality
+ * { email: 'user@example.com' }
+ *
+ * // With operators
+ * { age: { gt: 18, lt: 65 } }
+ *
+ * // AND/OR combinations
+ * { AND: [{ status: 'ACTIVE' }, { age: { gte: 18 } }] }
+ *
+ * // RAW SQL expression
+ * { RAW: (table) => sql`${table.email} ILIKE '%@gmail.com'` }
+ * ```
+ */
+type RelationsWhereFilter = Record<string, any>;
+/**
+ * Type-safe wrapper for Drizzle's RelationalQueryBuilder (v2 API).
  * This interface matches the method signatures of RelationalQueryBuilder
  * but properly binds the TSelect generic for type safety.
  *
  * We use this instead of RelationalQueryBuilder directly because
  * TypeScript cannot infer TSelect from the generic base repository context.
+ *
+ * @remarks
+ * Drizzle ORM v2 uses object-based `where` filters instead of SQL expressions.
+ * See: https://orm.drizzle.team/docs/relations-v1-v2
  */
 interface TypedRelationalQueryBuilder<TSelect> {
     findFirst(config?: {
-        where?: SQL;
+        where?: RelationsWhereFilter;
         with?: Record<string, unknown>;
         columns?: Record<string, boolean>;
     }): Promise<TSelect | undefined>;
     findMany(config?: {
-        where?: SQL;
-        orderBy?: SQL;
+        where?: RelationsWhereFilter;
+        orderBy?: Record<string, 'asc' | 'desc'>;
         limit?: number;
         offset?: number;
         with?: Record<string, unknown>;
@@ -610,17 +817,17 @@ interface TypedRelationalQueryBuilder<TSelect> {
  *     super(database, users);
  *   }
  *
- *   // Use Prisma-like relational query syntax (recommended)
+ *   // Use Drizzle v2 object-based where syntax (recommended)
  *   async findByEmail(email: string): Promise<User | undefined> {
  *     return this.model.findFirst({
- *       where: eq(users.email, email),
+ *       where: { email },
  *     });
  *   }
  *
- *   // Use Prisma-like with relations
+ *   // With relations
  *   async findWithRelations(id: string): Promise<User | undefined> {
  *     return this.model.findFirst({
- *       where: eq(users.id, id),
+ *       where: { id },
  *       with: { posts: true, profile: true }
  *     });
  *   }
@@ -633,7 +840,8 @@ declare abstract class PrimaryBaseRepository<TTable extends PgTable, TInsert = I
     protected readonly logger: Logger;
     /**
      * The table name extracted from the Drizzle table at runtime.
-     * Used to access the query API for this repository's table.
+     * Stored in camelCase to match Drizzle's query object keys.
+     * Example: 'email_verifications' -> 'emailVerifications'
      */
     private readonly tableName;
     /**
@@ -643,15 +851,15 @@ declare abstract class PrimaryBaseRepository<TTable extends PgTable, TInsert = I
      */
     protected get db(): TypedDrizzleClient;
     /**
-     * Model query API for THIS repository's table (Prisma-like syntax)
+     * Model query API for THIS repository's table (Drizzle v2 relational queries)
      * Scoped to only the table this repository manages.
      * Returns a type-safe wrapper around Drizzle's RelationalQueryBuilder.
      *
      * @example
      * ```typescript
-     * // Use relational queries with type safety
+     * // Use relational queries with v2 object-based where syntax
      * const user = await this.model.findFirst({
-     *   where: eq(users.id, id),
+     *   where: { id },
      *   with: { posts: true, profile: true }
      * });
      * ```
@@ -701,43 +909,60 @@ declare abstract class PrimaryBaseRepository<TTable extends PgTable, TInsert = I
      */
     findById(id: string): Promise<TSelect | undefined>;
     /**
-     * Find a single record with custom where clause
+     * Find a single record with custom where clause (Drizzle v2 object-based syntax)
      *
-     * @param where - SQL condition
+     * @param where - Object-based filter condition
      * @returns Promise resolving to the record or undefined if not found
      *
      * @example
      * ```typescript
-     * import { eq } from 'drizzle-orm';
-     * const user = await userRepository.findOne(eq(users.email, 'user@example.com'));
+     * // Simple equality
+     * const user = await userRepository.findOne({ email: 'user@example.com' });
+     *
+     * // With operators
+     * const user = await userRepository.findOne({ age: { gte: 18 } });
+     *
+     * // Multiple conditions (AND)
+     * const user = await userRepository.findOne({
+     *   email: 'user@example.com',
+     *   status: 'ACTIVE'
+     * });
      * ```
      */
-    findOne(where: SQL): Promise<TSelect | undefined>;
+    findOne(where: RelationsWhereFilter): Promise<TSelect | undefined>;
     /**
-     * Find multiple records
+     * Find multiple records (Drizzle v2 object-based syntax)
      *
      * @param options - Query options (where, orderBy, limit, offset)
      * @returns Promise resolving to an array of records
      *
      * @example
      * ```typescript
-     * import { eq, desc } from 'drizzle-orm';
-     *
      * // Find all users
      * const users = await userRepository.findMany();
      *
-     * // Find with filtering and pagination
+     * // Find with filtering and pagination (v2 object syntax)
      * const users = await userRepository.findMany({
-     *   where: eq(users.accountStatus, 'ACTIVE'),
-     *   orderBy: desc(users.createdAt),
+     *   where: { accountStatus: 'ACTIVE' },
+     *   orderBy: { createdAt: 'desc' },
      *   limit: 10,
      *   offset: 0
      * });
+     *
+     * // Multiple conditions
+     * const users = await userRepository.findMany({
+     *   where: {
+     *     AND: [
+     *       { status: 'ACTIVE' },
+     *       { age: { gte: 18 } }
+     *     ]
+     *   }
+     * });
      * ```
      */
     findMany(options?: {
-        where?: SQL;
-        orderBy?: SQL;
+        where?: RelationsWhereFilter;
+        orderBy?: Record<string, 'asc' | 'desc'>;
         limit?: number;
         offset?: number;
     }): Promise<TSelect[]>;
@@ -1138,8 +1363,8 @@ declare class RequestService {
      */
     getAccessToken(): string | null;
     /**
-     * Extract refresh token from session-id cookie
-     * Cookie name: session-id
+     * Extract refresh token from httpOnly cookie
+     * Cookie name is configurable via api-sdk config
      * @returns Refresh token or null if not found
      */
     getRefreshToken(): string | null;
@@ -1157,27 +1382,27 @@ declare class RequestService {
 }
 
 /**
- * Vritti Authentication Guard - Validates JWT tokens and tenant context
+ * Vritti Authentication Guard - Validates JWT access tokens and tenant context
  *
- * This guard performs comprehensive validation and attaches user data to request.
+ * This guard performs access token validation and attaches user data to request.
+ * NOTE: Refresh tokens are NOT validated here - they are only validated in
+ * /auth/token and /auth/refresh endpoints (session.service.ts).
  *
  * Validation Flow:
  * 1. Checks if endpoint is marked with @Public() decorator → skip all validation
  * 2. Checks if endpoint is marked with @Onboarding() decorator:
  *    - Requires token type='onboarding'
  *    - Validates JWT signature and expiry only
- *    - Skips tenant and refresh token validation
+ *    - Skips tenant validation
  *    - Attaches user data to request.user
  * 3. For regular endpoints (no decorator):
  *    - Rejects tokens with type='onboarding'
  *    - Validates access token (JWT signature, expiry, nbf)
- *    - Validates refresh token from session-id cookie
  *    - Validates tenant exists and is ACTIVE
  *    - Attaches user data to request.user
  *
  * Token Format:
  * - Access Token: "Authorization: Bearer <jwt_token>"
- * - Refresh Token: "session-id" cookie
  *
  * Token Types:
  * - type='onboarding': Limited access during registration flow (@Onboarding endpoints only)
@@ -1185,11 +1410,9 @@ declare class RequestService {
  *
  * Environment Variables Required:
  * - JWT_SECRET: Secret key to verify access tokens (required)
- * - JWT_REFRESH_SECRET: Secret key for refresh tokens (optional, falls back to JWT_SECRET)
  *
  * Error Responses:
  * - 401: Invalid/expired access token
- * - 401: Invalid/expired refresh token
  * - 401: Tenant not found or inactive
  * - 401: Tenant identifier not found
  * - 401: Token type mismatch (onboarding token on regular endpoint or vice versa)
@@ -1237,14 +1460,15 @@ declare class VrittiAuthGuard implements CanActivate {
      */
     private validateAccessToken;
     /**
-     * Validate refresh token with proper expiry checks
-     * Throws UnauthorizedException if token is invalid or expired
-     */
-    private validateRefreshToken;
-    /**
-     * Helper to validate refresh token with specific secret
+     * Validate that the access token is bound to the refresh token in the cookie.
+     * This prevents token theft - a stolen access token is useless without the
+     * corresponding refresh token cookie.
+     *
+     * @param context - The execution context containing the request
+     * @param validatedToken - The decoded and validated JWT token
+     * @throws UnauthorizedException if token binding validation fails
      */
-    private validateRefreshTokenWithSecret;
+    private validateRefreshTokenBinding;
 }
 
 /**
@@ -2270,4 +2494,4 @@ declare function generateCorrelationId(): string;
  */
 declare function addCorrelationIdToResponse(reply: FastifyReply, correlationId: string, headerName?: string): void;
 
-export { type ApiErrorResponse, AuthConfigModule, BadGatewayException, BadRequestException, BaseFieldException, ConflictException, type CorrelationContext, CorrelationIdMiddleware, CsrfGuard, DEFAULT_CORRELATION_HEADER, DatabaseModule, type DatabaseModuleOptions, type FieldError, ForbiddenException, GoneException, HttpExceptionFilter, HttpLoggerInterceptor, type HttpLoggerOptions, HttpModule, InternalServerErrorException, LOGGER_MODULE_OPTIONS, type LogFormat, type LogLevel, type LogMetadata, LoggerModule, type LoggerModuleAsyncOptions, type LoggerModuleOptions, type LoggerOptionsFactory, LoggerService, MethodNotAllowedException, NotAcceptableException, NotFoundException, NotImplementedException, Onboarding, PayloadTooLargeException, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, type ProblemDetails, Public, type RegisteredSchema, RequestTimeoutException, type SchemaRegistry, ServiceUnavailableException, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, TooManyRequestsException, type TypedDrizzleClient, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, ValidationException, VrittiAuthGuard, addCorrelationIdToResponse, correlationStorage, generateCorrelationId, getCorrelationContext, getHttpStatusTitle, runWithCorrelationContext, updateCorrelationContext };
+export { type ApiErrorResponse, type ApiSdkConfig, AuthConfigModule, BadGatewayException, BadRequestException, BaseFieldException, ConflictException, type CookieConfig, type CorrelationContext, CorrelationIdMiddleware, CsrfGuard, DEFAULT_CORRELATION_HEADER, DatabaseModule, type DatabaseModuleOptions, type FieldError, ForbiddenException, GoneException, type GuardConfig, HttpExceptionFilter, HttpLoggerInterceptor, type HttpLoggerOptions, HttpModule, InternalServerErrorException, type JwtConfig, LOGGER_MODULE_OPTIONS, type LogFormat, type LogLevel, type LogMetadata, LoggerModule, type LoggerModuleAsyncOptions, type LoggerModuleOptions, type LoggerOptionsFactory, LoggerService, MethodNotAllowedException, NotAcceptableException, NotFoundException, NotImplementedException, Onboarding, PayloadTooLargeException, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, type ProblemDetails, Public, type RegisteredSchema, RequestTimeoutException, type SchemaRegistry, ServiceUnavailableException, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, TooManyRequestsException, type TypedDrizzleClient, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, ValidationException, VrittiAuthGuard, addCorrelationIdToResponse, configureApiSdk, correlationStorage, defineConfig, generateCorrelationId, getConfig, getCorrelationContext, getHttpStatusTitle, getJwtExpiry, getRefreshCookieOptions, hashToken, resetConfig, runWithCorrelationContext, updateCorrelationContext, verifyTokenHash };