@nuwax-io/nuwault-core

v1.0.2

Published

4 days ago

Advanced password generation library with character diversity optimization, repetition control, and balanced distribution for maximum security

Downloads

136

Nuwault Core - Enterprise-grade deterministic password generation library built with TypeScript. Transform your memorable keywords into cryptographically secure passwords with guaranteed consistency across all platforms and devices. Featuring advanced character diversity algorithms, repetition control, and balanced distribution for maximum security without compromising usability.

Key Highlights

Enterprise Security: SHA-512 cryptographic hashing with 1000+ configurable iterations, unique salt per iteration, timing attack resistance, and optional master salt support
Deterministic Generation: Same inputs always produce identical passwords across all platforms (Node.js, browsers, different OS) with test vector validation
Privacy-First: Zero data collection, works completely offline, no external dependencies, uses native Web Crypto API
Performance Optimized: Configurable hash iterations (fast: 100, secure: 1000, maximum: 5000+) for different security needs
Advanced Character Analytics: Built-in password strength analysis, entropy calculation, character diversity metrics, repetition control, and balanced distribution algorithms
Cross-Platform Validated: Node.js 16+, modern browsers (Chrome 60+, Firefox 55+, Safari 11+), Web Workers, Electron, with automated compatibility testing
Developer-Friendly: Full TypeScript support, comprehensive type definitions, intellisense, both modern and legacy JavaScript APIs
Production Ready: Algorithm stability validation, health check endpoints, regression testing, version synchronization, and deployment validation
Highly Customizable: Flexible character sets, adaptive distribution algorithms, security configurations, and password composition options
Algorithm Validation: Comprehensive test vector validation, cross-platform consistency checks, and version tracking with compatibility guarantees
Stability Monitoring: Automated regression detection, algorithm change detection, and deployment safety validation
Modular Design: Use individual functions (generatePassword, analyzePassword) or complete NuwaultCore class
Dual API Support: Modern TypeScript API with full type safety and legacy JavaScript API for backward compatibility

Perfect For

Enterprise Applications: Password managers, authentication systems, security platforms requiring deterministic password generation
Personal Security Tools: Generate unique, memorable passwords for each service without storing them locally
Gaming & Simulation: Consistent seed generation for deterministic content, procedural generation, and reproducible randomness
Web Applications: Client-side password generation with zero server dependencies and offline capability
Progressive Web Apps: Offline password generation for enhanced privacy and cross-device synchronization
Developer & Testing Tools: Reproducible password generation for unit tests, integration tests, and CI/CD pipelines
CLI Tools & Scripts: Deterministic password generation for automation, deployment scripts, and infrastructure tools

Quality Assurance

Comprehensive Testing: 28+ test cases covering hash generation, password generation, character diversity, and cross-platform compatibility
Character Diversity Algorithms: Dynamic repetition control (8-char: max 2 reps, 32-char: max 4 reps), balanced distribution, and entropy maximization
Adaptive Distribution: Length-based strategies (short: equal, medium: 25/35/20/20, long: 20/35/20/25) for optimal security
Algorithm Stability: Test vector validation across Node.js, browsers, and Electron with automated regression detection
Cryptographic Standards: SHA-512 (NIST FIPS 180-4), Web Crypto API (W3C standard), IEEE-754 number precision
Complete Documentation: API reference, usage examples, TypeScript integration guide, and production deployment guide

Extended Documentation

Developer Guide - Complete API reference and configuration
Usage Examples - Comprehensive examples and patterns
Production Guide - Enterprise deployment and monitoring
TypeScript Guide - Full TypeScript integration guide

Getting Started

Core Features

Development

Production & Examples

Project Info

Installation

npm install @nuwax-io/nuwault-core

Quick Start

Using the Main Class (Recommended)

import NuwaultCore from '@nuwax-io/nuwault-core';

const generator = new NuwaultCore();

