yamlock 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PAVEL TKACHEV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+```ascii
+░█░█░█▀█░█▄░▄█░█░░░█▀█░█▀▀░█░█░
+░░█░░█▀█░█░▀░█░█░░░█░█░█░░░█▀▄░
+░░▀░░▀░▀░▀░░░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░
+```
+
+# yamlock
+
+Value-level encryption for YAML and JSON configuration files. The name **yamlock** combines "YAML" and "lock" while also sounding like "warlock", hinting at a little configuration magic.
+
+## Requirements
+
+- Node.js 22.x via `asdf`
+- Yarn Classic (1.x)
+
+## Current status
+
+- 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`.
+
+## Working locally
+
+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.
+
+## Available scripts
+
+- `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.
+
+## Usage
+
+### CLI
+
+```bash
+# Encrypt values in a YAML file
+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
+```
+
+The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and writes the file back in the same format.
+
+### Node.js API
+
+```js
+import { encryptValue, decryptValue, processConfig } from 'yamlock';
+
+const encrypted = encryptValue('swordfish', process.env.YAMLOCK_KEY, 'db.password');
+const decrypted = decryptValue(encrypted, process.env.YAMLOCK_KEY, 'db.password');
+
+const config = { db: { password: 'swordfish' } };
+const locked = processConfig(config, { mode: 'encrypt', key: process.env.YAMLOCK_KEY });
+const unlocked = processConfig(locked, { mode: 'decrypt', key: process.env.YAMLOCK_KEY });
+```
+
+See `examples/basic.js` for a runnable end-to-end script (`node examples/basic.js`).
+
+### Encrypted value format
+
+Every locked string follows the format:
+
+```txt
+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.
+
+### 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:
+
+- [autoapply/yaml-crypt](https://github.com/autoapply/yaml-crypt)
+- [huwtl/secure_yaml](https://github.com/huwtl/secure_yaml)
+- [bitnami-labs/sealed-secrets](https://github.com/bitnami-labs/sealed-secrets)
+- [getsops/sops](https://github.com/getsops/sops)
+
+Each of those projects solves secure config storage differently, yet none fit my exact needs. **yamlock** is the bicycle I am building for my own projects to add an extra layer of encryption for sensitive YAML/JSON values while keeping the workflow lightweight.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, coding standards, 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.
+
+## License
+
+MIT © PAVEL TKACHEV

package/bin/yamlock

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import('../dist/cli/cli.js').catch((error) => {
+  console.error('[yamlock] CLI failed to start:', error);
+  process.exit(1);
+});

package/dist/cli/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, extname } from 'node:path';
+import { exit } from 'node:process';
+
+import yaml from 'js-yaml';
+
+import { processConfig } from '../utils/config.js';
+
+const HELP_TEXT = `
+░█░█░█▀█░█▄░▄█░█░░░█▀█░█▀▀░█░█░
+░░█░░█▀█░█░▀░█░█░░░█░█░█░░░█▀▄░
+░░▀░░▀░▀░▀░░░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░
+
+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.
+
+Options:
+  -k, --key <value>        Encryption key (or use YAMLOCK_KEY env).
+  -a, --algorithm <value>  Cipher algorithm (default: aes-256-cbc).
+`;
+
+function print(message) {
+  console.log(message);
+}
+
+function printError(message) {
+  console.error(message);
+}
+
+function detectFormat(filePath) {
+  const extension = extname(filePath).toLowerCase();
+  if (extension === '.yaml' || extension === '.yml') {
+    return 'yaml';
+  }
+
+  return 'json';
+}
+
+function readConfigFile(filePath) {
+  const content = readFileSync(filePath, 'utf8');
+  const format = detectFormat(filePath);
+
+  if (format === 'yaml') {
+    return { format, data: yaml.load(content) ?? {} };
+  }
+
+  return { format, data: JSON.parse(content) };
+}
+
+function writeConfigFile(filePath, format, data) {
+  if (format === 'yaml') {
+    const serialized = yaml.dump(data, { lineWidth: 120 });
+    writeFileSync(filePath, serialized, 'utf8');
+    return;
+  }
+
+  const serialized = JSON.stringify(data, null, 2);
+  writeFileSync(filePath, `${serialized}\n`, 'utf8');
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const result = {
+    command: args[0],
+    file: args[1],
+    options: {}
+  };
+
+  for (let i = 2; i < args.length; i += 1) {
+    const arg = args[i];
+    const next = args[i + 1];
+
+    if (arg === '-k' || arg === '--key') {
+      result.options.key = next;
+      i += 1;
+    } else if (arg === '-a' || arg === '--algorithm') {
+      result.options.algorithm = next;
+      i += 1;
+    }
+  }
+
+  return result;
+}
+
+async function main() {
+  const { command, file, options } = parseArgs(process.argv);
+
+  if (!command || !file) {
+    print(HELP_TEXT.trim());
+    return exit(1);
+  }
+
+  const key = options.key ?? process.env.YAMLOCK_KEY;
+  if (!key) {
+    printError('Encryption key is required via --key or YAMLOCK_KEY.');
+    return exit(1);
+  }
+
+  const absolutePath = resolve(process.cwd(), file);
+  let config;
+  try {
+    config = readConfigFile(absolutePath);
+  } catch (error) {
+    printError(`Failed to read config file: ${error.message}`);
+    return exit(1);
+  }
+
+  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}`);
+      return exit(0);
+    }
+
+    if (command === 'decrypt') {
+      const result = processConfig(config.data, { mode: 'decrypt', key });
+      writeConfigFile(absolutePath, config.format, result);
+      print(`Decrypted values in ${file}`);
+      return exit(0);
+    }
+
+    printError(`Unknown command: ${command}`);
+    print(HELP_TEXT.trim());
+    return exit(1);
+  } catch (error) {
+    printError(`Operation failed: ${error.message}`);
+    return exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/dist/crypto/decrypt.js

@@ -0,0 +1,40 @@
+import { createDecipheriv } from 'node:crypto';
+
+import {
+  decodeFieldPathSalt,
+  deriveKey,
+  ensureAlgorithm,
+  isYamlockPayload,
+  parsePayload
+} from './utils.js';
+
+/**
+ * Decrypts a yamlock payload for the provided field path.
+ * @param {string} encryptedValue
+ * @param {string|Buffer} key
+ * @param {string} fieldPath
+ * @returns {string}
+ */
+export function decryptValue(encryptedValue, key, fieldPath) {
+  if (!isYamlockPayload(encryptedValue)) {
+    throw new Error('decryptValue expects a yamlock-formatted payload.');
+  }
+
+  const payload = parsePayload(encryptedValue);
+  const normalizedAlgorithm = ensureAlgorithm(payload.algorithm);
+  const saltFieldPath = decodeFieldPathSalt(payload.salt);
+
+  if (!fieldPath) {
+    throw new Error('Field path is required to decrypt a value.');
+  }
+
+  if (saltFieldPath !== 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()]);
+
+  return decrypted.toString('utf8');
+}

