Overly restrictive .env file blocking prevents reading legitimate files

Issue: Overly Restrictive .env File Blocking

Summary

The Read tool blocks access to ANY file containing ".env" in its path, preventing legitimate reads of:

Environment configuration files (.env.local, .env.development, .env.production)
Source code files with "env" in the path (environment/, config/env/)
Template/example files that should be readable (.env.template)

Reproduction

Current Behavior

// Trying to read any file with "env" in path
Read({ filePath: ".env.local" })
// ❌ Error: "The user has blocked you from reading .env.local, DO NOT make further attempts to read it"

Read({ filePath: "src/config/environment.ts" })
// ❌ Error: "The user has blocked you from reading src/config/environment.ts, DO NOT make further attempts to read it"

Read({ filePath: ".env.template" })
// ❌ Error: "The user has blocked you from reading .env.template, DO NOT make further attempts to read it"

Files Currently Blocked

❌ Blocked (shouldn't be):

.env.local, .env.development, .env.production
.env.template
src/environment/config.ts
config/env/settings.ts
Any path containing "env"

✅ Allowed (whitelist):

.env.sample
Files ending with .example

Root Cause

Location: packages/opencode/src/tool/read.ts:63-74

const block = iife(() => {
  const whitelist = [".env.sample", ".example"]

  if (whitelist.some((w) => filepath.endsWith(w))) return false
  if (filepath.includes(".env")) return true  // ❌ TOO BROAD

  return false
})

if (block) {
  throw new Error(`The user has blocked you from reading ${filepath}, DO NOT make further attempts to read it`)
}

Problem: The check filepath.includes(".env") blocks:

Any file with "env" anywhere in the path (not just .env files)
All .env variants (.env.local, .env.development, etc.)
Template files that are safe to read

Impact

Development Workflow Issues

Configuration Discovery: Cannot read environment config files to understand app setup
Template Usage: Cannot read .env.template or .env.example files
Source Code: Cannot read legitimate source files with "env" in path
Debugging: Cannot inspect environment configuration when troubleshooting

Security Intent

The blocking was likely intended to:

✅ Prevent leaking secrets in .env
✅ Protect production credentials

However, it's too aggressive and blocks safe files.

Proposed Solution

Recommended Fix: Basename-Based Blocking

Make the blocking more precise by checking only the filename, not the full path:

const block = iife(() => {
  const whitelist = [
    ".env.sample",
    ".env.example",
    ".example",
    ".env.template",
    ".env.schema"
  ]

  if (whitelist.some((w) => filepath.endsWith(w))) return false

  // Only block files that ARE actual .env files (basename check)
  const basename = path.basename(filepath)
  if (basename.startsWith(".env")) return true

  return false
})

if (block) {
  throw new Error(`The user has blocked you from reading ${filepath}, DO NOT make further attempts to read it`)
}

Alternative: Pattern-Based Whitelist

More explicit pattern matching:

const block = iife(() => {
  const basename = path.basename(filepath)

  // Whitelist: Safe template/example files
  const safePatterns = [
    /\.env\.sample$/,
    /\.env\.example$/,
    /\.env\.template$/,
    /\.env\.schema$/,
    /\.example$/
  ]

  if (safePatterns.some(pattern => pattern.test(filepath))) {
    return false
  }

  // Block: Actual .env files with potential secrets
  const blockPatterns = [
    /^\.env$/,                    // .env
    /^\.env\.local$/,             // .env.local
    /^\.env\.development$/,       // .env.development
    /^\.env\.production$/,        // .env.production
    /^\.env\.staging$/,           // .env.staging
    /^\.env\.test$/,              // .env.test
    /^\.env\.[a-z]+\.local$/      // .env.*.local
  ]

  return blockPatterns.some(pattern => pattern.test(basename))
})

Comparison Table

File Path	Current Behavior	After Fix
`.env`	❌ Blocked	❌ Blocked (correct)
`.env.local`	❌ Blocked	❌ Blocked (correct)
`.env.production`	❌ Blocked	❌ Blocked (correct)
`.env.sample`	✅ Allowed	✅ Allowed
`.env.example`	✅ Allowed	✅ Allowed
`.env.template`	❌ Blocked	✅ Allowed (fix)
`src/environment.ts`	❌ Blocked	✅ Allowed (fix)
`config/env/settings.ts`	❌ Blocked	✅ Allowed (fix)
`.example`	✅ Allowed	✅ Allowed

Testing

To verify fix:

// Test 1: Block actual .env files
Read({ filePath: ".env" })
// Should throw: blocked

Read({ filePath: ".env.local" })
// Should throw: blocked

// Test 2: Allow template files
Read({ filePath: ".env.template" })
// Should succeed

Read({ filePath: ".env.example" })
// Should succeed

// Test 3: Allow source files with "env" in path
Read({ filePath: "src/config/environment.ts" })
// Should succeed

Read({ filePath: "utils/envParser.ts" })
// Should succeed

Security Considerations

The fix maintains security by:

✅ Still blocking .env and variants (.env.local, .env.production, etc.)
✅ Preventing accidental secret leakage
✅ Allowing safe template/example files
✅ Not blocking legitimate source code

Additional Context

Security Goal: Prevent reading files with actual secrets
User Experience: Allow reading configuration templates and source code
Best Practice: Use .env.example or .env.template for documentation
Related Code: packages/opencode/src/tool/read.ts

References

Twelve-Factor App: https://12factor.net/config
dotenv best practices: https://github.com/motdotla/dotenv#should-i-commit-my-env-file

This issue might be a duplicate of or closely related to existing issues. Please check:

Feature Request: Zero-Trust Architecture for Environment Variable Security #4961: Feature Request: Zero-Trust Architecture for Environment Variable Security - Proposes implementing client-side secret detection and placeholder replacement to prevent actual secrets from being transmitted to LLM providers. This addresses the same underlying security/usability concern but from a different angle (content transformation vs file blocking).
[SECURITY] allow ignoring files to prevent secrets being leaked from .env to LLM #539 (CLOSED): [SECURITY] allow ignoring files to prevent secrets being leaked from .env to LLM - The original security concern that led to the current blocking mechanism. Understanding this closed issue's resolution may provide context for refining the approach.
Limiting access for tools in a safer way #4667: Limiting access for tools in a safer way - Proposes a broader security context model for tools. May be related if file access restrictions are being reconsidered as part of a larger security framework.

Feel free to ignore if your specific case differs from these, but they may provide useful context for the .env file handling discussion.

+1, Blocking .env files is great as a security-minded default, but users need control over what gets blacklisted when. And saying that the user requested this in the error message is downright misleading!

The current approach also blocks other legitimate use cases, for example opencode is now incapable of editing direnv configs cause they go in .envrc which trips the substring match and gets blocked by this code. I'm having to dust off claude code just to edit my direnv config 😨!

Yeah ill make it better v soon

hi guys, i still searching here for config, i don't find any config, only permission from official documentation, that globally restrict AI from reading any files with some type of patterns, like claude code have, here no solution right now for this right ?

fix(read): narrow .env file blocking to not block .envrc and other files

holy, all laravel projects got messy due to this .env blocking...

The solution is very straightforward, simply give read permissions to OpenCode in opencode.json:

  		"read": {
			"*.env*": "allow",
			"*": "allow"
		},

Be aware of the risks this carries.

Navigation Menu

Repository navigation

Overly restrictive .env file blocking prevents reading legitimate files #4969

Issue: Overly Restrictive .env File Blocking

Summary

Reproduction

Current Behavior

Files Currently Blocked

Root Cause

Impact

Development Workflow Issues

Security Intent

Proposed Solution

Recommended Fix: Basename-Based Blocking

Alternative: Pattern-Based Whitelist

Comparison Table

Testing

Security Considerations

Additional Context

References

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Overly restrictive .env file blocking prevents reading legitimate files #4969

Description

Issue: Overly Restrictive .env File Blocking

Summary

Reproduction

Current Behavior

Files Currently Blocked

Root Cause

Impact

Development Workflow Issues

Security Intent

Proposed Solution

Recommended Fix: Basename-Based Blocking

Alternative: Pattern-Based Whitelist

Comparison Table

Testing

Security Considerations

Additional Context

References

Activity

github-actions commented on Dec 2, 2025

nikvdp commented on Dec 10, 2025

rekram1-node commented on Dec 11, 2025

Act0r1 commented on Dec 14, 2025

khoa5935 commented on Dec 19, 2025

edxeth commented on Jan 12, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions