@dotenvx/dotenvx 2.7.3 → 2.8.0

package/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 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.7.3...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.8.0...main)
+
+## [2.8.0](https://github.com/dotenvx/dotenvx/compare/v2.7.3...v2.8.0) (2026-07-14)
+
+### Added
+
+* Add `FILE_NOT_WRITABLE` error for user convenience ([#891](https://github.com/dotenvx/dotenvx/pull/891))
+* Support Enclaved Armored Keys ([#892](https://github.com/dotenvx/dotenvx/pull/892))
 
 ## [2.7.3](https://github.com/dotenvx/dotenvx/compare/v2.7.2...v2.7.3) (2026-07-13)
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.7.3",
+  "version": "2.8.0",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",

package/src/cli/actions/ext/prebuild.js

@@ -17,7 +17,7 @@ function prebuild (directory) {
     } = new Prebuild(directory, options).run()
 
     for (const warning of warnings) {
-      logger.warn(warning.messageWithHelp)
+      logger.warn(warning.messageWithHelp || warning.message)
     }
 
     logger.success(successMessage)

package/src/cli/actions/ext/precommit.js

@@ -17,7 +17,7 @@ function precommit (directory) {
     } = new Precommit(directory, options).run()
 
     for (const warning of warnings) {
-      logger.warn(warning.messageWithHelp)
+      logger.warn(warning.messageWithHelp || warning.message)
     }
 
     logger.success(successMessage)

package/src/cli/actions/get.js

@@ -53,7 +53,7 @@ async function get (key) {
       }
 
       errorCount += 1
-      logger.error(error.messageWithHelp)
+      logger.error(error.messageWithHelp || error.message)
     }
 
     if (spinner) spinner.stop()

package/src/cli/actions/run.js

@@ -151,7 +151,7 @@ async function run () {
         if (error.code === 'MISSING_ENV_FILE' && options.convention) { // do not output error for conventions (too noisy)
           // intentionally quiet
         } else {
-          logger.error(error.messageWithHelp)
+          logger.error(error.messageWithHelp || error.message)
         }
       }
 

package/src/lib/api/postArmorDecrypt.js

@@ -0,0 +1,49 @@
+const { http } = require('../helpers/http')
+const buildApiError = require('../helpers/buildApiError')
+const packageJson = require('../helpers/packageJson')
+const normalizeToken = require('../helpers/normalizeToken')
+
+class PostArmorDecrypt {
+  constructor (hostname, token, devicePublicKey, publicKey, src, grantToken) {
+    this.hostname = hostname || 'https://armor.dotenvx.com'
+    this.token = token
+    this.devicePublicKey = devicePublicKey
+    this.publicKey = publicKey
+    this.src = src
+    this.grantToken = grantToken
+  }
+
+  async run () {
+    const token = normalizeToken(this.token)
+    const url = `${this.hostname}/api/armor/decrypt`
+    const body = {
+      device_public_key: this.devicePublicKey,
+      cli_version: packageJson.version,
+      public_key: this.publicKey,
+      src: this.src
+    }
+
+    if (this.grantToken) {
+      body.grant_token = this.grantToken
+    }
+
+    const resp = await http(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    })
+
+    const json = await resp.body.json()
+
+    if (resp.statusCode >= 400) {
+      throw buildApiError(resp.statusCode, json)
+    }
+
+    return json
+  }
+}
+
+module.exports = PostArmorDecrypt

package/src/lib/decryptors/armor/index.js

@@ -0,0 +1,21 @@
+const Session = require('../../../db/session')
+const PostArmorDecrypt = require('../../api/postArmorDecrypt')
+
+async function index (src, options = {}) {
+  const sesh = new Session()
+
+  const hostname = sesh.hostname()
+  const token = sesh.token()
+  const devicePublicKey = sesh.devicePublicKey()
+
+  return await new PostArmorDecrypt(
+    hostname,
+    token,
+    devicePublicKey,
+    options.publicKey,
+    src,
+    options.grantToken
+  ).run()
+}
+
+module.exports = index

package/src/lib/decryptors/decryptor-worker.js

@@ -0,0 +1,6 @@
+const { runAsWorker } = require('@dotenvx/tooling')
+const decryptor = require('./armor/index')
+
+runAsWorker(async (src, options) => {
+  return decryptor(src, options)
+})

package/src/lib/decryptors/index.js

@@ -0,0 +1,69 @@
+const Session = require('./../../db/session')
+
+const armorDecryptor = require('./armor/index')
+
+function syncArmorDecryptor (src, options) {
+  const { createSyncFn } = require('@dotenvx/tooling')
+  const runDecryptorSync = createSyncFn(require.resolve('./decryptor-worker.js'))
+  return runDecryptorSync(src, options)
+}
+
+function armorDecryptorForOptions (options) {
+  return (src, decryptOptions) => armorDecryptor(src, {
+    ...decryptOptions,
+    onStatus: options.onStatus,
+    token: options.token,
+    command: options.command
+  })
+}
+
+function syncArmorDecryptorForOptions (options) {
+  return (src, decryptOptions) => syncArmorDecryptor(src, {
+    ...decryptOptions,
+    onStatus: options.onStatus,
+    token: options.token,
+    command: options.command
+  })
+}
+
+function useArmor (options, noArmor) {
+  return options.noArmor !== true && options.armor !== false && !noArmor
+}
+
+async function decryptors (options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, 'decryptor')) {
+    return options.decryptor
+  }
+
+  if (options.noArmor === true || options.armor === false) {
+    return null
+  }
+
+  const sesh = new Session()
+  const noArmor = !options.token && await sesh.noArmor()
+  if (!useArmor(options, noArmor)) {
+    return null
+  }
+
+  return armorDecryptorForOptions(options)
+}
+
+decryptors.sync = function decryptorsSync (options = {}) {
+  if (Object.prototype.hasOwnProperty.call(options, 'decryptor')) {
+    return options.decryptor
+  }
+
+  if (options.noArmor === true || options.armor === false) {
+    return null
+  }
+
+  const sesh = new Session()
+  const noArmor = !options.token && sesh.noArmorSync()
+  if (!useArmor(options, noArmor)) {
+    return null
+  }
+
+  return syncArmorDecryptorForOptions(options)
+}
+
+module.exports = decryptors

