@faizahmed/secret-keystore 1.1.0

package/src/path-matcher.js

@@ -0,0 +1,319 @@
+/**
+ * @faizahmed/secret-keystore - Path Matching
+ *
+ * Utilities for matching paths in nested objects using ** patterns.
+ * Only ** (any-depth) pattern is supported, not * (single-level).
+ */
+
+const { PathError, PATH_ERROR_CODES } = require('./errors');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATH UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get a value from an object by dot-notation path
+ * @param {Object} obj - Object to get value from
+ * @param {string} path - Dot-notation path (e.g., 'a.b.c')
+ * @returns {*} Value at path or undefined
+ */
+function getByPath(obj, path) {
+    if (!path) return obj;
+
+    const parts = path.split('.');
+    let current = obj;
+
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        current = current[part];
+    }
+
+    return current;
+}
+
+/**
+ * Set a value in an object by dot-notation path
+ * @param {Object} obj - Object to set value in
+ * @param {string} path - Dot-notation path (e.g., 'a.b.c')
+ * @param {*} value - Value to set
+ * @returns {Object} Modified object
+ */
+function setByPath(obj, path, value) {
+    if (!path) return value;
+
+    const parts = path.split('.');
+    let current = obj;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (current[part] === undefined || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+
+    current[parts[parts.length - 1]] = value;
+    return obj;
+}
+
+/**
+ * Get all paths in an object (leaf nodes only)
+ * @param {Object} obj - Object to traverse
+ * @param {string} [prefix=''] - Current path prefix
+ * @returns {string[]} Array of dot-notation paths
+ */
+function getAllPaths(obj, prefix = '') {
+    const paths = [];
+
+    if (obj === null || obj === undefined) {
+        return paths;
+    }
+
+    if (typeof obj !== 'object' || Array.isArray(obj) || Buffer.isBuffer(obj)) {
+        // Leaf node
+        if (prefix) {
+            paths.push(prefix);
+        }
+        return paths;
+    }
+
+    for (const [key, value] of Object.entries(obj)) {
+        const currentPath = prefix ? `${prefix}.${key}` : key;
+
+        if (
+            value !== null &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            !Buffer.isBuffer(value)
+        ) {
+            // Recurse into nested object
+            paths.push(...getAllPaths(value, currentPath));
+        } else {
+            // Leaf node
+            paths.push(currentPath);
+        }
+    }
+
+    return paths;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN MATCHING (** only)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert a ** pattern to a regex
+ * @param {string} pattern - Pattern with ** wildcards
+ * @returns {RegExp}
+ */
+function patternToRegex(pattern) {
+    // Escape special regex characters except **
+    let escaped = pattern
+        .replaceAll(/[.+^${}()|[\]\\]/g, String.raw`\$&`) // Escape special chars
+        .replaceAll('**', '{{DOUBLE_STAR}}'); // Temporarily replace **
+
+    // Replace ** with regex pattern (match any depth)
+    escaped = escaped.replaceAll('{{DOUBLE_STAR}}', '.*');
+
+    // Anchor the pattern
+    return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Check if a path matches a ** pattern
+ * @param {string} path - Dot-notation path
+ * @param {string} pattern - Pattern with ** wildcards
+ * @returns {boolean}
+ */
+function matchesPattern(path, pattern) {
+    // Handle patterns that start with **
+    if (pattern.startsWith('**.')) {
+        // **.foo matches any path ending with .foo or just foo
+        const suffix = pattern.slice(3);
+        if (path === suffix) return true;
+        if (path.endsWith('.' + suffix)) return true;
+        return false;
+    }
+
+    // Handle patterns that end with **
+    if (pattern.endsWith('.**')) {
+        // foo.** matches foo and any path starting with foo.
+        const prefix = pattern.slice(0, -3);
+        if (path === prefix) return true;
+        if (path.startsWith(prefix + '.')) return true;
+        return false;
+    }
+
+    // Handle patterns with ** in the middle or complex patterns
+    const regex = patternToRegex(pattern);
+    return regex.test(path);
+}
+
+/**
+ * Add explicit paths to selected set
+ * @private
+ */
+function addExplicitPaths(selectedPaths, allPaths, paths) {
+    if (!paths || !Array.isArray(paths)) return;
+
+    for (const path of paths) {
+        if (allPaths.includes(path)) {
+            selectedPaths.add(path);
+        }
+    }
+}
+
+/**
+ * Add pattern-matched paths to selected set
+ * @private
+ */
+function addPatternMatches(selectedPaths, allPaths, patterns) {
+    if (!patterns || !Array.isArray(patterns)) return;
+
+    for (const pattern of patterns) {
+        for (const path of allPaths) {
+            if (matchesPattern(path, pattern)) {
+                selectedPaths.add(path);
+            }
+        }
+    }
+}
+
+/**
+ * Filter paths using patterns and explicit paths
+ * @param {string[]} allPaths - All available paths
+ * @param {Object} options - Selection options
+ * @param {string[]} [options.paths] - Explicit paths to include
+ * @param {string[]} [options.patterns] - Patterns to match
+ * @param {Object} [options.exclude] - Exclusions
+ * @param {string[]} [options.exclude.paths] - Explicit paths to exclude
+ * @param {string[]} [options.exclude.patterns] - Patterns to exclude
+ * @returns {string[]} Matching paths
+ */
+function filterPaths(allPaths, options = {}) {
+    const { paths, patterns, exclude } = options;
+
+    // If no selection criteria, return all paths
+    if (!paths && !patterns) {
+        return excludePaths(allPaths, exclude);
+    }
+
+    const selectedPaths = new Set();
+
+    addExplicitPaths(selectedPaths, allPaths, paths);
+    addPatternMatches(selectedPaths, allPaths, patterns);
+
+    return excludePaths(Array.from(selectedPaths), exclude);
+}
+
+/**
+ * Exclude paths based on exclusion options
+ * @param {string[]} paths - Paths to filter
+ * @param {Object} [exclude] - Exclusion options
+ * @returns {string[]}
+ */
+function excludePaths(paths, exclude) {
+    if (!exclude) return paths;
+
+    return paths.filter(path => {
+        // Check explicit exclusions
+        if (exclude.paths && exclude.paths.includes(path)) {
+            return false;
+        }
+
+        // Check pattern exclusions
+        if (exclude.patterns) {
+            for (const pattern of exclude.patterns) {
+                if (matchesPattern(path, pattern)) {
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    });
+}
+
+/**
+ * Validate that all explicit paths exist
+ * @param {string[]} requestedPaths - Requested paths
+ * @param {string[]} existingPaths - Paths that exist
+ * @throws {PathError}
+ */
+function validatePathsExist(requestedPaths, existingPaths) {
+    for (const path of requestedPaths) {
+        if (!existingPaths.includes(path)) {
+            throw new PathError(`Path not found: ${path}`, PATH_ERROR_CODES.NOT_FOUND, path);
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// OBJECT TRANSFORMATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Transform values at selected paths in an object
+ * @param {Object} obj - Source object
+ * @param {string[]} paths - Paths to transform
+ * @param {Function} transformer - Async function (value, path) => newValue
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.continueOnError=false] - Continue on transformation errors
+ * @returns {Promise<Object>} Result with transformed object
+ */
+async function transformAtPaths(obj, paths, transformer, options = {}) {
+    const continueOnError = options.continueOnError === true;
+
+    const result = {
+        object: structuredClone(obj),
+        transformed: [],
+        skipped: [],
+        failed: []
+    };
+
+    for (const path of paths) {
+        const value = getByPath(obj, path);
+
+        if (value === undefined) {
+            result.skipped.push(path);
+            continue;
+        }
+
+        try {
+            const newValue = await transformer(value, path);
+            setByPath(result.object, path, newValue);
+            result.transformed.push(path);
+        } catch (error) {
+            if (continueOnError) {
+                result.failed.push({ path, error });
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    return result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+    // Path utilities
+    getByPath,
+    setByPath,
+    getAllPaths,
+
+    // Pattern matching
+    patternToRegex,
+    matchesPattern,
+    filterPaths,
+    excludePaths,
+    validatePathsExist,
+
+    // Object transformation
+    transformAtPaths
+};

package/src/rotate.js

@@ -0,0 +1,92 @@
+/**
+ * @faizahmed/secret-keystore - Key Rotation
+ *
+ * Re-encrypt the already-encrypted values in a config file under a NEW KMS Key
+ * ID, decrypting them with the OLD key first. Values that were plaintext stay
+ * plaintext; only previously-encrypted entries are rotated.
+ *
+ * Decryption happens in memory; nothing plaintext is written to disk by this
+ * helper (the caller decides what to do with the returned content string).
+ */
+
+const { encryptKMSEnvContent, decryptKMSEnvContent } = require('./content-operations');
+const { encryptKMSObject, decryptKMSObject } = require('./object-operations');
+const { getAllPaths, getByPath } = require('./path-matcher');
+const { isAlreadyEncrypted } = require('./kms');
+const { parseEnvContent } = require('./content-operations');
+const { parseYaml, serializeYaml } = require('./yaml-utils');
+const { ContentError, CONTENT_ERROR_CODES } = require('./errors');
+
+/**
+ * Find the keys/paths in a parsed config that are currently encrypted.
+ * @private
+ */
+function findEncryptedEnvKeys(content) {
+    return parseEnvContent(content)
+        .filter(entry => entry.type === 'keyvalue' && isAlreadyEncrypted(entry.value))
+        .map(entry => entry.key);
+}
+
+function findEncryptedObjectPaths(obj) {
+    return getAllPaths(obj).filter(path => {
+        const value = getByPath(obj, path);
+        return typeof value === 'string' && isAlreadyEncrypted(value);
+    });
+}
+
+/**
+ * Rotate encrypted values from oldKmsKeyId to newKmsKeyId.
+ *
+ * @param {string} content - Raw file content
+ * @param {'env'|'json'|'yaml'} format - Content format
+ * @param {string} oldKmsKeyId - KMS Key ID the content is currently encrypted with
+ * @param {string} newKmsKeyId - KMS Key ID to re-encrypt with
+ * @param {Object} [options] - Forwarded encrypt/decrypt options (aws, logger, etc.)
+ * @returns {Promise<{ content: string, rotated: string[] }>}
+ */
+async function rotateKMSContent(content, format, oldKmsKeyId, newKmsKeyId, options = {}) {
+    if (format === 'env') {
+        const encryptedKeys = findEncryptedEnvKeys(content);
+        if (encryptedKeys.length === 0) {
+            return { content, rotated: [] };
+        }
+        const decrypted = await decryptKMSEnvContent(content, oldKmsKeyId, options);
+        const reEncrypted = await encryptKMSEnvContent(decrypted.content, newKmsKeyId, {
+            ...options,
+            paths: encryptedKeys
+        });
+        return { content: reEncrypted.content, rotated: reEncrypted.encrypted };
+    }
+
+    if (format === 'json' || format === 'yaml') {
+        const obj = format === 'json' ? JSON.parse(content) : parseYaml(content);
+        const encryptedPaths = findEncryptedObjectPaths(obj);
+        if (encryptedPaths.length === 0) {
+            return { content, rotated: [] };
+        }
+
+        const decrypted = await decryptKMSObject(obj, oldKmsKeyId, {
+            ...options,
+            paths: encryptedPaths
+        });
+        const reEncrypted = await encryptKMSObject(decrypted.object, newKmsKeyId, {
+            ...options,
+            paths: encryptedPaths
+        });
+
+        const output =
+            format === 'json'
+                ? JSON.stringify(reEncrypted.object, null, 2)
+                : serializeYaml(reEncrypted.object);
+
+        return { content: output, rotated: reEncrypted.encrypted };
+    }
+
+    throw new ContentError(
+        `Unsupported format for rotation: ${format}`,
+        CONTENT_ERROR_CODES.INVALID_FORMAT,
+        format
+    );
+}
+
+module.exports = { rotateKMSContent };

package/src/yaml-utils.js

@@ -0,0 +1,265 @@
+/**
+ * @faizahmed/secret-keystore - YAML Utilities
+ *
+ * Handles YAML parsing/serialization with optional js-yaml dependency.
+ * Falls back to simple parser for basic YAML when js-yaml is not installed.
+ */
+
+const { ContentError, CONTENT_ERROR_CODES } = require('./errors');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// JS-YAML LOADER
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Cached reference to js-yaml module (or null if not available)
+ * @type {Object|null|undefined}
+ */
+let jsYamlModule;
+let jsYamlChecked = false;
+
+/**
+ * Check if js-yaml is available
+ * @returns {boolean}
+ */
+function isJsYamlAvailable() {
+    if (!jsYamlChecked) {
+        try {
+            jsYamlModule = require('js-yaml');
+        } catch {
+            jsYamlModule = null;
+        }
+        jsYamlChecked = true;
+    }
+    return jsYamlModule !== null;
+}
+
+/**
+ * Get the js-yaml module
+ * @returns {Object|null}
+ */
+function getJsYaml() {
+    if (!jsYamlChecked) {
+        isJsYamlAvailable();
+    }
+    return jsYamlModule;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SIMPLE YAML PARSER (FALLBACK)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Features NOT supported by simple parser:
+ * - Multi-line strings (| and >)
+ * - Anchors and aliases (&, *)
+ * - Complex nested arrays
+ * - Type tags (!!str, !!int, etc.)
+ * - Document separators (---, ...)
+ */
+const COMPLEX_YAML_PATTERNS = [
+    /&\w+/, // Anchors (&anchor)
+    /\*\w+/, // Aliases (*anchor)
+    /<<:/, // Merge key
+    /:\s*[|>]/m, // Multi-line strings
+    /^---/m, // Document separator
+    /^\.\.\./m, // Document end
+    /!!\w+/, // Type tags
+    /^\s*-\s*[^#\n]+:/m // Nested objects in arrays
+];
+
+/**
+ * Check if YAML content has complex features
+ * @param {string} content
+ * @returns {boolean}
+ */
+function hasComplexYamlFeatures(content) {
+    return COMPLEX_YAML_PATTERNS.some(pattern => pattern.test(content));
+}
+
+/**
+ * Simple YAML parser (handles basic key: value structures)
+ * @param {string} content - YAML content
+ * @returns {Object} Parsed object
+ */
+function parseYamlSimple(content) {
+    const lines = content.split('\n');
+    const result = {};
+    const stack = [{ obj: result, indent: -1 }];
+
+    for (const line of lines) {
+        // Skip empty lines and comments
+        if (!line.trim() || line.trim().startsWith('#')) continue;
+
+        const match = line.match(/^(\s*)([^:]+):\s*(.*)$/);
+        if (!match) continue;
+
+        const indent = match[1].length;
+        const key = match[2].trim();
+        let value = match[3].trim();
+
+        // Remove inline comments (not in quoted strings)
+        if (!value.startsWith('"') && !value.startsWith("'")) {
+            const commentIndex = value.indexOf('#');
+            if (commentIndex > 0) {
+                value = value.substring(0, commentIndex).trim();
+            }
+        }
+
+        // Remove quotes
+        if (
+            (value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))
+        ) {
+            value = value.slice(1, -1);
+        }
+
+        // Pop stack until we find parent
+        while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+
+        const parent = stack[stack.length - 1].obj;
+
+        if (value) {
+            parent[key] = value;
+        } else {
+            parent[key] = {};
+            stack.push({ obj: parent[key], indent });
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Simple YAML serializer
+ * @param {Object} obj - Object to serialize
+ * @param {number} indent - Current indentation level
+ * @returns {string} YAML string
+ */
+function serializeYamlSimple(obj, indent = 0) {
+    let result = '';
+    const spaces = '  '.repeat(indent);
+
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            result += `${spaces}${key}:\n`;
+            result += serializeYamlSimple(value, indent + 1);
+        } else {
+            const needsQuotes =
+                typeof value === 'string' &&
+                (value.includes(':') ||
+                    value.includes('#') ||
+                    value.includes(' ') ||
+                    value.includes('\n'));
+            const formattedValue = needsQuotes ? `"${value}"` : value;
+            result += `${spaces}${key}: ${formattedValue}\n`;
+        }
+    }
+
+    return result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PUBLIC API
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Parse YAML content to object
+ *
+ * Uses js-yaml if available, falls back to simple parser for basic YAML.
+ * Throws an error if content has complex features and js-yaml is not installed.
+ *
+ * @param {string} content - YAML content string
+ * @returns {Object} Parsed object
+ * @throws {ContentError} If parsing fails or complex YAML without js-yaml
+ */
+function parseYaml(content) {
+    const yaml = getJsYaml();
+
+    if (yaml) {
+        try {
+            return yaml.load(content);
+        } catch (error) {
+            throw new ContentError(
+                `Failed to parse YAML: ${error.message}`,
+                CONTENT_ERROR_CODES.PARSE_FAILED,
+                'yaml',
+                error
+            );
+        }
+    }
+
+    // No js-yaml available - check for complex features
+    if (hasComplexYamlFeatures(content)) {
+        throw new ContentError(
+            'YAML content has complex features (anchors, multi-line strings, etc.) that require js-yaml. ' +
+                'Install js-yaml: npm install js-yaml',
+            CONTENT_ERROR_CODES.PARSE_FAILED,
+            'yaml'
+        );
+    }
+
+    // Use simple parser for basic YAML
+    try {
+        return parseYamlSimple(content);
+    } catch (error) {
+        throw new ContentError(
+            `Failed to parse YAML: ${error.message}. For complex YAML, install js-yaml: npm install js-yaml`,
+            CONTENT_ERROR_CODES.PARSE_FAILED,
+            'yaml',
+            error
+        );
+    }
+}
+
+/**
+ * Serialize object to YAML string
+ *
+ * Uses js-yaml if available, falls back to simple serializer.
+ *
+ * @param {Object} obj - Object to serialize
+ * @returns {string} YAML string
+ */
+function serializeYaml(obj) {
+    const yaml = getJsYaml();
+
+    if (yaml) {
+        try {
+            return yaml.dump(obj, { lineWidth: -1 });
+        } catch (error) {
+            throw new ContentError(
+                `Failed to serialize YAML: ${error.message}`,
+                CONTENT_ERROR_CODES.SERIALIZATION_FAILED,
+                'yaml',
+                error
+            );
+        }
+    }
+
+    try {
+        return serializeYamlSimple(obj);
+    } catch (error) {
+        throw new ContentError(
+            `Failed to serialize YAML: ${error.message}`,
+            CONTENT_ERROR_CODES.SERIALIZATION_FAILED,
+            'yaml',
+            error
+        );
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+    isJsYamlAvailable,
+    getJsYaml,
+    parseYaml,
+    serializeYaml,
+    parseYamlSimple,
+    serializeYamlSimple,
+    hasComplexYamlFeatures
+};