configorama 1.0.2 → 1.1.0

package/plugins/onepassword/normalize.js

@@ -0,0 +1,145 @@
+/* Normalizes 1Password references into canonical secretRef/item/privateLink forms
+   Validates aliases, parses private item links, rejects public share links */
+
+const ALIAS_PATTERN = /^[A-Za-z0-9_]+$/
+const PRIVATE_LINK_PREFIXES = ['https://start.1password.com/open/i', 'onepassword://open/i']
+
+/**
+ * Validate an alias name from the refs config.
+ * Dots are reserved as the key path separator so they cannot appear in aliases.
+ * @param {string} alias - Alias name to validate
+ */
+function validateAliasName(alias) {
+  if (!ALIAS_PATTERN.test(alias)) {
+    throw new Error(`Invalid 1Password alias "${alias}". Aliases may contain only letters, numbers, and underscores.`)
+  }
+}
+
+/**
+ * Check whether a string is a private item link.
+ * @param {string} value - Candidate string
+ * @returns {boolean} True when the string is a private item link
+ */
+function isPrivateLink(value) {
+  return PRIVATE_LINK_PREFIXES.some((prefix) => value.startsWith(prefix))
+}
+
+/**
+ * Recognize abbreviated private-link forms where the scheme, host, and/or
+ * path have been stripped, leaving the query params (e.g. "open/i?...&i=ID",
+ * or a bare "v=VAULT&i=ID"). Requires an "i=" param plus a 1Password marker
+ * or a pure query string, so ordinary item names and unrelated URLs are not
+ * misread as links.
+ * @param {string} value - Candidate string
+ * @returns {boolean} True when the string looks like private-link query params
+ */
+function looksLikeLinkParams(value) {
+  const query = value.includes('?') ? value.slice(value.indexOf('?') + 1) : value
+  if (!/(?:^|&)i=[^&]/.test(query)) return false
+  return /1password\.com/.test(value) || /(?:^|\/)open\/i/.test(value) || !value.includes('/')
+}
+
+/**
+ * Parse a "Copy Private Link" URL (or an abbreviated form) into item and
+ * vault IDs. The a (account) and h (host) params identify the account and are
+ * intentionally dropped; item + vault IDs are all op item get needs.
+ * @param {string} url - Private item link or its query params
+ * @returns {{kind: string, item: string, vault: string|undefined, warnings: Array<{code: string, message: string}>}} Normalized reference
+ */
+function parsePrivateLink(url) {
+  const query = url.includes('?') ? url.slice(url.indexOf('?') + 1) : url
+  const params = new URLSearchParams(query)
+  const item = params.get('i')
+  const vault = params.get('v')
+
+  if (!item) {
+    throw new Error('Invalid 1Password private link. Expected query parameter "i" with the item ID.')
+  }
+
+  const warnings = []
+  if (!vault) {
+    warnings.push({
+      level: 'warning',
+      code: 'op_private_link_missing_vault',
+      message: '1Password private link did not include a vault ID; service accounts and duplicate item names may require vault scoping.',
+    })
+  }
+
+  return { kind: 'privateLink', item, vault: vault || undefined, warnings }
+}
+
+/**
+ * Normalize a string or object ref value into a canonical reference.
+ * Accepted forms: op:// string, item name string, private link string,
+ * { item, vault, section, field }, { ref }, { url }.
+ * @param {string|object} value - Ref value from config or direct spec
+ * @returns {object} Normalized reference ({ kind: 'secretRef'|'item'|'privateLink', ... })
+ */
+function normalizeRefValue(value) {
+  if (typeof value === 'string') {
+    return normalizeStringRef(value)
+  }
+  if (value && typeof value === 'object') {
+    return normalizeObjectRef(value)
+  }
+  throw new Error(`Invalid 1Password reference. Expected a string or object, got ${typeof value}.`)
+}
+
+/**
+ * @param {string} value - String ref (secret ref, link, or item name)
+ * @returns {object} Normalized reference
+ */
+function normalizeStringRef(value) {
+  if (value.startsWith('op://')) {
+    return { kind: 'secretRef', ref: value }
+  }
+  // Public share links are rejected in any form (full URL or share token).
+  if (value.includes('share.1password.com') || /1password\.com\/s#/.test(value)) {
+    throw new Error('Public 1Password share links are not supported. Use Copy Private Link or an op:// secret reference.')
+  }
+  // Private links: full URL, onepassword://, or an abbreviated form carrying
+  // the query params (scheme/host/path stripped).
+  if (isPrivateLink(value) || looksLikeLinkParams(value)) {
+    return parsePrivateLink(value)
+  }
+  if (/^https?:\/\/|^onepassword:\/\//.test(value)) {
+    throw new Error('Unrecognized 1Password link. Use Copy Private Link or an op:// secret reference.')
+  }
+  return { kind: 'item', item: value, vault: undefined, section: undefined, field: undefined }
+}
+
+/**
+ * @param {object} value - Object ref ({ item }, { ref }, or { url })
+ * @returns {object} Normalized reference
+ */
+function normalizeObjectRef(value) {
+  const specifiers = ['item', 'ref', 'url'].filter((key) => value[key] !== undefined)
+  if (specifiers.length !== 1) {
+    throw new Error('Invalid 1Password reference. Object refs must specify exactly one of "item", "ref", or "url".')
+  }
+
+  if (value.ref !== undefined) {
+    return normalizeStringRef(value.ref)
+  }
+  if (value.url !== undefined) {
+    const normalized = normalizeStringRef(value.url)
+    if (normalized.kind !== 'privateLink') {
+      throw new Error('Invalid 1Password reference. "url" must be a private item link.')
+    }
+    return normalized
+  }
+
+  if (value.section !== undefined && value.field === undefined) {
+    throw new Error('Invalid 1Password reference. "section" is only meaningful together with "field".')
+  }
+
+  return {
+    kind: 'item',
+    item: value.item,
+    vault: value.vault,
+    section: value.section,
+    field: value.field,
+  }
+}
+
+module.exports = { validateAliasName, normalizeRefValue, parsePrivateLink, isPrivateLink }