package/src/lib/helpers/catchAndLog.js

@@ -1,6 +1,11 @@
 const { logger } = require('./../../shared/logger')
+const Errors = require('./errors')
 
 function catchAndLog (error) {
+  if (error.code === 'EACCES' || error.code === 'EPERM') {
+    error = new Errors({ filepath: error.path }).fileNotWritable()
+  }
+
   const msg = error.messageWithHelp || error.message
   if (msg) {
     logger.error(msg)

package/src/lib/helpers/errors.js

@@ -20,6 +20,7 @@ const ISSUE_BY_CODE = {
   MISSING_PRIVATE_KEY: 'https://github.com/dotenvx/dotenvx/issues/464',
   MISSING_PUBLIC_KEY: 'https://github.com/dotenvx/dotenvx/issues/865',
   MISSING_VALUE: 'https://github.com/dotenvx/dotenvx/issues/864',
+  FILE_NOT_WRITABLE: 'https://github.com/dotenvx/dotenvx/issues/890',
   PRECOMMIT_HOOK_MODIFY_FAILED: 'try again or report error',
   WRONG_PRIVATE_KEY: 'https://github.com/dotenvx/dotenvx/issues/466'
 }
@@ -279,6 +280,19 @@ class Errors {
     return e
   }
 
+  fileNotWritable () {
+    const code = 'FILE_NOT_WRITABLE'
+    const filepath = this.filepath || 'unknown'
+    const message = `[${code}] cannot write to file (${filepath})`
+    const help = `fix: [${ISSUE_BY_CODE[code]}]`
+
+    const e = new Error(message)
+    e.code = code
+    e.help = help
+    e.messageWithHelp = `${message}. ${help}`
+    return e
+  }
+
   missingValue () {
     const code = 'MISSING_VALUE'
     const message = `[${code}] missing value (${this.key})`

package/src/lib/helpers/isNetworkError.js

@@ -0,0 +1,21 @@
+const NETWORK_ERROR_CODES = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ENOTFOUND',
+  'ENETDOWN',
+  'ENETUNREACH',
+  'EHOSTDOWN',
+  'EHOSTUNREACH',
+  'EPIPE',
+  'ETIMEDOUT',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_BODY_TIMEOUT',
+  'UND_ERR_SOCKET'
+])
+
+function isNetworkError (error) {
+  return NETWORK_ERROR_CODES.has(error && error.code) || NETWORK_ERROR_CODES.has(error && error.cause && error.cause.code)
+}
+
+module.exports = isNetworkError

package/src/lib/helpers/parseWithDecryptor.js

@@ -0,0 +1,66 @@
+const { parse, parseSync } = require('@dotenvx/primitives')
+const isNetworkError = require('./isNetworkError')
+
+const SERVER_SIDE_DECRYPTION_REQUIRED = 'SERVER_SIDE_DECRYPTION_REQUIRED'
+
+function decryptOptions (error) {
+  const meta = error.meta || {}
+
+  return {
+    publicKey: meta.public_key,
+    grantToken: meta.grant_token,
+    error
+  }
+}
+
+function parseOptionsWithoutProvider (options) {
+  return {
+    ...options,
+    provider: null,
+    decryptor: null
+  }
+}
+
+async function parseWithDecryptor (src, options = {}) {
+  try {
+    return await parse(src, options)
+  } catch (error) {
+    if (error.code !== SERVER_SIDE_DECRYPTION_REQUIRED || typeof options.decryptor !== 'function') {
+      throw error
+    }
+
+    try {
+      const result = await options.decryptor(src, decryptOptions(error))
+      return await parse(result.src, parseOptionsWithoutProvider(options))
+    } catch (decryptorError) {
+      if (isNetworkError(decryptorError)) {
+        return await parse(src, parseOptionsWithoutProvider(options))
+      }
+
+      throw decryptorError
+    }
+  }
+}
+
+parseWithDecryptor.sync = function parseWithDecryptorSync (src, options = {}) {
+  try {
+    return parseSync(src, options)
+  } catch (error) {
+    if (error.code !== SERVER_SIDE_DECRYPTION_REQUIRED || typeof options.decryptor !== 'function') {
+      throw error
+    }
+
+    try {
+      const result = options.decryptor(src, decryptOptions(error))
+      return parseSync(result.src, parseOptionsWithoutProvider(options))
+    } catch (decryptorError) {
+      if (isNetworkError(decryptorError)) {
+        return parseSync(src, parseOptionsWithoutProvider(options))
+      }
+
+      throw decryptorError
+    }
+  }
+}
+
+module.exports = parseWithDecryptor

package/src/lib/main.js

@@ -115,10 +115,10 @@ const config = function (options = {}) {
 
         if (error.code === 'MISSING_ENV_FILE') {
           if (!options.convention) { // do not output error for conventions (too noisy)
-            logger.error(error.messageWithHelp)
+            logger.error(error.messageWithHelp || error.message)
           }
         } else {
-          logger.error(error.messageWithHelp)
+          logger.error(error.messageWithHelp || error.message)
         }
       }
 
@@ -155,7 +155,7 @@ const config = function (options = {}) {
   } catch (error) {
     if (strict) throw error // throw immediately if strict
 
-    logger.error(error.messageWithHelp)
+    logger.error(error.messageWithHelp || error.message)
 
     return { parsed: {}, error }
   }
@@ -209,7 +209,7 @@ const parse = function (src, options = {}) {
       continue // ignore error
     }
 
-    logger.error(error.messageWithHelp)
+    logger.error(error.messageWithHelp || error.message)
   }
 
   return parsed
