@vritti/api-sdk 0.1.1 → 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
  *
@@ -663,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;
     /**
@@ -1185,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;
@@ -1204,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)
@@ -1232,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)
@@ -1284,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;
 }
 
 /**
@@ -2317,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 };

package/dist/index.d.ts

@@ -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
  *
@@ -663,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;
     /**
@@ -1185,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;
@@ -1204,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)
@@ -1232,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)
@@ -1284,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;
 }
 
 /**
@@ -2317,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 };