@plyaz/auth 1.0.0

package/src/common/types/index.ts

@@ -0,0 +1,297 @@
+/**
+ * @fileoverview Common types and utility types for @plyaz/auth
+ * @module @plyaz/auth/common/types
+ */
+
+/**
+ * Utility type to make specific properties optional
+ * @template T - The base type
+ * @template K - Keys to make optional
+ */
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/**
+ * Utility type to make specific properties required
+ * @template T - The base type
+ * @template K - Keys to make required
+ */
+export type RequiredFields<T, K extends keyof T> = T & Required<Pick<T, K>>;
+
+/**
+ * Utility type for deep partial objects
+ * @template T - The type to make deeply partial
+ */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * User account status enumeration
+ */
+export type UserStatus = 'active' | 'inactive' | 'suspended' | 'pending';
+
+/**
+ * Available permission actions for RBAC
+ */
+export type PermissionAction = 'create' | 'read' | 'update' | 'delete' | 'manage' | '*';
+
+/**
+ * Resource type identifier (e.g., 'users', 'posts', 'campaigns')
+ */
+export type ResourceType = string;
+
+/**
+ * Permission string format: resource:action
+ * @example 'users:read', 'posts:create', 'campaigns:manage'
+ */
+export type PermissionString = `${ResourceType}:${PermissionAction}`;
+
+/**
+ * Base configuration interface for all auth components
+ */
+export interface BaseConfig {
+  /** Whether the component is enabled */
+  enabled: boolean;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Authentication event structure for audit logging
+ */
+export interface AuthEvent {
+  /** Event type identifier */
+  type: string;
+  /** User ID associated with the event */
+  userId?: string;
+  /** Session ID associated with the event */
+  sessionId?: string;
+  /** Event timestamp */
+  timestamp: Date;
+  /** Additional event metadata */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Generic callback function for authentication events
+ * @template T - The data type passed to the callback
+ */
+export type AuthCallback<T > = (data: T) => void | Promise<void>;
+
+/**
+ * Error callback function type
+ */
+export type ErrorCallback = (error: Error) => void | Promise<void>;
+
+/**
+ * Standard API response structure
+ * @template T - The data type returned in the response
+ */
+export interface ApiResponse<T> {
+  /** Whether the request was successful */
+  success: boolean;
+  /** Response data (if successful) */
+  data?: T;
+  /** Error information (if failed) */
+  error?: {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: unknown;
+  };
+  /** Response metadata */
+  meta?: {
+    /** Response timestamp */
+    timestamp: string;
+    /** Unique request identifier */
+    requestId?: string;
+  };
+}
+
+/**
+ * Pagination parameters for list queries
+ */
+export interface PaginationParams {
+  /** Page number (1-based) */
+  page?: number;
+  /** Number of items per page */
+  limit?: number;
+  /** Number of items to skip */
+  offset?: number;
+}
+
+/**
+ * Paginated response structure
+ * @template T - The type of items in the response
+ */
+export interface PaginatedResponse<T> {
+  /** Array of items for the current page */
+  items: T[];
+  /** Total number of items across all pages */
+  total: number;
+  /** Current page number */
+  page: number;
+  /** Number of items per page */
+  limit: number;
+  /** Whether there is a next page */
+  hasNext: boolean;
+  /** Whether there is a previous page */
+  hasPrev: boolean;
+}
+
+/**
+ * Generic filter parameters for queries
+ */
+export interface FilterParams {
+  [key: string]: unknown;
+}
+
+/**
+ * Sort parameters for ordered queries
+ */
+export interface SortParams {
+  /** Field to sort by */
+  field: string;
+  /** Sort order */
+  order: 'asc' | 'desc';
+}
+
+/**
+ * Audit log entry for tracking system changes
+ */
+export interface AuditLog {
+  /** Unique audit log identifier */
+  id: string;
+  /** Action performed (e.g., 'create', 'update', 'delete') */
+  action: string;
+  /** Resource type affected */
+  resource: string;
+  /** Specific resource identifier */
+  resourceId?: string;
+  /** User who performed the action */
+  userId?: string;
+  /** Session identifier */
+  sessionId?: string;
+  /** Client IP address */
+  ipAddress?: string;
+  /** Client user agent */
+  userAgent?: string;
+  /** When the action occurred */
+  timestamp: Date;
+  /** Field-level changes made */
+  changes?: Record<string, { from: string; to: string }>;
+  /** Additional audit metadata */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Cache entry structure
+ * @template T - The type of cached value
+ */
+export interface CacheEntry<T> {
+  /** Cached value */
+  value: T;
+  /** Expiration timestamp (Unix timestamp) */
+  expiresAt: number;
+  /** Creation timestamp (Unix timestamp) */
+  createdAt: number;
+}
+
+/**
+ * Cache performance statistics
+ */
+export interface CacheStats {
+  /** Number of cache hits */
+  hits: number;
+  /** Number of cache misses */
+  misses: number;
+  /** Current cache size */
+  size: number;
+  /** Hit rate percentage (0-1) */
+  hitRate: number;
+}
+
+/**
+ * Validation rule definition for form fields
+ */
+export interface ValidationRule {
+  /** Field name to validate */
+  field: string;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Expected data type */
+  type?: 'string' | 'number' | 'boolean' | 'email' | 'url';
+  /** Minimum length for strings */
+  minLength?: number;
+  /** Maximum length for strings */
+  maxLength?: number;
+  /** Regular expression pattern to match */
+  pattern?: RegExp;
+  /** Custom validation function */
+  custom?: (value: unknown) => boolean | string;
+}
+
+/**
+ * Result of field validation
+ */
+export interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** Array of validation errors */
+  errors: Array<{
+    /** Field that failed validation */
+    field: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: string;
+  }>;
+}
+
+/**
+ * Database connection configuration
+ */
+export interface DatabaseConfig {
+  /** Database host */
+  host: string;
+  /** Database port */
+  port: number;
+  /** Database name */
+  database: string;
+  /** Database username */
+  username: string;
+  /** Database password */
+  password: string;
+  /** Enable SSL connection */
+  ssl?: boolean;
+  /** Connection pool settings */
+  pool?: {
+    /** Minimum pool connections */
+    min: number;
+    /** Maximum pool connections */
+    max: number;
+  };
+}
+
+/**
+ * Generic metrics collection
+ */
+export interface Metrics {
+  [key: string]: number | string | boolean;
+}
+
+/**
+ * Performance metrics for monitoring
+ */
+export interface PerformanceMetrics {
+  /** Operation duration in milliseconds */
+  duration: number;
+  /** Memory usage in bytes */
+  memory: number;
+  /** CPU usage percentage */
+  cpu: number;
+  /** Measurement timestamp */
+  timestamp: Date;
+}

package/src/common/utils/index.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Common utility functions for @plyaz/auth
+ * @module @plyaz/auth/common/utils
+ */
+
+import { NUMERIX } from "@plyaz/config";
+
+/**
+ * Generate a random string of specified length using alphanumeric characters
+ * @param length - Length of the random string (default: 32)
+ * @returns Random alphanumeric string
+ * @example
+ * ```typescript
+ * const randomId = generateRandomString(16); // "a1B2c3D4e5F6g7H8"
+ * ```
+ */
+export function generateRandomString(length: number = 32): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+/**
+ * Generate a cryptographically secure random ID with timestamp prefix
+ * @returns Unique identifier with timestamp and random suffix
+ * @example
+ * ```typescript
+ * const id = generateSecureId(); // "1703123456789_a1B2c3D4e5F6g7H8"
+ * ```
+ */
+export function generateSecureId(): string {
+  return `${Date.now()}_${generateRandomString(NUMERIX.SIXTEEN)}`;
+}
+
+/**
+ * Sleep for specified milliseconds (async delay)
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after the delay
+ * @example
+ * ```typescript
+ * await sleep(1000); // Wait 1 second
+ * ```
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => globalThis.setTimeout(resolve, ms));
+}
+
+/**
+ * Mask sensitive data fields for safe logging
+ * @param data - Object containing potentially sensitive data
+ * @param sensitiveFields - Array of field names to mask (default: ['password', 'token', 'secret'])
+ * @returns Object with sensitive fields masked
+ * @example
+ * ```typescript
+ * const masked = maskSensitiveData({ email: 'user@example.com', password: 'secret123' });
+ * // Result: { email: 'user@example.com', password: 'secr*****' }
+ * ```
+ */
+export function maskSensitiveData(
+  data: unknown,
+  sensitiveFields: string[] = ['password', 'token', 'secret']
+): unknown {
+  if (typeof data !== 'object' || data === null) {
+    return data;
+  }
+
+  // Type assertion to allow indexing by string
+  const masked: Record<string, string> = { ...(data as Record<string, string>) };
+  const four  = 4;
+  for (const field of sensitiveFields) {
+    if (field in masked) {
+      const value = masked[field];
+      if (typeof value === 'string' && value.length > 0) {
+        masked[field] = value.substring(0, four) + '*'.repeat(Math.max(0, value.length - four));
+      }
+    }
+  }
+  
+  return masked;
+}
+

package/src/core/blacklist/token.blacklist.ts

@@ -0,0 +1,60 @@
+export interface TokenBlacklistConfig {
+  redisUrl?: string;
+  keyPrefix: string;
+  defaultTTL: number;
+}
+
+export class TokenBlacklist {
+  private blacklistedTokens = new Map<string, number>();
+
+  constructor(private config: TokenBlacklistConfig) {}
+
+  async add(tokenId: string, expiresAt: number): Promise<void> {
+    const ttl = Math.max(0, expiresAt - Date.now());
+    this.blacklistedTokens.set(tokenId, Date.now() + ttl);
+    
+    // Auto-cleanup expired tokens
+    globalThis.setTimeout(() => {
+      this.blacklistedTokens.delete(tokenId);
+    }, ttl);
+  }
+
+  async blacklistToken(tokenId: string, expiresAt: number): Promise<void> {
+    return this.add(tokenId, expiresAt);
+  }
+
+  async isBlacklisted(tokenId: string): Promise<boolean> {
+    const expiry = this.blacklistedTokens.get(tokenId);
+    if (!expiry) return false;
+    
+    if (expiry < Date.now()) {
+      this.blacklistedTokens.delete(tokenId);
+      return false;
+    }
+    
+    return true;
+  }
+
+  async blacklistAllUserTokens(userId: string, issuedBefore: number): Promise<void> {
+    // In production, this would use Redis with a user-specific key
+    // For now, we'll use a simple approach
+    const userKey = `user:${userId}:blacklist_before`;
+    this.blacklistedTokens.set(userKey, issuedBefore);
+  }
+
+  async isUserTokenBlacklisted(userId: string, tokenIssuedAt: number): Promise<boolean> {
+    const userKey = `user:${userId}:blacklist_before`;
+    const blacklistBefore = this.blacklistedTokens.get(userKey);
+    
+    return blacklistBefore ? tokenIssuedAt < blacklistBefore : false;
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    this.blacklistedTokens.forEach((expiry, key) => {
+      if (expiry < now) {
+        this.blacklistedTokens.delete(key);
+      }
+    });
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,2 @@
+export * from './jwt/jwt.manager';
+export * from './session/session.manager';

package/src/core/jwt/jwt.manager.ts

@@ -0,0 +1,131 @@
+import { sign, verify, type JwtPayload, type SignOptions } from "jsonwebtoken";
+import type { AuthTokens } from '@plyaz/types';
+import { NUMERIX } from "@plyaz/config";
+
+// Define the token payload interface
+export interface TokenPayload extends JwtPayload {
+  sub: string;
+  type: "access" | "refresh" | "verification";
+}
+
+// Define the StringValue type to match what jsonwebtoken expects
+// Define the StringValue type to match what jsonwebtoken expects
+type StringValue = `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+
+
+export class JwtManager {
+  private config: {
+    privateKey: string;
+    publicKey: string;
+    issuer: string;
+    audience: string;
+  };
+  private algorithm: "RS256" | "HS256" | "ES256" | "HS512";
+
+  constructor(
+    config: typeof JwtManager.prototype.config,
+    algorithm: "RS256" | "HS256" | "ES256" | "HS512"
+  ) {
+    this.config = config;
+    this.algorithm = algorithm;
+  }
+
+  // -------------------
+  // Generic Token Generator
+  // -------------------
+  private generateToken(
+    payload: Omit<TokenPayload, "iss" | "aud" | "iat" | "exp">,
+    expiresIn: string | number = "1h"
+  ): string {
+    const signOptions: SignOptions = {
+      algorithm: this.algorithm,
+      expiresIn: expiresIn as StringValue | number,
+      issuer: this.config.issuer,
+      audience: this.config.audience,
+    };
+
+    return sign(payload, this.config.privateKey, signOptions);
+  }
+
+  generateTokens(
+    user: { id: string },
+    accessTokenExpiry: string | number = "1h",
+    refreshTokenExpiry: string | number = "7d"
+  ): AuthTokens {
+    const accessToken = this.generateToken({ sub: user.id, type: "access" }, accessTokenExpiry);
+    const refreshToken = this.generateToken({ sub: user.id, type: "refresh" }, refreshTokenExpiry);
+
+    // Calculate the actual expiration time in seconds
+    let expiresIn: number;
+    if (typeof accessTokenExpiry === 'string') {
+      // Parse time strings like "1h", "30m", etc.
+      const match = accessTokenExpiry.match(/^(\d+)([smhd])$/);
+      if (match) {
+        const value = globalThis.parseInt(match[1], NUMERIX.TEN);
+        const unit = match[2];
+        const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+        expiresIn = value * multipliers[unit];
+      } else {
+        expiresIn = NUMERIX.THIRTY_SIX_HUNDERD; // Default to 1 hour
+      }
+    } else {
+      expiresIn = accessTokenExpiry;
+    }
+
+    return { 
+      accessToken, 
+      refreshToken,
+      expiresIn,
+      tokenType: "Bearer"
+    };
+  }
+
+  // Generate access token
+  generateAccessToken(userId: string, expiresIn: string | number = "1h"): string {
+    return this.generateToken({ sub: userId, type: "access" }, expiresIn);
+  }
+
+  // Generate refresh token
+  generateRefreshToken(userId: string, expiresIn: string | number = "7d"): string {
+    return this.generateToken({ sub: userId, type: "refresh" }, expiresIn);
+  }
+
+  // Generate verification token (email confirmation)
+  generateVerificationToken(userId: string, expiresIn: string | number = "24h"): string {
+    return this.generateToken({ sub: userId, type: "verification" }, expiresIn);
+  }
+
+  // -------------------
+  // Token Verification
+  // -------------------
+  private verifyToken(token: string, tokenType: "access" | "refresh" | "verification"): TokenPayload {
+    const decoded = verify(token, this.config.publicKey, {
+      algorithms: [this.algorithm],
+      issuer: this.config.issuer,
+      audience: this.config.audience,
+    });
+
+    if (typeof decoded === "string") throw new Error(`Invalid ${tokenType} token payload`);
+    
+    const payload = decoded as JwtPayload;
+    
+    // Verify the token type
+    if (payload.type !== tokenType) {
+      throw new Error(`Invalid token type. Expected ${tokenType}, got ${payload.type}`);
+    }
+    
+    return payload as TokenPayload;
+  }
+
+  verifyAccessToken(token: string): TokenPayload {
+    return this.verifyToken(token, "access");
+  }
+
+  verifyRefreshToken(token: string): TokenPayload {
+    return this.verifyToken(token, "refresh");
+  }
+
+  verifyVerificationToken(token: string): TokenPayload {
+    return this.verifyToken(token, "verification");
+  }
+}

package/src/core/session/session.manager.ts

@@ -0,0 +1,56 @@
+
+import type { Session, SessionRepository, SessionConfig, CreateSessionData } from '@plyaz/types';
+
+
+
+export class SessionManager {
+  constructor(
+    private sessionRepo: SessionRepository,
+    private config: SessionConfig
+  ) {}
+
+  async createSession(userId: string, deviceInfo: Record<string,unknown>): Promise<Session> {
+    await this.enforceSessionLimits(userId);
+    
+    const sessionData: CreateSessionData = {
+      userId,
+      provider: 'default',
+      expiresAt: new Date(Date.now() + this.config.sessionTTL),
+      metadata:deviceInfo,
+    };
+
+    return this.sessionRepo.create(sessionData);
+  }
+
+  async getSession(sessionId: string): Promise<Session | null> {
+    const session = await this.sessionRepo.findById(sessionId);
+    if (!session || session.expiresAt < new Date()) {
+      return null;
+    }
+    return session;
+  }
+
+  async updateLastActive(sessionId: string): Promise<void> {
+    await this.sessionRepo.updateLastActive(sessionId);
+  }
+
+  async invalidateSession(sessionId: string): Promise<void> {
+    await this.sessionRepo.delete(sessionId);
+  }
+
+  async invalidateAllUserSessions(userId: string): Promise<void> {
+    await this.sessionRepo.deleteByUserId(userId);
+  }
+
+  private async enforceSessionLimits(userId: string): Promise<void> {
+    const sessions = await this.sessionRepo.findByUserId(userId);
+    if (sessions.length >= this.config.maxConcurrentSessions) {
+      const oldestSession = sessions.sort((a, b) => 
+        a.lastActivityAt.getTime() - b.lastActivityAt.getTime()
+      )[0];
+      await this.sessionRepo.delete(oldestSession.id);
+    }
+  }
+
+ 
+}