{"_id":"@byronzeet/amava-crypto","_rev":"9-8f2f0afc4274d85bab2d6ea8d4c22bfd","name":"@byronzeet/amava-crypto","dist-tags":{"latest":"0.3.1"},"versions":{"0.2.0":{"name":"@byronzeet/amava-crypto","version":"0.2.0","keywords":["encryption","aws-kms","soc2","batch-processing","performance","caching","security"],"author":{"name":"Zeet Agency"},"license":"MIT","_id":"@byronzeet/amava-crypto@0.2.0","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"9dd888a4aaa880275ad11b4cd1a13a42233d2e26","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.2.0.tgz","fileCount":7,"integrity":"sha512-rFp68037MfFopId1MrDJ2bbFT69uSDxBNqdEW7LdTnXqlRXHCraHKXfAnjSw5XlawhOweTjfy1XO9eaStNQeWQ==","signatures":[{"sig":"MEUCIQDPhtktQnLtFB5v41ZfDLAavZMhkU8kWeJUCqwefg/2EwIgad7iqqggC1xMvxIWhTKy8nCk6vVTvZIMo/B6+XdNSOM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74631},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"08c8f7f918ab2701e9b1d404c00f89a6e4ab8627","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","benchmark":"tsx src/run-benchmark.ts","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"11.3.0","description":"High-performance SOC2-compliant encryption library with AWS KMS integration, batch processing, and intelligent caching","directories":{},"_nodeVersion":"24.2.0","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.2.0_1757072260387_0.8486078062956763","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@byronzeet/amava-crypto","version":"0.2.1","keywords":["encryption","aws-kms","soc2","batch-processing","performance","caching","security"],"author":{"name":"Zeet Agency"},"license":"MIT","_id":"@byronzeet/amava-crypto@0.2.1","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"90456b30079cd74b263eee48e1355274bcd62d91","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.2.1.tgz","fileCount":7,"integrity":"sha512-93KBWDJhdn+pCTMMPLC3ZQoaNijBS3WzXQVOuV7Gre1RSaSI10nO0rtBqKpT1IoNbZKKdRpqLyNWpZ/Ml+UHtA==","signatures":[{"sig":"MEUCIQCKoQYwfg0hvza6C05WkcK+mXJMu/WOV/YsVU7v1SrYqwIgUSgGbaXExljaBaCBupBqyLWzdyx2yRVtvRcebo/hU0M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":80647},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"92490e8e119f40dd64fc741ea9f61a76a2682bd2","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","benchmark":"tsx src/run-benchmark.ts","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"11.3.0","description":"High-performance SOC2-compliant encryption library with AWS KMS integration, batch processing, and intelligent caching","directories":{},"_nodeVersion":"24.2.0","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.2.1_1757205035743_0.4474076969781915","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@byronzeet/amava-crypto","version":"0.2.2","keywords":["encryption","aws-kms","soc2","batch-processing","performance","caching","security"],"author":{"name":"Zeet Agency"},"license":"MIT","_id":"@byronzeet/amava-crypto@0.2.2","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"5e05dbac378fff20dadabc6376a9637a8a817976","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.2.2.tgz","fileCount":7,"integrity":"sha512-2AontQq3Ov6Ohv55B71Oa/G0hVwvBkMMQq8TiU1Yb7JWD5neX4mHskrFBu8efYV5i54OIZetymP72R59SL/74g==","signatures":[{"sig":"MEQCHw1u5nyF/sKFq505shK3t2SFICzNygAw7u40ffA+EOYCIQDrn3Njb6y2LegNK9b70TbE72RzK1BOKiCJMiIAFgUGMw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":80647},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"87a80feb5e8cb0d1d0f72a9e22d629ce264b1ed8","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","benchmark":"tsx src/run-benchmark.ts","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"11.3.0","description":"High-performance SOC2-compliant encryption library with AWS KMS integration, batch processing, and intelligent caching","directories":{},"_nodeVersion":"24.2.0","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.2.2_1757216949815_0.2267769818176384","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"name":"@byronzeet/amava-crypto","version":"0.2.3","_id":"@byronzeet/amava-crypto@0.2.3","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"080f3abe03fb141338fad780e5cf7facaf141573","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.2.3.tgz","fileCount":12,"integrity":"sha512-a7PJjI+x0ZWLlBkENO7ic1xp7bTRrSVn94Gv7oNRGldNYly4AIUgv5PMxD2frnPVKdBIJPTazEr36oEf1mtsuA==","signatures":[{"sig":"MEUCID9iQYTNL7QgL1W9cOp+pI0rj/yOZvqmbfcaSn1aT931AiEAl1Rqra2zKUItQr+jy/R3gXdL082zHUQbabt36xm+U0c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":88201},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"229f2ddc93ab5ed7534da83d80dc2818dfd0ad4b","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"11.6.2","directories":{},"_nodeVersion":"25.2.1","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.2.3_1765187079834_0.013671798986060413","host":"s3://npm-registry-packages-npm-production"}},"0.2.4":{"name":"@byronzeet/amava-crypto","version":"0.2.4","_id":"@byronzeet/amava-crypto@0.2.4","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"cbf2d7a094f171c63f2e71d85c352dc127cfd84e","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.2.4.tgz","fileCount":12,"integrity":"sha512-UJ3Gpcfm+Lc4F673IPb3SCLCz/7qxPZ8gj1VzcFfOITw+W+KJkyMx9KdXOrh29q5TQkcXSzkXyFyunA10DsAyg==","signatures":[{"sig":"MEYCIQCZcLSFVOQdTbyyuhF2wJxYN6TCmwJnrc1FDIcXNXqSnQIhAPMf3LbL+XLxJWp2vxPIXvBWibm56oDD3wPo5qXdpoJn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":94462},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"229f2ddc93ab5ed7534da83d80dc2818dfd0ad4b","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"11.6.2","directories":{},"_nodeVersion":"25.2.1","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.2.4_1765187296014_0.6207080836644161","host":"s3://npm-registry-packages-npm-production"}},"0.2.7":{"name":"@byronzeet/amava-crypto","version":"0.2.7","_id":"@byronzeet/amava-crypto@0.2.7","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"326bac42ab25fa5691076d53c33609085f1efbce","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.2.7.tgz","fileCount":12,"integrity":"sha512-5Pyut1VkcelWsjpgKc+kzbxW1jLWLlXZfeZ2TXO4somlLBMOZK3UHgOHyMUXJg0q0tfRza3RPcDqEccqnGB+eQ==","signatures":[{"sig":"MEUCIQCCnkEmNzWq/+p1AKq6AiMamsrDZ5UTPgSc+XucmqlfCgIgPcErXG/ckA5pYsDCjd/38soDVUjiPWp2k8Rh3DEXxfk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":96024},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"229f2ddc93ab5ed7534da83d80dc2818dfd0ad4b","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"11.6.2","directories":{},"_nodeVersion":"25.2.1","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.2.7_1765282766020_0.5452680982212701","host":"s3://npm-registry-packages-npm-production"}},"0.2.8":{"name":"@byronzeet/amava-crypto","version":"0.2.8","_id":"@byronzeet/amava-crypto@0.2.8","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"9f13f9e8c5470cc3a19521628865f144996a56cf","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.2.8.tgz","fileCount":12,"integrity":"sha512-s0U9uBretGHqZ9ecN2U6V+GXc5JIcTEeRs7EiLMaFO5HjBUsu+8iaCE6V2KXFB9ZJP0ljj64JAnMmNNflisJ5w==","signatures":[{"sig":"MEUCIQCNYNBa6hU88+8+0enpLwlFb/kAesfhJqZ3nkhlprnRHQIgE/eDqWh8+k96ZK8COq9/aRSC1Dgs3dpkVg1Xw5vus/o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":153771},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"ac149dc3fe49704d6a9809acdbe0da77d8cf1e0c","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"11.6.2","directories":{},"_nodeVersion":"25.2.1","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.2.8_1765352861726_0.550359403935329","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@byronzeet/amava-crypto","version":"0.3.0","keywords":["encryption","aws-kms","soc2","batch-processing","performance","caching","security"],"author":{"name":"Zeet Agency"},"license":"MIT","_id":"@byronzeet/amava-crypto@0.3.0","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"homepage":"https://github.com/zeet-agency/amava-crypto#readme","bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"dist":{"shasum":"22e8e456542238f088de7de8581b1a2b5f45692c","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.3.0.tgz","fileCount":7,"integrity":"sha512-04ZCedHkXd/oXZtoVdPSBXGsrgMerBRsINt3eFYR9pRGIobi3TYmfnKZDogWG114T52BcIzhgk0jbeN4orp5Xg==","signatures":[{"sig":"MEUCIQC2/e+lqcTFzJNw2S8uzaRDe0g/adiHVySAfncq6UL1gwIgTBmDvdNCY99Rzvqdxl3gdk3XGj4PqKavTuRkxmJG2hs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":85185},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"31634e2a8a7ec9553e3ec4ae982f3a7c8c5f9b23","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","benchmark":"tsx src/run-benchmark.ts","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"repository":{"url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git","type":"git"},"_npmVersion":"10.9.4","description":"High-performance SOC2-compliant encryption library with AWS KMS integration, batch processing, and intelligent caching","directories":{},"_nodeVersion":"22.21.1","dependencies":{"@aws-sdk/client-kms":"^3.637.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","vitest":"^1.6.0","typescript":"^5.4.5","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/amava-crypto_0.3.0_1786008961210_0.5981889717747382","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@byronzeet/amava-crypto","version":"0.3.1","description":"High-performance SOC2-compliant encryption library with AWS KMS integration, batch processing, and intelligent caching","type":"module","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","benchmark":"tsx src/run-benchmark.ts","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build && npm test"},"keywords":["encryption","aws-kms","soc2","batch-processing","performance","caching","security"],"author":{"name":"Zeet Agency"},"license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git"},"bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"homepage":"https://github.com/zeet-agency/amava-crypto#readme","dependencies":{"@aws-sdk/client-kms":"^3.1127.0"},"devDependencies":{"@types/node":"^22.18.0","tsx":"^4.23.13","typescript":"^5.9.3","vitest":"^4.0.18"},"_id":"@byronzeet/amava-crypto@0.3.1","gitHead":"da575a85f6f948aa8730ba0ffccffd87c74bb4a8","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-YkDH3hMiPw7KGc5dKHPh/dYeZEJbflV2OjI/OESb5WESOze76OH4sdRLHIeT+ldOLHYzB+cn+lcLjSakBrQd/A==","shasum":"60ff2d3f5f05b51097ead56e1f117557847a1903","tarball":"https://registry.npmjs.org/@byronzeet/amava-crypto/-/amava-crypto-0.3.1.tgz","fileCount":7,"unpackedSize":85600,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGiEsENaQaSoZJ2V9NmUxovfQLxJZYhw7LtXc8cyddsHAiB+9ViNGooAZxeFSYo+eoSToREHc82PzbkST6lhHnKrgA=="}]},"_npmUser":{"name":"byronzeet","email":"byron@zeet.agency"},"directories":{},"maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/amava-crypto_0.3.1_1788931216970_0.9541625321676415"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-05T11:37:40.312Z","modified":"2026-09-09T05:20:17.258Z","0.2.0":"2025-09-05T11:37:40.580Z","0.2.1":"2025-09-07T00:30:35.925Z","0.2.2":"2025-09-07T03:49:10.011Z","0.2.3":"2025-12-08T09:44:40.002Z","0.2.4":"2025-12-08T09:48:16.157Z","0.2.7":"2025-12-09T12:19:26.166Z","0.2.8":"2025-12-10T07:47:41.895Z","0.3.0":"2026-08-06T09:36:01.357Z","0.3.1":"2026-09-09T05:20:17.099Z"},"bugs":{"url":"https://github.com/zeet-agency/amava-crypto/issues"},"author":{"name":"Zeet Agency"},"license":"MIT","homepage":"https://github.com/zeet-agency/amava-crypto#readme","keywords":["encryption","aws-kms","soc2","batch-processing","performance","caching","security"],"repository":{"type":"git","url":"git+ssh://git@github.com/zeet-agency/amava-crypto.git"},"description":"High-performance SOC2-compliant encryption library with AWS KMS integration, batch processing, and intelligent caching","maintainers":[{"name":"byronzeet","email":"byron@zeet.agency"}],"readme":"# @byronzeet/amava-crypto\n\nHigh-performance SOC2-compliant encryption library with AWS KMS integration, batch processing, and intelligent caching.\n\n## Features\n\n- 🔐 **SOC2 Compliant Encryption**: AES-GCM envelope encryption with AWS KMS\n- ⚡ **Batch Processing**: Up to 70% performance improvement with batch decryption\n- 🚀 **Intelligent Caching**: Multi-tier data key caching with automatic warming\n- 📊 **Performance Monitoring**: Built-in benchmarking and metrics collection\n- 🔄 **Deterministic Hashing**: Consistent hash generation for encrypted data\n- 🛡️ **Type Safety**: Full TypeScript support with comprehensive type definitions\n\n## Performance Improvements\n\nBased on comprehensive benchmarking, this library delivers:\n\n- **37.6% average speed improvement** with batch processing\n- **67.3% reduction in AWS KMS calls** through intelligent caching\n- **60.9% efficiency gain** in high-volume operations\n\n## Installation\n\n```bash\nnpm install @byronzeet/amava-crypto\n```\n\n## Quick Start\n\n### Basic Usage\n\n```typescript\nimport { AmavaCrypto } from '@byronzeet/amava-crypto';\n\nconst crypto = new AmavaCrypto({\n  region: 'us-east-1',\n  keyId: 'your-kms-key-id'\n});\n\n// Encrypt text\nconst encrypted = await crypto.encryptText('sensitive data', {\n  tenantId: 'property-uuid',\n  table: 'users',\n  column: 'email',\n  rowId: '123'\n});\n\n// Decrypt text\nconst decrypted = await crypto.decryptText(encrypted.ciphertext, {\n  tenantId: 'property-uuid',\n  table: 'users',\n  column: 'email',\n  rowId: '123'\n});\n```\n\n### The canonical encryption context\n\nEvery encryption call MUST pass the full canonical context — `{tenantId, table,\ncolumn, rowId}` with non-empty values. Encryption throws if any of the four is\nmissing, `undefined`, `null`, or empty; there is no way to mint ciphertext with\nan incomplete binding.\n\nKey **order** in your object literal does not matter: the library serializes\nthe context in a fixed canonical order before using it as AAD, so\n`{rowId, table, column, tenantId}` and `{tenantId, table, column, rowId}`\nproduce identical envelopes. Decryption applies the same normalization and has\n**no completeness guard** — it accepts whatever context shape reproduces the\nstored AAD, which keeps envelopes written by older library versions readable.\n\nThere is deliberately no API that decrypts without a caller-supplied context.\nThe AAD binding is the integrity guarantee; see `docs/adr/0001` for rationale.\n\n### Batch Processing (Recommended for High Performance)\n\n```typescript\nimport { BatchDecryptItem } from '@byronzeet/amava-crypto';\n\nconst items: BatchDecryptItem[] = [\n  {\n    ciphertext: 'encrypted_data_1',\n    context: { tenantId: 'property-uuid', table: 'users', column: 'email', rowId: '1' }\n  },\n  {\n    ciphertext: 'encrypted_data_2', \n    context: { tenantId: 'property-uuid', table: 'users', column: 'email', rowId: '2' }\n  }\n  // ... more items\n];\n\nconst result = await crypto.decryptBatch(items, {\n  concurrencyPerGroup: 10,\n  collectMetrics: true\n});\n\nconsole.log(`Processed ${result.metrics.successCount} items`);\nconsole.log(`KMS calls: ${result.metrics.kmsCallCount}`);\nconsole.log(`Cache hits: ${result.metrics.cacheHitCount}`);\n```\n\n### Cache Management\n\n```typescript\n// Warm cache with frequently used keys\nawait crypto.warmCache(['key1', 'key2', 'key3'], {\n  concurrency: 5,\n  priority: 'frequency'\n});\n\n// Configure tiered TTL for optimal performance\ncrypto.configureTieredTtl({\n  frequentAccessTtl: 600000,    // 10 minutes for frequent keys\n  recentAccessTtl: 300000,      // 5 minutes for recent keys\n  standardTtl: 180000,          // 3 minutes for standard keys\n  frequentAccessThreshold: 5,   // 5+ hits = frequent\n  recentAccessThreshold: 60000  // 1 minute = recent\n});\n\n// Get cache statistics\nconst stats = crypto.getCacheStats();\nconsole.log(`Local cache: ${stats.local.size}/${stats.local.maxSize}`);\nconsole.log(`Shared cache: ${stats.shared.size}/${stats.shared.maxSize}`);\n```\n\n## Configuration Options\n\n### AmavaCrypto Constructor\n\n```typescript\ninterface AmavaCryptoConfig {\n  region: string;                    // AWS region\n  keyId: string;                     // KMS key ID\n  kmsClient?: KMSClient;            // Optional custom KMS client\n  useSharedCache?: boolean;         // Enable shared caching (default: true)\n  dataKeyCacheTtlMs?: number;       // Cache TTL in ms (default: 300000)\n  hooks?: CryptoHooks;              // Event hooks for monitoring\n}\n```\n\n### Batch Processing Options\n\n```typescript\ninterface BatchDecryptOptions {\n  concurrencyPerGroup?: number;     // Parallel operations per key group\n  failFast?: boolean;               // Stop on first error\n  collectMetrics?: boolean;         // Gather performance metrics\n}\n```\n\n## Performance Benchmarking\n\nRun performance benchmarks to measure improvements:\n\n```bash\nnpm run benchmark\n```\n\nThis generates a detailed report showing:\n- Speed improvements vs individual operations\n- KMS call reduction percentages\n- Cache hit rates and efficiency gains\n- Scaling benefits with larger datasets\n\n## API Reference\n\n### Core Methods\n\n#### `encryptText(plaintext: string, context: EncryptionContext): Promise<EncryptionResult>`\nEncrypts text with the provided context.\n\n#### `decryptText(ciphertext: string, context: EncryptionContext): Promise<string>`\nDecrypts text with the provided context.\n\n#### `decryptBatch(items: BatchDecryptItem[], options?: BatchDecryptOptions): Promise<BatchDecryptResult>`\nEfficiently decrypts multiple items in batches.\n\n#### `generateDeterministicHash(data: string): string`\nGenerates a consistent hash for the given data.\n\n### Cache Management\n\n#### `warmCache(keys: string[], options?: CacheWarmingOptions): Promise<CacheWarmResult>`\nProactively loads data keys into cache.\n\n#### `intelligentCacheWarmup(tierConfig?: CacheTierConfig): Promise<IntelligentWarmupResult>`\nAutomatically warms cache based on usage patterns.\n\n#### `getCacheStats(): CacheStats`\nReturns current cache statistics.\n\n#### `clearCache(): void`\nClears all cached data keys.\n\n### Configuration\n\n#### `configureTieredTtl(config: CacheTierConfig): void`\nSets up tiered TTL for different access patterns.\n\n## Types\n\n### Core Types\n\n```typescript\ninterface EncryptionContext {\n  tenantId?: string; // REQUIRED for encryption (guard-enforced); optional in the type only so decryption can reproduce legacy stored AADs\n  table: string;\n  column: string;\n  rowId?: string;    // REQUIRED for encryption (guard-enforced), same caveat\n}\n\ninterface EncryptionResult {\n  ciphertext: string;\n  hash: string;\n}\n\ninterface BatchDecryptItem {\n  ciphertext: string;\n  context: EncryptionContext;\n}\n\ninterface BatchDecryptResult {\n  results: Map<number, string>;\n  errors: Map<number, Error>;\n  metrics: BatchDecryptMetrics;\n}\n```\n\n### Performance Types\n\n```typescript\ninterface BatchDecryptMetrics {\n  totalDuration: number;\n  successCount: number;\n  errorCount: number;\n  keyGroupCount: number;\n  kmsCallCount: number;\n  cacheHitCount: number;\n}\n\ninterface CacheStats {\n  local: {\n    size: number;\n    maxSize: number;\n    hitRate: number;\n  };\n  shared: {\n    size: number;\n    maxSize: number;\n    hitRate: number;\n  };\n}\n```\n\n## Best Practices\n\n### 1. Use Batch Processing for Multiple Items\n```typescript\n// ❌ Inefficient - individual calls\nfor (const item of items) {\n  await crypto.decryptText(item.ciphertext, item.context);\n}\n\n// ✅ Efficient - batch processing\nconst result = await crypto.decryptBatch(items);\n```\n\n### 2. Enable Shared Caching\n```typescript\n// ✅ Recommended configuration\nconst crypto = new AmavaCrypto({\n  region: 'us-east-1',\n  keyId: 'your-key-id',\n  useSharedCache: true,        // Share cache across instances\n  dataKeyCacheTtlMs: 300000    // 5 minute TTL\n});\n```\n\n### 3. Warm Cache for Predictable Workloads\n```typescript\n// ✅ Warm cache during application startup\nconst frequentKeys = await getFrequentlyUsedKeys();\nawait crypto.warmCache(frequentKeys, {\n  concurrency: 10,\n  priority: 'frequency'\n});\n```\n\n### 4. Monitor Performance\n```typescript\n// ✅ Collect metrics for optimization\nconst result = await crypto.decryptBatch(items, {\n  collectMetrics: true\n});\n\nif (result.metrics.cacheHitCount / items.length < 0.5) {\n  console.warn('Low cache hit rate - consider cache warming');\n}\n```\n\n## Migration from v0.1.x\n\n### Breaking Changes\n- `decryptBatch` now returns a `BatchDecryptResult` object instead of an array\n- Cache configuration moved to constructor options\n- Some internal method signatures changed\n\n### Migration Steps\n\n1. **Update batch processing calls:**\n```typescript\n// v0.1.x\nconst results = await crypto.decryptBatch(items);\n\n// v0.2.0\nconst { results, metrics } = await crypto.decryptBatch(items);\n```\n\n2. **Update cache configuration:**\n```typescript\n// v0.1.x\ncrypto.setCacheTtl(300000);\n\n// v0.2.0\nconst crypto = new AmavaCrypto({\n  // ... other options\n  dataKeyCacheTtlMs: 300000\n});\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Run `npm test` and `npm run benchmark`\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: [Create an issue](https://github.com/zeet-agency/amava-crypto/issues)\n- Email: support@zeet.agency\n\n---\n\n**Performance tested and optimized for production workloads** 🚀\n","readmeFilename":"README.md"}