fortify2-js/README.md

MOST POWERFUL JavaScript Security Library! Military-grade cryptography + 19 enhanced object methods + quantum-resistant algorithms + perfect TypeScript support. More powerful than Lodash with built-in security.

# Nehonix FortifyJS - Advanced JavaScript Security Library

FortifyJS is a robust JavaScript security library designed to enhance data structures with advanced cryptographic features, real-time security, and type safety. It provides a comprehensive set of tools for secure data handling, featuring the world's most advanced SecureArray implementation with military-grade encryption and real-time monitoring.

## Why Choose FortifyJS?

FortifyJS empowers developers to create secure, type-safe, and chainable JavaScript objects with advanced cryptographic capabilities. Key advantages include:

-   **Enhanced Object Methods**: 19 powerful methods for data manipulation, surpassing standard JavaScript objects.
-   **Advanced Security**: Implements military-grade cryptography with quantum-resistant algorithms.
-   **Type Safety**: Full TypeScript support for robust, error-free development.

### Comparison with Standard Objects

| Feature       | Standard Object | FortifyJS SecureObject  |
| ------------- | --------------- | ----------------------- |
| Methods       | None            | 19 Enhanced Methods     |
| Type Safety   | Basic           | Full TypeScript Support |
| Security      | None            | Advanced Cryptography   |
| Chaining      | Not Supported   | Fully Chainable API     |
| Events        | Not Supported   | Event-Driven Operations |
| Memory Safety | Manual          | Automatic Cleanup       |

### Comparison with Lodash

| Feature           | Lodash        | FortifyJS                |
| ----------------- | ------------- | ------------------------ |
| Security          | None          | Built-In Cryptography    |
| Type Safety       | Partial       | Full TypeScript Support  |
| Memory Management | Manual        | Automatic                |
| Sensitive Data    | Not Supported | Security-Aware Filtering |
| Events            | Not Supported | Operation Tracking       |

### Testing and Validation

-   100% integration test coverage (14/14 tests passed)
-   Validated security features
-   Verified performance benchmarks
-   Optimized memory usage

## Key Features

### ⚡ FortifiedFunction - Ultra-Fast Secure Function Wrapper

A high-performance, security-enhanced function wrapper that provides intelligent caching, comprehensive monitoring, and configurable security features with ultra-fast execution modes.

**Performance Breakthrough**: Optimized from 109+ seconds to 1-4ms execution time - a **27,000x performance improvement**.

#### Performance Modes

| Mode           | Execution Time | Performance Gain | Use Case              |
| -------------- | -------------- | ---------------- | --------------------- |
| **Ultra-Fast** | 1-4ms          | 27,000x faster   | Hot paths, API routes |
| **Standard**   | 20-50ms        | 2,000x faster    | Business logic        |
| **Secure**     | 100-200ms      | 500x faster      | Sensitive operations  |

#### Quick Start

```typescript
import { func } from "fortify2-js";

// Ultra-fast mode for performance-critical paths
const ultraFastFunction = func(
    async (data) => {
        return processData(data);
    },
    { ultraFast: "minimal" }
);

// Standard balanced mode (default)
const standardFunction = func(async (data) => {
    return processData(data);
});

// Secure mode for sensitive operations
const secureFunction = func(
    async (data) => {
        return processData(data);
    },
    {
        autoEncrypt: true,
        auditLog: true,
        detailedMetrics: true,
    }
);
```

### 🔒 SecureArray - World's Most Advanced Secure Data Structure

-   **Military-Grade Encryption**: Real AES-256-CTR-HMAC with 77.98 bits entropy
-   **Real-Time Monitoring**: Live memory usage, access tracking, and performance metrics
-   **Snapshot Management**: Version control with create, restore, and rollback capabilities
-   **Event System**: Comprehensive event handling for all array operations
-   **Advanced Operations**: unique(), shuffle(), min(), max(), compact() with security
-   **Multiple Export Formats**: JSON, CSV, XML, YAML with integrity verification
-   **Memory Management**: Automatic cleanup, leak detection, and secure wiping
-   **100+ Methods**: Full JavaScript Array API compatibility plus security features

### SecureRandom with Encoding Support