package/plugins/onepassword/op-cli.js

@@ -0,0 +1,117 @@
+/* Executes the 1Password CLI with execFile and sanitized error translation
+   Never logs stdout/stderr; never passes resolved secret values as arguments */
+const childProcess = require('child_process')
+
+const AUTH_ERROR_PATTERN = /sign ?in|session|authoriz|authenticat|not currently signed|locked|service account token/i
+const NOT_FOUND_PATTERN = /isn'?t an? (item|vault)|not found|no item|no vault|doesn'?t exist|more than one item/i
+
+/**
+ * Run the op binary with the given args.
+ * No `command -v op` preflight: translating ENOENT is the existence check.
+ * @param {string[]} args - CLI arguments
+ * @param {object} [options] - { execFile, opPath, account, configDir, subject }
+ * @returns {Promise<string>} stdout
+ */
+function runOp(args, options = {}) {
+  const execFile = options.execFile || childProcess.execFile
+  const binary = options.opPath || 'op'
+  const finalArgs = args.slice()
+  if (options.account) {
+    finalArgs.push('--account', options.account)
+  }
+  if (options.configDir) {
+    finalArgs.push('--config', options.configDir)
+  }
+
+  return new Promise((resolve, reject) => {
+    execFile(binary, finalArgs, { maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        return reject(translateError(err, stderr, options.subject))
+      }
+      resolve(stdout)
+    })
+  })
+}
+
+/**
+ * Translate op failures into sanitized, actionable errors.
+ * stderr is inspected for classification but never included in messages.
+ * @param {Error & {code?: string|number}} err - execFile error
+ * @param {string} stderr - Captured stderr (classification only)
+ * @param {string} [subject] - Item/ref identifier already present in user config
+ * @returns {Error} Sanitized error
+ */
+function translateError(err, stderr, subject) {
+  if (err.code === 'ENOENT') {
+    return new Error('1Password CLI "op" was not found on PATH. Install 1Password CLI or remove the op resolver.')
+  }
+  const detail = String(stderr || err.message || '')
+  if (AUTH_ERROR_PATTERN.test(detail)) {
+    return new Error('1Password CLI could not read the item. Run op signin, unlock 1Password app integration, or configure OP_SERVICE_ACCOUNT_TOKEN.')
+  }
+  if (NOT_FOUND_PATTERN.test(detail)) {
+    const what = subject ? `"${subject}"` : 'the requested item, vault, or field'
+    return new Error(`1Password item, vault, or field could not be found (${what}).`)
+  }
+  return new Error('1Password CLI command failed.')
+}
+
+/**
+ * Reject config-controlled values that would be parsed as an op flag.
+ * execFile takes no shell, so this is not command injection - but a
+ * leading "-" turns a positional/vault value into an option that changes
+ * op's behavior. Secret refs are exempt: they always start with "op://".
+ * @param {string} value - Value destined for the op argument list
+ * @param {string} label - Human label for the error message
+ */
+function assertNotFlag(value, label) {
+  if (typeof value === 'string' && value.startsWith('-')) {
+    throw new Error(`Invalid 1Password ${label} "${value}": ${label} cannot start with "-" (it would be read as an op flag). Use the item ID or an op:// secret reference.`)
+  }
+}
+
+/**
+ * Read a secret reference with op read.
+ * @param {string} ref - op://vault/item/field reference
+ * @param {object} [options] - { execFile, account, configDir }
+ * @returns {Promise<string>} Secret value
+ */
+function readSecretRef(ref, options = {}) {
+  return runOp(['read', '--no-newline', ref], {
+    execFile: options.execFile,
+    opPath: options.opPath,
+    account: options.account,
+    configDir: options.configDir,
+    subject: ref,
+  })
+}
+
+/**
+ * Fetch an item as JSON with op item get.
+ * --reveal is required to include concealed field values in the JSON.
+ * @param {string} spec - Item ID or item name
+ * @param {object} [options] - { execFile, account, configDir, vault }
+ * @returns {Promise<object>} Parsed item JSON
+ */
+async function getItem(spec, options = {}) {
+  assertNotFlag(spec, 'item')
+  const args = ['item', 'get', spec, '--format', 'json', '--reveal']
+  if (options.vault) {
+    assertNotFlag(options.vault, 'vault')
+    args.push('--vault', options.vault)
+  }
+  const stdout = await runOp(args, {
+    execFile: options.execFile,
+    opPath: options.opPath,
+    account: options.account,
+    configDir: options.configDir,
+    subject: spec,
+  })
+  try {
+    return JSON.parse(stdout)
+  } catch (err) {
+    throw new Error(`Could not parse 1Password CLI output as JSON for item "${spec}".`)
+  }
+}
+
+module.exports = { runOp, readSecretRef, getItem }