package/dist/crypto/encrypt.js

@@ -0,0 +1,40 @@
+import { createCipheriv } from 'node:crypto';
+
+import {
+  deriveKey,
+  encodeFieldPathSalt,
+  ensureAlgorithm,
+  formatPayload,
+  generateIv
+} from './utils.js';
+
+const DEFAULT_ALGORITHM = 'aes-256-cbc';
+
+/**
+ * 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]
+ * @returns {string}
+ */
+export function encryptValue(value, key, fieldPath, algorithm = 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 salt = encodeFieldPathSalt(fieldPath);
+
+  const cipher = createCipheriv(normalizedAlgorithm, derivedKey, iv);
+  const encrypted = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()]);
+
+  return formatPayload({
+    algorithm: normalizedAlgorithm,
+    salt,
+    iv,
+    data: encrypted
+  });
+}

package/dist/crypto/utils.js

@@ -0,0 +1,172 @@
+import { createHash, getCipherInfo, getCiphers, randomBytes } from 'node:crypto';
+
+export const YAMLOCK_PREFIX = 'yl';
+export const YAMLOCK_DELIMITER = '|';
+
+/**
+ * Returns the sorted list of cipher algorithms supported by the current runtime.
+ * @returns {string[]}
+ */
+export function listSupportedAlgorithms() {
+  return [...new Set(getCiphers())].sort();
+}
+
+/**
+ * Ensures the provided algorithm is available in the current runtime.
+ * @param {string} algorithm
+ * @returns {string}
+ */
+export function ensureAlgorithm(algorithm) {
+  if (!algorithm) {
+    throw new Error('Encryption algorithm is required.');
+  }
+
+  if (!listSupportedAlgorithms().includes(algorithm)) {
+    throw new Error(`Unsupported algorithm: ${algorithm}`);
+  }
+
+  return algorithm;
+}
+
+/**
+ * Derives a key buffer with the exact size required by the cipher.
+ * @param {string|Buffer} secret
+ * @param {string} algorithm
+ * @returns {Buffer}
+ */
+export function deriveKey(secret, algorithm) {
+  const normalizedAlgorithm = ensureAlgorithm(algorithm);
+  if (secret === undefined || secret === null || secret === '') {
+    throw new Error('Encryption key is required to derive a cipher key.');
+  }
+
+  const baseBuffer = Buffer.isBuffer(secret)
+    ? secret
+    : Buffer.from(String(secret), 'utf8');
+
+  const keyLength = getCipherInfo(normalizedAlgorithm)?.keyLength ?? 32;
+  if (baseBuffer.length === keyLength) {
+    return baseBuffer;
+  }
+
+  const hash = createHash('sha512').update(baseBuffer).digest();
+  if (hash.length >= keyLength) {
+    return hash.subarray(0, keyLength);
+  }
+
+  const result = Buffer.allocUnsafe(keyLength);
+  let offset = 0;
+  let material = hash;
+  while (offset < keyLength) {
+    const chunk = material.subarray(0, Math.min(material.length, keyLength - offset));
+    chunk.copy(result, offset);
+    offset += chunk.length;
+    material = createHash('sha512').update(material).digest();
+  }
+
+  return result;
+}
+
+/**
+ * Generates an IV buffer for the given algorithm (defaults to 16 bytes).
+ * @param {string} algorithm
+ * @returns {Buffer}
+ */
+export function generateIv(algorithm) {
+  const normalizedAlgorithm = ensureAlgorithm(algorithm);
+  const ivLength = getCipherInfo(normalizedAlgorithm)?.ivLength ?? 16;
+  if (ivLength === 0) {
+    return Buffer.alloc(0);
+  }
+
+  return randomBytes(ivLength);
+}
+
+/**
+ * Creates a deterministic salt (Base64 field path) used when encrypting.
+ * @param {string} fieldPath
+ * @returns {string}
+ */
+export function encodeFieldPathSalt(fieldPath) {
+  if (!fieldPath) {
+    throw new Error('Field path is required to create a salt.');
+  }
+
+  return Buffer.from(String(fieldPath), 'utf8').toString('base64');
+}
+
+/**
+ * Decodes a Base64 salt string back to the original field path.
+ * @param {string} salt
+ * @returns {string}
+ */
+export function decodeFieldPathSalt(salt) {
+  if (!salt) {
+    throw new Error('Salt value is required.');
+  }
+
+  return Buffer.from(String(salt), 'base64').toString('utf8');
+}
+
+/**
+ * Formats the encrypted payload into the canonical yamlock string.
+ * @param {Object} payload
+ * @param {string} payload.algorithm
+ * @param {string} payload.salt
+ * @param {Buffer} payload.iv
+ * @param {Buffer} payload.data
+ * @returns {string}
+ */
+export function formatPayload({ algorithm, salt, iv, data }) {
+  if (!algorithm || !salt || !iv || !data) {
+    throw new Error('Algorithm, salt, IV, and data are required to format payload.');
+  }
+
+  return [
+    YAMLOCK_PREFIX,
+    algorithm,
+    salt,
+    iv.toString('base64'),
+    data.toString('base64')
+  ].join(YAMLOCK_DELIMITER);
+}
+
+/**
+ * Checks whether a string looks like a yamlock payload.
+ * @param {unknown} candidate
+ * @returns {boolean}
+ */
+export function isYamlockPayload(candidate) {
+  return (
+    typeof candidate === 'string' &&
+    candidate.startsWith(`${YAMLOCK_PREFIX}${YAMLOCK_DELIMITER}`)
+  );
+}
+
+/**
+ * Parses a yamlock payload and returns its structured pieces.
+ * @param {string} value
+ * @returns {{ algorithm: string, salt: string, iv: Buffer, data: Buffer }}
+ */
+export function parsePayload(value) {
+  if (!isYamlockPayload(value)) {
+    throw new Error('Value is not a yamlock payload.');
+  }
+
+  const parts = value.split(YAMLOCK_DELIMITER);
+  if (parts.length !== 5) {
+    throw new Error('Malformed yamlock payload.');
+  }
+
+  const [, algorithm, salt, ivBase64, dataBase64] = parts;
+  if (!algorithm || !salt || !ivBase64 || !dataBase64) {
+    throw new Error('Malformed yamlock payload segments.');
+  }
+
+  return {
+    algorithm,
+    salt,
+    iv: Buffer.from(ivBase64, 'base64'),
+    data: Buffer.from(dataBase64, 'base64')
+  };
+}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { encryptValue } from './crypto/encrypt.js';
+export { decryptValue } from './crypto/decrypt.js';
+export { processConfig } from './utils/config.js';
+export { listSupportedAlgorithms as getSupportedAlgorithms } from './crypto/utils.js';

