yamlock 0.2.9 → 1.0.0

package/dist/utils/config.js

@@ -1,12 +1,142 @@
 import { encryptValue } from '../crypto/encrypt.js';
 import { decryptValue } from '../crypto/decrypt.js';
-import { buildPath } from './path.js';
+import { detectPayloadVersion } from '../crypto/payload-v2.js';
+import { isYamlockPayload } from '../crypto/utils.js';
+import { YamlockConfigError } from '../errors.js';
+import { serializeLegacyPath, serializePath } from './path.js';
 
 const MODES = {
   ENCRYPT: 'encrypt',
   DECRYPT: 'decrypt'
 };
 
+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 isConfigContainer(value) {
+  if (Array.isArray(value)) {
+    return true;
+  }
+
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function createResultContainer(node) {
+  return Array.isArray(node)
+    ? new Array(node.length)
+    : Object.create(Object.getPrototypeOf(node));
+}
+
+function setResultValue(result, key, value) {
+  Object.defineProperty(result, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true
+  });
+}
+
+function validatePathSegments(segments, optionName) {
+  if (!Array.isArray(segments)) {
+    throw createConfigError(
+      'ERR_INVALID_PATH_SEGMENTS',
+      `${optionName} must be an array of non-empty strings or non-negative integers.`
+    );
+  }
+
+  const hasInvalidSegment = segments.some((segment) => (
+    (typeof segment !== 'string' || segment.length === 0) &&
+    (!Number.isInteger(segment) || segment < 0)
+  ));
+  if (hasInvalidSegment) {
+    throw createConfigError(
+      'ERR_INVALID_PATH_SEGMENTS',
+      `${optionName} must contain only non-empty strings or non-negative integers.`
+    );
+  }
+}
+
+function normalizePaths(paths) {
+  if (paths === undefined || (Array.isArray(paths) && paths.length === 0)) {
+    return null;
+  }
+
+  if (!Array.isArray(paths)) {
+    throw createConfigError('ERR_INVALID_PATHS', 'paths must be an array of non-empty strings.');
+  }
+
+  const normalized = paths.map((path) => {
+    if (typeof path !== 'string' || path.trim().length === 0) {
+      throw createConfigError('ERR_INVALID_PATHS', 'paths must contain only non-empty strings.');
+    }
+    return path.trim();
+  });
+  return new Set(normalized);
+}
+
+function resolveCurrentPaths(segments, pathSerializer) {
+  let currentPath;
+  try {
+    currentPath = pathSerializer
+      ? pathSerializer([...segments])
+      : serializePath(segments);
+  } catch (error) {
+    throw createConfigError(
+      pathSerializer ? 'ERR_INVALID_PATH_SERIALIZER' : 'ERR_INVALID_PATH_SEGMENTS',
+      `Failed to serialize config path: ${error.message}`
+    );
+  }
+
+  if (typeof currentPath !== 'string' || currentPath.length === 0) {
+    throw createConfigError(
+      'ERR_INVALID_PATH_SERIALIZER',
+      'pathSerializer must return a non-empty string.'
+    );
+  }
+
+  return {
+    currentPath,
+    legacyPath: pathSerializer ? null : serializeLegacyPath(segments)
+  };
+}
+
+function decryptConfigValue(value, key, currentPath, legacyPath, cryptoOptions) {
+  try {
+    return decryptValue(value, key, currentPath, cryptoOptions);
+  } catch (error) {
+    if (!legacyPath || legacyPath === currentPath) {
+      throw error;
+    }
+
+    return decryptValue(value, key, legacyPath, cryptoOptions);
+  }
+}
+
+function stringifyConfigLeaf(value, currentPath) {
+  const isJsonPrimitive = (
+    value === null ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value))
+  );
+  if (!isJsonPrimitive) {
+    throw createConfigError(
+      'ERR_UNSUPPORTED_CONFIG_VALUE',
+      `Value at ${currentPath} cannot be stringified without an explicit conversion.`
+    );
+  }
+
+  return JSON.stringify(value);
+}
+
 /**
  * Recursively processes a config object or array, encrypting/decrypting string values.
  * @param {Object|Array} node
@@ -15,71 +145,195 @@ const MODES = {
  * @param {string|Buffer} options.key
  * @param {string|object} [options.algorithm]
  * @param {object} [options.algorithmOptions]
+ * @param {1|2} [options.formatVersion]
+ * @param {"ignore"|"stringify"|"error"} [options.nonStringPolicy]
+ * @param {"preserve"|"error"|"encrypt"} [options.existingPayloadPolicy]
+ * @param {(segments: Array<string|number>) => string} [options.pathSerializer]
  * @param {string[]} [options.paths]
  * @param {Array<string|number>} [options.parentPath]
  * @returns {Object|Array}
  */
 export function processConfig(node, options) {
-  if (typeof node !== 'object' || node === null) {
-    throw new Error('processConfig expects a non-null object or array.');
+  if (!isConfigContainer(node)) {
+    throw createConfigError(
+      'ERR_INVALID_CONFIG_ROOT',
+      'processConfig expects an array or plain object.'
+    );
+  }
+
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw createConfigError('ERR_INVALID_CONFIG_OPTIONS', 'processConfig options must be an object.');
   }
 
   const mode = options.mode;
   if (mode !== MODES.ENCRYPT && mode !== MODES.DECRYPT) {
-    throw new Error(`Unknown processConfig mode: ${mode}`);
+    throw createConfigError('ERR_INVALID_MODE', `Unknown processConfig mode: ${mode}`);
+  }
+
+  if (mode !== MODES.ENCRYPT && options.existingPayloadPolicy !== undefined) {
+    throw createConfigError(
+      'ERR_INVALID_EXISTING_PAYLOAD_POLICY',
+      'existingPayloadPolicy is available only in encrypt mode.'
+    );
   }
 
-  const normalizedPaths = Array.isArray(options.paths) && options.paths.length > 0
-    ? new Set(options.paths.map((path) => String(path).trim()).filter(Boolean))
-    : null;
+  const nonStringPolicy = options.nonStringPolicy ?? 'ignore';
+  if (!NON_STRING_POLICIES.has(nonStringPolicy)) {
+    throw createConfigError(
+      'ERR_INVALID_NON_STRING_POLICY',
+      `Unknown nonStringPolicy: ${nonStringPolicy}`
+    );
+  }
+
+  if (options.pathSerializer !== undefined && typeof options.pathSerializer !== 'function') {
+    throw createConfigError(
+      'ERR_INVALID_PATH_SERIALIZER',
+      'pathSerializer must be a function.'
+    );
+  }
+
+  const parentPath = options.parentPath ?? [];
+  validatePathSegments(parentPath, 'parentPath');
+  const normalizedPaths = normalizePaths(options.paths);
+  const existingPayloadPolicy = options.existingPayloadPolicy ?? 'preserve';
+  if (!EXISTING_PAYLOAD_POLICIES.has(existingPayloadPolicy)) {
+    throw createConfigError(
+      'ERR_INVALID_EXISTING_PAYLOAD_POLICY',
+      `Unknown existingPayloadPolicy: ${existingPayloadPolicy}`
+    );
+  }
 
   return traverseConfig(node, {
     ...options,
     mode,
-    parentPath: options.parentPath ?? [],
-    normalizedPaths
+    parentPath,
+    normalizedPaths,
+    nonStringPolicy,
+    existingPayloadPolicy,
+    pathSerializer: options.pathSerializer,
+    ancestors: new WeakSet(),
+    seenPaths: new Set()
   });
 }
 
-function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPath, normalizedPaths }) {
+function traverseConfig(node, { mode, key, algorithm, algorithmOptions, formatVersion, parentPath, normalizedPaths, nonStringPolicy, existingPayloadPolicy, pathSerializer, ancestors, seenPaths }) {
   const isArrayNode = Array.isArray(node);
-  const result = isArrayNode ? [] : {};
-  const cryptoOptions = algorithmOptions ?? algorithm;
-
-  Object.entries(node).forEach(([rawKey, value]) => {
-    const segment = isArrayNode ? Number(rawKey) : rawKey;
-    const targetKey = isArrayNode ? segment : rawKey;
-    const currentPath = buildPath(parentPath, segment);
-
-    if (value !== null && typeof value === 'object') {
-      result[targetKey] = traverseConfig(value, {
-        mode,
-        key,
-        algorithm: cryptoOptions,
-        algorithmOptions: cryptoOptions,
-        parentPath: [...parentPath, segment],
-        normalizedPaths
-      });
-      return;
-    }
+  const result = createResultContainer(node);
+  const selectedCryptoOptions = algorithmOptions ?? algorithm;
+  const cryptoOptions = formatVersion === undefined
+    ? selectedCryptoOptions
+    : typeof selectedCryptoOptions === 'object' && selectedCryptoOptions !== null
+      ? { ...selectedCryptoOptions, formatVersion }
+      : { algorithm: selectedCryptoOptions, formatVersion };
 
-    if (typeof value !== 'string') {
-      result[targetKey] = value;
-      return;
-    }
+  ancestors.add(node);
+  try {
+    for (const [rawKey, originalValue] of Object.entries(node)) {
+      const segment = isArrayNode ? Number(rawKey) : rawKey;
+      const targetKey = isArrayNode ? segment : rawKey;
+      const pathSegments = [...parentPath, segment];
+      const { currentPath, legacyPath } = resolveCurrentPaths(pathSegments, pathSerializer);
 
-    const shouldProcess = !normalizedPaths || normalizedPaths.has(currentPath);
-    if (!shouldProcess) {
-      result[targetKey] = value;
-      return;
-    }
+      if (isConfigContainer(originalValue)) {
+        if (ancestors.has(originalValue)) {
+          throw createConfigError(
+            'ERR_CIRCULAR_CONFIG',
+            `Circular reference encountered at ${currentPath}.`
+          );
+        }
+
+        setResultValue(result, targetKey, traverseConfig(originalValue, {
+          mode,
+          key,
+          algorithm: cryptoOptions,
+          algorithmOptions: cryptoOptions,
+          parentPath: pathSegments,
+          normalizedPaths,
+          nonStringPolicy,
+          existingPayloadPolicy,
+          pathSerializer,
+          ancestors,
+          seenPaths
+        }));
+        continue;
+      }
+
+      if (seenPaths.has(currentPath)) {
+        throw createConfigError(
+          'ERR_PATH_COLLISION',
+          `Multiple config values resolve to the path ${currentPath}.`
+        );
+      }
+      seenPaths.add(currentPath);
+
+      const shouldProcess = !normalizedPaths || normalizedPaths.has(currentPath);
+      if (!shouldProcess) {
+        setResultValue(result, targetKey, originalValue);
+        continue;
+      }
+
+      let value = originalValue;
+      if (typeof value !== 'string') {
+        if (nonStringPolicy === 'ignore') {
+          setResultValue(result, targetKey, value);
+          continue;
+        }
 
-    if (mode === MODES.ENCRYPT) {
-      result[targetKey] = encryptValue(value, key, currentPath, cryptoOptions);
-    } else {
-      result[targetKey] = decryptValue(value, key, currentPath, cryptoOptions);
+        if (nonStringPolicy === 'error' || mode === MODES.DECRYPT) {
+          throw createConfigError(
+            'ERR_NON_STRING_VALUE',
+            `Non-string value encountered at ${currentPath}.`
+          );
+        }
+
+        value = stringifyConfigLeaf(value, currentPath);
+      }
+
+      if (mode === MODES.ENCRYPT) {
+        if (isYamlockPayload(value)) {
+          if (existingPayloadPolicy === 'encrypt') {
+            setResultValue(
+              result,
+              targetKey,
+              encryptValue(value, key, currentPath, cryptoOptions)
+            );
+            continue;
+          }
+
+          const payloadVersion = detectPayloadVersion(value);
+          decryptConfigValue(
+            value,
+            key,
+            currentPath,
+            legacyPath,
+            payloadVersion === 1 ? cryptoOptions : undefined
+          );
+
+          if (existingPayloadPolicy === 'error') {
+            throw createConfigError(
+              'ERR_ALREADY_ENCRYPTED',
+              `Selected value at ${currentPath} is already encrypted.`
+            );
+          }
+
+          setResultValue(result, targetKey, value);
+          continue;
+        }
+
+        setResultValue(result, targetKey, encryptValue(value, key, currentPath, cryptoOptions));
+      } else {
+        setResultValue(result, targetKey, decryptConfigValue(
+          value,
+          key,
+          currentPath,
+          legacyPath,
+          cryptoOptions
+        ));
+      }
     }
-  });
 
-  return result;
+    return result;
+  } finally {
+    ancestors.delete(node);
+  }
 }

package/dist/utils/file.js

@@ -0,0 +1,58 @@
+import {
+  closeSync,
+  fchmodSync,
+  fsyncSync,
+  linkSync,
+  openSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Writes a file through an exclusive temporary file in the destination
+ * directory and atomically installs it at the requested path.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @param {{mode?: number, refuseExisting?: boolean}} [options]
+ */
+export function writeFileAtomically(filePath, content, { mode, refuseExisting = false } = {}) {
+  const temporaryPath = join(
+    dirname(filePath),
+    `.${basename(filePath)}.yamlock-${process.pid}-${randomBytes(8).toString('hex')}.tmp`
+  );
+  let fileDescriptor;
+
+  try {
+    fileDescriptor = openSync(temporaryPath, 'wx', 0o600);
+    writeFileSync(fileDescriptor, content, 'utf8');
+    if (mode !== undefined) {
+      fchmodSync(fileDescriptor, mode);
+    }
+    fsyncSync(fileDescriptor);
+    closeSync(fileDescriptor);
+    fileDescriptor = undefined;
+
+    if (refuseExisting) {
+      linkSync(temporaryPath, filePath);
+      unlinkSync(temporaryPath);
+      return;
+    }
+
+    renameSync(temporaryPath, filePath);
+  } catch (error) {
+    if (fileDescriptor !== undefined) {
+      closeSync(fileDescriptor);
+    }
+
+    try {
+      unlinkSync(temporaryPath);
+    } catch {
+      // The temporary file may not exist or may already have been installed.
+    }
+    throw error;
+  }
+}

package/dist/utils/migrate.js

@@ -0,0 +1,170 @@
+import { decryptValue } from '../crypto/decrypt.js';
+import { encryptValue } from '../crypto/encrypt.js';
+import {
+  detectPayloadVersion,
+  V2_FORMAT_VERSION
+} from '../crypto/payload-v2.js';
+import { isYamlockPayload } from '../crypto/utils.js';
+import { serializeLegacyPath, serializePath } from './path.js';
+
+function createMigrationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function normalizePaths(paths) {
+  return Array.isArray(paths) && paths.length > 0
+    ? new Set(paths.map((path) => String(path).trim()).filter(Boolean))
+    : null;
+}
+
+function setResultValue(result, key, value) {
+  Object.defineProperty(result, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true
+  });
+}
+
+function decryptMigrationValue(value, key, currentPath, legacyPath) {
+  try {
+    return decryptValue(value, key, currentPath);
+  } catch (error) {
+    if (legacyPath === currentPath) {
+      throw error;
+    }
+
+    return decryptValue(value, key, legacyPath);
+  }
+}
+
+function traverse(node, context) {
+  const isArrayNode = Array.isArray(node);
+  const result = isArrayNode ? new Array(node.length) : {};
+
+  Object.entries(node).forEach(([rawKey, value]) => {
+    const segment = isArrayNode ? Number(rawKey) : rawKey;
+    const targetKey = isArrayNode ? segment : rawKey;
+    const pathSegments = [...context.parentPath, segment];
+    const currentPath = serializePath(pathSegments);
+    const legacyPath = serializeLegacyPath(pathSegments);
+
+    if (value !== null && typeof value === 'object') {
+      setResultValue(result, targetKey, traverse(value, {
+        ...context,
+        parentPath: pathSegments
+      }));
+      return;
+    }
+
+    const selected = !context.paths || context.paths.has(currentPath);
+    if (!selected) {
+      setResultValue(result, targetKey, value);
+      return;
+    }
+
+    context.stats.selected += 1;
+
+    if (typeof value !== 'string') {
+      throw createMigrationError(
+        'ERR_MIGRATION_NON_STRING',
+        `Selected value at ${currentPath} is not a string.`
+      );
+    }
+
+    if (!isYamlockPayload(value)) {
+      throw createMigrationError(
+        'ERR_MIGRATION_PLAINTEXT',
+        `Selected value at ${currentPath} is not encrypted; narrow --paths to legacy payloads.`
+      );
+    }
+
+    const version = detectPayloadVersion(value);
+    if (version === V2_FORMAT_VERSION) {
+      if (!context.allowMixed) {
+        throw createMigrationError(
+          'ERR_MIGRATION_ALREADY_V2',
+          `Selected value at ${currentPath} is already v2; use --allow-mixed to authenticate and preserve it.`
+        );
+      }
+
+      decryptMigrationValue(value, context.key, currentPath, legacyPath);
+      setResultValue(result, targetKey, value);
+      context.stats.preservedV2 += 1;
+      return;
+    }
+
+    if (version !== 1) {
+      throw createMigrationError(
+        'ERR_MIGRATION_UNSUPPORTED_VERSION',
+        `Selected value at ${currentPath} uses unsupported payload version ${version}.`
+      );
+    }
+
+    const plaintext = decryptMigrationValue(value, context.key, currentPath, legacyPath);
+    setResultValue(
+      result,
+      targetKey,
+      encryptValue(plaintext, context.key, currentPath, {
+        formatVersion: V2_FORMAT_VERSION
+      })
+    );
+    context.stats.migrated += 1;
+  });
+
+  return result;
+}
+
+/**
+ * Validates selected encrypted values and migrates legacy payloads to v2.
+ * The input object is not mutated.
+ * @param {Object|Array} node
+ * @param {Object} options
+ * @param {string|Buffer} options.key
+ * @param {string[]} [options.paths]
+ * @param {boolean} [options.allowMixed=false]
+ * @returns {{ data: Object|Array, changed: boolean, stats: { selected: number, migrated: number, preservedV2: number } }}
+ */
+export function migrateConfig(node, options) {
+  if (typeof node !== 'object' || node === null) {
+    throw createMigrationError(
+      'ERR_MIGRATION_INPUT',
+      'migrateConfig expects a non-null object or array.'
+    );
+  }
+
+  if (typeof options !== 'object' || options === null) {
+    throw createMigrationError(
+      'ERR_MIGRATION_OPTIONS',
+      'migrateConfig expects an options object.'
+    );
+  }
+
+  const stats = {
+    selected: 0,
+    migrated: 0,
+    preservedV2: 0
+  };
+  const data = traverse(node, {
+    key: options.key,
+    paths: normalizePaths(options.paths),
+    allowMixed: options.allowMixed === true,
+    parentPath: [],
+    stats
+  });
+
+  if (stats.migrated === 0 && stats.preservedV2 === 0) {
+    throw createMigrationError(
+      'ERR_MIGRATION_NOTHING_TO_DO',
+      'No selected encrypted values were found to migrate.'
+    );
+  }
+
+  return {
+    data,
+    changed: stats.migrated > 0,
+    stats
+  };
+}

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('');
 }