configorama 1.2.2 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -29,10 +29,6 @@
   "scripts": {
     "info": "repomix --include \"cli.js,src/**/*.js\" --ignore \"**/*.test.js\" --copy",
     "docs": "node ./scripts/docs.js",
-    "site:dev": "cd site && npm run dev",
-    "site:build": "cd site && npm run build",
-    "site:validate": "cd site && npm run validate",
-    "site:deploy": "cd site && npm run deploy",
     "t": "./scripts/run-tests.sh",
     "test": "npm run test:slow && npm run test:lib && uvu tests \".*\\.test.js$\"",
     "test:tests": "uvu tests \".*\\.test.js$\" ",
@@ -47,17 +43,15 @@
     "publish": "git push origin && git push origin --tags",
     "release:patch": "npm version patch && npm publish",
     "release:minor": "npm version minor && npm publish",
-    "release:major": "npm version major && npm publish",
-    "release": "lerna publish",
-    "version:all": "lerna version --no-push --no-git-tag-version",
-    "test:all": "pnpm -r test"
+    "release:major": "npm version major && npm publish"
   },
   "author": "David Wells",
   "license": "MIT",
   "homepage": "https://github.com/DavidWells/configorama#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DavidWells/configorama"
+    "url": "https://github.com/DavidWells/configorama",
+    "directory": "packages/configorama"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
@@ -83,8 +77,8 @@
   },
   "devDependencies": {
     "@cdktf/hcl2json": "^0.21.0",
+    "@davidwells/op-stash": "^0.1.2",
     "@types/node": "^24.10.1",
-    "lerna": "^9.0.0",
     "markdown-magic": "^4.8.0",
     "tsx": "^4.7.0",
     "typescript": "^5.8.3",
@@ -96,10 +90,14 @@
   },
   "peerDependencies": {
     "@cdktf/hcl2json": ">=0.20.0",
+    "@davidwells/op-stash": ">=0.1.0",
     "ts-node": ">=10.0.0",
     "tsx": ">=4.0.0"
   },
   "peerDependenciesMeta": {
+    "@davidwells/op-stash": {
+      "optional": true
+    },
     "@cdktf/hcl2json": {
       "optional": true
     },
@@ -110,6 +108,5 @@
       "optional": true
     }
   },
-  "packageManager": "pnpm@10.33.0",
-  "gitHead": "05dde9eefc90001bcea7f7e40f173cb87d18b4b6"
+  "gitHead": "54014035ae878f6d6634655e87a8a21df07d1f1f"
 }

package/plugins/onepassword/README.md

@@ -50,6 +50,7 @@ Options:
 | `configDir` | string | Passed to `op` as `--config` |
 | `opPath` | string | Path to the `op` binary (defaults to `op` on `PATH`) |
 | `skipResolution` | boolean | Record metadata and return deterministic placeholders without calling `op` |
+| `cache` | object | Optional cache provider config. `{ provider: 'op-stash' }` enables `@davidwells/op-stash` for every supported `${op...}` syntax |
 
 ## Alias syntax (recommended)
 
@@ -160,6 +161,49 @@ configorama: requesting 3 items from 1Password (expect an authorization prompt)
 
 The hint is TTY-only — silent in CI and pipes.
 
