yamlock 0.3.0 → 1.0.0

package/examples/docs/ci-cd.md

@@ -0,0 +1,58 @@
+# CI/CD Example: locking configs before deployment
+
+This example shows how to decrypt configs for build-time use and re-encrypt
+them with the default authenticated v2 format before artifacts are published.
+It assumes `yamlock` is declared in the project's dependencies or
+devDependencies.
+
+```yaml
+# .github/workflows/deploy.yml
+name: deploy
+
+on: [push]
+
+permissions:
+  contents: read
+
+env:
+  YARN_VERSION: 1.22.22
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+          cache: yarn
+
+      - name: Use Yarn Classic
+        run: npm install --global "yarn@$YARN_VERSION"
+
+      - name: Install deps
+        run: yarn install --frozen-lockfile
+
+      - name: Decrypt configs for build
+        run: |
+          yarn yamlock decrypt config.yaml --key "$YAMLOCK_KEY"
+          yarn yamlock decrypt secrets.json --key "$YAMLOCK_KEY" --paths "db.password,api.token"
+        env:
+          YAMLOCK_KEY: ${{ secrets.YAMLOCK_KEY }}
+
+      - name: Build
+        run: yarn build
+
+      - name: Re-encrypt before pushing artifacts
+        run: |
+          yarn yamlock encrypt config.yaml --key "$YAMLOCK_KEY"
+          yarn yamlock encrypt secrets.json --key "$YAMLOCK_KEY" --paths "db.password,api.token"
+        env:
+          YAMLOCK_KEY: ${{ secrets.YAMLOCK_KEY }}
+```
+
+Adjust the paths/filenames as needed. Keeping encryption in the pipeline helps
+prevent accidental plaintext commits. Add `--legacy` only when a consumer has a
+temporary, documented requirement for v1 payloads.

package/examples/docs/key-rotation.md

@@ -0,0 +1,65 @@
+# Key Rotation Guidance
+
+This document explains how to rotate encryption keys without losing data or
+leaving plaintext in the working tree longer than necessary. V2 authenticates
+the field path and uses a separate random KDF salt for every value.
+
+## Recommended approach
+
+1. **Inventory encrypted files**  
+   Maintain a manifest (for example, a simple `yamlock.files` text file at the repo root) listing every YAML/JSON file that contains encrypted values, one path per line. Example:
+
+   ```txt
+   config.yaml
+   secrets.json
+   infra/prod/environment.yaml
+   ```
+
+   Reference this file in scripts so rotations stay consistent.
+
+2. **Create recoverable backups**
+   - Copy encrypted inputs to a protected location before changing them.
+   - Keep backup permissions at least as restrictive as the source files.
+   - Do not commit decrypted files, keys, or backup archives.
+
+3. **Export decrypted configs**
+   - Use `yamlock decrypt <file> --key <old-key>` for every file in the manifest.  
+   - Work in a protected temporary directory outside the repository. Do not use `git stash`: it stores plaintext in Git objects.
+
+4. **Set the new key**
+   - Generate a fresh key via `yamlock keygen` or your secret manager.  
+   - Update `YAMLOCK_KEY` in CI secrets, `.env` files, and deployment platforms. Keep the old key accessible until rotation completes.
+
+5. **Re-encrypt with the new key**
+   - Run `yamlock encrypt <file> --key <new-key>` for each file.  
+   - The default writer produces authenticated v2 payloads; do not add `--legacy` unless an older consumer explicitly requires v1.
+   - Validate using `yamlock decrypt ... --key <new-key>` to confirm round-trips.
+
+6. **Deploy carefully**
+   - Ship the updated configs only after all environments know about the new key.  
+   - Monitor for authentication failures, unsupported payload versions, and missing-key errors.
+
+7. **Retire the old key**
+   - Once every environment reads the re-encrypted configs, revoke the previous key from secret stores.
+
+## Automation snippet
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+FILES=(config.yaml secrets.json infra/cluster.yaml)
+
+for file in "${FILES[@]}"; do
+  yamlock decrypt "$file" --key "$OLD_KEY"
+  yamlock encrypt "$file" --key "$NEW_KEY"
+done
+```
+
+Run the script from CI to ensure consistency. Store `OLD_KEY` and `NEW_KEY` via environment secrets.
+
+## Tips
+
+- Keep encrypted backups in protected storage; never put plaintext backups in Git, including stashes.
+- Keep temporary plaintext outside the repository and remove it after verified re-encryption.
+- Audit diffs before committing: only encrypted blobs should change.

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "yamlock",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "author": "PAVEL TKACHEV (phoenixweiss) <mail@phoenixweiss.me>",
   "description": "Value-level encryption for YAML/JSON configuration files with CLI + Node.js APIs.",
   "license": "MIT",
   "type": "module",
+  "packageManager": "yarn@1.22.22",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./package.json": "./package.json"
@@ -18,6 +21,8 @@
   "files": [
     "dist",
     "bin",
+    "docs",
+    "examples",
     "README.md",
     "LICENSE"
   ],
@@ -33,10 +38,15 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "rimraf dist && cp -R src dist",
+    "build": "rimraf dist && mkdir -p dist && cp -R src/* dist/",
+    "check:docs": "node scripts/check-docs.js",
+    "check:release": "node scripts/release-check.js",
     "lint": "eslint .",
     "prepare": "yarn run build",
-    "test": "node --test"
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='src/**/*.js' --test-coverage-lines=90 --test-coverage-branches=80 --test-coverage-functions=95",
+    "test:types": "yarn run build && tsc --project test/types/tsconfig.json",
+    "test:package": "yarn run build && node scripts/package-smoke.js"
   },
   "repository": {
     "type": "git",
@@ -47,12 +57,14 @@
   },
   "homepage": "https://github.com/phoenixweiss/yamlock#readme",
   "dependencies": {
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.3.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
-    "eslint": "^9.0.0",
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.39.5",
     "globals": "^15.0.0",
-    "rimraf": "^5.0.5"
+    "rimraf": "^5.0.5",
+    "typescript": "^5.9.2"
   }
 }