package/dist/utils/config.js

@@ -0,0 +1,60 @@
+import { encryptValue } from '../crypto/encrypt.js';
+import { decryptValue } from '../crypto/decrypt.js';
+import { buildPath } from './path.js';
+
+const MODES = {
+  ENCRYPT: 'encrypt',
+  DECRYPT: 'decrypt'
+};
+
+/**
+ * Recursively processes a config object or array, encrypting/decrypting string values.
+ * @param {Object|Array} node
+ * @param {Object} options
+ * @param {'encrypt'|'decrypt'} options.mode
+ * @param {string|Buffer} options.key
+ * @param {string} [options.algorithm]
+ * @param {Array<string|number>} [options.parentPath]
+ * @returns {Object|Array}
+ */
+export function processConfig(node, { mode, key, algorithm, parentPath = [] }) {
+  if (typeof node !== 'object' || node === null) {
+    throw new Error('processConfig expects a non-null object or array.');
+  }
+
+  if (mode !== MODES.ENCRYPT && mode !== MODES.DECRYPT) {
+    throw new Error(`Unknown processConfig mode: ${mode}`);
+  }
+
+  const isArrayNode = Array.isArray(node);
+  const result = isArrayNode ? [] : {};
+
+  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] = processConfig(value, {
+        mode,
+        key,
+        algorithm,
+        parentPath: [...parentPath, segment]
+      });
+      return;
+    }
+
+    if (typeof value !== 'string') {
+      result[targetKey] = value;
+      return;
+    }
+
+    if (mode === MODES.ENCRYPT) {
+      result[targetKey] = encryptValue(value, key, currentPath, algorithm);
+    } else {
+      result[targetKey] = decryptValue(value, key, currentPath);
+    }
+  });
+
+  return result;
+}

