yamlock 0.2.1 → 0.2.4

package/README.md

@@ -47,10 +47,26 @@ 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
+
+# Encrypt only selected fields into a new file
+yamlock encrypt config.json --key "$YAMLOCK_KEY" --paths "db.password,api.token" --output config.secure.json
+
+# Inspect CLI metadata
+yamlock version
+yamlock algorithms
+
+# Generate a random key for YAMLOCK_KEY
+yamlock keygen --length 64 --format base64
 ```
 
 The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and writes the file back in the same format.
 
+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`).
+- Command `keygen` produces a random key and shows how to store it (shell export or `.env`).
+- Commands `version` and `algorithms` print the installed CLI version and the list of supported ciphers respectively.
+
 ### Node.js API
 
 ```js

package/dist/cli/cli.js

@@ -2,27 +2,45 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve, extname } from 'node:path';
 import { exit } from 'node:process';
+import { createRequire } from 'node:module';
+import { randomBytes } from 'node:crypto';
 
 import yaml from 'js-yaml';
 
 import { processConfig } from '../utils/config.js';
+import { listSupportedAlgorithms } from '../crypto/utils.js';
 
-const HELP_TEXT = `
+const require = createRequire(import.meta.url);
+const packageJson = require('../../package.json');
+
+const BANNER = `
 ░█░█░█▀█░█▄░▄█░█░░░█▀█░█▀▀░█░█░
 ░░█░░█▀█░█░▀░█░█░░░█░█░█░░░█▀▄░
-░░▀░░▀░▀░▀░░░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░
+░░▀░░▀░▀░▀░░░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░`;
+
+function getHelpText() {
+  return `${BANNER}
+Version: ${packageJson.version}
 
 Usage:
 yamlock <command> [options]
 
 Commands:
-  encrypt <file>   Encrypt string values in the given YAML/JSON file.
-  decrypt <file>   Decrypt string values in the given YAML/JSON file.
+  encrypt <file>       Encrypt string values in the given YAML/JSON file.
+  decrypt <file>       Decrypt string values in the given YAML/JSON file.
+  version              Print the yamlock CLI version.
+  algorithms           Print the list of supported cipher algorithms.
+  keygen               Generate a random YAMLOCK_KEY.
 
 Options:
   -k, --key <value>        Encryption key (or use YAMLOCK_KEY env).
   -a, --algorithm <value>  Cipher algorithm (default: aes-256-cbc).
+  -o, --output <file>      Write the result to a different file (otherwise overwrites the input file).
+  -p, --paths <p1,p2>      Comma-separated list of field paths to process (dot/bracket notation).
+  --length <bytes>         (keygen) Number of random bytes to generate (default: 32).
+  --format <hex|base64>    (keygen) Output format (default: base64).
 `;
+}
 
 function print(message) {
   console.log(message);
@@ -63,15 +81,35 @@ function writeConfigFile(filePath, format, data) {
   writeFileSync(filePath, `${serialized}\n`, 'utf8');
 }
 
+function parsePaths(value) {
+  if (!value) {
+    return [];
+  }
+
+  return String(value)
+    .split(',')
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+}
+
 function parseArgs(argv) {
   const args = argv.slice(2);
   const result = {
     command: args[0],
-    file: args[1],
+    file: undefined,
     options: {}
   };
 
-  for (let i = 2; i < args.length; i += 1) {
+  let index = 1;
+  const potentialFile = args[1];
+  if (potentialFile && !potentialFile.startsWith('-')) {
+    result.file = potentialFile;
+    index = 2;
+  } else {
+    index = 1;
+  }
+
+  for (let i = index; i < args.length; i += 1) {
     const arg = args[i];
     const next = args[i + 1];
 
@@ -81,17 +119,79 @@ function parseArgs(argv) {
     } else if (arg === '-a' || arg === '--algorithm') {
       result.options.algorithm = next;
       i += 1;
+    } else if (arg === '-o' || arg === '--output') {
+      result.options.output = next;
+      i += 1;
+    } else if (arg === '-p' || arg === '--paths') {
+      result.options.paths = parsePaths(next);
+      i += 1;
+    } else if (arg === '--length') {
+      result.options.length = next;
+      i += 1;
+    } else if (arg === '--format') {
+      result.options.format = next;
+      i += 1;
     }
   }
 
   return result;
 }
 
+function generateRandomKey(length, format) {
+  const size = Number.isFinite(length) && length > 0 ? Math.floor(length) : 32;
+  const buffer = randomBytes(size);
+  if (format === 'hex') {
+    return buffer.toString('hex');
+  }
+  return buffer.toString('base64');
+}
+
 export async function runCli(argv = process.argv) {
   const { command, file, options } = parseArgs(argv);
 
-  if (!command || !file) {
-    print(HELP_TEXT.trim());
+  if (!command) {
+    print(getHelpText().trim());
+    return exit(1);
+  }
+
+  if (command === 'version') {
+    print(`yamlock ${packageJson.version}`);
+    return exit(0);
+  }
+
+  if (command === 'algorithms') {
+    const algorithms = listSupportedAlgorithms();
+    print('Supported algorithms:');
+    algorithms.forEach((name) => print(`- ${name}`));
+    return exit(0);
+  }
+
+  if (command === 'keygen') {
+    const desiredLength = options.length ? Number(options.length) : 32;
+    const normalizedFormat = (options.format ?? 'base64').toLowerCase();
+
+    if (!Number.isFinite(desiredLength) || desiredLength <= 0) {
+      printError('Key length must be a positive number.');
+      return exit(1);
+    }
+
+    if (!['base64', 'hex'].includes(normalizedFormat)) {
+      printError('Key format must be either "base64" or "hex".');
+      return exit(1);
+    }
+
+    const keyValue = generateRandomKey(desiredLength, normalizedFormat);
+    print(`Generated key (${normalizedFormat}, ${Math.floor(desiredLength)} bytes of entropy):`);
+    print(keyValue);
+    print('\nStore it securely, e.g.');
+    print(`  export YAMLOCK_KEY="${keyValue}"`);
+    print('  # or place in an .env file as YAMLOCK_KEY=your-key');
+    return exit(0);
+  }
+
+  if (!file) {
+    printError('A file path is required for this command.');
+    print(getHelpText().trim());
     return exit(1);
   }
 
@@ -110,23 +210,37 @@ export async function runCli(argv = process.argv) {
     return exit(1);
   }
 
+  const outputPath = options.output
+    ? resolve(process.cwd(), options.output)
+    : absolutePath;
+
   try {
     if (command === 'encrypt') {
-      const result = processConfig(config.data, { mode: 'encrypt', key, algorithm: options.algorithm });
-      writeConfigFile(absolutePath, config.format, result);
-      print(`Encrypted values in ${file}`);
+      const result = processConfig(config.data, {
+        mode: 'encrypt',
+        key,
+        algorithm: options.algorithm,
+        paths: options.paths
+      });
+      writeConfigFile(outputPath, config.format, result);
+      print(`Encrypted values in ${outputPath === absolutePath ? file : options.output}`);
       return exit(0);
     }
 
     if (command === 'decrypt') {
-      const result = processConfig(config.data, { mode: 'decrypt', key });
-      writeConfigFile(absolutePath, config.format, result);
-      print(`Decrypted values in ${file}`);
+      const result = processConfig(config.data, {
+        mode: 'decrypt',
+        key,
+        algorithm: options.algorithm,
+        paths: options.paths
+      });
+      writeConfigFile(outputPath, config.format, result);
+      print(`Decrypted values in ${outputPath === absolutePath ? file : options.output}`);
       return exit(0);
     }
 
     printError(`Unknown command: ${command}`);
-    print(HELP_TEXT.trim());
+    print(getHelpText().trim());
     return exit(1);
   } catch (error) {
     printError(`Operation failed: ${error.message}`);

package/dist/utils/config.js

@@ -15,18 +15,33 @@ const MODES = {
  * @param {string|Buffer} options.key
  * @param {string|object} [options.algorithm]
  * @param {object} [options.algorithmOptions]
+ * @param {string[]} [options.paths]
  * @param {Array<string|number>} [options.parentPath]
  * @returns {Object|Array}
  */
-export function processConfig(node, { mode, key, algorithm, algorithmOptions, parentPath = [] }) {
+export function processConfig(node, options) {
   if (typeof node !== 'object' || node === null) {
     throw new Error('processConfig expects a non-null object or array.');
   }
 
+  const mode = options.mode;
   if (mode !== MODES.ENCRYPT && mode !== MODES.DECRYPT) {
     throw new Error(`Unknown processConfig mode: ${mode}`);
   }
 
+  const normalizedPaths = Array.isArray(options.paths) && options.paths.length > 0
+    ? new Set(options.paths.map((path) => String(path).trim()).filter(Boolean))
+    : null;
+
+  return traverseConfig(node, {
+    ...options,
+    mode,
+    parentPath: options.parentPath ?? [],
+    normalizedPaths
+  });
+}
+
+function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPath, normalizedPaths }) {
   const isArrayNode = Array.isArray(node);
   const result = isArrayNode ? [] : {};
   const cryptoOptions = algorithmOptions ?? algorithm;
@@ -37,12 +52,13 @@ export function processConfig(node, { mode, key, algorithm, algorithmOptions, pa
     const currentPath = buildPath(parentPath, segment);
 
     if (value !== null && typeof value === 'object') {
-      result[targetKey] = processConfig(value, {
+      result[targetKey] = traverseConfig(value, {
         mode,
         key,
         algorithm: cryptoOptions,
         algorithmOptions: cryptoOptions,
-        parentPath: [...parentPath, segment]
+        parentPath: [...parentPath, segment],
+        normalizedPaths
       });
       return;
     }
@@ -52,6 +68,12 @@ export function processConfig(node, { mode, key, algorithm, algorithmOptions, pa
       return;
     }
 
+    const shouldProcess = !normalizedPaths || normalizedPaths.has(currentPath);
+    if (!shouldProcess) {
+      result[targetKey] = value;
+      return;
+    }
+
     if (mode === MODES.ENCRYPT) {
       result[targetKey] = encryptValue(value, key, currentPath, cryptoOptions);
     } else {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yamlock",
-  "version": "0.2.1",
-  "author": "PAVEL TKACHEV",
+  "version": "0.2.4",
+  "author": "PAVEL TKACHEV (phoenixweiss) <mail@phoenixweiss.me>",
   "description": "Value-level encryption for YAML/JSON configuration files with CLI + Node.js APIs.",
   "license": "MIT",
   "type": "module",