configorama 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",

package/src/metadata.js

@@ -9,6 +9,7 @@ const { normalizePath, extractFilePath, resolveInnerVariables } = require('./uti
 const { shouldIgnorePath } = require('./utils/paths/ignorePaths')
 const { findNestedVariables } = require('./utils/variables/findNestedVariables')
 const { splitOnPipe } = require('./utils/strings/splitOnPipe')
+const { applyDotenvFileRefMetadata } = require('./utils/security/dotenvFileRefs')
 
 /**
  * Collect metadata about all variables found in the configuration
@@ -329,6 +330,12 @@ function collectVariableMetadata({
               containsVariables,
               exists: fileExists,
             }
+            applyDotenvFileRefMetadata(configPathEntry, {
+              filePath: absolutePath,
+              relativePath: resolvedPath,
+              originalVariableString: rawValue,
+              resolvedVariableString: resolvedVarString,
+            })
             if (globPattern) {
               configPathEntry.pattern = globPattern
             }

package/src/resolvers/valueFromFile.js

@@ -9,6 +9,7 @@ const { findNestedVariables } = require('../utils/variables/findNestedVariables'
 const { makeBox } = require('@davidwells/box-logger')
 const { encodeJsSyntax, decodeJsonInVariable, hasEncodedJson } = require('../utils/encoders/js-fixes')
 const { checkFileAccess } = require('../utils/security/safetyPolicy')
+const { applyDotenvFileRefMetadata, isIniLikeFilePath } = require('../utils/security/dotenvFileRefs')
 
 /* File Parsers */
 const YAML = require('../parsers/yaml')
@@ -85,7 +86,7 @@ function parseFileContents(content, filePath) {
   if (ext === 'toml' || ext === 'tml') {
     return TOML.parse(content)
   }
-  if (isIniLikeExtension(ext)) {
+  if (isIniLikeExtension(ext, filePath)) {
     return INI.parse(content)
   }
 
@@ -93,8 +94,8 @@ function parseFileContents(content, filePath) {
   return content
 }
 
-function isIniLikeExtension(ext) {
-  return ext === 'ini' || ext === 'env'
+function isIniLikeExtension(ext, filePath) {
+  return ext === 'ini' || ext === 'env' || isIniLikeFilePath(filePath)
 }
 
 /**
@@ -205,6 +206,14 @@ async function getValueFromFile(ctx, variableString, options) {
     containsVariables: options.context.value !== options.context.originalSource,
     exists,
   }
+  applyDotenvFileRefMetadata(fileRefEntry, {
+    filePath: fullFilePath,
+    relativePath,
+    resolvedPath,
+    variableString,
+    originalVariableString: options.context.originalSource,
+    resolvedVariableString: options.context.value,
+  })
 
   if (wasOverridden) {
     fileRefEntry.wasOverridden = true
@@ -411,7 +420,7 @@ ${JSON.stringify(options.context, null, 2)}`,
       if (fileExtension === 'toml' || fileExtension === 'tml') {
         valueToPopulate = JSON.stringify(TOML.parse(valueToPopulate))
       }
-      if (isIniLikeExtension(fileExtension)) {
+      if (isIniLikeExtension(fileExtension, relativePath)) {
         valueToPopulate = INI.toJson(valueToPopulate)
       }
       if (fileExtension === 'tf' || fileExtension === 'hcl') {
@@ -451,7 +460,7 @@ Please use ":" or "." to reference sub properties. ${deepPropertiesStr}`
       return Promise.resolve(valueToPopulate)
     }
 
-    if (isIniLikeExtension(fileExtension)) {
+    if (isIniLikeExtension(fileExtension, relativePath)) {
       valueToPopulate = INI.parse(valueToPopulate)
       return Promise.resolve(valueToPopulate)
     }

package/src/utils/introspection/audit.js

@@ -12,7 +12,7 @@ function buildAuditReport(introspection, options = {}) {
 
   for (const node of introspection.nodes || []) {
     if (!node.risk || node.risk === 'none') continue
-    findings.push({
+    const finding = {
       id: node.id,
       severity: node.severity || severityForRisk(node.risk),
       risk: node.risk,
@@ -22,7 +22,12 @@ function buildAuditReport(introspection, options = {}) {
       relativePath: node.relativePath,
       configPaths: node.paths || [],
       message: messageForNode(node),
-    })
+    }
+    if (node.sensitive === true) finding.sensitive = true
+    if (node.sensitivityReason) finding.sensitivityReason = node.sensitivityReason
+    if (node.dotenvFile !== undefined) finding.dotenvFile = node.dotenvFile
+    if (node.dotenvReadScope) finding.dotenvReadScope = node.dotenvReadScope
+    findings.push(finding)
   }
 
   if (options.dotenv === true) {
@@ -68,6 +73,8 @@ function buildAuditReport(introspection, options = {}) {
 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.'
+  if (node.sensitivityReason === 'dotenv_file' && node.dotenvReadScope === 'full_file') return 'Reference reads an entire dotenv file; resolved output may contain secrets.'
+  if (node.sensitivityReason === 'dotenv_file') return 'Reference reads a key from a dotenv file.'
   if (node.risk === 'local_file_read') return 'Reference reads a local file.'
   if (node.risk === 'data_flow_expression') return 'Expression can read resolved config values but is not JavaScript execution.'
   return `Risk surface: ${node.risk}`

package/src/utils/introspection/model.js

@@ -1,6 +1,7 @@
 const path = require('path')
 const { EXECUTABLE_EXTENSIONS } = require('../security/safetyPolicy')
 const { redactRequirementValue } = require('../redaction/redact')
+const { getDotenvFileRefMetadata } = require('../security/dotenvFileRefs')
 
 const SCHEMA_VERSION = 1
 
@@ -42,6 +43,25 @@ function severityForRisk(risk) {
   return 'info'
 }
 
+function severityForNode(risk, metadata) {
+  if (metadata && metadata.dotenvFile && metadata.dotenvReadScope === 'full_file') return 'medium'
+  return severityForRisk(risk)
+}
+
+function firstOccurrenceVariable(entry) {
+  const occurrence = entry && Array.isArray(entry.occurrences) ? entry.occurrences[0] : null
+  return occurrence ? (occurrence.varMatch || occurrence.originalString) : null
+}
+
+function assignSensitivity(target, metadata) {
+  if (!metadata) return target
+  if (metadata.sensitive === true) target.sensitive = true
+  if (metadata.sensitivityReason) target.sensitivityReason = metadata.sensitivityReason
+  if (metadata.dotenvFile !== undefined) target.dotenvFile = metadata.dotenvFile
+  if (metadata.dotenvReadScope) target.dotenvReadScope = metadata.dotenvReadScope
+  return target
+}
+
 function buildIntrospection(enrichedMetadata = {}, options = {}) {
   const uniqueVariables = enrichedMetadata.uniqueVariables || {}
   const requirements = options.requirements || []
@@ -55,6 +75,11 @@ function buildIntrospection(enrichedMetadata = {}, options = {}) {
     const variableType = normalizeVariableType(entry.variableType)
     const requirement = requirementsByVariable.get(variable)
     const risk = riskForVariable(variableType, variable)
+    const dotenvMetadata = getDotenvFileRefMetadata({
+      ...entry,
+      variable,
+      originalVariableString: firstOccurrenceVariable(entry),
+    })
     const node = {
       id: `variable:${variable}`,
       kind: variableType === 'file' || variableType === 'text'
@@ -64,10 +89,11 @@ function buildIntrospection(enrichedMetadata = {}, options = {}) {
       variableType,
       sourceClass: entry.variableSourceType || entry.sourceClass || requirement?.sourceClass || null,
       risk,
-      severity: severityForRisk(risk),
+      severity: severityForNode(risk, dotenvMetadata || entry),
       paths: [...new Set((entry.occurrences || []).map(occ => occ.path).filter(Boolean))].sort(),
-      sensitive: requirement ? requirement.sensitive === true : false,
+      sensitive: requirement ? requirement.sensitive === true : entry.sensitive === true,
     }
+    assignSensitivity(node, dotenvMetadata || entry)
     if (requirement) {
       node.required = requirement.required
       node.default = redactRequirementValue(requirement, requirement.default)
@@ -104,16 +130,20 @@ function buildIntrospection(enrichedMetadata = {}, options = {}) {
   const fileDeps = enrichedMetadata.fileDependencies || {}
   for (const dep of fileDeps.byConfigPath || []) {
     const id = `file:${dep.relativePath || dep.filePath}`
+    const dotenvMetadata = getDotenvFileRefMetadata(dep)
+    const risk = EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'executable_code' : 'local_file_read'
     if (!nodes.some(node => node.id === id)) {
-      nodes.push({
+      const node = {
         id,
         kind: EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'executable' : 'file',
         path: dep.filePath,
         relativePath: dep.relativePath,
         exists: dep.exists,
-        risk: EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'executable_code' : 'local_file_read',
-        severity: EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'high' : 'low',
-      })
+        risk,
+        severity: severityForNode(risk, dotenvMetadata || dep),
+      }
+      assignSensitivity(node, dotenvMetadata || dep)
+      nodes.push(node)
     }
     if (dep.location) {
       edges.push({

package/src/utils/parsing/enrichMetadata.js

@@ -5,6 +5,7 @@ const { normalizePath, extractFilePath, normalizeFileVariable, resolveInnerVaria
 const { preResolveString, preResolveSingle } = require('../resolution/preResolveVariable')
 const { parseOneOfFilter } = require('../filters/oneOf')
 const { extractComment } = require('./extractComment')
+const { applyDotenvFileRefMetadata, normalizeDotenvFileVariable } = require('../security/dotenvFileRefs')
 
 // Type filters that indicate expected value types
 const TYPE_FILTERS = ['Boolean', 'String', 'Number', 'Array', 'Object', 'Json']
@@ -109,6 +110,12 @@ function getSourceForType(variableType, variableTypes) {
   return typeDef?.source
 }
 
+function sameFileRefPath(left, right) {
+  if (!left || !right) return false
+  const normalize = value => String(value).replace(/^\.\//, '')
+  return normalize(left) === normalize(right)
+}
+
 /**
  * Enriches variable metadata with resolution tracking data.
  * @param {object} metadata - The metadata object from collectVariableMetadata.
@@ -388,6 +395,7 @@ async function enrichMetadata(
             containsVariables: !!ref.hasInnerVariable,
             exists: details.exists,
           }
+          applyDotenvFileRefMetadata(confDetails, details)
           if (ref.pattern) {
             confDetails.pattern = ref.pattern
           }
@@ -478,7 +486,7 @@ async function enrichMetadata(
     }
 
     // Normalize file() and text() references
-    baseVar = normalizeFileVariable(baseVar)
+    baseVar = normalizeDotenvFileVariable(baseVar) || normalizeFileVariable(baseVar)
 
     if (!uniqueVariablesMap.has(baseVar)) {
       uniqueVariablesMap.set(baseVar, {
@@ -536,7 +544,7 @@ async function enrichMetadata(
             const siblingBaseVar = detail.valueBeforeFallback || detail.variable
 
             // Normalize file/text references for sibling too
-            const normalizedSiblingVar = normalizeFileVariable(siblingBaseVar)
+            const normalizedSiblingVar = normalizeDotenvFileVariable(siblingBaseVar) || normalizeFileVariable(siblingBaseVar)
 
             // Create or get entry for this sibling variable
             if (!uniqueVariablesMap.has(normalizedSiblingVar)) {
@@ -665,7 +673,7 @@ async function enrichMetadata(
         }
 
         // Normalize file paths after variable substitution
-        resolvedVariable = normalizeFileVariable(resolvedVariable)
+        resolvedVariable = normalizeDotenvFileVariable(resolvedVariable) || normalizeFileVariable(resolvedVariable)
 
         // Update the variable to the resolved version and update map key
         if (resolvedVariable !== baseVar) {
@@ -712,13 +720,22 @@ async function enrichMetadata(
 
         if (!hasVariables) {
           // Look up in fileRefsFound to see if file exists
-          const fileRef = fileRefsFound.find(ref => ref.relativePath === filePath)
+          const fileRef = fileRefsFound.find(ref => sameFileRefPath(ref.relativePath, filePath))
           if (fileRef) {
             entry.fileExists = fileRef.exists
+            applyDotenvFileRefMetadata(entry, {
+              ...fileRef,
+              variable: entry.variable,
+            })
           } else if (configPath) {
             const thePath = path.resolve(path.dirname(configPath), filePath)
             const fileExists = fs.existsSync(thePath)
             entry.fileExists = fileExists
+            applyDotenvFileRefMetadata(entry, {
+              filePath: thePath,
+              relativePath: filePath,
+              variable: entry.variable,
+            })
           }
         }
       }

package/src/utils/security/dotenvFileRefs.js

@@ -0,0 +1,134 @@
+const path = require('path')
+const { normalizePath } = require('../paths/filePathUtils')
+const { splitCsv } = require('../strings/splitCsv')
+const { trimSurroundingQuotes } = require('../strings/quoteUtils')
+
+const DOTENV_SENSITIVITY_REASON = 'dotenv_file'
+
+function isDotenvFilePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return false
+  const cleanPath = filePath.trim().replace(/^["']|["']$/g, '')
+  const baseName = path.basename(cleanPath)
+  return baseName === '.env' || baseName.startsWith('.env.')
+}
+
+function hasFileAccessor(variableString) {
+  const expression = extractFileExpression(variableString)
+  if (!expression) return false
+  const suffix = String(variableString || '').slice(expression.end).trim()
+  return suffix.startsWith(':') || suffix.startsWith('.')
+}
+
+function extractFileExpression(variableString) {
+  const value = String(variableString || '')
+  const prefixMatch = /(?:^|[^\w.])((?:file|text)\()/.exec(value)
+  if (!prefixMatch) return null
+
+  const expressionStart = prefixMatch.index + prefixMatch[0].indexOf(prefixMatch[1])
+  const openParenIndex = expressionStart + prefixMatch[1].length - 1
+  let depth = 1
+  let index = openParenIndex + 1
+
+  while (index < value.length && depth > 0) {
+    if (value[index] === '(') depth++
+    else if (value[index] === ')') depth--
+    index++
+  }
+
+  if (depth !== 0) return null
+
+  const fileContent = value.substring(openParenIndex + 1, index - 1).trim()
+  if (!fileContent) return null
+
+  const parts = splitCsv(fileContent, undefined, { protectVariables: true })
+  const filePath = trimSurroundingQuotes(parts[0].trim(), false)
+
+  return {
+    filePath,
+    expression: value.slice(expressionStart, index),
+    start: expressionStart,
+    end: index,
+  }
+}
+
+function extractDotenvPath(source) {
+  const candidates = [
+    source.relativePath,
+    source.resolvedPath,
+    source.filePath,
+    source.fullFilePath,
+  ].filter(Boolean)
+
+  for (const candidate of candidates) {
+    if (isDotenvFilePath(candidate)) return candidate
+  }
+
+  const variableCandidates = [
+    source.variable,
+    source.variableString,
+    source.originalVariableString,
+    source.resolvedVariableString,
+  ].filter(Boolean)
+
+  for (const candidate of variableCandidates) {
+    const extracted = extractFileExpression(String(candidate))
+    if (extracted && isDotenvFilePath(extracted.filePath)) {
+      return extracted.filePath
+    }
+  }
+
+  return null
+}
+
+function getDotenvFileRefMetadata(source = {}) {
+  const dotenvPath = extractDotenvPath(source)
+  if (!dotenvPath) return null
+
+  const scopeSource = source.variableString ||
+    source.variable ||
+    source.originalVariableString ||
+    source.resolvedVariableString ||
+    ''
+  const accessorScope = hasFileAccessor(scopeSource) ? 'key' : null
+
+  return {
+    sensitive: true,
+    sensitivityReason: DOTENV_SENSITIVITY_REASON,
+    dotenvFile: true,
+    dotenvReadScope: accessorScope || source.dotenvReadScope || 'full_file',
+  }
+}
+
+function normalizeDotenvFileVariable(variableString) {
+  const value = String(variableString || '')
+  const expression = extractFileExpression(value)
+  if (!expression || !isDotenvFilePath(expression.filePath)) return null
+
+  const normalizedPath = normalizePath(expression.filePath) || expression.filePath
+  const normalizedExpression = expression.expression.replace(/\(([\s\S]*)\)$/, `(${normalizedPath})`)
+  const suffix = value.slice(expression.end).trim()
+  const accessor = suffix.match(/^([:.][\w.[\]-]+)/)
+
+  return accessor ? `${normalizedExpression}${accessor[1]}` : normalizedExpression
+}
+
+function isIniLikeFilePath(filePath) {
+  const ext = path.extname(String(filePath || '')).slice(1).toLowerCase()
+  return ext === 'ini' || isDotenvFilePath(filePath)
+}
+
+function applyDotenvFileRefMetadata(target, source) {
+  const metadata = getDotenvFileRefMetadata(source)
+  if (metadata) Object.assign(target, metadata)
+  return target
+}
+
+module.exports = {
+  DOTENV_SENSITIVITY_REASON,
+  applyDotenvFileRefMetadata,
+  getDotenvFileRefMetadata,
+  hasFileAccessor,
+  normalizeDotenvFileVariable,
+  isDotenvFilePath,
+  isIniLikeFilePath,
+}

package/src/utils/security/dotenvFileRefs.test.js

@@ -0,0 +1,47 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const {
+  getDotenvFileRefMetadata,
+  hasFileAccessor,
+  isDotenvFilePath,
+  normalizeDotenvFileVariable,
+} = require('./dotenvFileRefs')
+
+test('dotenv file detection matches .env and .env variants', () => {
+  assert.is(isDotenvFilePath('.env'), true)
+  assert.is(isDotenvFilePath('./.env.production'), true)
+  assert.is(isDotenvFilePath('/tmp/app/.env.local'), true)
+  assert.is(isDotenvFilePath('./env.yml'), false)
+})
+
+test('dotenv accessors are detected without assuming ${} syntax', () => {
+  assert.is(hasFileAccessor('file(.env).API_KEY'), true)
+  assert.is(hasFileAccessor('file(.env):TOKEN'), true)
+  assert.is(hasFileAccessor('${file(.env).API_KEY}'), true)
+  assert.is(hasFileAccessor('[[file(.env).API_KEY]]'), true)
+  assert.is(hasFileAccessor('file(.env)'), false)
+})
+
+test('dotenv metadata classifies full-file and key reads', () => {
+  assert.equal(getDotenvFileRefMetadata({ variable: 'file(.env)' }), {
+    sensitive: true,
+    sensitivityReason: 'dotenv_file',
+    dotenvFile: true,
+    dotenvReadScope: 'full_file',
+  })
+  assert.equal(getDotenvFileRefMetadata({ variable: '[[file(.env):TOKEN]]' }), {
+    sensitive: true,
+    sensitivityReason: 'dotenv_file',
+    dotenvFile: true,
+    dotenvReadScope: 'key',
+  })
+})
+
+test('dotenv variable normalization preserves key accessors', () => {
+  assert.is(normalizeDotenvFileVariable('file(.env)'), 'file(./.env)')
+  assert.is(normalizeDotenvFileVariable('file(.env).API_KEY'), 'file(./.env).API_KEY')
+  assert.is(normalizeDotenvFileVariable('file(.env):TOKEN'), 'file(./.env):TOKEN')
+  assert.is(normalizeDotenvFileVariable('file(config.yml):value'), null)
+})
+
+test.run()