yamlock 0.1.1 → 0.2.0

package/README.md

@@ -13,27 +13,29 @@ Value-level encryption for YAML and JSON configuration files. The name **yamlock
 - Node.js 22.x via `asdf`
 - Yarn Classic (1.x)
 
-## Current status
+## Installation
 
-- Package metadata, linting config, and MIT license are in place.
-- Core crypto helpers (`encryptValue`, `decryptValue`, and supporting utils) work with per-field salts and have unit tests.
-- `processConfig` can walk nested objects/arrays and apply encryption/decryption to every string value.
-- Public API exports (`encryptValue`, `decryptValue`, `processConfig`, `getSupportedAlgorithms`) are wired and verified by tests.
-- Directory structure for source, CLI, tests, and examples exists.
-- CLI binary can encrypt/decrypt YAML and JSON files by calling `processConfig`.
+### npm
 
-## Working locally
+```bash
+npm install -g yamlock      # CLI usage
+npm install yamlock         # project dependency
+```
+
+### Yarn Classic
 
-1. Install the toolchain: `asdf install nodejs 22` and `yarn set version classic` if needed.
-2. Install dependencies with `yarn install`.
-3. Use the scripts below during development.
+```bash
+yarn global add yamlock     # CLI usage
+yarn add yamlock            # project dependency
+```
 
-## Available scripts
+## Features
 
-- `yarn build` — copies the current `src` tree into `dist` (temporary until a real build pipeline appears).
-- `yarn prepare` — invokes `yarn build` automatically when installing from git.
-- `yarn test` — runs Node built-in test runner.
-- `yarn lint` — executes ESLint with the provided config.
+- Encrypt/decrypt individual configuration values with deterministic field-path salts.
+- CLI workflow that processes YAML or JSON files in place.
+- Recursively lock/unlock entire objects via `processConfig`.
+- Public API exports that mirror CLI behavior for programmatic use.
+- Focus on Node.js 22+, ESM modules, and a lightweight dependency set (`js-yaml`).
 
 ## Usage
 