@@ -347,7 +347,7 @@ const get = async function (key, options = {}) {
 
     if (options.strict) throw error // throw immediately if strict
 
-    logger.error(error.messageWithHelp)
+    logger.error(error.messageWithHelp || error.message)
   }
 
   if (key) {

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

@@ -1,6 +1,7 @@
 const Session = require('../../../db/session')
 const ArmorKeyring = require('../../services/armorKeyring')
 const armoredKeyDisplay = require('../../helpers/armoredKeyDisplay')
+const isNetworkError = require('../../helpers/isNetworkError')
 
 async function index (publicKeyHex, options = {}) {
   const sesh = new Session()
@@ -23,7 +24,15 @@ async function index (publicKeyHex, options = {}) {
     }
   }
 
-  return await keyring.run() // { "publicKey": "privateKey" }
+  try {
+    return await keyring.run() // { "publicKey": "privateKey" }
+  } catch (error) {
+    if (isNetworkError(error)) {
+      return {}
+    }
+
+    throw error
+  }
 }
 
 module.exports = index

package/src/lib/providers/index.js

@@ -5,8 +5,8 @@ const nativeProvider = require('./native/index')
 
 function syncArmorProvider (publicKeyHex) {
   const { createSyncFn } = require('@dotenvx/tooling')
-  const runProviderSync = createSyncFn(require.resolve('./worker.js'))
-  return runProviderSync(require.resolve('./armor/index'), publicKeyHex)
+  const runProviderSync = createSyncFn(require.resolve('./provider-worker.js'))
+  return runProviderSync(publicKeyHex)
 }
 
 function hasKey (keyring, publicKeyHex) {

package/src/lib/providers/provider-worker.js

@@ -0,0 +1,6 @@
+const { runAsWorker } = require('@dotenvx/tooling')
+const provider = require('./armor/index')
+
+runAsWorker(async (publicKeyHex) => {
+  return provider(publicKeyHex)
+})

package/src/lib/resolvers/envs.js

@@ -1,6 +1,6 @@
 const fsx = require('./../helpers/fsx')
 const path = require('path')
-const { encrypted, parse, parseSync } = require('@dotenvx/primitives')
+const { encrypted } = require('@dotenvx/primitives')
 
 const TYPE_ENV = 'env'
 const TYPE_ENV_FILE = 'envFile'
@@ -10,6 +10,8 @@ const detectEncoding = require('./../helpers/detectEncoding')
 const detectEncodingSync = require('./../helpers/detectEncodingSync')
 const keynames = require('./../conventions/keynames')
 const providers = require('./../providers')
+const decryptors = require('./../decryptors')
+const parseWithDecryptor = require('./../helpers/parseWithDecryptor')
 
 function unresolvedEncryptedErrors (parsed) {
   const keys = []
@@ -48,7 +50,7 @@ function inject (processEnv, parsed) {
   }
 }
 
-function buildParseOptions ({ processEnv, overload, envKeysFilepath, provider }) {
+function buildParseOptions ({ processEnv, overload, envKeysFilepath, provider, decryptor }) {
   const options = {
     processEnv,
     overload,
@@ -61,10 +63,14 @@ function buildParseOptions ({ processEnv, overload, envKeysFilepath, provider })
     options.provider = null
   }
 
+  if (decryptor) {
+    options.decryptor = decryptor
+  }
+
   return options
 }
 
-async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider }) {
+async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider, decryptor }) {
   const row = {}
   row.type = TYPE_ENV
   row.string = env.value
@@ -79,7 +85,8 @@ async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider
       processEnv: parseProcessEnv,
       overload,
       envKeysFilepath,
-      provider
+      provider,
+      decryptor
     })
 
     const {
@@ -87,7 +94,7 @@ async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider
       errors,
       injected,
       existed
-    } = await parse(env.value, parseOptions)
+    } = await parseWithDecryptor(env.value, parseOptions)
 
     row.parsed = parsed
     row.errors = decryptErrors(parsed, errors)
