@etcsec-com/etc-collector 1.4.0

package/src/data/repositories/token.repository.ts

@@ -0,0 +1,160 @@
+import Database from 'better-sqlite3';
+import { Token, TokenCreateInput, ActiveToken } from '../models/Token.model';
+
+/**
+ * Token Repository
+ * Handles CRUD operations for JWT tokens in SQLite database
+ * Uses synchronous better-sqlite3 for thread-safe operations
+ */
+export class TokenRepository {
+  constructor(private db: Database.Database) {}
+
+  /**
+   * Create a new token record
+   * @param input - Token creation data
+   * @returns The created token with generated ID
+   */
+  create(input: TokenCreateInput): Token {
+    const stmt = this.db.prepare(`
+      INSERT INTO tokens (jti, public_key, expires_at, max_uses, metadata)
+      VALUES (@jti, @public_key, @expires_at, @max_uses, @metadata)
+    `);
+
+    stmt.run({
+      jti: input.jti,
+      public_key: input.public_key,
+      expires_at: input.expires_at,
+      max_uses: input.max_uses ?? 0,
+      metadata: input.metadata ?? null,
+    });
+
+    return this.findByJti(input.jti)!;
+  }
+
+  /**
+   * Find a token by its JTI (JWT ID)
+   * @param jti - The JWT ID to search for
+   * @returns The token if found, null otherwise
+   */
+  findByJti(jti: string): Token | null {
+    const stmt = this.db.prepare(`
+      SELECT id, jti, public_key, created_at, expires_at, max_uses, used_count,
+             revoked_at, revoked_by, revoked_reason, metadata
+      FROM tokens
+      WHERE jti = ?
+    `);
+
+    return (stmt.get(jti) as Token | undefined) ?? null;
+  }
+
+  /**
+   * Get all tokens (including expired and revoked)
+   * @returns Array of all tokens
+   */
+  findAll(): Token[] {
+    const stmt = this.db.prepare(`
+      SELECT id, jti, public_key, created_at, expires_at, max_uses, used_count,
+             revoked_at, revoked_by, revoked_reason, metadata
+      FROM tokens
+      ORDER BY created_at DESC
+    `);
+
+    return stmt.all() as Token[];
+  }
+
+  /**
+   * Get all active tokens (not expired, not revoked, within usage limits)
+   * Uses the v_active_tokens view for optimized query
+   * @returns Array of active tokens with remaining_uses calculated
+   */
+  findActive(): ActiveToken[] {
+    const stmt = this.db.prepare(`
+      SELECT id, jti, created_at, expires_at, max_uses, used_count, remaining_uses
+      FROM v_active_tokens
+      ORDER BY created_at DESC
+    `);
+
+    return stmt.all() as ActiveToken[];
+  }
+
+  /**
+   * Increment the usage count for a token
+   * @param jti - The JWT ID of the token to increment
+   * @throws Error if token not found or usage limit exceeded
+   */
+  incrementUsage(jti: string): void {
+    const stmt = this.db.prepare(`
+      UPDATE tokens
+      SET used_count = used_count + 1
+      WHERE jti = ?
+        AND (max_uses = 0 OR used_count < max_uses)
+        AND revoked_at IS NULL
+        AND datetime(expires_at) > datetime('now')
+    `);
+
+    const result = stmt.run(jti);
+
+    if (result.changes === 0) {
+      throw new Error(`Token not found, expired, revoked, or usage limit exceeded: ${jti}`);
+    }
+  }
+
+  /**
+   * Revoke a token, making it unusable
+   * @param jti - The JWT ID to revoke
+   * @param revokedBy - Identifier of who revoked the token
+   * @param reason - Reason for revocation
+   * @throws Error if token not found or already revoked
+   */
+  revoke(jti: string, revokedBy: string, reason: string): void {
+    const stmt = this.db.prepare(`
+      UPDATE tokens
+      SET revoked_at = datetime('now'),
+          revoked_by = ?,
+          revoked_reason = ?
+      WHERE jti = ?
+        AND revoked_at IS NULL
+    `);
+
+    const result = stmt.run(revokedBy, reason, jti);
+
+    if (result.changes === 0) {
+      throw new Error(`Token not found or already revoked: ${jti}`);
+    }
+  }
+
+  /**
+   * Delete all expired tokens from the database
+   * Used for cleanup operations
+   * @returns Number of tokens deleted
+   */
+  deleteExpired(): number {
+    const stmt = this.db.prepare(`
+      DELETE FROM tokens
+      WHERE datetime(expires_at) <= datetime('now')
+    `);
+
+    const result = stmt.run();
+    return result.changes;
+  }
+
+  /**
+   * Count total number of tokens
+   * @returns Total token count
+   */
+  count(): number {
+    const stmt = this.db.prepare('SELECT COUNT(*) as count FROM tokens');
+    const result = stmt.get() as { count: number };
+    return result.count;
+  }
+
+  /**
+   * Count number of active tokens
+   * @returns Active token count
+   */
+  countActive(): number {
+    const stmt = this.db.prepare('SELECT COUNT(*) as count FROM v_active_tokens');
+    const result = stmt.get() as { count: number };
+    return result.count;
+  }
+}

