@dotenvx/dotenvx 2.24.0 → 2.25.0

package/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.24.0...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.25.0...main)
+
+## [2.25.0](https://github.com/dotenvx/dotenvx/compare/v2.24.1...v2.25.0) (2026-09-14)
+
+### Changed
+
+* Store private key to os secret store rather than `.env.keys` by default ([#967](https://github.com/dotenvx/dotenvx/pull/967))
+
+## [2.24.1](https://github.com/dotenvx/dotenvx/compare/v2.24.0...v2.24.1) (2026-09-11)
+
+### Changed
+
+* Upgraded to latest [@dotenvx/primitives](https://www.npmjs.com/package/@dotenvx/primitives)
 
 ## [2.24.0](https://github.com/dotenvx/dotenvx/compare/v2.23.0...v2.24.0) (2026-09-10)
 

package/README.md

@@ -872,6 +872,14 @@ $ dotenvx encrypt
 
 > A `DOTENV_PUBLIC_KEY` (encryption key) and a `DOTENV_PRIVATE_KEY` (decryption key) are generated using the same public-key cryptography as [Bitcoin](https://en.bitcoin.it/wiki/Secp256k1).
 
+New private keys created by `encrypt` and encrypted `set` default to your OS secret store: macOS Keychain, Windows Credential Manager, or Linux Secret Service. When logged into Armor, the interactive picker offers OS secret store or Armor. When Armor is off, OS storage is selected automatically. Existing `.env.keys` files are not automatically migrated.
+
+Linux requires `secret-tool` (typically the `libsecret-tools` package), a running Secret Service such as GNOME Keyring, and a user D-Bus session. When native tooling or the service is missing, dotenvx reports the fallback to `.env.keys`. Locked, denied, timed-out, or unverified storage operations fail without falling back to a plaintext key file.
+
+CI uses file storage. To explicitly use file storage elsewhere, run `dotenvx encrypt --no-native --no-armor` (or pass both flags to `set`). For deployment, continue supplying the private key through your platform's secret injection.
+
+To move an existing key into the OS store, run `dotenvx native up`. It verifies the stored key before removing it from `.env.keys`. Use `dotenvx native push` to keep a file copy, `dotenvx native pull` to export a copy, or `dotenvx native down` to move it back to `.env.keys`. Add `-f .env.production` for a particular env file. Keep a recoverable copy in your team's secret manager or backup before replacing or losing the machine.
+
 More examples
 
 <details><summary>`.env`</summary><br>

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.24.0",
+  "version": "2.25.0",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -53,7 +53,7 @@
   },
   "funding": "https://dotenvx.com",
   "dependencies": {
-    "@dotenvx/primitives": "^2.2.0",
+    "@dotenvx/primitives": "^3.0.2",
     "@dotenvx/tooling": "^1.0.3",
     "yocto-spinner": "^1.2.1"
   },

package/src/cli/actions/encrypt.js

@@ -35,7 +35,7 @@ async function encryptAction () {
         errorCount += 1
         logger.error(processedEnv.error.messageWithHelp || processedEnv.error.message)
       }
-      if (processedEnv.envSrc) {
+      if (!processedEnv.error && processedEnv.envSrc) {
         console.log(processedEnv.envSrc)
       }
     }

package/src/lib/helpers/linuxSecretService.js

@@ -1,4 +1,5 @@
 const { execFileSync } = require('child_process')
+const nativeStoreError = require('./nativeStoreError')
 
 const SECRET_TOOL_BIN = 'secret-tool'
 const SERVICE = 'dotenvx'
@@ -10,11 +11,13 @@ function attributes (publicKey) {
 function get (publicKey) {
   try {
     return execFileSync(SECRET_TOOL_BIN, ['lookup', ...attributes(publicKey)], {
+      timeout: 10000,
+      killSignal: 'SIGKILL',
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe']
     }).trim() || null
-  } catch {
-    throw new Error('failed to read private key from Linux Secret Service')
+  } catch (error) {
+    throw nativeStoreError('failed to read private key from Linux Secret Service', error, true)
   }
 }
 
@@ -22,11 +25,13 @@ function set (publicKey, privateKey, label) {
   try {
     execFileSync(SECRET_TOOL_BIN, ['store', `--label=${label}`, ...attributes(publicKey)], {
       input: privateKey,
+      timeout: 10000,
+      killSignal: 'SIGKILL',
       encoding: 'utf8',
       stdio: ['pipe', 'ignore', 'pipe']
     })
-  } catch {
-    throw new Error('failed to save private key to Linux Secret Service')
+  } catch (error) {
+    throw nativeStoreError('failed to save private key to Linux Secret Service', error, true)
   }
 }
 
@@ -36,10 +41,12 @@ module.exports = {
   delete (publicKey) {
     try {
       execFileSync(SECRET_TOOL_BIN, ['clear', ...attributes(publicKey)], {
+        timeout: 10000,
+        killSignal: 'SIGKILL',
         stdio: ['ignore', 'ignore', 'pipe']
       })
-    } catch {
-      throw new Error('failed to delete private key from Linux Secret Service')
+    } catch (error) {
+      throw nativeStoreError('failed to delete private key from Linux Secret Service', error, true)
     }
   }
 }

package/src/lib/helpers/macosKeychain.js

@@ -1,26 +1,36 @@
 const { execFileSync } = require('child_process')
+const nativeStoreError = require('./nativeStoreError')
 
 const SECURITY_BIN = '/usr/bin/security'
 const SERVICE = 'dotenvx'
 
 module.exports = {
   get (key) {
-    return execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', key, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    try {
+      return execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', key, '-w'], {
+        timeout: 10000,
+        killSignal: 'SIGKILL',
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim()
+    } catch (error) {
+      throw nativeStoreError('failed to read private key from macOS Keychain', error)
+    }
   },
 
   set (key, value, label) {
     try {
-      execFileSync(SECURITY_BIN, ['add-generic-password', '-U', '-s', SERVICE, '-a', key, '-l', label, '-w', value], { stdio: 'ignore' })
-    } catch {
-      throw new Error('failed to save private key to macOS Keychain')
+      execFileSync(SECURITY_BIN, ['add-generic-password', '-U', '-s', SERVICE, '-a', key, '-l', label, '-w', value], { timeout: 10000, killSignal: 'SIGKILL', stdio: 'ignore' })
+    } catch (error) {
+      throw nativeStoreError('failed to save private key to macOS Keychain', error)
     }
   },
 
   delete (key) {
     try {
-      execFileSync(SECURITY_BIN, ['delete-generic-password', '-s', SERVICE, '-a', key], { stdio: 'ignore' })
-    } catch {
-      throw new Error('failed to delete private key from macOS Keychain')
+      execFileSync(SECURITY_BIN, ['delete-generic-password', '-s', SERVICE, '-a', key], { timeout: 10000, killSignal: 'SIGKILL', stdio: 'ignore' })
+    } catch (error) {
+      throw nativeStoreError('failed to delete private key from macOS Keychain', error)
     }
   }
 }

package/src/lib/helpers/nativeStoreError.js

@@ -0,0 +1,10 @@
+// Never attach subprocess errors: their command/output may contain private keys.
+function nativeStoreError (message, error, linux = false) {
+  const unavailable = error.code === 'ENOENT' || (linux &&
+    /org\.freedesktop\.DBus\.Error\.(ServiceUnknown|NoServer)|Cannot autolaunch D-Bus without X11|Failed to connect to socket .*: No such file or directory/.test(String(error.stderr || '')))
+  const result = new Error(message)
+  result.code = unavailable ? 'NATIVE_UNAVAILABLE' : 'NATIVE_ACCESS_FAILED'
+  return result
+}
+
+module.exports = nativeStoreError

package/src/lib/helpers/parseWithDecryptor.js

@@ -1,4 +1,4 @@
-const { parse, parseSync } = require('@dotenvx/primitives')
+const { parse, parseSync, parsearrays } = require('@dotenvx/primitives')
 const SERVER_SIDE_DECRYPTION_REQUIRED = 'SERVER_SIDE_DECRYPTION_REQUIRED'
 
 function decryptOptions (error) {
@@ -27,21 +27,29 @@ function failedKeyAccessFallback (result, error) {
 }
 
 async function parseWithDecryptor (src, options = {}) {
+  return parseWith(src, options, parse)
+}
+
+parseWithDecryptor.arrays = async function parsearraysWithDecryptor (src, options = {}) {
+  return parseWith(src, options, parsearrays)
+}
+
+async function parseWith (src, options, parser) {
   try {
-    return await parse(src, options)
+    return await parser(src, options)
   } catch (error) {
     if (error.code !== SERVER_SIDE_DECRYPTION_REQUIRED || typeof options.decryptor !== 'function') {
       if (typeof options.provider !== 'function') throw error
 
-      const result = await parse(src, parseOptionsWithoutProvider(options))
+      const result = await parser(src, parseOptionsWithoutProvider(options))
       return failedKeyAccessFallback(result, error)
     }
 
     try {
       const result = await options.decryptor(src, decryptOptions(error))
-      return await parse(result.src, parseOptionsWithoutProvider(options))
+      return await parser(result.src, parseOptionsWithoutProvider(options))
     } catch (decryptorError) {
-      const result = await parse(src, parseOptionsWithoutProvider(options))
+      const result = await parser(src, parseOptionsWithoutProvider(options))
       return failedKeyAccessFallback(result, decryptorError)
     }
   }

package/src/lib/helpers/selectKeyStorage.js

@@ -0,0 +1,23 @@
+const prompts = require('./prompts')
+
+const secretStoreNames = {
+  darwin: 'macOS Keychain',
+  win32: 'Windows Credential Manager',
+  linux: 'Linux Secret Service'
+}
+
+async function selectKeyStorage (options = {}) {
+  const useNative = !options.noKeychain && !process.env.CI && ['darwin', 'linux', 'win32'].includes(process.platform)
+  const defaultStorage = useNative ? 'native' : 'file'
+  if (process.env.CI || options.noCreate || options.noArmor || !process.stdin.isTTY || !process.stderr.isTTY) return defaultStorage
+
+  return prompts.select({
+    message: 'Choose private key storage',
+    choices: [
+      ...(useNative ? [{ name: `□ Local Custody (${secretStoreNames[process.platform]})`, value: 'native' }] : []),
+      { name: '⛨ Managed Custody (Armor)', value: 'armored' }
+    ]
+  }, { input: process.stdin, output: process.stderr })
+}
+
+module.exports = selectKeyStorage

package/src/lib/helpers/storeNativePrivateKey.js

@@ -0,0 +1,24 @@
+const nativeProvider = require('../providers/native')
+const armoredKeyDisplay = require('./armoredKeyDisplay')
+const { logger } = require('../../shared/logger')
+
+function storeNativePrivateKey (publicKey, privateKey, keysFilepath) {
+  try {
+    nativeProvider.set(publicKey, privateKey, `dotenvx (${armoredKeyDisplay(publicKey)})`)
+  } catch (error) {
+    if (error.code !== 'NATIVE_UNAVAILABLE') throw error
+    logger.warn(`OS secret store unavailable; saving private key to ${keysFilepath}`)
+    return false
+  }
+
+  // A successful write must be readable before committing the encrypted file.
+  // Read failures must never fall back to plaintext storage.
+  if (nativeProvider.get(publicKey) !== privateKey) {
+    const error = new Error('could not verify private key in OS secret store')
+    error.code = 'NATIVE_VERIFY_FAILED'
+    throw error
+  }
+  return true
+}
+
+module.exports = storeNativePrivateKey

package/src/lib/helpers/windowsCredentialManager.js

@@ -1,4 +1,5 @@
 const { execFileSync } = require('child_process')
+const nativeStoreError = require('./nativeStoreError')
 
 const POWERSHELL_BIN = 'powershell.exe'
 const SERVICE = 'dotenvx'
@@ -128,6 +129,8 @@ function target (publicKey) {
 function run (payload) {
   return execFileSync(POWERSHELL_BIN, ['-NoProfile', '-NonInteractive', '-EncodedCommand', encodedScript], {
     input: JSON.stringify(payload),
+    timeout: 10000,
+    killSignal: 'SIGKILL',
     encoding: 'utf8',
     stdio: ['pipe', 'pipe', 'pipe'],
     windowsHide: true
@@ -137,16 +140,16 @@ function run (payload) {
 function get (publicKey) {
   try {
     return run({ action: 'read', target: target(publicKey) }).trim() || null
-  } catch {
-    throw new Error('failed to read private key from Windows Credential Manager')
+  } catch (error) {
+    throw nativeStoreError('failed to read private key from Windows Credential Manager', error)
   }
 }
 
 function set (publicKey, privateKey) {
   try {
     run({ action: 'write', target: target(publicKey), username: publicKey, secret: privateKey })
-  } catch {
-    throw new Error('failed to save private key to Windows Credential Manager')
+  } catch (error) {
+    throw nativeStoreError('failed to save private key to Windows Credential Manager', error)
   }
 }
 
@@ -156,8 +159,8 @@ module.exports = {
   delete (publicKey) {
     try {
       run({ action: 'delete', target: target(publicKey) })
-    } catch {
-      throw new Error('failed to delete private key from Windows Credential Manager')
+    } catch (error) {
+      throw nativeStoreError('failed to delete private key from Windows Credential Manager', error)
     }
   }
 }

package/src/lib/main.d.ts

@@ -306,6 +306,7 @@ export type SetProcessedEnv = {
   publicKey?: string;
   privateKey?: string;
   localPrivateKeyAdded?: boolean;
+  nativePrivateKeyAdded?: boolean;
   remotePrivateKeyAdded?: boolean;
   privateKeyName?: string;
   error?: Error;

package/src/lib/services/keychainUp.js

@@ -54,6 +54,9 @@ class KeychainUp {
     }
 
     nativeProvider.set(publicKey, privateKey, label)
+    if (nativeProvider.get(publicKey) !== privateKey) {
+      throw new Error('could not verify private key in OS secret store; .env.keys unchanged')
+    }
     removeEnvKey(privateKeyName, envKeysFile)
 
     return {

package/src/lib/transforms/decrypt.js

@@ -44,7 +44,7 @@ async function decrypt (options = {}) {
       const encoding = await detectEncoding(filepath)
       row.envSrc = await fsx.readFileX(filepath, { encoding })
 
-      const { parsed, errors } = await parseWithDecryptor(row.envSrc, { fk, ik, ek, array: true, provider, decryptor })
+      const { parsed, errors } = await parseWithDecryptor.arrays(row.envSrc, { fk, ik, ek, provider, decryptor })
 
       if (errors.length > 0) {
         row.error = parseError(errors[0])

package/src/lib/transforms/encrypt.js

@@ -16,27 +16,15 @@ const teamChoicesFromMeta = require('../helpers/teamChoicesFromMeta')
 const isTeamRequiredError = require('../helpers/isTeamRequiredError')
 const Session = require('../../db/session')
 
-async function selectKeyStorage () {
-  const selected = await prompts.select({
-    message: 'Choose private key storage',
-    choices: [
-      { name: '◫ File (.env.keys)', value: 'file' },
-      { name: '⛨ Armor (armor.dotenvx.com)', value: 'armored' }
-    ]
-  }, {
-    input: process.stdin,
-    output: process.stderr
-  })
-
-  return selected
-}
+const selectKeyStorage = require('../helpers/selectKeyStorage')
+const storeNativePrivateKey = require('../helpers/storeNativePrivateKey')
 
 async function encryptTransform (options = {}) {
   const envs = options.envs || []
   const ik = options.ik
   const ek = options.ek
   const fk = options.fk || '.env.keys'
-  let noArmor = options.noArmor // key storage selector below
+  let storage
   const noCreate = options.noCreate
 
   const processedEnvs = []
@@ -85,9 +73,7 @@ async function encryptTransform (options = {}) {
       let publicKey = publickeys(row.envSrc)[0]
 
       if (!publicKey) {
-        if (!noCreate && !noArmor && selectKeyStorage) {
-          noArmor = await selectKeyStorage() !== 'armored'
-        }
+        storage = storage || await selectKeyStorage(options)
 
         // upsert public key to .env file
         const kp = keypair() // local
@@ -99,7 +85,9 @@ async function encryptTransform (options = {}) {
 
         const comment = path.basename(envFilepath)
 
-        if (noArmor) {
+        if (storage === 'native' && storeNativePrivateKey(publicKey, privateKey, fk)) {
+          row.nativePrivateKeyAdded = true
+        } else if (storage !== 'armored') {
           const mutated = mutateKeysSrc({ keysSrc, privateKeyName, privateKeyValue: privateKey, comment })
           keysSrc = mutated.keysSrc
         } else {

package/src/lib/transforms/set.js

@@ -16,27 +16,16 @@ const teamChoicesFromMeta = require('../helpers/teamChoicesFromMeta')
 const isTeamRequiredError = require('../helpers/isTeamRequiredError')
 const Session = require('../../db/session')
 
-async function selectKeyStorage () {
-  const selected = await prompts.select({
-    message: 'Choose private key storage',
-    choices: [
-      { name: '◫ File (.env.keys)', value: 'file' },
-      { name: '⛨ Armor (armor.dotenvx.com)', value: 'armored' }
-    ]
-  }, {
-    input: process.stdin,
-    output: process.stderr
-  })
-
-  return selected
-}
+const selectKeyStorage = require('../helpers/selectKeyStorage')
+const storeNativePrivateKey = require('../helpers/storeNativePrivateKey')
 
 async function setTransform (options = {}) {
   const envs = options.envs || []
   const key = options.key
   const value = options.value
   const fk = options.fk || '.env.keys'
-  let noArmor = options.noArmor // key storage selector below
+  const noArmor = options.noArmor
+  let storage
   const noKeychain = options.noKeychain
   const noCreate = options.noCreate
   const noEncrypt = !options.encrypt || isPlainKey(key)
@@ -88,9 +77,7 @@ async function setTransform (options = {}) {
 
       // only create if missing public key and encryption needed
       if (!publicKey && !noEncrypt) {
-        if (!noCreate && !noArmor && selectKeyStorage) {
-          noArmor = await selectKeyStorage() !== 'armored'
-        }
+        storage = storage || await selectKeyStorage(options)
 
         // upsert public key to .env file
         const kp = keypair() // local
@@ -102,7 +89,9 @@ async function setTransform (options = {}) {
 
         const comment = path.basename(envFilepath)
 
-        if (noArmor) {
+        if (storage === 'native' && storeNativePrivateKey(publicKey, privateKey, fk)) {
+          row.nativePrivateKeyAdded = true
+        } else if (storage !== 'armored') {
           const mutated = mutateKeysSrc({ keysSrc, privateKeyName, privateKeyValue: privateKey, comment })
           keysSrc = mutated.keysSrc
         } else {