@@ -102,7 +109,7 @@ async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider
   return row
 }
 
-function injectEnvSync ({ env, overload, processEnv, envKeysFilepath, provider }) {
+function injectEnvSync ({ env, overload, processEnv, envKeysFilepath, provider, decryptor }) {
   const row = {}
   row.type = TYPE_ENV
   row.string = env.value
@@ -117,7 +124,8 @@ function injectEnvSync ({ env, overload, processEnv, envKeysFilepath, provider }
       processEnv: parseProcessEnv,
       overload,
       envKeysFilepath,
-      provider
+      provider,
+      decryptor
     })
 
     const {
@@ -125,7 +133,7 @@ function injectEnvSync ({ env, overload, processEnv, envKeysFilepath, provider }
       errors,
       injected,
       existed
-    } = parseSync(env.value, parseOptions)
+    } = parseWithDecryptor.sync(env.value, parseOptions)
 
     row.parsed = parsed
     row.errors = decryptErrors(parsed, errors)
@@ -140,7 +148,7 @@ function injectEnvSync ({ env, overload, processEnv, envKeysFilepath, provider }
   return row
 }
 
-async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, provider, readableFilepaths }) {
+async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, provider, decryptor, readableFilepaths }) {
   const row = {}
   row.type = TYPE_ENV_FILE
   row.filepath = env.value
@@ -157,7 +165,8 @@ async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, prov
       processEnv,
       overload,
       envKeysFilepath: fk,
-      provider
+      provider,
+      decryptor
     })
 
     const {
@@ -165,7 +174,7 @@ async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, prov
       errors,
       injected,
       existed
-    } = await parse(src, parseOptions)
+    } = await parseWithDecryptor(src, parseOptions)
 
     row.src = src
     row.parsed = parsed
