feat: cross-tool secret taint tracking (v1.3) + reversible secret cloaking (v1.4)

v1.3 — cross-tool secret taint tracking: when a credential-shaped value is
returned by one MCP tool, tag a SHA-256 hash of it (never the raw secret)
into a shared per-project ledger; when that same value later appears in a
different tool's call arguments, escalate the call to at least Approval,
closing the cross-tool confused-deputy relay (OWASP MCP09). Also wired into
the --check-staged and --check-cmd surfaces. New flags: --taint-ttl-secs,
--no-taint-tracking, --taint-list, --taint-flush.

v1.4 — reversible secret cloaking: register a secret and reference it in
tool-call arguments as {{cloak:NAME}}. Shield resolves the placeholder to
the real value only on the copy it forwards to the MCP server, so the secret
never lands in the agent/LLM context; in reverse, any registered secret that
leaks into a tool result is scrubbed back to its placeholder before the
agent sees it. Covers both stdio and Streamable-HTTP transports; zero-copy
when no placeholder is present. New module src/cloak.rs; vault at
~/.aperion-shield/cloak-vault.json (mode 0600, never logged). New flags:
--cloak-add, --cloak-list, --cloak-remove, --no-cloak.

Bumps to 1.4.0.

Author: scottbitbot2502

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "aperion-shield"
-version = "1.2.1"
+version = "1.4.0"
 edition = "2021"
 description = "Aperion Shield -- a local MCP guardrail for AI coding agents with optional biometric identity gates (ID.me). Standalone, free, open source."
 license = "Apache-2.0"

Cargo.toml

@@ -52,6 +52,36 @@ the relying party — no rewrite, no re-install.
 
 ---
 
+## What's new in v1.4
+
+**Reversible secret cloaking** — register a secret once, then reference it
+in your agent's tool-call arguments as the placeholder `{{cloak:NAME}}`.
+Shield swaps in the real value **only on the copy it forwards to the MCP
+server** — so the actual secret never lands in the agent's context, the
+transcript, the model provider's logs, or any prompt cache. In the reverse
+direction, if a tool *result* echoes a registered secret back, Shield
+scrubs it to its placeholder before the agent (and the model) ever sees it.
+
+This is the reversible complement to v1.3's taint tracking: taint is
+detect-and-escalate over one-way hashes; cloak is a local, reversible vault
+that transforms the wire at both proxy seams. Both stdio and Streamable-HTTP
+transports are covered, and the transform is a zero-copy fast path when no
+placeholder is present.
+
+```bash
+# Register a secret (value read from $SHIELD_CLOAK_VALUE or stdin, never argv):
+SHIELD_CLOAK_VALUE='sk_live_…' aperion-shield --cloak-add stripe_key
+aperion-shield --cloak-list                # names only, never values
+aperion-shield --cloak-remove stripe_key
+```
+
+Your agent then sends `Authorization: Bearer {{cloak:stripe_key}}`; the
+upstream server receives the real key; the model context only ever holds
+the placeholder. The vault lives at `~/.aperion-shield/cloak-vault.json`
+(mode `0600`, protected by filesystem permissions — never logged, never
+included in audit events). New flags: `--cloak-add NAME`, `--cloak-list`,
+`--cloak-remove NAME`, `--no-cloak`.
+
 ## What's new in v1.3
 
 **Cross-tool secret taint tracking** — the first Shield capability that

README.md

@@ -146,6 +146,47 @@ but does **not** make it cryptographically impossible to evade:
   constrains what a malicious server can *do* even if it evades
   catalog-level detection entirely.
 
+### Known limitation: cross-tool taint tracking is heuristic (v1.3+)
+
+Cross-tool secret taint tracking (`--taint-ttl-secs`, shipped in v1.3)
+tags a hash of any credential-shaped value a tool *returns*, and escalates
+a later call on any surface that relays the same value. It closes the
+confused-deputy / cross-tool-relay gap (OWASP MCP09) that per-call checks
+miss, but it is **heuristic correlation, not a cryptographic taint-
+tracking guarantee**:
+
+- **Hash-equality only.** The correlation works by matching a SHA-256 of
+  the *exact substring* our regex extracts. A secret that is re-encoded or
+  transformed before reuse -- base64/hex re-encoding, URL-encoding,
+  splitting across fields, partial retyping, or wrapping in a different
+  serialization -- will not hash-match and will evade detection. Detecting
+  transformed secrets would require dataflow-level taint propagation
+  inside the agent/runtime, which a protocol-level proxy cannot see.
+- **Regex coverage is finite.** Only the enumerated high-signal shapes
+  (AWS/GitHub/Slack/OpenAI/Anthropic/Google/Stripe tokens, JWTs, PEM
+  private-key blocks, DB connection strings) are tracked. A bespoke or
+  vendor-specific credential format outside that corpus is not tagged. The
+  scope is deliberately tight to keep false positives near zero; it is not
+  a claim of completeness.
+- **No file locking.** The ledger (`.aperion-shield/taint.jsonl`) is
+  append-only and lock-free, the same best-effort contract as decision
+  memory. A read/write race between two Shield processes in the same
+  project can, in a narrow window, miss a just-written entry (fail open,
+  never fail closed with a false block on unrelated data).
+- **CWD-scoped.** The ledger lives under the current working directory's
+  `.aperion-shield/` (falling back to `~/.aperion-shield/` when the
+  project dir is read-only) -- the same inherited scoping caveat that
+  already applies to decision memory. Two IDE windows rooted at different
+  directories do not share a ledger.
+- **We never store the raw secret** -- only its hash, plus the entity kind
+  and the source tool/surface for the human-readable reason. `--taint-list`
+  and the audit log surface those metadata, never the credential itself.
+
+The signal is intended to *raise the cost and visibility* of a cross-tool
+credential relay and force a human decision on it, not to be an
+unbypassable exfiltration control. For "I don't trust this server's
+process at all," `--sandbox` remains the complementary control.
+
 ### Cryptographic primitives
 
 - **Ed25519** for identity proofs (the `--identity-*` family) and
