@dotenvx/dotenvx 2.26.1 → 2.27.0

package/src/lib/proxy/proxyCertificates.js

@@ -0,0 +1,44 @@
+const { generateKeyPair, randomBytes } = require('node:crypto')
+const { promisify } = require('node:util')
+const forge = require('node-forge')
+
+// Only public certificates are persisted. Both signing keys stay in this process.
+module.exports = async function proxyCertificates (hosts = ['localhost']) {
+  const generate = () => promisify(generateKeyPair)('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
+  })
+  const [caKeys, leafKeys] = await Promise.all([generate(), generate()])
+  const issuer = [{ name: 'commonName', value: 'dotenvx temporary proxy' }]
+  const certificate = (keys, subject) => {
+    const cert = forge.pki.createCertificate()
+    cert.publicKey = forge.pki.publicKeyFromPem(keys.publicKey)
+    cert.serialNumber = '01' + randomBytes(16).toString('hex')
+    cert.validity.notBefore = new Date(Date.now() - 60000)
+    cert.validity.notAfter = new Date(Date.now() + 24 * 60 * 60 * 1000)
+    cert.setSubject(subject)
+    cert.setIssuer(issuer)
+    return cert
+  }
+  const ca = certificate(caKeys, issuer)
+  ca.setExtensions([
+    { name: 'basicConstraints', cA: true, critical: true },
+    { name: 'subjectKeyIdentifier' },
+    { name: 'authorityKeyIdentifier', keyIdentifier: true },
+    { name: 'keyUsage', keyCertSign: true, cRLSign: true, critical: true }
+  ])
+  const signingKey = forge.pki.privateKeyFromPem(caKeys.privateKey)
+  ca.sign(signingKey, forge.md.sha256.create())
+  const leaf = certificate(leafKeys, [{ name: 'commonName', value: hosts[0] || 'localhost' }])
+  leaf.setExtensions([
+    { name: 'basicConstraints', cA: false, critical: true },
+    { name: 'subjectKeyIdentifier' },
+    { name: 'authorityKeyIdentifier', keyIdentifier: ca.generateSubjectKeyIdentifier().getBytes() },
+    { name: 'keyUsage', digitalSignature: true, keyEncipherment: true, critical: true },
+    { name: 'extKeyUsage', serverAuth: true },
+    { name: 'subjectAltName', altNames: hosts.map(value => ({ type: 2, value })) }
+  ])
+  leaf.sign(signingKey, forge.md.sha256.create())
+  return { ca: forge.pki.certificateToPem(ca), cert: forge.pki.certificateToPem(leaf), key: leafKeys.privateKey }
+}

package/src/lib/proxy/proxyForward.js

@@ -0,0 +1,65 @@
+const eligibleHeaders = require('./eligibleHeaders')
+
+// Parent-only forwarding. Never load credential configuration into the application.
+function install (config, nativeFetch = globalThis.fetch) {
+  if (typeof nativeFetch !== 'function') throw new Error('Credential proxy requires Node.js with built-in fetch.')
+  return async function proxyFetch (input, init) {
+    const url = new URL(input instanceof Request ? input.url : input)
+    if (!config.credentials.some(item => item.host === url.hostname)) return nativeFetch(input, init)
+    if (url.protocol !== 'https:' || (url.port && url.port !== '443') || url.username || url.password) {
+      throw new Error('Credential proxy requests must use HTTPS on port 443.')
+    }
+    const request = new Request(input, init)
+    const upstreamHeaders = Object.fromEntries([...request.headers].filter(([name]) => eligibleHeaders(name)))
+    const values = Object.entries(upstreamHeaders).map(([name, value]) => {
+      // Preserve existing Basic support: its placeholder is encoded on the wire.
+      if (name === 'authorization' && value.startsWith('Basic ')) {
+        const encoded = value.slice(6)
+        const decoded = Buffer.from(encoded, 'base64')
+        if (decoded.toString('base64') !== encoded) throw new Error('Invalid Basic authorization.')
+        return decoded.toString('utf8')
+      }
+      return value
+    })
+    const active = config.credentials.filter(credential => {
+      const occurrences = values.reduce((total, value) => total + value.split(credential.placeholder).length - 1, 0)
+      if (occurrences && credential.host !== url.hostname) throw new Error('Proxy credential is not allowed at this destination.')
+      if (occurrences > 1) throw new Error('Proxy credential must occur in only one eligible header, once.')
+      return occurrences === 1
+    })
+    if (!active.length) throw new Error('Credential proxy requires a proxied environment variable in an eligible header.')
+    if (active.length > 8 || active.some(item => item.publicKey !== active[0].publicKey)) {
+      throw new Error('Proxy request requires at most eight credentials from the same keypair.')
+    }
+    const body = ['GET', 'HEAD'].includes(request.method) ? null : Buffer.from(await request.arrayBuffer())
+    if (body && body.length > 256 * 1024) throw new Error('Proxy request body exceeds 256 KiB.')
+    const credentials = active.map(({ publicKey, placeholder, ciphertext }) => ({ publicKey, placeholder, ciphertext }))
+    const metadata = JSON.stringify({ headers: upstreamHeaders, credentials })
+    if (Buffer.byteLength(metadata) > 64 * 1024) throw new Error('Proxy request metadata exceeds 64 KiB.')
+    const payload = JSON.stringify({
+      version: 1,
+      request: {
+        url: url.href,
+        method: request.method,
+        headers: upstreamHeaders,
+        body: body === null ? null : { encoding: 'base64', data: body.toString('base64') }
+      },
+      credentials
+    })
+    if (Buffer.byteLength(payload) > 512 * 1024) throw new Error('Proxy request envelope exceeds 512 KiB.')
+    const headers = new Headers({
+      Authorization: `Bearer ${config.token}`,
+      'Content-Type': 'application/json'
+    })
+    if (config.devicePublicKey) headers.set('dotenvx-device-public-key', config.devicePublicKey)
+    return nativeFetch(`${config.hostname}/api/proxy`, {
+      method: 'POST',
+      headers,
+      body: payload,
+      signal: request.signal,
+      redirect: 'error'
+    })
+  }
+}
+
+module.exports = install

