@claude-flow/security 3.0.0-alpha.9 → 3.0.1

package/src/credential-generator.ts

@@ -1,368 +0,0 @@
-/**
- * Credential Generator - CVE-3 Remediation
- *
- * Fixes hardcoded default credentials by providing secure random
- * credential generation for installation and runtime.
- *
- * Security Properties:
- * - Uses crypto.randomBytes for cryptographically secure randomness
- * - Configurable entropy levels
- * - No hardcoded defaults stored in code
- * - Secure credential storage recommendations
- *
- * @module v3/security/credential-generator
- */
-
-import { randomBytes, randomUUID } from 'crypto';
-
-export interface CredentialConfig {
-  /**
-   * Length of generated passwords.
-   * Default: 32 characters
-   */
-  passwordLength?: number;
-
-  /**
-   * Length of generated API keys.
-   * Default: 48 characters
-   */
-  apiKeyLength?: number;
-
-  /**
-   * Length of generated secrets (JWT, session, etc.).
-   * Default: 64 characters
-   */
-  secretLength?: number;
-
-  /**
-   * Character set for password generation.
-   * Default: alphanumeric + special
-   */
-  passwordCharset?: string;
-
-  /**
-   * Character set for API key generation.
-   * Default: alphanumeric only (URL-safe)
-   */
-  apiKeyCharset?: string;
-}
-
-export interface GeneratedCredentials {
-  adminPassword: string;
-  servicePassword: string;
-  jwtSecret: string;
-  sessionSecret: string;
-  encryptionKey: string;
-  generatedAt: Date;
-  expiresAt?: Date;
-}
-
-export interface ApiKeyCredential {
-  key: string;
-  prefix: string;
-  keyId: string;
-  createdAt: Date;
-}
-
-export class CredentialGeneratorError extends Error {
-  constructor(
-    message: string,
-    public readonly code: string,
-  ) {
-    super(message);
-    this.name = 'CredentialGeneratorError';
-  }
-}
-
-/**
- * Character sets for credential generation
- */
-const CHARSETS = {
-  UPPERCASE: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
-  LOWERCASE: 'abcdefghijklmnopqrstuvwxyz',
-  DIGITS: '0123456789',
-  SPECIAL: '!@#$%^&*()_+-=[]{}|;:,.<>?',
-  // URL-safe characters for API keys
-  URL_SAFE: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_',
-  // Hex characters for secrets
-  HEX: '0123456789abcdef',
-} as const;
-
-/**
- * Secure credential generator.
- *
- * This class provides cryptographically secure credential generation
- * to replace hardcoded default credentials.
- *
- * @example
- * ```typescript
- * const generator = new CredentialGenerator();
- * const credentials = generator.generateInstallationCredentials();
- * // Store credentials securely (environment variables, secrets manager)
- * ```
- */
-export class CredentialGenerator {
-  private readonly config: Required<CredentialConfig>;
-
-  constructor(config: CredentialConfig = {}) {
-    this.config = {
-      passwordLength: config.passwordLength ?? 32,
-      apiKeyLength: config.apiKeyLength ?? 48,
-      secretLength: config.secretLength ?? 64,
-      passwordCharset: config.passwordCharset ??
-        CHARSETS.UPPERCASE + CHARSETS.LOWERCASE + CHARSETS.DIGITS + CHARSETS.SPECIAL,
-      apiKeyCharset: config.apiKeyCharset ?? CHARSETS.URL_SAFE,
-    };
-
-    this.validateConfig();
-  }
-
-  /**
-   * Validates configuration parameters.
-   */
-  private validateConfig(): void {
-    if (this.config.passwordLength < 16) {
-      throw new CredentialGeneratorError(
-        'Password length must be at least 16 characters',
-        'INVALID_PASSWORD_LENGTH'
-      );
-    }
-
-    if (this.config.apiKeyLength < 32) {
-      throw new CredentialGeneratorError(
-        'API key length must be at least 32 characters',
-        'INVALID_API_KEY_LENGTH'
-      );
-    }
-
-    if (this.config.secretLength < 32) {
-      throw new CredentialGeneratorError(
-        'Secret length must be at least 32 characters',
-        'INVALID_SECRET_LENGTH'
-      );
-    }
-  }
-
-  /**
-   * Generates a cryptographically secure random string using rejection sampling
-   * to eliminate modulo bias.
-   *
-   * @param length - Length of the string to generate
-   * @param charset - Character set to use
-   * @returns Random string
-   */
-  private generateSecureString(length: number, charset: string): string {
-    const charsetLength = charset.length;
-    const result = new Array(length);
-
-    // Calculate rejection threshold to eliminate modulo bias
-    // For a byte (0-255), we reject values >= (256 - (256 % charsetLength))
-    // This ensures uniform distribution over charset indices
-    const maxValidValue = 256 - (256 % charsetLength);
-
-    let i = 0;
-    while (i < length) {
-      // Generate more random bytes than needed to reduce iterations
-      const randomBuffer = randomBytes(Math.max(length - i, 16));
-
-      for (let j = 0; j < randomBuffer.length && i < length; j++) {
-        const randomValue = randomBuffer[j];
-
-        // Rejection sampling: only accept values below threshold
-        if (randomValue < maxValidValue) {
-          result[i] = charset[randomValue % charsetLength];
-          i++;
-        }
-        // Values >= maxValidValue are rejected to avoid bias
-      }
-    }
-
-    return result.join('');
-  }
-
-  /**
-   * Generates a secure random password.
-   *
-   * @param length - Optional custom length (default from config)
-   * @returns Secure random password
-   */
-  generatePassword(length?: number): string {
-    const len = length ?? this.config.passwordLength;
-
-    // Ensure password contains at least one of each required character type
-    const password = this.generateSecureString(len, this.config.passwordCharset);
-
-    // Validate the generated password meets requirements
-    if (!this.hasRequiredCharacterTypes(password)) {
-      // Regenerate if requirements not met (rare case)
-      return this.generatePassword(length);
-    }
-
-    return password;
-  }
-
-  /**
-   * Checks if password has required character types.
-   */
-  private hasRequiredCharacterTypes(password: string): boolean {
-    const hasUppercase = /[A-Z]/.test(password);
-    const hasLowercase = /[a-z]/.test(password);
-    const hasDigit = /\d/.test(password);
-    const hasSpecial = /[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]/.test(password);
-
-    return hasUppercase && hasLowercase && hasDigit && hasSpecial;
-  }
-
-  /**
-   * Generates a secure API key.
-   *
-   * @param prefix - Optional prefix for the key (e.g., 'cf_')
-   * @returns API key credential with metadata
-   */
-  generateApiKey(prefix = 'cf_'): ApiKeyCredential {
-    const keyBody = this.generateSecureString(
-      this.config.apiKeyLength - prefix.length,
-      this.config.apiKeyCharset
-    );
-
-    const key = `${prefix}${keyBody}`;
-    const keyId = randomUUID();
-
-    return {
-      key,
-      prefix,
-      keyId,
-      createdAt: new Date(),
-    };
-  }
-
-  /**
-   * Generates a secure secret for JWT, sessions, etc.
-   *
-   * @param length - Optional custom length (default from config)
-   * @returns Hex-encoded secret
-   */
-  generateSecret(length?: number): string {
-    const len = length ?? this.config.secretLength;
-    // Generate raw bytes and encode as hex for consistent storage
-    return randomBytes(Math.ceil(len / 2)).toString('hex').slice(0, len);
-  }
-
-  /**
-   * Generates an encryption key suitable for AES-256.
-   *
-   * @returns 32-byte key encoded as hex (64 characters)
-   */
-  generateEncryptionKey(): string {
-    return randomBytes(32).toString('hex');
-  }
-
-  /**
-   * Generates a complete set of installation credentials.
-   *
-   * These should be stored securely (environment variables,
-   * secrets manager, etc.) and NEVER committed to version control.
-   *
-   * @param expirationDays - Optional expiration period in days
-   * @returns Complete credential set
-   */
-  generateInstallationCredentials(expirationDays?: number): GeneratedCredentials {
-    const now = new Date();
-    const expiresAt = expirationDays
-      ? new Date(now.getTime() + expirationDays * 24 * 60 * 60 * 1000)
-      : undefined;
-
-    return {
-      adminPassword: this.generatePassword(),
-      servicePassword: this.generatePassword(),
-      jwtSecret: this.generateSecret(64),
-      sessionSecret: this.generateSecret(64),
-      encryptionKey: this.generateEncryptionKey(),
-      generatedAt: now,
-      expiresAt,
-    };
-  }
-
-  /**
-   * Generates a secure session token.
-   *
-   * @returns URL-safe session token
-   */
-  generateSessionToken(): string {
-    return this.generateSecureString(64, CHARSETS.URL_SAFE);
-  }
-
-  /**
-   * Generates a secure CSRF token.
-   *
-   * @returns CSRF token
-   */
-  generateCsrfToken(): string {
-    return randomBytes(32).toString('base64url');
-  }
-
-  /**
-   * Generates a secure nonce for one-time use.
-   *
-   * @returns Unique nonce value
-   */
-  generateNonce(): string {
-    return randomBytes(16).toString('hex');
-  }
-
-  /**
-   * Creates a setup script output for secure credential deployment.
-   *
-   * @param credentials - Generated credentials
-   * @returns Environment variable export script
-   */
-  createEnvScript(credentials: GeneratedCredentials): string {
-    return `# Claude Flow V3 - Generated Credentials
-# Generated: ${credentials.generatedAt.toISOString()}
-# IMPORTANT: Store these securely and delete this file after use
-
-export CLAUDE_FLOW_ADMIN_PASSWORD="${credentials.adminPassword}"
-export CLAUDE_FLOW_SERVICE_PASSWORD="${credentials.servicePassword}"
-export CLAUDE_FLOW_JWT_SECRET="${credentials.jwtSecret}"
-export CLAUDE_FLOW_SESSION_SECRET="${credentials.sessionSecret}"
-export CLAUDE_FLOW_ENCRYPTION_KEY="${credentials.encryptionKey}"
-`;
-  }
-
-  /**
-   * Creates a JSON configuration output for secure credential deployment.
-   *
-   * @param credentials - Generated credentials
-   * @returns JSON configuration (for secrets manager import)
-   */
-  createJsonConfig(credentials: GeneratedCredentials): string {
-    return JSON.stringify({
-      'claude-flow/admin-password': credentials.adminPassword,
-      'claude-flow/service-password': credentials.servicePassword,
-      'claude-flow/jwt-secret': credentials.jwtSecret,
-      'claude-flow/session-secret': credentials.sessionSecret,
-      'claude-flow/encryption-key': credentials.encryptionKey,
-      'claude-flow/generated-at': credentials.generatedAt.toISOString(),
-      'claude-flow/expires-at': credentials.expiresAt?.toISOString() ?? null,
-    }, null, 2);
-  }
-}
-
-/**
- * Factory function to create a production credential generator.
- *
- * @returns Configured CredentialGenerator instance
- */
-export function createCredentialGenerator(): CredentialGenerator {
-  return new CredentialGenerator();
-}
-
-/**
- * Quick credential generation for CLI usage.
- *
- * @returns Generated installation credentials
- */
-export function generateCredentials(): GeneratedCredentials {
-  const generator = new CredentialGenerator();
-  return generator.generateInstallationCredentials();
-}

