yamlock 0.3.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,205 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. Release versions are finalized in dedicated commits and use matching numeric Git tags.
+
+## [Unreleased]
+
+## [1.1.0] - 2026-08-14
+
+### Added
+- Tag-gated GitHub Release automation that reuses the full CI matrix, validates the tag against `main`, derives notes from the matching changelog section, verifies a draft, and publishes the release as latest.
+- Structural `pathPatterns` / `--path-patterns` selectors for `processConfig` and CLI encrypt/decrypt/migrate workflows, with whole-segment `*`, `[*]`, and `**` matching, exact-path authentication, and fail-closed validation without reinterpreting existing `paths`.
+
+## [1.0.0] - 2026-08-11
+
+### Added
+- Authenticated payload v2 for the Node.js API, using AES-256-GCM, scrypt, strict parsing, and authenticated field-path metadata.
+- Frozen legacy payload fixtures and v2 regression tests for deterministic vectors, tampering, malformed input, mixed-format configs, and resource limits.
+- Payload v2 design documentation covering the threat model, serialized format, compatibility, and staged migration.
+- Safe `yamlock migrate` workflow with dry-run summaries, selective paths, mixed-format validation, explicit backups, separate outputs, and atomic permission-preserving writes.
+- Explicit CLI legacy-write compatibility through `yamlock encrypt --legacy`; custom encryption algorithms require this mode.
+- Strict repeated-encryption checks through CLI `--error-on-encrypted` and Node.js `existingPayloadPolicy: 'error'`.
+- Explicit `--force-encrypt` / `existingPayloadPolicy: 'encrypt'` handling for intentional `yl|...` plaintext or nested encryption.
+- YAML rewrite documentation and regression coverage for comments, formatting, anchors, aliases, merge keys, and explicit/custom tags.
+- Public `serializePath(segments)` helper for constructing canonical field paths without string ambiguity.
+- Edge-case regression coverage for empty containers, sparse arrays, special and Unicode keys, empty strings, and large values.
+- Automated npm tarball smoke coverage for package contents, public API imports, and the installed distribution-first CLI.
+- Stable public Node.js error classes and `ERR_*` codes for validation, payload, authentication, legacy decryption, and config-processing failures.
+- Bundled TypeScript declarations and a documented `1.x` stability contract for the public Node.js API.
+- Built-in coverage thresholds plus automated Markdown-link and release-metadata checks.
+- Packaged runnable API and CI/CD examples with regression coverage against the installed distribution.
+- Conventional `help`, `-h`, and `--help` CLI entry points with installed-package smoke coverage.
+- Tracked Bumpster configuration, synchronized `VERSION` metadata, and a pre-bump release gate.
+
+### Changed
+- Updated `js-yaml` to 4.3.1 to address merge-key, alias, and ordered-map denial-of-service advisories; refreshed ESLint 9 tooling within the existing major version.
+- Package builds now exclude ignored local dotfiles, and tarball smoke checks recursively for local workflow artifacts.
+- CI now covers supported Node.js releases on Linux and macOS, uses current Node 24-based GitHub Actions, and performs a tag-gated package preflight.
+- Development and dependency updates now target `dev`; Bumpster releases atomically synchronize `dev`, `main`, and `vX.Y.Z` tags.
+- `encryptValue`, `processConfig`, and `yamlock encrypt` now write authenticated v2 payloads by default.
+- `decryptValue` and `processConfig` continue to auto-detect and read both legacy and v2 payloads; API callers can request legacy writing explicitly with `formatVersion: 1` or legacy algorithm options.
+- Repeated `processConfig`/CLI encryption now authenticates and preserves existing payloads instead of adding another encryption layer; fully encrypted in-place inputs are not rewritten.
+- CLI argument parsing now rejects unknown or duplicate options, missing values, extra positional arguments, and options that do not belong to the selected command before reading input files; `keygen --length` accepts only integers from 1 to 4096 bytes.
+- CLI integration tests now force an explicit source mode through the real `bin/yamlock` launcher, preventing stale local `dist` output from masking source changes while preserving distribution-first behavior for normal runs.
+- `processConfig` now validates non-string policies, path options, serializer output, collisions, and circular structures; opaque values are preserved by `ignore`, while `stringify` fails closed for values that cannot be converted without type loss.
+- Selective processing applies non-string policies only to selected leaves, and YAML timestamp values are no longer collapsed into empty objects during CLI traversal.
+- Normal CLI encrypt/decrypt writes now use the shared atomic temporary-file writer, verify that the source did not change after reading, preserve source or existing-output modes, reject symbolic-link paths, and clean up temporary files after failures.
+- CLI help now warns that YAML presentation details are normalized during writes and points users toward `--dry-run` or `--output` workflows.
+- YAML and JSON parse failures now report sanitized diagnostics without echoing source lines that may contain secrets.
+- Default field paths now escape reserved characters in object keys, CLI path lists understand escaped commas, and existing payloads with legacy ambiguous paths remain readable.
+- Config processing and migration now preserve sparse-array length and holes; `processConfig` also retains null prototypes and own keys such as `__proto__` without prototype assignment.
+
+## [0.3.0] - 2025-12-01
+### Added
+- `processConfig` non-string policies (`ignore`, `stringify`, `error`) and optional `pathSerializer` hook.
+- Unit tests demonstrating the new policies.
+
+### Changed
+- README highlights non-string handling in the advanced usage section.
+
+## [0.2.10] - 2025-12-01
+### Added
+- README example demonstrating the `--dry-run` workflow (with sample diff output).
+
+### Changed
+- Package version bumped to keep documentation in sync.
+
+## [0.2.9] - 2025-12-01
+### Added
+- CLI `--dry-run` flag prints the diff without touching files.
+- Structured error codes (e.g., `[yamlock:ERR_MISSING_KEY]`) for machine-readable failure handling.
+- Integration tests covering dry-run and the new error format.
+
+### Changed
+- README documents the `--dry-run` flag and behavior.
+
+## [0.2.8] - 2025-12-01
+### Added
+- Advanced usage docs: selective path tips, CI/CD workflow example (`examples/docs/ci-cd.md`), and an expanded key-rotation guide with scripting advice.
+- README now links to the new docs and highlights selective encryption in a dedicated section.
+
+### Changed
+- Package version bumped to keep documentation in sync.
+
+## [0.2.7] - 2025-12-01
+### Added
+- README badges for npm version and Node test status, plus a release information section summarizing install options.
+
+### Changed
+- Package version bumped to keep documentation in sync.
+
+## [0.2.6] - 2025-11-28
+### Added
+- Unit tests covering `processConfig` path filters and CLI integration tests for custom algorithms/decrypt paths.
+
+### Changed
+- README/CLI behavior unchanged.
+
+## [0.2.5] - 2025-11-28
+### Added
+- `yamlock algorithms` now distinguishes between tested presets and other OpenSSL-provided ciphers.
+- Integration tests updated to confirm the new output format.
+
+### Changed
+- README notes that the algorithms command shows both tested and additional cipher lists.
+
+## [0.2.4] - 2025-11-28
+### Added
+- `yamlock keygen` command generates random keys with configurable length and format, including guidance on storing them.
+- Integration tests covering key generation.
+
+### Changed
+- README documents the key generator usage.
+
+## [0.2.3] - 2025-11-27
+### Added
+- `yamlock version` command prints the installed CLI version.
+- `yamlock algorithms` lists all ciphers available in the current runtime.
+- Integration tests cover the new commands.
+
+### Changed
+- CLI help and README highlight the new commands.
+- Moved shared fixtures under `fixtures/` so the test runner skips them as standalone suites.
+
+## [0.2.2] - 2025-11-27
+### Added
+- CLI support for `--paths` (partial encryption/decryption) and `--output` (separate destination files).
+- `processConfig` now accepts targeted path lists so API/CLI share the same behavior.
+
+### Changed
+- README documents the new CLI options with examples.
+
+## [0.2.1] - 2025-11-26
+### Changed
+- Unified unit tests around shared fixtures/helpers to remove duplication and ensure every supported algorithm is exercised consistently.
+
+## [0.2.0] - 2025-11-26
+### Added
+- Algorithm presets with override support (e.g., `chacha20-poly1305` with auth tags, configurable key/IV lengths).
+- API support for passing algorithm options through `encryptValue`, `decryptValue`, and `processConfig`.
+- Additional unit coverage for presets and algorithm-aware config processing.
+
+## [0.1.2] - 2025-11-26
+### Fixed
+- CLI binary now falls back to the source entry during development, ensuring `yamlock` works when installed globally or run via `node bin/yamlock`.
+- Integration tests call the published bin, catching future regressions.
+
+## [0.1.1] - 2025-11-26
+### Added
+- Key rotation guide under `docs/key-rotation.md` and README link.
+- Documented CLI exit codes and reference to the example script.
+
+## [0.1.0] - 2025-11-26
+### Added
+- Example script under `examples/basic.js` demonstrating encrypt/decrypt flows.
+- GitHub Actions CI workflow to lint, test, and build on pushes/PRs.
+- README now links to the example script.
+
+## [0.0.10] - 2025-11-26
+### Added
+- Expanded README with usage examples, encrypted format description, and contributing link.
+- CONTRIBUTING guide plus GitHub issue and pull request templates.
+
+## [0.0.9] - 2025-11-26
+### Added
+- CLI now auto-detects YAML vs JSON, loads via js-yaml, and writes back preserving the original format.
+- Integration tests covering YAML encrypt/decrypt flows.
+
+## [0.0.8] - 2025-11-26
+### Added
+- CLI skeleton capable of encrypting/decrypting JSON files with `--key` and `--algorithm` options.
+- Integration tests covering CLI encrypt/decrypt flows and key validation.
+
+## [0.0.7] - 2025-11-26
+### Added
+- Public API exports for `encryptValue`, `decryptValue`, `processConfig`, and `getSupportedAlgorithms`.
+- Unit tests ensuring the API surface is available and round-trips data correctly.
+
+## [0.0.6] - 2025-11-25
+### Added
+- `processConfig` helper to walk objects/arrays and encrypt or decrypt every string value based on field paths.
+- Unit tests covering nested traversal, arrays, round-trips, and validation errors.
+
+## [0.0.5] - 2025-11-25
+### Added
+- Field path utilities that serialize nested object/array locations (`src/utils/path.js`).
+- Unit tests covering dot/bracket formatting and invalid input handling.
+
+## [0.0.4] - 2025-11-25
+### Added
+- `decryptValue` support with field-path validation and yamlock payload parsing.
+- Unit tests for decrypt flow, mismatch handling, and invalid payload detection.
+
+## [0.0.3] - 2025-11-24
+### Added
+- `encryptValue` function that encrypts string fields with per-path salts and random IVs.
+- Unit tests covering payload structure, IV randomness, and validation checks.
+
+## [0.0.2] - 2025-11-24
+### Added
+- Crypto utility helpers for key derivation, IV generation, salt encoding, and payload formatting/parsing.
+- Unit tests covering the utility layer and yamlock payload parsing.
+
+## [0.0.1] - 2025-11-24
+### Added
+- Initial project scaffold: package metadata, README baseline, ESLint config, CLI stub, and directory structure.