-   Supports multiple encodings: hex, base64, base64url, base58, binary, utf8
-   Utilizes cryptographically secure pseudorandom number generators (CSPRNG)
-   Cross-platform compatibility for Node.js and browsers
-   Quantum-safe random generation options
-   Built-in entropy quality assessment

### RSA Key Calculator & Generator

-   Calculates optimal RSA key sizes based on data requirements
-   Provides comprehensive security assessments
-   Supports multiple hash algorithms (SHA-256, SHA-384, SHA-512)
-   Offers hybrid encryption recommendations
-   Includes performance benchmarking

### Password Management System

-   Implements Argon2ID, Argon2I, and Argon2D algorithms
-   Provides military-grade hashing with timing-safe verification
-   Supports seamless migration from bcrypt
-   Includes password strength analysis with entropy calculation
-   Achieves hash/verify times of 674-995ms for optimal security

### Advanced Security Features

-   Secure memory management with buffer protection
-   Resistance to side-channel attacks
-   Quantum-resistant cryptographic algorithms
-   Support for hardware security modules (HSMs)
-   Real-time security monitoring

## Installation

Install FortifyJS via npm:

```bash
npm install fortify2-js
```

### Optional Security Packages

For enhanced cryptographic functionality, install:

```bash
npm install @noble/hashes @noble/ciphers libsodium-wrappers argon2 bcryptjs
```

## Quick Start

### SecureArray - Military-Grade Secure Data Structure

```typescript
import { fArray } "fortify2-js"

// Create a secure array with AES-256-CTR-HMAC encryption
const secureData = fArray(["sensitive-data", "api-keys", "user-info"]);

// Set encryption key
secureData.setEncryptionKey("your-super-secret-key-2025");

// Encrypt all data with military-grade security
secureData.encryptAll();

// Use like a regular array - data is automatically encrypted/decrypted
secureData.push("new-secret");
const firstItem = secureData.get(0); // Automatically decrypted
const filtered = secureData.filter((item) => item.includes("api"));

// Advanced features
const snapshot = secureData.createSnapshot(); // Version control
const stats = secureData.getStats(); // Real-time monitoring
const exported = secureData.exportData("csv"); // Multiple export formats

// Event system
secureData.on("push", (data) => console.log("New item added securely"));

// Comprehensive security status
const status = secureData.getEncryptionStatus();
console.log(status.algorithm); // "AES-256-CTR-HMAC"
```

### Password Management

```typescript
import { PasswordManager } from "fortify2-js";

// or import pm directly
// import { pm } from "fortify2-js"; //NOTE: pm uses default configuration, for custom config, use PasswordManager.create() or PasswordManager.getInstance()

const pm = PasswordManager.getInstance();

// Generate a secure password
const password = pm.generateSecurePassword(16, {
    includeUppercase: true,
    includeLowercase: true,
    includeNumbers: true,
    includeSymbols: true,
});
console.log("Generated password:", password);

// Analyze password strength
const analysis = pm.analyzeStrength("MyPassword123!");
console.log("Strength score:", analysis.score);
console.log("Entropy:", analysis.entropy);

// Hash password with Argon2ID
const hash = await pm.hash("MyPassword123!", {
    algorithm: "argon2id",
    securityLevel: "high",
});
console.log("Secure hash:", hash);

// Verify password
const verification = await pm.verify("MyPassword123!", hash);
console.log("Valid password:", verification.isValid);
console.log("Security level:", verification.securityLevel);
```

### SecureRandom with Encoding

```typescript
import { SecureRandom } from "fortify2-js";
// or use: import { Random } from "fortify2-js";

const randomBytes = SecureRandom.getRandomBytes(32);

// Multiple encoding options
console.log("Hex:", randomBytes.toString("hex"));
console.log("Base64:", randomBytes.toString("base64"));
console.log("Base64URL:", randomBytes.toString("base64url"));
console.log("Base58:", randomBytes.toString("base58"));

// Entropy information
console.log("Entropy Info:", randomBytes.getEntropyInfo());
```

### RSA Key Calculator & Generator

