yamlock 0.2.3 → 0.2.4

package/README.md

@@ -54,6 +54,9 @@ yamlock encrypt config.json --key "$YAMLOCK_KEY" --paths "db.password,api.token"
 # 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.
@@ -61,6 +64,7 @@ The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and writ
 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

package/dist/cli/cli.js

@@ -3,6 +3,7 @@ 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';
 
@@ -12,10 +13,14 @@ import { listSupportedAlgorithms } from '../crypto/utils.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../../package.json');
 
-const HELP_TEXT = `
+const BANNER = `
 ░█░█░█▀█░█▄░▄█░█░░░█▀█░█▀▀░█░█░
 ░░█░░█▀█░█░▀░█░█░░░█░█░█░░░█▀▄░
-░░▀░░▀░▀░▀░░░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░
+░░▀░░▀░▀░▀░░░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░`;
+
+function getHelpText() {
+  return `${BANNER}
+Version: ${packageJson.version}
 
 Usage:
 yamlock <command> [options]
@@ -25,13 +30,17 @@ Commands:
   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);
@@ -87,11 +96,20 @@ 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];
 
@@ -107,17 +125,32 @@ function parseArgs(argv) {
     } 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) {
-    print(HELP_TEXT.trim());
+    print(getHelpText().trim());
     return exit(1);
   }
 
@@ -133,9 +166,32 @@ export async function runCli(argv = process.argv) {
     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(HELP_TEXT.trim());
+    print(getHelpText().trim());
     return exit(1);
   }
 
@@ -184,7 +240,7 @@ export async function runCli(argv = process.argv) {
     }
 
     printError(`Unknown command: ${command}`);
-    print(HELP_TEXT.trim());
+    print(getHelpText().trim());
     return exit(1);
   } catch (error) {
     printError(`Operation failed: ${error.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamlock",
-  "version": "0.2.3",
+  "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",