yamlock 0.3.0 → 1.1.0

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/dist/utils/path.js

@@ -1,15 +1,46 @@
+import {
+  YAMLOCK_ERROR_CODES,
+  YamlockValidationError
+} from '../errors.js';
+
+const RESERVED_PATH_CHARACTERS = new Set(['\\', '.', '[', ']', ',']);
+
+function validateSegments(segments, functionName) {
+  if (!Array.isArray(segments) || segments.length === 0) {
+    throw new YamlockValidationError(
+      `${functionName} requires a non-empty segments array.`,
+      { code: YAMLOCK_ERROR_CODES.INVALID_PATH_SEGMENTS }
+    );
+  }
+
+  const invalid = segments.some((segment) => (
+    (typeof segment !== 'string' || segment.length === 0) &&
+    (!Number.isInteger(segment) || segment < 0)
+  ));
+  if (invalid) {
+    throw new YamlockValidationError(
+      'Path segments must be non-empty strings or non-negative integers.',
+      { code: YAMLOCK_ERROR_CODES.INVALID_PATH_SEGMENTS }
+    );
+  }
+}
+
+function escapeStringSegment(segment) {
+  return [...segment]
+    .map((character) => RESERVED_PATH_CHARACTERS.has(character) ? `\\${character}` : character)
+    .join('');
+}
+
 /**
- * Builds a dot/bracket path string that uniquely identifies a value
- * inside a nested object/array structure.
- * Example: ["db", "users", 0, "password"] => "db.users[0].password"
+ * Builds a canonical dot/bracket path that uniquely identifies a value.
+ * Reserved characters in object keys are escaped with a backslash.
+ * Example: ["db.settings", "users", 0] => "db\\.settings.users[0]"
  *
  * @param {Array<string|number>} segments
  * @returns {string}
  */
 export function serializePath(segments) {
-  if (!Array.isArray(segments) || segments.length === 0) {
-    throw new Error('serializePath requires a non-empty segments array.');
-  }
+  validateSegments(segments, 'serializePath');
 
   return segments
     .map((segment, index) => {
@@ -17,11 +48,29 @@ export function serializePath(segments) {
         return `[${segment}]`;
       }
 
-      if (typeof segment === 'string' && segment.length > 0) {
-        return index === 0 ? segment : `.${segment}`;
+      const escaped = escapeStringSegment(segment);
+      return index === 0 ? escaped : `.${escaped}`;
+    })
+    .join('');
+}
+
+/**
+ * Reproduces the path representation written by yamlock before escaping was
+ * introduced. This is used only to read existing payloads.
+ *
+ * @param {Array<string|number>} segments
+ * @returns {string}
+ */
+export function serializeLegacyPath(segments) {
+  validateSegments(segments, 'serializeLegacyPath');
+
+  return segments
+    .map((segment, index) => {
+      if (typeof segment === 'number') {
+        return `[${segment}]`;
       }
 
-      throw new Error('Path segments must be non-empty strings or numbers.');
+      return index === 0 ? segment : `.${segment}`;
     })
     .join('');
 }

package/docs/api.md

@@ -0,0 +1,63 @@
+# Public Node.js API
+
+yamlock `1.x` exposes one ESM entry point. The supported package exports are:
+
+- `encryptValue(value, key, fieldPath, options?)`
+- `decryptValue(payload, key, fieldPath, options?)`
+- `processConfig(config, options)`
+- `serializePath(segments)`
+- `getSupportedAlgorithms()`
+- `YAMLOCK_ERROR_CODES` and the documented `YamlockError` class hierarchy
+
+The package includes TypeScript declarations for these values and for their
+options, path segments, keys, config containers, and error codes. Internal files
+under `dist/` are implementation details and are intentionally unavailable as
+package subpath exports.
+
+## Stability contract for 1.x
+
+- The default writer produces authenticated v2 payloads. Their serialized
+  fields, KDF profile, limits, and field-path binding remain compatible
+  throughout `1.x`.
+- Legacy payload reading remains available throughout `1.x`. Explicit legacy
+  writing through `formatVersion: 1`, legacy algorithm options, or CLI
+  `--legacy` is a deprecated compatibility path, but will not be removed before
+  a future major release.
+- Canonical path serialization and the legacy-path read fallback remain
+  compatible throughout `1.x`.
+- Existing exports, documented option names, return types, error classes, and
+  error codes will not be removed or incompatibly redefined in a minor or patch
+  release.
+- New optional exports, options, and error codes may be added in a minor
+  release. Human-readable error messages may be clarified without changing the
+  stable error code.
+- The synchronous API remains supported. A future async API, if added, will be
+  additive rather than replacing the synchronous functions in `1.x`.
+
+## Crypto options
+
+With no crypto options, `encryptValue` and `processConfig` write v2 payloads.
+V2 accepts `formatVersion: 2` and the fixed `aes-256-gcm` profile; free-form
+algorithm sizing is rejected.
+
+Legacy compatibility accepts `formatVersion: 1`, an algorithm string, or an
+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`, 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.