package/src/lib/proxy/proxyPreload.js

@@ -0,0 +1,21 @@
+// Other runtimes use standard proxy/CA variables. Node also needs a bridge for
+// older runtimes and core HTTP clients that do not read proxy variables.
+if (process.env.DOTENVX_PROXY_URL) {
+  const http = require('node:http')
+  if (typeof http.setGlobalProxyFromEnv === 'function') {
+    http.setGlobalProxyFromEnv()
+  } else {
+    const { ProxyAgent, Agent, Dispatcher, setGlobalDispatcher } = require('undici')
+    const proxy = new ProxyAgent(process.env.DOTENVX_PROXY_URL)
+    const direct = new Agent()
+    class ProxyDispatcher extends Dispatcher {
+      dispatch (options, handler) {
+        const host = new URL(options.origin).hostname
+        return (['localhost', '127.0.0.1', '[::1]'].includes(host) ? direct : proxy).dispatch(options, handler)
+      }
+    }
+    setGlobalDispatcher(new ProxyDispatcher())
+  }
+  const { createGlobalProxyAgent } = require('global-agent')
+  createGlobalProxyAgent({ environmentVariableNamespace: '', forceGlobalAgent: true })
+}

package/src/lib/proxy/proxyPreloadSource.js

@@ -0,0 +1,3 @@
+// Source installs can resolve dependencies beside the original preload. The
+// executable build replaces this module with the bundled, standalone script.
+module.exports = `require(${JSON.stringify(require.resolve('./proxyPreload'))})\n`

package/src/lib/proxy/proxyServer.js