package/plugins/onepassword/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "configorama-onepassword",
+  "version": "0.1.0",
+  "description": "1Password variable source plugin for configorama",
+  "main": "index.js",
+  "scripts": {
+    "test": "node parser.test.js && node normalize.test.js && node op-cli.test.js && node fields.test.js && node index.test.js && node smoke.test.js"
+  },
+  "keywords": [
+    "configorama",
+    "1password",
+    "secrets"
+  ],
+  "license": "MIT"
+}

package/plugins/onepassword/parser.js

@@ -0,0 +1,70 @@
+/* Parses 1Password field text as INI/dotenv for key path reads
+   Raw field text is only parsed when a config reference asks for a key path */
+const ini = require('ini')
+
+/**
+ * Restore ini module coercions so secret values stay strings.
+ * The ini parser coerces true/false/null which corrupts literal
+ * secret text like FLAG=true.
+ * @param {*} value - Parsed ini node
+ * @returns {*} Node with primitives restored to strings
+ */
+function stringifyPrimitives(value) {
+  if (value === true) return 'true'
+  if (value === false) return 'false'
+  if (value === null) return 'null'
+  if (typeof value === 'object') {
+    const result = {}
+    for (const key of Object.keys(value)) {
+      result[key] = stringifyPrimitives(value[key])
+    }
+    return result
+  }
+  return value
+}
+
+/**
+ * Parse structured secret text.
+ * V1 supports INI/dotenv only. Future format detection order:
+ * 1. explicit format option on the ref
+ * 2. JSON if the trimmed value starts with { or [
+ * 3. YAML only with proof it is not confused with INI
+ * 4. INI fallback
+ * @param {string} value - Raw field text
+ * @param {object} [options] - Reserved for future format selection
+ * @returns {object} Parsed key/value structure
+ */
+function parseStructuredSecret(value, options = {}) {
+  let parsed
+  try {
+    parsed = ini.parse(value)
+  } catch (err) {
+    throw new Error(`Could not parse 1Password field "${options.fieldName || 'value'}" as INI/dotenv.`)
+  }
+  return stringifyPrimitives(parsed)
+}
+
+/**
+ * Read a dot-separated key path from a parsed structure.
+ * Error messages never include secret values.
+ * @param {object} parsed - Result of parseStructuredSecret
+ * @param {string} keyPath - Dot-separated path, e.g. "database.password"
+ * @param {string} fieldName - 1Password field name for error messages
+ * @returns {string} Selected value
+ */
+function getKeyPath(parsed, keyPath, fieldName) {
+  const segments = keyPath.split('.')
+  let current = parsed
+  for (const segment of segments) {
+    if (current === null || typeof current !== 'object' || !(segment in current)) {
+      throw new Error(`Key path "${keyPath}" was not found in 1Password field "${fieldName}".`)
+    }
+    current = current[segment]
+  }
+  if (typeof current === 'object') {
+    throw new Error(`Key path "${keyPath}" was not found in 1Password field "${fieldName}".`)
+  }
+  return current
+}
+
+module.exports = { parseStructuredSecret, getKeyPath }