@@ -64,6 +66,49 @@ const unlocked = processConfig(locked, { mode: 'decrypt', key: process.env.YAMLO
 
 See `examples/basic.js` for a runnable end-to-end script (`node examples/basic.js`).
 
+### Algorithm customization
+
+Each function accepts either a cipher name or an options object:
+
+```js
+const encrypted = encryptValue('swordfish', KEY, 'db.password', {
+  algorithm: 'chacha20-poly1305',
+  ivLength: 12 // override the IV size used during encryption
+});
+
+// When decrypting, the algorithm is inferred from the payload,
+// but you can still override key/IV sizes if the cipher requires it.
+const decrypted = decryptValue(encrypted, KEY, 'db.password', /* optional overrides */);
+
+// processConfig propagates the same options through every nested field.
+const processed = processConfig(
+  { db: { password: 'swordfish' }, api: { token: 'secret' } },
+  {
+    mode: 'encrypt',
+    key: KEY,
+    algorithm: { algorithm: 'aes-192-cbc', ivLength: 24 }
+  }
+);
+
+// Later you can decrypt with the same options:
+const restored = processConfig(processed, {
+  mode: 'decrypt',
+  key: KEY,
+  algorithm: { algorithm: 'aes-192-cbc', ivLength: 24 }
+});
+```
+
+### Supported algorithms
+
+| Algorithm | Type | Notes |
+|-----------|------|-------|
+| `aes-128-cbc` | Block cipher (CBC) | 128-bit keys, 16-byte IV. Works well for backward-compatibility scenarios. |
+| `aes-192-cbc` | Block cipher (CBC) | 192-bit keys, 16-byte IV. Slightly stronger than AES-128 with the same IV requirements. |
+| `aes-256-cbc` (default) | Block cipher (CBC) | 256-bit keys, 16-byte IV. Balanced combination of strength and compatibility. |
+| `chacha20-poly1305` | AEAD stream cipher | 256-bit keys, 12-byte nonce, 16-byte auth tag. Provides built-in integrity/authentication. |
+
+You can also pass any algorithm supported by the current Node.js runtime (`crypto.getCiphers()`), along with custom `keyLength`, `ivLength`, or `authTagLength` overrides. Only the algorithms above are actively tested; additional presets may be added or revised in future releases.
+
 ### Encrypted value format
 
 Every locked string follows the format:
@@ -72,25 +117,19 @@ Every locked string follows the format:
 yl|<algorithm>|<salt_base64>|<iv_base64>|<data_base64>
 ```
 
-where the salt is derived from the full field path. Moving or renaming the field invalidates the salt, preventing accidental decryption in the wrong location.
+Where:
+- `yl` - format marker prefix
+- `<algorithm>` - algorithm name (e.g., aes-256-cbc)
+- `<salt_base64>` - Base64-encoded field path
+- `<iv_base64>` - Base64-encoded initialization vector
+- `<data_base64>` - Base64-encoded encrypted data
+
+The salt is derived from the full field path. Moving or renaming the field invalidates the salt, preventing accidental decryption in the wrong location.
 
 ### Key rotation
 
 See [docs/key-rotation.md](docs/key-rotation.md) for a step-by-step guide to rotating `YAMLOCK_KEY` without losing data.
 
-## Project structure
-
-```txt
-yamlock/
-├── src/            # Source files (API, CLI, utilities)
-├── dist/           # Build output created by `yarn build`
-├── bin/            # CLI entry point (loads dist/cli/cli.js)
-├── test/           # Unit and integration suites
-├── examples/       # Usage demos (TBD)
-├── CHANGELOG.md    # Step-by-step release history
-└── README.md / LICENSE
-```
-
 ## Inspiration and motivation
 
 I have worked with Ruby on Rails apps for more than ten years and appreciated how its secret management evolved between 4.2 and 6.x. That flow influenced **yamlock**, but I also explored modern tools such as:
@@ -104,12 +143,18 @@ Each of those projects solves secure config storage differently, yet none fit my
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, coding standards, and release instructions.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, available scripts, and release instructions.
 
 ## Exit codes
 
 `yamlock` returns `0` when encryption/decryption completes successfully and `1` on validation or runtime errors (missing keys, malformed payloads, failed file reads). Use these exit codes to gate CI jobs or deployment steps.
 
+## Future work
+
+- Additional cipher presets and stronger default algorithms.
+- More CLI/API examples for rotating keys, selective field targeting, and CI automation.
+- Configurable behavior for non-string values (skip vs. coerce) and stricter file format validation.
+
 ## License
 
 MIT © PAVEL TKACHEV

package/bin/yamlock

@@ -1,6 +1,34 @@
 #!/usr/bin/env node
 
-import('../dist/cli/cli.js').catch((error) => {
-  console.error('[yamlock] CLI failed to start:', error);
-  process.exit(1);
-});
+async function loadCliEntry() {
+  try {
+    const distModule = await import('../dist/cli/cli.js');
+    if (distModule.runCli) {
+      return distModule.runCli;
+    }
+  } catch (error) {
+    if (!(error.code === 'ERR_MODULE_NOT_FOUND' || (error.message && error.message.includes('dist/cli/cli.js')))) {
+      throw error;
+    }
+  }
+
+  try {
+    const srcModule = await import('../src/cli/cli.js');
+    if (srcModule.runCli) {
+      return srcModule.runCli;
+    }
+  } catch (error) {
+    if (!(error.code === 'ERR_MODULE_NOT_FOUND')) {
+      throw error;
+    }
+  }
+
+  throw new Error('CLI entry not found.');
+}
+
+loadCliEntry()
+  .then((runCli) => runCli(process.argv))
+  .catch((error) => {
+    console.error('[yamlock] CLI failed to start:', error);
+    process.exit(1);
+  });

package/dist/cli/cli.js

@@ -87,8 +87,8 @@ function parseArgs(argv) {
   return result;
 }
 
-async function main() {
-  const { command, file, options } = parseArgs(process.argv);
+export async function runCli(argv = process.argv) {
+  const { command, file, options } = parseArgs(argv);
 
   if (!command || !file) {
     print(HELP_TEXT.trim());
@@ -135,5 +135,5 @@ async function main() {
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  main();
+  runCli();
 }

package/dist/crypto/decrypt.js

@@ -3,25 +3,37 @@ import { createDecipheriv } from 'node:crypto';
 import {
   decodeFieldPathSalt,
   deriveKey,
-  ensureAlgorithm,
   isYamlockPayload,
-  parsePayload
+  parsePayload,
+  resolveAlgorithmOptions
 } from './utils.js';
 
+function resolveDecryptOptions(payloadAlgorithm, overrides) {
+  if (typeof overrides === 'string' || overrides === undefined) {
+    return resolveAlgorithmOptions({ algorithm: payloadAlgorithm });
+  }
+
+  return resolveAlgorithmOptions({
+    ...overrides,
+    algorithm: payloadAlgorithm
+  });
+}
+
 /**
  * Decrypts a yamlock payload for the provided field path.
  * @param {string} encryptedValue
  * @param {string|Buffer} key
  * @param {string} fieldPath
+ * @param {string|object} [algorithmOptions]
  * @returns {string}
  */
-export function decryptValue(encryptedValue, key, fieldPath) {
+export function decryptValue(encryptedValue, key, fieldPath, algorithmOptions) {
   if (!isYamlockPayload(encryptedValue)) {
     throw new Error('decryptValue expects a yamlock-formatted payload.');
   }
 
   const payload = parsePayload(encryptedValue);
-  const normalizedAlgorithm = ensureAlgorithm(payload.algorithm);
+  const resolvedOptions = resolveDecryptOptions(payload.algorithm, algorithmOptions);
   const saltFieldPath = decodeFieldPathSalt(payload.salt);
 
   if (!fieldPath) {
@@ -32,9 +44,27 @@ export function decryptValue(encryptedValue, key, fieldPath) {
     throw new Error('Field path does not match the encrypted payload.');
   }
 
-  const derivedKey = deriveKey(key, normalizedAlgorithm);
-  const decipher = createDecipheriv(normalizedAlgorithm, derivedKey, payload.iv);
-  const decrypted = Buffer.concat([decipher.update(payload.data), decipher.final()]);
+  const derivedKey = deriveKey(key, resolvedOptions);
+  let ciphertext = payload.data;
+  let authTag;
+  if (resolvedOptions.authTagLength) {
+    if (ciphertext.length < resolvedOptions.authTagLength) {
+      throw new Error('Encrypted payload is missing an authentication tag.');
+    }
+    authTag = ciphertext.subarray(ciphertext.length - resolvedOptions.authTagLength);
+    ciphertext = ciphertext.subarray(0, ciphertext.length - resolvedOptions.authTagLength);
+  }
+
+  const decipherOptions = resolvedOptions.authTagLength ? { authTagLength: resolvedOptions.authTagLength } : undefined;
+  const decipher = createDecipheriv(resolvedOptions.algorithm, derivedKey, payload.iv, decipherOptions);
+  if (authTag) {
+    if (typeof decipher.setAuthTag !== 'function') {
+      throw new Error(`Algorithm ${resolvedOptions.algorithm} requires auth tags but setAuthTag is unavailable.`);
+    }
+    decipher.setAuthTag(authTag);
+  }
+
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
 
   return decrypted.toString('utf8');
 }

package/dist/crypto/encrypt.js

@@ -1,38 +1,52 @@
 import { createCipheriv } from 'node:crypto';
 
 import {
+  DEFAULT_ALGORITHM,
   deriveKey,
   encodeFieldPathSalt,
-  ensureAlgorithm,
   formatPayload,
-  generateIv
+  generateIv,
+  resolveAlgorithmOptions
 } from './utils.js';
 
-const DEFAULT_ALGORITHM = 'aes-256-cbc';
+function resolveOptions(input) {
+  if (typeof input === 'string' || input === undefined) {
+    return resolveAlgorithmOptions({ algorithm: input ?? DEFAULT_ALGORITHM });
+  }
+  return resolveAlgorithmOptions(input);
+}
 
 /**
  * Encrypts a string value for a specific configuration field path.
  * @param {string} value
  * @param {string|Buffer} key
  * @param {string} fieldPath
- * @param {string} [algorithm=DEFAULT_ALGORITHM]
+ * @param {string|object} [algorithmOptions=DEFAULT_ALGORITHM]
  * @returns {string}
  */
-export function encryptValue(value, key, fieldPath, algorithm = DEFAULT_ALGORITHM) {
+export function encryptValue(value, key, fieldPath, algorithmOptions = DEFAULT_ALGORITHM) {
   if (typeof value !== 'string') {
     throw new Error('encryptValue expects the value to be a string.');
   }
 
-  const normalizedAlgorithm = ensureAlgorithm(algorithm);
-  const derivedKey = deriveKey(key, normalizedAlgorithm);
-  const iv = generateIv(normalizedAlgorithm);
+  const resolvedOptions = resolveOptions(algorithmOptions);
+  const derivedKey = deriveKey(key, resolvedOptions);
+  const iv = generateIv(resolvedOptions);
   const salt = encodeFieldPathSalt(fieldPath);
 
-  const cipher = createCipheriv(normalizedAlgorithm, derivedKey, iv);
-  const encrypted = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()]);
+  const cipherOptions = resolvedOptions.authTagLength ? { authTagLength: resolvedOptions.authTagLength } : undefined;
+  const cipher = createCipheriv(resolvedOptions.algorithm, derivedKey, iv, cipherOptions);
+  let encrypted = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()]);
+  if (resolvedOptions.authTagLength) {
+    if (typeof cipher.getAuthTag !== 'function') {
+      throw new Error(`Algorithm ${resolvedOptions.algorithm} requires auth tags but getAuthTag is unavailable.`);
+    }
+    const authTag = cipher.getAuthTag();
+    encrypted = Buffer.concat([encrypted, authTag]);
+  }
 
   return formatPayload({
-    algorithm: normalizedAlgorithm,
+    algorithm: resolvedOptions.algorithm,
     salt,
     iv,
     data: encrypted

package/dist/crypto/utils.js

@@ -2,6 +2,13 @@ import { createHash, getCipherInfo, getCiphers, randomBytes } from 'node:crypto'
 
 export const YAMLOCK_PREFIX = 'yl';
 export const YAMLOCK_DELIMITER = '|';
+export const DEFAULT_ALGORITHM = 'aes-256-cbc';
+export const ALGORITHM_PRESETS = {
+  'aes-256-cbc': { keyLength: 32, ivLength: 16, authTagLength: 0 },
+  'aes-192-cbc': { keyLength: 24, ivLength: 16, authTagLength: 0 },
+  'aes-128-cbc': { keyLength: 16, ivLength: 16, authTagLength: 0 },
+  'chacha20-poly1305': { keyLength: 32, ivLength: 12, authTagLength: 16 }
+};
 
 /**
  * Returns the sorted list of cipher algorithms supported by the current runtime.
@@ -28,14 +35,46 @@ export function ensureAlgorithm(algorithm) {
   return algorithm;
 }
 
+function normalizeAlgorithmInput(input) {
+  if (!input || typeof input === 'string') {
+    return { algorithm: input };
+  }
+  return input;
+}
+
+/**
+ * Resolves algorithm settings with optional key/IV overrides.
+ * @param {object|string} [input]
+ * @param {string} [input.algorithm]
+ * @param {number} [input.keyLength]
+ * @param {number} [input.ivLength]
+ * @returns {{ algorithm: string, keyLength: number, ivLength: number, authTagLength: number }}
+ */
+export function resolveAlgorithmOptions(input) {
+  const normalized = normalizeAlgorithmInput(input);
+  const algorithmName = ensureAlgorithm(normalized.algorithm ?? DEFAULT_ALGORITHM);
+  const preset = ALGORITHM_PRESETS[algorithmName] ?? {};
+  const cipherInfo = getCipherInfo(algorithmName) ?? {};
+
+  const keyLength = normalized.keyLength ?? preset.keyLength ?? cipherInfo.keyLength ?? 32;
+  const ivLength = normalized.ivLength ?? preset.ivLength ?? cipherInfo.ivLength ?? 16;
+  const authTagLength = normalized.authTagLength ?? preset.authTagLength ?? 0;
+
+  return {
+    algorithm: algorithmName,
+    keyLength,
+    ivLength,
+    authTagLength
+  };
+}
+
 /**
  * Derives a key buffer with the exact size required by the cipher.
  * @param {string|Buffer} secret
- * @param {string} algorithm
+ * @param {{ algorithm: string, keyLength: number }} options
  * @returns {Buffer}
  */
-export function deriveKey(secret, algorithm) {
-  const normalizedAlgorithm = ensureAlgorithm(algorithm);
+export function deriveKey(secret, { algorithm, keyLength }) {
   if (secret === undefined || secret === null || secret === '') {
     throw new Error('Encryption key is required to derive a cipher key.');
   }
@@ -44,21 +83,22 @@ export function deriveKey(secret, algorithm) {
     ? secret
     : Buffer.from(String(secret), 'utf8');
 
-  const keyLength = getCipherInfo(normalizedAlgorithm)?.keyLength ?? 32;
-  if (baseBuffer.length === keyLength) {
+  const normalizedAlgorithm = ensureAlgorithm(algorithm);
+  const requiredLength = keyLength ?? getCipherInfo(normalizedAlgorithm)?.keyLength ?? 32;
+  if (baseBuffer.length === requiredLength) {
     return baseBuffer;
   }
 
   const hash = createHash('sha512').update(baseBuffer).digest();
-  if (hash.length >= keyLength) {
-    return hash.subarray(0, keyLength);
+  if (hash.length >= requiredLength) {
+    return hash.subarray(0, requiredLength);
   }
 
-  const result = Buffer.allocUnsafe(keyLength);
+  const result = Buffer.allocUnsafe(requiredLength);
   let offset = 0;
   let material = hash;
-  while (offset < keyLength) {
-    const chunk = material.subarray(0, Math.min(material.length, keyLength - offset));
+  while (offset < requiredLength) {
+    const chunk = material.subarray(0, Math.min(material.length, requiredLength - offset));
     chunk.copy(result, offset);
     offset += chunk.length;
     material = createHash('sha512').update(material).digest();
@@ -68,18 +108,18 @@ export function deriveKey(secret, algorithm) {
 }
 
 /**
- * Generates an IV buffer for the given algorithm (defaults to 16 bytes).
- * @param {string} algorithm
+ * Generates an IV buffer for the given algorithm configuration.
+ * @param {{ algorithm: string, ivLength: number }} options
  * @returns {Buffer}
  */
-export function generateIv(algorithm) {
+export function generateIv({ algorithm, ivLength }) {
   const normalizedAlgorithm = ensureAlgorithm(algorithm);
-  const ivLength = getCipherInfo(normalizedAlgorithm)?.ivLength ?? 16;
-  if (ivLength === 0) {
+  const length = ivLength ?? getCipherInfo(normalizedAlgorithm)?.ivLength ?? 16;
+  if (length === 0) {
     return Buffer.alloc(0);
   }
 
-  return randomBytes(ivLength);
+  return randomBytes(length);
 }
 
 /**

package/dist/utils/config.js

@@ -13,11 +13,12 @@ const MODES = {
  * @param {Object} options
  * @param {'encrypt'|'decrypt'} options.mode
  * @param {string|Buffer} options.key
- * @param {string} [options.algorithm]
+ * @param {string|object} [options.algorithm]
+ * @param {object} [options.algorithmOptions]
  * @param {Array<string|number>} [options.parentPath]
  * @returns {Object|Array}
  */
-export function processConfig(node, { mode, key, algorithm, parentPath = [] }) {
+export function processConfig(node, { mode, key, algorithm, algorithmOptions, parentPath = [] }) {
   if (typeof node !== 'object' || node === null) {
     throw new Error('processConfig expects a non-null object or array.');
   }
@@ -28,6 +29,7 @@ export function processConfig(node, { mode, key, algorithm, parentPath = [] }) {
 
   const isArrayNode = Array.isArray(node);
   const result = isArrayNode ? [] : {};
+  const cryptoOptions = algorithmOptions ?? algorithm;
 
   Object.entries(node).forEach(([rawKey, value]) => {
     const segment = isArrayNode ? Number(rawKey) : rawKey;
@@ -38,7 +40,8 @@ export function processConfig(node, { mode, key, algorithm, parentPath = [] }) {
       result[targetKey] = processConfig(value, {
         mode,
         key,
-        algorithm,
+        algorithm: cryptoOptions,
+        algorithmOptions: cryptoOptions,
         parentPath: [...parentPath, segment]
       });
       return;
@@ -50,9 +53,9 @@ export function processConfig(node, { mode, key, algorithm, parentPath = [] }) {
     }
 
     if (mode === MODES.ENCRYPT) {
-      result[targetKey] = encryptValue(value, key, currentPath, algorithm);
+      result[targetKey] = encryptValue(value, key, currentPath, cryptoOptions);
     } else {
-      result[targetKey] = decryptValue(value, key, currentPath);
+      result[targetKey] = decryptValue(value, key, currentPath, cryptoOptions);
     }
   });
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "yamlock",
-  "version": "0.1.1",
+  "version": "0.2.0",
+  "author": "PAVEL TKACHEV",
   "description": "Value-level encryption for YAML/JSON configuration files with CLI + Node.js APIs.",
   "license": "MIT",
   "type": "module",