@dotenvx/dotenvx 2.28.0 → 2.28.1

package/src/lib/custodians/local/file.js

@@ -0,0 +1,18 @@
+const { mutateKeysSrc } = require('../../helpers/cryptography')
+
+// File keys are loaded by envResolution before provider lookup. Creation is
+// staged here so the caller can commit .env.keys with the encrypted env files.
+module.exports = {
+  id: 'file',
+  name: 'File (.env.keys)',
+  enabled: () => true,
+  available: () => true,
+  store (publicKey, privateKey, context) {
+    return mutateKeysSrc({
+      keysSrc: context.keysSrc,
+      privateKeyName: context.privateKeyName,
+      privateKeyValue: privateKey,
+      comment: context.comment
+    })
+  }
+}

package/src/lib/custodians/local/native/backend.js

@@ -0,0 +1,62 @@
+const macosKeychain = require('../../../helpers/macosKeychain')
+const windowsCredentialManager = require('../../../helpers/windowsCredentialManager')
+const linuxSecretService = require('../../../helpers/linuxSecretService')
+
+function get (key) {
+  if (process.platform === 'win32') {
+    return windowsCredentialManager.get(key)
+  }
+
+  if (process.platform === 'linux') {
+    return linuxSecretService.get(key)
+  }
+
+  return macosKeychain.get(key)
+}
+
+function set (key, value, label = key) {
+  if (process.platform === 'win32') {
+    windowsCredentialManager.set(key, value, label)
+    return
+  }
+
+  if (process.platform === 'linux') {
+    linuxSecretService.set(key, value, label)
+    return
+  }
+
+  macosKeychain.set(key, value, label)
+}
+
+index.delete = function (key) {
+  if (process.platform === 'win32') {
+    windowsCredentialManager.delete(key)
+    return
+  }
+
+  if (process.platform === 'linux') {
+    linuxSecretService.delete(key)
+    return
+  }
+
+  macosKeychain.delete(key)
+}
+
+function index (publicKeyHex) {
+  if (!['darwin', 'linux', 'win32'].includes(process.platform)) return {}
+
+  try {
+    const privateKeyHex = get(publicKeyHex)
+
+    if (!privateKeyHex) return {}
+
+    return { [publicKeyHex]: privateKeyHex }
+  } catch {
+    return {}
+  }
+}
+
+index.set = set
+index.get = get
+
+module.exports = index

package/src/lib/custodians/local/native/index.js

@@ -0,0 +1,28 @@
+const backend = require('./backend')
+const storePrivateKey = require('./store')
+
+const names = {
+  darwin: 'macOS Keychain',
+  win32: 'Windows Credential Manager',
+  linux: 'Linux Secret Service'
+}
+
+function enabled (options = {}) {
+  return !!names[process.platform] && !process.env.CI && options.noNative !== true && options.native !== false && process.env.DOTENVX_NO_NATIVE !== 'true'
+}
+
+module.exports = {
+  id: 'native',
+  get name () { return `OS${names[process.platform] ? ` (${names[process.platform]})` : ''}` },
+  enabled,
+  available: () => true,
+  configured: () => true,
+  get: backend,
+  getSync: backend,
+  set: backend.set,
+  delete: backend.delete,
+  store (publicKey, privateKey, context) {
+    if (!storePrivateKey(publicKey, privateKey, context.keysFilepath)) return { fallback: 'file' }
+    return { nativePrivateKeyAdded: true }
+  }
+}

package/src/lib/{helpers/storeNativePrivateKey.js → custodians/local/native/store.js}

