ruvnet--ruflo/v3/@claude-flow/security/README.md

# @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