@@ -0,0 +1,175 @@
+const http = require('node:http')
+const https = require('node:https')
+const net = require('node:net')
+const tls = require('node:tls')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const certificates = require('./proxyCertificates')
+const forward = require('./proxyForward')
+const eligibleHeaders = require('./eligibleHeaders')
+
+const REQUEST_LIMIT = 256 * 1024
+const RESPONSE_LIMIT = 2 * 1024 * 1024
+const RESPONSE_HEADERS = ['content-type', 'request-id', 'retry-after', 'stripe-version']
+
+module.exports = async function startProxy (config, nativeFetch) {
+  const fetch = forward(config, nativeFetch)
+  const hosts = new Set(config.credentials.map(item => item.host))
+  const identity = await certificates(hosts.size ? [...hosts] : ['localhost'])
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'dxp-'))
+  fs.chmodSync(directory, 0o700)
+  const caPath = path.join(directory, 'ca.pem')
+  const sockets = new Set()
+  const track = socket => {
+    sockets.add(socket)
+    socket.on('close', () => sockets.delete(socket))
+    socket.on('error', () => {})
+    socket.setTimeout(30000, () => socket.destroy())
+    return socket
+  }
+  const reject = socket => socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n')
+  const servers = new Map()
+  for (const host of hosts) {
+    const secure = https.createServer({ key: identity.key, cert: identity.cert, ALPNProtocols: ['http/1.1'] }, async (req, res) => {
+      const controller = new AbortController()
+      res.on('close', () => { if (!res.writableEnded) controller.abort() })
+      try {
+        const url = new URL(req.url, `https://${host}`)
+        if (![host, `${host}:443`].includes(req.headers.host?.toLowerCase()) ||
+          url.origin !== `https://${host}` || url.username || url.password || url.hash ||
+          !req.url.startsWith('/') || req.url.startsWith('//') ||
+          !['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
+          res.writeHead(403).end('Proxy request is not allowed.')
+          return
+        }
+        const chunks = []
+        let size = 0
+        for await (const chunk of req) {
+          size += chunk.length
+          if (size > REQUEST_LIMIT) {
+            res.writeHead(413).end('Proxy request exceeds 256 KiB.')
+            return
+          }
+          chunks.push(chunk)
+        }
+        const headers = new Headers()
+        for (const [name, value] of Object.entries(req.headers)) {
+          if (eligibleHeaders(name)) headers.set(name, Array.isArray(value) ? value.join(', ') : value)
+        }
+        const response = await fetch(url.href, {
+          method: req.method,
+          headers,
+          body: ['GET', 'HEAD'].includes(req.method) ? undefined : Buffer.concat(chunks),
+          signal: controller.signal
+        })
+        const output = []
+        let bytes = 0
+        if (response.body) {
+          for await (const chunk of response.body) {
+            bytes += chunk.length
+            if (bytes > RESPONSE_LIMIT) throw new Error('response too large')
+            output.push(Buffer.from(chunk))
+          }
+        }
+        for (const name of RESPONSE_HEADERS) {
+          if (response.headers.has(name)) res.setHeader(name, response.headers.get(name))
+        }
+        res.writeHead(response.status).end(Buffer.concat(output))
+      } catch {
+        if (!res.headersSent) res.writeHead(502)
+        res.end('Proxy request failed.')
+      }
+    })
+    secure.on('secureConnection', track)
+    secure.on('tlsClientError', (_error, socket) => socket.destroy())
+    secure.on('upgrade', (_req, socket) => reject(socket))
+    secure.requestTimeout = 30000
+    secure.headersTimeout = 10000
+    servers.set(host, secure)
+  }
+
+  const server = http.createServer((req, res) => {
+    // Ordinary HTTP is forwarded without injecting any proxy credential.
+    let url
+    try { url = new URL(req.url) } catch { res.writeHead(400).end(); return }
+    if (url.protocol !== 'http:' || url.username || url.password || hosts.has(url.hostname) || self(url)) {
+      res.writeHead(403).end('Proxy request is not allowed.')
+      return
+    }
+    const headers = { ...req.headers, host: url.host }
+    for (const name of ['proxy-authorization', 'proxy-connection', 'connection']) delete headers[name]
+    const upstream = http.request(url, { method: req.method, headers, agent: false }, response => {
+      const responseHeaders = { ...response.headers }
+      delete responseHeaders['proxy-authenticate']
+      res.writeHead(response.statusCode, responseHeaders)
+      response.pipe(res)
+      response.on('error', () => res.destroy())
+    })
+    upstream.on('socket', track)
+    upstream.on('error', () => { if (!res.headersSent) res.writeHead(502); res.end('Proxy request failed.') })
+    res.on('close', () => upstream.destroy())
+    req.pipe(upstream)
+  })
+  function self (url) {
+    return ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) && Number(url.port) === server.address()?.port
+  }
+  server.on('connection', track)
+  server.on('upgrade', (_req, socket) => reject(socket))
+  server.on('connect', (req, socket, head) => {
+    let target
+    try {
+      if (!/^(\[[\da-f:]+\]|[a-z\d.-]+):\d+$/i.test(req.url)) throw new Error('invalid authority')
+      target = new URL(`https://${req.url}`)
+      if (self(target)) throw new Error('proxy loop')
+    } catch { reject(socket); return }
+    if (hosts.has(target.hostname)) {
+      if (target.port && target.port !== '443') { reject(socket); return }
+      socket.write('HTTP/1.1 200 Connection Established\r\n\r\n')
+      if (head.length) socket.unshift(head)
+      servers.get(target.hostname).emit('connection', socket)
+      return
+    }
+    // Unmanaged HTTPS remains end-to-end encrypted through a standard CONNECT tunnel.
+    const upstream = track(net.connect(Number(target.port) || 443, target.hostname.replace(/^\[|\]$/g, '')))
+    upstream.on('connect', () => {
+      socket.write('HTTP/1.1 200 Connection Established\r\n\r\n')
+      if (head.length) upstream.write(head)
+      socket.pipe(upstream).pipe(socket)
+    })
+    upstream.on('error', () => socket.destroy())
+    socket.on('close', () => upstream.destroy())
+    upstream.on('close', () => socket.destroy())
+  })
+  server.requestTimeout = 30000
+  server.headersTimeout = 10000
+  let closed
+  const close = () => {
+    if (!closed) {
+      closed = (async () => {
+        for (const socket of sockets) socket.destroy()
+        await new Promise(resolve => server.close(resolve))
+        fs.rmSync(directory, { recursive: true, force: true })
+      })()
+    }
+    return closed
+  }
+  try {
+    const roots = typeof tls.getCACertificates === 'function' ? tls.getCACertificates('default') : tls.rootCertificates
+    const trust = new Set(roots)
+    const env = config.env || {}
+    for (const name of ['NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'GIT_SSL_CAINFO', 'CARGO_HTTP_CAINFO', 'DENO_CERT']) {
+      if (env[name]) trust.add(fs.readFileSync(env[name], 'utf8'))
+    }
+    trust.add(identity.ca)
+    fs.writeFileSync(caPath, [...trust].join('\n'), { mode: 0o600 })
+    await new Promise((resolve, reject) => {
+      server.once('error', reject)
+      server.listen(0, '127.0.0.1', () => { server.removeListener('error', reject); resolve() })
+    })
+  } catch (error) {
+    await close()
+    throw error
+  }
+  return { proxyUrl: `http://127.0.0.1:${server.address().port}`, caPath, close }
+}

