feat: keep secrets out of MCP client context (path guard, content and shape redaction)

[flow-systems]

Problem

DOKPLOY_REDACT_ENV masks secret-bearing fields by matching the field name of
an API response. That covers structured payloads well, but three classes of
response slip past it entirely:

1. Raw file contents. docker-readContainerFile,
dockerVolume-readVolumeFile and settings-readTraefikFile return a file as an
opaque string. The field wrapping it is called something neutral, so name-based
matching never fires. With redaction fully enabled, asking for /app/.env
returns every variable in it.

2. Database storage. Relational engines keep row data unencrypted on disk.
Reading /var/lib/postgresql/data/base/16384/2619 returns the contents of a
table in the clear — no SQL, no password, not even a running server. For a
payroll or customer database that is a larger exposure than the credentials the
field list already covers.

3. Log output. deployment-readLogs, application-readLogs and
compose-readLogs return prose. There is no field name and no path to key off,
so a build script that echoes a connection string hands it over intact.

Change

Three layers, all gated behind the existing DOKPLOY_REDACT_ENV rather than new
master switches.

Path guard (DOKPLOY_BLOCK_SECRET_PATHS, default true). Before a tool that
takes a filesystem path runs, that path is normalised — traversal segments and
percent-encoding are resolved — and matched against a deny-list of globs:
dotenv files, /run/secrets/**, private keys, credential stores, and the storage
directories of Postgres, MySQL, MongoDB, Redis and SQLite. On a match the call is
refused with an actionable error. Everything else about the tool keeps working,
so /app/logs/error.log still reads fine.

The guard keys off the presence of a string path argument rather than a
hardcoded tool-name list. Exactly ten of the generated tools take one, all of
them genuine file operations, so tools added later are covered without
maintenance.

Content redaction. When a file-access tool does return contents, those
contents are scanned for KEY=value assignments and the value is masked when the
key names a secret — reusing DOKPLOY_REDACT_FIELDS rather than introducing a
second list. DB_PASSWORD=hunter2 is masked, PORT=3000 stays readable.

Shape redaction. Every response is additionally scanned for secret formats:
credentials inside a URI, Authorization headers, PEM blocks, JWTs, and the
token formats of GitHub, GitLab, AWS, OpenAI, Slack and Stripe. A connection
string keeps everything but its password, so
postgres://appuser:hunter2@db:5432/app becomes
postgres://appuser:[REDACTED]@db:5432/app and remains useful for debugging.

Also included:

• DOKPLOY_EXTRA_REDACT_FIELDS and DOKPLOY_EXTRA_SECRET_PATHS, which append
  to the defaults. The existing variables replace them wholesale, which puts the
  common intent — "the defaults, plus this one entry" — on the dangerous path:
  the operator writes out the full list from an older copy and silently loses
  protections. A full override still works but now logs a warning.
• Base64 handling. The container file APIs return files base64-encoded, so both
  content passes decode before masking and re-encode afterwards. A payload is
  only treated as text when it round-trips back to identical base64, which
  rejects binary files and coincidental alphabet matches. Untouched responses are
  returned byte-identical.

Behaviour change to be aware of

The path guard is on by default, so a caller that reads .env files through
docker-readContainerFile today will start getting refusals. That default is a
deliberate proposal, not an oversight — the failure mode of the other direction
is silent — but it is the obvious thing to push back on, and
DOKPLOY_BLOCK_SECRET_PATHS=false restores the previous behaviour exactly.

Scope

This guards what reaches the MCP client. It is not a permission boundary:
anyone holding the same DOKPLOY_API_KEY can call the Dokploy API directly. It
also cannot detect a password written as prose (Connecting as admin with password hunter2), and no entropy-based guessing is attempted — a log shredded
by false positives is useless exactly when it is needed. Both limitations are
documented and one is pinned by a test.

Notes

• 89 new tests (134 total, all passing). pnpm type-check clean.
• pnpm lint reports one pre-existing formatting error in
  src/utils/redactSensitive.test.ts; this branch adds tests to that file but
  does not touch the offending lines.
• Happy to split this further or to flip the default if you would rather ship it
  opt-in first.

---

Disclosure: this was written by Claude (Anthropic) in a pair-programming
session — design, code, tests and this description. Every commit carries a
Co-Authored-By trailer. Two things worth knowing about that:

The tests are AI-written as well, so they are not independent evidence that the
code is correct. One concrete example of why that matters: the content redaction
layer shipped in my own deployment for several hours doing nothing at all,
because the tests were written against plain text while the API returns base64.
Every test passed. It surfaced only when the guards were exercised against the
live API, and the fix is the last commit on this branch.

What I can vouch for is usage, not review: this runs against five Dokploy
instances plus one HTTP deployment, and the path guard was verified against a
real container — .env, a traversal, a percent-encoded variant, an SSH key, a
service private key and a Postgres heap file were all refused, while ordinary
files kept reading normally. Please review it as unreviewed code from a stranger,
because in the ways that matter that is what it is.