@dotenvx/dotenvx 2.1.5 → 2.2.1

package/src/cli/actions/run.js

@@ -63,6 +63,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
 
   if (commandArgs.length < 1) {
     if (spinner) spinner.stop()
@@ -98,6 +99,7 @@ async function run () {
       processEnv: process.env,
       envKeysFile: options.envKeysFile,
       noArmor,
+      noKeychain,
       token: options.token,
       command: commandArgs,
       onStatus: (text) => {

package/src/cli/actions/set.js

@@ -65,11 +65,12 @@ 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
 
   let errorCount = 0
 
   try {
-    const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await setTransform({ envs, key, value, fk, noArmor, noCreate, encrypt })
+    const { keysSrc, processedEnvs, changedFilepaths, unchangedFilepaths } = await setTransform({ envs, key, value, fk, noArmor, noCreate, encrypt, noKeychain })
 
     if (keysSrc) {
       await fsx.writeFileX(fk, keysSrc)

package/src/cli/commands/keychain.js

@@ -0,0 +1,43 @@
+function configureKeychainCommand (keychain) {
+  keychain
+    .description('store private keys in macOS Keychain')
+    .action(function () {
+      this.help()
+    })
+
+  const upAction = require('./../actions/keychain/up')
+  keychain
+    .command('up')
+    .description('store key in macOS Keychain')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(upAction)
+
+  const downAction = require('./../actions/keychain/down')
+  keychain
+    .command('down')
+    .description('move key from macOS Keychain to .env.keys')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(downAction)
+
+  const pushAction = require('./../actions/keychain/push')
+  keychain
+    .command('push')
+    .description('push key to macOS Keychain from .env.keys')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(pushAction)
+
+  const pullAction = require('./../actions/keychain/pull')
+  keychain
+    .command('pull')
+    .description('pull key from macOS Keychain into .env.keys')
+    .option('-f, --env-file <path>', 'path to your env file')
+    .option('-fk, --env-keys-file <path>', 'path to your .env.keys file', '.env.keys')
+    .action(pullAction)
+
+  return keychain
+}
+
+module.exports = configureKeychainCommand

package/src/cli/dotenvx.js

@@ -72,7 +72,8 @@ program.command('run')
   .option('--convention <name>', 'load a .env convention (available conventions: [\'nextjs\', \'flow\'])')
   .option('--ignore <errorCodes...>', 'error code(s) to ignore (example: --ignore=MISSING_ENV_FILE)')
   .option('--token <token>', 'set Armor ⛨ token')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -95,7 +96,8 @@ program.command('get')
   .option('-pp, --pretty-print', 'pretty print output')
   .option('--pp', 'pretty print output (alias)')
   .option('--format <type>', 'format of the output (json, shell, colon, eval)', 'json')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -115,7 +117,8 @@ program.command('set')
   .option('-c, --encrypt', 'encrypt value', true)
   .option('-p, --plain', 'store value as plain text', false)
   .option('--no-create', 'do not create .env file(s) when missing')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -132,7 +135,8 @@ program.command('encrypt')
   .option('--stdout', 'send to stdout')
   .option('--token <token>', 'set Armor ⛨ token')
   .option('--no-create', 'do not create .env file(s) when missing')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .action(function (...args) {
     this.envs = envs
@@ -146,7 +150,8 @@ program.command('decrypt')
   .option('-fk, --env-keys-file <path>', 'path to your .env.keys file (default: same path as your env file)')
   .option('-k, --key <keys...>', 'keys(s) to decrypt (default: all keys in file)')
   .option('-ek, --exclude-key <excludeKeys...>', 'keys(s) to exclude from decryption (default: none)')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .option('--stdout', 'send to stdout')
   .action(function (...args) {
@@ -161,7 +166,8 @@ program.command('keypair')
   .argument('[KEY]', 'environment variable key name')
   .option('-f, --env-file <path>', 'path(s) to your env file(s)')
   .option('-fk, --env-keys-file <path>', 'path to your .env.keys file (default: same path as your env file)')
-  .option('--no-armor', 'disable dotenvx-armor features')
+  .option('--no-armor', 'disable Dotenvx Armor features')
+  .option('--no-keychain', 'disable macOS Keychain features')
   .addOption(new Option('--no-ops', 'disable dotenvx-ops features (deprecated. use --no-armor)').hideHelp())
   .option('-pp, --pretty-print', 'pretty print output')
   .option('--pp', 'pretty print output (alias)')
@@ -180,6 +186,15 @@ program.command('ls')
     return require('./actions/ls').apply(this, args)
   })
 
+// dotenvx genexample
+program.command('genexample')
+  .description('generate .env.example')
+  .argument('[directory]', 'directory to generate from', '.')
+  .option('-f, --env-file <paths...>', 'path(s) to your env file(s)', '.env')
+  .action(function (...args) {
+    return require('./actions/ext/genexample').apply(this, args)
+  })
+
 // dotenvx gitignore
 program.command('gitignore')
   .description('append to .gitignore')
@@ -255,7 +270,11 @@ program.addHelpText('after', ' ')
 program.addHelpText('after', 'Professional Security: ')
 program.addHelpText('after', '  login                    log in to move keys off-device, share with your team, and audit access')
 program.addHelpText('after', '  logout                   log out of connected security features')
-program.addHelpText('after', '  armor                    ⛨ move private keys off-device [www.dotenvx.com/armor]')
+program.addHelpText('after', '  keychain                 ⌥ move private keys into macOS Keychain')
+program.addHelpText('after', '  armor                    ⛨ move private keys into Dotenvx Armor [www.dotenvx.com/armor]')
+
+// dotenvx keychain
+require('./commands/keychain')(program.command('keychain', { hidden: true }))
 
 // dotenvx armor
 require('./commands/armor')(program.command('armor', { hidden: true }))

package/src/lib/main.d.ts

@@ -179,6 +179,14 @@ export interface DotenvConfigOptions {
    */
   noArmor?: boolean;
 
+  /**
+   * Turn off macOS Keychain features.
+   *
+   * @default false
+   * @example require('@dotenvx/dotenvx').config({ noKeychain: true })
+   */
+  noKeychain?: boolean;
+
   /**
    * Turn off Dotenvx Armor features. Alias for `noArmor`.
    *
@@ -262,6 +270,14 @@ export interface SetOptions {
    */
   noArmor?: boolean;
 
+  /**
+   * Turn off macOS Keychain features.
+   *
+   * @default false
+   * @example require('@dotenvx/dotenvx').set(key, value, { noKeychain: true })
+   */
+  noKeychain?: boolean;
+
   /**
    * Turn off Dotenvx Armor features. Alias for `noArmor`.
    *
@@ -347,6 +363,14 @@ export interface GetOptions {
    */
   noArmor?: boolean;
 
+  /**
+   * Turn off macOS Keychain features.
+   *
+   * @default false
+   * @example require('@dotenvx/dotenvx').get('KEY', { noKeychain: true })
+   */
+  noKeychain?: boolean;
+
   /**
    * Turn off Dotenvx Armor features. Alias for `noArmor`.
    *

package/src/lib/main.js

@@ -66,6 +66,7 @@ const config = function (options = {}) {
 
   // dotenvx-armor related
   const noArmor = resolveNoArmor(options)
+  const noKeychain = resolveNoKeychain(options)
 
   try {
     let envs = buildEnvs(options)
@@ -81,6 +82,7 @@ const config = function (options = {}) {
       processEnv,
       envKeysFile,
       noArmor,
+      noKeychain,
       noSpinner: options.noSpinner,
       token: options.token
     })
@@ -227,6 +229,7 @@ const set = async function (key, value, options = {}) {
   const envKeysFilepath = options.envKeysFile
   const noCreate = options.create === false
   const noArmor = resolveNoArmor(options)
+  const noKeychain = resolveNoKeychain(options)
 
   const {
     keysSrc,
@@ -239,6 +242,7 @@ const set = async function (key, value, options = {}) {
     value,
     fk: envKeysFilepath,
     noArmor,
+    noKeychain,
     noCreate,
     encrypt
   })
@@ -306,6 +310,7 @@ const get = async function (key, options = {}) {
 
   const envs = buildEnvs(options)
   const noArmor = resolveNoArmor(options)
+  const noKeychain = resolveNoKeychain(options)
 
   // ignore
   const ignore = options.ignore || []
@@ -316,7 +321,8 @@ const get = async function (key, options = {}) {
     overload: options.overload,
     all: options.all,
     envKeysFile: options.envKeysFile,
-    noArmor
+    noArmor,
+    noKeychain
   })
 
   for (const error of errors || []) {
@@ -377,6 +383,10 @@ function resolveNoArmor (options = {}) {
   return options.noArmor === true || options.noOps === true || (!options.token && sesh.noArmorSync())
 }
 
+function resolveNoKeychain (options = {}) {
+  return options.noKeychain === true || options.keychain === false
+}
+
 module.exports = {
   // dotenv proxies
   config,

package/src/lib/providers/index.js

@@ -1,25 +1,41 @@
 const Session = require('./../../db/session')
 
 const armorProvider = require('./armor/index')
+const keychainProvider = require('./keychain/index')
+
 function syncArmorProvider (publicKeyHex) {
   const { createSyncFn } = require('synckit')
   const runProviderSync = createSyncFn(require.resolve('./worker.js'))
   return runProviderSync(require.resolve('./armor/index'), publicKeyHex)
 }
 
-async function providers (options = {}) {
-  if (Object.prototype.hasOwnProperty.call(options, 'provider')) {
-    return options.provider
-  }
+function hasKey (keyring, publicKeyHex) {
+  return keyring && keyring[publicKeyHex]
+}
 
-  if (options.noArmor || options.armor === false) {
-    return null
+function composeProviders (providerFns) {
+  return async function provider (publicKeyHex) {
+    for (const providerFn of providerFns) {
+      const keyring = await providerFn(publicKeyHex)
+      if (hasKey(keyring, publicKeyHex)) return keyring
+    }
+
+    return {}
   }
+}
 
-  const sesh = new Session()
-  const noArmor = !options.token && await sesh.noArmor()
-  if (noArmor) return null
+function composeProvidersSync (providerFns) {
+  return function providerSync (publicKeyHex) {
+    for (const providerFn of providerFns) {
+      const keyring = providerFn(publicKeyHex)
+      if (hasKey(keyring, publicKeyHex)) return keyring
+    }
 
+    return {}
+  }
+}
+
+function armorProviderForOptions (options) {
   return (publicKeyHex) => armorProvider(publicKeyHex, {
     onStatus: options.onStatus,
     token: options.token,
@@ -27,20 +43,65 @@ async function providers (options = {}) {
   })
 }
 
+function useKeychain (options) {
+  if (process.platform !== 'darwin') return false
+  if (process.env.CI) return false
+  return options.noKeychain !== true && options.keychain !== false
+}
+
+function useArmor (options, noArmor) {
+  return options.noArmor !== true && options.armor !== false && !noArmor
+}
+
+function providerFrom (providerFns, compose) {
+  if (providerFns.length === 0) return null
+  if (providerFns.length === 1) return providerFns[0]
+
+  return compose(providerFns)
+}
+
+async function providers (options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, 'provider')) {
+    return options.provider
+  }
+
+  const providerFns = []
+
+  if (useKeychain(options)) {
+    providerFns.push(keychainProvider)
+  }
+
+  if (options.noArmor !== true && options.armor !== false) {
+    const sesh = new Session()
+    const noArmor = !options.token && await sesh.noArmor()
+    if (useArmor(options, noArmor)) {
+      providerFns.push(armorProviderForOptions(options))
+    }
+  }
+
+  return providerFrom(providerFns, composeProviders)
+}
+
 providers.sync = function providersSync (options = {}) {
   if (Object.prototype.hasOwnProperty.call(options, 'provider')) {
     return options.provider
   }
 
-  if (options.noArmor || options.armor === false) {
-    return null
+  const providerFns = []
+
+  if (useKeychain(options)) {
+    providerFns.push(keychainProvider)
   }
 
-  const sesh = new Session()
-  const noArmor = !options.token && sesh.noArmorSync()
-  if (noArmor) return null
+  if (options.noArmor !== true && options.armor !== false) {
+    const sesh = new Session()
+    const noArmor = !options.token && sesh.noArmorSync()
+    if (useArmor(options, noArmor)) {
+      providerFns.push(syncArmorProvider)
+    }
+  }
 
-  return syncArmorProvider
+  return providerFrom(providerFns, composeProvidersSync)
 }
 
 module.exports = providers

package/src/lib/providers/keychain/index.js

@@ -0,0 +1,20 @@
+const { execFileSync } = require('child_process')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+function index (publicKeyHex) {
+  if (process.platform !== 'darwin') return {}
+
+  try {
+    const stdout = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKeyHex, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    const privateKeyHex = stdout.trim()
+    if (!privateKeyHex) return {}
+
+    return { [publicKeyHex]: privateKeyHex }
+  } catch {
+    return {}
+  }
+}
+
+module.exports = index

package/src/lib/resolvers/envs.js

@@ -235,7 +235,7 @@ async function envs (options = {}) {
   const readableFilepaths = new Set()
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
-  const provider = options.noArmor ? null : await providers(options)
+  const provider = await providers(options)
 
   for (const env of options.envs || []) {
     if (env.type === TYPE_ENV_FILE) {
@@ -269,7 +269,7 @@ function envsSync (options = {}) {
   const readableFilepaths = new Set()
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
-  const provider = options.noArmor ? null : providers.sync(options)
+  const provider = providers.sync(options)
 
   for (const env of options.envs || []) {
     if (env.type === TYPE_ENV_FILE) {

package/src/lib/resolvers/get.js

@@ -50,6 +50,7 @@ function buildOptions (options, processEnv) {
     processEnv,
     envKeysFilepath: options.envKeysFilepath || options.envKeysFile || null,
     noArmor: options.noArmor,
+    noKeychain: options.noKeychain,
     onStatus: options.onStatus
   }
 }

package/src/lib/services/genexample.js

@@ -45,7 +45,7 @@ class Genexample {
       const filepath = path.resolve(this.directory, envFilepath)
       if (!fsx.existsSync(filepath)) {
         const error = new Errors({ envFilepath, filepath }).missingEnvFile()
-        error.help = `? add it with [echo "HELLO=World" > ${envFilepath}] and then run [dotenvx ext genexample]`
+        error.help = `? add it with [echo "HELLO=World" > ${envFilepath}] and then run [dotenvx genexample]`
         throw error
       }
 

package/src/lib/services/keychainDown.js

@@ -0,0 +1,57 @@
+const { execFileSync } = require('child_process')
+
+const keynames = require('../conventions/keynames')
+const readEnvKey = require('../helpers/readEnvKey')
+const upsertEnvKey = require('../helpers/upsertEnvKey')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+class KeychainDown {
+  constructor (envFile = '.env', envKeysFile = '.env.keys') {
+    this.envFile = envFile
+    this.envKeysFile = envKeysFile
+  }
+
+  run () {
+    const envFile = this.envFile
+    const envKeysFile = this.envKeysFile
+
+    const {
+      publicKeyName,
+      privateKeyName
+    } = keynames(envFile)
+
+    const publicKey = readEnvKey(publicKeyName, envFile, { strict: true, ignore: ['MISSING_PRIVATE_KEY'] })
+    let privateKey
+
+    try {
+      privateKey = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKey, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    } catch (error) {
+      privateKey = readEnvKey(privateKeyName, envKeysFile, { strict: false })
+
+      if (privateKey) {
+        return {
+          changed: false,
+          privateKeyName,
+          privateKeyValue: privateKey,
+          publicKeyValue: publicKey
+        }
+      }
+
+      throw error
+    }
+
+    upsertEnvKey(privateKeyName, privateKey, envKeysFile)
+    execFileSync(SECURITY_BIN, ['delete-generic-password', '-s', SERVICE, '-a', publicKey], { stdio: 'ignore' })
+
+    return {
+      changed: true,
+      privateKeyName,
+      privateKeyValue: privateKey,
+      publicKeyValue: publicKey
+    }
+  }
+}
+
+module.exports = KeychainDown

package/src/lib/services/keychainPull.js

@@ -0,0 +1,46 @@
+const { execFileSync } = require('child_process')
+
+const keynames = require('../conventions/keynames')
+const readEnvKey = require('../helpers/readEnvKey')
+const upsertEnvKey = require('../helpers/upsertEnvKey')
+const armoredKeyDisplay = require('../helpers/armoredKeyDisplay')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+class KeychainPull {
+  constructor (envFile = '.env', envKeysFile = '.env.keys') {
+    this.envFile = envFile
+    this.envKeysFile = envKeysFile
+  }
+
+  run () {
+    const envFile = this.envFile
+    const envKeysFile = this.envKeysFile
+
+    const {
+      publicKeyName,
+      privateKeyName
+    } = keynames(envFile)
+
+    const publicKey = readEnvKey(publicKeyName, envFile, { strict: true, ignore: ['MISSING_PRIVATE_KEY'] })
+    let privateKey
+
+    try {
+      privateKey = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKey, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    } catch {
+      throw new Error(`[NOT_FOUND] private key not found in macOS Keychain (${armoredKeyDisplay(publicKey)}). fix: [dotenvx keychain up]`)
+    }
+
+    const result = upsertEnvKey(privateKeyName, privateKey, envKeysFile)
+
+    return {
+      changed: result.changed,
+      privateKeyName,
+      privateKeyValue: privateKey,
+      publicKeyValue: publicKey
+    }
+  }
+}
+
+module.exports = KeychainPull

package/src/lib/services/keychainPush.js

@@ -0,0 +1,63 @@
+const { execFileSync } = require('child_process')
+
+const keynames = require('../conventions/keynames')
+const readEnvKey = require('../helpers/readEnvKey')
+const armoredKeyDisplay = require('../helpers/armoredKeyDisplay')
+
+const SECURITY_BIN = '/usr/bin/security'
+const SERVICE = 'dotenvx'
+
+function addGenericPassword (publicKey, label, privateKey) {
+  try {
+    execFileSync(SECURITY_BIN, ['add-generic-password', '-U', '-s', SERVICE, '-a', publicKey, '-l', label, '-w', privateKey], { stdio: 'ignore' })
+  } catch {
+    throw new Error('failed to save private key to macOS Keychain')
+  }
+}
+
+class KeychainPush {
+  constructor (envFile = '.env', envKeysFile = '.env.keys') {
+    this.envFile = envFile
+    this.envKeysFile = envKeysFile
+  }
+
+  run () {
+    const envFile = this.envFile
+    const envKeysFile = this.envKeysFile
+
+    const {
+      publicKeyName,
+      privateKeyName
+    } = keynames(envFile)
+
+    const publicKey = readEnvKey(publicKeyName, envFile, { strict: true, ignore: ['MISSING_PRIVATE_KEY'] })
+    const privateKey = readEnvKey(privateKeyName, envKeysFile, { strict: true })
+    const label = `dotenvx (${armoredKeyDisplay(publicKey)})`
+
+    try {
+      const existingPrivateKey = execFileSync(SECURITY_BIN, ['find-generic-password', '-s', SERVICE, '-a', publicKey, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+
+      if (existingPrivateKey === privateKey) {
+        return {
+          changed: false,
+          label,
+          privateKeyName,
+          privateKeyValue: privateKey,
+          publicKeyValue: publicKey
+        }
+      }
+    } catch {}
+
+    addGenericPassword(publicKey, label, privateKey)
+
+    return {
+      changed: true,
+      label,
+      privateKeyName,
+      privateKeyValue: privateKey,
+      publicKeyValue: publicKey
+    }
+  }
+}
+
+module.exports = KeychainPush