package/README.md

@@ -5,7 +5,7 @@
 ```
 
 [![npm version](https://img.shields.io/npm/v/yamlock)](https://www.npmjs.com/package/yamlock)
-[![Tests](https://img.shields.io/badge/tests-node--test-green)](https://github.com/phoenixweiss/yamlock/actions)
+[![CI](https://github.com/phoenixweiss/yamlock/actions/workflows/ci.yml/badge.svg)](https://github.com/phoenixweiss/yamlock/actions/workflows/ci.yml)
 
 # yamlock
 
@@ -13,8 +13,10 @@ Value-level encryption for YAML and JSON configuration files. The name **yamlock
 
 ## Requirements
 
-- Node.js 22.x via `asdf`
-- Yarn Classic (1.x)
+- Node.js 22 or newer
+
+The package works with npm or another Node.js package manager. This repository
+uses Yarn Classic 1.22.22 for development and release checks.
 
 ## Installation
 
@@ -34,9 +36,11 @@ yarn add yamlock            # project dependency
 
 ## Features
 
-- Encrypt/decrypt individual configuration values with deterministic field-path salts.
+- Encrypt/decrypt individual values with authenticated field-path metadata.
 - CLI workflow that processes YAML or JSON files in place.
+- Safe CLI migration from legacy payloads to authenticated v2 payloads.
 - Recursively lock/unlock entire objects via `processConfig`.
+- Select repeated fields or subtrees with structural path patterns.
 - Public API exports that mirror CLI behavior for programmatic use.
 - Focus on Node.js 22+, ESM modules, and a lightweight dependency set (`js-yaml`).
 
@@ -48,13 +52,17 @@ yarn add yamlock            # project dependency
 # Encrypt values in a YAML file
 YAMLOCK_KEY="super-secret" yamlock encrypt config.yaml
 
-# Decrypt values in place using explicit key/algorithm flags
-yamlock decrypt settings.json --key "super-secret" --algorithm aes-256-cbc
+# Decrypt values in place; the payload determines its format and algorithm
+yamlock decrypt settings.json --key "super-secret"
 
 # Encrypt only selected fields into a new file
 yamlock encrypt config.json --key "$YAMLOCK_KEY" --paths "db.password,api.token" --output config.secure.json
 
+# Encrypt repeated tokens and an entire subtree
+yamlock encrypt config.json --key "$YAMLOCK_KEY" --path-patterns 'users[*].token,services.**'
+
 # Inspect CLI metadata
+yamlock --help
 yamlock version
 yamlock algorithms
 
@@ -63,39 +71,170 @@ yamlock keygen --length 64 --format base64
 
 # Preview changes without touching files
 yamlock encrypt config.yml -o config.enc.yml -p db.password -k "my-secret-key" -d
+
+# Preview a legacy-to-v2 migration without printing config contents
+yamlock migrate config.yml -k "$YAMLOCK_KEY" -p db.password -d
+
+# Explicitly write legacy v1 for a temporary compatibility requirement
+yamlock encrypt config.yml -k "$YAMLOCK_KEY" --legacy --algorithm aes-256-cbc
 ```
 