```typescript
import {
    calculateRSAKeySize,
    generateRSAKeyPairForData,
    validateDataSizeForRSAKey,
    getRSARecommendations,
    assessRSASecurity,
} from "fortify2-js";

const dataSize = 190; // bytes
const keySize = calculateRSAKeySize(dataSize, "sha256");
console.log(`Recommended key size: ${keySize} bits`);

const keyPair = generateRSAKeyPairForData(dataSize, "sha256");
console.log("Public Key:", keyPair.publicKey);
console.log("Max Data Size:", keyPair.maxDataSize);

const validation = validateDataSizeForRSAKey(dataSize, 2048, "sha256");
console.log("Valid:", validation.valid);
console.log("Recommendation:", validation.recommendation);

const recommendations = getRSARecommendations(dataSize);
recommendations.forEach((rec) => {
    console.log(`${rec.keySize}-bit: ${rec.recommendation}`);
});

const security = assessRSASecurity(2048, "sha256", dataSize);
console.log("Security Level:", security.level);
console.log("Security Score:", security.score);
console.log("NIST Compliant:", security.compliance.nist);
```

## FortifiedFunction - Comprehensive Guide

### Overview

FortifiedFunction transforms ordinary functions into secure, monitored, and optimized execution units. It provides multiple performance modes ranging from ultra-fast execution (1-4ms) to comprehensive security monitoring, making it suitable for both performance-critical applications and security-sensitive environments.

### Configuration Options

#### Performance Options

```typescript
interface PerformanceOptions {
    ultraFast?: "minimal" | "standard" | "maximum" | boolean;
    memoize?: boolean; // Enable result caching
    timeout?: number; // Execution timeout (ms)
    retries?: number; // Retry attempts
    maxRetryDelay?: number; // Maximum retry delay (ms)
    smartCaching?: boolean; // Intelligent cache management
    cacheStrategy?: "adaptive" | "lru" | "fifo";
    cacheTTL?: number; // Cache time-to-live (ms)
    maxCacheSize?: number; // Maximum cache entries
    optimizeExecution?: boolean; // Enable execution optimizations
}
```

#### Security Options

```typescript
interface SecurityOptions {
    autoEncrypt?: boolean; // Automatic parameter encryption
    secureParameters?: (string | number)[]; // Parameters to encrypt
    memoryWipeDelay?: number; // Memory cleanup delay (ms)
    stackTraceProtection?: boolean; // Sanitize stack traces
    smartSecurity?: boolean; // Advanced security features
    threatDetection?: boolean; // Real-time threat detection
}
```

#### Monitoring Options

```typescript
interface MonitoringOptions {
    auditLog?: boolean; // Enable audit logging
    performanceTracking?: boolean; // Track performance metrics
    debugMode?: boolean; // Enable debug output
    detailedMetrics?: boolean; // Comprehensive metrics
    anomalyDetection?: boolean; // Detect unusual patterns
    performanceRegression?: boolean; // Monitor performance degradation
}
```

### Performance Mode Details

#### Ultra-Fast Mode (`ultraFast: 'minimal'`)

Optimized for maximum performance with minimal overhead:

-   **Target**: <10ms execution time
-   **Achieved**: 1-4ms actual performance
-   **Features**: Direct execution bypass, object pooling, fast cache keys
-   **Security**: Minimal (stack trace protection only)
-   **Monitoring**: Disabled for maximum speed

```typescript
const hotPath = func(criticalFunction, {
    ultraFast: "minimal",
    memoize: true,
    cacheTTL: 300000,
});
```

#### Standard Mode (Default)

Balanced performance and functionality for typical production use:

-   **Target**: <50ms execution time
-   **Features**: Smart caching, performance tracking, audit logging
-   **Security**: Stack trace protection, basic monitoring
-   **Monitoring**: Essential metrics enabled

```typescript
const businessLogic = func(regularFunction, {
    // Uses optimized defaults
    memoize: true,
    smartCaching: true,
    auditLog: true,
});
```

#### Secure Mode

Maximum security and comprehensive monitoring:

-   **Target**: <200ms execution time
-   **Features**: Full encryption, detailed metrics, threat detection
-   **Security**: Complete security suite enabled
-   **Monitoring**: Comprehensive tracking and analytics