package/src/lib/resolvers/envs.js

@@ -54,10 +54,12 @@ function inject (processEnv, parsed) {
   }
 }
 
-function buildParseOptions ({ processEnv, overload, envKeysFilepath, provider, decryptor }) {
+function buildParseOptions ({ processEnv, overload, envKeysFilepath, provider, decryptor, proxyCredentials, proxyRules }) {
   const options = {
     processEnv,
     overload,
+    proxyCredentials,
+    proxyRules,
     fk: envKeysFilepath
   }
 
@@ -74,7 +76,7 @@ function buildParseOptions ({ processEnv, overload, envKeysFilepath, provider, d
   return options
 }
 
-async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider, decryptor, no1Password, noBitwarden, onStatus }) {
+async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider, decryptor, no1Password, noBitwarden, onStatus, proxyCredentials, proxyRules }) {
   const row = {}
   row.type = TYPE_ENV
   row.string = env.value
@@ -90,7 +92,9 @@ async function injectEnv ({ env, overload, processEnv, envKeysFilepath, provider
       overload,
       envKeysFilepath,
       provider,
-      decryptor
+      decryptor,
+      proxyCredentials,
+      proxyRules
     })
 
     const {
@@ -179,7 +183,7 @@ function injectEnvSync ({ env, overload, processEnv, envKeysFilepath, provider,
   return row
 }
 
-async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, provider, decryptor, readableFilepaths, no1Password, noBitwarden, onStatus }) {
+async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, provider, decryptor, readableFilepaths, no1Password, noBitwarden, onStatus, proxyCredentials, proxyRules }) {
   const row = {}
   row.type = TYPE_ENV_FILE
   row.filepath = env.value
@@ -197,7 +201,9 @@ async function injectEnvFile ({ env, overload, processEnv, envKeysFilepath, prov
       overload,
       envKeysFilepath: fk,
       provider,
-      decryptor
+      decryptor,
+      proxyCredentials,
+      proxyRules
     })
 
     const {
@@ -319,6 +325,8 @@ async function envs (options = {}) {
         readableFilepaths,
         no1Password,
         noBitwarden,
+        proxyCredentials: options.proxyCredentials,
+        proxyRules: options.proxyRules,
         onStatus: options.onStatus
       }))
     } else if (env.type === TYPE_ENV) {
@@ -331,6 +339,8 @@ async function envs (options = {}) {
         decryptor,
         no1Password,
         noBitwarden,
+        proxyCredentials: options.proxyCredentials,
+        proxyRules: options.proxyRules,
         onStatus: options.onStatus
       }))
     }

