eip-cloud-services 1.2.6 → 1.3.0

package/README.md

@@ -81,6 +81,51 @@ module.exports = {
 4. [MySQL Module](#mysql-module)
 5. [AWS Lambda Module](#aws-lambda-module)
 6. [AWS SQS Module](#aws-sqs-module)
+7. [AWS Secrets Manager Module](#aws-secrets-manager-module)
+
+# AWS Secrets Manager Module
+
+## Overview
+
+This module provides helpers for reading and creating AWS Secrets Manager secrets. Secret reads use a local tmp-directory cache by default to avoid unnecessary AWS requests. Use `bypassCache` when the caller must force a fresh AWS lookup.
+
+## Usage
+
+```javascript
+const { secrets } = require('eip-cloud-services');
+
+const appKey = await secrets.get('my-service/apple-news-app-key');
+const configSecret = await secrets.get('my-service/config', { parseJson: true });
+```
+
+## Creating Secrets
+
+Existing secrets are never overwritten.
+
+```javascript
+await secrets.set('my-service/apple-news-app-key', 'secret-value');
+await secrets.set('my-service/config', { apiKey: 'secret-value' });
+```
+
+CLI usage:
+
+```bash
+npm run secrets:set -- --name=my-service/apple-news-app-key --value='secret-value'
+npm run secrets:set -- --name=my-service/config --json='{"apiKey":"secret-value"}'
+npm run secrets:set -- --name=my-service/apple-news-app-key --file=./secret.txt
+```
+
+If `--name` is omitted, the script uses the current `package.json` name. If no package name is available, it prompts for one.
+
+## Cache Options
+
+By default `secrets.get()` checks a local tmp cache first and writes AWS results back to that cache. There is no TTL. To force AWS:
+
+```javascript
+await secrets.get('my-service/apple-news-app-key', { bypassCache: true });
+```
+
+Set `EIP_SECRETS_CACHE_DIR` or `secrets.cacheDir` to control cache location.
 
 # AWS Lambda Module
 

package/index.js

@@ -4,5 +4,6 @@ exports.s3 = require ( './src/s3' );
 exports.cdn = require ( './src/cdn' );
 exports.lambda = require ( './src/lambda' );
 exports.sqs = require ( './src/sqs' );
+exports.secrets = require ( './src/secrets' );
 exports.mysql = require ( './src/mysql' );
 exports.mysql8 = require ( './src/mysql8' );

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "eip-cloud-services",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "Houses a collection of helpers for connecting with Cloud services.",
   "main": "index.js",
   "scripts": {
-    "test": "mocha"
+    "test": "mocha",
+    "secrets:set": "node scripts/set-secret.js"
   },
   "author": "Oliver Edgington <oliver@edgington.com>",
   "license": "ISC",

package/scripts/set-secret.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+const fs = require ( 'fs' );
+const readline = require ( 'readline' );
+const secrets = require ( '../src/secrets' );
+
+const parseArgs = ( argv = process.argv.slice ( 2 ) ) => {
+    const args = {};
+    for ( let i = 0; i < argv.length; i++ ) {
+        const arg = argv[ i ];
+        if ( !arg.startsWith ( '--' ) ) continue;
+
+        const [ rawKey, inlineValue ] = arg.slice ( 2 ).split ( '=' );
+        const key = rawKey.replace ( /-([a-z])/g, ( _match, char ) => char.toUpperCase () );
+        if ( inlineValue !== undefined ) {
+            args[ key ] = inlineValue;
+            continue;
+        }
+
+        if ( argv[ i + 1 ] && !argv[ i + 1 ].startsWith ( '--' ) ) {
+            args[ key ] = argv[ i + 1 ];
+            i++;
+            continue;
+        }
+
+        args[ key ] = true;
+    }
+
+    return args;
+};
+
+const prompt = question => new Promise ( resolve => {
+    const rl = readline.createInterface ( {
+        input: process.stdin,
+        output: process.stdout
+    } );
+    rl.question ( question, answer => {
+        rl.close ();
+        resolve ( answer.trim () );
+    } );
+} );
+
+const resolveSecretValue = args => {
+    if ( args.value !== undefined ) return String ( args.value );
+    if ( args.json !== undefined ) return JSON.parse ( String ( args.json ) );
+    if ( args.file ) return fs.readFileSync ( String ( args.file ), 'utf8' );
+    throw new Error ( 'Missing secret value. Use --value, --json, or --file.' );
+};
+
+const main = async () => {
+    const args = parseArgs ();
+    const name = secrets.resolveDefaultSecretName ( { name: args.name } ) || await prompt ( 'Secret name: ' );
+    if ( !name ) throw new Error ( 'Secret name is required.' );
+
+    const value = resolveSecretValue ( args );
+    const response = await secrets.set ( name, value, {
+        region: args.region,
+        description: args.description,
+        cacheDir: args.cacheDir
+    } );
+
+    process.stdout.write ( JSON.stringify ( {
+        name,
+        arn: response.ARN || response.arn || null,
+        versionId: response.VersionId || response.versionId || null
+    }, null, 2 ) );
+    process.stdout.write ( '\n' );
+};
+
+if ( require.main === module ) {
+    main ().catch ( error => {
+        process.stderr.write ( `${ error?.message || error }\n` );
+        process.exitCode = 1;
+    } );
+}
+
+module.exports = {
+    parseArgs,
+    resolveSecretValue
+};

package/src/s3.js

@@ -50,7 +50,9 @@ const zlib = require ( 'zlib' );
 const crypto = require ( 'crypto' );
 const { cwd } = require ( 'process' );
 const { log } = config?.s3?.logsFunction ? require ( `${  cwd ()}/${config?.s3?.logsFunction}` ) : console;
-const S3 = new S3Client ( { region: 'eu-west-1' } );
+const S3 = new S3Client ( {
+    region: process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || config?.s3?.region || 'eu-west-1'
+} );
 const { pipeline, Writable } = require ( 'stream' );
 const util = require ( 'util' );
 const pipelineAsync = util.promisify ( pipeline );
@@ -408,4 +410,4 @@ const streamToBuffer = async ( stream ) => {
     await pipelineAsync ( stream, collectorStream );
     
     return Buffer.concat ( chunks );
-};
+};

package/src/secrets.js

@@ -0,0 +1,169 @@
+const { SecretsManagerClient, CreateSecretCommand, DescribeSecretCommand, GetSecretValueCommand } = require ( '@aws-sdk/client-secrets-manager' );
+const crypto = require ( 'crypto' );
+const fs = require ( 'fs' );
+const os = require ( 'os' );
+const path = require ( 'path' );
+
+let config = {};
+const configDirPath = `${ process.cwd ()}/config`;
+if ( fs.existsSync ( configDirPath ) && fs.statSync ( configDirPath ).isDirectory () ) {
+    config = require ( 'config' );
+}
+
+const DEFAULT_REGION = 'eu-west-1';
+const DEFAULT_CACHE_DIR = path.join ( os.tmpdir (), 'eip-cloud-services', 'secrets' );
+
+let clientOverride = null;
+
+const resolveRegion = options => options.region || config?.secrets?.region || process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || DEFAULT_REGION;
+
+const getClient = options => clientOverride || new SecretsManagerClient ( { region: resolveRegion ( options ) } );
+
+const safeCacheFileName = ( secretName, region ) => `${ crypto.createHash ( 'sha256' ).update ( `${ region }:${ secretName }` ).digest ( 'hex' ) }.json`;
+
+const resolveCacheDir = options => options.cacheDir || config?.secrets?.cacheDir || process.env.EIP_SECRETS_CACHE_DIR || DEFAULT_CACHE_DIR;
+
+const resolveCachePath = ( secretName, options = {} ) => path.join ( resolveCacheDir ( options ), safeCacheFileName ( secretName, resolveRegion ( options ) ) );
+
+const readCache = ( secretName, options = {} ) => {
+    if ( options.bypassCache ) return null;
+
+    const cachePath = resolveCachePath ( secretName, options );
+    if ( !fs.existsSync ( cachePath ) ) return null;
+
+    const cached = JSON.parse ( fs.readFileSync ( cachePath, 'utf8' ) );
+    return cached.value;
+};
+
+const writeCache = ( secretName, value, options = {} ) => {
+    if ( options.cache === false ) return;
+
+    const cachePath = resolveCachePath ( secretName, options );
+    fs.mkdirSync ( path.dirname ( cachePath ), { recursive: true, mode: 0o700 } );
+    fs.writeFileSync ( cachePath, JSON.stringify ( {
+        secretName,
+        region: resolveRegion ( options ),
+        cachedAt: Date.now (),
+        value
+    } ), { mode: 0o600 } );
+};
+
+const parseSecretValue = ( value, options = {} ) => {
+    if ( !options.parseJson || typeof value !== 'string' ) return value;
+
+    try {
+        return JSON.parse ( value );
+    }
+    catch ( _error ) {
+        return value;
+    }
+};
+
+const stringifySecretValue = value => typeof value === 'string' ? value : JSON.stringify ( value );
+
+/**
+ * Resolve the default secret name from an explicit value or the current package name.
+ *
+ * @param {object} [options={}] Options.
+ * @param {string} [options.name] Explicit secret name.
+ * @param {string} [options.cwd=process.cwd()] Directory containing package.json.
+ * @returns {string} The resolved secret name, or an empty string when none can be resolved.
+ */
+exports.resolveDefaultSecretName = ( options = {} ) => {
+    if ( options.name ) return String ( options.name ).trim ();
+
+    const packagePath = path.join ( options.cwd || process.cwd (), 'package.json' );
+    if ( !fs.existsSync ( packagePath ) ) return '';
+
+    try {
+        const packageJson = JSON.parse ( fs.readFileSync ( packagePath, 'utf8' ) );
+        return typeof packageJson.name === 'string' ? packageJson.name.trim () : '';
+    }
+    catch ( _error ) {
+        return '';
+    }
+};
+
+/**
+ * Check whether a secret exists in AWS Secrets Manager.
+ *
+ * @param {string} secretName Secret name or ARN.
+ * @param {object} [options={}] Options.
+ * @param {string} [options.region] AWS region.
+ * @returns {Promise<boolean>} True when the secret exists, false when not found.
+ */
+exports.exists = async ( secretName, options = {} ) => {
+    try {
+        await getClient ( options ).send ( new DescribeSecretCommand ( { SecretId: secretName } ) );
+        return true;
+    }
+    catch ( error ) {
+        if ( error?.name === 'ResourceNotFoundException' ) return false;
+        throw error;
+    }
+};
+
+/**
+ * Get a secret value, checking the local tmp cache first unless bypassed.
+ *
+ * @param {string} secretName Secret name or ARN.
+ * @param {object} [options={}] Options.
+ * @param {boolean} [options.bypassCache=false] Force AWS lookup instead of tmp cache.
+ * @param {boolean} [options.cache=true] Write AWS results to tmp cache.
+ * @param {boolean} [options.parseJson=false] Parse JSON string secrets when possible.
+ * @param {string} [options.region] AWS region.
+ * @param {string} [options.cacheDir] Custom cache directory.
+ * @returns {Promise<string|object>} Secret value.
+ */
+exports.get = async ( secretName, options = {} ) => {
+    const cached = readCache ( secretName, options );
+    if ( cached !== null && cached !== undefined ) return parseSecretValue ( cached, options );
+
+    const response = await getClient ( options ).send ( new GetSecretValueCommand ( { SecretId: secretName } ) );
+    const value = response.SecretString || ( response.SecretBinary ? Buffer.from ( response.SecretBinary ).toString ( 'utf8' ) : '' );
+    writeCache ( secretName, value, options );
+
+    return parseSecretValue ( value, options );
+};
+
+/**
+ * Create a new secret in AWS Secrets Manager. Existing secrets are never overwritten.
+ *
+ * @param {string} secretName Secret name.
+ * @param {string|object} value Secret value.
+ * @param {object} [options={}] Options.
+ * @param {string} [options.description] Secret description.
+ * @param {string} [options.region] AWS region.
+ * @param {string} [options.cacheDir] Custom cache directory.
+ * @returns {Promise<object>} AWS CreateSecret response.
+ */
+exports.set = async ( secretName, value, options = {} ) => {
+    if ( await exports.exists ( secretName, options ) ) {
+        throw new Error ( `Secret already exists: ${ secretName }` );
+    }
+
+    const secretString = stringifySecretValue ( value );
+    const response = await getClient ( options ).send ( new CreateSecretCommand ( {
+        Name: secretName,
+        SecretString: secretString,
+        Description: options.description
+    } ) );
+    writeCache ( secretName, secretString, options );
+
+    return response;
+};
+
+exports.__private = {
+    parseSecretValue,
+    readCache,
+    resolveCachePath,
+    safeCacheFileName,
+    stringifySecretValue,
+    writeCache,
+    setClient: client => {
+        clientOverride = client;
+    },
+    clearClient: () => {
+        clientOverride = null;
+    }
+};