configorama 1.0.2 → 1.1.0

package/README.md

@@ -141,6 +141,7 @@ npx configorama inspect config.yml
   - [Functions (Experimental)](#functions-experimental)
 - [Bundled Plugins](#bundled-plugins)
   - [CloudFormation](#cloudformation)
+  - [1Password](#1password)
 - [API Reference](#api-reference)
   - [Async API](#async-api)
   - [Sync API](#sync-api)
@@ -1550,6 +1551,36 @@ Peer dependency (install separately):
 npm install @aws-sdk/client-cloudformation @aws-sdk/credential-providers
 ```
 
+### 1Password
+
+Resolves secret values through the [1Password CLI](https://developer.1password.com/docs/cli/) (`op`). Secrets are fetched at resolution time — never persisted, never logged.
+
+```yaml
+npmToken: ${op:npm.NPM_TOKEN}
+dbPassword: ${op:database}
+directRef: ${op(op://vault/item/field)}
+```
+
+```javascript
+const configorama = require('configorama')
+const createOnePasswordResolver = require('configorama/plugins/onepassword')
+
+const opResolver = createOnePasswordResolver({
+  refs: {
+    npm: 'op://production/npm-automation/notesPlain',
+    database: { item: 'database-prod', vault: 'production', field: 'password' },
+  },
+})
+
+const config = await configorama('config.yml', {
+  variableSources: [opResolver]
+})
+```
+
+Full docs: [`plugins/onepassword/README.md`](./plugins/onepassword/README.md). Covers alias refs, private item links, field inference and ambiguity rules, INI/dotenv key paths, `skipResolution`, and sync usage.
+
+No npm dependencies — requires the `op` binary on `PATH` and a signed-in CLI (or `OP_SERVICE_ACCOUNT_TOKEN`).
+
 ---
 
 ## API Reference

package/package.json

@@ -1,21 +1,27 @@
 {
   "name": "configorama",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",
   "exports": {
     ".": "./src/index.js",
-    "./parse-file": "./src/utils/parsing/parse.js"
+    "./parse-file": "./src/utils/parsing/parse.js",
+    "./plugins/cloudformation": "./plugins/cloudformation/index.js",
+    "./plugins/onepassword": "./plugins/onepassword/index.js"
   },
   "files": [
     "cli.js",
     "src",
+    "plugins",
     "types",
     "index.d.ts",
     "package.json",
     "package-lock.json",
-    "README.md"
+    "README.md",
+    "!plugins/*/*.test.js",
+    "!plugins/*/example",
+    "!plugins/*/node_modules"
   ],
   "bin": {
     "config": "./cli.js",
@@ -56,6 +62,7 @@
     "@davidwells/box-logger": "^2.0.3",
     "@iarna/toml": "^2.2.5",
     "dot-prop": "^5.3.0",
+    "dotenv": "^17.2.2",
     "env-stage-loader": "^1.1.3",
     "find-up": "^3.0.0",
     "git-url-parse": "^14.0.0",

package/plugins/cloudformation/README.md

@@ -0,0 +1,79 @@
+# CloudFormation variable source
+
+Resolves CloudFormation stack output values in configorama configs.
+
+## Syntax
+
+```
+${cf:stackName.outputKey}                   # default region, default credentials
+${cf(region):stackName.outputKey}           # explicit region, default credentials
+${cf(account:region):stackName.outputKey}   # explicit account alias + region
+```
+
+## Usage
+
+```js
+const configorama = require('configorama')
+const createCloudFormationResolver = require('configorama/plugins/cloudformation')
+
+const cfResolver = createCloudFormationResolver({
+  defaultRegion: 'us-east-1',     // optional
+  skipResolution: false,          // true = collect metadata without calling AWS
+  // credentials: { ... }         // optional: bypass env-var discovery
+})
+
+const result = await configorama(configPath, {
+  returnMetadata: true,
+  variableSources: [cfResolver]
+})
+```
+
+## Multi-account
+
+Account aliases map to env-var prefixes. To make `${cf(prod:us-west-2):…}` work,
+set:
+
+```bash
+export PROD_AWS_ACCESS_KEY_ID=AKIA...
+export PROD_AWS_SECRET_ACCESS_KEY=...
+export PROD_AWS_REGION=us-west-2      # optional; falls back to AWS_REGION
+```
+
+The alias is the prefix lowercased, so `STAGING_AWS_ACCESS_KEY_ID` becomes
+`staging`. The alias is **not** an AWS 12-digit account number; it's whatever
+string you put before `_AWS_ACCESS_KEY_ID`.
+
+### Credential discovery rules
+
+1. Scan `process.env` for `{PREFIX}_AWS_ACCESS_KEY_ID` → register `{prefix}` (lowercased).
+2. If `AWS_ACCESS_KEY_ID` is set unprefixed, register it as `default`.
+3. If no `default` exists and there's exactly one prefixed set, use it as
+   `default` (and copy into unprefixed env vars so the AWS SDK can find them).
+
+### Parallel safety
+
+Multiple resolves for the **same** account run concurrently. Resolves for
+**different** accounts are serialized via a refcounted mutex, since
+`process.env` is process-global and two accounts can't be active at once.
+
+## Metadata
+
+Each resolved variable is recorded in `result.metadata.cfReferences`:
+
+```js
+{
+  raw: '${cf(prod:us-west-2):api-service-prod.ApiUrl}',
+  resolved: '${cf(prod:us-west-2):api-service-prod.ApiUrl}',
+  stackName: 'api-service-prod',
+  outputKey: 'ApiUrl',
+  region: 'us-west-2',
+  account: 'prod',                // null when not multi-account
+  configPath: 'provider.environment.API_URL',
+}
+```
+
+## Skip resolution
+
+`skipResolution: true` collects metadata without calling AWS. Values are
+replaced with placeholders like `[CF:prod:us-west-2:api-service-prod.ApiUrl]`,
+useful in CI for dependency analysis.

package/plugins/cloudformation/credentials.js

@@ -0,0 +1,231 @@
+/* AWS credential discovery and runtime swapping for multi-account deployments */
+
+const AWS_CRED_SUFFIXES = [
+  'AWS_ACCESS_KEY_ID',
+  'AWS_SECRET_ACCESS_KEY',
+  'AWS_SESSION_TOKEN',
+  'AWS_REGION'
+]
+
+/** @type {Map<string, Object>|null} */
+let credentialCache = null
+
+// Mutex state for credential swapping (prevents race conditions in parallel deploys)
+/** @type {string|null} */
+let activeAccount = null
+/** @type {number} */
+let activeRefCount = 0
+/** @type {Promise<void>|null} */
+let lockPromise = null
+/** @type {Function|null} */
+let lockResolve = null
+
+/**
+ * @typedef {Object} AwsCredentials
+ * @property {string} [AWS_ACCESS_KEY_ID]
+ * @property {string} [AWS_SECRET_ACCESS_KEY]
+ * @property {string} [AWS_SESSION_TOKEN]
+ * @property {string} [AWS_REGION]
+ */
+
+/**
+ * Discover all credential sets from env vars matching {PREFIX}_AWS_ACCESS_KEY_ID.
+ * E.g., STAGING_AWS_ACCESS_KEY_ID, PROD_AWS_ACCESS_KEY_ID -> "staging", "prod".
+ *
+ * @returns {Map<string, AwsCredentials>} Map of account alias -> credentials
+ */
+function discoverCredentialSets() {
+  if (credentialCache) return credentialCache
+
+  const sets = new Map()
+  const pattern = /^(.+)_AWS_ACCESS_KEY_ID$/
+
+  for (const key of Object.keys(process.env)) {
+    const match = key.match(pattern)
+    if (match) {
+      const prefix = match[1]
+      const name = prefix.toLowerCase()
+
+      sets.set(name, {
+        AWS_ACCESS_KEY_ID: process.env[`${prefix}_AWS_ACCESS_KEY_ID`],
+        AWS_SECRET_ACCESS_KEY: process.env[`${prefix}_AWS_SECRET_ACCESS_KEY`],
+        AWS_SESSION_TOKEN: process.env[`${prefix}_AWS_SESSION_TOKEN`],
+        AWS_REGION: process.env[`${prefix}_AWS_REGION`] || process.env.AWS_REGION,
+      })
+    }
+  }
+
+  // Capture "default" from unprefixed vars if present and not already discovered
+  if (process.env.AWS_ACCESS_KEY_ID && !sets.has('default')) {
+    sets.set('default', {
+      AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID,
+      AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY,
+      AWS_SESSION_TOKEN: process.env.AWS_SESSION_TOKEN,
+      AWS_REGION: process.env.AWS_REGION,
+    })
+  }
+
+  // Auto-default: if no unprefixed creds but exactly one prefixed set, use it as default
+  if (!sets.has('default') && sets.size === 1) {
+    const [, creds] = [...sets.entries()][0]
+    sets.set('default', creds)
+    for (const [key, value] of Object.entries(creds)) {
+      if (value && !process.env[key]) {
+        process.env[key] = value
+      }
+    }
+  }
+
+  credentialCache = sets
+  return sets
+}
+
+/**
+ * Get available account aliases.
+ * @returns {string[]}
+ */
+function getAvailableAccounts() {
+  return [...discoverCredentialSets().keys()]
+}
+
+/**
+ * Check if credentials exist for an account alias.
+ * @param {string} account
+ * @returns {boolean}
+ */
+function hasCredentials(account) {
+  return discoverCredentialSets().has(account.toLowerCase())
+}
+
+/**
+ * Get credentials for an account alias.
+ * @param {string} account
+ * @returns {AwsCredentials|null}
+ */
+function getCredentials(account) {
+  return discoverCredentialSets().get(account.toLowerCase()) || null
+}
+
+/**
+ * Snapshot current AWS env vars so they can be restored after a swap.
+ * @returns {AwsCredentials}
+ */
+function saveCurrentCredentials() {
+  const creds = {}
+  for (const suffix of AWS_CRED_SUFFIXES) {
+    if (process.env[suffix]) {
+      creds[suffix] = process.env[suffix]
+    }
+  }
+  return creds
+}
+
+/**
+ * Replace AWS env vars with the supplied credentials.
+ * @param {AwsCredentials} creds
+ */
+function applyCredentials(creds) {
+  for (const suffix of AWS_CRED_SUFFIXES) {
+    delete process.env[suffix]
+  }
+  for (const [key, value] of Object.entries(creds)) {
+    if (value) process.env[key] = value
+  }
+}
+
+/**
+ * Acquire credential lock for an account.
+ * Same account can have multiple concurrent holders (refcounted).
+ * Different account must wait for current holders to release.
+ *
+ * @param {string} account
+ */
+async function acquireLock(account) {
+  while (activeAccount !== null && activeAccount !== account) {
+    if (lockPromise) {
+      await lockPromise
+    }
+  }
+
+  if (activeAccount === null) {
+    activeAccount = account
+    lockPromise = new Promise(resolve => { lockResolve = resolve })
+  }
+  activeRefCount++
+}
+
+/**
+ * Release credential lock.
+ */
+function releaseLock() {
+  activeRefCount--
+  if (activeRefCount === 0) {
+    activeAccount = null
+    if (lockResolve) {
+      lockResolve()
+      lockResolve = null
+      lockPromise = null
+    }
+  }
+}
+
+/**
+ * Execute a function with specific account credentials.
+ * Uses a refcounted mutex so multiple resolves for the same account run in
+ * parallel but different accounts are serialized — env vars are global, so two
+ * accounts can't be active at once.
+ *
+ * @template T
+ * @param {string} account - Account alias (matches {ACCOUNT}_AWS_ACCESS_KEY_ID prefix, case-insensitive)
+ * @param {() => Promise<T>} fn - Async function to execute with swapped credentials
+ * @returns {Promise<T>}
+ */
+async function useCredentials(account, fn) {
+  const accountLower = account.toLowerCase()
+  const sets = discoverCredentialSets()
+
+  // If requesting default and we have unprefixed creds already active, no swap needed
+  if (accountLower === 'default' && !sets.has('default')) {
+    return fn()
+  }
+
+  const targetCreds = sets.get(accountLower)
+  if (!targetCreds) {
+    const available = [...sets.keys()].join(', ') || 'none'
+    throw new Error(`No credentials found for account "${account}". Available: ${available}`)
+  }
+
+  await acquireLock(accountLower)
+  const savedCreds = saveCurrentCredentials()
+
+  try {
+    applyCredentials(targetCreds)
+    return await fn()
+  } finally {
+    applyCredentials(savedCreds)
+    releaseLock()
+  }
+}
+
+/**
+ * Clear the credential cache and reset mutex state (useful for testing).
+ */
+function clearCache() {
+  credentialCache = null
+  activeAccount = null
+  activeRefCount = 0
+  lockPromise = null
+  lockResolve = null
+}
+
+module.exports = {
+  discoverCredentialSets,
+  getAvailableAccounts,
+  hasCredentials,
+  getCredentials,
+  useCredentials,
+  clearCache,
+  // Low-level (exported for testing)
+  saveCurrentCredentials,
+  applyCredentials,
+}

package/plugins/cloudformation/index.js

@@ -0,0 +1,204 @@
+/* CloudFormation stack output variable source */
+const { useCredentials } = require('./credentials')
+
+const CF_PREFIX = 'cf'
+// Supports: cf:stack.output, cf(region):stack.output, cf(account:region):stack.output
+const cfVariableSyntax = RegExp(/^cf(\([a-z0-9_-]+(:[a-z0-9_-]+)?\))?:/i)
+
+/**
+ * Creates a CloudFormation variable source resolver.
+ *
+ * Syntax:
+ *   ${cf:stackName.outputKey}                       — default region, default creds
+ *   ${cf(region):stackName.outputKey}               — explicit region, default creds
+ *   ${cf(account:region):stackName.outputKey}       — explicit account alias + region
+ *
+ * `account` is an env-var-prefix alias matching `{ACCOUNT}_AWS_ACCESS_KEY_ID`
+ * (case-insensitive). E.g., with PROD_AWS_ACCESS_KEY_ID set, use `cf(prod:us-west-2):…`.
+ * See credentials.js for the discovery rules.
+ *
+ * @param {object} options - Configuration options
+ * @param {object} [options.credentials] - AWS credentials (bypasses env-var discovery)
+ * @param {string} [options.defaultRegion] - Default region if not specified in variable
+ * @param {boolean} [options.skipResolution] - Skip AWS calls, just collect metadata
+ * @param {object} [options.clientOptions] - Additional options passed to CloudFormation client
+ * @returns {object} Variable source configuration with resolver and metadata collector
+ */
+function createCloudFormationResolver(options = {}) {
+  const {
+    credentials,
+    defaultRegion = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || 'us-east-1',
+    skipResolution = false,
+    clientOptions = {}
+  } = options
+
+  const cfReferences = []
+
+  // Clients are cached per (account, region) — different accounts cannot share a
+  // client because the provider chain memoizes credentials on first resolve.
+  const clientCache = new Map()
+  const outputCache = new Map()
+
+  async function getClient(region, account) {
+    const cacheKey = `${account || 'default'}:${region}`
+    if (clientCache.has(cacheKey)) {
+      return clientCache.get(cacheKey)
+    }
+
+    const { CloudFormationClient } = await import('@aws-sdk/client-cloudformation')
+    const { fromNodeProviderChain } = await import('@aws-sdk/credential-providers')
+
+    const clientConfig = {
+      region,
+      credentials: credentials || fromNodeProviderChain(),
+      ...clientOptions
+    }
+
+    const client = new CloudFormationClient(clientConfig)
+    clientCache.set(cacheKey, client)
+    return client
+  }
+
+  async function getStackOutput(stackName, outputKey, region, account = null) {
+    const cacheKey = `${account || 'default'}:${region}:${stackName}`
+
+    if (outputCache.has(cacheKey)) {
+      const outputs = outputCache.get(cacheKey)
+      const output = outputs.find(o => o.OutputKey === outputKey)
+      return output ? output.OutputValue : null
+    }
+
+    const fetchStack = async () => {
+      const client = await getClient(region, account)
+      const { DescribeStacksCommand } = await import('@aws-sdk/client-cloudformation')
+      const command = new DescribeStacksCommand({ StackName: stackName })
+
+      let response
+      try {
+        response = await client.send(command)
+      } catch (err) {
+        const code = err.Code || err.name
+        const accountInfo = account ? ` for account "${account}"` : ''
+        const messages = {
+          ExpiredToken: `AWS credentials expired${accountInfo}. Refresh your credentials and try again.`,
+          AccessDenied: `Access denied to CloudFormation stack "${stackName}" in ${region}${accountInfo}. Check IAM permissions.`,
+          ValidationError: `Stack "${stackName}" not found in ${region}${accountInfo}.`,
+          CredentialsProviderError: `No AWS credentials found${accountInfo}. Configure credentials via environment, ~/.aws/credentials, or pass explicitly.`,
+        }
+        throw new Error(messages[code] || `CloudFormation error: ${err.message}`)
+      }
+
+      if (!response.Stacks || response.Stacks.length === 0) {
+        throw new Error(`CloudFormation stack "${stackName}" not found in region "${region}"`)
+      }
+
+      const outputs = response.Stacks[0].Outputs || []
+      outputCache.set(cacheKey, outputs)
+
+      const output = outputs.find(o => o.OutputKey === outputKey)
+      return output ? output.OutputValue : null
+    }
+
+    if (account) {
+      return useCredentials(account, fetchStack)
+    }
+    return fetchStack()
+  }
+
+  /**
+   * Parse cf: variable string.
+   *
+   * @param {string} varString
+   * @returns {{stackName: string, outputKey: string, region: string, account: string|null}}
+   */
+  function parseVariable(varString) {
+    let region = defaultRegion
+    let account = null
+
+    const paramsMatch = varString.match(/^cf\(([a-z0-9_-]+(?::[a-z0-9_-]+)?)\):/i)
+    if (paramsMatch) {
+      const params = paramsMatch[1]
+      if (params.includes(':')) {
+        const [accountPart, regionPart] = params.split(':')
+        account = accountPart
+        region = regionPart
+      } else {
+        region = params
+      }
+    }
+
+    const withoutPrefix = varString.replace(/^cf(\([a-z0-9_-]+(?::[a-z0-9_-]+)?\))?:/i, '')
+
+    const dotIndex = withoutPrefix.indexOf('.')
+    if (dotIndex === -1) {
+      throw new Error(`Invalid cf: variable syntax "${varString}". Expected format: cf:stackName.outputKey`)
+    }
+
+    const stackName = withoutPrefix.slice(0, dotIndex)
+    const outputKey = withoutPrefix.slice(dotIndex + 1)
+
+    if (!stackName || !outputKey) {
+      throw new Error(`Invalid cf: variable syntax "${varString}". Both stackName and outputKey are required.`)
+    }
+
+    return { stackName, outputKey, region, account }
+  }
+
+  async function resolver(varString, opts, currentObject, valueObject) {
+    const { stackName, outputKey, region, account } = parseVariable(varString)
+
+    cfReferences.push({
+      raw: valueObject.originalSource,
+      resolved: `\${${varString}}`,
+      stackName,
+      outputKey,
+      region,
+      account,
+      configPath: valueObject.path.join('.')
+    })
+
+    if (skipResolution) {
+      const accountInfo = account ? `${account}:` : ''
+      return `[CF:${accountInfo}${region}:${stackName}.${outputKey}]`
+    }
+
+    const value = await getStackOutput(stackName, outputKey, region, account)
+
+    if (value === null) {
+      const accountInfo = account ? `, account: ${account}` : ''
+      throw new Error(`Output "${outputKey}" not found in CloudFormation stack "${stackName}" (region: ${region}${accountInfo})`)
+    }
+
+    return value
+  }
+
+  return {
+    type: CF_PREFIX,
+    source: 'remote',
+    prefix: CF_PREFIX,
+    syntax: '${cf:stackName.outputKey}, ${cf(region):stackName.outputKey}, or ${cf(account:region):stackName.outputKey}',
+    description: 'Resolves CloudFormation stack output values (supports multi-region and multi-account)',
+    match: cfVariableSyntax,
+    resolver,
+    metadataKey: 'cfReferences',
+    collectMetadata: () => cfReferences,
+    clearCache: () => {
+      outputCache.clear()
+      clientCache.clear()
+      cfReferences.length = 0
+    }
+  }
+}
+
+if (require.main === module) {
+  const instance = createCloudFormationResolver()
+  instance.resolver(
+    'cf:rbac-service-v2-dev.RBACTableArn',
+    {},
+    {},
+    { originalSource: '${cf:rbac-service-v2-dev.RBACTableArn}', path: ['provider', 'rbacTableArn'] }
+  ).then(console.log).catch(console.error)
+}
+
+module.exports = createCloudFormationResolver
+module.exports.cfVariableSyntax = cfVariableSyntax