@faizahmed/secret-keystore 1.1.0

package/package.json

@@ -0,0 +1,77 @@
+{
+    "name": "@faizahmed/secret-keystore",
+    "version": "1.1.0",
+    "description": "Secure secrets management with AWS KMS encryption, in-memory keystore, and Nitro Enclave attestation support",
+    "main": "src/index.js",
+    "types": "src/index.d.ts",
+    "bin": {
+        "secret-keystore": "bin/cli.js"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "packageManager": "pnpm@9.15.9",
+    "files": [
+        "src/**/*.js",
+        "src/**/*.d.ts",
+        "bin/**/*.js",
+        "README.md",
+        "SECURITY.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "@aws-sdk/client-kms": "^3.1067.0",
+        "asn1js": "^3.0.10",
+        "pkijs": "^3.4.0",
+        "pvtsutils": "^1.3.5"
+    },
+    "peerDependencies": {
+        "@aws-sdk/client-kms": "^3.x",
+        "js-yaml": "^4.x"
+    },
+    "peerDependenciesMeta": {
+        "js-yaml": {
+            "optional": true
+        }
+    },
+    "scripts": {
+        "test": "node --test test/*.test.js",
+        "test:coverage": "c8 node --test test/*.test.js",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier --write \"{src,bin,test}/**/*.js\"",
+        "format:check": "prettier --check \"{src,bin,test}/**/*.js\"",
+        "typecheck": "tsc --noEmit --strict --lib es2022 src/index.d.ts",
+        "pack:local": "pnpm pack"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.0.0",
+        "aws-sdk-client-mock": "^4.1.0",
+        "c8": "^10.1.0",
+        "eslint": "^9.0.0",
+        "globals": "^15.0.0",
+        "prettier": "^3.3.0",
+        "typescript": "^5.5.0"
+    },
+    "keywords": [
+        "kms",
+        "secrets",
+        "keystore",
+        "aws",
+        "encryption",
+        "decryption",
+        "dotenv",
+        "nitro",
+        "attestation"
+    ],
+    "author": "Faiz Ahmed Farooqui",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/faizahmedfarooqui/secret-keystore.git"
+    },
+    "homepage": "https://github.com/faizahmedfarooqui/secret-keystore#readme",
+    "bugs": {
+        "url": "https://github.com/faizahmedfarooqui/secret-keystore/issues"
+    }
+}

package/src/attestation/attestation-client.js

