{"id":29884775,"url":"https://github.com/chrishubert/password-manager-crypt","last_synced_at":"2026-05-17T11:33:53.785Z","repository":{"id":305344714,"uuid":"1022629667","full_name":"chrishubert/password-manager-crypt","owner":"chrishubert","description":"🔐 Secure, zero-dependency cryptographic library for password managers with universal runtime support (Node.js, CloudFlare Workers, Browsers)","archived":false,"fork":false,"pushed_at":"2025-08-25T16:49:54.000Z","size":299,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-04T02:54:41.729Z","etag":null,"topics":["browser","cloudflare-workers","cryptography","encryption","nodejs","password-manager","security","typescript","webcrypto","zero-knowledge"],"latest_commit_sha":null,"homepage":"https://chrishubert.github.io/password-manager-crypt","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrishubert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T13:41:11.000Z","updated_at":"2025-07-27T09:49:41.000Z","dependencies_parsed_at":"2025-07-19T18:28:05.750Z","dependency_job_id":"60a6fcf4-d7d9-49d6-b081-c1631172c136","html_url":"https://github.com/chrishubert/password-manager-crypt","commit_stats":null,"previous_names":["chrishubert/password-manager-crypt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/chrishubert/password-manager-crypt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fpassword-manager-crypt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fpassword-manager-crypt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fpassword-manager-crypt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fpassword-manager-crypt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrishubert","download_url":"https://codeload.github.com/chrishubert/password-manager-crypt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrishubert%2Fpassword-manager-crypt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33136781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T09:28:26.183Z","status":"ssl_error","status_checked_at":"2026-05-17T09:27:52.702Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","cloudflare-workers","cryptography","encryption","nodejs","password-manager","security","typescript","webcrypto","zero-knowledge"],"created_at":"2025-07-31T15:08:13.322Z","updated_at":"2026-05-17T11:33:53.769Z","avatar_url":"https://github.com/chrishubert.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Password Manager Cryptographic Library\n\n[![CI/CD Pipeline](https://github.com/chrishubert/password-manager-crypt/actions/workflows/ci.yml/badge.svg)](https://github.com/chrishubert/password-manager-crypt/actions/workflows/ci.yml)\n[![Security Checks](https://github.com/chrishubert/password-manager-crypt/actions/workflows/security.yml/badge.svg)](https://github.com/chrishubert/password-manager-crypt/actions/workflows/security.yml)\n[![npm version](https://badge.fury.io/js/password-manager-crypt.svg)](https://badge.fury.io/js/password-manager-crypt)\n\nA secure, zero-dependency cryptographic library designed specifically for password managers, implementing industry-standard encryption with zero-knowledge architecture principles.\n\n**✅ Production Ready**: Now available on NPM with universal support for **Node.js**, **CloudFlare Workers**, and **Browsers**.\n\n## Features\n\n- **🌍 Universal Runtime Support**: Node.js, CloudFlare Workers, and Browser environments\n- **⚡ Performance Optimized**: WebCrypto API provides 2-15x performance boost for large operations\n- **🔐 AES-256-GCM encryption** with authenticated encryption\n- **🔑 PBKDF2 key derivation** with configurable iterations (default: 600,000)\n- **📦 Zero dependencies** for minimal attack surface\n- **🏗️ TypeScript support** with comprehensive type definitions\n- **⏱️ Constant-time operations** to prevent timing attacks\n- **🛡️ Sanitized error handling** to prevent information leakage\n- **✅ NIST-compliant algorithms** for regulatory compliance\n- **🏭 Smart factory pattern** with automatic environment detection\n\n## Installation\n\n```bash\nnpm install password-manager-crypt\n```\n\n## Quick Start\n\n### Universal Usage (Auto-Detection)\n\n```typescript\nimport { cryptoServiceFactory, DEFAULT_KEY_DERIVATION_PARAMS } from 'password-manager-crypt';\n\n// Automatic environment detection and optimal performance selection\nconst cryptoService = cryptoServiceFactory.createForPerformance('high');\n```\n\n### Environment-Specific Usage\n\n```typescript\n// Node.js\nconst nodeService = cryptoServiceFactory.createForEnvironment('node');\n\n// CloudFlare Workers\nconst workerService = cryptoServiceFactory.createForEnvironment('worker');\n\n// Browser\nconst browserService = cryptoServiceFactory.createForEnvironment('browser');\n```\n\n### Complete Example\n\n```typescript\n// Encrypt vault data\nasync function encryptVault(masterPassword: string, vaultData: string): Promise\u003c{\n  encryptedData: EncryptedData;\n  salt: Uint8Array;\n}\u003e {\n  // Generate unique salt for this vault\n  const salt = cryptoService.generateSalt();\n  \n  // Derive encryption key from master password\n  const key = await cryptoService.deriveKey(\n    masterPassword, \n    salt, \n    DEFAULT_KEY_DERIVATION_PARAMS\n  );\n  \n  // Encrypt the vault data\n  const encryptedData = await cryptoService.encrypt(\n    new TextEncoder().encode(vaultData), \n    key\n  );\n  \n  return { encryptedData, salt };\n}\n\n// Decrypt vault data\nasync function decryptVault(\n  masterPassword: string, \n  salt: Uint8Array, \n  encryptedData: EncryptedData\n): Promise\u003cstring | null\u003e {\n  // Derive decryption key\n  const key = await cryptoService.deriveKey(\n    masterPassword, \n    salt, \n    DEFAULT_KEY_DERIVATION_PARAMS\n  );\n  \n  // Decrypt the vault data\n  const decryptedBytes = await cryptoService.decrypt(encryptedData, key);\n  \n  if (!decryptedBytes) {\n    return null; // Invalid password or tampered data\n  }\n  \n  return new TextDecoder().decode(decryptedBytes);\n}\n```\n\n## API Reference\n\n### CryptoService Interface\n\n#### `deriveKey(password: string, salt: Uint8Array, params: KeyDerivationParams): Promise\u003cUint8Array\u003e`\n\nDerives a cryptographic key from a password using PBKDF2.\n\n```typescript\nconst salt = cryptoService.generateSalt();\nconst key = await cryptoService.deriveKey('user-password', salt, {\n  iterations: 600000,\n  keyLength: 32,\n  algorithm: 'pbkdf2',\n  hashFunction: 'sha256'\n});\n```\n\n#### `encrypt(data: Uint8Array, key: Uint8Array): Promise\u003cEncryptedData\u003e`\n\nEncrypts data using AES-256-GCM with a random IV.\n\n```typescript\nconst data = new TextEncoder().encode('sensitive data');\nconst encryptedData = await cryptoService.encrypt(data, key);\n// Returns: { data, iv, salt, authTag }\n```\n\n#### `decrypt(encryptedData: EncryptedData, key: Uint8Array): Promise\u003cUint8Array | null\u003e`\n\nDecrypts data and verifies authentication tag. Returns `null` if decryption fails.\n\n```typescript\nconst decryptedData = await cryptoService.decrypt(encryptedData, key);\nif (decryptedData) {\n  const plaintext = new TextDecoder().decode(decryptedData);\n}\n```\n\n#### `generateSalt(length?: number): Uint8Array`\n\nGenerates a cryptographically secure random salt (default: 32 bytes).\n\n```typescript\nconst salt = cryptoService.generateSalt(); // 32 bytes\nconst customSalt = cryptoService.generateSalt(16); // 16 bytes\n```\n\n#### `generateIV(length?: number): Uint8Array`\n\nGenerates a cryptographically secure random IV (default: 12 bytes for GCM).\n\n```typescript\nconst iv = cryptoService.generateIV(); // 12 bytes for AES-GCM\n```\n\n### Factory Pattern\n\n#### `cryptoServiceFactory.createForEnvironment(env)`\n\nCreates a crypto service optimized for the specified environment:\n\n```typescript\n// Node.js environment (uses Node.js crypto module)\nconst nodeService = cryptoServiceFactory.createForEnvironment('node');\n\n// CloudFlare Workers (uses WebCrypto API)\nconst workerService = cryptoServiceFactory.createForEnvironment('worker');\n\n// Browser environment (uses WebCrypto API)\nconst browserService = cryptoServiceFactory.createForEnvironment('browser');\n```\n\n#### `cryptoServiceFactory.createForPerformance(level)`\n\nCreates a crypto service optimized for the specified performance level:\n\n```typescript\n// High performance: Prefers Node.js crypto, falls back to WebCrypto\nconst highPerfService = cryptoServiceFactory.createForPerformance('high');\n\n// Medium/Low performance: Prefers WebCrypto for universal compatibility\nconst mediumPerfService = cryptoServiceFactory.createForPerformance('medium');\n```\n\n### Types\n\n#### `EncryptedData`\n\n```typescript\ninterface EncryptedData {\n  readonly data: Uint8Array;      // Encrypted data\n  readonly iv: Uint8Array;        // Initialization vector\n  readonly salt: Uint8Array;      // Salt for key derivation\n  readonly authTag: Uint8Array;   // Authentication tag\n}\n```\n\n#### `KeyDerivationParams`\n\n```typescript\ninterface KeyDerivationParams {\n  readonly iterations: number;    // PBKDF2 iterations (recommend 600,000+)\n  readonly keyLength: number;     // Output key length in bytes\n  readonly algorithm: 'pbkdf2';   // Algorithm type\n  readonly hashFunction: 'sha256' | 'sha512'; // Hash function\n}\n```\n\n## Security Best Practices\n\n### Password Requirements\n\n```typescript\n// Use strong, unique master passwords\nconst masterPassword = 'MySecure!MasterPassword2024';\n\n// Always use unique salts per vault\nconst salt = cryptoService.generateSalt();\n```\n\n### Error Handling\n\n```typescript\ntry {\n  const key = await cryptoService.deriveKey(password, salt, params);\n  const encrypted = await cryptoService.encrypt(data, key);\n} catch (error) {\n  if (error instanceof CryptoError) {\n    console.log(`Crypto operation failed: ${error.category}`);\n    // Error messages are sanitized automatically\n  }\n}\n```\n\n### Memory Management\n\n```typescript\n// Clear sensitive data when done (best effort)\nconst clearArray = (arr: Uint8Array): void =\u003e {\n  for (let i = 0; i \u003c arr.length; i++) {\n    arr[i] = 0;\n  }\n};\n\n// Use and clear\nconst key = await cryptoService.deriveKey(password, salt, params);\n// ... use key for encryption/decryption\nclearArray(key);\n```\n\n## Environment-Specific Usage\n\n### CloudFlare Workers\n\n```typescript\n// wrangler.toml (optional - enables Node.js crypto compatibility)\ncompatibility_flags = [\"nodejs_compat\"]\ncompatibility_date = \"2024-09-23\"\n\n// worker.js\nimport { cryptoServiceFactory } from 'password-manager-crypt';\n\nexport default {\n  async fetch(request, env, ctx) {\n    // Use WebCrypto for maximum compatibility\n    const cryptoService = cryptoServiceFactory.createForEnvironment('worker');\n    \n    const vault = await encryptVault('master-password', 'sensitive-data');\n    return new Response(JSON.stringify(vault));\n  }\n};\n```\n\n### Browser Usage\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  \u003cscript type=\"module\"\u003e\n    import { cryptoServiceFactory } from 'https://unpkg.com/password-manager-crypt/dist/index.esm.js';\n    \n    // Browser environment with WebCrypto\n    const cryptoService = cryptoServiceFactory.createForEnvironment('browser');\n    \n    async function handlePasswordStorage() {\n      const vault = await encryptVault('user-password', 'user-data');\n      localStorage.setItem('encrypted-vault', JSON.stringify(vault));\n    }\n  \u003c/script\u003e\n\u003c/head\u003e\n\u003c/html\u003e\n```\n\n### Node.js Server\n\n```typescript\nimport { cryptoServiceFactory } from 'password-manager-crypt';\n\n// High-performance Node.js crypto\nconst cryptoService = cryptoServiceFactory.createForEnvironment('node');\n\n// Express.js route example\napp.post('/encrypt-vault', async (req, res) =\u003e {\n  const { password, data } = req.body;\n  const vault = await encryptVault(password, data);\n  res.json(vault);\n});\n```\n\n## Performance Considerations\n\n### Environment Performance Comparison\n\n| Environment | Implementation | Relative Performance | Best For |\n|-------------|----------------|---------------------|----------|\n| Node.js | Native crypto module | 🔥🔥🔥 Fastest (3x) | Server-side, CLI tools |\n| CloudFlare Workers | WebCrypto API | 🔥🔥 Fast (2-15x) | Edge computing, APIs |\n| Browser | WebCrypto API | 🔥🔥 Fast (2-15x) | Client-side encryption |\n\n### Key Derivation\n\n- PBKDF2 with 600,000 iterations:\n  - **Node.js**: ~300ms \n  - **WebCrypto**: ~400-500ms \n- Consider caching derived keys in memory for session duration\n- Use Web Workers in browsers for non-blocking key derivation\n\n### Encryption Performance\n\n- **Large data (\u003e1MB)**: All implementations benefit from native crypto APIs\n- **Small data (\u003c10KB)**: WebCrypto has lower initialization overhead\n- **Streaming**: Consider chunked encryption for very large datasets\n\n## Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n## Building\n\n```bash\n# Build all formats\nnpm run build\n\n# Build specific formats\nnpm run build:cjs    # CommonJS\nnpm run build:esm    # ES Modules\nnpm run build:types  # TypeScript declarations\n```\n\n## Security Audit Status\n\nThis library implements well-established cryptographic algorithms and follows security best practices:\n\n- **Algorithms**: AES-256-GCM (NIST approved), PBKDF2-SHA256 (NIST approved)\n- **Key derivation**: 600,000+ iterations (exceeds OWASP recommendations)\n- **Random generation**: Uses Node.js crypto.randomBytes (CSPRNG)\n- **Authentication**: GCM mode provides built-in authenticated encryption\n\n**Note**: This library has not yet undergone formal cryptographic audit. For production use in critical applications, consider professional security review.\n\n## CI/CD Pipeline\n\nThis project uses comprehensive GitHub Actions workflows for quality assurance:\n\n### 🔄 **Continuous Integration** (`ci.yml`)\n- **Multi-Node.js testing**: Tests on Node.js 16, 18, 20, 22\n- **Cross-platform validation**: Ubuntu, Windows, macOS\n- **Quality checks**: Linting, type checking, test coverage\n- **Build verification**: Validates all module formats (CJS, ESM, TypeScript)\n\n### 🔒 **Security Monitoring** (`security.yml`)\n- **CodeQL analysis**: Static security scanning\n- **Dependency auditing**: Weekly vulnerability checks\n- **License compliance**: Ensures compatible licenses only\n- **Supply chain security**: Dependency review on PRs\n\n### 🚀 **Automated Releases** (`release.yml`)\n- **Tag-triggered releases**: Automatically publishes on version tags\n- **NPM publishing**: With provenance attestation for supply chain security\n- **GitHub releases**: Auto-generated changelogs and artifacts\n\n### 📦 **Package Publishing**\n```bash\n# Create and publish a release\ngit tag v1.0.0\ngit push origin v1.0.0\n# CI automatically builds, tests, and publishes to NPM\n```\n\n### 🔧 **Required Secrets**\nSet these in your GitHub repository settings:\n- `NPM_TOKEN`: NPM authentication token with publish permissions\n\n## License\n\nApache 2.0 - See [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Follow existing code style and patterns\n2. Add comprehensive tests for new features\n3. Ensure all security checks pass\n4. Update documentation as needed\n\n## Support\n\n- GitHub Issues: Report bugs and request features\n- Security Issues: Contact maintainers privately for security vulnerabilities\n\n## Migration Guide\n\n### From v0.1.x to v0.2.x\n\nAll `encrypt` and `decrypt` methods are now async for consistency across environments:\n\n```typescript\n// Before (v0.1.x)\nconst encrypted = cryptoService.encrypt(data, key);\nconst decrypted = cryptoService.decrypt(encrypted, key);\n\n// After (v0.2.x)\nconst encrypted = await cryptoService.encrypt(data, key);\nconst decrypted = await cryptoService.decrypt(encrypted, key);\n```\n\n## Browser Compatibility\n\n| Browser | WebCrypto Support | Status |\n|---------|------------------|--------|\n| Chrome 37+ | ✅ Full support | Recommended |\n| Firefox 34+ | ✅ Full support | Recommended |\n| Safari 7+ | ✅ Full support | Recommended |\n| Edge 12+ | ✅ Full support | Recommended |\n| IE | ❌ Not supported | Use polyfill |\n\n## CloudFlare Workers Compatibility\n\n| Feature | Status | Notes |\n|---------|--------|-------|\n| WebCrypto API | ✅ Full support | Recommended approach |\n| Node.js crypto | ✅ With nodejs_compat flag | Optional for compatibility |\n| Performance | 🔥🔥 Excellent | 2-15x faster than pure JS |\n\n## Changelog\n\n### v0.2.0 (2025-07-19) - Production Release\n\n- ✅ **Universal Runtime Support**: CloudFlare Workers and Browser environments\n- ✅ **WebCrypto Implementation**: 2-15x performance improvement for large operations  \n- ✅ **Smart Factory Pattern**: Automatic environment detection and optimization\n- ✅ **Consistent Async API**: All crypto operations now return Promises\n- ✅ **Comprehensive Testing**: 85 tests including NIST test vectors and cross-environment validation\n- ✅ **Security Maintained**: All timing attack protections preserved\n- ✅ **NPM Published**: Available with provenance attestation for supply chain security\n- 🔄 **Breaking Change**: encrypt/decrypt methods now async\n\n### v0.1.0\n\n- Initial release with Node.js support\n- AES-256-GCM encryption/decryption\n- PBKDF2 key derivation\n- Comprehensive test suite\n- TypeScript support","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrishubert%2Fpassword-manager-crypt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrishubert%2Fpassword-manager-crypt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrishubert%2Fpassword-manager-crypt/lists"}