package/dist/utils/path.js

@@ -0,0 +1,39 @@
+/**
+ * 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"
+ *
+ * @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.');
+  }
+
+  return segments
+    .map((segment, index) => {
+      if (typeof segment === 'number') {
+        return `[${segment}]`;
+      }
+
+      if (typeof segment === 'string' && segment.length > 0) {
+        return index === 0 ? segment : `.${segment}`;
+      }
+
+      throw new Error('Path segments must be non-empty strings or numbers.');
+    })
+    .join('');
+}
+
+/**
+ * Returns the full path string for a given traversal context.
+ * @param {Array<string|number>} parentSegments
+ * @param {string|number} currentSegment
+ * @returns {string}
+ */
+export function buildPath(parentSegments, currentSegment) {
+  const segments = [...(parentSegments ?? [])];
+  segments.push(currentSegment);
+  return serializePath(segments);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "yamlock",
+  "version": "0.1.1",
+  "description": "Value-level encryption for YAML/JSON configuration files with CLI + Node.js APIs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "yamlock": "bin/yamlock"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "yaml",
+    "cli",
+    "config",
+    "json",
+    "encryption",
+    "security"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && cp -R src dist",
+    "lint": "eslint .",
+    "prepare": "yarn run build",
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phoenixweiss/yamlock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/phoenixweiss/yamlock/issues"
+  },
+  "homepage": "https://github.com/phoenixweiss/yamlock#readme",
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0",
+    "rimraf": "^5.0.5"
+  }
+}