package/src/providers/azure/auth.provider.ts

@@ -0,0 +1,14 @@
+/**
+ * Azure OAuth 2.0 Authentication Provider
+ * Handles client credentials flow
+ * TODO: Full implementation in Story 1.6
+ */
+export class AzureAuthProvider {
+  async getAccessToken(): Promise<string> {
+    throw new Error('Azure auth token not implemented yet');
+  }
+
+  async refreshToken(): Promise<string> {
+    throw new Error('Azure token refresh not implemented yet');
+  }
+}

package/src/providers/azure/azure-errors.ts

@@ -0,0 +1,189 @@
+/**
+ * Azure Error Types
+ *
+ * Custom error classes for Microsoft Graph / Azure AD operations.
+ * Provides specific error types for different failure scenarios.
+ *
+ * Task 2: Create Error Types for Azure Operations (Story 1.6)
+ */
+
+/**
+ * Base Azure Error
+ *
+ * Base class for all Azure/Microsoft Graph-related errors.
+ */
+export class AzureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AzureError';
+    Object.setPrototypeOf(this, AzureError.prototype);
+  }
+}
+
+/**
+ * Azure Authentication Error
+ *
+ * Thrown when OAuth 2.0 authentication fails.
+ */
+export class AzureAuthenticationError extends AzureError {
+  public readonly tenantId: string;
+  public readonly clientId: string;
+  public override readonly cause?: Error;
+
+  constructor(message: string, tenantId: string, clientId: string, cause?: Error) {
+    super(message);
+    this.name = 'AzureAuthenticationError';
+    this.tenantId = tenantId;
+    this.clientId = clientId;
+    this.cause = cause;
+    Object.setPrototypeOf(this, AzureAuthenticationError.prototype);
+  }
+}
+
+/**
+ * Azure API Error
+ *
+ * Thrown when Microsoft Graph API request fails.
+ */
+export class AzureAPIError extends AzureError {
+  public readonly statusCode?: number;
+  public readonly endpoint: string;
+  public override readonly cause?: Error;
+
+  constructor(message: string, endpoint: string, statusCode?: number, cause?: Error) {
+    super(message);
+    this.name = 'AzureAPIError';
+    this.endpoint = endpoint;
+    this.statusCode = statusCode;
+    this.cause = cause;
+    Object.setPrototypeOf(this, AzureAPIError.prototype);
+  }
+}
+
+/**
+ * Azure Rate Limit Error
+ *
+ * Thrown when Graph API rate limit (429) is exceeded.
+ */
+export class AzureRateLimitError extends AzureError {
+  public readonly retryAfter: number; // seconds
+  public readonly endpoint: string;
+
+  constructor(message: string, endpoint: string, retryAfter: number) {
+    super(message);
+    this.name = 'AzureRateLimitError';
+    this.endpoint = endpoint;
+    this.retryAfter = retryAfter;
+    Object.setPrototypeOf(this, AzureRateLimitError.prototype);
+  }
+}
+
+/**
+ * Azure Timeout Error
+ *
+ * Thrown when Graph API request times out.
+ */
+export class AzureTimeoutError extends AzureError {
+  public readonly operation: string;
+  public readonly timeoutMs: number;
+
+  constructor(message: string, operation: string, timeoutMs: number) {
+    super(message);
+    this.name = 'AzureTimeoutError';
+    this.operation = operation;
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, AzureTimeoutError.prototype);
+  }
+}
+
+/**
+ * Azure Permission Error
+ *
+ * Thrown when application doesn't have required permissions.
+ */
+export class AzurePermissionError extends AzureError {
+  public readonly requiredPermissions: string[];
+  public readonly endpoint: string;
+
+  constructor(message: string, endpoint: string, requiredPermissions: string[]) {
+    super(message);
+    this.name = 'AzurePermissionError';
+    this.endpoint = endpoint;
+    this.requiredPermissions = requiredPermissions;
+    Object.setPrototypeOf(this, AzurePermissionError.prototype);
+  }
+}
+
+/**
+ * Azure Configuration Error
+ *
+ * Thrown when Azure configuration is invalid or missing.
+ */
+export class AzureConfigurationError extends AzureError {
+  public readonly configKey: string;
+
+  constructor(message: string, configKey: string) {
+    super(message);
+    this.name = 'AzureConfigurationError';
+    this.configKey = configKey;
+    Object.setPrototypeOf(this, AzureConfigurationError.prototype);
+  }
+}
+
+/**
+ * Azure Token Expired Error
+ *
+ * Thrown when access token has expired and needs refresh.
+ */
+export class AzureTokenExpiredError extends AzureError {
+  public readonly expiresAt: Date;
+
+  constructor(message: string, expiresAt: Date) {
+    super(message);
+    this.name = 'AzureTokenExpiredError';
+    this.expiresAt = expiresAt;
+    Object.setPrototypeOf(this, AzureTokenExpiredError.prototype);
+  }
+}
+
+/**
+ * Check if an error is retryable
+ *
+ * Determines if an Azure operation should be retried based on error type.
+ * Rate limit errors (429) and transient network errors are retryable.
+ *
+ * @param error - The error to check
+ * @returns True if the error is retryable
+ */
+export function isRetryableError(error: Error): boolean {
+  // Rate limit errors are retryable with delay
+  if (error instanceof AzureRateLimitError) {
+    return true;
+  }
+
+  // Timeout errors are retryable
+  if (error instanceof AzureTimeoutError) {
+    return true;
+  }
+
+  // API errors with certain status codes are retryable
+  if (error instanceof AzureAPIError) {
+    const retryableStatusCodes = [429, 500, 502, 503, 504];
+    return error.statusCode ? retryableStatusCodes.includes(error.statusCode) : false;
+  }
+
+  // Network errors (ECONNREFUSED, ETIMEDOUT, etc.) are retryable
+  if ('code' in error) {
+    const networkErrorCodes = [
+      'ECONNREFUSED',
+      'ECONNRESET',
+      'ETIMEDOUT',
+      'ENOTFOUND',
+      'ENETUNREACH',
+      'EHOSTUNREACH',
+    ];
+    return networkErrorCodes.includes((error as { code: string }).code);
+  }
+
+  return false;
+}