@@ -1,6 +1,6 @@
-const nativeProvider = require('../providers/native')
-const armoredKeyDisplay = require('./armoredKeyDisplay')
-const { logger } = require('../../shared/logger')
+const nativeProvider = require('./backend')
+const armoredKeyDisplay = require('../../../helpers/armoredKeyDisplay')
+const { logger } = require('../../../../shared/logger')
 
 function storeNativePrivateKey (publicKey, privateKey, keysFilepath) {
   try {

package/src/lib/{helpers/onePasswordCustody.js → custodians/local/onepassword.js}

@@ -1,7 +1,7 @@
 const { execFile, execFileSync } = require('child_process')
-const { derive } = require('@dotenvx/primitives')
-const Session = require('../../db/session')
-const armoredKeyDisplay = require('./armoredKeyDisplay')
+const matchesStoredKey = require('../../helpers/matchesStoredKey')
+const Session = require('../../../db/session')
+const armoredKeyDisplay = require('../../helpers/armoredKeyDisplay')
 
 const PREFIX = 'DOTENVX_ONEPASSWORD_'
 const ID = /^[a-z0-9]{26}$/i
@@ -98,7 +98,7 @@ function location (publicKey) {
 
 function verified (publicKey, privateKey) {
   try {
-    if (derive(privateKey) === publicKey) return { [publicKey]: privateKey }
+    if (matchesStoredKey(publicKey, privateKey)) return { [publicKey]: privateKey }
   } catch {}
   throw failure('1Password private key does not match the .env public key')
 }
@@ -164,4 +164,8 @@ async function remove (publicKey) {
   new Session().openStore().delete(`${PREFIX}${publicKey}`)
 }
 
-module.exports = { available, configured, get, getSync, set, delete: remove }
+function enabled (options = {}) {
+  return options.no1Password !== true && process.env.DOTENVX_NO_1PASSWORD !== 'true'
+}
+
+module.exports = { id: 'onepassword', name: '1Password', enabled, store: set, available, configured, get, getSync, set, delete: remove }

package/src/lib/custodians/lock.js

@@ -0,0 +1,80 @@
+const { derive } = require('@dotenvx/primitives')
+const lockedValue = require('../helpers/lockedValue')
+const unlockedValue = require('../helpers/unlockedValue')
+const prompts = require('../helpers/prompts')
+const createSpinner = require('../helpers/createSpinner')
+const matchesKey = require('../helpers/matchesStoredKey')
+const Errors = require('../helpers/errors')
+const resolveLockPassword = require('../helpers/resolveLockPassword')
+
+// Context is shared only within a transform; never cache passphrases globally
+// by filename or return them alongside the staged keys.
+const passphrases = new WeakMap()
+
+async function promptPassphrase () {
+  createSpinner.pause()
+  try {
+    const passphrase = await prompts.password({ message: 'passphrase', prefix: '⊡', separator: '=' }, {
+      input: process.stdin,
+      output: process.stderr
+    })
+    if (!passphrase) throw new Error('passphrase must not be empty')
+    return passphrase
+  } finally {
+    createSpinner.resume()
+  }
+}
+
+async function lock (publicKey, privateKey, context) {
+  if (derive(privateKey) !== publicKey) throw new Error('private key does not match the .env public key')
+  if (!passphrases.has(context)) {
+    const password = resolveLockPassword(context)
+    if (password === '') throw new Error('passphrase must not be empty')
+    passphrases.set(context, password !== undefined ? password : promptPassphrase())
+  }
+  return lockedValue(privateKey, await passphrases.get(context), publicKey)
+}
+
+function isLocked (value) {
+  return typeof value === 'string' && value.startsWith('locked:')
+}
+
+function unlockValue (publicKey, ring, passphrase) {
+  try {
+    const privateKey = unlockedValue(ring[publicKey], passphrase)
+    if (derive(privateKey) !== publicKey) throw new Error('key mismatch')
+    return { ...ring, [publicKey]: privateKey }
+  } catch {
+    throw new Errors().invalidPassphrase()
+  }
+}
+
+function validateLocked (publicKey, ring) {
+  const value = ring && ring[publicKey]
+  if (!isLocked(value)) return false
+  if (!matchesKey(publicKey, value)) throw new Error('invalid locked private key')
+  return true
+}
+
+function passwordRequired () {
+  const error = new Error('[LOCKED_PRIVATE_KEY] supply --lock-password, lockPassword, or DOTENVX_LOCK_PASSWORD to unlock the private key')
+  error.code = 'LOCKED_PRIVATE_KEY'
+  return error
+}
+
+async function unlock (publicKey, ring, options = {}) {
+  if (!validateLocked(publicKey, ring)) return ring
+  const password = resolveLockPassword(options)
+  if (password !== undefined) return unlockValue(publicKey, ring, password)
+  if (!process.stdin.isTTY || !process.stderr.isTTY || process.env.CI) throw passwordRequired()
+  return unlockValue(publicKey, ring, await promptPassphrase())
+}
+
+function unlockSync (publicKey, ring, options = {}) {
+  if (!validateLocked(publicKey, ring)) return ring
+  const password = resolveLockPassword(options)
+  if (password === undefined) throw passwordRequired()
+  return unlockValue(publicKey, ring, password)
+}
+
+module.exports = { lock, unlock, unlockSync }

package/src/lib/{providers/armor/index.js → custodians/managed/armor/get.js}

@@ -1,9 +1,9 @@
-const Session = require('../../../db/session')
-const ArmorKeyring = require('../../services/armorKeyring')
-const armoredKeyDisplay = require('../../helpers/armoredKeyDisplay')
-const isNetworkError = require('../../helpers/isNetworkError')
-const listenForOpenKey = require('../../helpers/listenForOpenKey')
-const openUrl = require('../../helpers/openUrl')
+const Session = require('../../../../db/session')
+const ArmorKeyring = require('../../../services/armorKeyring')
+const armoredKeyDisplay = require('../../../helpers/armoredKeyDisplay')
+const isNetworkError = require('../../../helpers/isNetworkError')
+const listenForOpenKey = require('../../../helpers/listenForOpenKey')
+const openUrl = require('../../../helpers/openUrl')
 
 async function index (publicKeyHex, options = {}) {
   const sesh = new Session()

package/src/lib/custodians/managed/armor/index.js

@@ -0,0 +1,24 @@
+const Session = require('../../../../db/session')
+const get = require('./get')
+const store = require('./store')
+
+module.exports = {
+  id: 'armored',
+  name: '⛨ Armor',
+  custody: 'managed',
+  enabled: (options = {}) => options.noArmor !== true && options.armor !== false,
+  available: () => true,
+  async configured (options = {}) {
+    return !!options.token || !await new Session().noArmor()
+  },
+  configuredSync (options = {}) {
+    return !!options.token || !new Session().noArmorSync()
+  },
+  get,
+  getSync (publicKey) {
+    const { createSyncFn } = require('@dotenvx/tooling')
+    const runProviderSync = createSyncFn(require.resolve('../../../providers/provider-worker.js'))
+    return runProviderSync(publicKey)
+  },
+  store
+}

package/src/lib/custodians/managed/armor/store.js

@@ -0,0 +1,37 @@
+const Session = require('../../../../db/session')
+const PostArmorUp = require('../../../api/postArmorUp')
+const prompts = require('../../../helpers/prompts')
+const teamChoicesFromMeta = require('../../../helpers/teamChoicesFromMeta')
+const isTeamRequiredError = require('../../../helpers/isTeamRequiredError')
+
+async function store (publicKey, privateKey) {
+  const sesh = new Session()
+  const hostname = sesh.hostname()
+  const token = sesh.token()
+  const devicePublicKey = sesh.devicePublicKey()
+
+  try {
+    await new PostArmorUp(hostname, token, devicePublicKey, publicKey, privateKey, undefined).run()
+  } catch (error) {
+    if (!isTeamRequiredError(error)) {
+      throw error
+    }
+
+    const choices = teamChoicesFromMeta(error.meta)
+
+    let team = choices[0].value
+    if (choices.length > 1) {
+      team = await prompts.select({
+        message: 'Select team',
+        choices
+      }, {
+        input: process.stdin,
+        output: process.stderr
+      })
+    }
+
+    await new PostArmorUp(hostname, token, devicePublicKey, publicKey, privateKey, team).run()
+  }
+}
+
+module.exports = store

package/src/lib/helpers/installPrecommitFilter.js

@@ -0,0 +1,50 @@
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { execFileSync } = require('child_process')
+
+const ATTRIBUTE = '.env* filter=dotenvx'
+
+function quote (value) {
+  return "'" + value.replace(/'/g, "'\\''") + "'"
+}
+
+function installPrecommitFilter (global = false) {
+  const git = (...args) => execFileSync('git', args, { encoding: 'utf8' }).trim()
+  let attributesPath
+  if (global) {
+    try {
+      attributesPath = git('config', '--global', '--includes', '--path', '--get', 'core.attributesFile')
+    } catch (error) {
+      if (error.status !== 1) throw error
+    }
+    if (!attributesPath) {
+      attributesPath = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'git/attributes')
+      git('config', '--global', 'core.attributesFile', attributesPath)
+    }
+  } else {
+    attributesPath = git('rev-parse', '--git-path', 'info/attributes')
+  }
+  const hookPath = global ? null : git('rev-parse', '--git-path', 'hooks/pre-commit')
+  const current = fs.existsSync(attributesPath) ? fs.readFileSync(attributesPath, 'utf8') : ''
+  // Use the installed executable, including standalone builds. Never download a
+  // replacement via npx while Git is handling secret input.
+  const executable = process.pkg
+    ? quote(process.execPath)
+    : `${quote(process.execPath)} ${quote(path.resolve(__dirname, '../../cli/dotenvx.js'))}`
+
+  const scope = global ? '--global' : '--local'
+  // Git's filter_buffer_or_fd shell-quotes the filename with sq_quote_buf
+  // before substituting %f (convert.c). Keep the placeholder unquoted here.
+  git('config', scope, 'filter.dotenvx.clean', `${executable} precommit --clean %f`)
+  git('config', scope, 'filter.dotenvx.required', 'true')
+  fs.mkdirSync(path.dirname(attributesPath), { recursive: true })
+  if (!current.split(/\r?\n/).includes(ATTRIBUTE)) {
+    fs.appendFileSync(attributesPath, `${current && !current.endsWith('\n') ? '\n' : ''}${ATTRIBUTE}\n`)
+  }
+  if (global) return attributesPath
+  fs.mkdirSync(path.dirname(hookPath), { recursive: true })
+  return hookPath
+}
+
+module.exports = installPrecommitFilter

package/src/lib/helpers/installPrecommitHook.js

@@ -25,8 +25,8 @@ fi
 `
 
 class InstallPrecommitHook {
-  constructor () {
-    this.hookPath = path.join('.git', 'hooks', 'pre-commit')
+  constructor (hookPath = path.join('.git', 'hooks', 'pre-commit')) {
+    this.hookPath = hookPath
   }
 
   run () {

package/src/lib/helpers/lockedValue.js

@@ -0,0 +1,24 @@
+const crypto = require('crypto')
+
+function lockedValue (privateKey, passphrase, publicKey) {
+  const salt = crypto.randomBytes(16)
+  const iv = crypto.randomBytes(12)
+  const key = crypto.scryptSync(passphrase, salt, 32)
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv)
+  const ciphertext = Buffer.concat([
+    cipher.update(privateKey, 'utf8'),
+    cipher.final()
+  ])
+  const tag = cipher.getAuthTag()
+  const payload = Buffer.concat([
+    Buffer.from([1]),
+    salt,
+    iv,
+    tag,
+    ciphertext
+  ]).toString('base64url')
+
+  return `locked:${publicKey}:${payload}`
+}
+
+module.exports = lockedValue

package/src/lib/helpers/macosKeychain.js

@@ -1,9 +1,14 @@
-const { execFileSync } = require('child_process')
+const { execFileSync, spawnSync } = require('child_process')
 const nativeStoreError = require('./nativeStoreError')
 
 const SECURITY_BIN = '/usr/bin/security'
 const SERVICE = 'dotenvx'
 
+function quoteArgument (value) {
+  if (typeof value !== 'string' || /[\r\n\0]/.test(value)) throw new Error('invalid Keychain argument')
+  return '"' + value.replace(/[\\"]/g, '\\$&') + '"'
+}
+
 module.exports = {
   get (key) {
     try {
@@ -20,7 +25,18 @@ module.exports = {
 
   set (key, value, label) {
     try {
-      execFileSync(SECURITY_BIN, ['add-generic-password', '-U', '-s', SERVICE, '-a', key, '-l', label, '-w', value], { timeout: 10000, killSignal: 'SIGKILL', stdio: 'ignore' })
+      const input = ['add-generic-password', '-U', '-s', SERVICE, '-a', key, '-l', label, '-w', value].map(quoteArgument).join(' ') + '\n'
+      // security's 4096-byte line buffer must also consume the newline and NUL.
+      if (Buffer.byteLength(input, 'utf8') >= 4096) throw new Error('Keychain command too long')
+      // Interactive security can exit zero on failure, so inspect stderr too.
+      const result = spawnSync(SECURITY_BIN, ['-i'], {
+        input,
+        timeout: 10000,
+        killSignal: 'SIGKILL',
+        stdio: ['pipe', 'ignore', 'pipe']
+      })
+      if (result.error) throw result.error
+      if (result.status !== 0 || result.signal || result.stderr.length > 0) throw new Error('Keychain write failed')
     } catch (error) {
       throw nativeStoreError('failed to save private key to macOS Keychain', error)
     }

package/src/lib/helpers/matchesStoredKey.js

@@ -0,0 +1,16 @@
+const { derive } = require('@dotenvx/primitives')
+
+// Locked values can be transported without unlocking. Validate the envelope
+// here; authenticate and derive the actual key when unlocking for use.
+function matchesStoredKey (publicKey, value) {
+  if (typeof value !== 'string') return false
+  if (value.startsWith('locked:')) {
+    const parts = value.split(':')
+    if (parts.length !== 3 || parts[1] !== publicKey || !/^(02|03)[a-f0-9]{64}$/i.test(publicKey)) return false
+    const payload = Buffer.from(parts[2], 'base64url')
+    return payload.length === 109 && payload[0] === 1 && payload.toString('base64url') === parts[2]
+  }
+  try { return derive(value) === publicKey } catch { return false }
+}
+
+module.exports = matchesStoredKey

package/src/lib/helpers/normalizeDotenvConfigPath.js

@@ -3,7 +3,7 @@ const TYPE_ENV_FILE = 'envFile'
 function normalizeDotenvConfigPath (envs = [], processEnv = process.env) {
   if (envs.some(env => env.type === TYPE_ENV_FILE)) return envs
 
-  const configuredEnvFiles = processEnv.DOTENV_PATH || processEnv.DOTENV_F
+  const configuredEnvFiles = processEnv.DOTENV_FILE || processEnv.DOTENV_PATH || processEnv.DOTENV_F
   if (!configuredEnvFiles) return envs
 
   const envFiles = configuredEnvFiles.split(',').map(value => value.trim()).filter(Boolean)

package/src/lib/helpers/parseWithDecryptor.js

@@ -1,5 +1,6 @@
 const { parse, parseSync, parsearrays, scan, encrypted } = require('@dotenvx/primitives')
 const prepareProxy = require('../proxy/prepareProxy')
+const withLockedKeys = require('./withLockedKeys')
 const SERVER_SIDE_DECRYPTION_REQUIRED = 'SERVER_SIDE_DECRYPTION_REQUIRED'
 
 function decryptOptions (error) {
@@ -43,6 +44,7 @@ parseWithDecryptor.arrays = async function parsearraysWithDecryptor (src, option
 }
 
 async function parseWith (src, options, parser) {
+  options = withLockedKeys(options)
   try {
     return await parser(src, options)
   } catch (error) {
@@ -64,6 +66,7 @@ async function parseWith (src, options, parser) {
 }
 
 parseWithDecryptor.sync = function parseWithDecryptorSync (src, options = {}) {
+  options = withLockedKeys(options, true)
   try {
     return parseSync(src, options)
   } catch (error) {

package/src/lib/helpers/prompts.js

@@ -51,6 +51,23 @@ async function select ({ message, choices }, context) {
   return answer.value
 }
 
+async function confirm ({ message, initial = false }, context) {
+  try {
+    const answer = await enquirer.prompt({
+      type: 'confirm',
+      name: 'value',
+      message,
+      initial,
+      ...enquirerOptions(context)
+    })
+    return answer.value === true
+  } catch {
+    const error = new Error('prompt cancelled')
+    error.code = 'PROMPT_CANCELLED'
+    throw error
+  }
+}
+
 async function password ({ message, prefix, separator }, context) {
   const output = (context && context.output) || process.stderr
 
@@ -85,6 +102,7 @@ async function password ({ message, prefix, separator }, context) {
 }
 
 module.exports = {
+  confirm,
   password,
   select
 }

package/src/lib/helpers/resolveLockPassword.js

@@ -0,0 +1,5 @@
+function resolveLockPassword (options = {}) {
+  return options.lockPassword !== undefined ? options.lockPassword : process.env.DOTENVX_LOCK_PASSWORD
+}
+
+module.exports = resolveLockPassword

package/src/lib/helpers/selectKeyStorage.js

@@ -1,29 +1,15 @@
 const prompts = require('./prompts')
-const onePasswordCustody = require('./onePasswordCustody')
-const bitwardenCustody = require('./bitwardenCustody')
-
-const secretStoreNames = {
-  darwin: 'macOS Keychain',
-  win32: 'Windows Credential Manager',
-  linux: 'Linux Secret Service'
-}
+const custodians = require('../custodians')
 
 async function selectKeyStorage (options = {}) {
-  const useNative = !options.noNative && process.env.DOTENVX_NO_NATIVE !== 'true' && !process.env.CI && ['darwin', 'linux', 'win32'].includes(process.platform)
-  const defaultStorage = useNative ? 'native' : 'file'
+  const defaultStorage = custodians.get('native').enabled(options) ? 'native' : 'file'
   if (process.env.CI || options.noCreate || !process.stdin.isTTY || !process.stderr.isTTY) return defaultStorage
 
-  const use1Password = !options.no1Password && process.env.DOTENVX_NO_1PASSWORD !== 'true' && await onePasswordCustody.available()
-  const useBitwarden = !options.noBitwarden && process.env.DOTENVX_NO_BITWARDEN !== 'true' && await bitwardenCustody.available()
-  const localChoices = [
-    { name: `OS${secretStoreNames[process.platform] ? ` (${secretStoreNames[process.platform]})` : ''}`, value: 'native', disabled: !useNative },
-    { name: '1Password', value: 'onepassword', disabled: !use1Password },
-    { name: 'Bitwarden', value: 'bitwarden', disabled: !useBitwarden },
-    { name: 'File (.env.keys)', value: 'file', disabled: false }
-  ]
+  const localChoices = await custodians.choices(options)
 
   const choices = [{ name: '⛉ Local Custody', value: 'local', disabled: false }]
-  if (!options.noArmor) choices.push({ name: '⛊ Managed Custody', value: 'managed' })
+  const managedChoices = (await custodians.choices(options, 'managed')).filter(choice => !choice.disabled).map(({ name, value }) => ({ name, value }))
+  if (managedChoices.length) choices.push({ name: '⛊ Managed Custody', value: 'managed' })
 
   const context = { input: process.stdin, output: process.stderr }
   const custody = await prompts.select({
@@ -31,10 +17,12 @@ async function selectKeyStorage (options = {}) {
     choices
   }, context)
 
-  return prompts.select({
+  const storage = await prompts.select({
     message: custody === 'local' ? 'Choose local custody' : 'Choose managed custody',
-    choices: custody === 'local' ? localChoices : [{ name: '⛨ Armor', value: 'armored' }]
+    choices: custody === 'local' ? localChoices : managedChoices
   }, context)
+
+  return storage
 }
 
 module.exports = selectKeyStorage

package/src/lib/helpers/unlockedValue.js

@@ -0,0 +1,26 @@
+const crypto = require('crypto')
+
+function unlockedValue (lockedPrivateKey, passphrase) {
+  const parts = lockedPrivateKey.split(':')
+  const payload = Buffer.from(parts.slice(2).join(':'), 'base64url')
+  const version = payload.subarray(0, 1)[0]
+  const salt = payload.subarray(1, 17)
+  const iv = payload.subarray(17, 29)
+  const tag = payload.subarray(29, 45)
+  const ciphertext = payload.subarray(45)
+  const key = crypto.scryptSync(passphrase, salt, 32)
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv)
+
+  if (version !== 1) {
+    throw new Error('unsupported locked private key version')
+  }
+
+  decipher.setAuthTag(tag)
+
+  return Buffer.concat([
+    decipher.update(ciphertext),
+    decipher.final()
+  ]).toString('utf8')
+}
+
+module.exports = unlockedValue

package/src/lib/helpers/withLockedKeys.js

@@ -0,0 +1,41 @@
+const fs = require('fs')
+const { scan } = require('@dotenvx/primitives')
+const protection = require('../custodians/lock')
+
+// Primitives already resolve raw file/environment keys first. This provider
+// supplies locked keys only when the requested private key is still missing.
+function withLockedKeys (options, sync = false) {
+  const candidates = []
+  const paths = Array.isArray(options.fk) ? options.fk : [options.fk || '.env.keys']
+  for (const filepath of paths) {
+    let src
+    try { src = fs.readFileSync(filepath, 'utf8') } catch { continue }
+    for (const [name, values] of Object.entries(scan(src).parsed)) {
+      if (name.startsWith('DOTENV_PRIVATE_KEY')) candidates.push(...values.flatMap(value => value.split(',')))
+    }
+  }
+  // Environment assignments take precedence over key files.
+  for (const [name, value] of Object.entries(options.processEnv || process.env)) {
+    if (name.startsWith('DOTENV_PRIVATE_KEY') && typeof value === 'string') candidates.push(...value.split(','))
+  }
+  if (!candidates.some(value => value.startsWith('locked:'))) return options
+  candidates.reverse()
+  function find (publicKey) {
+    return candidates.find(value => value.startsWith(`locked:${publicKey}:`))
+  }
+  const provider = options.provider
+  return {
+    ...options,
+    provider: sync
+      ? publicKey => {
+        const value = find(publicKey)
+        return value ? protection.unlockSync(publicKey, { [publicKey]: value }, options) : (provider ? provider(publicKey) : {})
+      }
+      : async publicKey => {
+        const value = find(publicKey)
+        return value ? protection.unlock(publicKey, { [publicKey]: value }, options) : (provider ? provider(publicKey) : {})
+      }
+  }
+}
+
+module.exports = withLockedKeys