// Generate a password
const password = await generator.generatePassword(
  ['github.com', '[email protected]', 'my-master-key'],
  {
    length: 32,
    includeUppercase: true,
    includeLowercase: true,
    includeNumbers: true,
    includeSymbols: true
  }
);

console.log('Generated password:', password);

// Check algorithm health and version
import { getAlgorithmVersion, quickCompatibilityCheck } from '@nuwax-io/nuwault-core';

const version = getAlgorithmVersion();
const isHealthy = await quickCompatibilityCheck();

console.log(`Algorithm version: ${version.version}`);
console.log(`Library status: ${isHealthy ? 'Healthy ✅' : 'Issues detected ❌'}`);

Using Individual Functions

import { generatePassword, analyzeCharacterDistribution } from '@nuwax-io/nuwault-core';

// Generate password
const password = await generatePassword(
  ['github.com', '[email protected]'],
  { length: 16 }
);

// Analyze password strength
const analysis = analyzeCharacterDistribution(password, {
  includeUppercase: true,
  includeLowercase: true,
  includeNumbers: true,
  includeSymbols: true
});

console.log('Password:', password);
console.log('Distribution quality:', analysis.distribution);

Developer Guide

For detailed documentation on using the library, including comprehensive API reference, configuration options, and advanced usage examples, please see the Developer Guide.

Quick Class Reference

import NuwaultCore from '@nuwax-io/nuwault-core';

// Create generator
const generator = new NuwaultCore(customConfig);

// Generate password
const password = await generator.generatePassword(['github.com', 'username'], {
  length: 32,
  includeUppercase: true,
  includeLowercase: true,
  includeNumbers: true,
  includeSymbols: true
});

// Analyze password quality
const analysis = generator.analyzePassword(password);
console.log(`Password quality: ${analysis.distribution}`);

Available Functions

import {
  generatePassword,
  generateHash,
  hashToPassword,
  analyzeCharacterDistribution,
  validateAlgorithmCompatibility,
  quickCompatibilityCheck,
  getAlgorithmVersion,
  SECURITY_CONFIG,
  CHARACTER_SETS
} from '@nuwax-io/nuwault-core';

Complete API Documentation

Configuration

You can customize the security settings by providing a custom configuration:

import NuwaultCore from '@nuwax-io/nuwault-core';

const generator = new NuwaultCore({
  SECURITY_CONFIG: {
    hashIterations: 2000,        // More iterations = more secure but slower
    defaultPasswordLength: 32,   // Default password length
    minPasswordLength: 8,        // Minimum allowed length
    maxPasswordLength: 128,      // Maximum allowed length
    masterSalt: 'your-custom-salt' // Optional master salt (null = no salt)
  },
  CHARACTER_SETS: {
    SYMBOLS: '!@#$%^&*'         // Custom symbol set
  }
});

Algorithm Overview

Core Process

Input Validation: Validates and sanitizes input strings
Normalization: Converts inputs to lowercase, removes diacritics
Hash Generation: Multiple SHA-512 iterations with unique salts
Character Distribution: Advanced algorithms for balanced output
Deterministic Shuffle: Consistent results across generations

Character Distribution

The library uses sophisticated algorithms to ensure balanced character distribution with minimal repetition:

Adaptive Distribution: Different strategies based on password length
Character Repetition Control: Dynamic maximum repetition limits
Intelligent Character Selection: Multi-layer selection algorithm
Character Diversity Optimization: Maximizes unique character usage
Weighted Selection: Symbols and numbers get higher priority in longer passwords
Deterministic Shuffle: Fisher-Yates shuffle using hash entropy for consistent results

Hash Generation Security

Multiple Iterations: Configurable iterations (default: 1000) prevent rainbow table attacks
Unique Salt per Iteration: Each iteration uses a unique salt combining master salt, iteration counter, and previous hash
Master Salt Integration: When provided, prepended to every iteration for unique password variants
Timing Attack Prevention: Small delays during first iteration
Input Entropy Validation: Minimum combined input length requirements

Salt Construction Example:

// With master salt "org-salt"  
"org-salt|iter-0|github.com|[email protected]|initial-hash"
"org-salt|iter-1|github.com|[email protected]|previous-iteration-hash"

Security & Validation

Security Features

Multiple Hash Iterations: Configurable iterations (default: 1000) to prevent rainbow table attacks
Optional Master Salt: User-provided master salt for additional security (null by default)
Unique Salt per Iteration: Each hash iteration uses a unique salt combining master salt, iteration counter, and previous hash
Timing Attack Prevention: Small delays during hash generation
Input Validation: Comprehensive validation and sanitization
Deterministic Generation: Same inputs always produce the same password

Algorithm Validation

The library includes comprehensive validation systems to ensure algorithm consistency across different environments, platforms, and library versions.

import { validateAlgorithmCompatibility, getAlgorithmVersion } from '@nuwax-io/nuwault-core';

// Algorithm version tracking
const versionInfo = getAlgorithmVersion();
console.log(`Algorithm Version: ${versionInfo.version}`);

// Comprehensive validation
const validation = await validateAlgorithmCompatibility();
console.log(`Overall Compatible: ${validation.overall.isFullyCompatible}`);
console.log(`Hash Generation: ${validation.hashGeneration.isCompatible}`);
console.log(`Password Generation: ${validation.passwordGeneration.isCompatible}`);

Stability Guarantees

Deterministic Behavior: Same inputs always produce identical outputs across all platforms
Version Compatibility: Algorithm versioning prevents breaking changes
Platform Independence: Identical results on Node.js vs. Browser vs. Electron across different OS
Future-Proof Design: SHA-512 algorithm standardized by NIST (FIPS 180-4)

Supported Environments