package/src/providers/azure/azure-retry.ts

@@ -0,0 +1,168 @@
+/**
+ * Azure Retry Logic
+ *
+ * Provides retry functionality for Azure/Microsoft Graph API operations.
+ * Implements exponential backoff with jitter and special handling for rate limits (429).
+ *
+ * Task 5: Add retry logic with exponential backoff (Story 1.6)
+ */
+
+import { AzureRateLimitError, isRetryableError } from './azure-errors';
+
+/**
+ * Retry options
+ */
+export interface RetryOptions {
+  maxAttempts?: number; // default: 3
+  initialDelay?: number; // milliseconds, default: 1000
+  maxDelay?: number; // milliseconds, default: 30000
+  backoffMultiplier?: number; // default: 2
+  jitterPercent?: number; // 0-100, default: 10
+  onRetry?: (error: Error, attempt: number, delay: number) => void;
+}
+
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param ms - Milliseconds to sleep
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (0-based)
+ * @param options - Retry options
+ * @returns Delay in milliseconds
+ */
+export function calculateDelay(attempt: number, options: Required<RetryOptions>): number {
+  // Exponential backoff: initialDelay * (multiplier ^ attempt)
+  const exponentialDelay = options.initialDelay * Math.pow(options.backoffMultiplier, attempt);
+
+  // Cap at maxDelay
+  const cappedDelay = Math.min(exponentialDelay, options.maxDelay);
+
+  // Add jitter to prevent thundering herd
+  // Jitter is random value between [0, jitterPercent% of delay]
+  const jitterAmount = cappedDelay * (options.jitterPercent / 100);
+  const jitter = Math.random() * jitterAmount;
+
+  return Math.round(cappedDelay + jitter);
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ *
+ * @param operation - Async operation to retry
+ * @param options - Retry options
+ * @returns Result of the operation
+ * @throws Last error if all retries fail
+ */
+export async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const opts: Required<RetryOptions> = {
+    maxAttempts: options.maxAttempts ?? 3,
+    initialDelay: options.initialDelay ?? 1000,
+    maxDelay: options.maxDelay ?? 30000,
+    backoffMultiplier: options.backoffMultiplier ?? 2,
+    jitterPercent: options.jitterPercent ?? 10,
+    onRetry: options.onRetry ?? (() => {}),
+  };
+
+  let attempt = 0;
+  let lastError: Error | undefined;
+
+  while (attempt < opts.maxAttempts) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      const isLastAttempt = attempt === opts.maxAttempts - 1;
+
+      // Don't retry if it's the last attempt
+      if (isLastAttempt) {
+        throw lastError;
+      }
+
+      // Check if error is retryable
+      if (!isRetryableError(lastError)) {
+        throw lastError;
+      }
+
+      // For rate limit errors, use the retry-after value
+      let delay: number;
+      if (lastError instanceof AzureRateLimitError) {
+        // Use the retry-after value from the error (in seconds)
+        delay = lastError.retryAfter * 1000; // convert to ms
+      } else {
+        // Calculate delay with exponential backoff
+        delay = calculateDelay(attempt, opts);
+      }
+
+      // Call retry callback
+      opts.onRetry(lastError, attempt, delay);
+
+      // Wait before retrying
+      await sleep(delay);
+
+      attempt++;
+    }
+  }
+
+  // This should never happen, but TypeScript doesn't know that
+  throw lastError || new Error('Retry failed with unknown error');
+}
+
+/**
+ * Retry configuration for different scenarios
+ */
+export const AZURE_RETRY_CONFIGS = {
+  /**
+   * Default retry config for most operations
+   */
+  default: {
+    maxAttempts: 3,
+    initialDelay: 1000, // 1 second
+    maxDelay: 30000, // 30 seconds
+    backoffMultiplier: 2,
+    jitterPercent: 10,
+  },
+
+  /**
+   * Aggressive retry config for operations that are likely to succeed quickly
+   */
+  aggressive: {
+    maxAttempts: 5,
+    initialDelay: 500, // 0.5 seconds
+    maxDelay: 15000, // 15 seconds
+    backoffMultiplier: 1.5,
+    jitterPercent: 15,
+  },
+
+  /**
+   * Conservative retry config for expensive operations
+   */
+  conservative: {
+    maxAttempts: 2,
+    initialDelay: 2000, // 2 seconds
+    maxDelay: 60000, // 60 seconds
+    backoffMultiplier: 3,
+    jitterPercent: 5,
+  },
+
+  /**
+   * Rate limit retry config - respects rate limit headers
+   */
+  rateLimit: {
+    maxAttempts: 3,
+    initialDelay: 60000, // 60 seconds (default if no retry-after header)
+    maxDelay: 300000, // 5 minutes
+    backoffMultiplier: 1, // Don't use exponential backoff for rate limits
+    jitterPercent: 0, // No jitter for rate limits (use exact retry-after)
+  },
+} as const;