package/src/domain/entities/security-context.ts

@@ -1,173 +0,0 @@
-/**
- * Security Context Entity - Domain Layer
- *
- * Represents security context for operations with validation and policy enforcement.
- *
- * @module v3/security/domain/entities
- */
-
-import { randomUUID } from 'crypto';
-
-/**
- * Permission levels
- */
-export type PermissionLevel = 'read' | 'write' | 'execute' | 'admin';
-
-/**
- * Security context properties
- */
-export interface SecurityContextProps {
-  id?: string;
-  principalId: string;
-  principalType: 'agent' | 'user' | 'system';
-  permissions: PermissionLevel[];
-  allowedPaths?: string[];
-  blockedPaths?: string[];
-  allowedCommands?: string[];
-  blockedCommands?: string[];
-  metadata?: Record<string, unknown>;
-  expiresAt?: Date;
-  createdAt?: Date;
-}
-
-/**
- * Security Context - Entity
- */
-export class SecurityContext {
-  private _id: string;
-  private _principalId: string;
-  private _principalType: 'agent' | 'user' | 'system';
-  private _permissions: Set<PermissionLevel>;
-  private _allowedPaths: Set<string>;
-  private _blockedPaths: Set<string>;
-  private _allowedCommands: Set<string>;
-  private _blockedCommands: Set<string>;
-  private _metadata: Record<string, unknown>;
-  private _expiresAt?: Date;
-  private _createdAt: Date;
-
-  private constructor(props: SecurityContextProps) {
-    this._id = props.id ?? randomUUID();
-    this._principalId = props.principalId;
-    this._principalType = props.principalType;
-    this._permissions = new Set(props.permissions);
-    this._allowedPaths = new Set(props.allowedPaths ?? []);
-    this._blockedPaths = new Set(props.blockedPaths ?? []);
-    this._allowedCommands = new Set(props.allowedCommands ?? []);
-    this._blockedCommands = new Set(props.blockedCommands ?? []);
-    this._metadata = props.metadata ?? {};
-    this._expiresAt = props.expiresAt;
-    this._createdAt = props.createdAt ?? new Date();
-  }
-
-  static create(props: SecurityContextProps): SecurityContext {
-    return new SecurityContext(props);
-  }
-
-  static fromPersistence(props: SecurityContextProps): SecurityContext {
-    return new SecurityContext(props);
-  }
-
-  get id(): string { return this._id; }
-  get principalId(): string { return this._principalId; }
-  get principalType(): string { return this._principalType; }
-  get permissions(): PermissionLevel[] { return Array.from(this._permissions); }
-  get allowedPaths(): string[] { return Array.from(this._allowedPaths); }
-  get blockedPaths(): string[] { return Array.from(this._blockedPaths); }
-  get allowedCommands(): string[] { return Array.from(this._allowedCommands); }
-  get blockedCommands(): string[] { return Array.from(this._blockedCommands); }
-  get metadata(): Record<string, unknown> { return { ...this._metadata }; }
-  get expiresAt(): Date | undefined { return this._expiresAt; }
-  get createdAt(): Date { return new Date(this._createdAt); }
-
-  // Business Logic
-
-  hasPermission(level: PermissionLevel): boolean {
-    return this._permissions.has(level) || this._permissions.has('admin');
-  }
-
-  isExpired(): boolean {
-    if (!this._expiresAt) return false;
-    return Date.now() > this._expiresAt.getTime();
-  }
-
-  canAccessPath(path: string): boolean {
-    if (this.isExpired()) return false;
-
-    // Check blocked paths first
-    for (const blocked of this._blockedPaths) {
-      if (path.startsWith(blocked) || this.matchGlob(path, blocked)) {
-        return false;
-      }
-    }
-
-    // If no allowed paths specified, allow all non-blocked
-    if (this._allowedPaths.size === 0) return true;
-
-    // Check allowed paths
-    for (const allowed of this._allowedPaths) {
-      if (path.startsWith(allowed) || this.matchGlob(path, allowed)) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  canExecuteCommand(command: string): boolean {
-    if (this.isExpired()) return false;
-
-    const cmdBase = command.split(' ')[0];
-
-    // Check blocked commands first
-    if (this._blockedCommands.has(cmdBase) || this._blockedCommands.has(command)) {
-      return false;
-    }
-
-    // If no allowed commands specified, allow all non-blocked
-    if (this._allowedCommands.size === 0) return true;
-
-    // Check allowed commands
-    return this._allowedCommands.has(cmdBase) || this._allowedCommands.has(command);
-  }
-
-  private matchGlob(path: string, pattern: string): boolean {
-    const regex = pattern
-      .replace(/\*\*/g, '.*')
-      .replace(/\*/g, '[^/]*')
-      .replace(/\?/g, '.');
-    return new RegExp(`^${regex}$`).test(path);
-  }
-
-  grantPermission(level: PermissionLevel): void {
-    this._permissions.add(level);
-  }
-
-  revokePermission(level: PermissionLevel): void {
-    this._permissions.delete(level);
-  }
-
-  addAllowedPath(path: string): void {
-    this._allowedPaths.add(path);
-  }
-
-  addBlockedPath(path: string): void {
-    this._blockedPaths.add(path);
-  }
-
-  toPersistence(): Record<string, unknown> {
-    return {
-      id: this._id,
-      principalId: this._principalId,
-      principalType: this._principalType,
-      permissions: Array.from(this._permissions),
-      allowedPaths: Array.from(this._allowedPaths),
-      blockedPaths: Array.from(this._blockedPaths),
-      allowedCommands: Array.from(this._allowedCommands),
-      blockedCommands: Array.from(this._blockedCommands),
-      metadata: this._metadata,
-      expiresAt: this._expiresAt?.toISOString(),
-      createdAt: this._createdAt.toISOString(),
-    };
-  }
-}

package/src/domain/index.ts

@@ -1,17 +0,0 @@
-/**
- * Security Domain Layer - Public Exports
- *
- * @module v3/security/domain
- */
-
-export {
-  SecurityContext,
-  type PermissionLevel,
-  type SecurityContextProps,
-} from './entities/security-context.js';
-
-export {
-  SecurityDomainService,
-  type ValidationResult,
-  type ThreatDetectionResult,
-} from './services/security-domain-service.js';