WARDEN-WP-0026 T03: masking display filter (defense-in-depth)

- warden/mask.py: fingerprint()/mask_value() — presence, length, 8-char sha256
  prefix; never the value.
- proxy.proxy_fetch_fingerprint + `warden access --fingerprint`: masked status view
  (presence/length/hash) that emits no value, so it bypasses the T02 stdout guard.
  Lets two parties compare sha256 prefixes to confirm a shared value without seeing
  it (e.g. rotation landed).
- documented as defense-in-depth (raw bao bypasses it) in OperatorAccessAssist.md
  and the module docstring.
- tests: tests/test_mask.py + CLI fingerprint test. 299 pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/warden/cli.py

@@ -960,6 +960,7 @@ def _access_proxy(
     wrap: bool = False,
     wrap_ttl: str = "5m",
     unsafe_stdout: bool = False,
+    fingerprint: bool = False,
 ) -> None:
     """Proxy a non-SSH credential fetch as the caller (WP-0014 T3).
 
@@ -973,6 +974,7 @@ def _access_proxy(
         caller_auth_present,
         proxy_exec,
         proxy_fetch,
+        proxy_fetch_fingerprint,
         proxy_fetch_to_file,
         proxy_fetch_wrapped,
         resolve_fetch_command,
@@ -1061,7 +1063,7 @@ def _access_proxy(
     # secret value on stdout. Streaming a value to stdout is the documented anti-pattern:
     # allowed only to an interactive terminal, and only with an explicit acknowledgment
     # when stdout is captured/piped (the logged-context disclosure risk).
-    if not is_login and not do_exec and not wrap and not out_path:
+    if not is_login and not do_exec and not wrap and not out_path and not fingerprint:
         import sys as _sys
 
         if not _sys.stdout.isatty() and not unsafe_stdout:
@@ -1098,6 +1100,15 @@ def _access_proxy(
         elif out_path:
             rc = proxy_fetch_to_file(resolved, Path(out_path))
             err.print(f"[dim]value written to {out_path} (mode 0600); not shown[/dim]")
+        elif fingerprint:
+            fp = proxy_fetch_fingerprint(resolved)
+            # Masked fingerprint only — presence, length, short hash; never the value.
+            print(fp.render())
+            err.print(
+                "[dim]masked fingerprint (defense-in-depth; not the value). Compare "
+                "sha256 prefixes to confirm two parties hold the same secret.[/dim]"
+            )
+            rc = 0
         else:
             rc = proxy_fetch(resolved)
     except ProxyError as e:
@@ -1160,6 +1171,10 @@ def access(
         bool,
         typer.Option("--unsafe-stdout", help="Acknowledge streaming a value to a captured/piped stdout (anti-pattern)"),
     ] = False,
+    fingerprint: Annotated[
+        bool,
+        typer.Option("--fingerprint", help="Show a masked fingerprint (presence, length, short hash) — never the value"),
+    ] = False,
     no_policy: Annotated[
         bool,
         typer.Option("--no-policy", help="Acknowledge proxying when the flex-auth gate is not enforced"),
@@ -1195,7 +1210,7 @@ def access(
 
     entry = matches[0]
 
-    if do_fetch or do_exec or out_path or wrap:
+    if do_fetch or do_exec or out_path or wrap or fingerprint:
         _access_proxy(
             entry,
             domain=domain,
@@ -1208,6 +1223,7 @@ def access(
             wrap=wrap,
             wrap_ttl=wrap_ttl,
             unsafe_stdout=unsafe_stdout,
+            fingerprint=fingerprint,
         )
         return
 

src/warden/mask.py

@@ -0,0 +1,46 @@
+"""Masking display filter for KV values (WARDEN-WP-0026 T03).
+
+Defense-in-depth, **not a boundary**: any place warden would otherwise render a
+secret value for a human (a status/listing view) shows a *fingerprint* instead —
+presence, length, and a short non-reversible hash. Two operators can compare
+fingerprints to confirm they hold the same value (e.g. that a rotation landed the
+expected token) without either seeing it, and a fingerprint in a transcript
+discloses nothing.
+
+Limitation (documented, by design): raw `bao kv get <path>` bypasses this entirely
+— warden only masks *warden-mediated* output. The real boundary is OpenBao policy
+plus the T01 capabilities-safe verify and T02 no-stdout transports.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+# Short, non-reversible hash: first 8 hex chars of SHA-256. Not a value, and a
+# collision is irrelevant for the "same/different?" comparison this supports.
+_HASH_PREFIX_LEN = 8
+
+
+@dataclass(frozen=True)
+class Fingerprint:
+    present: bool
+    length: int
+    sha256_prefix: str  # "" when the value is empty/absent
+
+    def render(self) -> str:
+        if not self.present:
+            return "‹absent›"
+        return f"‹hidden len={self.length} sha256:{self.sha256_prefix}›"
+
+
+def fingerprint(value: str | None) -> Fingerprint:
+    """Compute a non-reversible fingerprint of a value. Never returns the value."""
+    if not value:
+        return Fingerprint(present=False, length=0, sha256_prefix="")
+    digest = hashlib.sha256(value.encode("utf-8")).hexdigest()[:_HASH_PREFIX_LEN]
+    return Fingerprint(present=True, length=len(value), sha256_prefix=digest)
+
+
+def mask_value(value: str | None) -> str:
+    """Render a value as its masked fingerprint string. Never emits the value."""
+    return fingerprint(value).render()

src/warden/proxy.py

@@ -301,6 +301,22 @@ def proxy_fetch_wrapped(resolved: ResolvedFetch) -> str:
     return str(token)
 
 
+def proxy_fetch_fingerprint(resolved: ResolvedFetch):
+    """Fetch the value and return a masked fingerprint — never the value (T03).
+
+    Defense-in-depth status view: lets an operator confirm presence/length and
+    compare a short non-reversible hash without disclosing the secret. The value
+    transits warden's memory only to be hashed, and is scrubbed immediately.
+    """
+    from warden.mask import fingerprint
+
+    value = _capture_value(resolved)
+    try:
+        return fingerprint(value)
+    finally:
+        value = ""  # noqa: F841 — best-effort scrub
+
+
 def proxy_exec(resolved: ResolvedFetch, *, env_var: str, child_argv: List[str]) -> int:
     """Fetch the value and inject it into a child command's environment only.