@faizahmed/secret-keystore 1.1.0 → 1.1.1

package/README.md

@@ -12,6 +12,15 @@ A secure secrets management library for Node.js applications using AWS KMS encry
 
 > **Design principle:** the only thing a developer ever handles is a **KMS Key ID** — which is *not* a secret. No private keys, no passphrases, no key material. AWS KMS holds all key material server-side and authorizes access via IAM, and decrypted values live **only in memory** (never in `process.env`, never on disk) to keep the blast radius of any RCE as small as possible.
 
+## Guides & Deep-Dives
+
+A full walkthrough lives on the blog, as part of the ***[Mastering Encryption](https://blog.faizahmed.in/series/encryption)*** series:
+
+- **[Encrypted .env for Node.js with AWS KMS: The Complete Guide](https://blog.faizahmed.in/encrypted-env-aws-kms-nodejs-complete-guide)** — the overview and map.
+- **[Your .env Is a Loaded Gun: A Saner Threat Model for Node.js Secrets](https://blog.faizahmed.in/nodejs-secrets-threat-model-aws-kms)** — why `process.env` is the problem.
+- **[Encrypt Your .env with One Command: The secret-keystore CLI](https://blog.faizahmed.in/secret-keystore-cli-encrypt-env-aws-kms)** — every CLI command, hands-on.
+- **[Loading Secrets at Runtime Without Leaking Them](https://blog.faizahmed.in/secret-keystore-runtime-config-loader-nodejs)** — `config()`, the keystore, rotation, and Nitro attestation.
+
 ## Table of Contents
 
 - [Features](#features)
@@ -201,7 +210,7 @@ npm pack
 # pnpm
 pnpm pack
 
-# This creates: faizahmedfarooqui-secret-keystore-1.0.0.tgz (scoped package name)
+# This creates: faizahmed-secret-keystore-1.1.1.tgz (scoped package name)
 ```
 
 Or use the provided script:
@@ -217,14 +226,14 @@ In your consumer project:
 
 ```bash
 # Copy the tarball to your project
-cp ../secret-keystore/faizahmedfarooqui-secret-keystore-1.0.0.tgz ./
+cp ../secret-keystore/faizahmed-secret-keystore-1.1.1.tgz ./
 
 # Install from tarball
 # npm
-npm install ./faizahmedfarooqui-secret-keystore-1.0.0.tgz
+npm install ./faizahmed-secret-keystore-1.1.1.tgz
 
 # pnpm
-pnpm add ./faizahmedfarooqui-secret-keystore-1.0.0.tgz
+pnpm add ./faizahmed-secret-keystore-1.1.1.tgz
 ```
 
 Or add a script to your consumer's `package.json`:
@@ -233,7 +242,7 @@ Or add a script to your consumer's `package.json`:
 {
   "scripts": {
     "pack:keystore": "cd ../secret-keystore && npm pack --pack-destination ../your-project",
-    "install:keystore": "npm run pack:keystore && npm install ./faizahmedfarooqui-secret-keystore-*.tgz"
+    "install:keystore": "npm run pack:keystore && npm install ./faizahmed-secret-keystore-*.tgz"
   }
 }
 ```
@@ -245,7 +254,7 @@ After installing, your `package.json` will reference the local tarball:
 ```json
 {
   "dependencies": {
-    "@faizahmed/secret-keystore": "file:./faizahmedfarooqui-secret-keystore-1.0.0.tgz"
+    "@faizahmed/secret-keystore": "file:./faizahmed-secret-keystore-1.1.1.tgz"
   }
 }
 ```
@@ -263,7 +272,7 @@ WORKDIR /app
 COPY package.json yarn.lock ./
 
 # Copy the local tarball (must be in the Docker build context)
-COPY faizahmedfarooqui-secret-keystore-1.0.0.tgz ./
+COPY faizahmed-secret-keystore-1.1.1.tgz ./
 
 # Install dependencies (tarball is referenced in package.json)
 RUN yarn install --frozen-lockfile
@@ -277,18 +286,18 @@ RUN yarn install --frozen-lockfile
 # 1. In the keystore library directory
 cd secret-keystore
 npm pack          # or: pnpm pack
-mv faizahmedfarooqui-secret-keystore-*.tgz ../your-consumer-project/
+mv faizahmed-secret-keystore-*.tgz ../your-consumer-project/
 
 # 2. In your consumer project
 cd ../your-consumer-project
 
 # Update package.json to reference the tarball
-# "dependencies": { "@faizahmed/secret-keystore": "file:./faizahmedfarooqui-secret-keystore-1.0.0.tgz" }
+# "dependencies": { "@faizahmed/secret-keystore": "file:./faizahmed-secret-keystore-1.1.1.tgz" }
 
 npm install       # or: pnpm install
 
 # 3. Commit the tarball to your repo (for CI/CD)
-git add faizahmedfarooqui-secret-keystore-*.tgz
+git add faizahmed-secret-keystore-*.tgz
 git commit -m "Add @faizahmed/secret-keystore tarball for Docker builds"
 ```
 
@@ -398,7 +407,7 @@ bootstrap();
 ## CLI Reference
 
 ```bash
-npx @faizahmed/secret-keystore <encrypt|decrypt> [options]
+npx @faizahmed/secret-keystore <command> [options]
 ```
 
 ### Commands

package/SECURITY.md

@@ -9,6 +9,7 @@ This document explains the security model of [`@faizahmed/secret-keystore`](http
 - [Overview](#overview)
 - [Threat Scenarios](#threat-scenarios)
 - [Security Layers](#security-layers)
+- [CLI Security Notes](#cli-security-notes)
 - [Security-First Dependency Policy](#security-first-dependency-policy)
 - [Nitro Enclave Attestation](#nitro-enclave-attestation)
   - [Full Attestation Flow](#full-attestation-flow)
@@ -79,7 +80,7 @@ Even with both:
 ```mermaid
 flowchart TB
     subgraph CONFIG["Config File"]
-        A["DB_PASSWORD=ENC[AQICAHh...encrypted...]"]
+        A["DB_PASSWORD=ENC#91;AQICAHh...encrypted...#93;"]
     end
 
     subgraph KMS["AWS KMS"]
@@ -122,6 +123,22 @@ flowchart TB
 - Accessible only via `keyStore.get()` API
 - Secure memory wipe on `destroy()`
 
+The zero-config **`config()`** loader follows the same rule. It discovers and cascades your `.env` files (`.env` → `.env.local` → `.env.<NODE_ENV>` → `.env.<NODE_ENV>.local`), decrypts them via KMS, and loads everything into the in-memory keystore it returns. Nothing decrypted is written to disk, and nothing is placed in `process.env`.
+
+> **⚠️ `populateProcessEnv` is a deliberate footgun.** `config({ populateProcessEnv: true })` copies decrypted values into `process.env` for drop-in `dotenv` compatibility. This **re-introduces the bulk-exposure blast radius this library exists to remove** — a single `env` dump or `/proc/[pid]/environ` read would leak everything. It is **off by default**, emits a runtime warning when enabled, and should be avoided in production. Prefer reading from the returned keystore via `.get()`.
+
+## CLI Security Notes
+
+The CLI commands keep the same blast-radius discipline, with a couple of deliberate, time-boxed exceptions worth understanding:
+
+| Command | Security note |
+|---------|---------------|
+| `encrypt` / `decrypt` | `decrypt` writes plaintext to disk (in place or `--output`). To *run* an app, prefer `run` or `config()` so plaintext never lands on disk. |
+| `run` | Decrypts and launches your command with secrets in the **child process's** environment. The parent never holds them — but code inside the child can read them via `env`, which is unavoidable for any process runner. Use `config()` if you can modify the app and want secrets to stay out of `process.env` entirely. |
+| `edit` | Decrypts into a `0600`-permission temp file, opens `$EDITOR`, re-encrypts on save, then overwrites and deletes (shreds) the temp file. Plaintext exists on disk only while the editor is open. |
+| `rotate` | Re-encrypts already-encrypted values under a new KMS Key ID (decrypting with the old key in a single pass). Plaintext is only ever held in memory. Use it after suspected key exposure. |
+| `keys` / `status` | Read-only inspection. They print key names and encrypted/plaintext status only — **never secret values** — so they're safe to use in CI and logs. |
+
 ## Security-First Dependency Policy
 
 > **Critical Decision:** This library intentionally avoids third-party dependencies for all security-sensitive operations.
@@ -468,6 +485,7 @@ const keyStore = await createSecretKeyStore(source, kmsKeyId, {
 | **Test Recovery** | Ensure you can recover if KMS access is lost |
 | **Document Key Policies** | Keep track of what each key policy allows |
 | **Rotate Secrets Regularly** | Re-encrypt with new values periodically |
+| **Rotate KMS Keys** | Use `rotate --old-kms-key-id=... --kms-key-id=...` to re-encrypt under a new key, especially after suspected exposure |
 
 ## Security Checklist
 
@@ -487,6 +505,7 @@ const keyStore = await createSecretKeyStore(source, kmsKeyId, {
 - [ ] Secure memory wipe enabled (default)
 - [ ] In-memory AES-256-GCM encryption enabled (default)
 - [ ] No secrets logged, even in debug mode
+- [ ] If using `config()`, `populateProcessEnv` left at its default (`false`) — secrets stay out of `process.env`
 
 ### Nitro Enclave Attestation (Maximum Security)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@faizahmed/secret-keystore",
-    "version": "1.1.0",
+    "version": "1.1.1",
     "description": "Secure secrets management with AWS KMS encryption, in-memory keystore, and Nitro Enclave attestation support",
     "main": "src/index.js",
     "types": "src/index.d.ts",