+## Optional op-stash
+
+For fresh-process workflows such as agents repeatedly running `configx .env -- <command>`, install `@davidwells/op-stash` and opt in explicitly:
+
+```bash
+npm install @davidwells/op-stash
+```
+
+```js
+const createOnePasswordResolver = require('configorama/plugins/onepassword')
+
+module.exports = {
+  variableSources: [
+    createOnePasswordResolver({
+      cache: {
+        provider: 'op-stash',
+        ttlSeconds: 300,
+        scope: process.env.OP_STASH_SCOPE || 'user',
+        fallbackToOp: false,
+        allowServiceAccountTokenCache: false
+      }
+    })
+  ]
+}
+```
+
+Every supported syntax caches when the cache option is configured — aliases, item names and IDs, private links, explicit fields, inferred fields, and structured note key paths, plus direct `op://` refs:
+
+```yaml
+a: ${op:npm.NPM_TOKEN}            # alias + structured note key path
+b: ${op(database-prod).password}  # item name + field
+c: ${op(<private link>).KEY}      # private link + key
+d: ${op(op://vault/item/field)}   # direct secret ref
+```
+
+The cache stores **final resolved values only**, never `op item get` JSON. A cached entry is exactly the string a variable resolved to, so the daemon never holds more secret material than a config actually requested, and a cache hit returns the value without any `op` call. Item JSON is deliberately not cached: whole items hold every revealed field, complicate invalidation, and would turn the cache into something 1Password-shape-aware instead of a scalar secret store.
+
+One granularity consequence: `${op(op://vault/item/notesPlain).KEY}` caches the selected `KEY` value, not the whole `notesPlain` field. Resolving a key path that no earlier run resolved costs one fresh `op` call even when a sibling key is already cached.
+
+Values live in daemon memory only — until TTL expiry, `op-stash clear`, or `op-stash stop`; nothing is written to disk. Short TTLs (minutes, not hours) are recommended for interactive agent workflows. `OP_STASH_DISABLED=1` bypasses all cache paths.
+
+The plugin fails closed by default when a configured cache provider is broken. Set `fallbackToOp: true` to degrade to direct resolution. If `OP_SERVICE_ACCOUNT_TOKEN` is set, the cache is bypassed unless `allowServiceAccountTokenCache: true` is configured.
+
 ## Security model
 
 - Secrets are fetched from `op` at resolution time. The plugin never writes them to disk, never logs CLI output, and never passes resolved values as command-line arguments. Resolved values **do** enter the config object returned to your code — treat that object as sensitive (don't log it, commit it, or emit it to an untrusted sink).

package/plugins/onepassword/cache-ref.js

@@ -0,0 +1,34 @@
+/* Builds synthetic cache refs for final-value op-stash entries.
+   NUL-joined fixed-order dimensions hashed with SHA-256 — never raw links. */
+const crypto = require('crypto')
+
+// Bump whenever field-selection semantics or the envelope shape change:
+// old entries then live under unreachable keys and expire unread.
+const CACHE_REF_SCHEMA_VERSION = 'v1'
+
+/**
+ * Deterministic cache reference for one final-value resolver operation.
+ * Dimensions are requested inputs only — never discovered outputs — so the
+ * key is computable before any op call. account/configDir/opPath are NOT
+ * included here; they travel via getOrSet opts and op-stash applies them as
+ * key dimensions, exactly as it does for read (one owner per dimension).
+ * @param {object} reference - Normalized reference ({ kind, item, vault, section, field, ref })
+ * @param {string|undefined} keyPath - Requested key path
+ * @returns {string} configorama-op://v1/<sha256hex>
+ */
+function buildCacheRef(reference, keyPath) {
+  const itemOrRef = reference.kind === 'secretRef' ? reference.ref : reference.item
+  const parts = [
+    CACHE_REF_SCHEMA_VERSION,
+    reference.kind || '',
+    itemOrRef || '',
+    reference.vault || '',
+    reference.section || '',
+    reference.field || '',
+    keyPath || '',
+  ]
+  const hash = crypto.createHash('sha256').update(parts.join('\0')).digest('hex')
+  return `configorama-op://${CACHE_REF_SCHEMA_VERSION}/${hash}`
+}
+
+module.exports = { buildCacheRef, CACHE_REF_SCHEMA_VERSION }

package/plugins/onepassword/envelope.js

@@ -0,0 +1,45 @@
+/* Encodes cached final values as { value, fieldName } JSON strings.
+   Private plugin convention: op-stash stores these as opaque strings. */
+
+/**
+ * @param {string} value - Final resolved value
+ * @param {string|undefined} fieldName - Discovered field name for audit metadata
+ * @returns {string} Envelope JSON string
+ */
+function encodeEnvelope(value, fieldName) {
+  if (typeof value !== 'string') throw new Error('Envelope value must be a string.')
+  return JSON.stringify(fieldName === undefined ? { value } : { value, fieldName })
+}
+
+/**
+ * @param {string} encoded - Envelope JSON string
+ * @returns {{value: string, fieldName: string|undefined}}
+ */
+function decodeEnvelope(encoded) {
+  let parsed
+  try {
+    parsed = JSON.parse(encoded)
+  } catch (err) {
+    throw new Error('Malformed op-stash envelope: not valid JSON.')
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || typeof parsed.value !== 'string') {
+    throw new Error('Malformed op-stash envelope: missing string value.')
+  }
+  return { value: parsed.value, fieldName: typeof parsed.fieldName === 'string' ? parsed.fieldName : undefined }
+}
+
+/**
+ * validateCached hook: rejecting here makes getOrSet recompute and overwrite.
+ * @param {string} encoded - Cached string
+ * @returns {boolean}
+ */
+function isValidEnvelope(encoded) {
+  try {
+    decodeEnvelope(encoded)
+    return true
+  } catch (err) {
+    return false
+  }
+}
+
+module.exports = { encodeEnvelope, decodeEnvelope, isValidEnvelope }

package/plugins/onepassword/index.js

@@ -4,6 +4,8 @@ const { readSecretRef, getItem } = require('./op-cli')
 const { validateAliasName, normalizeRefValue, isItemId } = require('./normalize')
 const { selectField, trySelectField } = require('./fields')
 const { parseStructuredSecret, getKeyPath } = require('./parser')
+const { buildCacheRef } = require('./cache-ref')
+const { encodeEnvelope, decodeEnvelope, isValidEnvelope } = require('./envelope')
 
 const OP_PREFIX = 'op'
 
@@ -45,6 +47,7 @@ const opVariableSyntax = /^op(?::|\()/
  * @param {string} [options.opPath] - Path to the op binary (defaults to "op" on PATH)
  * @param {string} [options.programName] - Host tool name for the auth-prompt hint (defaults to $CONFIGORAMA_PROGRAM_NAME or "configorama")
  * @param {boolean} [options.skipResolution] - Collect metadata and return placeholders without calling op
+ * @param {object} [options.cache] - Optional cache provider config ({ provider: 'op-stash', ttlSeconds, scope, fallbackToOp, allowServiceAccountTokenCache })
  * @param {Function} [options.execFile] - execFile injection for tests (not serializable; unavailable in sync mode)
  * @returns {object} Variable source configuration with resolver and metadata collector
  */
@@ -56,9 +59,17 @@ function createOnePasswordResolver(options = {}) {
     opPath,
     programName,
     skipResolution = false,
+    cache,
     execFile,
   } = options
 
+  // An unrecognized provider fails loudly: a typo silently disabling a
+  // requested secrets cache would look identical to working caching.
+  if (cache && cache.provider !== 'op-stash') {
+    throw new Error(`Unknown 1Password cache provider "${cache.provider}". Supported: 'op-stash'.`)
+  }
+  const opStash = cache ? loadOpStash() : undefined
+
   const aliasRefs = {}
   for (const alias of Object.keys(refs)) {
     validateAliasName(alias)
@@ -207,6 +218,75 @@ function createOnePasswordResolver(options = {}) {
     return `[OP:item:${reference.item}${keyPath ? `:${keyPath}` : ''}]`
   }
 
+  /**
+   * Resolve a normalized reference to its final value.
+   * Direct secret refs without a key path keep the read path (same daemon
+   * keys as standalone `op-stash read`); every other syntax caches its
+   * final resolved value under a synthetic ref.
+   * @param {object} reference - Normalized reference
+   * @param {string|undefined} keyPath - Requested key path
+   * @param {string} [label] - Human label for the auth hint
+   * @returns {Promise<{value: string, fieldName: string|undefined}>} Final value
+   */
+  async function resolveReference(reference, keyPath, label) {
+    if (reference.kind === 'secretRef' && keyPath === undefined) {
+      const value = await cached(secretRefCache, `${scopeKey}|${reference.ref}`, () => {
+        return readSecretRefWithOptionalCache(reference.ref)
+      }, label)
+      return { value, fieldName: undefined }
+    }
+    return finalValueWithOptionalCache(reference, keyPath, label)
+  }
+
+  /**
+   * Final-value caching through op-stash getOrSet. The cached payload is a
+   * { value, fieldName } envelope so audit metadata survives cache hits;
+   * malformed envelopes are rejected via validateCached and recomputed.
+   * @param {object} reference - Normalized reference
+   * @param {string|undefined} keyPath - Requested key path
+   * @param {string} [label] - Human label for the auth hint
+   * @returns {Promise<{value: string, fieldName: string|undefined}>} Final value
+   */
+  async function finalValueWithOptionalCache(reference, keyPath, label) {
+    if (!opStash || shouldBypassOpStash()) {
+      return computeFinalValue(reference, keyPath, label)
+    }
+    const cacheRef = buildCacheRef(reference, keyPath)
+    const encoded = await opStash.getOrSet(cacheRef, async () => {
+      const resolved = await computeFinalValue(reference, keyPath, label)
+      return encodeEnvelope(resolved.value, resolved.fieldName)
+    }, {
+      account,
+      configDir,
+      opPath,
+      ttlSeconds: cache.ttlSeconds,
+      scope: cache.scope,
+      fallbackToOp: cache.fallbackToOp === true,
+      validateCached: isValidEnvelope,
+      stderr: process.stderr,
+    })
+    return decodeEnvelope(encoded)
+  }
+
+  /**
+   * Compute the final resolver value with no persistent cache involved.
+   * This is the getOrSet producer body; the cold-start latch lives in here
+   * (via cached) so daemon hits never serialize behind it and auth hints
+   * only print when an op call actually happens.
+   * @param {object} reference - Normalized reference
+   * @param {string|undefined} keyPath - Requested key path
+   * @param {string} [label] - Human label for the auth hint
+   * @returns {Promise<{value: string, fieldName: string|undefined}>} Final value
+   */
+  async function computeFinalValue(reference, keyPath, label) {
+    const { value, fieldName, remainingKeyPath } = await selectBackingValue(reference, keyPath, label)
+    if (remainingKeyPath === undefined) {
+      return { value, fieldName }
+    }
+    const parsedValue = parseStructuredSecret(value, { fieldName })
+    return { value: getKeyPath(parsedValue, remainingKeyPath, fieldName), fieldName }
+  }
+
   /**
    * Fetch and select the backing field value for a normalized reference.
    * For items without a configured field, the first key path segment may
@@ -218,7 +298,7 @@ function createOnePasswordResolver(options = {}) {
    * @param {string} [label] - Human label for the auth hint
    * @returns {Promise<{value: string, fieldName: string, remainingKeyPath: string|undefined}>} Selected value
    */
-  async function fetchValue(reference, keyPath, label) {
+  async function selectBackingValue(reference, keyPath, label) {
     if (reference.kind === 'secretRef') {
       const value = await cached(secretRefCache, `${scopeKey}|${reference.ref}`, () => {
         return readSecretRef(reference.ref, cliOptions)
@@ -301,16 +381,11 @@ function createOnePasswordResolver(options = {}) {
       || (configPath ? configPath.split('.').pop() : undefined)
       || reference.field
       || (reference.kind === 'secretRef' ? reference.ref : reference.item)
-    const { value, fieldName, remainingKeyPath } = await fetchValue(reference, keyPath, label)
-    if (entry.field === undefined && reference.kind !== 'secretRef') {
-      entry.field = fieldName
+    const resolved = await resolveReference(reference, keyPath, label)
+    if (entry.field === undefined && reference.kind !== 'secretRef' && resolved.fieldName !== undefined) {
+      entry.field = resolved.fieldName
     }
-
-    if (remainingKeyPath === undefined) {
-      return value
-    }
-    const parsedValue = parseStructuredSecret(value, { fieldName })
-    return getKeyPath(parsedValue, remainingKeyPath, fieldName)
+    return resolved.value
   }
 
   return {
@@ -342,6 +417,7 @@ function createOnePasswordResolver(options = {}) {
    */
   function buildSyncOptions() {
     const syncOptions = { refs, account, configDir, opPath, skipResolution }
+    if (cache !== undefined) syncOptions.cache = cache
     if (execFile) {
       // Functions cannot cross the JSON boundary into the sync worker;
       // flag it so sync-factory can fail loudly instead of silently
@@ -350,6 +426,48 @@ function createOnePasswordResolver(options = {}) {
     }
     return syncOptions
   }
+
+  /**
+   * @param {string} ref - Direct op:// secret reference
+   * @returns {Promise<string>} Secret value
+   */
+  function readSecretRefWithOptionalCache(ref) {
+    if (!opStash || shouldBypassOpStash()) {
+      return readSecretRef(ref, cliOptions)
+    }
+    return opStash.read(ref, {
+      account,
+      configDir,
+      opPath,
+      ttlSeconds: cache.ttlSeconds,
+      scope: cache.scope,
+      fallbackToOp: cache.fallbackToOp === true,
+      stderr: process.stderr,
+    })
+  }
+
+  /**
+   * @returns {boolean} Whether cache must be bypassed for this read
+   */
+  function shouldBypassOpStash() {
+    if (process.env.OP_STASH_DISABLED === '1') return true
+    if (execFile) return true
+    if (process.env.OP_SERVICE_ACCOUNT_TOKEN && !(cache && cache.allowServiceAccountTokenCache === true)) {
+      return true
+    }
+    return false
+  }
+}
+
+/**
+ * @returns {object} @davidwells/op-stash API
+ */
+function loadOpStash() {
+  try {
+    return require('@davidwells/op-stash')
+  } catch (err) {
+    throw new Error('1Password op-stash provider requested but @davidwells/op-stash is not installed. Install it with: npm install @davidwells/op-stash')
+  }
 }
 
 module.exports = createOnePasswordResolver

package/types/src/resolvers/valueFromSelf.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=valueFromSelf.d.ts.map

package/types/src/resolvers/valueFromSelf.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"valueFromSelf.d.ts","sourceRoot":"","sources":["../../../src/resolvers/valueFromSelf.js"],"names":[],"mappings":""}