{"_id":"@dolianecom/crypto-toolkit","_rev":"3-3a694f7cdd670cdfafc9c894cf55eb2e","name":"@dolianecom/crypto-toolkit","dist-tags":{"latest":"1.0.1"},"versions":{"0.1.0":{"name":"@dolianecom/crypto-toolkit","version":"0.1.0","keywords":["crypto","aes","gcm","aes-kw","streaming","webcrypto","typescript","security","encoding","hex","base58"],"license":"MIT","_id":"@dolianecom/crypto-toolkit@0.1.0","maintainers":[{"name":"nyedidikeke","email":"me@nyedidikeke.com"}],"homepage":"https://github.com/dolianecom/crypto-toolkit#readme","bugs":{"url":"https://github.com/dolianecom/crypto-toolkit/issues"},"dist":{"shasum":"87e6ba3c39f8943330221236f5157a52ff257ec0","tarball":"https://registry.npmjs.org/@dolianecom/crypto-toolkit/-/crypto-toolkit-0.1.0.tgz","fileCount":36,"integrity":"sha512-8KOlThia746H14pJk2NyFLGJIHBRkO9YZAa7Fud9/80LFbFcT8YUW4pvRBUgF2gBOi5Z8jle/yJDlRHVuG9GJA==","signatures":[{"sig":"MEUCIHdBBmxkfBz3PLsSHzqTCBnOVb9SYT9qY8BGBuP/2/JNAiEAs8Jq7wIIP8iH8dgTUo0ybg6o9THfYhty0kQ7rVbxHO4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":104227},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=24.11"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"8ce1185de2a2c9f9619433a15c49a0f1dcb8ecc0","scripts":{"dev":"tsc -w","lint":"eslint . --fix","test":"pnpm run test:regular && pnpm run test:fuzz && pnpm run test:stress","build":"tsc -p tsconfig.json","clean":"rm -rf dist && rm -rf node_modules","format":"prettier --write .","prepare":"husky","test:fuzz":"node dist/test/aes-gcm.fuzz.spec.js && node dist/test/encoders.fuzz.spec.js","clean:dist":"rm -rf dist","lint:check":"eslint .","test:stress":"node dist/test/aes-gcm.stress.spec.js && node dist/test/encoders.stress.spec.js","format:check":"prettier --check .","test:regular":"node dist/test/aes-gcm.spec.js && node dist/test/encoders.spec.js"},"_npmUser":{"name":"nyedidikeke","email":"me@nyedidikeke.com"},"repository":{"url":"git+https://github.com/dolianecom/crypto-toolkit.git","type":"git"},"_npmVersion":"11.6.2","description":"Framework-agnostic, TypeScript cryptographic toolkit built on Web Crypto API (AES-GCM, AES-KW, streaming, encoders)","directories":{},"lint-staged":{"*.{js,ts}":["eslint --fix"],"*.{js,ts,json,md,yml,yaml}":["prettier --write"]},"sideEffects":false,"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"packageManager":"pnpm@10.9.0","devDependencies":{"husky":"9.1.7","eslint":"9.39.1","ts-node":"^10.9.2","prettier":"3.7.2","@eslint/js":"9.39.1","@types/node":"^24.10.1","lint-staged":"16.2.7","@commitlint/cli":"20.1.0","typescript-eslint":"8.48.0","@semantic-release/git":"10.0.1","@semantic-release/npm":"13.1.2","eslint-config-prettier":"10.1.8","@semantic-release/github":"12.0.2","@semantic-release/changelog":"6.0.3","@commitlint/config-conventional":"20.0.0","eslint-plugin-simple-import-sort":"12.1.1","@semantic-release/commit-analyzer":"13.0.1","@semantic-release/release-notes-generator":"14.1.0"},"_npmOperationalInternal":{"tmp":"tmp/crypto-toolkit_0.1.0_1764586548723_0.0837126529905754","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@dolianecom/crypto-toolkit","version":"1.0.0","keywords":["crypto","aes","gcm","aes-kw","streaming","webcrypto","typescript","security","encoding","hex","base58"],"license":"MIT","_id":"@dolianecom/crypto-toolkit@1.0.0","maintainers":[{"name":"nyedidikeke","email":"me@nyedidikeke.com"}],"homepage":"https://github.com/dolianecom/crypto-toolkit#readme","bugs":{"url":"https://github.com/dolianecom/crypto-toolkit/issues"},"dist":{"shasum":"0ea36e94e7a6d53ff4c6d5b44f29a60df162bbae","tarball":"https://registry.npmjs.org/@dolianecom/crypto-toolkit/-/crypto-toolkit-1.0.0.tgz","fileCount":36,"integrity":"sha512-cQVxdkX4f+qIDoO8oYHZDL6BLdZnklXoWBe9ioxXGgnQKnSpBKmOK9cxX7OyIbKo5UPbnbuWFCqlpaNVsNocmQ==","signatures":[{"sig":"MEUCIQCTI14Deh73dyLvBBO5gHaVwyurN7AAKMnxh6hcWH8+ewIgfs/kbN1rrGHguzd5BakT/BDjUfWBBv0ZJxDWz1L5gok=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dolianecom%2fcrypto-toolkit@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":105830},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=24.11"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"dd6449642822c750480b1da3f79c85c547eed8a3","scripts":{"dev":"tsc -w","lint":"eslint . --fix","test":"pnpm run test:regular && pnpm run test:fuzz && pnpm run test:stress","build":"tsc -p tsconfig.json","clean":"rm -rf dist && rm -rf node_modules","format":"prettier --write .","prepare":"husky","test:fuzz":"node dist/test/aes-gcm.fuzz.spec.js && node dist/test/encoders.fuzz.spec.js","clean:dist":"rm -rf dist","lint:check":"eslint .","test:stress":"node dist/test/aes-gcm.stress.spec.js && node dist/test/encoders.stress.spec.js","format:check":"prettier --check .","test:regular":"node dist/test/aes-gcm.spec.js && node dist/test/encoders.spec.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:fd383e26-dd59-424b-932a-d117274e28b1"}},"repository":{"url":"git+https://github.com/dolianecom/crypto-toolkit.git","type":"git"},"_npmVersion":"11.6.2","description":"Framework-agnostic, TypeScript cryptographic toolkit built on Web Crypto API (AES-GCM, AES-KW, streaming, encoders)","directories":{},"lint-staged":{"*.{js,ts}":["eslint --fix"],"*.{js,ts,json,md,yml,yaml}":["prettier --write"]},"sideEffects":false,"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"packageManager":"pnpm@10.9.0","devDependencies":{"husky":"9.1.7","eslint":"9.39.1","ts-node":"^10.9.2","prettier":"3.7.2","@eslint/js":"9.39.1","@types/node":"^24.10.1","lint-staged":"16.2.7","@commitlint/cli":"20.1.0","typescript-eslint":"8.48.0","@semantic-release/git":"10.0.1","@semantic-release/npm":"13.1.2","eslint-config-prettier":"10.1.8","@semantic-release/github":"12.0.2","@semantic-release/changelog":"6.0.3","@commitlint/config-conventional":"20.0.0","eslint-plugin-simple-import-sort":"12.1.1","@semantic-release/commit-analyzer":"13.0.1","@semantic-release/release-notes-generator":"14.1.0"},"_npmOperationalInternal":{"tmp":"tmp/crypto-toolkit_1.0.0_1764623144854_0.21953960045511778","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@dolianecom/crypto-toolkit","version":"1.0.1","description":"Framework-agnostic, TypeScript cryptographic toolkit built on Web Crypto API (AES-GCM, AES-KW, streaming, encoders)","type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"sideEffects":false,"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist && rm -rf node_modules","clean:dist":"rm -rf dist","dev":"tsc -w","test":"pnpm run test:regular && pnpm run test:fuzz && pnpm run test:stress","test:regular":"node dist/test/aes-gcm.spec.js && node dist/test/encoders.spec.js","test:fuzz":"node dist/test/aes-gcm.fuzz.spec.js && node dist/test/encoders.fuzz.spec.js","test:stress":"node dist/test/aes-gcm.stress.spec.js && node dist/test/encoders.stress.spec.js","lint":"eslint . --fix","lint:check":"eslint .","format":"prettier --write .","format:check":"prettier --check .","prepare":"husky"},"engines":{"node":">=24.11"},"keywords":["crypto","aes","gcm","aes-kw","streaming","webcrypto","typescript","security","encoding","hex","base58"],"repository":{"type":"git","url":"git+https://github.com/dolianecom/crypto-toolkit.git"},"license":"MIT","devDependencies":{"@commitlint/cli":"20.1.0","@commitlint/config-conventional":"20.0.0","@eslint/js":"9.39.1","@semantic-release/changelog":"6.0.3","@semantic-release/commit-analyzer":"13.0.1","@semantic-release/git":"10.0.1","@semantic-release/github":"12.0.2","@semantic-release/npm":"13.1.2","@semantic-release/release-notes-generator":"14.1.0","@types/node":"^24.10.1","eslint":"9.39.1","eslint-config-prettier":"10.1.8","eslint-plugin-simple-import-sort":"12.1.1","husky":"9.1.7","lint-staged":"16.2.7","prettier":"3.7.2","ts-node":"^10.9.2","typescript-eslint":"8.48.0"},"lint-staged":{"*.{js,ts,json,md,yml,yaml}":["prettier --write"],"*.{js,ts}":["eslint --fix"]},"packageManager":"pnpm@10.9.0","gitHead":"8a0835e649c31202e7499de372f8c4085144b136","_id":"@dolianecom/crypto-toolkit@1.0.1","bugs":{"url":"https://github.com/dolianecom/crypto-toolkit/issues"},"homepage":"https://github.com/dolianecom/crypto-toolkit#readme","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-ppsPp1CvbgzRzNYG5wxlmoBxHnb8Ksdpjg518fi7eougImfgMJ8QfO77Ggp52QTuPE2a7AYV3JwNWBTJksrgjQ==","shasum":"54247c262107a4e75c096ef99b4617f568069421","tarball":"https://registry.npmjs.org/@dolianecom/crypto-toolkit/-/crypto-toolkit-1.0.1.tgz","fileCount":36,"unpackedSize":106119,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dolianecom%2fcrypto-toolkit@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA7awHPc/o1tToOdyDaYMuC2bFybGqs0RMWo8qcc2Ei9AiEA5HAIjwsMZ4VpC6P96rADZ99TeR/nxwX9ex+f3ij3ZEI="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:fd383e26-dd59-424b-932a-d117274e28b1"}},"directories":{},"maintainers":[{"name":"nyedidikeke","email":"me@nyedidikeke.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/crypto-toolkit_1.0.1_1764642126553_0.4880168550879962"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-01T10:55:48.527Z","modified":"2025-12-02T02:22:07.189Z","0.1.0":"2025-12-01T10:55:48.918Z","1.0.0":"2025-12-01T21:05:45.031Z","1.0.1":"2025-12-02T02:22:06.769Z"},"bugs":{"url":"https://github.com/dolianecom/crypto-toolkit/issues"},"license":"MIT","homepage":"https://github.com/dolianecom/crypto-toolkit#readme","keywords":["crypto","aes","gcm","aes-kw","streaming","webcrypto","typescript","security","encoding","hex","base58"],"repository":{"type":"git","url":"git+https://github.com/dolianecom/crypto-toolkit.git"},"description":"Framework-agnostic, TypeScript cryptographic toolkit built on Web Crypto API (AES-GCM, AES-KW, streaming, encoders)","maintainers":[{"name":"nyedidikeke","email":"me@nyedidikeke.com"}],"readme":"# Crypto Toolkit\n\nA lightweight TypeScript/JavaScript library providing **AES‑256‑GCM encryption/decryption** and **encoding utilities** (UTF‑8, Base64, Base64URL, byte concatenation).  \nIncludes **comprehensive test coverage** with regular, fuzz, and stress suites.  \nWorks seamlessly in **Node.js (v18+)** and modern browsers.\n\n---\n\n## 📑 Table of Contents\n\n- [✨ Features](#-features)\n- [📦 Installation](#-installation)\n- [🚀 Usage](#-usage)\n  - [🖥️ Node.js (ESM)](#-nodejs-esm)\n  - [🌐 Browser](#-browser)\n- [🔧 API](#-api)\n- [🧪 Testing](#-testing)\n  - [⚡ Quick Test](#-quick-test)\n  - [🧭 Running Tests](#-running-tests)\n- [🛠 Development](#-development)\n- [🤝 Contributing](#-contributing)\n- [🔒 Security](#-security)\n- [🔖 Release & Versioning](#-release--versioning)\n- [🗺 Roadmap](#-roadmap)\n- [❓ FAQ](#-faq)\n- [💬 Support](#-support)\n- [🙏 Credits / Acknowledgements](#-credits--acknowledgements)\n- [📥 Installation from Source](#-installation-from-source)\n- [⚖️ License](#-license)\n\n---\n\n## ✨ Features\n\n- AES‑256‑GCM symmetric encryption/decryption\n- PBKDF2 key derivation with SHA‑256\n- Secure random IV generation (12 bytes, recommended for GCM)\n- Encoding helpers: UTF‑8, Base64, Base64URL, byte concatenation\n- Portable across Node.js and browsers\n- **Testing strategy with finer‑control scripts:**\n  - Regular tests (deterministic correctness)\n  - Fuzz tests (randomized breadth)\n  - Stress tests (large inputs & concurrency)\n\n---\n\n## 📦 Installation\n\n```bash\npnpm add @dolianecom/crypto-toolkit\n# or\nnpm install @dolianecom/crypto-toolkit\n```\n\n---\n\n## 🚀 Usage\n\n### 🖥️ Node.js (ESM)\n\n```ts\nimport {\n  importKey,\n  encrypt,\n  decrypt,\n  randomIv,\n  utf8ToBytes,\n  bytesToUtf8,\n  toBase64Url,\n  fromBase64Url,\n} from '@dolianecom/crypto-toolkit'\n\nimport { getCrypto } from '@dolianecom/crypto-toolkit/env.js'\n\nasync function demo() {\n  const crypto = getCrypto()\n\n  // Generate a random AES-256 key\n  const rawKey = crypto.getRandomValues(new Uint8Array(32))\n  const key = await importKey(rawKey)\n\n  // Encrypt a message\n  const iv = randomIv()\n  const plaintext = utf8ToBytes('hello, world')\n  const { ciphertext } = await encrypt(key, plaintext, { iv })\n\n  // Pack IV and ciphertext into a Base64Url string\n  const packed = `${toBase64Url(iv)}.${toBase64Url(ciphertext)}`\n  console.log('Packed:', packed)\n\n  // Unpack and decrypt\n  const [ivB64, ctB64] = packed.split('.')\n  const decrypted = await decrypt(key, fromBase64Url(ivB64), fromBase64Url(ctB64))\n\n  console.log('Decrypted:', bytesToUtf8(decrypted))\n}\n\ndemo()\n```\n\n### 🌐 Browser\n\n```ts\nimport { importKey, encrypt, decrypt, randomIv, utf8ToBytes, bytesToUtf8 } from '@dolianecom/crypto-toolkit'\n;(async () => {\n  // Generate a random AES-256 key\n  const rawKey = crypto.getRandomValues(new Uint8Array(32))\n  const key = await importKey(rawKey)\n\n  // Encrypt a message\n  const iv = randomIv()\n  const msg = utf8ToBytes('secret message')\n  const { ciphertext } = await encrypt(key, msg, { iv })\n\n  // Decrypt the message\n  const decrypted = await decrypt(key, iv, ciphertext)\n  console.log(bytesToUtf8(decrypted)) // \"secret message\"\n})()\n```\n\n---\n\n## 🔧 API\n\n```ts\n// Key management\nimportKey(rawKey: Uint8Array): Promise<CryptoKey>\nderiveKeyFromPassword(password: string, salt: Uint8Array, iterations?: number): Promise<Uint8Array>\n\n// AES-GCM encryption/decryption\nencrypt(key: CryptoKey, plaintext: Uint8Array, opts?: AesGcmOptions): Promise<{ iv: Uint8Array; ciphertext: Uint8Array }>\ndecrypt(key: CryptoKey, iv: Uint8Array, ciphertext: Uint8Array, opts?: AesGcmOptions): Promise<Uint8Array>\nrandomIv(): Uint8Array\n\n// Encoding utilities\nutf8ToBytes(input: string): Uint8Array\nbytesToUtf8(bytes: Uint8Array): string\ntoBase64(bytes: Uint8Array): string\nfromBase64(str: string): Uint8Array\ntoBase64Url(bytes: Uint8Array): string\nfromBase64Url(str: string): Uint8Array\nconcatBytes(...arrays: Uint8Array[]): Uint8Array\n```\n\n---\n\n## 🧪 Testing\n\nWe maintain **three layers of tests**:\n\n- **Regular tests**: deterministic correctness (round‑trip, wrong key/IV, corrupted ciphertext, malformed encodings).\n- **Fuzz tests**: randomized inputs for breadth (random plaintext, strings, AAD/tag lengths, malformed encodings).\n- **Stress tests**: large inputs and concurrency for robustness (1MB plaintext, 100 sequential, 50 concurrent, large Base64).\n\n### ⚡ Quick Test\n\nYou can quickly verify the build with:\n\n```bash\npnpm build\nnode dist/scratch.js\n```\n\nExpected output:\n\n```text\nPacked: <base64url-iv>.<base64url-ciphertext>\nDecrypted: hello, world\n```\n\n### 🧭 Running Tests\n\nWe use finer‑control scripts in `package.json`:\n\n```bash\npnpm test\npnpm test:regular\npnpm test:fuzz\npnpm test:stress\n```\n\nRun all suites:\n\n```bash\npnpm build\npnpm test\n```\n\n---\n\n## 🛠 Development\n\nTo set up a local development environment:\n\n```bash\n# Clone the repository\ngit clone https://github.com/dolianecom/crypto-toolkit.git\n\n# Navigate into the project directory\ncd crypto-toolkit\n\n# Install dependencies\npnpm install\n\n# Build the project\npnpm build\n\n# Run the full test suite to verify everything works\npnpm test\n\n# Execute a quick scratch script for a sanity check\nnode dist/scratch.js\n```\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions of all kinds — bug fixes, documentation improvements, and new features.  \nTo keep our history clean and consistent, we follow specific development and commit guidelines.\n\n👉 Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contributor guide.\n\n---\n\n## 🔒 Security\n\nFor details on reporting vulnerabilities and best practices for safe usage,  \nplease see our dedicated [SECURITY.md](./SECURITY.md) file.\n\nWe take security seriously and appreciate responsible disclosure.  \nFollowing the guidelines in `SECURITY.md` helps ensure your use of the toolkit remains secure in production environments.\n\n---\n\n## 🔖 Release & Versioning\n\nWe follow **Semantic Versioning (SemVer)**:\n\n- **MAJOR**: Breaking changes\n- **MINOR**: New features\n- **PATCH**: Bug fixes\n\n```bash\npnpm test\npnpm version <major|minor|patch>\ngit push && git push --tags\npnpm publish --access public\n```\n\n---\n\n## 🗺 Roadmap\n\n- Streaming API support\n- Key wrapping/unwrapping (AES‑KW)\n- Browser UMD build\n- Hex and base58 encoding helpers\n- Performance benchmarks and tracking\n- Examples gallery (Express, React, Deno)\n\n---\n\n## ❓ FAQ\n\n**Q: Why AES‑GCM instead of other modes like CBC?**  \nA: AES‑GCM provides both confidentiality and integrity (authenticated encryption). It's faster and safer than CBC for modern applications.\n\n**Q: Does this library work in Deno?**  \nA: Yes. Deno supports the Web Crypto API, so the core functions should work. You may need to adjust imports for Deno's module system.\n\n**Q: How do I generate a secure key?**  \nA: Use `crypto.getRandomValues(new Uint8Array(32))` for a raw 256‑bit key, then call `importKey`.\n\n**Q: Can I use this for password storage?**  \nA: No. AES‑GCM is for encryption/decryption. For password storage, use a hashing algorithm like bcrypt, scrypt, or Argon2.\n\n**Q: Is this library production‑ready?**  \nA: It's designed to be lightweight and standards‑compliant. Always audit cryptographic code before deploying in production.\n\n**Q: Does this library include encoders?**  \nA: Yes. It provides UTF‑8, Base64, Base64URL, and byte concatenation helpers, tested with regular, fuzz, and stress suites.\n\n**Q: How are tests organized?**  \nA: With finer‑control scripts: `test:regular`, `test:fuzz`, `test:stress`, and `test` to run everything.\n\n---\n\n## 💬 Support\n\nIf you need help:\n\n- Open an issue on [GitHub Issues](https://github.com/dolianecom/crypto-toolkit/issues).\n- Check the [FAQ](#-faq) and [Roadmap](#-roadmap) for common questions and planned features.\n- For security concerns, follow the steps in the [Security](#-security) section.\n- For general questions, discussions, or feature requests, use [GitHub Discussions](https://github.com/dolianecom/crypto-toolkit/discussions).\n\nWe aim to respond promptly and welcome community engagement.\n\n---\n\n## 🙏 Credits / Acknowledgements\n\n- Inspired by the **Web Crypto API** and its cross‑platform capabilities.\n- Thanks to the **TypeScript** and **Node.js** communities for guidance on strict typing and ESM support.\n- Special appreciation to contributors who improve documentation, tests, and features.\n- Badge icons provided by [Shields.io](https://shields.io).\n\n---\n\n## 📥 Installation from Source\n\n```bash\ngit clone https://github.com/dolianecom/crypto-toolkit.git\ncd crypto-toolkit\npnpm install\npnpm build\nnode dist/scratch.js\n```\n\n---\n\n## ⚖️ License\n\n```text\nThis project is licensed under the terms of the MIT license.\n```\n","readmeFilename":"README.md"}