PRD 0062: supervisor override for egress token blocks

When the outbound DLP catches a token, route the block through the
existing supervisor approval queue instead of returning 403 outright.
The egress proxy holds the request open until the operator answers, then
remembers an approved value for the life of the proxy so the request --
and later ones carrying it -- flow through. Fails closed on rejection,
timeout, malformed response, or when supervise is disabled.

- ScanResult.matched carries the raw matched substring (sidecar-only;
  never logged or written to the proposal). scan_outbound and the token
  detectors take a safe_tokens set and skip approved values, continuing
  past a safelisted match so a second secret in the same request is
  still caught.
- New egress-token-allow proposal tool, written directly to the queue by
  the addon (the gitleaks-allow pattern from PRD 0061). build_token_allow
  _payload renders host/method/path/detector reason + redacted context.
- Async request hook polls the queue without stalling the proxy event
  loop; EGRESS_TOKEN_ALLOW_TIMEOUT_SECONDS (default 300) bounds the wait.
- Supervisor TUI renders egress-token-allow like gitleaks-allow: report
  only, modify unavailable, approval requires a recorded reason.
- Unit tests for the matched/safe-tokens plumbing, payload builder, tool
  constant round-trip, and TUI paths; README + PRD 0062.

Closes #261.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HnvBjPZC5V7qeQpFbQdDmS

tests/unit/test_dlp_detectors.py

@@ -445,5 +445,47 @@ class TestKnownSecretsNewVariants(unittest.TestCase):
         self.assertIsNotNone(result)
 
 
+class TestMatchedAndSafeTokens(unittest.TestCase):
+    """PRD 0062: detectors carry the raw matched value, and a safelisted
+    value is skipped so the supervisor can approve a specific token."""
+
+    def test_token_pattern_sets_matched(self):
+        token = "ghp_" + "A" * 36
+        result = scan_token_patterns(f"token: {token}")
+        assert result is not None
+        self.assertEqual(token, result.matched)
+
+    def test_safe_token_is_skipped(self):
+        token = "ghp_" + "A" * 36
+        self.assertIsNone(
+            scan_token_patterns(f"token: {token}", safe_tokens={token})
+        )
+
+    def test_safe_token_does_not_mask_other_token(self):
+        safe = "ghp_" + "A" * 36
+        other = "AKIAIOSFODNN7EXAMPLE"
+        result = scan_token_patterns(
+            f"a={safe} b={other}", safe_tokens={safe},
+        )
+        assert result is not None
+        self.assertEqual(other, result.matched)
+        self.assertIn("AWS", result.reason)
+
+    def test_known_secret_sets_matched_and_safelist_skips(self):
+        secret = "supersecretvalue123"
+        env = {"EGRESS_TOKEN_FOO": secret}
+        result = scan_known_secrets(f"x={secret}", env=env)
+        assert result is not None
+        self.assertEqual(secret, result.matched)
+        self.assertIsNone(
+            scan_known_secrets(f"x={secret}", env=env, safe_tokens={secret})
+        )
+
+    def test_crlf_block_has_no_matched_value(self):
+        result = scan_crlf_injection("path%0d%0aHost: evil")
+        assert result is not None
+        self.assertEqual("", result.matched)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_egress_addon_core.py

@@ -22,8 +22,10 @@ from bot_bottle.egress_addon_core import (
     MatchEntry,
     PathMatch,
     Route,
+    ScanResult,
     build_inbound_scan_text,
     build_outbound_scan_text,
+    build_token_allow_payload,
     decide,
     decide_git_fetch,
     evaluate_matches,
@@ -1167,5 +1169,55 @@ class TestScanInbound(unittest.TestCase):
         self.assertEqual("block", result.severity)
 
 
+class TestScanOutboundSafeTokens(unittest.TestCase):
+    """PRD 0062: scan_outbound threads the supervisor-approved safe-tokens
+    set into the token detectors."""
+
+    def test_safe_token_allows_request(self):
+        text = build_outbound_scan_text(
+            host="api.example.com", path="/v1/data", query="",
+            headers={}, body=f"key={_AWS_KEY}",
+        )
+        self.assertIsNone(
+            scan_outbound(_ROUTE, text, {}, safe_tokens={_AWS_KEY})
+        )
+
+    def test_unrelated_safe_token_still_blocks(self):
+        text = build_outbound_scan_text(
+            host="api.example.com", path="/v1/data", query="",
+            headers={}, body=f"key={_AWS_KEY}",
+        )
+        result = scan_outbound(_ROUTE, text, {}, safe_tokens={"ghp_" + "A" * 36})
+        self.assertIsNotNone(result)
+        assert result is not None
+        self.assertEqual(_AWS_KEY, result.matched)
+
+
+class TestBuildTokenAllowPayload(unittest.TestCase):
+    def test_payload_includes_context_and_no_raw_token(self):
+        result = ScanResult(
+            severity="block",
+            reason="AWS access key found in body",
+            location="body",
+            context="key=******** tail",
+            matched=_AWS_KEY,
+        )
+        payload = build_token_allow_payload(
+            "api.example.com", "POST", "/v1/ingest", result,
+        )
+        self.assertIn("host: api.example.com", payload)
+        self.assertIn("method: POST", payload)
+        self.assertIn("path: /v1/ingest", payload)
+        self.assertIn("AWS access key found in body", payload)
+        self.assertIn("key=******** tail", payload)
+        # The raw matched value must never appear in the proposal file.
+        self.assertNotIn(_AWS_KEY, payload)
+
+    def test_payload_omits_context_line_when_empty(self):
+        result = ScanResult(severity="block", reason="r", matched="x")
+        payload = build_token_allow_payload("h", "GET", "/", result)
+        self.assertNotIn("context:", payload)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_supervise.py

@@ -322,11 +322,22 @@ class TestToolConstants(unittest.TestCase):
                 TOOL_CAPABILITY_BLOCK,
                 supervise.TOOL_EGRESS_BLOCK,
                 TOOL_GITLEAKS_ALLOW,
+                supervise.TOOL_EGRESS_TOKEN_ALLOW,
                 supervise.TOOL_LIST_EGRESS_ROUTES,
             ),
             supervise.TOOLS,
         )
 
