configorama 1.0.2 → 1.1.0

package/plugins/cloudformation/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "configorama-cloudformation",
+  "version": "0.1.1",
+  "description": "CloudFormation variable source plugin for configorama",
+  "main": "index.js",
+  "scripts": {
+    "test": "node index.test.js",
+    "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"
+  },
+  "keywords": [
+    "configorama",
+    "cloudformation",
+    "aws",
+    "serverless"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-cloudformation": "^3.700.0",
+    "@aws-sdk/credential-providers": "^3.700.0"
+  }
+}

package/plugins/onepassword/README.md

@@ -0,0 +1,175 @@
+# configorama 1Password plugin
+
+Resolves configuration values from 1Password through the [`op` CLI](https://developer.1password.com/docs/cli/).
+
+Secrets are fetched at resolution time. The plugin never persists them, 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.
+
+## Prerequisites
+
+- Install the [1Password CLI](https://developer.1password.com/docs/cli/get-started/) and make sure `op` is on `PATH`.
+- Sign in with `op signin`, enable the 1Password app integration, or set `OP_SERVICE_ACCOUNT_TOKEN`. The CLI reads `OP_ACCOUNT`, `OP_CONFIG_DIR`, and `OP_SERVICE_ACCOUNT_TOKEN` on its own — the plugin does not manage auth.
+
+## Setup
+
+```js
+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'
+    },
+    github: {
+      item: 'GitHub',
+      vault: 'development',
+      section: 'credentials',
+      field: 'personal_token'
+    },
+    copiedLink: 'https://start.1password.com/open/i?a=ACCT&v=VAULT_ID&i=ITEM_ID&h=my.1password.com'
+  },
+  // account: 'my',            // passed to op as --account
+  // configDir: '/op/config',  // passed to op as --config
+  // skipResolution: true,     // collect metadata, return placeholders, never call op
+})
+
+const config = await configorama('config.yml', {
+  variableSources: [opResolver]
+})
+```
+
+Options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `refs` | object | Alias map. Values may be an `op://` secret reference, an item ID/name, a private item link, or `{ item, vault, section, field }` / `{ ref }` / `{ url }` |
+| `account` | string | Passed to `op` as `--account` |
+| `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` |
+
+## Alias syntax (recommended)
+
+```yaml
+npmToken: ${op:npm.NPM_TOKEN}
+dbPassword: ${op:database}
+rawNote: ${op:npm}
+nested: ${op:npm.database.password}
+```
+
+Alias names may contain only letters, numbers, and underscores. Dots separate the alias from a key path.
+
+## Direct function syntax
+
+```yaml
+directItem: ${op(item-id-example).NPM_TOKEN}
+spacedName: ${op(My Database Login).password}
+directRef: ${op(op://vault/item/field)}
+directRefKey: ${op(op://vault/item/notesPlain).NPM_TOKEN}
+privateLink: ${op(https://start.1password.com/open/i?a=ACCT&v=VAULT_ID&i=ITEM_ID&h=my.1password.com).NPM_TOKEN}
+```
+
+The parentheses give the parser a reliable boundary for specs containing dots, slashes, spaces, or query parameters. Prefer aliases for readability and auditability.
+
+### Unsupported syntax
+
+- `${op:op://vault/item/field}` — colon syntax is reserved for aliases. Error message points you to `${op(op://vault/item/field)}`.
+- Private links in colon syntax.
+- Public "share with anyone" links (`share.1password.com`) in any position. Use **Copy Private Link** or an `op://` secret reference instead.
+
+## Private item links
+
+Links copied with **Copy Private Link** are supported:
+
+```text
+https://start.1password.com/open/i?a=ACCOUNT&v=VAULT_ID&i=ITEM_ID&h=my.1password.com
+onepassword://open/i?a=ACCOUNT&v=VAULT_ID&i=ITEM_ID&h=my.1password.com
+```
+
+The plugin extracts `i` (item ID) and `v` (vault ID) and fetches with `op item get <itemId> --vault <vaultId>`. The `a`/`h` parameters and the raw URL are never stored in metadata. A link without `v` still resolves, with a warning diagnostic — service accounts and duplicate item names may require vault scoping.
+
+## Field selection
+
+With an explicit `field` on a ref, the plugin matches against the 1Password field `id`, `label`, and `purpose` (case-insensitive). `section` matches `section.id`/`section.label` and is required when the same label exists in multiple sections.
+
+Without a configured `field`, the plugin infers a single secret field:
+
+- `notesPlain`/notes, `purpose: PASSWORD`, `type: CONCEALED`, or secret-like labels (`password`, `token`, `api_key`, `secret`, `credential`, `private key`) are candidates
+- username, email, URL, and other metadata fields are ignored
+- exactly one candidate wins; zero or multiple candidates throw an error telling you to set `field` (and `section`)
+
+Ambiguity is always an error — the plugin never silently prefers `notesPlain` over `password`.
+
+In direct/alias syntax without a configured field, the first key path segment may select a field by name: `${op(My Login).password}` picks the `password` field. If no field matches, the segment is treated as an INI key inside the inferred field: `${op(note-item).NPM_TOKEN}`.
+
+## Structured notes (INI/dotenv)
+
+A secure note like:
+
+```ini
+# npm automation token
+NPM_TOKEN=npm_xxx
+
+[database]
+password=s3cr3t
+```
+
+resolves as:
+
+```yaml
+npmToken: ${op:npm.NPM_TOKEN}          # npm_xxx
+dbPassword: ${op:npm.database.password} # s3cr3t
+rawNote: ${op:npm}                      # the whole note text, unparsed
+```
+
+`${op:alias}` always returns the raw field text — even when it contains `=`. Parsing only happens when a key path is requested, so tokens, base64, and connection strings are never corrupted.
+
+## skipResolution
+
+With `skipResolution: true` the resolver records metadata and returns deterministic placeholders without calling `op`:
+
+```text
+[OP:alias:npm.NPM_TOKEN]
+[OP:secretRef:op://vault/item/field]
+[OP:item:item-id:NPM_TOKEN]
+[OP:privateLink:item-id]
+```
+
+## Sync usage
+
+```js
+const config = configorama.sync('config.yml', {
+  variableSources: [createOnePasswordResolver({ refs })]
+})
+```
+
+Sync mode rebuilds the resolver inside a worker process from JSON-serializable options and always uses the real `op` binary.
+
+## Auth prompts
+
+1Password app-integration auth is per `op` process. The resolver runs the first `op` call alone and queues the rest behind it, so a config referencing many items triggers at most one biometric/authorization prompt per resolution run instead of one per item.
+
+The 1Password dialog names the terminal app (OS-attributed, not customizable), so before the first call the resolver prints a context line to stderr in interactive terminals:
+
+```text
+configorama: requesting 3 items from 1Password (expect an authorization prompt)
+```
+
+The hint is TTY-only — silent in CI and pipes.
+
+## 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).
+- **Direct syntax reads whatever your `op` session can reach.** `${op(op://any-vault/any-item/field)}`, direct item IDs, and private links are not restricted to the aliases in `refs`. If you resolve a config file you do not fully trust while a 1Password session is unlocked, that config can read any secret the session can access. For untrusted config, run with `safeMode: true` (which blocks all custom resolvers) or audit first — `configorama.audit()` flags this resolver as high-severity `remote_secret_read`.
+
+## Safe mode and audit
+
+- `safeMode: true` blocks all custom resolvers during resolution, including this one.
+- `configorama.audit()` registers the plugin without fetching secrets and reports a high-severity `remote_secret_read` finding, because this resolver returns secret material.
+
+## Metadata
+
+With `returnMetadata: true`, references are collected under `metadata.opReferences` — reference kinds, item/vault IDs, fields, key paths, and config paths. Secret values, full private links, and CLI output are never recorded.

package/plugins/onepassword/fields.js

@@ -0,0 +1,126 @@
+/* Selects a field from op item get JSON, explicitly or by inference
+   Ambiguity is always an error - never silently prefers one secret field over another */
+
+const SECRET_LABELS = new Set(['password', 'token', 'api_key', 'api key', 'secret', 'credential', 'private key'])
+const IGNORED_PURPOSES = new Set(['USERNAME'])
+const IGNORED_TYPES = new Set(['URL'])
+const IGNORED_LABELS = new Set(['username', 'email', 'url', 'website', 'created', 'updated', 'title'])
+
+/**
+ * @param {object} item - Parsed op item get JSON
+ * @returns {string} Display name for error messages
+ */
+function itemName(item) {
+  return item.title || item.id || 'unknown'
+}
+
+/**
+ * @param {string|undefined} value - Field attribute
+ * @param {string} wanted - Configured name
+ * @returns {boolean} Case-insensitive equality
+ */
+function matches(value, wanted) {
+  return typeof value === 'string' && value.toLowerCase() === wanted.toLowerCase()
+}
+
+/**
+ * Select a field from an item.
+ * With options.field: explicit matching on id/label/purpose (+ section).
+ * Without: inference over secret-content candidates; ambiguity throws.
+ * @param {object} item - Parsed op item get JSON
+ * @param {object} [options] - { field, section }
+ * @returns {object} The selected field object
+ */
+function selectField(item, options = {}) {
+  const fields = item.fields || []
+  if (options.field) {
+    return selectExplicit(item, fields, options.field, options.section)
+  }
+  return inferField(item, fields)
+}
+
+/**
+ * @param {object} item - Item for error messages
+ * @param {object[]} fields - item.fields
+ * @param {string} wanted - Configured field name
+ * @param {string} [section] - Configured section name
+ * @returns {object} Matched field
+ */
+function selectExplicit(item, fields, wanted, section) {
+  const found = trySelectField(item, { field: wanted, section })
+  if (!found) {
+    throw new Error(`Field "${wanted}" was not found in 1Password item "${itemName(item)}".`)
+  }
+  return found
+}
+
+/**
+ * Match a field by name, returning null when nothing matches.
+ * Still throws on ambiguity - duplicate labels always need a section.
+ * @param {object} item - Parsed op item get JSON
+ * @param {object} options - { field, section }
+ * @returns {object|null} Matched field or null
+ */
+function trySelectField(item, options) {
+  const fields = item.fields || []
+  const wanted = options.field
+  let candidates = fields.filter((field) => {
+    return matches(field.id, wanted) || matches(field.label, wanted) || matches(field.purpose, wanted)
+  })
+
+  if (options.section) {
+    candidates = candidates.filter((field) => {
+      const fieldSection = field.section || {}
+      return matches(fieldSection.id, options.section) || matches(fieldSection.label, options.section)
+    })
+  }
+
+  if (candidates.length === 0) {
+    return null
+  }
+  if (candidates.length > 1) {
+    throw new Error(`1Password item "${itemName(item)}" has multiple fields labeled "${wanted}". Set section explicitly.`)
+  }
+  return candidates[0]
+}
+
+/**
+ * @param {object} field - Item field
+ * @returns {boolean} True when the field likely holds secret content
+ */
+function isSecretCandidate(field) {
+  if (field.value === undefined || field.value === '') return false
+  const label = (field.label || '').toLowerCase()
+  const purpose = (field.purpose || '').toUpperCase()
+  const type = (field.type || '').toUpperCase()
+
+  if (IGNORED_PURPOSES.has(purpose) || IGNORED_TYPES.has(type) || IGNORED_LABELS.has(label)) {
+    return false
+  }
+  if (matches(field.id, 'notesPlain') || matches(field.label, 'notesPlain') || purpose === 'NOTES') return true
+  if (purpose === 'PASSWORD') return true
+  if (type === 'CONCEALED') return true
+  if (SECRET_LABELS.has(label)) return true
+  return false
+}
+
+/**
+ * Infer the single secret-content field or throw.
+ * Never prefers notesPlain over password (or vice versa) - two candidates is an error.
+ * @param {object} item - Item for error messages
+ * @param {object[]} fields - item.fields
+ * @returns {object} Inferred field
+ */
+function inferField(item, fields) {
+  const candidates = fields.filter(isSecretCandidate)
+  if (candidates.length === 1) {
+    return candidates[0]
+  }
+  if (candidates.length > 1) {
+    const labels = candidates.map((field) => field.label || field.id).join(', ')
+    throw new Error(`1Password item "${itemName(item)}" has multiple candidate secret fields: ${labels}. Set field explicitly.`)
+  }
+  throw new Error(`1Password item "${itemName(item)}" has no obvious secret field. Set field explicitly.`)
+}
+
+module.exports = { selectField, trySelectField }

package/plugins/onepassword/index.js

@@ -0,0 +1,345 @@
+/* 1Password variable source for configorama
+   Resolves ${op:alias} and ${op(item)} references through the op CLI */
+const { readSecretRef, getItem } = require('./op-cli')
+const { validateAliasName, normalizeRefValue } = require('./normalize')
+const { selectField, trySelectField } = require('./fields')
+const { parseStructuredSecret, getKeyPath } = require('./parser')
+
+const OP_PREFIX = 'op'
+
+/**
+ * Tell interactive users why an authorization prompt is about to appear,
+ * naming what is being fetched. The 1Password dialog only names the terminal
+ * app (OS-attributed), so this line supplies the configorama context. Labels
+ * are config keys / aliases / fields — references, never secret values.
+ * TTY-only: silent in CI and pipes.
+ * @param {string[]} labels - Human labels for the values being fetched
+ * @param {string} programName - Host tool name shown as the message prefix
+ */
+function logAuthHint(labels, programName) {
+  if (!process.stderr.isTTY) return
+  const unique = [...new Set(labels)]
+  const n = unique.length
+  const what = n > 0 && n <= 8 ? unique.join(', ') : `${n} value${n === 1 ? '' : 's'}`
+  process.stderr.write(`${programName}: fetching ${what} from 1Password (expect an authorization prompt)\n`)
+}
+// Supports: op:alias, op:alias.KEY, op(item), op(item).KEY
+const opVariableSyntax = /^op(?::|\()/
+
+/**
+ * Creates a 1Password variable source resolver.
+ *
+ * Syntax:
+ *   ${op:alias}            — alias from refs, raw selected field
+ *   ${op:alias.KEY}        — alias, INI/dotenv key path into the field
+ *   ${op(spec)}            — direct item ID/name, op:// ref, or private link
+ *   ${op(spec).KEY}        — direct spec with key path
+ *
+ * Colon syntax is reserved for aliases; raw op:// refs and links must use
+ * function syntax so the parser has a reliable spec boundary.
+ *
+ * @param {object} options - Configuration options
+ * @param {object} [options.refs] - Alias map: name -> string ref, item name, private link, or { item, vault, section, field } / { ref } / { url }
+ * @param {string} [options.account] - Passed to op as --account
+ * @param {string} [options.configDir] - Passed to op as --config
+ * @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 {Function} [options.execFile] - execFile injection for tests (not serializable; unavailable in sync mode)
+ * @returns {object} Variable source configuration with resolver and metadata collector
+ */
+function createOnePasswordResolver(options = {}) {
+  const {
+    refs = {},
+    account,
+    configDir,
+    opPath,
+    programName,
+    skipResolution = false,
+    execFile,
+  } = options
+
+  const aliasRefs = {}
+  for (const alias of Object.keys(refs)) {
+    validateAliasName(alias)
+    aliasRefs[alias] = normalizeRefValue(refs[alias])
+  }
+
+  const opReferences = []
+  // Caches hold in-flight promises so concurrent references to the same
+  // item/ref share one op call. Failed promises are evicted immediately,
+  // so auth/not-found/parse failures are never cached.
+  const secretRefCache = new Map()
+  const itemCache = new Map()
+
+  const cliOptions = { account, configDir, opPath, execFile }
+  const scopeKey = `${account || ''}|${configDir || ''}`
+
+  /**
+   * @param {Map} cache - Promise cache
+   * @param {string} key - Cache key
+   * @param {Function} fn - Producer returning a promise
+   * @param {string} [label] - Human label for the auth hint
+   * @returns {Promise<*>} Shared promise
+   */
+  function cached(cache, key, fn, label) {
+    if (cache.has(key)) {
+      return cache.get(key)
+    }
+    const promise = withColdStartLatch(fn, label).catch((err) => {
+      cache.delete(key)
+      throw err
+    })
+    cache.set(key, promise)
+    return promise
+  }
+
+  // 1Password app-integration auth prompts once per op PROCESS until a
+  // session exists. Parallel resolution of N distinct items would spawn N
+  // processes at cold start and trigger N biometric prompts, so the first
+  // op call runs alone; everything else queues behind its settlement and
+  // then fans out in parallel against the authorized session.
+  let coldStartCall = null
+  let hintScheduled = false
+  const pendingLabels = []
+
+  /**
+   * @param {Function} fn - Producer returning a promise
+   * @param {string} [label] - Human label for the auth hint
+   * @returns {Promise<*>} Producer result, gated behind the first call
+   */
+  function withColdStartLatch(fn, label) {
+    if (label) pendingLabels.push(label)
+    if (!hintScheduled) {
+      hintScheduled = true
+      // setImmediate lets the whole parallel fan-out register first so the
+      // hint names every value being fetched. The prefix is read here (not at
+      // factory time) so a host tool can set CONFIGORAMA_PROGRAM_NAME after the
+      // resolver is constructed but before resolution runs.
+      setImmediate(() => {
+        const prefix = programName || process.env.CONFIGORAMA_PROGRAM_NAME || 'configorama'
+        logAuthHint(pendingLabels, prefix)
+      })
+    }
+    if (!coldStartCall) {
+      coldStartCall = fn()
+      return coldStartCall
+    }
+    return coldStartCall.catch(() => {}).then(fn)
+  }
+
+  /**
+   * Parse an op variable string into its reference and key path.
+   * @param {string} varString - e.g. "op:npm.NPM_TOKEN" or "op(item-id).KEY"
+   * @returns {{reference: object, keyPath: string|undefined, alias: string|undefined}} Parsed parts
+   */
+  function parseVariable(varString) {
+    const trimmed = varString.trim()
+
+    const funcMatch = trimmed.match(/^op\((.*)\)(?:\.(.+))?$/)
+    if (funcMatch) {
+      const spec = funcMatch[1].trim()
+      if (!spec) {
+        throw new Error(`Invalid 1Password reference "${varString}". Expected \${op(item)}, \${op(op://vault/item/field)}, or a private link.`)
+      }
+      return { reference: normalizeRefValue(spec), keyPath: funcMatch[2], alias: undefined }
+    }
+
+    // Bare 1Password secret reference: ${op://vault/item/field}. This is the
+    // native op:// URI and is treated as a direct secret ref (op read). Key
+    // paths are not supported here because op:// refs contain dots and slashes;
+    // use alias or function syntax for a structured-note key path.
+    if (trimmed.startsWith('op://')) {
+      return { reference: { kind: 'secretRef', ref: trimmed }, keyPath: undefined, alias: undefined }
+    }
+
+    if (!trimmed.startsWith('op:')) {
+      throw new Error(`Invalid 1Password variable "${varString}".`)
+    }
+    const rest = trimmed.slice(3)
+    if (rest.startsWith('op://')) {
+      throw new Error(`Use \${op(${rest})} for direct secret references.`)
+    }
+    // A private link (or any URL) after the colon is a common mistake — colon
+    // syntax is alias-only. Point to function syntax without echoing the link
+    // (it carries account/host params we treat as sensitive).
+    if (/^https?:\/\//.test(rest) || rest.startsWith('onepassword://')) {
+      throw new Error('1Password private links are not supported in colon syntax. Use function syntax: ${op(<private link>)}, or an op:// secret reference.')
+    }
+
+    const dotIndex = rest.indexOf('.')
+    const alias = dotIndex === -1 ? rest : rest.slice(0, dotIndex)
+    const keyPath = dotIndex === -1 ? undefined : rest.slice(dotIndex + 1)
+
+    validateAliasName(alias)
+    const reference = aliasRefs[alias]
+    if (!reference) {
+      throw new Error(`Unknown 1Password alias "${alias}". Configure refs.${alias}.`)
+    }
+    return { reference, keyPath, alias }
+  }
+
+  /**
+   * @param {object} params - { reference, keyPath, alias }
+   * @returns {string} Deterministic placeholder (never links or secrets)
+   */
+  function placeholderFor({ reference, keyPath, alias }) {
+    if (alias) {
+      return `[OP:alias:${alias}${keyPath ? `.${keyPath}` : ''}]`
+    }
+    if (reference.kind === 'secretRef') {
+      return `[OP:secretRef:${reference.ref}]`
+    }
+    if (reference.kind === 'privateLink') {
+      return `[OP:privateLink:${reference.item}]`
+    }
+    return `[OP:item:${reference.item}${keyPath ? `:${keyPath}` : ''}]`
+  }
+
+  /**
+   * Fetch and select the backing field value for a normalized reference.
+   * For items without a configured field, the first key path segment may
+   * select a field directly: ${op(My Login).password} picks the password
+   * field, while ${op(note-item).NPM_TOKEN} falls back to inference and
+   * treats NPM_TOKEN as an INI key inside the inferred field.
+   * @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, remainingKeyPath: string|undefined}>} Selected value
+   */
+  async function fetchValue(reference, keyPath, label) {
+    if (reference.kind === 'secretRef') {
+      const value = await cached(secretRefCache, `${scopeKey}|${reference.ref}`, () => {
+        return readSecretRef(reference.ref, cliOptions)
+      }, label)
+      return { value, fieldName: reference.ref, remainingKeyPath: keyPath }
+    }
+
+    const vault = reference.vault
+    const itemKey = `${scopeKey}|${vault || ''}|${reference.item}`
+    const item = await cached(itemCache, itemKey, () => {
+      return getItem(reference.item, { ...cliOptions, vault })
+    }, label)
+
+    // Field selection is a pure function over the cached item JSON, so it
+    // needs no cache of its own - no op call is ever saved by one.
+    if (reference.field) {
+      const field = selectField(item, { field: reference.field, section: reference.section })
+      return { value: field.value, fieldName: field.label || field.id, remainingKeyPath: keyPath }
+    }
+
+    if (keyPath !== undefined) {
+      const dotIndex = keyPath.indexOf('.')
+      const firstSegment = dotIndex === -1 ? keyPath : keyPath.slice(0, dotIndex)
+      const fieldMatch = trySelectField(item, { field: firstSegment })
+      if (fieldMatch) {
+        const remaining = dotIndex === -1 ? undefined : keyPath.slice(dotIndex + 1)
+        return { value: fieldMatch.value, fieldName: fieldMatch.label || fieldMatch.id, remainingKeyPath: remaining }
+      }
+    }
+
+    const field = selectField(item, {})
+    return { value: field.value, fieldName: field.label || field.id, remainingKeyPath: keyPath }
+  }
+
+  /**
+   * @param {string} varString - Variable body without ${}
+   * @param {object} opts - Resolver options from core (unused)
+   * @param {object} currentObject - Config object being populated (unused)
+   * @param {object} valueObject - Core value context ({ originalSource, path })
+   * @returns {Promise<string>} Resolved value or placeholder
+   */
+  async function resolver(varString, opts, currentObject, valueObject) {
+    const parsed = parseVariable(varString)
+    const { reference, keyPath, alias } = parsed
+    const configPath = valueObject && valueObject.path ? valueObject.path.join('.') : undefined
+
+    // Direct private links put the full URL (with account/host params) in
+    // the variable string itself - redact it from opReferences entries.
+    const isDirectLink = reference.kind === 'privateLink' && !alias
+    const redacted = `\${op(...)${keyPath ? `.${keyPath}` : ''}}`
+    const entry = {
+      raw: isDirectLink ? redacted : (valueObject ? valueObject.originalSource : `\${${varString}}`),
+      resolved: isDirectLink ? redacted : `\${${varString}}`,
+      alias,
+      referenceKind: reference.kind,
+      ref: reference.kind === 'secretRef' ? reference.ref : undefined,
+      item: reference.item,
+      vault: reference.vault,
+      field: reference.field,
+      section: reference.section,
+      keyPath,
+      configPath,
+      sensitive: true,
+      risk: 'remote_secret_read',
+      source: 'remote',
+      skipped: skipResolution === true,
+    }
+    if (reference.warnings && reference.warnings.length) {
+      entry.diagnostics = reference.warnings.map((warning) => ({ ...warning, configPath }))
+    }
+    opReferences.push(entry)
+
+    if (skipResolution) {
+      return placeholderFor(parsed)
+    }
+
+    // Auth-hint label: what the user recognizes — the alias, else the config
+    // key being set, else the field. Never a secret value.
+    const label = alias
+      || (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
+    }
+
+    if (remainingKeyPath === undefined) {
+      return value
+    }
+    const parsedValue = parseStructuredSecret(value, { fieldName })
+    return getKeyPath(parsedValue, remainingKeyPath, fieldName)
+  }
+
+  return {
+    type: OP_PREFIX,
+    source: 'remote',
+    prefix: OP_PREFIX,
+    syntax: '${op:alias.KEY}, ${op(item).KEY}, or ${op(op://vault/item/field)}',
+    description: 'Resolves values from 1Password through the op CLI',
+    sensitive: true,
+    risk: 'remote_secret_read',
+    match: opVariableSyntax,
+    resolver,
+    metadataKey: 'opReferences',
+    collectMetadata: () => opReferences,
+    clearCache: () => {
+      secretRefCache.clear()
+      itemCache.clear()
+      opReferences.length = 0
+      coldStartCall = null
+      hintScheduled = false
+      pendingLabels.length = 0
+    },
+    syncFactory: require.resolve('./sync-factory'),
+    syncOptions: buildSyncOptions(),
+  }
+
+  /**
+   * @returns {object} JSON-serializable options for the sync worker
+   */
+  function buildSyncOptions() {
+    const syncOptions = { refs, account, configDir, opPath, skipResolution }
+    if (execFile) {
+      // Functions cannot cross the JSON boundary into the sync worker;
+      // flag it so sync-factory can fail loudly instead of silently
+      // running the real op binary.
+      syncOptions.hasInjectedExecFile = true
+    }
+    return syncOptions
+  }
+}
+
+module.exports = createOnePasswordResolver
+module.exports.opVariableSyntax = opVariableSyntax