```typescript
const sensitiveOperation = func(secureFunction, {
    autoEncrypt: true,
    stackTraceProtection: true,
    detailedMetrics: true,
    threatDetection: true,
    anomalyDetection: true,
});
```

### API Reference

#### Core Methods

##### `execute(...args): Promise<R>`

Executes the wrapped function with all configured security and monitoring features.

##### `getStats(): FunctionStats`

Returns comprehensive execution statistics including performance metrics and cache statistics.

##### `getCacheStats(): CacheStats`

Returns detailed cache performance information including hit rates and memory usage.

##### `clearCache(): void`

Clears all cached results and resets cache statistics.

##### `destroy(): void`

Properly cleans up all resources, active executions, and event listeners.

#### Advanced Methods

##### `getOptimizationSuggestions(): OptimizationSuggestion[]`

Returns AI-generated suggestions for improving function performance based on execution patterns.

##### `getPerformanceTrends(): PerformanceTrend[]`

Returns historical performance data for trend analysis and capacity planning.

##### `warmCache(): void`

Pre-populates cache with frequently accessed data for improved response times.

### Best Practices

#### Choosing Performance Modes

**Use Ultra-Fast Mode When:**

-   Function is called frequently (>1000 times/minute)
-   Response time is critical (<10ms requirement)
-   Security requirements are minimal
-   Function handles non-sensitive data

**Use Standard Mode When:**

-   Balanced performance and security needed
-   Function handles business logic
-   Debugging capabilities required
-   Moderate call frequency (<100 times/minute)

**Use Secure Mode When:**

-   Function processes sensitive data
-   Compliance requirements exist
-   Comprehensive audit trails needed
-   Security is prioritized over performance

#### Performance Optimization Guidelines

1. **Enable Caching**: Always enable `memoize` for functions with deterministic outputs
2. **Tune Cache TTL**: Set appropriate `cacheTTL` based on data freshness requirements
3. **Monitor Metrics**: Use `performanceTracking` to identify bottlenecks
4. **Optimize Hot Paths**: Apply `ultraFast: 'minimal'` to frequently called functions
5. **Memory Management**: Configure `maxMemoryUsage` based on available system resources

#### Security Considerations

1. **Encryption**: Enable `autoEncrypt` for functions handling PII or sensitive data
2. **Audit Logging**: Always enable `auditLog` in production environments
3. **Stack Protection**: Keep `stackTraceProtection` enabled to prevent information leakage
4. **Threat Detection**: Enable in high-security environments with `threatDetection`

### Migration Guide

#### From Version 1.x

```typescript
// Old approach
const wrappedFunction = fortify(myFunction, {
    cache: true,
    security: "high",
});

// New approach
const wrappedFunction = func(myFunction, {
    memoize: true,
    autoEncrypt: true,
    auditLog: true,
});
```

#### Performance Migration

For existing high-performance requirements:

```typescript
// Replace performance-critical functions
const optimizedFunction = func(existingFunction, {
    ultraFast: "minimal", // New ultra-fast mode
    memoize: true,
    cacheTTL: 300000,
});
```

### Advanced Usage

#### Custom Cache Strategies

```typescript
const customCachedFunction = func(expensiveOperation, {
    smartCaching: true,
    cacheStrategy: "adaptive",
    maxCacheSize: 5000,
    cacheTTL: 600000, // 10 minutes
});
```

#### Comprehensive Monitoring

```typescript
const monitoredFunction = func(businessCriticalFunction, {
    auditLog: true,
    performanceTracking: true,
    detailedMetrics: true,
    anomalyDetection: true,
});

// Access monitoring data
const stats = monitoredFunction.getStats();
const trends = monitoredFunction.getPerformanceTrends();
const suggestions = monitoredFunction.getOptimizationSuggestions();
```

#### Event Handling

```typescript
const eventAwareFunction = func(myFunction, options);

eventAwareFunction.on("execution_success", (data) => {
    console.log(`Function executed successfully in ${data.executionTime}ms`);
});

eventAwareFunction.on("cache_hit", (data) => {
    console.log(`Cache hit for execution ${data.executionId}`);
});

eventAwareFunction.on("performance_warning", (data) => {
    console.warn(`Performance degradation detected: ${data.message}`);
});
```