@@ -0,0 +1,146 @@
+/**
+ * @faizahmed/secret-keystore - Attestation Client
+ *
+ * Fetches attestation documents from AWS Nitro Enclaves or Anjuna endpoints.
+ * The attestation document contains the caller's public key and is signed
+ * by the enclave's PCR values.
+ */
+
+const https = require('node:https');
+const http = require('node:http');
+const { URL } = require('node:url');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ATTESTATION CLIENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Default attestation endpoint (Anjuna)
+ */
+const DEFAULT_ATTESTATION_ENDPOINT = 'http://localhost:50123/api/v1/attestation/report';
+
+/**
+ * Fetch attestation document from Nitro/Anjuna endpoint
+ *
+ * @param {Object} params - Attestation request parameters
+ * @param {string} params.publicKey - Base64url-encoded DER public key
+ * @param {string} [params.userData] - Base64url-encoded user data
+ * @param {string} [params.nonce] - Base64-encoded nonce
+ * @param {Object} [options] - Client options
+ * @param {string} [options.endpoint] - Attestation endpoint URL
+ * @param {number} [options.timeout] - Request timeout in milliseconds (default: 10000)
+ * @returns {Promise<{ attestationDocument: string }>} - Base64-encoded attestation document
+ * @throws {Error} If the request fails
+ */
+async function fetchAttestationDocument(params, options = {}) {
+    const endpoint = options.endpoint || DEFAULT_ATTESTATION_ENDPOINT;
+    const timeout = options.timeout || 10000;
+
+    // Build URL with query parameters
+    const url = new URL(endpoint);
+    if (params.publicKey) {
+        url.searchParams.set('public_key', params.publicKey);
+    }
+    if (params.userData) {
+        url.searchParams.set('user_data', params.userData);
+    }
+    if (params.nonce) {
+        url.searchParams.set('nonce', params.nonce);
+    }
+
+    // Choose http or https based on protocol
+    const client = url.protocol === 'https:' ? https : http;
+
+    return new Promise((resolve, reject) => {
+        const req = client.get(
+            url.toString(),
+            {
+                timeout,
+                headers: {
+                    Accept: 'application/octet-stream'
+                }
+            },
+            res => {
+                const chunks = [];
+
+                res.on('data', chunk => chunks.push(chunk));
+
+                res.on('end', () => {
+                    const buffer = Buffer.concat(chunks);
+
+                    if (res.statusCode !== 200) {
+                        const errorMessage = buffer.toString('utf8');
+                        reject(
+                            new Error(
+                                `Attestation endpoint returned ${res.statusCode}: ${errorMessage}`
+                            )
+                        );
+                        return;
+                    }
+
+                    // The response is binary attestation document, convert to base64
+                    const attestationDocument = buffer.toString('base64');
+
+                    resolve({ attestationDocument });
+                });
+            }
+        );
+
+        req.on('error', error => {
+            reject(new Error(`Attestation request failed: ${error.message}`));
+        });
+
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error(`Attestation request timed out after ${timeout}ms`));
+        });
+    });
+}
+
+/**
+ * Check if running inside a Nitro Enclave
+ * Nitro Enclaves have /dev/nsm device
+ *
+ * @returns {boolean}
+ */
+function isNitroEnclave() {
+    try {
+        const fs = require('node:fs');
+        return fs.existsSync('/dev/nsm');
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Check if attestation endpoint is reachable
+ *
+ * @param {string} [endpoint] - Attestation endpoint URL
+ * @param {number} [timeout] - Request timeout in milliseconds
+ * @returns {Promise<boolean>}
+ */
+async function isAttestationAvailable(endpoint = DEFAULT_ATTESTATION_ENDPOINT, timeout = 3000) {
+    const url = new URL(endpoint);
+    const client = url.protocol === 'https:' ? https : http;
+
+    return new Promise(resolve => {
+        const req = client.get(url.toString(), { timeout }, res => {
+            // Any response means the endpoint is available
+            res.resume(); // Consume response data to free up memory
+            resolve(true);
+        });
+
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+
+module.exports = {
+    fetchAttestationDocument,
+    isNitroEnclave,
+    isAttestationAvailable,
+    DEFAULT_ATTESTATION_ENDPOINT
+};

package/src/attestation/attestation-manager.js

@@ -0,0 +1,339 @@
+/**
+ * @faizahmed/secret-keystore - Attestation Manager
+ *
+ * Manages the attestation document lifecycle:
+ * - Generates ephemeral RSA key pairs
+ * - Fetches attestation documents from Nitro/Anjuna
+ * - Caches attestation materials
+ * - Handles 5-minute age limit by refreshing on demand
+ * - Provides CMS unwrapping for KMS CiphertextForRecipient
+ */
+
+const { DecryptCommand } = require('@aws-sdk/client-kms');
+const { generateEphemeralKeyPair, prepareAttestationParams } = require('./key-pair');
+const { fetchAttestationDocument, DEFAULT_ATTESTATION_ENDPOINT } = require('./attestation-client');
+const { unwrapCms } = require('./cms-unwrap');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ATTESTATION MANAGER CLASS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * AttestationManager handles the full attestation lifecycle
+ */
+class AttestationManager {
+    constructor(options = {}) {
+        this.endpoint = options.endpoint || DEFAULT_ATTESTATION_ENDPOINT;
+        this.timeout = options.timeout || 10000;
+        this.userData = options.userData || '';
+        this.logger = options.logger || null;
+
+        // Cached materials
+        this.cachedKeyPair = null;
+        this.cachedDocument = null;
+        this.cachedTimestamp = null;
+
+        // Initialization state
+        this.initialized = false;
+        this.initError = null;
+
+        // Mutex for concurrent initialization
+        this.initPromise = null;
+    }
+
+    /**
+     * Initialize attestation (generate key pair, fetch document)
+     * @returns {Promise<void>}
+     */
+    async initialize() {
+        // Prevent concurrent initialization
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+
+        this.initPromise = this._doInitialize();
+        try {
+            await this.initPromise;
+        } finally {
+            this.initPromise = null;
+        }
+    }
+
+    /**
+     * Internal initialization logic
+     * @private
+     */
+    async _doInitialize() {
+        this._log('debug', 'Initializing attestation...');
+        this.initialized = false;
+        this.initError = null;
+
+        try {
+            // 1. Generate ephemeral RSA-4096 key pair
+            this._log('debug', 'Generating ephemeral RSA-4096 key pair...');
+            this.cachedKeyPair = generateEphemeralKeyPair();
+
+            // 2. Prepare attestation request parameters
+            const params = prepareAttestationParams(this.cachedKeyPair.publicKey, this.userData);
+
+            // 3. Fetch attestation document
+            this._log('debug', `Fetching attestation document from ${this.endpoint}...`);
+            const response = await fetchAttestationDocument(params, {
+                endpoint: this.endpoint,
+                timeout: this.timeout
+            });
+
+            // 4. Cache the document
+            this.cachedDocument = response.attestationDocument;
+            this.cachedTimestamp = Date.now();
+            this.initialized = true;
+
+            this._log('info', 'Attestation initialized successfully');
+        } catch (error) {
+            this.initError = error.message;
+            this.initialized = false;
+            this._log('error', `Attestation initialization failed: ${error.message}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Reinitialize attestation (for 5-minute refresh)
+     * @returns {Promise<void>}
+     */
+    async reinitialize() {
+        this._log('warn', 'Reinitializing attestation (5-minute refresh)...');
+        // Clear current cache
+        this.cachedKeyPair = null;
+        this.cachedDocument = null;
+        this.cachedTimestamp = null;
+        this.initialized = false;
+
+        // Re-initialize
+        await this.initialize();
+    }
+
+    /**
+     * Check if attestation is initialized and usable
+     * @returns {boolean}
+     */
+    isInitialized() {
+        return this.initialized && !!this.cachedDocument && !!this.cachedKeyPair;
+    }
+
+    /**
+     * Get cached attestation materials
+     * @returns {{ document: string, privateKey: string, publicKey: string } | null}
+     */
+    getCachedMaterials() {
+        if (!this.isInitialized()) {
+            return null;
+        }
+
+        return {
+            document: this.cachedDocument,
+            privateKey: this.cachedKeyPair.privateKey,
+            publicKey: this.cachedKeyPair.publicKey
+        };
+    }
+
+    /**
+     * Get the age of the cached attestation document in milliseconds
+     * @returns {number | null}
+     */
+    getDocumentAge() {
+        if (!this.cachedTimestamp) {
+            return null;
+        }
+        return Date.now() - this.cachedTimestamp;
+    }
+
+    /**
+     * Perform attested decrypt with KMS
+     *
+     * This method:
+     * 1. Ensures attestation is initialized
+     * 2. Calls KMS Decrypt with Recipient parameter
+     * 3. Handles CiphertextForRecipient by unwrapping with PKIjs
+     * 4. Retries on 5-minute age limit error
+     *
+     * @param {import('@aws-sdk/client-kms').KMSClient} kmsClient - KMS client
+     * @param {Buffer} ciphertextBlob - The encrypted data
+     * @param {string} kmsKeyId - The KMS key ID
+     * @param {Object} [options] - Additional options
+     * @param {string} [options.encryptionAlgorithm] - 'RSAES_OAEP_SHA_256' or 'SYMMETRIC_DEFAULT'
+     * @param {Object} [options.encryptionContext] - KMS encryption context
+     * @returns {Promise<Buffer>} - Decrypted plaintext
+     */
+    async decryptWithAttestation(kmsClient, ciphertextBlob, kmsKeyId, options = {}) {
+        // Ensure initialized
+        if (!this.isInitialized()) {
+            await this.initialize();
+        }
+
+        const materials = this.getCachedMaterials();
+        if (!materials) {
+            throw new Error('Failed to get attestation materials after initialization');
+        }
+
+        try {
+            return await this._performAttestedDecrypt(
+                kmsClient,
+                ciphertextBlob,
+                kmsKeyId,
+                materials,
+                options
+            );
+        } catch (error) {
+            // Check for 5-minute age limit error
+            if (this._isAgeLimitError(error)) {
+                this._log('warn', 'Attestation document expired (5-minute limit), refreshing...');
+
+                // Reinitialize to get fresh materials
+                await this.reinitialize();
+
+                const freshMaterials = this.getCachedMaterials();
+                if (!freshMaterials) {
+                    throw new Error('Failed to get fresh attestation materials');
+                }
+
+                // Retry once with fresh materials
+                return await this._performAttestedDecrypt(
+                    kmsClient,
+                    ciphertextBlob,
+                    kmsKeyId,
+                    freshMaterials,
+                    options
+                );
+            }
+
+            throw error;
+        }
+    }
+
+    /**
+     * Perform the actual attested decrypt
+     * @private
+     */
+    async _performAttestedDecrypt(kmsClient, ciphertextBlob, kmsKeyId, materials, options) {
+        const attestationBuffer = Buffer.from(materials.document, 'base64');
+
+        // Build KMS Decrypt command with Recipient
+        const command = new DecryptCommand({
+            KeyId: kmsKeyId,
+            CiphertextBlob: ciphertextBlob,
+            EncryptionAlgorithm: options.encryptionAlgorithm,
+            EncryptionContext: options.encryptionContext,
+            Recipient: {
+                KeyEncryptionAlgorithm: 'RSAES_OAEP_SHA_256',
+                AttestationDocument: attestationBuffer
+            }
+        });
+
+        this._log('debug', 'Sending KMS Decrypt with Recipient...');
+        const response = await kmsClient.send(command);
+
+        // With Recipient, KMS returns CiphertextForRecipient, NOT Plaintext
+        if (!response.CiphertextForRecipient) {
+            throw new Error(
+                'KMS did not return CiphertextForRecipient - check key policy and Recipient support'
+            );
+        }
+
+        const ciphertextForRecipient = Buffer.from(response.CiphertextForRecipient);
+        this._log(
+            'debug',
+            `Received CiphertextForRecipient (${ciphertextForRecipient.length} bytes)`
+        );
+
+        // Unwrap CMS EnvelopedData using our ephemeral private key
+        this._log('debug', 'Unwrapping CMS EnvelopedData...');
+        const plaintext = await unwrapCms(ciphertextForRecipient, materials.privateKey);
+        this._log('debug', `Decrypted plaintext (${plaintext.length} bytes)`);
+
+        return plaintext;
+    }
+
+    /**
+     * Check if an error is a 5-minute age limit error
+     * @private
+     */
+    _isAgeLimitError(error) {
+        const message = error.message || '';
+        return (
+            message.includes('exceeded the five-minute age limit') ||
+            message.includes('exceeded the five minute age limit') ||
+            message.includes('age limit') ||
+            message.includes('cannot parse the attestation document') ||
+            message.includes('cannot parse attestation document')
+        );
+    }
+
+    /**
+     * Log a message
+     * @private
+     */
+    _log(level, message) {
+        if (this.logger && typeof this.logger[level] === 'function') {
+            this.logger[level](`[AttestationManager] ${message}`);
+        }
+    }
+
+    /**
+     * Get initialization status
+     * @returns {Object}
+     */
+    getStatus() {
+        return {
+            initialized: this.initialized,
+            hasError: !!this.initError,
+            error: this.initError,
+            hasDocument: !!this.cachedDocument,
+            hasKeyPair: !!this.cachedKeyPair,
+            documentAge: this.getDocumentAge(),
+            endpoint: this.endpoint
+        };
+    }
+
+    /**
+     * Destroy the manager and clear all cached materials
+     */
+    destroy() {
+        this.cachedKeyPair = null;
+        this.cachedDocument = null;
+        this.cachedTimestamp = null;
+        this.initialized = false;
+        this.initError = null;
+        this._log('debug', 'Attestation manager destroyed');
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FACTORY FUNCTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create and initialize an AttestationManager
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.endpoint] - Attestation endpoint URL
+ * @param {number} [options.timeout] - Request timeout in ms
+ * @param {string} [options.userData] - User data to include in attestation
+ * @param {Object} [options.logger] - Logger instance
+ * @param {boolean} [options.autoInitialize=true] - Initialize on creation
+ * @returns {Promise<AttestationManager>}
+ */
+async function createAttestationManager(options = {}) {
+    const manager = new AttestationManager(options);
+
+    if (options.autoInitialize !== false) {
+        await manager.initialize();
+    }
+
+    return manager;
+}
+
+module.exports = {
+    AttestationManager,
+    createAttestationManager
+};