@plyaz/auth 1.0.0

package/src/tokens/token-validator.ts

@@ -0,0 +1,311 @@
+/* eslint-disable no-magic-numbers */
+/**
+ * @fileoverview Token validator for @plyaz/auth
+ * @module @plyaz/auth/tokens/token-validator
+ * 
+ * @description
+ * Provides comprehensive JWT token validation including signature verification,
+ * expiration checks, blacklist validation, and issuer/audience verification.
+ * Used by guards and middleware to validate incoming authentication tokens.
+ * 
+ * @example
+ * ```typescript
+ * import { TokenValidator } from '@plyaz/auth';
+ * 
+ * const validator = new TokenValidator({
+ *   publicKey: 'your-public-key',
+ *   issuer: 'plyaz.com',
+ *   audience: 'plyaz-api'
+ * });
+ * 
+ * const payload = await validator.validateToken(token);
+ * ```
+ */
+
+import type { JwtPayload, Algorithm } from 'jsonwebtoken';
+import { verify } from 'jsonwebtoken';
+import { TokenBlacklist } from '../core/blacklist/token.blacklist';
+import { Buffer } from 'buffer';
+
+/**
+ * Token validation configuration
+ */
+export interface TokenValidatorConfig {
+  /** Public key for signature verification */
+  publicKey: string;
+  /** Expected token issuer */
+  issuer: string;
+  /** Expected token audience */
+  audience: string;
+  /** Algorithm for verification */
+  algorithm?: string;
+  /** Clock tolerance in seconds */
+  clockTolerance?: number;
+  /** Enable blacklist checking */
+  enableBlacklist?: boolean;
+}
+
+/**
+ * Validated token payload
+ */
+export interface ValidatedTokenPayload extends JwtPayload {
+  /** User ID (subject) */
+  sub: string;
+  /** Session ID */
+  sessionId?: string;
+  /** User roles */
+  roles?: string[];
+  /** User permissions */
+  permissions?: string[];
+  /** Token type */
+  type?: 'access' | 'refresh';
+}
+
+/**
+ * Token validation result
+ */
+export interface TokenValidationResult {
+  /** Validation success */
+  valid: boolean;
+  /** Decoded payload (if valid) */
+  payload?: ValidatedTokenPayload;
+  /** Error details (if invalid) */
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+/**
+ * Token validator implementation
+ * Validates JWT tokens with comprehensive security checks
+ */
+export class TokenValidator {
+  private readonly config: Required<TokenValidatorConfig>;
+  private readonly blacklist?: TokenBlacklist;
+
+  constructor(config: TokenValidatorConfig) {
+    this.config = {
+      algorithm: 'RS256',
+      clockTolerance: 30,
+      enableBlacklist: true,
+      ...config
+    };
+
+    if (this.config.enableBlacklist) {
+      this.blacklist = new TokenBlacklist({ keyPrefix: 'token:', defaultTTL: 3600 });
+    }
+  }
+
+  /**
+   * Validate JWT token with comprehensive checks
+   * @param token - JWT token to validate
+   * @returns Validation result with payload or error
+   */
+  async validateToken(token: string): Promise<TokenValidationResult> {
+    try {
+      // Basic format check
+      if (!token || typeof token !== 'string') {
+        return this.createErrorResult('INVALID_FORMAT', 'Token format is invalid');
+      }
+
+      // Check if token is blacklisted
+      if (this.blacklist && await this.blacklist.isBlacklisted(token)) {
+        return this.createErrorResult('TOKEN_REVOKED', 'Token has been revoked');
+      }
+
+      // Verify JWT signature and claims
+      const payload = verify(token, this.config.publicKey, {
+        issuer: this.config.issuer,
+        audience: this.config.audience,
+        algorithms: [this.config.algorithm as Algorithm],
+        clockTolerance: this.config.clockTolerance
+      }) as ValidatedTokenPayload;
+
+      // Additional payload validation
+      const validationError = this.validatePayload(payload);
+      if (validationError) {
+        return validationError;
+      }
+
+      return {
+        valid: true,
+        payload
+      };
+
+    } catch (error) {
+      return this.handleVerificationError(error as Error);
+    }
+  }
+
+  /**
+   * Validate access token specifically
+   * @param token - Access token to validate
+   * @returns Validation result
+   */
+  async validateAccessToken(token: string): Promise<TokenValidationResult> {
+    const result = await this.validateToken(token);
+    
+    if (result.valid && result.payload?.type && result.payload.type !== 'access') {
+      return this.createErrorResult('INVALID_TOKEN_TYPE', 'Expected access token');
+    }
+    
+    return result;
+  }
+
+  /**
+   * Validate refresh token specifically
+   * @param token - Refresh token to validate
+   * @returns Validation result
+   */
+  async validateRefreshToken(token: string): Promise<TokenValidationResult> {
+    const result = await this.validateToken(token);
+    
+    if (result.valid && result.payload?.type && result.payload.type !== 'refresh') {
+      return this.createErrorResult('INVALID_TOKEN_TYPE', 'Expected refresh token');
+    }
+    
+    return result;
+  }
+
+  /**
+   * Extract token payload without validation (for debugging)
+   * @param token - JWT token
+   * @returns Decoded payload or null
+   */
+  extractPayload(token: string): ValidatedTokenPayload | null {
+    try {
+      const parts = token.split('.');
+      if (parts.length !== 3) {
+        return null;
+      }
+
+      const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if token is expired (without full validation)
+   * @param token - JWT token
+   * @returns True if token is expired
+   */
+  isTokenExpired(token: string): boolean {
+    const payload = this.extractPayload(token);
+    
+    if (!payload?.exp) {
+      return true;
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    return payload.exp < now;
+  }
+
+  /**
+   * Get token expiration time
+   * @param token - JWT token
+   * @returns Expiration date or null
+   */
+  getTokenExpiration(token: string): Date | null {
+    const payload = this.extractPayload(token);
+    
+    if (!payload?.exp) {
+      return null;
+    }
+
+    return new Date(payload.exp * 1000);
+  }
+
+  /**
+   * Get time until token expires
+   * @param token - JWT token
+   * @returns Seconds until expiration or null
+   */
+  getTimeUntilExpiration(token: string): number | null {
+    const expiration = this.getTokenExpiration(token);
+    
+    if (!expiration) {
+      return null;
+    }
+
+    const now = Date.now();
+    const timeUntilExpiry = expiration.getTime() - now;
+    
+    return Math.max(0, Math.floor(timeUntilExpiry / 1000));
+  }
+
+  /**
+   * Validate token payload structure and claims
+   * @param payload - Decoded JWT payload
+   * @returns Error result if invalid, null if valid
+   * @private
+   */
+  private validatePayload(payload: ValidatedTokenPayload): TokenValidationResult | null {
+    // Check required claims
+    if (!payload.sub) {
+      return this.createErrorResult('MISSING_SUBJECT', 'Token missing subject claim');
+    }
+
+    if (!payload.iat) {
+      return this.createErrorResult('MISSING_ISSUED_AT', 'Token missing issued at claim');
+    }
+
+    if (!payload.exp) {
+      return this.createErrorResult('MISSING_EXPIRATION', 'Token missing expiration claim');
+    }
+
+    // Validate issued at time (not in future)
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.iat > now + this.config.clockTolerance) {
+      return this.createErrorResult('TOKEN_NOT_YET_VALID', 'Token issued in the future');
+    }
+
+    // Additional custom validations can be added here
+    
+    return null;
+  }
+
+  /**
+   * Handle JWT verification errors
+   * @param error - Verification error
+   * @returns Error result
+   * @private
+   */
+  private handleVerificationError(error : Error): TokenValidationResult {
+    if (error.name === 'TokenExpiredError') {
+      return this.createErrorResult('TOKEN_EXPIRED', 'Token has expired', error);
+    }
+    
+    if (error.name === 'JsonWebTokenError') {
+      return this.createErrorResult('INVALID_SIGNATURE', 'Token signature is invalid', error);
+    }
+    
+    if (error.name === 'NotBeforeError') {
+      return this.createErrorResult('TOKEN_NOT_YET_VALID', 'Token not yet valid', error);
+    }
+
+    return this.createErrorResult('VALIDATION_FAILED', error.message ?? 'Token validation failed', error);
+  }
+
+  /**
+   * Create error result
+   * @param code - Error code
+   * @param message - Error message
+   * @param details - Additional error details
+   * @returns Error result
+   * @private
+   */
+  private createErrorResult(code: string, message: string, details?: unknown): TokenValidationResult {
+    return {
+      valid: false,
+      error: {
+        code,
+        message,
+        details
+      }
+    };
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,28 @@
+{
+  "extends": "@plyaz/devtools/configs/tsconfig.build.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true,
+      "strict": true,
+    "strictNullChecks": true,
+    "moduleResolution": "bundler",
+    "module": "preserve",
+      "lib": ["ES2021", "DOM"],
+    "jsx": "react-jsx",
+    "types": ["node", "react"],
+    "target": "ES2017",
+    "resolveJsonModule": true,
+    "baseUrl": "./src",
+    "paths": {
+      "@/*": ["*"],
+      "@common/*": ["common/utils/*"],
+      "@providers/*": ["providers/clerk-supabase/*"],
+      "@server/*": ["server/*"],
+      "@strategies/*": ["server/strategies/*"],
+      "@libs/*" : ["src/libs/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "build", "coverage", "tests"]
+}

package/tsconfig.json

@@ -0,0 +1,38 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "composite": true,
+    "moduleResolution": "bundler",
+      "strict": true,
+    "strictNullChecks": true,
+    "module": "preserve",
+    "jsx": "react-jsx",
+    "types": ["node", "react", "react-dom"],
+      "lib": ["ES2021", "DOM"],
+    "resolveJsonModule": true,
+       "target": "ES2017",
+    "baseUrl": "./src",
+    "paths": {
+      "@/*": ["*"],
+      "@/enums": ["common/enums"],
+      "@/interfaces": ["common/interfaces"],
+      "@/regex": ["common/regex"],
+      "@/constants": ["common/constants"],
+      "@/errors": ["common/errors"],
+      "@/types": ["types"],
+      "@/core": ["core"],
+      "@/rbac": ["rbac"],
+      "@/security": ["security"],
+      "@/session": ["session"],
+      "@/tokens": ["tokens"],
+      "@/db": ["db"],
+      "@/server": ["server"],
+      "@/client": ["client"],
+      "@/flows": ["flows"],
+      "@/providers": ["providers"],
+      "@libs/*" : ["src/libs/*"]
+    }
+  },
+  "include": ["**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tsup.config.mjs

@@ -0,0 +1,28 @@
+import { createTsupConfig } from "@plyaz/devtools/configs/tsup.base.config.mjs";
+
+export default createTsupConfig({
+  entry: {
+    index: "src/index.ts",
+    "common/index": "src/common/utils/index.ts",
+  },
+  dts: false,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  external: [
+    '@nestjs/common',
+    '@nestjs/core', 
+    '@nestjs/jwt',
+    '@nestjs/config',
+    'react',
+    'zustand',
+    'jsonwebtoken',
+    '@clerk/clerk-sdk-node',
+    '@supabase/supabase-js'
+  ],
+  outExtension({ format }) {
+    return {
+      js: format === 'cjs' ? '.cjs' : '.mjs',
+    };
+  },
+});

package/vitest.config.mjs

@@ -0,0 +1,16 @@
+import { createVitestConfig } from '@plyaz/devtools/configs/vitest.config';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const config = createVitestConfig(__dirname);
+
+// Configure for type-only package - run minimal test to satisfy CI
+config.test = {
+  ...config.test,
+  passWithNoTests: true
+};
+
+export default config;

package/vitest.setup.d.ts

@@ -0,0 +1,2 @@
+import '@plyaz/devtools/configs/vitest.setup';
+//# sourceMappingURL=vitest.setup.d.ts.map

package/vitest.setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.setup.d.ts","sourceRoot":"","sources":["vitest.setup.ts"],"names":[],"mappings":"AAAA,OAAO,sCAAsC,CAAC"}

package/vitest.setup.ts

@@ -0,0 +1 @@
+import '@plyaz/devtools/configs/vitest.setup';