## Encoding Types

FortifyJS supports various encoding formats:

| Encoding  | Use Case            | Example Output             |
| --------- | ------------------- | -------------------------- |
| hex       | Debugging           | `a1b2c3d4e5f6...`          |
| base64    | Data transmission   | `oWvD1OX2...`              |
| base64url | URL-safe tokens     | `oWvD1OX2...` (no padding) |
| base58    | Cryptocurrency      | `2NEpo7TZR...`             |
| binary    | Raw binary data     | Binary string              |
| utf8      | Text representation | UTF-8 string               |

## RSA Key Size Recommendations

| Data Size   | Recommended Key Size | Security Level | Use Case              |
| ----------- | -------------------- | -------------- | --------------------- |
| ≤ 190 bytes | 2048 bits            | Standard       | API keys, tokens      |
| ≤ 318 bytes | 3072 bits            | High           | Certificates, keys    |
| ≤ 446 bytes | 4096 bits            | Maximum        | High-security apps    |
| > 446 bytes | Hybrid Encryption    | Optimal        | Large data encryption |

## Security Levels

### Memory Protection Levels

-   **Basic**: Standard secure wiping
-   **Enhanced**: Includes fragmentation, encryption, and canaries
-   **Military**: Adds advanced obfuscation
-   **Quantum-Safe**: Incorporates quantum-resistant algorithms

### RSA Security Assessment

-   **Minimal**: 2048-bit keys (legacy compatibility)
-   **Standard**: 3072-bit keys (current standard)
-   **High**: 4096-bit keys (high-security applications)
-   **Maximum**: 8192+ bit keys (maximum security)

## Performance Benchmarks

### FortifiedFunction Performance

| Mode           | Execution Time | Performance Gain | Throughput (ops/sec) | Status           |
| -------------- | -------------- | ---------------- | -------------------- | ---------------- |
| **Ultra-Fast** | 1-4ms          | 27,000x faster   | 250-1,000            | Production Ready |
| **Standard**   | 20-50ms        | 2,000x faster    | 20-50                | Production Ready |
| **Secure**     | 100-200ms      | 500x faster      | 5-10                 | Production Ready |

**Baseline**: Original implementation: 109+ seconds per operation

### Random Generation Performance

| Operation                 | Rate (ops/sec) | Performance Grade |
| ------------------------- | -------------- | ----------------- |
| Random Float Generation   | 2,029,015      | Excellent         |
| Random Integer Generation | 1,645,765      | Excellent         |
| Secure UUID Generation    | 85,259         | Excellent         |
| Random Bytes (32B)        | 69,485         | Excellent         |
| Salt Generation (64B)     | 72,654         | Excellent         |

### Hash Operations Performance

| Operation         | Rate (ops/sec) | Security Level |
| ----------------- | -------------- | -------------- |
| SHA-256 Hashing   | 16             | Military-Grade |
| SHA-512 Hashing   | 14             | Military-Grade |
| BLAKE3 Hashing    | 3              | Maximum        |
| Hash Verification | 16             | Military-Grade |

### Password Algorithm Performance

| Algorithm | Hash Time | Verify Time | Security Level | Status           |
| --------- | --------- | ----------- | -------------- | ---------------- |
| Argon2ID  | 931ms     | 995ms       | High           | Production Ready |
| Argon2I   | 674ms     | 681ms       | High           | Production Ready |
| Argon2D   | 737ms     | 740ms       | High           | Production Ready |
| Scrypt    | TBD       | TBD         | Standard       | In Development   |
| PBKDF2    | TBD       | TBD         | Standard       | In Development   |
| Military  | TBD       | TBD         | Maximum        | In Development   |

### SecureArray Performance

| Operation             | Rate (ops/sec) | Security Level | Status           |
| --------------------- | -------------- | -------------- | ---------------- |
| Array Creation        | 50,000+        | Military-Grade | Production Ready |
| Encrypted Push/Pop    | 25,000+        | AES-256-CTR    | Production Ready |
| Snapshot Creation     | 10,000+        | Full State     | Production Ready |
| Event System          | 100,000+       | Real-Time      | Production Ready |
| Memory Management     | Auto           | Leak Detection | Production Ready |
| Serialization (JSON)  | 5,000+         | Compressed     | Production Ready |
| Export (CSV/XML/YAML) | 3,000+         | Multi-Format   | Production Ready |
| Integrity Validation  | 15,000+        | Checksum       | Production Ready |

