@claude-flow/security 3.0.0-alpha.1 → 3.0.0-alpha.11

package/README.md

@@ -1,234 +1,292 @@
-# @claude-flow/security
-
-[![npm version](https://img.shields.io/npm/v/@claude-flow/security.svg)](https://www.npmjs.com/package/@claude-flow/security)
-[![npm downloads](https://img.shields.io/npm/dm/@claude-flow/security.svg)](https://www.npmjs.com/package/@claude-flow/security)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Security Audit](https://img.shields.io/badge/Security-Audited-green.svg)](https://github.com/ruvnet/claude-flow)
-
-> Comprehensive security module for Claude Flow V3 - CVE fixes, input validation, path security, and secure credential management.
-
-## Features
-
-- **CVE Remediation** - Fixes for CVE-2 (Weak Password Hashing), CVE-3 (Hardcoded Credentials), HIGH-1 (Command Injection), HIGH-2 (Path Traversal)
-- **Password Hashing** - Secure bcrypt-based password hashing with configurable rounds (12+ recommended)
-- **Credential Generation** - Cryptographically secure credential and API key generation
-- **Safe Command Execution** - Allowlist-based command execution preventing injection attacks
-- **Path Validation** - Protection against path traversal and symlink attacks
-- **Input Validation** - Zod-based schema validation for all input types
-- **Token Generation** - Secure token creation with HMAC signing
-
-## Installation
-
-```bash
-npm install @claude-flow/security
-```
-
-## Quick Start
-
-```typescript
-import { createSecurityModule } from '@claude-flow/security';
-
-// Create a complete security module
-const security = createSecurityModule({
-  projectRoot: '/workspaces/project',
-  hmacSecret: process.env.HMAC_SECRET!,
-  bcryptRounds: 12,
-  allowedCommands: ['git', 'npm', 'npx', 'node']
-});
-
-// Hash a password
-const hash = await security.passwordHasher.hash('userPassword123');
-
-// Validate a path
-const pathResult = await security.pathValidator.validate('/workspaces/project/src/file.ts');
-
-// Execute command safely
-const output = await security.safeExecutor.execute('git', ['status']);
-
-// Generate secure credentials
-const creds = await security.credentialGenerator.generate();
-```
-
-## API Reference
-
-### Password Hashing (CVE-2 Fix)
-
-```typescript
-import { PasswordHasher, createPasswordHasher } from '@claude-flow/security';
-
-const hasher = createPasswordHasher({ rounds: 12 });
-
-// Hash password
-const hash = await hasher.hash('password');
-
-// Verify password
-const isValid = await hasher.verify('password', hash);
-
-// Check if hash needs rehashing
-const needsRehash = hasher.needsRehash(hash);
-```
-
-### Credential Generation (CVE-3 Fix)
-
-```typescript
-import { CredentialGenerator, generateCredentials } from '@claude-flow/security';
-
-const generator = new CredentialGenerator();
-
-// Generate API key
-const apiKey = await generator.generateApiKey({
-  prefix: 'cf',
-  length: 32
-});
-
-// Generate complete credentials
-const creds = generateCredentials({
-  includeApiKey: true,
-  includeSecret: true
-});
-```
-
-### Safe Command Execution (HIGH-1 Fix)
-
-```typescript
-import { SafeExecutor, createDevelopmentExecutor } from '@claude-flow/security';
-
-const executor = createDevelopmentExecutor();
-
-// Execute allowed command
-const result = await executor.execute('git', ['status']);
-
-// With timeout
-const result2 = await executor.execute('npm', ['install'], {
-  timeout: 60000,
-  cwd: '/workspaces/project'
-});
-```
-
-### Path Validation (HIGH-2 Fix)
-
-```typescript
-import { PathValidator, createProjectPathValidator } from '@claude-flow/security';
-
-const validator = createProjectPathValidator('/workspaces/project');
-
-// Validate path
-const result = await validator.validate('../../../etc/passwd');
-// { valid: false, reason: 'Path traversal detected' }
-
-// Safe path
-const result2 = await validator.validate('/workspaces/project/src/index.ts');
-// { valid: true, normalized: '/workspaces/project/src/index.ts' }
-```
-
-### Input Validation
-
-```typescript
-import {
-  InputValidator,
-  SafeStringSchema,
-  EmailSchema,
-  PasswordSchema,
-  SpawnAgentSchema
-} from '@claude-flow/security';
-
-// Validate email
-const email = EmailSchema.parse('user@example.com');
-
-// Validate password
-const password = PasswordSchema.parse('SecurePass123!');
-
-// Validate agent spawn request
-const agentRequest = SpawnAgentSchema.parse({
-  type: 'coder',
-  name: 'code-agent-1'
-});
-
-// Sanitize HTML
-import { sanitizeHtml } from '@claude-flow/security';
-const safe = sanitizeHtml('<script>alert("xss")</script>Hello');
-// 'Hello'
-```
-
-### Token Generation
-
-```typescript
-import { TokenGenerator, quickGenerate } from '@claude-flow/security';
-
-const generator = new TokenGenerator({
-  hmacSecret: process.env.HMAC_SECRET!
-});
-
-// Generate signed token
-const token = await generator.generate({
-  type: 'session',
-  expiresIn: 3600
-});
-
-// Verify token
-const verified = await generator.verify(token);
-
-// Quick generation
-const sessionToken = quickGenerate.sessionToken();
-const verificationCode = quickGenerate.verificationCode();
-```
-
-## Security Constants
-
-```typescript
-import {
-  MIN_BCRYPT_ROUNDS,      // 12
-  MAX_BCRYPT_ROUNDS,      // 14
-  MIN_PASSWORD_LENGTH,    // 8
-  MAX_PASSWORD_LENGTH,    // 72 (bcrypt limit)
-  DEFAULT_TOKEN_EXPIRATION,   // 3600 (1 hour)
-  DEFAULT_SESSION_EXPIRATION  // 86400 (24 hours)
-} from '@claude-flow/security';
-```
-
-## Security Audit
-
-```typescript
-import { auditSecurityConfig } from '@claude-flow/security';
-
-const warnings = auditSecurityConfig({
-  bcryptRounds: 10,
-  hmacSecret: 'short'
-});
-
-// ['bcryptRounds (10) below recommended minimum (12)',
-//  'hmacSecret should be at least 32 characters']
-```
-
-## Validation Schemas
-
-| Schema | Description |
-|--------|-------------|
-| `SafeStringSchema` | Basic safe string with length limits |
-| `IdentifierSchema` | Alphanumeric identifiers |
-| `FilenameSchema` | Safe filenames |
-| `EmailSchema` | Email addresses |
-| `PasswordSchema` | Secure passwords |
-| `UUIDSchema` | UUID v4 format |
-| `HttpsUrlSchema` | HTTPS URLs only |
-| `SemverSchema` | Semantic versions |
-| `PortSchema` | Valid port numbers |
-| `IPv4Schema` | IPv4 addresses |
-| `SpawnAgentSchema` | Agent spawn requests |
-| `TaskInputSchema` | Task definitions |
-| `SecurityConfigSchema` | Security configuration |
-
-## Dependencies
-
-- `bcrypt` - Password hashing
-- `zod` - Schema validation
-
-## Related Packages
-
-- [@claude-flow/shared](../shared) - Shared types and utilities
-- [@claude-flow/swarm](../swarm) - Swarm coordination (secure agent spawning)
-
-## License
-
-MIT
+# @claude-flow/security
+
+[![npm version](https://img.shields.io/npm/v/@claude-flow/security.svg)](https://www.npmjs.com/package/@claude-flow/security)
+[![npm downloads](https://img.shields.io/npm/dm/@claude-flow/security.svg)](https://www.npmjs.com/package/@claude-flow/security)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Security Audit](https://img.shields.io/badge/Security-Audited-green.svg)](https://github.com/ruvnet/claude-flow)
+
+> Comprehensive security module for Claude Flow V3 - CVE fixes, input validation, path security, and secure credential management.
+
+## Features
+
+- **CVE Remediation** - Fixes for CVE-2 (Weak Password Hashing), CVE-3 (Hardcoded Credentials), HIGH-1 (Command Injection), HIGH-2 (Path Traversal)
+- **Password Hashing** - Secure bcrypt-based password hashing with configurable rounds (12+ recommended)
+- **Credential Generation** - Cryptographically secure credential and API key generation
+- **Safe Command Execution** - Allowlist-based command execution preventing injection attacks
+- **Path Validation** - Protection against path traversal and symlink attacks
+- **Input Validation** - Zod-based schema validation for all input types
+- **Token Generation** - Secure token creation with HMAC signing
+
+## Installation
+
+```bash
+npm install @claude-flow/security
+```
+
+## Standalone use (without the Ruflo CLI)
+
+This is a plain library — every primitive (`PasswordHasher`,
+`PathValidator`, `SafeExecutor`, `InputValidator`, `CredentialGenerator`)
+is independently importable. No CLI, no MCP server, no daemon. The
+primitives close CVE-2 (weak hashing), CVE-3 (default credentials),
+HIGH-1 (command injection), and HIGH-2 (path traversal) — drop them
+into any Node app that needs to validate at a system boundary.
+
+### Recipe — Validate input, hash a password, generate an API key
+
+```typescript
+// recipe.mjs
+import {
+  InputValidator,
+  EmailSchema,
+  PasswordHasher,
+  createCredentialGenerator,
+} from '@claude-flow/security';
+
+// 1. Validate user input at the boundary (Zod schemas, no surprises)
+const email = InputValidator.validate(EmailSchema, 'user@example.com');
+//             ↳ throws if invalid; returns the typed value otherwise
+
+// 2. Hash a password with bcrypt at the recommended cost (CVE-2)
+//    Default policy: ≥8 chars, ≥1 upper, ≥1 lower, ≥1 digit.
+//    Tune with new PasswordHasher({ rounds, requireUppercase, ... }).
+const hasher = new PasswordHasher({ rounds: 12 });
+const hash   = await hasher.hash('CorrectHorseBatteryStaple9');
+const ok     = await hasher.verify('CorrectHorseBatteryStaple9', hash); // true
+
+// 3. Generate a high-entropy API key (CVE-3) — uses crypto.randomBytes
+//    under the hood and refuses to emit keys below 32 bytes of entropy.
+const creds = createCredentialGenerator();
+const apiKey = creds.generateApiKey('ck_live_');
+console.log(apiKey.keyId, apiKey.key.slice(0, 16) + '…');
+// → 7e2b1a9c-…  ck_live_xX9aQ…
+```
+
+### Recipe — Refuse command injection + path traversal
+
+```typescript
+import {
+  createDevelopmentExecutor,
+  createProjectPathValidator,
+} from '@claude-flow/security';
+
+// SafeExecutor — only the allow-listed commands ever run (HIGH-1)
+const exec = createDevelopmentExecutor({ projectRoot: process.cwd() });
+const { stdout } = await exec.execute('git', ['status', '--porcelain']);
+
+// PathValidator — refuses traversal and symlinks out of the project (HIGH-2)
+const paths = createProjectPathValidator(process.cwd());
+const result = await paths.validate('../../etc/passwd');
+if (!result.isValid) console.log('blocked:', result.errors.join('; '));
+// → blocked: Path traversal pattern detected
+```
+
+## Quick Start
+
+```typescript
+import { createSecurityModule } from '@claude-flow/security';
+
+// Create a complete security module
+const security = createSecurityModule({
+  projectRoot: '/workspaces/project',
+  hmacSecret: process.env.HMAC_SECRET!,
+  bcryptRounds: 12,
+  allowedCommands: ['git', 'npm', 'node']
+});
+
+// Hash a password
+const hash = await security.passwordHasher.hash('userPassword123');
+
+// Validate a path
+const pathResult = await security.pathValidator.validate('/workspaces/project/src/file.ts');
+
+// Execute command safely
+const output = await security.safeExecutor.execute('git', ['status']);
+
+// Generate secure credentials
+const creds = await security.credentialGenerator.generate();
+```
+
+## API Reference
+
+### Password Hashing (CVE-2 Fix)
+
+```typescript
+import { PasswordHasher, createPasswordHasher } from '@claude-flow/security';
+
+const hasher = createPasswordHasher({ rounds: 12 });
+
+// Hash password
+const hash = await hasher.hash('password');
+
+// Verify password
+const isValid = await hasher.verify('password', hash);
+
+// Check if hash needs rehashing
+const needsRehash = hasher.needsRehash(hash);
+```
+
+### Credential Generation (CVE-3 Fix)
+
+```typescript
+import { CredentialGenerator, generateCredentials } from '@claude-flow/security';
+
+const generator = new CredentialGenerator();
+
+// Generate API key
+const apiKey = await generator.generateApiKey({
+  prefix: 'cf',
+  length: 32
+});
+
+// Generate complete credentials
+const creds = generateCredentials({
+  includeApiKey: true,
+  includeSecret: true
+});
+```
+
+### Safe Command Execution (HIGH-1 Fix)
+
+```typescript
+import { SafeExecutor, createDevelopmentExecutor } from '@claude-flow/security';
+
+const executor = createDevelopmentExecutor();
+
+// Execute allowed command
+const result = await executor.execute('git', ['status']);
+
+// With timeout
+const result2 = await executor.execute('npm', ['install'], {
+  timeout: 60000,
+  cwd: '/workspaces/project'
+});
+```
+
+### Path Validation (HIGH-2 Fix)
+
+```typescript
+import { PathValidator, createProjectPathValidator } from '@claude-flow/security';
+
+const validator = createProjectPathValidator('/workspaces/project');
+
+// Validate path
+const result = await validator.validate('../../../etc/passwd');
+// { valid: false, reason: 'Path traversal detected' }
+
+// Safe path
+const result2 = await validator.validate('/workspaces/project/src/index.ts');
+// { valid: true, normalized: '/workspaces/project/src/index.ts' }
+```
+
+### Input Validation
+
+```typescript
+import {
+  InputValidator,
+  SafeStringSchema,
+  EmailSchema,
+  PasswordSchema,
+  SpawnAgentSchema
+} from '@claude-flow/security';
+
+// Validate email
+const email = EmailSchema.parse('user@example.com');
+
+// Validate password
+const password = PasswordSchema.parse('SecurePass123!');
+
+// Validate agent spawn request
+const agentRequest = SpawnAgentSchema.parse({
+  type: 'coder',
+  name: 'code-agent-1'
+});
+
+// Sanitize HTML
+import { sanitizeHtml } from '@claude-flow/security';
+const safe = sanitizeHtml('<script>alert("xss")</script>Hello');
+// 'Hello'
+```
+
+### Token Generation
+
+```typescript
+import { TokenGenerator, quickGenerate } from '@claude-flow/security';
+
+const generator = new TokenGenerator({
+  hmacSecret: process.env.HMAC_SECRET!
+});
+
+// Generate signed token
+const token = await generator.generate({
+  type: 'session',
+  expiresIn: 3600
+});
+
+// Verify token
+const verified = await generator.verify(token);
+
+// Quick generation
+const sessionToken = quickGenerate.sessionToken();
+const verificationCode = quickGenerate.verificationCode();
+```
+
+## Security Constants
+
+```typescript
+import {
+  MIN_BCRYPT_ROUNDS,      // 12
+  MAX_BCRYPT_ROUNDS,      // 14
+  MIN_PASSWORD_LENGTH,    // 8
+  MAX_PASSWORD_LENGTH,    // 72 (bcrypt limit)
+  DEFAULT_TOKEN_EXPIRATION,   // 3600 (1 hour)
+  DEFAULT_SESSION_EXPIRATION  // 86400 (24 hours)
+} from '@claude-flow/security';
+```
+
+## Security Audit
+
+```typescript
+import { auditSecurityConfig } from '@claude-flow/security';
+
+const warnings = auditSecurityConfig({
+  bcryptRounds: 10,
+  hmacSecret: 'short'
+});
+
+// ['bcryptRounds (10) below recommended minimum (12)',
+//  'hmacSecret should be at least 32 characters']
+```
+
+## Validation Schemas
+
+| Schema | Description |
+|--------|-------------|
+| `SafeStringSchema` | Basic safe string with length limits |
+| `IdentifierSchema` | Alphanumeric identifiers |
+| `FilenameSchema` | Safe filenames |
+| `EmailSchema` | Email addresses |
+| `PasswordSchema` | Secure passwords |
+| `UUIDSchema` | UUID v4 format |
+| `HttpsUrlSchema` | HTTPS URLs only |
+| `SemverSchema` | Semantic versions |
+| `PortSchema` | Valid port numbers |
+| `IPv4Schema` | IPv4 addresses |
+| `SpawnAgentSchema` | Agent spawn requests |
+| `TaskInputSchema` | Task definitions |
+| `SecurityConfigSchema` | Security configuration |
+
+## Dependencies
+
+- `bcrypt` - Password hashing
+- `zod` - Schema validation
+
+## Related Packages
+
+- [@claude-flow/shared](../shared) - Shared types and utilities
+- [@claude-flow/swarm](../swarm) - Swarm coordination (secure agent spawning)
+
+## License
+
+MIT