+    def test_token_allow_proposal_roundtrips(self):
+        p = Proposal.new(
+            bottle_slug="dev",
+            tool=supervise.TOOL_EGRESS_TOKEN_ALLOW,
+            proposed_file="host: api.example.com\n",
+            justification="false positive",
+            current_file_hash="h",
+        )
+        self.assertEqual(p, Proposal.from_dict(p.to_dict()))
+
     def test_component_map_has_egress_entries(self):
         self.assertEqual(
             {

tests/unit/test_supervise_cli.py

@@ -20,6 +20,7 @@ from bot_bottle.supervise import (
     STATUS_REJECTED,
     TOOL_CAPABILITY_BLOCK,
     TOOL_GITLEAKS_ALLOW,
+    TOOL_EGRESS_TOKEN_ALLOW,
     read_audit_entries,
     read_response,
     sha256_hex,
@@ -35,6 +36,7 @@ def _proposal(slug: str = "dev", tool: str = TOOL_CAPABILITY_BLOCK) -> Proposal:
         supervise.TOOL_ALLOW: "routes:\n  - host: example.com\n",
         supervise.TOOL_EGRESS_BLOCK: "routes:\n  - host: example.com\n",
         TOOL_GITLEAKS_ALLOW: "file: tests/test_fixture.py\nline: 3\n",
+        TOOL_EGRESS_TOKEN_ALLOW: "host: api.example.com\ndetector: token\n",
     }
     payload = payloads.get(tool, "")
     return Proposal.new(
@@ -196,6 +198,39 @@ class TestApproveReject(_FakeHomeMixin, unittest.TestCase):
         resp = read_response(qp.queue_dir, qp.proposal.id)
         self.assertEqual("test fixture", resp.notes)
 
+    def test_approve_token_allow_leaves_response_for_egress(self):
+        qp = self._enqueue(tool=TOOL_EGRESS_TOKEN_ALLOW)
+        supervise_cli.approve(qp, notes="false positive")
+        # The egress addon polls the queue dir for the response; the TUI must
+        # not archive it (the addon archives after reading).
+        resp = read_response(qp.queue_dir, qp.proposal.id)
+        self.assertEqual(STATUS_APPROVED, resp.status)
+        self.assertEqual("false positive", resp.notes)
+        self.assertFalse((qp.queue_dir / "processed").exists())
+
+    def test_token_allow_writes_no_audit_log(self):
+        qp = self._enqueue(tool=TOOL_EGRESS_TOKEN_ALLOW)
+        supervise_cli.approve(qp, notes="false positive")
+        self.assertEqual([], read_audit_entries("egress", "dev"))
+
+    def test_tui_token_allow_requires_reason(self):
+        qp = self._enqueue(tool=TOOL_EGRESS_TOKEN_ALLOW)
+        with patch.object(supervise_cli, "_prompt", return_value=""):
+            status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
+        self.assertEqual("approve aborted (empty reason)", status)
+        self.assertFalse((qp.queue_dir / "processed").exists())
+
+    def test_tui_token_allow_writes_reason(self):
+        qp = self._enqueue(tool=TOOL_EGRESS_TOKEN_ALLOW)
+        with patch.object(supervise_cli, "_prompt", return_value="legit"):
+            status = supervise_cli._approve_from_tui(None, qp)  # type: ignore[arg-type]
+        self.assertIn("approved egress-token-allow", status)
+        resp = read_response(qp.queue_dir, qp.proposal.id)
+        self.assertEqual("legit", resp.notes)
+
+    def test_suffix_for_token_allow_is_txt(self):
+        self.assertEqual(".txt", supervise_cli._suffix_for_tool(TOOL_EGRESS_TOKEN_ALLOW))
+
 
 # class TestCapabilityApplyWiring(_FakeHomeMixin, unittest.TestCase):
 #     # DISABLED — capability_apply functionality is currently commented out.