package/plugins/onepassword/sync-factory.js

@@ -0,0 +1,15 @@
+/* Factory entry for configorama.sync() workers
+   Rebuilds the 1Password resolver from JSON-serializable options inside the sync worker */
+const createOnePasswordResolver = require('./index')
+
+/**
+ * @param {object} options - JSON-round-tripped syncOptions ({ refs, account, configDir, skipResolution })
+ * @returns {object} Variable source
+ */
+module.exports = function createSyncOnePasswordResolver(options = {}) {
+  if (options.hasInjectedExecFile) {
+    throw new Error('1Password resolver options are not serializable for sync usage. Remove the injected execFile or use the async API.')
+  }
+  const { hasInjectedExecFile, ...factoryOptions } = options
+  return createOnePasswordResolver(factoryOptions)
+}

package/src/index.js

@@ -163,7 +163,14 @@ module.exports.audit = async (configPathOrObject, settings = {}) => {
   const requirements = buildConfigRequirements(analysis)
   const introspection = buildIntrospection(analysis, { requirements })
   const customResolvers = Array.isArray(settings.variableSources)
-    ? settings.variableSources.map(source => source.type).filter(Boolean)
+    ? settings.variableSources
+      .filter(source => source.type)
+      .map(source => ({
+        type: source.type,
+        sensitive: source.sensitive,
+        risk: source.risk,
+        description: source.description,
+      }))
     : []
   const originalConfig = analysis.originalConfig || {}
   return buildAuditReport(introspection, {

package/src/main.js

@@ -92,6 +92,7 @@ const { mergeByKeys } = require('./utils/parsing/mergeByKeys')
 const { arrayToJsonPath } = require('./utils/parsing/arrayToJsonPath')
 /* Utils - paths */
 const { findLineByPath } = require('./utils/paths/findLineForKey')
+const { configFileType } = require('./utils/paths/fileType')
 const { normalizeIgnorePaths, compileIgnorePaths, shouldIgnorePath } = require('./utils/paths/ignorePaths')
 /* Utils - regex */
 const { combineRegexes, funcRegex, fileRefSyntax, textRefSyntax } = require('./utils/regex')
@@ -2574,8 +2575,8 @@ Missing Value ${missingValue} - ${matchedString}
           if (valueCount.length === 1 && noNestedVars) {
             let lineInfo = ''
             if (this.originalString && this.configFilePath && valueObject.path) {
-              const ext = path.extname(this.configFilePath)
-              if (ext === '.yml' || ext === '.yaml' || ext === '.json') {
+              const ext = configFileType(this.configFilePath)
+              if (ext === '.yml' || ext === '.yaml' || ext === '.json' || ext === '.env') {
                 const rawLines = this.originalString.split('\n')
                 const lineNum = findLineByPath(arrayToJsonPath(valueObject.path), rawLines, ext)
                 if (lineNum) lineInfo = ` at line ${lineNum},`
@@ -3049,7 +3050,9 @@ Missing Value ${missingValue} - ${matchedString}
   // ###############
   initialCall(func) {
     this.deep = []
-    this.tracker.start()
+    // Progress reporting is a debug-only aid; the tracker still coordinates
+    // promises and detects cycles regardless.
+    this.tracker.start(DEBUG)
     return func().finally(() => {
       this.tracker.stop()
       this.deep = []

package/src/parsers/dotenv.js

@@ -0,0 +1,13 @@
+// Parses .env file contents into a flat key/value object
+// Values keep their raw text so configorama can resolve ${...} references in them
+const dotenv = require('dotenv')
+
+/**
+ * @param {string} contents - Raw .env file text
+ * @returns {Object} Flat map of KEY -> raw string value
+ */
+function parse(contents) {
+  return dotenv.parse(contents)
+}
+
+module.exports = { parse }

package/src/resolvers/valueFromFile.js

@@ -266,7 +266,8 @@ Default fallback value will be used if provided.
 
 ${JSON.stringify(options.context, null, 2)}`,
       })
-      console.log(errorMsg)
+      // Diagnostic goes to stderr so it never pollutes resolved-config stdout
+      console.error(errorMsg)
     }
     // TODO maybe reject. YAML does not allow for null/undefined values
     // return Promise.reject(new Error(errorMsg))

package/src/sync.js

@@ -9,6 +9,21 @@ const enrichMetadata = require('./utils/parsing/enrichMetadata')
  */
 module.exports = function configoramaSync(variableSources = []) {
   const customVariableSources = variableSources.map((varSrc) => {
+    /* Plugin factories: match/resolver do not survive the JSON trip through
+       sync-rpc, so plugins carry a syncFactory path + JSON syncOptions and
+       the real source is rebuilt here inside the worker process */
+    if (varSrc.syncFactory) {
+      const factoryPath = getFullPath(varSrc.syncFactory)
+      if (!fs.existsSync(factoryPath)) {
+        throw new Error(`Sync factory missing. Can't find ${factoryPath}`)
+      }
+      const createSource = require(factoryPath)
+      if (typeof createSource !== 'function') {
+        throw new Error(`Sync factory must export a function. Check ${factoryPath}`)
+      }
+      return createSource(varSrc.syncOptions || {})
+    }
+
     if (!varSrc.match || typeof varSrc.match !== 'string') {
       throw new Error('Variable source must be string for .sync usage')
     }
@@ -67,6 +82,18 @@ module.exports = function configoramaSync(variableSources = []) {
         instance.variableTypes
       )
 
+      /* Collect custom metadata from worker-side sources, mirroring the
+         collectMetadata loop the async API runs in src/index.js */
+      for (const source of customVariableSources) {
+        if (typeof source.collectMetadata === 'function') {
+          const customData = source.collectMetadata()
+          if (customData !== undefined && customData !== null) {
+            const metadataKey = source.metadataKey || `${source.type}References`
+            enrichedMetadata[metadataKey] = customData
+          }
+        }
+      }
+
       return {
         variableSyntax: instance.variableSyntax,
         variableTypes: instance.variableTypes,

package/src/utils/PromiseTracker.js

@@ -13,15 +13,21 @@ class PromiseTracker {
     this.startTime = Date.now()
     this.cursor = 0
   }
-  start() {
+  start(enableProgress = false) {
     this.reset()
-    this.interval = setInterval(this.report.bind(this), 2500)
+    // The tracker's job is cycle detection and promise coordination; the
+    // periodic progress report is a debug-only aid, off unless requested.
+    if (enableProgress) {
+      this.interval = setInterval(this.report.bind(this), 2500)
+    }
   }
   report() {
     const delta = Date.now() - this.startTime
     const pending = this.getPending()
     const dots = dotDotDot(this.cursor++, 100, '...')
-    console.log([
+    // Diagnostic progress goes to stderr so it never pollutes stdout (resolved
+    // config output, or `configx --export` lines consumed by eval).
+    console.error([
       `Fetching Async values${dots}`,
     ].concat(
       pending.map((promise) => `- ${promise.waitList}`)
@@ -40,7 +46,8 @@ class PromiseTracker {
     /**/
   }
   stop() {
-    clearInterval(this.interval)
+    if (this.interval) clearInterval(this.interval)
+    this.interval = null
     this.reset()
   }
   add(variable, promise, specifier, hasFilter, promiseKey) {

package/src/utils/PromiseTracker.test.js

@@ -0,0 +1,48 @@
+/* Tests that resolution progress output goes to stderr, not stdout */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const PromiseTracker = require('./PromiseTracker')
+
+test('start() does not enable progress logging by default', () => {
+  const tracker = new PromiseTracker()
+  tracker.start()
+  const hasInterval = !!tracker.interval
+  tracker.stop()
+  assert.is(hasInterval, false, 'no interval timer unless progress is requested')
+})
+
+test('start(true) enables the progress interval; stop() clears it', () => {
+  const tracker = new PromiseTracker()
+  tracker.start(true)
+  assert.ok(tracker.interval, 'interval set when progress requested')
+  tracker.stop()
+  assert.is(tracker.interval, null, 'interval cleared on stop')
+})
+
+test('report() writes progress to stderr, not stdout', () => {
+  const tracker = new PromiseTracker()
+  const pending = Promise.resolve()
+  tracker.add('${op(a?x=1&y=2)}', pending, '${op(a?x=1&y=2)}')
+  // add() attaches a .then that flips state to resolved on next tick; force pending
+  tracker.promiseList[0].state = 'pending'
+
+  const outLines = []
+  const errLines = []
+  const origLog = console.log
+  const origErr = console.error
+  console.log = (...args) => outLines.push(args.join(' '))
+  console.error = (...args) => errLines.push(args.join(' '))
+  try {
+    tracker.report()
+  } finally {
+    console.log = origLog
+    console.error = origErr
+  }
+
+  assert.is(outLines.length, 0, 'nothing on stdout')
+  assert.ok(errLines.some((line) => line.includes('Fetching Async values')), 'progress on stderr')
+  // the pending variable (with & in it) must not leak to stdout
+  assert.ok(outLines.every((line) => !line.includes('&')))
+})
+
+test.run()

package/src/utils/introspection/audit.js

@@ -41,15 +41,11 @@ function buildAuditReport(introspection, options = {}) {
   }
 
   if (options.customResolvers && options.customResolvers.length) {
-    for (const resolver of options.customResolvers.slice().sort()) {
-      findings.push({
-        id: `customResolver:${resolver}`,
-        severity: 'high',
-        risk: 'custom_extension',
-        kind: 'source',
-        variableType: resolver,
-        message: `Custom resolver "${resolver}" can execute user-provided code.`,
-      })
+    const sorted = options.customResolvers.slice().sort((a, b) => {
+      return String(a.type || a).localeCompare(String(b.type || b))
+    })
+    for (const resolver of sorted) {
+      findings.push(customResolverFinding(resolver))
     }
   }
 
@@ -70,6 +66,40 @@ function buildAuditReport(introspection, options = {}) {
   }
 }
 
+/**
+ * Build the audit finding for one custom resolver.
+ * Resolvers that self-describe as sensitive/risky get a specific finding
+ * instead of the generic custom_extension one - never both.
+ * @param {string|{type: string, sensitive?: boolean, risk?: string, description?: string}} resolver
+ * @returns {object} Audit finding
+ */
+function customResolverFinding(resolver) {
+  const source = typeof resolver === 'string' ? { type: resolver } : resolver
+  const { type, sensitive, risk, description } = source
+
+  if (sensitive === true || risk) {
+    const finding = {
+      id: `customResolver:${type}`,
+      severity: 'high',
+      risk: risk || 'custom_extension',
+      kind: 'source',
+      variableType: type,
+      message: `Custom resolver "${type}" reads secret values.${description ? ` ${description}.` : ''}`,
+    }
+    if (sensitive === true) finding.sensitive = true
+    return finding
+  }
+
+  return {
+    id: `customResolver:${type}`,
+    severity: 'high',
+    risk: 'custom_extension',
+    kind: 'source',
+    variableType: type,
+    message: `Custom resolver "${type}" can execute user-provided code.`,
+  }
+}
+
 function messageForNode(node) {
   if (node.risk === 'executable_code') return 'Reference may execute JavaScript or TypeScript.'
   if (node.risk === 'process_spawn') return 'Reference may spawn a git process.'

package/src/utils/parsing/parse.js

@@ -4,8 +4,10 @@ const path = require('path')
 const YAML = require('../../parsers/yaml')
 const TOML = require('../../parsers/toml')
 const INI = require('../../parsers/ini')
+const DOTENV = require('../../parsers/dotenv')
 const JSON5 = require('../../parsers/json5')
 const HCL = require('../../parsers/hcl')
+const { isEnvFile } = require('../paths/fileType')
 const { executeTypeScriptFileSync } = require('../../parsers/typescript')
 const { executeESMFileSync } = require('../../parsers/esm')
 const cloudFormationSchema = require('./cloudformationSchema')
@@ -72,8 +74,12 @@ function detectFormat(contents) {
 function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
   let fileType = path.extname(filePath)
 
-  // Content-based detection for extensionless or unrecognized files
-  if (!fileType || !KNOWN_EXTENSIONS.has(fileType.toLowerCase())) {
+  // Dotenv files have no extension (path.extname('.env') === ''), so detect
+  // them by name before falling back to content sniffing.
+  if (isEnvFile(filePath)) {
+    fileType = '.env'
+  } else if (!fileType || !KNOWN_EXTENSIONS.has(fileType.toLowerCase())) {
+    // Content-based detection for extensionless or unrecognized files
     fileType = detectFormat(contents)
   }
 
@@ -105,6 +111,8 @@ function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
     configObject = TOML.parse(contents)
   } else if (fileType.match(/\.(ini)/i)) {
     configObject = INI.parse(contents)
+  } else if (fileType === '.env') {
+    configObject = DOTENV.parse(contents)
   } else if (fileType.match(/\.(json|json5|jsonc)/i)) {
     configObject = JSON5.parse(contents)
   } else if (fileType.match(/\.(tf|hcl)$/i) || filePath.match(/\.tf\.json$/i)) {