✅ Node.js 16+: Full support with all features using Node.js crypto module
✅ Modern Browsers: Chrome 60+, Firefox 55+, Safari 11+, Edge 79+ with Web Crypto API
✅ Web Workers: Full support for background password generation
✅ Electron: Compatible with all Electron versions (uses Chromium's Web Crypto API)
❌ React Native: NOT supported - JavaScriptCore engine lacks Web Crypto API support

Note: React Native developers need to use crypto polyfills (like react-native-crypto) or alternative approaches as the native JavaScriptCore engine does not support the Web Crypto API required by this library.

Validation Commands

npm test                    # Run all tests including algorithm validation
npm run validate           # Comprehensive validation (type-check + test + version-check)
npm run version-check      # Check algorithm/package version synchronization
npm run prepublishOnly     # Pre-deployment validation

Production Features

The library is designed for enterprise production environments with comprehensive monitoring and validation capabilities. For detailed production deployment guides, enterprise configurations, and monitoring implementations, please see the Production Guide.

Key Features

Health Check API: Real-time algorithm compatibility monitoring endpoints
Deployment Validation: Automated algorithm integrity verification after deployments
Performance Monitoring: Built-in performance metrics and alerting
Enterprise Configuration: Organization-wide security settings and standards
Monitoring Dashboard Integration: Prometheus/Grafana metrics collection
Version Synchronization: Automated package.json ↔ algorithm version sync
CI/CD Integration: Pipeline validation and deployment safety checks

Quick Setup

// Health check endpoint
import { quickCompatibilityCheck } from '@nuwax-io/nuwault-core';

app.get('/health/algorithm', async (req, res) => {
  const isHealthy = await quickCompatibilityCheck();
  res.json({ 
    status: isHealthy ? 'healthy' : 'unhealthy',
    timestamp: new Date().toISOString()
  });
});

// Enterprise configuration
const enterpriseGenerator = new NuwaultCore({
  SECURITY_CONFIG: {
    hashIterations: 5000,
    defaultPasswordLength: 32,
    masterSalt: process.env.ORG_MASTER_SALT
  }
});

// Deployment validation
import { validateAlgorithmCompatibility } from '@nuwax-io/nuwault-core';
const validation = await validateAlgorithmCompatibility();
if (!validation.overall.isFullyCompatible) {
  throw new Error('Deployment validation failed');
}

Complete Production Guide

Browser Support

✅ Modern browsers with Web Crypto API support
✅ Node.js 16+
✅ Supports ES modules and CommonJS
✅ UMD build for legacy browser support

TypeScript Support

Full TypeScript support included with comprehensive type definitions and intellisense. For detailed TypeScript usage, interface definitions, configuration, and best practices, please see the TypeScript Guide.

Key TypeScript Features

Complete Type Definitions: Full type coverage for all functions and interfaces
Intellisense Support: Rich autocomplete and error detection in IDEs
Type-Safe API: Strict typing for all password generation and validation functions
Generic Support: Advanced generic types for custom implementations
Utility Types: Type guards, validation helpers, and custom type definitions

Quick TypeScript Example

import NuwaultCore from '@nuwax-io/nuwault-core';
import type { 
  PasswordGenerationResult, 
  CompatibilityResult,
  AlgorithmVersion 
} from '@nuwax-io/nuwault-core';

// Type-safe password generation
const generator = new NuwaultCore();
const result: PasswordGenerationResult = await generator.generatePassword(
  ['github.com', 'username'],
  { length: 32, includeSymbols: true }
);

// Type-safe algorithm validation
const validation: CompatibilityResult = await validateAlgorithmCompatibility();
const version: AlgorithmVersion = getAlgorithmVersion();

console.log(`Password: ${result.password}`);
console.log(`Algorithm compatible: ${validation.overall.isFullyCompatible}`);
console.log(`Version: ${version.version}`);

Complete TypeScript Guide

Usage Examples

For comprehensive usage examples, including advanced configurations, enterprise implementations, algorithm validation, and production monitoring examples, please see the Usage Examples.

Quick Examples

import NuwaultCore from '@nuwax-io/nuwault-core';

// Basic usage
const generator = new NuwaultCore();
const password = await generator.generatePassword(['github.com', 'username']);

// Advanced configuration
const advancedGenerator = new NuwaultCore({
  SECURITY_CONFIG: {
    hashIterations: 5000,
    defaultPasswordLength: 32,
    masterSalt: 'my-organization-salt'
  }
});

// Master salt usage
const userPassword = await generator.generatePassword(
  ['secure-site.com', '[email protected]'],
  { 
    length: 24,
    masterSalt: 'user-specific-salt' 
  }
);

// Password analysis
const analysis = generator.analyzePassword(password);
console.log(`Password quality: ${analysis.distribution}`);

// Algorithm validation
import { quickCompatibilityCheck, getAlgorithmVersion } from '@nuwax-io/nuwault-core';

const isHealthy = await quickCompatibilityCheck();
const version = getAlgorithmVersion();
console.log(`Algorithm version: ${version.version}, Status: ${isHealthy ? 'Healthy' : 'Issues detected'}`);

Complete Usage Examples

License

MIT - see LICENSE file for details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Security Policy

We take security seriously and appreciate responsible disclosure of vulnerabilities. For detailed security information, vulnerability reporting procedures, and security best practices, please see our Security Policy.

Security Overview

Secure by Design: SHA-512 hashing with multiple iterations
Deterministic Generation: Consistent, predictable outputs
Input Validation: Comprehensive validation and sanitization
Timing Attack Resistance: Protected against timing-based attacks
Memory Safety: Best-effort secure memory handling

Reporting Vulnerabilities

Please do not report security vulnerabilities via GitHub issues.

For security vulnerabilities, please:

Email: [email protected]
Follow our coordinated disclosure process
Receive acknowledgment within 48 hours

Complete Security Policy

Contact & Support

For general inquiries, technical support, or feedback, please reach out to us:

Support Email: [email protected]
GitHub Issues: Report bugs or request features
Documentation: Complete documentation and guides

We welcome your feedback and are committed to helping you get the most out of Nuwault Core.

Changelog

See CHANGELOG.md for a detailed history of changes.