@@ -329,3 +370,4 @@ If you operate Shield as part of an enterprise deployment:
 | 2026-05-20 | v0.7.0 shipped. No new advisories or fix-required changes; this is a feature-only release. `cargo audit` clean against `Cargo.lock` at the v0.7.0 commit. New surfaces (`--install-hooks`, `--check-staged`, `--check-pushed-refs`, `--suggest-rules`) all stay within the standalone process model — no new network endpoints, no new on-disk persistence beyond `.git/hooks/` (Shield itself) and the operator-redirected audit log. Supported-versions table updated; v0.6.x dropped to security-only. |
 | 2026-07-03 | v1.2.1 shipped. Hardening for the v1.2 continuous drift-check probe, prompted by external feedback: dropped the `__shield_drift_`-prefixed request id (a static, greppable marker, given this project is open source) in favor of a bare random UUID, and added +/-20% jitter to the polling interval so the cadence isn't a clean periodic signal. New §3 subsection "Known limitation: drift-check probes are not unspoofable" documents what this does and does not close — a targeted adversary running statistical traffic analysis could still attempt evasion; that residual risk is inherent to any protocol-level monitor sharing a channel with the thing it doesn't trust, and `--sandbox` is the complementary control for that threat model. No CVE; not a regression, a hardening of a feature shipped hours earlier. |
 | 2026-05-27 | v0.8.0 shipped. No new advisories or fix-required changes; this is a feature-only release. `cargo audit` clean against `Cargo.lock` at the v0.8.0 commit. New surfaces (`--install-shims`, `--uninstall-shims`, `--list-shims`, `--check-cmd`, `--explain`) all stay within the standalone process model. The shim path writes per-command `/bin/sh` wrappers into `~/.aperion-shield/bin/` (or `--shim-dir PATH`) at mode `0755` inside a directory at mode `0700`; **Shield will NOT overwrite any file it didn't write itself** (foreign-file collisions exit non-zero, file untouched). `--explain` is pure-input/pure-output — no on-disk persistence, no side-effects on decision memory or audit. Supported-versions table updated; v0.7.x dropped to security-only. |
+| 2026-07-03 | v1.3.0 shipped. New feature: cross-tool secret taint tracking (`--taint-ttl-secs`, `--no-taint-tracking`, `--taint-list`, `--taint-flush`). Closes the OWASP MCP09 confused-deputy / cross-tool-relay gap that per-call, single-server guardrails structurally miss — a credential leaked by one tool being relayed into a different tool/server/surface. New on-disk persistence: `.aperion-shield/taint.jsonl`, a per-project append-only ledger storing **only a SHA-256 hash** of each observed credential-shaped value (never the raw secret) plus its entity kind and source tool/surface. No new network endpoints. New §3 subsection "Known limitation: cross-tool taint tracking is heuristic" documents the honest limits: hash-equality correlation only (transformed/re-encoded secrets evade), finite regex corpus, lock-free (fail-open) ledger, CWD-scoped — it raises the cost and visibility of a relay and forces a human decision, it is not an unbypassable exfiltration control; `--sandbox` remains the complementary process-level control. `cargo audit` clean against `Cargo.lock` at the v1.3.0 commit. |

SECURITY.md

@@ -3,7 +3,7 @@
   "name": "io.github.AperionAI/shield",
   "title": "Aperion Shield",
   "description": "Local guardrail proxy that blocks destructive MCP tool calls, rug pulls, and tool poisoning",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "websiteUrl": "https://docs.aperion.ai/aperion-shield.html",
   "repository": {
     "url": "https://github.com/AperionAI/shield",
@@ -12,7 +12,7 @@
   "packages": [
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/aperionai/shield:shield-v1.2.1",
+      "identifier": "ghcr.io/aperionai/shield:shield-v1.3.0",
       "transport": {
         "type": "stdio"
       }