-The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and writes the file back in the same format.
+The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and
+writes the file back in the same format. Normal `encrypt` and `decrypt` writes
+use an fsynced temporary file plus an atomic rename. In-place writes preserve
+the source mode; a new `--output` inherits the source mode, while an existing
+regular output preserves its own mode. Mutating operations reject symbolic-link
+inputs and outputs rather than following or replacing their targets.
+
+YAML writes preserve parsed values, not the original syntax tree. Comments,
+anchor/alias syntax, merge keys, explicit tags, quoting, and formatting may be
+removed or normalized. Review [the YAML rewrite contract](docs/yaml-behavior.md)
+and use `--dry-run` or `--output` when presentation details matter.
 
 Options of note:
 - `--output <file>` writes the result to a separate file instead of overwriting the input.
-- `--paths <path1,path2>` targets only the specified fields (dot/bracket notation like `db.password` or `users[0].token`).
-- `--dry-run` shows the would-be changes without modifying files (prints original vs new content).
-- Command `keygen` produces a random key and shows how to store it (shell export or `.env`).
-- Command `algorithms` prints two lists: tested presets (covered by yamlock) and additional ciphers available from the runtime.
+- `--paths <path1,path2>` targets only the specified fields using the [escaped path syntax](#field-path-syntax).
+- `--path-patterns <pattern1,pattern2>` selects structural paths with whole-segment `*`, `[*]`, and `**` wildcards.
+- `--dry-run` previews an operation without modifying files; encrypt/decrypt print content changes, while migrate prints only counts and target paths.
+- `migrate` decrypts selected legacy payloads and re-encrypts them as authenticated v2 payloads.
+- `migrate --allow-mixed` additionally authenticates and preserves selected values that are already v2.
+- In-place migration creates `<file>.yamlock.bak` by default; `--no-backup` disables it explicitly.
+- `encrypt --legacy` writes the legacy v1 format; `--algorithm` is accepted for encryption only together with `--legacy`.
+- `encrypt --error-on-encrypted` fails when a selected value is already encrypted instead of preserving it.
+- `encrypt --force-encrypt` explicitly treats selected `yl|...` strings as plaintext and adds another encryption layer.
+- Command `keygen` produces a random key of 1–4096 whole bytes and shows how to store it (shell export or `.env`).
+- Command `algorithms` prints the fixed v2 profile, tested legacy presets, and additional legacy ciphers available from the runtime.
 - Command `version` prints the installed CLI version.
 
+The CLI rejects unknown or duplicate options, missing option values, extra
+positional arguments, and options that do not apply to the selected command.
+Argument errors use structured `[yamlock:ERR_*]` codes and are reported before
+the CLI reads or modifies a configuration file.
+
+### Field path syntax
+
+Default field paths use dots for object nesting and brackets for array indexes:
+`db.password` and `users[0].token`. Inside an object key, backslashes, dots,
+brackets, and commas are escaped with a backslash. For example,
+`db\.primary.token` selects `token` below the literal key `db.primary`, while
+`db.primary.token` selects three nested object keys. Quote escaped CLI paths so
+the shell passes each backslash unchanged:
+
+```bash
+yamlock encrypt config.json --key "$YAMLOCK_KEY" --paths 'db\.primary.token,labels\,primary'
+```
+
+Node.js callers can build the same canonical strings from unambiguous segments:
+
+```js
+import { processConfig, serializePath } from 'yamlock';
+
+const selectedPath = serializePath(['db.primary', 'token']);
+const encrypted = processConfig(config, {
+  mode: 'encrypt',
+  key: process.env.YAMLOCK_KEY,
+  paths: [selectedPath]
+});
+```
+
+New payloads bind authentication to the escaped canonical path. Payloads written
+by older yamlock versions for keys containing reserved characters remain
+readable through the default serializer's compatibility path; selecting those
+keys now requires the canonical escaped spelling. A custom `pathSerializer`
+keeps its own contract and does not use the default compatibility fallback.
+
+### Path patterns
+
+Patterns are separate from exact `paths`; using both forms a union. They match
+complete structural leaf paths:
+
+- `services.*.token` matches one object-key segment, such as
+  `services.api.token`, but not `services[0].token`.
+- `users[*].token` matches array elements such as `users[0].token`.
+- `db.**` matches a leaf at `db` or any descendant below it, including arrays.
+
+Wildcards must occupy a complete segment. Partial globs such as `service-*`
+are rejected with `ERR_INVALID_PATH_PATTERNS` before the CLI reads the input
+file. Literal reserved characters use the same escaping as exact paths, and
+`\*` selects a literal asterisk key:
+
+```bash
+yamlock encrypt config.json \
+  --key "$YAMLOCK_KEY" \
+  --paths 'root.literal' \
+  --path-patterns 'services.*.token,users[*].token,labels\,primary'
+```
+
+Patterns only decide which leaves are selected. Encryption, decryption, and
+migration continue to bind every payload to its exact canonical leaf path.
+Node.js callers use `pathPatterns: string[]`; it cannot be combined with a
+custom `pathSerializer`.
+
 ### Node.js API
 
 ```js
-import { encryptValue, decryptValue, processConfig } from 'yamlock';
+import { encryptValue, decryptValue, processConfig, serializePath } from 'yamlock';
 
 const encrypted = encryptValue('swordfish', process.env.YAMLOCK_KEY, 'db.password');
 const decrypted = decryptValue(encrypted, process.env.YAMLOCK_KEY, 'db.password');
 
 const config = { db: { password: 'swordfish' } };
-const locked = processConfig(config, { mode: 'encrypt', key: process.env.YAMLOCK_KEY });
-const unlocked = processConfig(locked, { mode: 'decrypt', key: process.env.YAMLOCK_KEY });
+const selectors = { pathPatterns: ['db.**'] };
+const locked = processConfig(config, {
+  mode: 'encrypt',
+  key: process.env.YAMLOCK_KEY,
+  ...selectors
+});
+const unlocked = processConfig(locked, {
+  mode: 'decrypt',
+  key: process.env.YAMLOCK_KEY,
+  ...selectors
+});
+```
+
+Expected Node.js API failures extend `YamlockError` and expose stable `ERR_*`
+codes. Specialized classes distinguish validation, payload, authentication,
+legacy decryption, and config-processing failures; `YAMLOCK_ERROR_CODES` avoids
+repeating code strings. See the [Node.js error contract](docs/errors.md).
+
+The package includes TypeScript declarations. The supported exports, option
+types, and `1.x` compatibility guarantees are listed in the
+[public Node.js API contract](docs/api.md).
+
+Repeated encryption is safe by default. `processConfig` authenticates selected
+existing payloads with the supplied key and field path, preserves them
+unchanged, and encrypts only selected plaintext values. Use
+`existingPayloadPolicy: 'error'` when existing encrypted values should fail the
+operation:
+
+```js
+processConfig(config, {
+  mode: 'encrypt',
+  key: process.env.YAMLOCK_KEY,
+  existingPayloadPolicy: 'error'
+});
 ```
 
+Malformed payloads, incorrect keys, and incorrect field paths are never silently
+skipped. Re-running `yamlock encrypt` on a fully encrypted input does not rewrite
+the source file. Use `yamlock migrate` rather than `encrypt` to convert preserved
+legacy values to v2.
+
+If plaintext intentionally begins with `yl|`, use
+`existingPayloadPolicy: 'encrypt'` or CLI `--force-encrypt`. This also permits
+deliberate nested encryption, so it should not be enabled in routine workflows;
+each added layer requires a matching decrypt operation.
+
 See `examples/basic.js` for a runnable end-to-end script (`node examples/basic.js`).
 
-### Algorithm customization
+### Legacy algorithm customization
 
-Each function accepts either a cipher name or an options object:
+V2 deliberately has no free-form cipher settings. For temporary legacy
+compatibility, select format version 1 and provide the old cipher options:
 
 ```js
 const encrypted = encryptValue('swordfish', KEY, 'db.password', {
+  formatVersion: 1,
   algorithm: 'chacha20-poly1305',
   ivLength: 12 // override the IV size used during encryption
 });
@@ -110,6 +249,7 @@ const processed = processConfig(
   {
     mode: 'encrypt',
     key: KEY,
+    formatVersion: 1,
     algorithm: { algorithm: 'aes-192-cbc', ivLength: 24 }
   }
 );
@@ -118,6 +258,7 @@ const processed = processConfig(
 const restored = processConfig(processed, {
   mode: 'decrypt',
   key: KEY,
+  formatVersion: 1,
   algorithm: { algorithm: 'aes-192-cbc', ivLength: 24 }
 });
 
@@ -126,7 +267,7 @@ const mixedConfig = { db: { password: 'secret', retries: 3 } };
 const lockedMixed = processConfig(mixedConfig, {
   mode: 'encrypt',
   key: KEY,
-  nonStringPolicy: 'stringify', // stringifies numbers/objects before encrypting
+  nonStringPolicy: 'stringify', // stringifies finite numbers, booleans, and null
   pathSerializer: (segments) => segments.join('/') // custom path naming (db/password instead of dot notation)
 });
 
@@ -146,49 +287,135 @@ const lockedUsers = processConfig(
 );
 ```
 
+`processConfig` recursively traverses arrays and plain objects. With the default
+`nonStringPolicy: 'ignore'`, selected non-string and opaque values such as
+`Date`, `undefined`, or `BigInt` are preserved unchanged. Policy `'error'`
+rejects a selected non-string value. Policy `'stringify'` accepts only finite
+numbers, booleans, and `null`; values that native JSON conversion could omit or
+silently change are rejected instead of being encrypted with lost type
+information. Decrypted stringified primitives remain strings.
+
+Circular arrays/objects are rejected. A custom `pathSerializer` must return a
+non-empty, unique string for every leaf and the same serializer must be used for
+encryption and decryption. Policies apply only to values selected by `paths`;
+unselected leaf values are preserved.
+
+Direct `processConfig` calls preserve empty containers, sparse-array length and
+holes, null-prototype objects, and own keys such as `__proto__`. JSON and YAML
+files retain the values their parsers can represent, but those formats do not
+encode JavaScript sparse-array holes as a distinct portable value.
+
+### Authenticated payload v2 (default)
+
+`encryptValue`, `processConfig`, and `yamlock encrypt` write authenticated v2
+payloads by default. `decryptValue` and `processConfig` automatically read both
+v1 and v2.
+
+```js
+const encrypted = encryptValue('swordfish', KEY, 'db.password');
+
+const locked = processConfig(
+  { db: { password: 'swordfish' } },
+  { mode: 'encrypt', key: KEY }
+);
+
+// No format or algorithm option is required when decrypting.
+const original = decryptValue(encrypted, KEY, 'db.password');
+const unlocked = processConfig(locked, { mode: 'decrypt', key: KEY });
+```
+
+V2 uses a fixed AES-256-GCM profile, a random 12-byte nonce, a 16-byte
+authentication tag, and scrypt with a separate random KDF salt. The field path
+and security-critical metadata are authenticated. Free-form cipher and size
+overrides are intentionally unavailable for v2.
+
+Existing legacy files can be migrated safely with the CLI:
+
+```bash
+# Preview counts and target paths; config contents are not printed.
+yamlock migrate config.yaml --key "$YAMLOCK_KEY" --paths "db.password,api.token" --dry-run
+
+# Migrate in place and create config.yaml.yamlock.bak.
+yamlock migrate config.yaml --key "$YAMLOCK_KEY" --paths "db.password,api.token"
+
+# Preserve the source and write a new file. Existing outputs are never replaced.
+yamlock migrate config.yaml --key "$YAMLOCK_KEY" --paths "db.password,api.token" --output config.v2.yaml
+```
+
+Migration validates every selected value and builds the complete result before
+writing. Selected plaintext and non-string values are rejected, so use
+`--paths` or `--path-patterns` for partially encrypted configs. Selected v2
+values are rejected unless `--allow-mixed` is set; with that flag they are
+authenticated and kept unchanged. In-place writes are atomic, preserve the
+source file mode, and do not replace an existing backup. To roll back, verify
+the backup and then copy
+`config.yaml.yamlock.bak` over `config.yaml`.
+
+Legacy AES-CBC payloads have no authentication, so migration can only validate
+their structure, field path, and successful decryption. Backups use the source
+file permissions and match `*.yamlock.bak` in the repository `.gitignore`.
+See [the payload v2 design](docs/design/payload-v2.md) for the format, threat
+model, limits, and staged migration plan. This design and implementation have
+not received a third-party security audit.
+
 ## Advanced usage
 
-- **Selective encryption**: combine `--paths` on the CLI or `paths: []` in `processConfig` to encrypt only sensitive sections of a config file.
-- **Non-string handling**: use `nonStringPolicy: 'ignore' | 'stringify' | 'error'` to control how numbers/objects are treated, and `pathSerializer` to change how traversal paths are represented (e.g., `db/password` instead of dot notation).
+- **Selective encryption**: use exact `--paths`/`paths` selectors, structural `--path-patterns`/`pathPatterns`, or their union to encrypt only sensitive fields.
+- **Repeated encryption**: valid selected payloads are authenticated and preserved; add `--error-on-encrypted` or `existingPayloadPolicy: 'error'` for strict workflows.
+- **Non-string handling**: use `nonStringPolicy: 'ignore' | 'stringify' | 'error'` to preserve opaque leaves, stringify finite JSON primitives, or reject selected non-string values; use `pathSerializer` to change path representation (e.g., `db/password` instead of dot notation).
 - **CI/CD flows**: see [examples/docs/ci-cd.md](examples/docs/ci-cd.md) for a GitHub Actions job that decrypts configs for builds and re-encrypts them before publishing artifacts.
 - **Key rotation**: follow [examples/docs/key-rotation.md](examples/docs/key-rotation.md) for a step-by-step process, including scripting tips for large repos.
 
 ### Supported algorithms
 
-| Algorithm | Type | Notes |
-|-----------|------|-------|
-| `aes-128-cbc` | Block cipher (CBC) | 128-bit keys, 16-byte IV. Works well for backward-compatibility scenarios. |
-| `aes-192-cbc` | Block cipher (CBC) | 192-bit keys, 16-byte IV. Slightly stronger than AES-128 with the same IV requirements. |
-| `aes-256-cbc` (default) | Block cipher (CBC) | 256-bit keys, 16-byte IV. Balanced combination of strength and compatibility. |
-| `chacha20-poly1305` | AEAD stream cipher | 256-bit keys, 12-byte nonce, 16-byte auth tag. Provides built-in integrity/authentication. |
+| Algorithm | Format | Notes |
+|-----------|--------|-------|
+| `aes-256-gcm` | v2 default | Fixed authenticated profile with scrypt, a 12-byte nonce, and a 16-byte tag. |
+| `aes-128-cbc` | legacy v1 | Compatibility only; ciphertext and metadata are not authenticated. |
+| `aes-192-cbc` | legacy v1 | Compatibility only; ciphertext and metadata are not authenticated. |
+| `aes-256-cbc` | legacy v1 | Compatibility default when `--legacy` is used without `--algorithm`. |
+| `chacha20-poly1305` | legacy v1 | Authenticates ciphertext, but not all serialized metadata protected by v2. |
 
-You can also pass any algorithm supported by the current Node.js runtime (`crypto.getCiphers()`), along with custom `keyLength`, `ivLength`, or `authTagLength` overrides. Only the algorithms above are actively tested; additional presets may be added or revised in future releases.
+Additional algorithms exposed by `crypto.getCiphers()` are available only in
+explicit legacy mode and are not part of the supported v2 profile. Prefer the
+default v2 writer for new data.
 
 ## Release information
 
-- The badges at the top show the latest npm version and the status of the Node test suite.
-- See [CHANGELOG.md](CHANGELOG.md) for detailed release notes; install a specific tag via `npm install yamlock@<version>`.
+- The badges at the top show the latest npm version and the status of the full CI matrix.
+- See [GitHub Releases](https://github.com/phoenixweiss/yamlock/releases) and
+  [CHANGELOG.md](CHANGELOG.md) for detailed release notes; install a specific
+  version via `npm install yamlock@<version>`.
+- yamlock versions are bumped with my own release utility,
+  [Bumpster](https://github.com/phoenixweiss/Bumpster). It keeps the tracked
+  `VERSION` file and `package.json` synchronized while publishing the `dev`,
+  `main`, and `vX.Y.Z` Git refs atomically. Each stable tag must pass the full
+  CI and package preflight before its GitHub Release is published.
+
+### Encrypted value formats
+
+New values use the authenticated v2 envelope:
 
-### Encrypted value format
+```txt
+yl|2|aes-256-gcm|scrypt|32768|8|1|<kdf_salt>|<nonce>|<path>|<ciphertext>|<tag>
+```
 
-Every locked string follows the format:
+Legacy values remain readable and can still be written explicitly:
 
 ```txt
 yl|<algorithm>|<salt_base64>|<iv_base64>|<data_base64>
 ```
 
-Where:
-- `yl` - format marker prefix
-- `<algorithm>` - algorithm name (e.g., aes-256-cbc)
-- `<salt_base64>` - Base64-encoded field path
-- `<iv_base64>` - Base64-encoded initialization vector
-- `<data_base64>` - Base64-encoded encrypted data
+The legacy name `<salt_base64>` is historical: that segment is only the
+Base64-encoded field path and is not a random salt or KDF input.
 
-The salt is derived from the full field path. Moving or renaming the field invalidates the salt, preventing accidental decryption in the wrong location.
+See [the payload v2 design](docs/design/payload-v2.md) for the canonical field
+definitions, limits, compatibility rules, and legacy security limitations.
 
 ### Key rotation
 
-See [docs/key-rotation.md](docs/key-rotation.md) for a step-by-step guide to rotating `YAMLOCK_KEY` without losing data.
+See [the key rotation guide](examples/docs/key-rotation.md) for a step-by-step
+workflow that re-encrypts values with v2 and a new `YAMLOCK_KEY`.
 
 ## Inspiration and motivation
 
@@ -211,9 +438,15 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, available scrip
 
 ## Future work
 
-- Additional cipher presets and stronger default algorithms.
-- More CLI/API examples for rotating keys, selective field targeting, and CI automation.
-- Configurable behavior for non-string values (skip vs. coerce) and stricter file format validation.
+- Safe subtree and wildcard selectors are specified in the
+  [path pattern design proposal](docs/design/path-patterns.md). Existing
+  `paths` remain exact; the proposed feature is not implemented yet.
+- An async encryption API with bounded scrypt concurrency for large configs.
+- Stricter file-format validation and preservation rules for advanced YAML features.
+
+## Author
+
+Created and maintained by [Pavel Tkachev (@phoenixweiss)](https://github.com/phoenixweiss).
 
 ## License
 

package/bin/yamlock

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 
 async function loadCliEntry() {
+  if (process.env.YAMLOCK_TEST_SOURCE === '1') {
+    const sourceModule = await import('../src/cli/cli.js');
+    if (sourceModule.runCli) {
+      return sourceModule.runCli;
+    }
+    throw new Error('Source CLI entry does not export runCli.');
+  }
+
   try {
     const distModule = await import('../dist/cli/cli.js');
     if (distModule.runCli) {