yamlock 1.0.0 → 1.1.1

package/README.md

@@ -7,6 +7,8 @@
 [![npm version](https://img.shields.io/npm/v/yamlock)](https://www.npmjs.com/package/yamlock)
 [![CI](https://github.com/phoenixweiss/yamlock/actions/workflows/ci.yml/badge.svg)](https://github.com/phoenixweiss/yamlock/actions/workflows/ci.yml)
 
+[Project website](https://phoenixweiss.github.io/yamlock/)
+
 # yamlock
 
 Value-level encryption for YAML and JSON configuration files. The name **yamlock** combines "YAML" and "lock" while also sounding like "warlock", hinting at a little configuration magic.
@@ -40,6 +42,7 @@ yarn add yamlock            # project dependency
 - 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`).
 
@@ -57,6 +60,9 @@ 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
@@ -90,6 +96,7 @@ 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 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.
@@ -138,6 +145,33 @@ 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
@@ -147,8 +181,17 @@ const encrypted = encryptValue('swordfish', process.env.YAMLOCK_KEY, 'db.passwor
 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_*`
@@ -303,10 +346,11 @@ yamlock migrate config.yaml --key "$YAMLOCK_KEY" --paths "db.password,api.token"
 
 Migration validates every selected value and builds the complete result before
 writing. Selected plaintext and non-string values are rejected, so use
-`--paths` 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
+`--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
@@ -318,7 +362,7 @@ not received a third-party security audit.
 
 ## Advanced usage
 
-- **Selective encryption**: combine `--paths` on the CLI or a non-empty `paths: ['db.password']` array in `processConfig` to encrypt only sensitive fields.
+- **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.
@@ -341,11 +385,14 @@ default v2 writer for new data.
 ## Release information
 
 - The badges at the top show the latest npm version and the status of the full CI matrix.
-- See [CHANGELOG.md](CHANGELOG.md) for detailed release notes; install a specific tag via `npm install yamlock@<version>`.
+- 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.
+  `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
 
@@ -393,6 +440,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, available scrip
 
 ## Future work
 
+- 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.
 

package/dist/cli/cli.js

@@ -14,6 +14,7 @@ import yaml from 'js-yaml';
 import { processConfig } from '../utils/config.js';
 import { writeFileAtomically } from '../utils/file.js';
 import { migrateConfig } from '../utils/migrate.js';
+import { compilePathPatterns } from '../utils/path-pattern.js';
 import { listSupportedAlgorithms, TESTED_ALGORITHMS } from '../crypto/utils.js';
 
 const require = createRequire(import.meta.url);
@@ -32,6 +33,7 @@ const OPTION_SPECS = [
   { key: 'algorithm', names: ['-a', '--algorithm'], takesValue: true },
   { key: 'output', names: ['-o', '--output'], takesValue: true },
   { key: 'paths', names: ['-p', '--paths'], takesValue: true },
+  { key: 'pathPatterns', names: ['--path-patterns'], takesValue: true },
   { key: 'dryRun', names: ['-d', '--dry-run'], takesValue: false },
   { key: 'allowMixed', names: ['--allow-mixed'], takesValue: false },
   { key: 'noBackup', names: ['--no-backup'], takesValue: false },
@@ -53,13 +55,22 @@ const COMMAND_OPTIONS = new Map([
     'algorithm',
     'output',
     'paths',
+    'pathPatterns',
     'dryRun',
     'legacy',
     'errorOnEncrypted',
     'forceEncrypt'
   ])],
-  ['decrypt', new Set(['key', 'output', 'paths', 'dryRun'])],
-  ['migrate', new Set(['key', 'output', 'paths', 'dryRun', 'allowMixed', 'noBackup'])],
+  ['decrypt', new Set(['key', 'output', 'paths', 'pathPatterns', 'dryRun'])],
+  ['migrate', new Set([
+    'key',
+    'output',
+    'paths',
+    'pathPatterns',
+    'dryRun',
+    'allowMixed',
+    'noBackup'
+  ])],
   ['keygen', new Set(['length', 'format'])],
   ['help', new Set()],
   ['version', new Set()],
@@ -87,6 +98,7 @@ Options:
   -a, --algorithm <value>  Legacy cipher algorithm (encrypt --legacy only).
   -o, --output <file>      Write the result to a different file (otherwise overwrites the input file).
   -p, --paths <p1,p2>      Comma-separated escaped field paths to process (dot/bracket notation).
+  --path-patterns <p1,p2>  Structural selectors using *, [*], and ** whole-segment wildcards.
   -d, --dry-run             Preview the operation without modifying files.
   --allow-mixed            (migrate) Authenticate and preserve selected v2 values.
   --no-backup              (migrate) Replace the input without creating <file>.yamlock.bak.
@@ -104,6 +116,7 @@ YAML rewrite note:
 Path syntax:
   Object-key backslashes, dots, brackets, and commas must be backslash-escaped.
   Example: db\\.primary.token selects { "db.primary": { "token": ... } }.
+  Patterns are separate selectors; e.g. services.*.token or users[*].token.
 `;
 }
 
@@ -164,7 +177,7 @@ function serializeConfig(format, data) {
   return `${JSON.stringify(data, null, 2)}\n`;
 }
 
-function parsePaths(value) {
+function splitPathList(value) {
   if (!value) {
     return [];
   }
@@ -189,9 +202,7 @@ function parsePaths(value) {
   }
   paths.push(current);
 
-  return paths
-    .map((segment) => segment.trim())
-    .filter((segment) => segment.length > 0);
+  return paths.map((segment) => segment.trim());
 }
 
 function parseArgs(argv) {
@@ -242,15 +253,26 @@ function parseArgs(argv) {
         );
       }
 
-      if (spec.key === 'paths') {
-        const paths = parsePaths(next);
-        if (paths.length === 0) {
+      if (spec.key === 'paths' || spec.key === 'pathPatterns') {
+        const splitSelectors = splitPathList(next);
+        const selectors = spec.key === 'pathPatterns'
+          ? splitSelectors
+          : splitSelectors.filter((selector) => selector.length > 0);
+        if (
+          selectors.length === 0 ||
+          (spec.key === 'pathPatterns' && selectors.some((selector) => selector.length === 0))
+        ) {
           throw cliError(
-            'ERR_INVALID_OPTION_VALUE',
-            'Option --paths requires at least one non-empty field path.'
+            spec.key === 'pathPatterns'
+              ? 'ERR_INVALID_PATH_PATTERNS'
+              : 'ERR_INVALID_OPTION_VALUE',
+            `Option ${OPTION_LABELS.get(spec.key)} requires at least one non-empty selector.`
           );
         }
-        result.options.paths = paths;
+        if (spec.key === 'pathPatterns') {
+          compilePathPatterns(selectors);
+        }
+        result.options[spec.key] = selectors;
       } else {
         result.options[spec.key] = next;
       }
@@ -435,6 +457,7 @@ function handleMigration({ file, absolutePath, outputPath, config, key, options
   const result = migrateConfig(config.data, {
     key,
     paths: options.paths,
+    pathPatterns: options.pathPatterns,
     allowMixed: options.allowMixed
   });
   const serialized = serializeConfig(config.format, result.data);
@@ -629,7 +652,8 @@ export async function runCli(argv = process.argv) {
           : options.errorOnEncrypted
             ? 'error'
             : 'preserve',
-        paths: options.paths
+        paths: options.paths,
+        pathPatterns: options.pathPatterns
       });
       if (outputPath === absolutePath && isDeepStrictEqual(result, config.data)) {
         print('No plaintext values required encryption. No files were modified.');
@@ -651,7 +675,8 @@ export async function runCli(argv = process.argv) {
       const result = processConfig(config.data, {
         mode: 'decrypt',
         key,
-        paths: options.paths
+        paths: options.paths,
+        pathPatterns: options.pathPatterns
       });
       handleWrite({
         dryRun: options.dryRun,
@@ -671,8 +696,10 @@ export async function runCli(argv = process.argv) {
     const structuredCode = typeof error.code === 'string' && error.code.startsWith('ERR_')
       ? error.code
       : null;
+    const isMigrationCode = structuredCode === 'ERR_INVALID_PATH_PATTERNS' ||
+      structuredCode?.startsWith('ERR_MIGRATION_');
     const code = command === 'migrate'
-      ? structuredCode?.startsWith('ERR_MIGRATION_')
+      ? isMigrationCode
         ? structuredCode
         : 'ERR_MIGRATION_FAILED'
       : structuredCode ?? 'ERR_PROCESS_FAILED';

package/dist/errors.js

@@ -15,6 +15,7 @@ export const YAMLOCK_ERROR_CODES = Object.freeze({
   INVALID_NON_STRING_POLICY: 'ERR_INVALID_NON_STRING_POLICY',
   INVALID_OPTIONS: 'ERR_INVALID_OPTIONS',
   INVALID_PATH_SEGMENTS: 'ERR_INVALID_PATH_SEGMENTS',
+  INVALID_PATH_PATTERNS: 'ERR_INVALID_PATH_PATTERNS',
   INVALID_PATH_SERIALIZER: 'ERR_INVALID_PATH_SERIALIZER',
   INVALID_PATHS: 'ERR_INVALID_PATHS',
   INVALID_PAYLOAD: 'ERR_INVALID_PAYLOAD',

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export interface ProcessConfigCommonOptions {
   nonStringPolicy?: YamlockNonStringPolicy;
   pathSerializer?: (segments: YamlockPathSegment[]) => string;
   paths?: string[];
+  pathPatterns?: string[];
   parentPath?: YamlockPathSegment[];
 }
 
@@ -57,6 +58,7 @@ export const YAMLOCK_ERROR_CODES: Readonly<{
   INVALID_NON_STRING_POLICY: 'ERR_INVALID_NON_STRING_POLICY';
   INVALID_OPTIONS: 'ERR_INVALID_OPTIONS';
   INVALID_PATH_SEGMENTS: 'ERR_INVALID_PATH_SEGMENTS';
+  INVALID_PATH_PATTERNS: 'ERR_INVALID_PATH_PATTERNS';
   INVALID_PATH_SERIALIZER: 'ERR_INVALID_PATH_SERIALIZER';
   INVALID_PATHS: 'ERR_INVALID_PATHS';
   INVALID_PAYLOAD: 'ERR_INVALID_PAYLOAD';

package/dist/utils/config.js

@@ -4,6 +4,11 @@ import { detectPayloadVersion } from '../crypto/payload-v2.js';
 import { isYamlockPayload } from '../crypto/utils.js';
 import { YamlockConfigError } from '../errors.js';
 import { serializeLegacyPath, serializePath } from './path.js';
+import {
+  compilePathPatterns,
+  matchesAnyPathPattern,
+  PathPatternSyntaxError
+} from './path-pattern.js';
 
 const MODES = {
   ENCRYPT: 'encrypt',
@@ -13,8 +18,11 @@ const MODES = {
 const NON_STRING_POLICIES = new Set(['ignore', 'stringify', 'error']);
 const EXISTING_PAYLOAD_POLICIES = new Set(['preserve', 'error', 'encrypt']);
 
-function createConfigError(code, message) {
-  return new YamlockConfigError(message, { code });
+function createConfigError(code, message, cause) {
+  return new YamlockConfigError(message, {
+    code,
+    ...(cause === undefined ? {} : { cause })
+  });
 }
 
 function isConfigContainer(value) {
@@ -83,6 +91,22 @@ function normalizePaths(paths) {
   return new Set(normalized);
 }
 
+function normalizePathPatterns(pathPatterns) {
+  try {
+    return compilePathPatterns(pathPatterns);
+  } catch (error) {
+    if (!(error instanceof PathPatternSyntaxError)) {
+      throw error;
+    }
+
+    throw createConfigError(
+      'ERR_INVALID_PATH_PATTERNS',
+      error.message,
+      error
+    );
+  }
+}
+
 function resolveCurrentPaths(segments, pathSerializer) {
   let currentPath;
   try {
@@ -150,6 +174,7 @@ function stringifyConfigLeaf(value, currentPath) {
  * @param {"preserve"|"error"|"encrypt"} [options.existingPayloadPolicy]
  * @param {(segments: Array<string|number>) => string} [options.pathSerializer]
  * @param {string[]} [options.paths]
+ * @param {string[]} [options.pathPatterns]
  * @param {Array<string|number>} [options.parentPath]
  * @returns {Object|Array}
  */
@@ -195,6 +220,13 @@ export function processConfig(node, options) {
   const parentPath = options.parentPath ?? [];
   validatePathSegments(parentPath, 'parentPath');
   const normalizedPaths = normalizePaths(options.paths);
+  const compiledPathPatterns = normalizePathPatterns(options.pathPatterns);
+  if (compiledPathPatterns.length > 0 && options.pathSerializer !== undefined) {
+    throw createConfigError(
+      'ERR_INVALID_PATH_PATTERNS',
+      'pathPatterns cannot be combined with pathSerializer.'
+    );
+  }
   const existingPayloadPolicy = options.existingPayloadPolicy ?? 'preserve';
   if (!EXISTING_PAYLOAD_POLICIES.has(existingPayloadPolicy)) {
     throw createConfigError(
@@ -208,6 +240,7 @@ export function processConfig(node, options) {
     mode,
     parentPath,
     normalizedPaths,
+    compiledPathPatterns,
     nonStringPolicy,
     existingPayloadPolicy,
     pathSerializer: options.pathSerializer,
@@ -216,7 +249,7 @@ export function processConfig(node, options) {
   });
 }
 
-function traverseConfig(node, { mode, key, algorithm, algorithmOptions, formatVersion, parentPath, normalizedPaths, nonStringPolicy, existingPayloadPolicy, pathSerializer, ancestors, seenPaths }) {
+function traverseConfig(node, { mode, key, algorithm, algorithmOptions, formatVersion, parentPath, normalizedPaths, compiledPathPatterns, nonStringPolicy, existingPayloadPolicy, pathSerializer, ancestors, seenPaths }) {
   const isArrayNode = Array.isArray(node);
   const result = createResultContainer(node);
   const selectedCryptoOptions = algorithmOptions ?? algorithm;
@@ -249,6 +282,7 @@ function traverseConfig(node, { mode, key, algorithm, algorithmOptions, formatVe
           algorithmOptions: cryptoOptions,
           parentPath: pathSegments,
           normalizedPaths,
+          compiledPathPatterns,
           nonStringPolicy,
           existingPayloadPolicy,
           pathSerializer,
@@ -266,7 +300,10 @@ function traverseConfig(node, { mode, key, algorithm, algorithmOptions, formatVe
       }
       seenPaths.add(currentPath);
 
-      const shouldProcess = !normalizedPaths || normalizedPaths.has(currentPath);
+      const hasSelectors = normalizedPaths !== null || compiledPathPatterns.length > 0;
+      const shouldProcess = !hasSelectors ||
+        normalizedPaths?.has(currentPath) ||
+        matchesAnyPathPattern(compiledPathPatterns, pathSegments);
       if (!shouldProcess) {
         setResultValue(result, targetKey, originalValue);
         continue;

package/dist/utils/migrate.js

@@ -6,6 +6,7 @@ import {
 } from '../crypto/payload-v2.js';
 import { isYamlockPayload } from '../crypto/utils.js';
 import { serializeLegacyPath, serializePath } from './path.js';
+import { compilePathPatterns, matchesAnyPathPattern } from './path-pattern.js';
 
 function createMigrationError(code, message) {
   const error = new Error(message);
@@ -59,7 +60,10 @@ function traverse(node, context) {
       return;
     }
 
-    const selected = !context.paths || context.paths.has(currentPath);
+    const hasSelectors = context.paths !== null || context.pathPatterns.length > 0;
+    const selected = !hasSelectors ||
+      context.paths?.has(currentPath) ||
+      matchesAnyPathPattern(context.pathPatterns, pathSegments);
     if (!selected) {
       setResultValue(result, targetKey, value);
       return;
@@ -77,7 +81,7 @@ function traverse(node, context) {
     if (!isYamlockPayload(value)) {
       throw createMigrationError(
         'ERR_MIGRATION_PLAINTEXT',
-        `Selected value at ${currentPath} is not encrypted; narrow --paths to legacy payloads.`
+        `Selected value at ${currentPath} is not encrypted; narrow the path selectors to legacy payloads.`
       );
     }
 
@@ -124,6 +128,7 @@ function traverse(node, context) {
  * @param {Object} options
  * @param {string|Buffer} options.key
  * @param {string[]} [options.paths]
+ * @param {string[]} [options.pathPatterns]
  * @param {boolean} [options.allowMixed=false]
  * @returns {{ data: Object|Array, changed: boolean, stats: { selected: number, migrated: number, preservedV2: number } }}
  */
@@ -150,6 +155,7 @@ export function migrateConfig(node, options) {
   const data = traverse(node, {
     key: options.key,
     paths: normalizePaths(options.paths),
+    pathPatterns: compilePathPatterns(options.pathPatterns),
     allowMixed: options.allowMixed === true,
     parentPath: [],
     stats

package/dist/utils/path-pattern.js

@@ -0,0 +1,260 @@
+import { YAMLOCK_ERROR_CODES } from '../errors.js';
+
+const COMPILED_PATTERN = Symbol('yamlock.compiledPathPattern');
+const ALLOWED_ESCAPES = new Set(['\\', '.', '[', ']', ',', '*']);
+const EMPTY_COMPILED_PATTERNS = Object.freeze([]);
+
+const TOKEN_TYPES = Object.freeze({
+  ARRAY_INDEX: 'array-index',
+  ARRAY_WILDCARD: 'array-wildcard',
+  GLOBSTAR: 'globstar',
+  OBJECT_KEY: 'object-key',
+  OBJECT_WILDCARD: 'object-wildcard'
+});
+
+export class PathPatternSyntaxError extends Error {
+  constructor(message, offset = 0) {
+    super(`Invalid path pattern at offset ${offset}: ${message}`);
+    this.name = 'PathPatternSyntaxError';
+    this.code = YAMLOCK_ERROR_CODES.INVALID_PATH_PATTERNS;
+    this.offset = offset;
+  }
+}
+
+function syntaxError(message, offset) {
+  throw new PathPatternSyntaxError(message, offset);
+}
+
+function freezeToken(type, value) {
+  return Object.freeze(value === undefined ? { type } : { type, value });
+}
+
+function parseObjectToken(source, start) {
+  let index = start;
+  let value = '';
+  let hasUnescapedWildcard = false;
+
+  while (index < source.length) {
+    const character = source[index];
+    if (character === '.' || character === '[') {
+      break;
+    }
+
+    if (character === '\\') {
+      const escaped = source[index + 1];
+      if (escaped === undefined) {
+        syntaxError('A trailing backslash is not allowed.', index);
+      }
+      if (!ALLOWED_ESCAPES.has(escaped)) {
+        syntaxError(`Unsupported escape \\${escaped}.`, index);
+      }
+      value += escaped;
+      index += 2;
+      continue;
+    }
+
+    if (character === ']') {
+      syntaxError('Unexpected closing bracket.', index);
+    }
+    if (character === ',') {
+      syntaxError('Literal commas must be escaped.', index);
+    }
+    if (character === '*') {
+      hasUnescapedWildcard = true;
+    }
+
+    value += character;
+    index += 1;
+  }
+
+  if (index === start) {
+    syntaxError('Object path segments must not be empty.', start);
+  }
+
+  const rawSegment = source.slice(start, index);
+  if (hasUnescapedWildcard) {
+    if (rawSegment === '*') {
+      return {
+        nextIndex: index,
+        token: freezeToken(TOKEN_TYPES.OBJECT_WILDCARD)
+      };
+    }
+    if (rawSegment === '**') {
+      return {
+        nextIndex: index,
+        token: freezeToken(TOKEN_TYPES.GLOBSTAR)
+      };
+    }
+    syntaxError('Wildcards must occupy a complete object segment.', start);
+  }
+
+  return {
+    nextIndex: index,
+    token: freezeToken(TOKEN_TYPES.OBJECT_KEY, value)
+  };
+}
+
+function parseArrayToken(source, start) {
+  const closingBracket = source.indexOf(']', start + 1);
+  if (closingBracket === -1) {
+    syntaxError('Array segments require a closing bracket.', start);
+  }
+
+  const content = source.slice(start + 1, closingBracket);
+  if (content === '*') {
+    return {
+      nextIndex: closingBracket + 1,
+      token: freezeToken(TOKEN_TYPES.ARRAY_WILDCARD)
+    };
+  }
+
+  if (!/^(?:0|[1-9]\d*)$/u.test(content)) {
+    syntaxError('Array indexes must be canonical non-negative integers or *.', start);
+  }
+
+  const value = Number(content);
+  if (!Number.isSafeInteger(value)) {
+    syntaxError('Array indexes must be safe integers.', start);
+  }
+
+  return {
+    nextIndex: closingBracket + 1,
+    token: freezeToken(TOKEN_TYPES.ARRAY_INDEX, value)
+  };
+}
+
+function compileNormalizedPattern(source) {
+  const tokens = [];
+  let index = 0;
+
+  while (index < source.length) {
+    const parsed = source[index] === '['
+      ? parseArrayToken(source, index)
+      : parseObjectToken(source, index);
+    tokens.push(parsed.token);
+    index = parsed.nextIndex;
+
+    if (index === source.length) {
+      break;
+    }
+
+    if (source[index] === '[') {
+      continue;
+    }
+
+    if (source[index] !== '.') {
+      syntaxError(`Unexpected character ${source[index]}.`, index);
+    }
+
+    index += 1;
+    if (index === source.length) {
+      syntaxError('A pattern must not end with a dot.', index - 1);
+    }
+    if (source[index] === '[') {
+      syntaxError('Array segments must not follow a dot.', index);
+    }
+  }
+
+  const compiled = {
+    source,
+    tokens: Object.freeze(tokens)
+  };
+  Object.defineProperty(compiled, COMPILED_PATTERN, { value: true });
+  return Object.freeze(compiled);
+}
+
+export function compilePathPattern(pattern) {
+  if (typeof pattern !== 'string') {
+    syntaxError('A pattern must be a string.', 0);
+  }
+
+  const source = pattern.trim();
+  if (source.length === 0) {
+    syntaxError('A pattern must not be empty.', 0);
+  }
+
+  return compileNormalizedPattern(source);
+}
+
+export function compilePathPatterns(patterns) {
+  if (patterns === undefined || (Array.isArray(patterns) && patterns.length === 0)) {
+    return EMPTY_COMPILED_PATTERNS;
+  }
+  if (!Array.isArray(patterns)) {
+    syntaxError('pathPatterns must be an array of non-empty strings.', 0);
+  }
+
+  const compiledBySource = new Map();
+  for (const pattern of patterns) {
+    const compiled = compilePathPattern(pattern);
+    compiledBySource.set(compiled.source, compiled);
+  }
+  return Object.freeze([...compiledBySource.values()]);
+}
+
+function validatePathSegments(segments) {
+  if (!Array.isArray(segments)) {
+    throw new TypeError('Path segments must be an array.');
+  }
+
+  const invalid = segments.some((segment) => (
+    (typeof segment !== 'string' || segment.length === 0) &&
+    (!Number.isInteger(segment) || segment < 0)
+  ));
+  if (invalid) {
+    throw new TypeError('Path segments must be non-empty strings or non-negative integers.');
+  }
+}
+
+function tokenMatchesSegment(token, segment) {
+  switch (token.type) {
+    case TOKEN_TYPES.OBJECT_KEY:
+      return typeof segment === 'string' && segment === token.value;
+    case TOKEN_TYPES.ARRAY_INDEX:
+      return typeof segment === 'number' && segment === token.value;
+    case TOKEN_TYPES.OBJECT_WILDCARD:
+      return typeof segment === 'string';
+    case TOKEN_TYPES.ARRAY_WILDCARD:
+      return typeof segment === 'number';
+    default:
+      return false;
+  }
+}
+
+export function matchesPathPattern(compiledPattern, segments) {
+  if (!compiledPattern?.[COMPILED_PATTERN]) {
+    throw new TypeError('matchesPathPattern requires a compiled path pattern.');
+  }
+  validatePathSegments(segments);
+
+  let previous = new Array(segments.length + 1).fill(false);
+  previous[0] = true;
+
+  for (const token of compiledPattern.tokens) {
+    const current = new Array(segments.length + 1).fill(false);
+    if (token.type === TOKEN_TYPES.GLOBSTAR) {
+      current[0] = previous[0];
+      for (let index = 1; index <= segments.length; index += 1) {
+        current[index] = previous[index] || current[index - 1];
+      }
+    } else {
+      for (let index = 1; index <= segments.length; index += 1) {
+        current[index] = previous[index - 1] && tokenMatchesSegment(
+          token,
+          segments[index - 1]
+        );
+      }
+    }
+    previous = current;
+  }
+
+  return previous[segments.length];
+}
+
+export function matchesAnyPathPattern(compiledPatterns, segments) {
+  if (!Array.isArray(compiledPatterns)) {
+    throw new TypeError('matchesAnyPathPattern requires an array of compiled patterns.');
+  }
+  validatePathSegments(segments);
+  return compiledPatterns.some((pattern) => matchesPathPattern(pattern, segments));
+}

package/docs/api.md

@@ -45,12 +45,19 @@ options object with `algorithm`, `keyLength`, `ivLength`, and `authTagLength`.
 The algorithm stored in a payload is authoritative during decryption; sizing
 overrides exist only for low-level legacy compatibility.
 
-`processConfig` additionally accepts exact `paths`, `parentPath`, a custom
-`pathSerializer`, `nonStringPolicy`, and encrypt-only
+`processConfig` additionally accepts exact `paths`, structural `pathPatterns`,
+`parentPath`, a custom `pathSerializer`, `nonStringPolicy`, and encrypt-only
 `existingPayloadPolicy`. It returns a new config container and does not mutate
 the input. With `nonStringPolicy: 'stringify'`, selected finite JSON primitives
 may become strings, so the TypeScript return type is intentionally widened.
 
+`paths` remains exact throughout the `1.x` line. `pathPatterns` is a separate
+selector list with whole-segment `*`, `[*]`, and `**` wildcards. Exact paths
+and patterns form a union, while payload authentication always uses the exact
+leaf path rather than pattern text. `pathPatterns` cannot be combined with a
+custom `pathSerializer`. See the [path pattern design](design/path-patterns.md)
+for the grammar and compatibility rules.
+
 See the [Node.js error contract](errors.md) and the
 [payload v2 design](design/payload-v2.md) for the security and serialization
 details.

package/docs/design/path-patterns.md

@@ -0,0 +1,213 @@
+# Path pattern design
+
+Status: implemented on `dev` for a future `1.x` minor release; release and
+hosted-CI verification remain pending.
+
+## Goals
+
+- Select a config subtree without listing every leaf.
+- Select repeated object fields and array elements with structural wildcards.
+- Keep the existing exact `paths` contract fully backward compatible.
+- Keep selector syntax separate from the exact field path authenticated by a
+  payload.
+- Share the same selection behavior across `processConfig` and the CLI
+  `encrypt`, `decrypt`, and `migrate` commands.
+- Reject malformed or ambiguous patterns before reading or modifying a config
+  file.
+
+## Non-goals
+
+- Changing `serializePath`, payload metadata, key derivation, or authenticated
+  field paths.
+- Treating existing `paths` strings as globs.
+- Regular expressions, partial-segment wildcards, character classes, braces,
+  negation, or exclusion rules.
+- Selecting containers as values. yamlock continues to process leaves only.
+- Pattern matching against a custom `pathSerializer` in the first release.
+
+## Compatibility decision
+
+The Node.js API adds a separate `pathPatterns?: string[]` option. The CLI adds
+`--path-patterns <pattern1,pattern2>`. Existing `paths` and `--paths`
+remain exact selectors, including strings containing literal `*` characters.
+
+Exact selectors and patterns form a union: a leaf is selected when either its
+exact serialized path is present in `paths` or its structural segments match a
+pattern. When both selector arrays are omitted or empty, all leaves remain
+selected as they are today. Duplicate and overlapping selectors process a leaf
+only once.
+
+Patterns operate on the original string/array path segments. They never become
+the field path passed to `encryptValue` or `decryptValue`; encryption and
+authentication continue to use the exact canonical path, or the exact output
+of `pathSerializer` where supported. This prevents a broad selector such as
+`db.**` from weakening field-path binding.
+
+`pathPatterns` and `pathSerializer` are mutually exclusive. Exact
+`paths` remain available with a custom serializer. Failing closed avoids an
+ambiguous API where pattern syntax appears to use a serializer but actually
+matches a different structural representation.
+
+## Pattern grammar
+
+Patterns use the existing dot/bracket structure plus three whole-segment
+wildcards:
+
+| Syntax | Meaning |
+| --- | --- |
+| `name` | One exact object-key segment |
+| `[0]` | One exact array-index segment |
+| `*` | Any one object-key segment |
+| `[*]` | Any one array-index segment |
+| `**` | Zero or more object-key or array-index segments |
+
+Examples:
+
+| Pattern | Matches | Does not match |
+| --- | --- | --- |
+| `db.**` | `db.password`, `db.replica.password`, a leaf at `db` | `database.password` |
+| `services.*.token` | `services.api.token` | `services[0].token` |
+| `users[*].token` | `users[0].token`, `users[12].token` | `users.admin.token` |
+| `**.token` | `token`, `api.token`, `users[0].token` | `token.value` |
+| `matrix[*][*].secret` | `matrix[0][1].secret` | `matrix.primary.secret` |
+
+`*` and `**` are special only when they occupy a complete object segment.
+`[*]` is special only as a complete array segment. Partial globs such as
+`service-*.token` are invalid rather than being interpreted differently by
+different callers.
+
+## Escaping
+
+Pattern literals retain the canonical escaping rules for `\\`, `.`, `[`, `]`,
+and `,`. In addition, `\*` represents a literal asterisk inside an object key.
+Examples:
+
+| Pattern | Selected structural path |
+| --- | --- |
+| `a\.b.**` | descendants of the literal root key `a.b` |
+| `labels\,primary` | the literal root key `labels,primary` |
+| `\*` | the literal root key `*` |
+| `features.\*\.enabled` | the literal key `*.enabled` below `features` |
+| `items\[\*\]` | the literal object key `items[*]` |
+
+A trailing backslash, an unsupported escape, an empty segment, malformed
+brackets, a negative/non-integer array index, or a wildcard embedded in a
+literal segment is invalid. CLI comma splitting continues to preserve escaped
+commas before the shared pattern parser validates each item.
+
+This escaping affects selectors only. It does not add `*` to the reserved
+characters used by `serializePath`, so existing payload paths and exact
+selectors do not change.
+
+## Matching semantics
+
+- Patterns match complete leaf paths, not string prefixes.
+- `**` may consume zero, one, or many structural segments, including array
+  indexes.
+- `db` selects a leaf exactly at `db`; it does not select descendants. Use
+  `db.**` for the subtree.
+- `*` never matches an array index, and `[*]` never matches an object key.
+- A pattern can contain more than one `**`; matching must remain deterministic.
+- Empty containers and sparse-array holes contain no leaves and therefore do
+  not produce matches.
+- `parentPath` participates in the full structural path before matching.
+- Pattern order does not affect the result.
+
+Patterns must be parsed into structural tokens once before traversal. Matching
+must use a bounded dynamic-programming or equivalent token algorithm rather
+than converting user input into a backtracking regular expression. A malformed
+pattern must fail before traversal, crypto work, or file access.
+
+## API and CLI
+
+Node.js API:
+
+```js
+processConfig(config, {
+  mode: 'encrypt',
+  key,
+  paths: ['root.literal'],
+  pathPatterns: ['db.**', 'users[*].token']
+});
+```
+
+CLI:
+
+```bash
+yamlock encrypt config.yaml \
+  --key "$YAMLOCK_KEY" \
+  --paths 'root.literal' \
+  --path-patterns 'db.**,users[*].token'
+```
+
+The CLI option applies to `encrypt`, `decrypt`, and `migrate`. It requires at
+least one non-empty pattern. Invalid syntax uses the structured
+`[yamlock:ERR_INVALID_PATH_PATTERNS]` error and exit code `1` before the input
+file is read. The Node.js API adds the same stable error code through
+`YamlockConfigError`.
+
+## Interaction with existing behavior
+
+### Encryption
+
+Each matched plaintext leaf is encrypted with its exact field path. Existing
+payload handling still follows `existingPayloadPolicy`; overlapping patterns do
+not create nested encryption layers.
+
+### Decryption
+
+Every matched leaf must satisfy the same payload, key, and exact field-path
+checks as an exact selection. A broad pattern does not silently skip plaintext
+or malformed values.
+
+### Migration
+
+Every matched leaf follows the existing fail-closed migration rules. Plaintext
+fails, selected v2 payloads require `--allow-mixed`, and legacy payloads migrate
+to v2 only after the complete selection validates. Pattern overlap does not
+inflate migration statistics.
+
+### Non-string values
+
+Pattern selection occurs before `nonStringPolicy`, matching the current exact
+selector behavior. Selected values are ignored, stringified, or rejected by
+the configured policy; unselected values remain unchanged.
+
+### YAML
+
+Patterns operate on the resolved object/array structure returned by `js-yaml`.
+Anchors, aliases, and merge keys therefore follow their independent resolved
+paths, consistent with the existing YAML rewrite contract.
+
+## Required tests
+
+- Existing exact `paths` tests remain unchanged, including literal `*` keys.
+- Exact object keys and array indexes stay distinct.
+- `*`, `[*]`, and `**` cover zero/one/many segment matches and mixed nesting.
+- Escaped dots, brackets, commas, backslashes, and literal asterisks match only
+  their intended object keys.
+- Malformed patterns fail before traversal and before CLI file reads.
+- `parentPath` is included; `pathSerializer` plus patterns fails explicitly.
+- Exact selectors and patterns form a union; duplicates and overlap process a
+  leaf once.
+- Sparse arrays, empty containers, Unicode keys, null-prototype objects, and
+  own `__proto__` keys retain their current behavior.
+- Encrypt/decrypt round trips authenticate exact leaf paths rather than pattern
+  text.
+- Wrong keys, wrong paths, malformed payloads, plaintext decrypt selections,
+  and unsafe migration selections still fail closed.
+- CLI integration tests cover JSON and YAML, escaped comma splitting, dry-run,
+  separate output, migration, and no-write failure cases.
+- TypeScript declarations, public error codes, documentation, package smoke,
+  and the installed CLI expose the same contract.
+
+## Delivery sequence
+
+1. Implement and unit-test the pattern tokenizer/compiler and matcher without
+   connecting it to config traversal.
+2. Add `pathPatterns` to `processConfig`, types, and stable errors while keeping
+   exact `paths` regression tests frozen.
+3. Add shared CLI validation plus `--path-patterns` for encrypt/decrypt.
+4. Add migration support and integration tests for atomic/no-write failures.
+5. Update public documentation and package smoke, then release the completed
+   additive feature in a minor version after full CI.

package/docs/errors.md

@@ -53,6 +53,7 @@ repeat string literals.
 | `ERR_INVALID_FIELD_PATH` | The caller supplied an invalid field path. |
 | `ERR_INVALID_OPTIONS` | Crypto options have an invalid shape or unsupported override. |
 | `ERR_INVALID_MODE` | `processConfig` received an unknown mode. |
+| `ERR_INVALID_PATH_PATTERNS` | A path pattern list or pattern syntax is invalid. |
 | `ERR_UNSUPPORTED_ALGORITHM` | The requested writer algorithm is unavailable or unsupported. |
 | `ERR_UNSUPPORTED_PAYLOAD_VERSION` | The payload or requested writer version is unsupported. |
 | `ERR_INVALID_PAYLOAD` | The payload is missing or malformed. |
@@ -63,7 +64,7 @@ repeat string literals.
 | `ERR_DECRYPTION_FAILED` | A legacy payload could not be decrypted. |
 
 `processConfig` also preserves its specific codes for invalid roots/options,
-policies, path serializers, path lists, circular input, path collisions,
+policies, path serializers, exact path lists, path patterns, circular input, path collisions,
 non-string values, unsupported values, and already encrypted values. These are
 available through `YAMLOCK_ERROR_CODES` and use `YamlockConfigError`.
 

package/docs/yaml-behavior.md

@@ -5,6 +5,9 @@ and serializes that value back to YAML. It does not edit or round-trip the
 original YAML syntax tree. A write can therefore preserve data while changing
 or removing presentation details.
 
+Empty or comment-only files are treated as empty mappings. Multiple YAML
+documents are rejected before processing or writing.
+
 ## What happens during a rewrite
 
 | YAML feature | Current behavior |
@@ -39,8 +42,9 @@ unchanged.
 
 1. Keep source YAML under version control or make a verified backup.
 2. Run with `--dry-run` to inspect the complete serialized result.
-3. Use `--paths` to select every resolved path that should be encrypted,
-   including values originally introduced through aliases or merge keys.
+3. Use exact `--paths` or structural `--path-patterns` to select every resolved
+   path that should be encrypted, including values originally introduced
+   through aliases or merge keys.
 4. Use `--output` when the source document's comments or formatting must remain
    untouched.
 5. Do not use unknown application-specific YAML tags in files processed by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamlock",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "author": "PAVEL TKACHEV (phoenixweiss) <mail@phoenixweiss.me>",
   "description": "Value-level encryption for YAML/JSON configuration files with CLI + Node.js APIs.",
   "license": "MIT",
@@ -60,11 +60,11 @@
     "js-yaml": "^4.3.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.5",
+    "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
-    "eslint": "^9.39.5",
-    "globals": "^15.0.0",
-    "rimraf": "^5.0.5",
-    "typescript": "^5.9.2"
+    "eslint": "^10.9.0",
+    "globals": "^17.11.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^7.0.2"
   }
 }