@faizahmed/secret-keystore 1.1.0

package/src/attestation/cms-unwrap.js

@@ -0,0 +1,166 @@
+/**
+ * @faizahmed/secret-keystore - CMS EnvelopedData Unwrapping
+ *
+ * Uses PKIjs and asn1js to unwrap CMS EnvelopedData returned by AWS KMS
+ * when using the Recipient parameter with attestation.
+ *
+ * When KMS receives a Recipient with AttestationDocument, it returns
+ * CiphertextForRecipient instead of Plaintext. This CiphertextForRecipient
+ * is a CMS EnvelopedData structure encrypted with the public key from
+ * the attestation document.
+ */
+
+const crypto = require('node:crypto');
+const asn1js = require('asn1js');
+const pkijs = require('pkijs');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PKIJS ENGINE SETUP
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Use Node.js WebCrypto for PKIjs
+const nodeCrypto = crypto.webcrypto;
+
+/**
+ * Initialize PKIjs engine with Node.js crypto
+ * Must be called before any PKIjs operations
+ */
+function initializePkijsEngine() {
+    const engine = new pkijs.CryptoEngine({
+        name: 'nodeEngine',
+        crypto: nodeCrypto,
+        subtle: nodeCrypto.subtle
+    });
+    pkijs.setEngine('nodeEngine', engine);
+}
+
+// Initialize on module load
+initializePkijsEngine();
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CMS UNWRAP
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Unwrap CMS EnvelopedData using PKIjs
+ *
+ * @param {Buffer} ciphertextForRecipient - The CMS EnvelopedData from KMS
+ * @param {string} privateKeyPem - The ephemeral private key (PKCS#8 PEM)
+ * @returns {Promise<Buffer>} - The decrypted plaintext
+ * @throws {Error} If parsing or decryption fails
+ */
+async function unwrapCms(ciphertextForRecipient, privateKeyPem) {
+    // Ensure engine is initialized
+    initializePkijsEngine();
+
+    // 1. Parse CMS DER structure
+    const derView = new Uint8Array(
+        ciphertextForRecipient.buffer,
+        ciphertextForRecipient.byteOffset,
+        ciphertextForRecipient.byteLength
+    );
+
+    const asn1Result = asn1js.fromBER(derView);
+    if (asn1Result.offset === -1) {
+        throw new Error('Failed to parse CMS DER structure');
+    }
+
+    // 2. Parse ContentInfo
+    const contentInfo = new pkijs.ContentInfo({ schema: asn1Result.result });
+
+    // Verify it's EnvelopedData (OID: 1.2.840.113549.1.7.3)
+    if (contentInfo.contentType !== '1.2.840.113549.1.7.3') {
+        throw new Error(
+            `Expected CMS EnvelopedData (1.2.840.113549.1.7.3), got ${contentInfo.contentType}`
+        );
+    }
+
+    // 3. Parse EnvelopedData
+    const envelopedData = new pkijs.EnvelopedData({ schema: contentInfo.content });
+
+    // 4. Import private key for decryption
+    const privateKey = await importPrivateKey(privateKeyPem);
+
+    // 5. Decrypt the content
+    const decryptResult = await envelopedData.decrypt(0, {
+        recipientPrivateKey: privateKey,
+        crypto: nodeCrypto
+    });
+
+    // 6. Handle different return types from PKIjs
+    let plaintext;
+    if (typeof decryptResult === 'boolean') {
+        // PKIjs modifies envelopedData.encryptedContentInfo.encryptedContent in-place
+        const encryptedContent = envelopedData.encryptedContentInfo?.encryptedContent;
+        if (!encryptedContent) {
+            throw new Error('Decryption returned true but no content found');
+        }
+        plaintext = Buffer.from(encryptedContent.valueBlock.valueHexView);
+    } else if (decryptResult instanceof ArrayBuffer) {
+        plaintext = Buffer.from(decryptResult);
+    } else if (ArrayBuffer.isView(decryptResult)) {
+        plaintext = Buffer.from(
+            decryptResult.buffer,
+            decryptResult.byteOffset,
+            decryptResult.byteLength
+        );
+    } else {
+        throw new TypeError(`Unexpected decrypt result type: ${typeof decryptResult}`);
+    }
+
+    return plaintext;
+}
+
+/**
+ * Import PKCS#8 PEM private key for RSA-OAEP decryption
+ *
+ * @param {string} privateKeyPem - PKCS#8 PEM private key
+ * @returns {Promise<CryptoKey>}
+ */
+async function importPrivateKey(privateKeyPem) {
+    // Extract base64 from PEM
+    const base64 = privateKeyPem
+        .replaceAll('-----BEGIN PRIVATE KEY-----', '')
+        .replaceAll('-----END PRIVATE KEY-----', '')
+        .replaceAll(/\s+/g, '');
+
+    const pkcs8Buffer = Buffer.from(base64, 'base64');
+
+    // Import as RSA-OAEP key
+    const privateKey = await nodeCrypto.subtle.importKey(
+        'pkcs8',
+        pkcs8Buffer,
+        {
+            name: 'RSA-OAEP',
+            hash: 'SHA-256'
+        },
+        false, // not extractable
+        ['decrypt']
+    );
+
+    return privateKey;
+}
+
+/**
+ * Validate that a PEM string is a valid PKCS#8 private key
+ *
+ * @param {string} pem - The PEM string to validate
+ * @returns {boolean}
+ */
+function validatePrivateKeyFormat(pem) {
+    if (!pem || typeof pem !== 'string') {
+        return false;
+    }
+
+    const hasHeader = pem.includes('-----BEGIN PRIVATE KEY-----');
+    const hasFooter = pem.includes('-----END PRIVATE KEY-----');
+
+    return hasHeader && hasFooter;
+}
+
+module.exports = {
+    unwrapCms,
+    importPrivateKey,
+    validatePrivateKeyFormat,
+    initializePkijsEngine
+};

package/src/attestation/index.js

@@ -0,0 +1,66 @@
+/**
+ * @faizahmed/secret-keystore - Attestation Module
+ *
+ * Complete AWS Nitro Enclave attestation support including:
+ * - Ephemeral RSA key pair generation
+ * - Attestation document fetching from Anjuna/Nitro endpoints
+ * - CMS EnvelopedData unwrapping with PKIjs
+ * - Lifecycle management with 5-minute refresh
+ */
+
+// Key pair utilities
+const {
+    generateEphemeralKeyPair,
+    pemToDerPublic,
+    pemToDerPrivate,
+    toBase64Url,
+    toBase64,
+    generateNonce,
+    prepareAttestationParams
+} = require('./key-pair');
+
+// CMS unwrapping
+const {
+    unwrapCms,
+    importPrivateKey,
+    validatePrivateKeyFormat,
+    initializePkijsEngine
+} = require('./cms-unwrap');
+
+// Attestation client
+const {
+    fetchAttestationDocument,
+    isNitroEnclave,
+    isAttestationAvailable,
+    DEFAULT_ATTESTATION_ENDPOINT
+} = require('./attestation-client');
+
+// Attestation manager
+const { AttestationManager, createAttestationManager } = require('./attestation-manager');
+
+module.exports = {
+    // Key pair
+    generateEphemeralKeyPair,
+    pemToDerPublic,
+    pemToDerPrivate,
+    toBase64Url,
+    toBase64,
+    generateNonce,
+    prepareAttestationParams,
+
+    // CMS
+    unwrapCms,
+    importPrivateKey,
+    validatePrivateKeyFormat,
+    initializePkijsEngine,
+
+    // Client
+    fetchAttestationDocument,
+    isNitroEnclave,
+    isAttestationAvailable,
+    DEFAULT_ATTESTATION_ENDPOINT,
+
+    // Manager
+    AttestationManager,
+    createAttestationManager
+};

package/src/attestation/key-pair.js

@@ -0,0 +1,129 @@
+/**
+ * @faizahmed/secret-keystore - Ephemeral Key Pair Generation
+ *
+ * Generates RSA-4096 key pairs for attestation document requests.
+ * The public key is embedded in the attestation document, and the
+ * private key is used to unwrap the CMS EnvelopedData from KMS.
+ */
+
+const crypto = require('node:crypto');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY PAIR GENERATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate an ephemeral RSA-4096 key pair for attestation
+ * @returns {{ publicKey: string, privateKey: string, publicKeyDer: Buffer, privateKeyDer: Buffer }}
+ */
+function generateEphemeralKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
+        modulusLength: 4096,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
+    });
+
+    // Export public key as DER (for attestation request)
+    const publicKeyDer = crypto
+        .createPublicKey({ key: publicKey, format: 'pem' })
+        .export({ format: 'der', type: 'spki' });
+
+    // Export private key as DER (for CMS unwrap with OpenSSL, if needed)
+    const privateKeyDer = crypto
+        .createPrivateKey({ key: privateKey, format: 'pem' })
+        .export({ format: 'der', type: 'pkcs1' });
+
+    return {
+        publicKey, // PEM format
+        privateKey, // PEM format (PKCS#8)
+        publicKeyDer, // DER format (SPKI)
+        privateKeyDer // DER format (PKCS#1)
+    };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PEM/DER UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert PEM public key to DER format
+ * @param {string} pem - PEM-encoded public key
+ * @returns {Buffer}
+ */
+function pemToDerPublic(pem) {
+    const base64 = String(pem)
+        .replaceAll('-----BEGIN PUBLIC KEY-----', '')
+        .replaceAll('-----END PUBLIC KEY-----', '')
+        .replaceAll(/\s+/g, '');
+    return Buffer.from(base64, 'base64');
+}
+
+/**
+ * Convert PEM private key to DER format (PKCS#8)
+ * @param {string} pem - PEM-encoded private key
+ * @returns {Buffer}
+ */
+function pemToDerPrivate(pem) {
+    const base64 = String(pem)
+        .replaceAll('-----BEGIN PRIVATE KEY-----', '')
+        .replaceAll('-----END PRIVATE KEY-----', '')
+        .replaceAll(/\s+/g, '');
+    return Buffer.from(base64, 'base64');
+}
+
+/**
+ * Convert buffer to base64url with padding (for attestation params)
+ * @param {Buffer} buf
+ * @returns {string}
+ */
+function toBase64Url(buf) {
+    return Buffer.from(buf).toString('base64').replaceAll('+', '-').replaceAll('/', '_');
+}
+
+/**
+ * Convert buffer to standard base64
+ * @param {Buffer} buf
+ * @returns {string}
+ */
+function toBase64(buf) {
+    return Buffer.from(buf).toString('base64');
+}
+
+/**
+ * Generate a random nonce for attestation
+ * @param {number} [length=16] - Nonce length in bytes
+ * @returns {Buffer}
+ */
+function generateNonce(length = 16) {
+    return crypto.randomBytes(length);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ATTESTATION PARAMS PREPARATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Prepare attestation request parameters
+ * @param {string} publicKeyPem - PEM-encoded public key
+ * @param {string} [userData=''] - Optional user data
+ * @returns {{ publicKey: string, userData: string, nonce: string }}
+ */
+function prepareAttestationParams(publicKeyPem, userData = '') {
+    const publicKeyDer = pemToDerPublic(publicKeyPem);
+
+    return {
+        publicKey: toBase64Url(publicKeyDer),
+        userData: userData ? toBase64Url(Buffer.from(userData, 'utf8')) : '',
+        nonce: toBase64(generateNonce(16))
+    };
+}
+
+module.exports = {
+    generateEphemeralKeyPair,
+    pemToDerPublic,
+    pemToDerPrivate,
+    toBase64Url,
+    toBase64,
+    generateNonce,
+    prepareAttestationParams
+};

package/src/config.js

@@ -0,0 +1,130 @@
+/**
+ * @faizahmed/secret-keystore - Runtime config loader
+ *
+ * Zero-config loader that discovers and cascades .env files, decrypts their
+ * KMS-encrypted (ENC[...]) values, and loads everything into an in-memory
+ * SecretKeyStore.
+ *
+ * SECURITY: decrypted values live ONLY in the returned SecretKeyStore's memory.
+ * They are never written to disk and — unless populateProcessEnv is explicitly
+ * enabled — never placed in process.env. This is deliberate: putting secrets in
+ * process.env widens the RCE blast radius (an attacker with code execution can
+ * dump them with `env`).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseEnvContent } = require('./content-operations');
+const { createSecretKeyStore } = require('./keystore');
+const { validateKmsKeyId } = require('./options');
+
+/**
+ * Resolve the ordered list of .env files to load.
+ *
+ * Cascade order (later overrides earlier):
+ *   .env  →  .env.local  →  .env.<NODE_ENV>  →  .env.<NODE_ENV>.local
+ *
+ * If an explicit `path` is given, only those file(s) are used (in order).
+ *
+ * @param {Object} options
+ * @param {string} [options.cwd=process.cwd()] - Base directory
+ * @param {string|string[]} [options.path] - Explicit file path(s)
+ * @param {string} [options.nodeEnv] - Environment name for the cascade
+ * @returns {string[]} Absolute paths of files that exist, in load order
+ */
+function resolveEnvFiles({ cwd = process.cwd(), path: explicitPath, nodeEnv } = {}) {
+    if (explicitPath) {
+        const list = Array.isArray(explicitPath) ? explicitPath : [explicitPath];
+        return list.map(p => path.resolve(cwd, p)).filter(f => fs.existsSync(f));
+    }
+
+    const names = ['.env', '.env.local'];
+    if (nodeEnv) {
+        names.push(`.env.${nodeEnv}`, `.env.${nodeEnv}.local`);
+    }
+
+    return names.map(n => path.resolve(cwd, n)).filter(f => fs.existsSync(f));
+}
+
+/**
+ * Merge .env files into a single key→value map (later files win).
+ * Values may still be encrypted (ENC[...]) at this stage.
+ *
+ * @param {string[]} files - Absolute file paths, in load order
+ * @returns {{ merged: Record<string, string>, used: string[] }}
+ */
+function mergeEnvFiles(files) {
+    const merged = {};
+    const used = [];
+
+    for (const file of files) {
+        if (!fs.existsSync(file)) continue;
+
+        const content = fs.readFileSync(file, 'utf-8');
+        for (const entry of parseEnvContent(content)) {
+            if (entry.type === 'keyvalue') {
+                merged[entry.key] = entry.value;
+            }
+        }
+        used.push(file);
+    }
+
+    return { merged, used };
+}
+
+/**
+ * Load and cascade .env files into an in-memory SecretKeyStore.
+ *
+ * @param {Object} options
+ * @param {string} options.kmsKeyId - REQUIRED KMS Key ID (explicit; no env fallback)
+ * @param {string} [options.cwd=process.cwd()] - Base directory for discovery
+ * @param {string|string[]} [options.path] - Explicit file path(s) (skips cascade)
+ * @param {string} [options.nodeEnv=process.env.NODE_ENV] - Environment for the cascade
+ * @param {boolean} [options.populateProcessEnv=false] - Opt-in: also copy decrypted
+ *   values into process.env (override). Discouraged — widens RCE blast radius.
+ * @param {Object} [options.processEnv=process.env] - Target object for populateProcessEnv
+ * @param {Object} [options.logger] - Logger instance
+ * @returns {Promise<import('./keystore').SecretKeyStore>} Initialized in-memory store
+ */
+async function config(options = {}) {
+    const {
+        kmsKeyId,
+        cwd = process.cwd(),
+        path: explicitPath,
+        nodeEnv = process.env.NODE_ENV,
+        populateProcessEnv = false,
+        processEnv = process.env,
+        logger,
+        ...keystoreOptions
+    } = options;
+
+    // Explicit-only Key ID: throws ValidationError if missing/invalid.
+    validateKmsKeyId(kmsKeyId);
+
+    const files = resolveEnvFiles({ cwd, path: explicitPath, nodeEnv });
+    const { merged, used } = mergeEnvFiles(files);
+
+    const names = used.map(f => path.basename(f)).join(', ') || '(none)';
+    logger?.info?.(`[config] Loaded ${used.length} env file(s): ${names}`);
+
+    const store = await createSecretKeyStore({ type: 'values', values: merged }, kmsKeyId, {
+        ...keystoreOptions,
+        logger
+    });
+
+    if (populateProcessEnv) {
+        logger?.warn?.(
+            '[config] populateProcessEnv=true: decrypted secrets are being copied into ' +
+                'process.env (override). This widens the RCE blast radius (e.g. `env` dumps ' +
+                'them). Prefer reading from the returned in-memory store.'
+        );
+        for (const [key, value] of Object.entries(store.getAll())) {
+            processEnv[key] = value;
+        }
+    }
+
+    return store;
+}
+
+module.exports = { config, resolveEnvFiles, mergeEnvFiles };