package/src/lib/resolvers/get.js

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

package/src/lib/services/validate.js

@@ -0,0 +1,58 @@
+const envsResolver = require('../resolvers/envs')
+const Session = require('../../db/session')
+const buildCommandEnvs = require('../helpers/buildCommandEnvs')
+const resolveEnvKeysFile = require('../helpers/resolveEnvKeysFile')
+const readEnvfile = require('../helpers/readEnvfile')
+const validateEnvfile = require('../helpers/validateEnvfile')
+const normalizeDotenvConfigPath = require('../helpers/normalizeDotenvConfigPath')
+const Errors = require('../helpers/errors')
+const { determine } = require('../helpers/envResolution')
+
+// Load once and validate the final values; callers own presentation and execution.
+module.exports = async function validate ({ envs = [], options = {}, processEnv = { ...process.env }, requireEnvfile = true, command, onStatus } = {}) {
+  envs = buildCommandEnvs(normalizeDotenvConfigPath(envs, processEnv), options.convention)
+  envs = determine(envs, processEnv)
+  const schema = readEnvfile(undefined, envs.filter(env => env.type === 'envFile').map(env => env.value))
+  if (requireEnvfile && !schema.exists) throw new Errors().envfileRequired()
+
+  const session = new Session()
+  const proxyToken = options.token || processEnv.DOTENVX_TOKEN
+  const noArmor = options.armor === false || (!proxyToken && (await session.noArmor()))
+  if (schema.proxyRules.size > 0 && noArmor) throw new Error('Envfile proxy requires Armor. Enable Armor and authenticate before running.')
+  const proxyCredentials = noArmor ? undefined : []
+  const { processedEnvs, readableFilepaths } = await envsResolver({
+    envs,
+    proxyRules: schema.proxyRules,
+    proxyCredentials,
+    overload: options.overload,
+    processEnv,
+    envKeysFile: resolveEnvKeysFile(options.envKeysFile),
+    noArmor,
+    noNative: options.native === false || options.noNative === true,
+    no1Password: options['1password'] === false || options.no1Password === true,
+    noBitwarden: options.bitwarden === false || options.noBitwarden === true,
+    token: options.token,
+    command,
+    onStatus
+  })
+
+  let proxyError
+  for (const name of schema.proxyRules.keys()) {
+    if (processEnv[name] !== undefined && !(proxyCredentials || []).some(credential => credential.name === name && credential.placeholder === processEnv[name])) {
+      proxyError = new Error(`Envfile proxy requires an encrypted ${name} loaded from an env file. Remove plaintext or shell overrides, or use --overload.`)
+      break
+    }
+  }
+
+  return {
+    processEnv,
+    processedEnvs,
+    readableFilepaths,
+    hasEnvfile: schema.exists,
+    proxyCredentials,
+    proxyToken,
+    session,
+    proxyError,
+    validationError: validateEnvfile(schema, processEnv, processedEnvs)
+  }
+}

package/src/lib/transforms/set.js

@@ -28,7 +28,7 @@ async function setTransform (options = {}) {
   const fk = options.fk || '.env.keys'
   const noArmor = options.noArmor
   let storage
-  const noKeychain = options.noKeychain
+  const noNative = options.noNative
   const noCreate = options.noCreate
   const noEncrypt = !options.encrypt || isPlainKey(key)
 
@@ -147,7 +147,7 @@ async function setTransform (options = {}) {
           all: true,
           envKeysFile: fk,
           noArmor,
-          noKeychain,
+          noNative,
           no1Password: options.no1Password,
           noBitwarden: options.noBitwarden
         })

package/src/lib/helpers/validateEnvExample.js

@@ -1,24 +0,0 @@
-const fs = require('fs')
-const { scan } = require('@dotenvx/primitives')
-
-const Errors = require('./errors')
-const validate = require('./validate')
-
-function validateEnvExample (env = process.env, options = {}) {
-  const filepath = options.filepath || '.env.example'
-
-  if (!fs.existsSync(filepath)) {
-    return new Errors().missingEnvExample()
-  }
-
-  const exampleSrc = fs.readFileSync(filepath, 'utf8')
-  const { parsed: example, comments } = scan(exampleSrc)
-  const validation = validate(example, env, { comments })
-
-  if (!validation.valid) {
-    const message = validation.errors.map(error => error.message).join('; ')
-    return new Errors({ message }).validationFailed()
-  }
-}
-
-module.exports = validateEnvExample