@@ -185,7 +194,7 @@ async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, prov
   return row
 }
 
-function injectEnvFileSync ({ env, overload, processEnv, envKeysFilepath, provider, readableFilepaths }) {
+function injectEnvFileSync ({ env, overload, processEnv, envKeysFilepath, provider, decryptor, readableFilepaths }) {
   const row = {}
   row.type = TYPE_ENV_FILE
   row.filepath = env.value
@@ -202,7 +211,8 @@ function injectEnvFileSync ({ env, overload, processEnv, envKeysFilepath, provid
       processEnv,
       overload,
       envKeysFilepath: fk,
-      provider
+      provider,
+      decryptor
     })
 
     const {
@@ -210,7 +220,7 @@ function injectEnvFileSync ({ env, overload, processEnv, envKeysFilepath, provid
       errors,
       injected,
       existed
-    } = parseSync(src, parseOptions)
+    } = parseWithDecryptor.sync(src, parseOptions)
 
     row.src = src
     row.parsed = parsed
@@ -236,6 +246,7 @@ async function envs (options = {}) {
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
   const provider = await providers(options)
+  const decryptor = await decryptors(options)
 
   for (const env of options.envs || []) {
     if (env.type === TYPE_ENV_FILE) {
@@ -245,6 +256,7 @@ async function envs (options = {}) {
         processEnv,
         envKeysFilepath,
         provider,
+        decryptor,
         readableFilepaths
       }))
     } else if (env.type === TYPE_ENV) {
@@ -253,7 +265,8 @@ async function envs (options = {}) {
         overload: options.overload,
         processEnv,
         envKeysFilepath,
-        provider
+        provider,
+        decryptor
       }))
     }
   }
@@ -270,6 +283,7 @@ function envsSync (options = {}) {
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
   const provider = providers.sync(options)
+  const decryptor = decryptors.sync(options)
 
   for (const env of options.envs || []) {
     if (env.type === TYPE_ENV_FILE) {
@@ -279,6 +293,7 @@ function envsSync (options = {}) {
         processEnv,
         envKeysFilepath,
         provider,
+        decryptor,
         readableFilepaths
       }))
     } else if (env.type === TYPE_ENV) {
@@ -287,7 +302,8 @@ function envsSync (options = {}) {
         overload: options.overload,
         processEnv,
         envKeysFilepath,
-        provider
+        provider,
+        decryptor
       }))
     }
   }

package/src/lib/transforms/decrypt.js

@@ -1,6 +1,6 @@
 const fsx = require('./../helpers/fsx')
 const path = require('path')
-const { parse, upsert } = require('@dotenvx/primitives')
+const { upsert } = require('@dotenvx/primitives')
 
 const TYPE_ENV_FILE = 'envFile'
 
@@ -8,6 +8,8 @@ const Errors = require('./../helpers/errors')
 const { determine } = require('./../helpers/envResolution')
 const detectEncoding = require('./../helpers/detectEncoding')
 const providers = require('./../providers')
+const decryptors = require('./../decryptors')
+const parseWithDecryptor = require('./../helpers/parseWithDecryptor')
 
 function parseError (error) {
   return new Errors({
@@ -23,6 +25,7 @@ async function decrypt (options = {}) {
   const ek = options.ek
   const fk = options.fk
   const provider = await providers(options)
+  const decryptor = await decryptors(options)
 
   const processedEnvs = []
   const changedFilepaths = []
@@ -41,7 +44,7 @@ async function decrypt (options = {}) {
       const encoding = await detectEncoding(filepath)
       row.envSrc = await fsx.readFileX(filepath, { encoding })
 
-      const { parsed, errors } = await parse(row.envSrc, { fk, ik, ek, array: true, provider })
+      const { parsed, errors } = await parseWithDecryptor(row.envSrc, { fk, ik, ek, array: true, provider, decryptor })
 
       if (errors.length > 0) {
         row.error = parseError(errors[0])

package/src/lib/providers/worker.js

@@ -1,6 +0,0 @@
-const { runAsWorker } = require('@dotenvx/tooling')
-
-runAsWorker(async (providerPath, publicKeyHex) => {
-  const provider = require(providerPath)
-  return provider(publicKeyHex)
-})