### Large Data Processing

| Data Size  | Rate (ops/sec) | Use Case            |
| ---------- | -------------- | ------------------- |
| 1KB Data   | 15             | Small files, tokens |
| 10KB Data  | 17             | Documents, configs  |
| 100KB Data | 17             | Large files, images |

## Security Compliance

FortifyJS adheres to industry standards:

-   NIST SP 800-57: Key management recommendations
-   FIPS 140-2: Cryptographic module standards
-   Common Criteria: Security evaluation standards
-   OWASP: Web application security guidelines
-   SOC 2: Security and availability standards

## Advanced Usage

### Hybrid Encryption Strategy

```typescript
import { getEncryptionSuggestion } from "fortify2-js";

const suggestion = getEncryptionSuggestion(1024);
if (suggestion.approach === "hybrid") {
    console.log(suggestion.reason);
    console.log(
        "Performance Gain:",
        suggestion.details?.estimatedPerformanceGain
    );
}
```

### Security Monitoring

```typescript
import { FortifyJS } from "fortify2-js";

const securityStatus = FortifyJS.verifyRuntimeSecurity();
if (!securityStatus.isSecure) {
    console.warn("Security threats detected:", securityStatus.threats);
}
```

## API Documentation

### SecureRandom Methods

-   `getRandomBytes(length, options?)`: Generates secure random bytes (same as SecureRandom or Random .getRandomBytes method)
-   `generateSecureToken(length, options?)`: Creates secure tokens
-   `generateSecureUUID(options?)`: Produces secure UUIDs
-   `createEnhancedUint8Array(bytes)`: Creates enhanced byte arrays

### RSA Calculator Methods

-   `calculateRSAKeySize(dataSize, hashAlgorithm?, allowCustomSize?)`: Determines optimal key size
-   `generateRSAKeyPairForData(dataSize, hashAlgorithm?, allowCustomSize?)`: Generates optimized key pairs
-   `validateDataSizeForRSAKey(dataSize, rsaKeySize, hashAlgorithm?)`: Validates data/key compatibility
-   `getRSARecommendations(dataSize, hashAlgorithm?)`: Provides security recommendations
-   `assessRSASecurity(keySize, hashAlgorithm, dataSize)`: Performs security assessment

### SecureBuffer Methods

-   `new SecureBuffer(size, fill?, options?)`: Creates a secure buffer
-   `lock()` / `unlock()`: Manages buffer access
-   `verifyIntegrity()`: Checks buffer integrity
-   `getSecurityInfo()`: Retrieves security statistics
-   `clone()` / `resize(newSize)`: Performs buffer operations

## 📚 Documentation

### Complete Documentation

-   **[Quick Start Guide](./docs/quick-start.md)** - Get started in 5 minutes
-   **[SecureArray Documentation](./docs/secure-array.md)** - Complete feature guide
-   **[API Reference](./docs/api/secure-array-api.md)** - Full API documentation
-   **[Changelog](./docs/CHANGELOG.md)** - Latest updates and features

### Security & Performance

-   **[Security Best Practices](./docs/security/)** - Security guidelines
-   **[Performance Guide](./docs/performance/)** - Optimization tips
-   **[Migration Guide](./docs/migration/)** - Upgrade instructions

## Contributing

Contributions are welcome. Please refer to the [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

-   GitHub: [https://github.com/nehonix/fortifyjs](https://github.com/nehonix/fortifyjs)
-   NPM: [https://www.npmjs.com/package/fortify2-js](https://www.npmjs.com/package/fortify2-js)
-   Documentation: [https://lab.nehonix.space](https://lab.nehonix.space/nehonix_viewer/_doc/Nehonix%20FortifyJs/readme.md)
-   Security: [SECURITY.md](SECURITY.md)

---

**Developed by NEHONIX** | **Securing the digital world with advanced cryptography**