@dotenvx/dotenvx 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -2,7 +2,27 @@
 
 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.2.1...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.3.0...main)
+
+## [2.3.0](https://github.com/dotenvx/dotenvx/compare/v2.2.2...v2.3.0) (2026-07-08)
+
+### Added
+
+* Add `lock up` and `lock down` commands for password protecting private keys ([#875](https://github.com/dotenvx/dotenvx/pull/875))
+
+### Changed
+
+* BREAKING: Rename `keychain` commands to `native` to make way for windows and linux. ([#875](https://github.com/dotenvx/dotenvx/pull/875))
+
+### Removed
+
+* BREAKING: Remove `--no-ops`. Use `--no-armor`. ([#875](https://github.com/dotenvx/dotenvx/pull/875))
+
+## [2.2.2](https://github.com/dotenvx/dotenvx/compare/v2.2.1...v2.2.2) (2026-07-08)
+
+### Changed
+
+* Move `login` and `logout` under armor ([#874](https://github.com/dotenvx/dotenvx/pull/874))
 
 ## [2.2.1](https://github.com/dotenvx/dotenvx/compare/v2.2.0...v2.2.1) (2026-07-08)
 

package/README.md

@@ -1385,12 +1385,12 @@ $ dotenvx run --token "$DOTENVX_ARMOR_TOKEN" -- yourcommand
 ```
 
 </details>
-<details><summary>`run --no-keychain`</summary><br>
+<details><summary>`run --no-native`</summary><br>
 
-Turn off macOS Keychain lookups.
+Turn off OS secret store lookups.
 
 ```sh
-$ dotenvx run --no-keychain -- yourcommand
+$ dotenvx run --no-native -- yourcommand
 ```
 
 </details>
@@ -1415,12 +1415,12 @@ World
 ```
 
 </details>
-<details><summary>`get KEY --no-keychain`</summary><br>
+<details><summary>`get KEY --no-native`</summary><br>
 
-Turn off macOS Keychain lookups for get.
+Turn off OS secret store lookups for get.
 
 ```sh
-$ dotenvx get HELLO --no-keychain
+$ dotenvx get HELLO --no-native
 ```
 
 </details>
@@ -1739,12 +1739,12 @@ set HELLO_PLAIN (.env)
 Keys ending in `_PLAIN` are not encrypted by `dotenvx set` or `dotenvx encrypt`.
 
 </details>
-<details><summary>`set KEY value --no-keychain`</summary><br>
+<details><summary>`set KEY value --no-native`</summary><br>
 
-Turn off macOS Keychain lookups for set.
+Turn off OS secret store lookups for set.
 
 ```sh
-$ dotenvx set HELLO Dotenvx --no-keychain
+$ dotenvx set HELLO Dotenvx --no-native
 ```
 
 </details>
@@ -1779,12 +1779,12 @@ $ dotenvx encrypt -f .env.production
 ```
 
 </details>
-<details><summary>`encrypt --no-keychain`</summary><br>
+<details><summary>`encrypt --no-native`</summary><br>
 
-Turn off macOS Keychain lookups for encrypt.
+Turn off OS secret store lookups for encrypt.
 
 ```sh
-$ dotenvx encrypt --no-keychain
+$ dotenvx encrypt --no-native
 ◈ encrypted (.env)
 ```
 
@@ -1918,12 +1918,12 @@ $ dotenvx decrypt
 ```
 
 </details>
-<details><summary>`decrypt --no-keychain`</summary><br>
+<details><summary>`decrypt --no-native`</summary><br>
 
-Turn off macOS Keychain lookups for decrypt.
+Turn off OS secret store lookups for decrypt.
 
 ```sh
-$ dotenvx decrypt --no-keychain
+$ dotenvx decrypt --no-native
 ◇ decrypted (.env)
 ```
 
@@ -2039,12 +2039,12 @@ $ dotenvx keypair
 ```
 
 </details>
-<details><summary>`keypair --no-keychain`</summary><br>
+<details><summary>`keypair --no-native`</summary><br>
 
-Turn off macOS Keychain lookups for keypair.
+Turn off OS secret store lookups for keypair.
 
 ```sh
-$ dotenvx keypair --no-keychain
+$ dotenvx keypair --no-native
 {"DOTENV_PUBLIC_KEY":"<publicKey>","DOTENV_PRIVATE_KEY":"<privateKey>"}
 ```
 
@@ -2323,52 +2323,93 @@ CMD ["/usr/local/bin/dotenvx", "run", "--", "node", "apps/backend/index.js"]
 ```
 
 </details>
-<details><summary>`keychain`</summary><br>
+<details><summary>`lock`</summary><br>
 
-Store private keys in macOS Keychain to keep them out of `.env.keys`.
+Lock private keys with a local passphrase to keep them protected inside `.env.keys`.
+
+```
+# example
+DOTENV_PRIVATE_KEY=locked:02f5b97ad58b49ae324cd4e7937bc19b251d006b31cacf46f789eeaf03f923cedc:AZIPDxKqjPLiGl5b4CqVGbR3CIBDUcqHthGaoeWLoUvxbTHJkj3jGoGWGaxFSDUJGQUmWDaExRzxKpVydYF_7qiWr1ecqksOFho5t3EMwKbqX2-y-LZO9K3a4SJaYAjDJXpn3NwG4vAt1oLmGA
+```
+
+</details>
+<details><summary>`lock up`</summary><br>
+
+Lock a private key in `.env.keys` with a local passphrase.
+
+```sh
+$ dotenvx lock up
+```
+
+Here's what a locked key looks like:
+
+```ini
+# .env.keys
+DOTENV_PRIVATE_KEY=locked:02f5b97ad58b49ae324cd4e7937bc19b251d006b31cacf46f789eeaf03f923cedc:AZIPDxKqjPLiGl5b4CqVGbR3CIBDUcqHthGaoeWLoUvxbTHJkj3jGoGWGaxFSDUJGQUmWDaExRzxKpVydYF_7qiWr1ecqksOFho5t3EMwKbqX2-y-LZO9K3a4SJaYAjDJXpn3NwG4vAt1oLmGA
+```
+
+Specify files with `-f` and `-fk`.
+
+```sh
+$ dotenvx lock up -f .env.production -fk .env.keys
+```
+
+</details>
+<details><summary>`lock down`</summary><br>
+
+Unlock a private key in `.env.keys` with its local passphrase.
+
+```sh
+$ dotenvx lock down
+```
+
+</details>
+<details><summary>`native`</summary><br>
+
+Move private keys into your OS secret store (macOS Keychain supported).
 
 Currently supported on macOS.
 
 </details>
-<details><summary>`keychain up`</summary><br>
+<details><summary>`native up`</summary><br>
 
-Move a private key from `.env.keys` into macOS Keychain.
+Move a private key from `.env.keys` into your OS secret store.
 
 ```sh
-$ dotenvx keychain up
+$ dotenvx native up
 ```
 
 Specify files with `-f` and `-fk`.
 
 ```sh
-$ dotenvx keychain up -f .env.production -fk .env.keys
+$ dotenvx native up -f .env.production -fk .env.keys
 ```
 
 </details>
-<details><summary>`keychain down`</summary><br>
+<details><summary>`native down`</summary><br>
 
-Move a private key from macOS Keychain back into `.env.keys`.
+Move a private key from your OS secret store back into `.env.keys`.
 
 ```sh
-$ dotenvx keychain down
+$ dotenvx native down
 ```
 
 </details>
-<details><summary>`keychain push`</summary><br>
+<details><summary>`native push`</summary><br>
 
-Copy a private key from `.env.keys` into macOS Keychain.
+Copy a private key from `.env.keys` into your OS secret store.
 
 ```sh
-$ dotenvx keychain push
+$ dotenvx native push
 ```
 
 </details>
-<details><summary>`keychain pull`</summary><br>
+<details><summary>`native pull`</summary><br>
 
-Copy a private key from macOS Keychain into `.env.keys`.
+Copy a private key from your OS secret store into `.env.keys`.
 
 ```sh
-$ dotenvx keychain pull
+$ dotenvx native pull
 ```
 
 </details>
@@ -2382,7 +2423,7 @@ Move private keys into [Dotenvx Armor ⛨](https://dotenvx.com/armor) for off-de
 Move a private key from `.env.keys` into Dotenvx Armor.
 
 ```sh
-$ dotenvx login
+$ dotenvx armor login
 $ dotenvx armor up
 ```
 
@@ -2434,6 +2475,24 @@ Move an armored key to another team.
 $ dotenvx armor move --team acme
 ```
 
+</details>
+<details><summary>`armor login`</summary><br>
+
+Log in to Dotenvx Armor.
+
+```sh
+$ dotenvx armor login
+```
+
+</details>
+<details><summary>`armor logout`</summary><br>
+
+Log out of Dotenvx Armor.
+
+```sh
+$ dotenvx armor logout
+```
+
 </details>
 <details><summary>`help`</summary><br>
 
@@ -2470,9 +2529,9 @@ Commands:
                      prevent including .env files in docker
  
 Professional Security: 
-  login                    log in to move keys off-device, share with your team, and audit access
-  logout                   log out of connected security features
-  armor                    ⛨ move private keys off-device [www.dotenvx.com/armor]
+  lock                     ⊡ lock private keys with a local passphrase
+  native                   ⌥ move private keys into your OS secret store (macOS Keychain supported)
+  armor                    ⛨ move private keys into Dotenvx Armor [www.dotenvx.com/armor]
 ```
 
 You can get more detailed help per command with `dotenvx help COMMAND`.
@@ -2520,24 +2579,6 @@ X.X.X
 
 </details>
 
-### Utilities
-
-Additional workflow helpers.
-
-<details><summary>`ext scan`</summary><br>
-
-Scan for leaked secrets.
-
-```sh
-$ dotenvx ext scan
-100 commits scanned.
-no leaks found
-```
-
-Uses [gitleaks](https://gitleaks.io) under the hood.
-
-</details>
-
 ### Library 📦
 
 Use dotenvx directly in code.
@@ -2888,18 +2929,6 @@ This is known as *Decryption at Access* and is written about in [the whitepaper]
 
 &nbsp;
 
-## Whitepaper
-
-> **Dotenvx: Reducing Secrets Risk with Cryptographic Separation**
->
-> Abstract. An ideal secrets solution would not only centralize secrets but also contain the fallout of a breach. While secrets managers offer centralized storage and distribution, their design creates a large blast radius, risking exposure of thousands or even millions of secrets. We propose a solution that reduces the blast radius by splitting secrets management into two distinct components: an encrypted secrets file and a separate decryption key.
->
-> ...
->
-> [Read the whitepaper](https://dotenvx.com/dotenvx.pdf)
-
-&nbsp;
-
 ## Guides
 
 > Go deeper with `dotenvx` – detailed framework and platform guides.
@@ -2931,6 +2960,9 @@ This is known as *Decryption at Access* and is written about in [the whitepaper]
   * [Render](https://dotenvx.com/docs/platforms/render)
 * [CI/CDs](https://dotenvx.com/docs#cis)
   * [GitHub Actions](https://dotenvx.com/docs/cis/github-actions)
+* [Password Managers](https://dotenvx.com/docs#password-managers)
+  * [1Password](https://dotenvx.com/docs/guides/1password)
+  * [Bitwarden](https://dotenvx.com/docs/guides/bitwarden)
 * [Background Jobs](https://dotenvx.com/docs#background-jobs)
   * [Trigger.dev](https://dotenvx.com/docs/background-jobs/triggerdotdev)
 * [Package Managers](https://dotenvx.com/docs#package-managers)

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.2.1",
+  "version": "2.3.0",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -36,7 +36,7 @@
     "standard": "standard",
     "standard:fix": "standard --fix",
     "test": "tap run --test-env=DOTENVX_NO_ARMOR=true --allow-empty-coverage --disable-coverage --timeout=60000",
-    "testshell": "bash shellspec",
+    "testshell": "shellspec --shell /bin/bash",
     "release:check": "npm test && npm run testshell",
     "prerelease": "npm run release:check",
     "release": "npm run release:check && standard-version"

package/src/cli/actions/decrypt.js

@@ -4,12 +4,11 @@ const { logger } = require('./../../shared/logger')
 const catchAndLog = require('../../lib/helpers/catchAndLog')
 const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
-const normalizeArmorAliases = require('./normalizeArmorAliases')
 
 const decryptTransform = require('./../../lib/transforms/decrypt')
 
 async function decrypt () {
-  const options = normalizeArmorAliases(this.opts())
+  const options = this.opts()
   const spinner = await createSpinner({ ...options, text: 'decrypting' })
 
   logger.debug(`options: ${JSON.stringify(options)}`)
@@ -17,7 +16,7 @@ async function decrypt () {
   const envs = this.envs
   const sesh = new Session()
   const noArmor = options.armor === false || (await sesh.noArmor())
-  const noKeychain = options.keychain === false || options.noKeychain === true
+  const noKeychain = options.native === false || options.noNative === true
 
   let errorCount = 0
 

package/src/cli/actions/encrypt.js

@@ -6,10 +6,9 @@ const encryptTransform = require('./../../lib/transforms/encrypt')
 const catchAndLog = require('../../lib/helpers/catchAndLog')
 const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
-const normalizeArmorAliases = require('./normalizeArmorAliases')
 
 async function encryptAction () {
-  const options = normalizeArmorAliases(this.opts())
+  const options = this.opts()
   const spinner = await createSpinner({ ...options, text: 'encrypting' })
   const sesh = new Session()
 
@@ -21,7 +20,7 @@ async function encryptAction () {
   const fk = options.envKeysFile || '.env.keys'
   const noCreate = options.create === false
   const noArmor = options.armor === false || (!options.token && (await sesh.noArmor()))
-  const noKeychain = options.keychain === false || options.noKeychain === true
+  const noKeychain = options.native === false || options.noNative === true
 
   let errorCount = 0
 

package/src/cli/actions/get.js

@@ -6,11 +6,10 @@ const catchAndLog = require('./../../lib/helpers/catchAndLog')
 const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
 const getResolver = require('./../../lib/resolvers/get')
-const normalizeArmorAliases = require('./normalizeArmorAliases')
 const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
 
 async function get (key) {
-  const options = normalizeDotenvConfigConvention(normalizeArmorAliases(this.opts()))
+  const options = normalizeDotenvConfigConvention(this.opts())
   const spinner = await createSpinner({ ...options, text: 'decrypting' })
 
   logger.debug(`options: ${JSON.stringify(options)}`)
@@ -33,7 +32,7 @@ async function get (key) {
   try {
     const sesh = new Session()
     const noArmor = options.armor === false || (await sesh.noArmor())
-    const noKeychain = options.keychain === false || options.noKeychain === true
+    const noKeychain = options.native === false || options.noNative === true
     const { parsed, errors } = await getResolver({
       key,
       envs,

package/src/cli/actions/keychain/up.js

@@ -5,7 +5,7 @@ const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
 
 async function up () {
   const options = this.opts()
-  const spinner = await createSpinner({ ...options, text: 'keychaining' })
+  const spinner = await createSpinner({ ...options, text: 'storing' })
 
   logger.debug(`options: ${JSON.stringify(options)}`)
 
@@ -15,7 +15,7 @@ async function up () {
 
     if (spinner) spinner.stop()
     if (changed) {
-      logger.success(`⌥ keychained (${keyDisplay})`)
+      logger.success(`⌥ stored (${keyDisplay})`)
     } else {
       logger.info(`○ no change (${keyDisplay})`)
     }

package/src/cli/actions/keypair.js

@@ -3,10 +3,9 @@ const { logger } = require('./../../shared/logger')
 const keypairResolver = require('./../../lib/resolvers/keypair')
 const catchAndLog = require('./../../lib/helpers/catchAndLog')
 const createSpinner = require('../../lib/helpers/createSpinner')
-const normalizeArmorAliases = require('./normalizeArmorAliases')
 
 async function keypair (key) {
-  const options = normalizeArmorAliases(this.opts())
+  const options = this.opts()
   const spinner = await createSpinner({ ...options, text: 'retrieving' })
 
   logger.debug(`options: ${JSON.stringify(options)}`)
@@ -21,7 +20,7 @@ async function keypair (key) {
       envFile: options.envFile,
       envKeysFile: options.envKeysFile,
       armor: options.armor,
-      noKeychain: options.keychain === false || options.noKeychain === true,
+      noKeychain: options.native === false || options.noNative === true,
       token: options.token,
       command: process.argv.slice(2),
       onStatus: (text) => {

package/src/cli/actions/lock/down.js

@@ -0,0 +1,74 @@
+const crypto = require('crypto')
+
+const { logger } = require('../../../shared/logger')
+const LockDown = require('./../../../lib/services/lockDown')
+const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
+const prompts = require('../../../lib/helpers/prompts')
+
+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')
+}
+
+async function down () {
+  const options = this.opts()
+  logger.debug(`options: ${JSON.stringify(options)}`)
+
+  try {
+    const lockDown = new LockDown(options.envFile, options.envKeysFile)
+    const plan = lockDown.plan()
+    let results = plan.alreadyUnlocked
+
+    if (plan.locked.length > 0) {
+      const passphrase = await prompts.password({
+        message: 'passphrase',
+        prefix: '⊡',
+        separator: '='
+      }, {
+        input: process.stdin,
+        output: process.stderr
+      })
+
+      results = lockDown.run(lockedPrivateKey => unlockedValue(lockedPrivateKey, passphrase)).results
+    }
+
+    for (const result of results) {
+      const keyDisplay = armoredKeyDisplay(result.publicKeyValue) || result.privateKeyName
+
+      if (result.changed) {
+        logger.success(`⊡ unlocked (${keyDisplay})`)
+      } else {
+        logger.info(`○ no change (${keyDisplay})`)
+      }
+    }
+  } catch (error) {
+    if (error.code === 'PROMPT_CANCELLED') {
+      process.exit(130)
+      return
+    }
+
+    logger.error(error.message)
+    process.exit(1)
+  }
+}
+
+module.exports = down
+module.exports.unlockedValue = unlockedValue

package/src/cli/actions/lock/up.js

@@ -0,0 +1,80 @@
+const crypto = require('crypto')
+
+const { logger } = require('../../../shared/logger')
+const LockUp = require('./../../../lib/services/lockUp')
+const armoredKeyDisplay = require('../../../lib/helpers/armoredKeyDisplay')
+const prompts = require('../../../lib/helpers/prompts')
+
+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}`
+}
+
+async function up () {
+  const options = this.opts()
+  logger.debug(`options: ${JSON.stringify(options)}`)
+
+  try {
+    const lockUp = new LockUp(options.envFile, options.envKeysFile)
+
+    const plan = lockUp.plan()
+    let results = plan.alreadyLocked.map(lockedPrivateKey => ({
+      changed: false,
+      privateKeyName: lockedPrivateKey.privateKeyName,
+      privateKeyValue: undefined,
+      lockedPrivateKeyValue: lockedPrivateKey.lockedPrivateKeyValue,
+      publicKeyValue: lockedPrivateKey.publicKeyValue,
+      alreadyLocked: true
+    }))
+
+    if (plan.matches.length > 0) {
+      const passphrase = await prompts.password({
+        message: 'passphrase',
+        prefix: '⊡',
+        separator: '='
+      }, {
+        input: process.stdin,
+        output: process.stderr
+      })
+
+      results = lockUp.run((privateKey, publicKey) => lockedValue(privateKey, passphrase, publicKey)).results
+    }
+
+    for (const result of results) {
+      const keyDisplay = armoredKeyDisplay(result.publicKeyValue) || result.privateKeyName
+
+      if (result.changed) {
+        logger.success(`⊡ locked (${keyDisplay})`)
+      } else {
+        logger.info(`○ no change (${keyDisplay})`)
+      }
+    }
+  } catch (error) {
+    if (error.code === 'PROMPT_CANCELLED') {
+      process.exit(130)
+      return
+    }
+
+    logger.error(error.message)
+    process.exit(1)
+  }
+}
+
+module.exports = up
+module.exports.lockedValue = lockedValue

package/src/cli/actions/run.js

@@ -6,7 +6,6 @@ const envsResolver = require('./../../lib/resolvers/envs')
 const catchAndLog = require('./../../lib/helpers/catchAndLog')
 const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
-const normalizeArmorAliases = require('./normalizeArmorAliases')
 const normalizeDotenvConfigQuiet = require('../../lib/helpers/normalizeDotenvConfigQuiet')
 const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
 
@@ -47,7 +46,7 @@ function uniqueInjectedKeys (processedEnvs) {
 }
 
 async function run () {
-  const options = normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(normalizeArmorAliases(this.opts())))
+  const options = normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts()))
 
   let commandArgs = this.args
   if (commandArgs.length < 1) {
@@ -63,7 +62,7 @@ async function run () {
 
   const sesh = new Session()
   const noArmor = options.armor === false || (!options.token && (await sesh.noArmor()))
-  const noKeychain = options.keychain === false || options.noKeychain === true
+  const noKeychain = options.native === false || options.noNative === true
 
   if (commandArgs.length < 1) {
     if (spinner) spinner.stop()

package/src/cli/actions/set.js

@@ -8,10 +8,9 @@ const createSpinner = require('../../lib/helpers/createSpinner')
 const Errors = require('../../lib/helpers/errors')
 const prompts = require('../../lib/helpers/prompts')
 const Session = require('../../db/session')
-const normalizeArmorAliases = require('./normalizeArmorAliases')
 
 async function set (key, value) {
-  const options = normalizeArmorAliases(this.opts())
+  const options = this.opts()
 
   let encrypt = true
   let settingMessage = 'encrypting'
@@ -65,7 +64,7 @@ async function set (key, value) {
   const fk = options.envKeysFile || '.env.keys'
   const noCreate = options.create === false
   const noArmor = options.armor === false || (!options.token && (await sesh.noArmor()))
-  const noKeychain = options.keychain === false || options.noKeychain === true
+  const noKeychain = options.native === false || options.noNative === true
 
   let errorCount = 0