@@ -78,7 +86,7 @@ function AnswerBody({ result, onCite }: { result: SynthesizeResult; onCite: (id:
) : (
onCite(seg.claimId)}
+ onClick={() => onCite(citeKind(seg.claimId), seg.claimId)}
className="mx-0.5 inline-block max-w-72 truncate rounded border border-accent/40 bg-accent/10 px-1.5 align-middle font-mono text-[11px] leading-5 text-accent-2 transition hover:bg-accent/20"
title={seg.claimId}
>
@@ -89,6 +97,14 @@ function AnswerBody({ result, onCite }: { result: SynthesizeResult; onCite: (id:
+ {result._meta?.synthesis_backend === 'llm' && (
+
+ llm
+
+ )}
{result.gaps.length > 0 && (
gaps: {result.gaps.map((g) => (
@@ -299,7 +315,17 @@ export function ChatView() {
if (threadEndpointRef.current !== submittedFor) return
setMessages((m) => [...m, { role: 'vouch', kind: 'search', query, result }])
} else {
- const result = await rpc(conn, 'kb.synthesize', { query: text })
+ // LLM-first: the endpoint drafts the answer with its configured
+ // compile.llm_cmd, grounded in KB pages + approved claims. Endpoints
+ // without an llm_cmd reject with "not configured" — fall back to
+ // deterministic claim synthesis so the chat still answers.
+ let result: SynthesizeResult
+ try {
+ result = await rpc(conn, 'kb.synthesize', { query: text, llm: true })
+ } catch (err) {
+ if (!(err instanceof VouchRpcError) || !/not configured/i.test(err.message)) throw err
+ result = await rpc(conn, 'kb.synthesize', { query: text })
+ }
if (threadEndpointRef.current !== submittedFor) return
setMessages((m) => [...m, { role: 'vouch', kind: 'answer', result }])
}
@@ -332,7 +358,7 @@ export function ChatView() {
) : (
-
setDrawer({ kind: 'claim', id })} />
+ setDrawer({ kind, id })} />
)
From 4de2b6663be4f2b65ac733084fb507b9928d3062 Mon Sep 17 00:00:00 2001
From: plind <59729252+plind-junior@users.noreply.github.com>
Date: Mon, 13 Jul 2026 06:15:29 -0400
Subject: [PATCH 02/12] feat(synthesize): llm answer backend grounded in pages,
live in chat (#467)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
implement the reserved llm=true path of kb.synthesize: retrieval picks
kb pages and approved claims, the deployment-configured compile.llm_cmd
drafts the prose, and code verifies every [id] citation against the
offered sources — invented ids are stripped, and a draft left with no
verifiable citation returns an empty answer instead of a guess. the
wire shape is unchanged plus additive pages and _meta.synthesis_backend
fields.
the console chat now asks with llm: true and falls back to
deterministic claim synthesis when no llm_cmd is configured; page
citations open the page drawer and llm answers carry a badge. cli
mirror: vouch synthesize --llm. the mcp tool gains the llm param; the
jsonl/http surface already forwarded it.
---
CHANGELOG.md | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d907b836..4458b62e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -59,6 +59,18 @@ All notable changes to vouch are documented here. Format follows
changed-files list and the stacked all-files diff. selection is
per-candidate, so inspecting claude's diff never moves the codex pane.
(#294)
+- `kb.synthesize` llm backend: `llm=true` drafts the answer with the
+ deployment-configured `compile.llm_cmd`, grounded in retrieved kb pages
+ and approved claims. code still verifies every `[id]` citation against
+ the offered sources — invented ids are stripped, and a draft left with no
+ verifiable citation returns an empty answer rather than a guess. the wire
+ shape is unchanged plus additive `pages` and `_meta.synthesis_backend`
+ fields. cli mirror: `vouch synthesize --llm`; the jsonl/http surface
+ already forwarded the flag.
+- console Chat: llm answers activated — the chat asks `kb.synthesize` with
+ `llm: true` and falls back to deterministic claim synthesis when no
+ `compile.llm_cmd` is configured. page citations open the page drawer, and
+ llm answers carry an `llm` badge next to the confidence grade.
### Fixed
- `vouch digest --limit` now caps the followups-due section like the
From 6dbc9ce2fca30bdb3956f17ca29414c947d78427 Mon Sep 17 00:00:00 2001
From: plind <59729252+plind-junior@users.noreply.github.com>
Date: Mon, 13 Jul 2026 10:36:45 -0400
Subject: [PATCH 03/12] docs(readme): remove the x/twitter follow badge (#471)
drop the @vouch_dev follow badge from the header badge row; the
remaining badges (ci, pypi, mcp registry, python versions, license,
gittensor) are all project-status links rather than social ones.
---
README.md | 1 -
1 file changed, 1 deletion(-)
diff --git a/README.md b/README.md
index 39056961..d6045694 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,6 @@
+
+
+
So the honest pitch: **vouch is not a better place to put memory — it's a review gate in front of one, and a wiki on the other side of it.** If you're solo and happy, one prompt is genuinely fine; vouch's session capture runs passively alongside whatever your host already remembers, rather than replacing it. But once a fleet of agents writes to shared knowledge — or a team does — that pile of notes needs an editor, and an editor is not something you can prompt your way to. The case in full: [docs/review-gate.md](docs/review-gate.md).
## Watch it work (110 seconds)
diff --git a/docs/img/trust-vs-writers-dark.svg b/docs/img/trust-vs-writers-dark.svg
new file mode 100644
index 00000000..1575be33
--- /dev/null
+++ b/docs/img/trust-vs-writers-dark.svg
@@ -0,0 +1,56 @@
+
+ Trust in what you read, as writers are added — identical at one writer; a memory file decays past two writers, a review gate holds.
+
+
+
+ Trust in what you read, as writers are added
+ illustrative — the shape of the argument, not a benchmark
+
+
+ vouch (review gate)
+ one prompt / memory file
+
+
+ high
+ low
+
+
+ 1
+ 2
+ 3
+ 4
+ 5+
+ writers sharing the knowledge (agents, teammates, future you)
+
+
+ one writer: the two are identical
+ n ≥ 2: writes now need a trust model
+
+
+ vouch (review gate)
+ every landed write reviewed
+ one prompt / memory file
+ last write wins, silently
+
+
+
diff --git a/docs/img/trust-vs-writers-light.svg b/docs/img/trust-vs-writers-light.svg
new file mode 100644
index 00000000..f4c9ec89
--- /dev/null
+++ b/docs/img/trust-vs-writers-light.svg
@@ -0,0 +1,56 @@
+
+ Trust in what you read, as writers are added — identical at one writer; a memory file decays past two writers, a review gate holds.
+
+
+
+ Trust in what you read, as writers are added
+ illustrative — the shape of the argument, not a benchmark
+
+
+ vouch (review gate)
+ one prompt / memory file
+
+
+ high
+ low
+
+
+ 1
+ 2
+ 3
+ 4
+ 5+
+ writers sharing the knowledge (agents, teammates, future you)
+
+
+ one writer: the two are identical
+ n ≥ 2: writes now need a trust model
+
+
+ vouch (review gate)
+ every landed write reviewed
+ one prompt / memory file
+ last write wins, silently
+
+
+
From 5c79374339f4ec2ce8495a784360a3f109217c9a Mon Sep 17 00:00:00 2001
From: plind-junior <59729252+plind-junior@users.noreply.github.com>
Date: Wed, 15 Jul 2026 12:35:14 +0900
Subject: [PATCH 07/12] fix(gate): bind the proposal/audit actor to the
authenticated subject
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
step 0.1 of the gate-integrity hotfix. the actor recorded on every proposal
and audit event came from client-controlled input: X-Vouch-Agent on /rpc
(jsonl_server._agent) and VOUCH_AGENT env on /mcp (server._agent). because the
self-approval gate compares actor strings, one bearer token could propose as
"alice" and approve as "bob" and the approval sailed through — the review gate
was forgeable by anyone holding a single token.
both _agent() resolvers now prefer trust.current().auth_subject when the
request is authenticated, returning a stable token: identity that the
client cannot override. the header/env fallback survives only for tokenless
loopback/dev, which is trusted by design. mirrors web/server.py, where the
token's label already wins over any client-supplied name.
the exploit is pinned by a test: propose-as-alice then approve-as-bob under
one token is now caught as forbidden_self_approval. /mcp callers also stop
collapsing to a single env identity — distinct tokens are distinct actors, so
cross-review becomes possible and attribution is real.
---
src/vouch/jsonl_server.py | 8 ++++
src/vouch/server.py | 7 ++++
tests/test_http_server_mcp.py | 26 +++++++++++++
tests/test_jsonl_server.py | 69 +++++++++++++++++++++++++++++++++++
4 files changed, 110 insertions(+)
diff --git a/src/vouch/jsonl_server.py b/src/vouch/jsonl_server.py
index 6e2fc6ab..d63ea354 100644
--- a/src/vouch/jsonl_server.py
+++ b/src/vouch/jsonl_server.py
@@ -84,6 +84,14 @@ def _store() -> KBStore:
def _agent() -> str:
+ # An authenticated bearer subject is the principal's real identity; it must
+ # win over the client-supplied X-Vouch-Agent header (and VOUCH_AGENT env),
+ # or one token could propose as one actor and approve as another to defeat
+ # the self-approval gate. Only fall back to the header/env when the request
+ # is unauthenticated (tokenless loopback/dev), which is trusted by design.
+ subject = trust_mod.current().auth_subject
+ if subject is not None:
+ return f"token:{subject}"
return _actor.get() or os.environ.get("VOUCH_AGENT", "unknown-agent")
diff --git a/src/vouch/server.py b/src/vouch/server.py
index b78c7ca1..26db4bfd 100644
--- a/src/vouch/server.py
+++ b/src/vouch/server.py
@@ -71,6 +71,13 @@ def _store() -> KBStore:
def _agent() -> str:
+ # An authenticated bearer subject (set by the /mcp transport) is the
+ # principal's real identity and must be what proposals/audit attribute to,
+ # so a token cannot be spoofed and distinct tokens are distinct actors.
+ # VOUCH_AGENT is only the tokenless (stdio/dev) fallback.
+ subject = trust_mod.current().auth_subject
+ if subject is not None:
+ return f"token:{subject}"
return os.environ.get("VOUCH_AGENT", "unknown-agent")
diff --git a/tests/test_http_server_mcp.py b/tests/test_http_server_mcp.py
index 7e58fcb8..726d3f90 100644
--- a/tests/test_http_server_mcp.py
+++ b/tests/test_http_server_mcp.py
@@ -339,3 +339,29 @@ def test_legacy_capabilities_unchanged(base_url: str) -> None:
code, body = _get(base_url, "/capabilities")
assert code == 200
assert "http" in body["transports"]
+
+
+def test_mcp_agent_binds_to_auth_subject(monkeypatch) -> None:
+ """On /mcp the tool actor must bind to the authenticated bearer subject.
+
+ server._agent read only VOUCH_AGENT, so every authenticated caller
+ collapsed to one env-set identity and the token was never the attribution.
+ """
+ from vouch import server as vouch_server
+ from vouch import trust as trust_mod
+
+ monkeypatch.setenv("VOUCH_AGENT", "env-agent")
+ trust = trust_mod.with_auth_subject(trust_mod.MCP_HTTP, "mcp-token")
+ with trust_mod.trust_context(trust):
+ actor = vouch_server._agent()
+ assert actor != "env-agent"
+ assert trust_mod.auth_subject_for_token("mcp-token") in actor
+
+
+def test_mcp_agent_falls_back_to_env_when_unauthenticated(monkeypatch) -> None:
+ from vouch import server as vouch_server
+ from vouch import trust as trust_mod
+
+ monkeypatch.setenv("VOUCH_AGENT", "env-agent")
+ with trust_mod.trust_context(trust_mod.MCP_STDIO): # no auth_subject
+ assert vouch_server._agent() == "env-agent"
diff --git a/tests/test_jsonl_server.py b/tests/test_jsonl_server.py
index e04286f6..75cecb8c 100644
--- a/tests/test_jsonl_server.py
+++ b/tests/test_jsonl_server.py
@@ -248,3 +248,72 @@ def _boom(_params: dict) -> dict:
assert resp["ok"] is False
assert resp["error"]["code"] == "internal_error"
assert "traceback" not in resp["error"]
+
+
+# --- gate integrity: the actor binds to the authenticated principal --------
+
+
+def test_jsonl_agent_binds_to_auth_subject_over_header() -> None:
+ """An authenticated request's actor is the token subject, not the header.
+
+ X-Vouch-Agent is client-supplied; it must never override an authenticated
+ identity, or one token could masquerade as any actor it likes.
+ """
+ from vouch import jsonl_server
+ from vouch import trust as trust_mod
+
+ trust = trust_mod.with_auth_subject(trust_mod.JSONL_HTTP, "one-token")
+ with trust_mod.trust_context(trust):
+ reset = jsonl_server._actor.set("spoofed-header")
+ try:
+ actor = jsonl_server._agent()
+ finally:
+ jsonl_server._actor.reset(reset)
+ assert "spoofed-header" not in actor
+ assert trust_mod.auth_subject_for_token("one-token") in actor
+
+
+def test_jsonl_agent_uses_header_when_unauthenticated() -> None:
+ """Tokenless (dev/loopback) requests keep the existing header attribution."""
+ from vouch import jsonl_server
+ from vouch import trust as trust_mod
+
+ with trust_mod.trust_context(trust_mod.JSONL_HTTP): # no auth_subject
+ reset = jsonl_server._actor.set("named-agent")
+ try:
+ actor = jsonl_server._agent()
+ finally:
+ jsonl_server._actor.reset(reset)
+ assert actor == "named-agent"
+
+
+def test_one_token_cannot_self_approve_by_swapping_header(
+ store: KBStore, monkeypatch
+) -> None:
+ """The core exploit is closed: propose-as-alice, approve-as-bob, one token.
+
+ Because the actor binds to the authenticated subject, both operations
+ resolve to the same actor and the self-approval gate blocks the approval.
+ """
+ from vouch import jsonl_server
+ from vouch import trust as trust_mod
+
+ src = store.put_source(b"evidence")
+ monkeypatch.chdir(store.root)
+ trust = trust_mod.with_auth_subject(trust_mod.JSONL_HTTP, "one-token")
+ with trust_mod.trust_context(trust):
+ reset = jsonl_server._actor.set("alice")
+ try:
+ pr = handle_request({"id": "1", "method": "kb.propose_claim",
+ "params": {"text": "c", "evidence": [src.id]}})
+ finally:
+ jsonl_server._actor.reset(reset)
+ pid = pr["result"]["proposal_id"]
+ reset = jsonl_server._actor.set("bob")
+ try:
+ resp = handle_request({"id": "2", "method": "kb.approve",
+ "params": {"proposal_id": pid}})
+ finally:
+ jsonl_server._actor.reset(reset)
+ assert not resp["ok"]
+ assert "forbidden_self_approval" in resp["error"]["message"]
From f7887d1a8baa426e13cfe65ce784457ebbce879a Mon Sep 17 00:00:00 2001
From: plind-junior <59729252+plind-junior@users.noreply.github.com>
Date: Wed, 15 Jul 2026 12:44:01 +0900
Subject: [PATCH 08/12] fix(gate): close the import_apply bypass past the
review gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
step 0.2 of the gate-integrity hotfix. kb.import_apply writes bundle members
(claims/pages/decided) straight to disk — a parallel path past
proposals.approve() — and it was reachable by agents on MCP and JSONL. two
stopgaps until gated import lands (roadmap 8.2):
- import_check now refuses any bundle carrying decided/ members, scanned
directly from the manifest (not a self-reported safety flag a hand-crafted
bundle could lie about), so import_apply raises on them for every caller
including the CLI. decided/ holds approved decisions; importing it would land
approved claims/pages with no receiving-side proposal.
- kb.import_apply is dropped from the agent surfaces — the MCP tool, the JSONL
handler + HANDLERS entry, and the METHODS list — and from hot_memory's
exclusion map. it survives only as the human `vouch import apply` CLI
command. the read-only kb.import_check stays available on every surface.
exports still include decided/ (a faithful snapshot); the guard is on the
write side. capabilities/handlers parity holds.
---
src/vouch/bundle.py | 12 ++++++++++++
src/vouch/capabilities.py | 3 ++-
src/vouch/hot_memory.py | 1 -
src/vouch/jsonl_server.py | 13 +++++--------
src/vouch/server.py | 15 ++++-----------
tests/test_bundle.py | 30 ++++++++++++++++++++++++++++++
tests/test_capabilities.py | 19 +++++++++++++++++++
7 files changed, 72 insertions(+), 21 deletions(-)
diff --git a/src/vouch/bundle.py b/src/vouch/bundle.py
index 51e2f0d9..18c83cdb 100644
--- a/src/vouch/bundle.py
+++ b/src/vouch/bundle.py
@@ -519,6 +519,18 @@ def import_check(kb_dir: Path, bundle_path: Path) -> ImportCheckResult:
issues.extend(_manifest_safety_issues(manifest))
recorded = {f["path"]: f for f in manifest["files"]}
manifest_paths = set(recorded)
+ # decided/ holds approved decisions; import writes members straight to
+ # disk, so a bundle carrying decided/ would land approved claims/pages
+ # without a receiving-side proposal — a write past the review gate.
+ # Refuse until gated import exists (roadmap 8.2). Scanned directly from
+ # the manifest rather than via a self-reported safety flag, which a
+ # hand-crafted bundle could lie about.
+ decided_members = sorted(p for p in manifest_paths if p.startswith("decided/"))
+ if decided_members:
+ issues.append(
+ "bundle carries decided/ members that cannot be imported past "
+ f"the review gate: {decided_members[0]}"
+ )
for f in manifest["files"]:
try:
dest = _safe_member_path(kb_dir, f["path"])
diff --git a/src/vouch/capabilities.py b/src/vouch/capabilities.py
index 9d50f305..84901e74 100644
--- a/src/vouch/capabilities.py
+++ b/src/vouch/capabilities.py
@@ -82,7 +82,8 @@
"kb.export",
"kb.export_check",
"kb.import_check",
- "kb.import_apply",
+ # kb.import_apply intentionally absent — it writes past the review gate, so
+ # it is a human-only CLI command, not an agent method (roadmap step 0.2).
"kb.audit",
"kb.reindex_embeddings",
"kb.dedup_scan",
diff --git a/src/vouch/hot_memory.py b/src/vouch/hot_memory.py
index b6eae608..fea42ea1 100644
--- a/src/vouch/hot_memory.py
+++ b/src/vouch/hot_memory.py
@@ -184,7 +184,6 @@ def mark_volunteered(session_id: str, claim_id: str, *, pushed_at: float) -> Non
"kb.export": "bundle write — not a read response",
"kb.export_check": "preflight — no claim sidebar needed",
"kb.import_check": "preflight — no claim sidebar needed",
- "kb.import_apply": "mutation — applies bundle",
"kb.audit": "event log — different shape from claim reads",
"kb.reindex_embeddings": "maintenance — mutates derived index",
"kb.dedup_scan": "analysis — not a standard read",
diff --git a/src/vouch/jsonl_server.py b/src/vouch/jsonl_server.py
index d63ea354..836d13ba 100644
--- a/src/vouch/jsonl_server.py
+++ b/src/vouch/jsonl_server.py
@@ -733,13 +733,11 @@ def _h_import_check(p: dict) -> dict:
"identical_files": len(r.identical), "issues": r.issues}
-def _h_import_apply(p: dict) -> dict:
- r = bundle.import_apply(
- _store().kb_dir, Path(p["bundle_path"]),
- on_conflict=p.get("on_conflict", "skip"), actor=_agent(),
- )
- health.rebuild_index(_store())
- return r
+# kb.import_apply is deliberately NOT an agent-facing handler: it writes bundle
+# members (claims/pages/decided) straight to disk, a parallel path past
+# proposals.approve(). It survives only as the human `vouch import apply` CLI
+# command until gated import lands (roadmap 8.2). kb.import_check (read-only)
+# stays available to agents.
def _h_audit(p: dict) -> dict:
@@ -948,7 +946,6 @@ def _h_propose_theme(p: dict) -> dict:
"kb.export": _h_export,
"kb.export_check": _h_export_check,
"kb.import_check": _h_import_check,
- "kb.import_apply": _h_import_apply,
"kb.audit": _h_audit,
"kb.reindex_embeddings": _h_reindex_embeddings,
"kb.dedup_scan": _h_dedup_scan,
diff --git a/src/vouch/server.py b/src/vouch/server.py
index 26db4bfd..15d473ed 100644
--- a/src/vouch/server.py
+++ b/src/vouch/server.py
@@ -1064,17 +1064,10 @@ def kb_import_check(bundle_path: str) -> dict[str, Any]:
}
-@mcp.tool()
-def kb_import_apply(bundle_path: str, on_conflict: str = "skip") -> dict[str, Any]:
- try:
- r = bundle.import_apply(
- _store().kb_dir, Path(bundle_path),
- on_conflict=on_conflict, actor=_agent(),
- )
- except (RuntimeError, ValueError) as e:
- raise ValueError(str(e)) from e
- health.rebuild_index(_store())
- return r
+# kb_import_apply is intentionally not exposed as an MCP tool: applying a bundle
+# writes members (claims/pages/decided) straight to disk, bypassing
+# proposals.approve(). It remains the human-only `vouch import apply` CLI command
+# until gated import lands (roadmap 8.2). kb_import_check (read-only) stays.
@mcp.tool()
diff --git a/tests/test_bundle.py b/tests/test_bundle.py
index 391cdc6c..a15291ef 100644
--- a/tests/test_bundle.py
+++ b/tests/test_bundle.py
@@ -45,6 +45,36 @@ def test_export_import_round_trip(store: KBStore, tmp_path: Path) -> None:
assert dest.get_claim("c1").text == "alpha"
+def test_import_rejects_bundle_carrying_decided_members(
+ store: KBStore, tmp_path: Path
+) -> None:
+ """A bundle with decided/ members is a write past the review gate.
+
+ decided/ holds approved decisions; import writes members straight to disk,
+ so importing decided/ lands approved claims/pages without a receiving-side
+ proposal. Until gated import exists (roadmap 8.2), any such bundle is
+ refused — by import_check (issue) and therefore import_apply (raises).
+ """
+ from vouch.proposals import approve, propose_claim
+
+ src = store.put_source(b"e", title="d")
+ pid = propose_claim(
+ store, text="alpha", evidence=[src.id], proposed_by="a"
+ ).id
+ approve(store, pid, approved_by="b")
+ assert any((store.kb_dir / "decided").glob("*")), "decided/ should be populated"
+
+ bundle_path = tmp_path / "out.tar.gz"
+ bundle.export(store.kb_dir, dest=bundle_path)
+
+ dest = KBStore.init(tmp_path / "dest")
+ diff = bundle.import_check(dest.kb_dir, bundle_path)
+ assert not diff.ok
+ assert any("decided" in issue for issue in diff.issues)
+ with pytest.raises(RuntimeError):
+ bundle.import_apply(dest.kb_dir, bundle_path)
+
+
def test_manifest_paths_match_tar_member_names(store: KBStore, tmp_path: Path) -> None:
# Regression for the Windows path-separator bug: when build_manifest used
# str(rel) the manifest stored "sources\\meta.yaml" while the tar
diff --git a/tests/test_capabilities.py b/tests/test_capabilities.py
index 4d4dcc27..a92aa7a4 100644
--- a/tests/test_capabilities.py
+++ b/tests/test_capabilities.py
@@ -11,6 +11,25 @@
from vouch.jsonl_server import HANDLERS
+def test_import_apply_is_not_on_agent_surfaces() -> None:
+ """kb.import_apply writes past the review gate, so agents must not reach it.
+
+ It stays a human-only CLI command; the read-only kb.import_check survives
+ on every surface. (The real fix is gated import — roadmap 8.2.)
+ """
+ from vouch.jsonl_server import HANDLERS
+
+ assert "kb.import_apply" not in HANDLERS
+ assert "kb.import_apply" not in set(capabilities.capabilities().methods)
+ # read-only diff stays available to agents
+ assert "kb.import_check" in HANDLERS
+
+ from vouch.server import mcp
+
+ assert mcp._tool_manager.get_tool("kb_import_apply") is None
+ assert mcp._tool_manager.get_tool("kb_import_check") is not None
+
+
def test_capabilities_matches_jsonl_handlers() -> None:
caps = capabilities.capabilities()
declared = set(caps.methods)
From a56da0bf26feee5c9271c9a12867b050191637f2 Mon Sep 17 00:00:00 2001
From: plind-junior <59729252+plind-junior@users.noreply.github.com>
Date: Wed, 15 Jul 2026 12:52:50 +0900
Subject: [PATCH 09/12] fix(gate): fence export/import paths to the project
root on remote surfaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
step 0.4 of the gate-integrity hotfix. kb.export took a client-supplied
out_path and wrote a tarball there (creating parent dirs), and
kb.import_check/export_check read a client-supplied bundle_path — so a remote
caller on /rpc or /mcp could clobber or read an arbitrary file
(out_path=../../etc/cron.d/x, bundle_path=/etc/passwd).
new KBStore.resolve_under_root is the containment half of read_under_root
(resolve + is_relative_to, no open), and bundle.fenced_bundle_path applies it
only when trust.current().remote — so both server surfaces confine the path to
the project root while local cli and stdio stay unfenced, since a human
choosing where to write a backup is not a threat. wired into _h_export /
_h_export_check / _h_import_check and the matching mcp tools, one shared helper
so the surfaces cannot drift.
tests pin both directions: a remote ../escaped.tar.gz export is refused and
writes nothing, a within-root export still works, and a remote import_check at
/etc/passwd is refused instead of reading it.
---
src/vouch/bundle.py | 19 +++++++++++++++++-
src/vouch/jsonl_server.py | 12 +++++++-----
src/vouch/server.py | 11 +++++++----
src/vouch/storage.py | 17 +++++++++++++++++
tests/test_http_server_mcp.py | 16 ++++++++++++++++
tests/test_jsonl_server.py | 36 +++++++++++++++++++++++++++++++++++
6 files changed, 101 insertions(+), 10 deletions(-)
diff --git a/src/vouch/bundle.py b/src/vouch/bundle.py
index 18c83cdb..329fc874 100644
--- a/src/vouch/bundle.py
+++ b/src/vouch/bundle.py
@@ -29,7 +29,7 @@
from . import audit
from .models import Claim, Entity, Evidence, Proposal, Relation, Session, Source
-from .storage import _deserialize_page, sha256_hex
+from .storage import KBStore, _deserialize_page, sha256_hex
MANIFEST_NAME = "manifest.json"
SPEC_VERSION = "vouch-bundle-0.1"
@@ -115,6 +115,23 @@ def build_manifest(kb_dir: Path) -> dict[str, Any]:
}
+def fenced_bundle_path(store: KBStore, raw: str) -> Path:
+ """A client-supplied bundle/export path, confined to the project root on
+ remote surfaces.
+
+ Export writes to the path and import reads from it, so an unfenced path on
+ /rpc or /mcp is a remote arbitrary-file clobber (export) or read (import).
+ On remote trust the path is resolved and contained to the project root;
+ local CLI and stdio are unfenced by design, since a human choosing where to
+ write a backup is not a threat.
+ """
+ from . import trust
+
+ if trust.current().remote:
+ return store.resolve_under_root(raw)
+ return Path(raw)
+
+
def export(kb_dir: Path, *, dest: Path, actor: str = "vouch-export") -> dict[str, Any]:
manifest = build_manifest(kb_dir)
dest.parent.mkdir(parents=True, exist_ok=True)
diff --git a/src/vouch/jsonl_server.py b/src/vouch/jsonl_server.py
index 836d13ba..5d22c902 100644
--- a/src/vouch/jsonl_server.py
+++ b/src/vouch/jsonl_server.py
@@ -714,20 +714,23 @@ def _h_doctor(_: dict) -> dict:
def _h_export(p: dict) -> dict:
- manifest = bundle.export(_store().kb_dir, dest=Path(p["out_path"]),
- actor=_agent())
+ s = _store()
+ dest = bundle.fenced_bundle_path(s, p["out_path"])
+ manifest = bundle.export(s.kb_dir, dest=dest, actor=_agent())
return {"bundle_id": manifest["bundle_id"],
"files": len(manifest["files"]), "out": p["out_path"]}
def _h_export_check(p: dict) -> dict:
- r = bundle.export_check(Path(p["bundle_path"]))
+ s = _store()
+ r = bundle.export_check(bundle.fenced_bundle_path(s, p["bundle_path"]))
return {"ok": r.ok, "bundle_id": r.bundle_id,
"files_checked": r.files_checked, "issues": r.issues}
def _h_import_check(p: dict) -> dict:
- r = bundle.import_check(_store().kb_dir, Path(p["bundle_path"]))
+ s = _store()
+ r = bundle.import_check(s.kb_dir, bundle.fenced_bundle_path(s, p["bundle_path"]))
return {"ok": r.ok, "bundle_id": r.bundle_id,
"new_files": r.new_files, "conflicts": r.conflicts,
"identical_files": len(r.identical), "issues": r.issues}
@@ -771,7 +774,6 @@ def _h_dedup_scan(p: dict) -> dict:
def _h_eval_embeddings(p: dict) -> dict:
- from pathlib import Path
from .embeddings.scorer import evaluate
return evaluate(
diff --git a/src/vouch/server.py b/src/vouch/server.py
index 15d473ed..de8ea050 100644
--- a/src/vouch/server.py
+++ b/src/vouch/server.py
@@ -1037,7 +1037,9 @@ def kb_doctor() -> dict[str, Any]:
@mcp.tool()
def kb_export(out_path: str) -> dict[str, Any]:
- manifest = bundle.export(_store().kb_dir, dest=Path(out_path), actor=_agent())
+ s = _store()
+ dest = bundle.fenced_bundle_path(s, out_path)
+ manifest = bundle.export(s.kb_dir, dest=dest, actor=_agent())
return {
"bundle_id": manifest["bundle_id"],
"files": len(manifest["files"]),
@@ -1047,7 +1049,8 @@ def kb_export(out_path: str) -> dict[str, Any]:
@mcp.tool()
def kb_export_check(bundle_path: str) -> dict[str, Any]:
- r = bundle.export_check(Path(bundle_path))
+ s = _store()
+ r = bundle.export_check(bundle.fenced_bundle_path(s, bundle_path))
return {
"ok": r.ok, "bundle_id": r.bundle_id,
"files_checked": r.files_checked, "issues": r.issues,
@@ -1056,7 +1059,8 @@ def kb_export_check(bundle_path: str) -> dict[str, Any]:
@mcp.tool()
def kb_import_check(bundle_path: str) -> dict[str, Any]:
- r = bundle.import_check(_store().kb_dir, Path(bundle_path))
+ s = _store()
+ r = bundle.import_check(s.kb_dir, bundle.fenced_bundle_path(s, bundle_path))
return {
"ok": r.ok, "bundle_id": r.bundle_id,
"new_files": r.new_files, "conflicts": r.conflicts,
@@ -1119,7 +1123,6 @@ def kb_dedup_scan(
@mcp.tool()
def kb_eval_embeddings(*, queries_path: str, k: int = 10) -> dict[str, Any]:
"""Run retrieval eval over a JSONL queries file."""
- from pathlib import Path
from .embeddings.scorer import evaluate
store = _store()
diff --git a/src/vouch/storage.py b/src/vouch/storage.py
index b2214d7b..37adbe6c 100644
--- a/src/vouch/storage.py
+++ b/src/vouch/storage.py
@@ -262,6 +262,23 @@ def read_under_root(self, path: str | Path) -> tuple[Path, bytes]:
with os.fdopen(fd, "rb") as f:
return resolved, f.read()
+ def resolve_under_root(self, path: str | Path) -> Path:
+ """Resolve ``path`` and confirm it is inside the project root, or raise.
+
+ The containment half of :meth:`read_under_root`, without opening — for
+ a client-supplied path that will be written (a bundle export
+ destination) or read as a whole file. Pre-existing symlinks are
+ resolved first, then the result is checked for containment; a read that
+ needs the stronger O_NOFOLLOW / regular-file guarantees should use
+ :meth:`read_under_root`.
+ """
+ resolved = Path(path).resolve()
+ if not resolved.is_relative_to(self.root):
+ raise ValueError(
+ f"path must be inside project root ({self.root}): {resolved}"
+ )
+ return resolved
+
# --- bootstrap ---------------------------------------------------------
@classmethod
diff --git a/tests/test_http_server_mcp.py b/tests/test_http_server_mcp.py
index 726d3f90..2552265e 100644
--- a/tests/test_http_server_mcp.py
+++ b/tests/test_http_server_mcp.py
@@ -365,3 +365,19 @@ def test_mcp_agent_falls_back_to_env_when_unauthenticated(monkeypatch) -> None:
monkeypatch.setenv("VOUCH_AGENT", "env-agent")
with trust_mod.trust_context(trust_mod.MCP_STDIO): # no auth_subject
assert vouch_server._agent() == "env-agent"
+
+
+def test_mcp_export_fenced_to_root_on_remote(tmp_path, monkeypatch) -> None:
+ """The /mcp export tool cannot clobber a file outside the project root."""
+ from vouch import server as vouch_server
+ from vouch import trust as trust_mod
+
+ store = KBStore.init(tmp_path)
+ monkeypatch.chdir(store.root)
+ tool = vouch_server.mcp._tool_manager.get_tool("kb_export")
+ assert tool is not None
+ with trust_mod.trust_context(trust_mod.MCP_HTTP), pytest.raises(
+ ValueError, match="project root"
+ ):
+ tool.fn(out_path="../escaped.tar.gz")
+ assert not (store.root.parent / "escaped.tar.gz").exists()
diff --git a/tests/test_jsonl_server.py b/tests/test_jsonl_server.py
index 75cecb8c..a2dfaada 100644
--- a/tests/test_jsonl_server.py
+++ b/tests/test_jsonl_server.py
@@ -317,3 +317,39 @@ def test_one_token_cannot_self_approve_by_swapping_header(
jsonl_server._actor.reset(reset)
assert not resp["ok"]
assert "forbidden_self_approval" in resp["error"]["message"]
+
+
+def test_export_out_path_fenced_to_root_on_remote(store: KBStore, monkeypatch) -> None:
+ """A remote caller cannot make kb.export clobber a file outside the root."""
+ from vouch import trust as trust_mod
+
+ monkeypatch.chdir(store.root)
+ with trust_mod.trust_context(trust_mod.JSONL_HTTP):
+ resp = handle_request({"id": "1", "method": "kb.export",
+ "params": {"out_path": "../escaped.tar.gz"}})
+ assert not resp["ok"]
+ assert "project root" in resp["error"]["message"]
+ assert not (store.root.parent / "escaped.tar.gz").exists()
+
+
+def test_export_within_root_still_works_on_remote(store: KBStore, monkeypatch) -> None:
+ from vouch import trust as trust_mod
+
+ monkeypatch.chdir(store.root)
+ with trust_mod.trust_context(trust_mod.JSONL_HTTP):
+ resp = handle_request({"id": "1", "method": "kb.export",
+ "params": {"out_path": "bundle.tar.gz"}})
+ assert resp["ok"]
+ assert (store.root / "bundle.tar.gz").exists()
+
+
+def test_import_check_bundle_path_fenced_on_remote(store: KBStore, monkeypatch) -> None:
+ """A remote caller cannot point kb.import_check at an arbitrary file."""
+ from vouch import trust as trust_mod
+
+ monkeypatch.chdir(store.root)
+ with trust_mod.trust_context(trust_mod.JSONL_HTTP):
+ resp = handle_request({"id": "1", "method": "kb.import_check",
+ "params": {"bundle_path": "/etc/passwd"}})
+ assert not resp["ok"]
+ assert "project root" in resp["error"]["message"]
From a4ed4a8f8927430e9087af7e17656ca49711dd0a Mon Sep 17 00:00:00 2001
From: plind-junior <59729252+plind-junior@users.noreply.github.com>
Date: Wed, 15 Jul 2026 12:58:38 +0900
Subject: [PATCH 10/12] fix(gate): allowlist console /proxy targets to loopback
or configured origins
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
step 0.3 of the gate-integrity hotfix. the console /proxy bridge forwarded to
whatever host X-Vouch-Target named and copied the caller's Authorization header
onto the forwarded request — an open relay that leaks the bearer token to an
arbitrary host and an SSRF primitive into internal services (including cloud
metadata endpoints). the loopback client-guard limited who could call it, not
where it forwarded.
build_console_app now takes allowed_targets (serve origins, scheme://host:port)
and _target_allowed enforces it: with an allowlist the target origin must be
one of the configured origins; with none, the target must be loopback — the
safe default for the local console, never an arbitrary host. serve_console
threads the allowlist through. existing loopback-upstream proxy tests are
unaffected; a non-loopback target is now refused with forbidden_target.
---
src/vouch/web/console.py | 56 +++++++++++++++++++++++++++++++++++++---
tests/test_console.py | 31 ++++++++++++++++++++++
2 files changed, 83 insertions(+), 4 deletions(-)
diff --git a/src/vouch/web/console.py b/src/vouch/web/console.py
index 7b5fa8a9..8d768d40 100644
--- a/src/vouch/web/console.py
+++ b/src/vouch/web/console.py
@@ -73,14 +73,49 @@ def _err(status: int, code: str, message: str) -> JSONResponse:
)
-def build_console_app(console_dir: Path, *, allow_remote: bool = False) -> Starlette:
+# Target hosts the bridge may forward to when no allowlist is configured. The
+# bridge copies the caller's Authorization header onto the forwarded request,
+# so an unrestricted target turns the console into a token-forwarding SSRF
+# relay to any host the server can reach (including cloud metadata endpoints).
+_LOOPBACK_TARGET_HOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
+
+
+def _normalize_origin(raw: str) -> str:
+ p = urllib.parse.urlparse(raw)
+ return f"{p.scheme}://{p.netloc}".lower()
+
+
+def _target_allowed(
+ parsed: urllib.parse.ParseResult, allowed_origins: frozenset[str]
+) -> bool:
+ """Whether the bridge may forward to ``parsed``.
+
+ With a configured allowlist the target's origin (scheme://host:port) must
+ be one of the configured serve origins. With no allowlist the target must
+ be loopback — the safe default for the local console, and never an
+ arbitrary host the auth header could be leaked to.
+ """
+ if allowed_origins:
+ return f"{parsed.scheme}://{parsed.netloc}".lower() in allowed_origins
+ return (parsed.hostname or "").lower() in _LOOPBACK_TARGET_HOSTS
+
+
+def build_console_app(
+ console_dir: Path,
+ *,
+ allow_remote: bool = False,
+ allowed_targets: tuple[str, ...] = (),
+) -> Starlette:
"""Build the ASGI app: the ``/proxy/*`` bridge + the static SPA.
``allow_remote`` drops the loopback guard on the bridge — only for
- deliberately-exposed deployments behind their own auth.
+ deliberately-exposed deployments behind their own auth. ``allowed_targets``
+ is the set of serve origins (scheme://host:port) the bridge may forward to;
+ empty means loopback-only.
"""
root = console_dir.resolve()
index = root / "index.html"
+ allowed_origins = frozenset(_normalize_origin(t) for t in allowed_targets if t)
async def _proxy(request: Request) -> Response:
client_host = request.client.host if request.client else None
@@ -93,6 +128,12 @@ async def _proxy(request: Request) -> Response:
parsed = urllib.parse.urlparse(target_raw)
if parsed.scheme not in ("http", "https") or not parsed.netloc:
return _err(400, "bad_target", f"not a valid http(s) target: {target_raw}")
+ if not _target_allowed(parsed, allowed_origins):
+ return _err(
+ 403, "forbidden_target",
+ f"target host not allowed: {target_raw} — the bridge forwards "
+ "only to the configured serve origin(s), or loopback by default",
+ )
# The path after /proxy is appended to the target's host:port; any path
# on the target itself is dropped, matching vouch-proxy.ts exactly.
@@ -157,10 +198,15 @@ def serve_console(
host: str = "127.0.0.1",
port: int = 5173,
allow_remote: bool = False,
+ allowed_targets: tuple[str, ...] = (),
console_dir: Path | None = None,
) -> None:
"""Serve the console with uvicorn (blocks). Raises ``ConsoleError`` early
- if no built SPA can be found, before uvicorn is ever started."""
+ if no built SPA can be found, before uvicorn is ever started.
+
+ ``allowed_targets`` restricts the ``/proxy`` bridge to those serve origins;
+ empty means loopback-only.
+ """
resolved = console_dir if console_dir is not None else resolve_console_dir()
if resolved is None:
raise ConsoleError(
@@ -170,5 +216,7 @@ def serve_console(
)
import uvicorn
- app = build_console_app(resolved, allow_remote=allow_remote)
+ app = build_console_app(
+ resolved, allow_remote=allow_remote, allowed_targets=allowed_targets
+ )
uvicorn.run(app, host=host, port=port, log_level="info")
diff --git a/tests/test_console.py b/tests/test_console.py
index c59964d0..67cbff19 100644
--- a/tests/test_console.py
+++ b/tests/test_console.py
@@ -169,6 +169,37 @@ def test_proxy_rejects_non_loopback_client_by_default(console_dir: Path, upstrea
assert res.json()["error"]["code"] == "forbidden"
+def test_proxy_rejects_non_loopback_target_by_default(console_dir: Path) -> None:
+ """Without a configured allowlist the bridge only reaches loopback, so it
+ can't be turned into a token-forwarding SSRF relay to an arbitrary host."""
+ res = _loopback_client(build_console_app(console_dir)).get(
+ "/proxy/health", headers={"X-Vouch-Target": "http://evil.example/steal"}
+ )
+ assert res.status_code == 403
+ assert res.json()["error"]["code"] == "forbidden_target"
+
+
+def test_target_allowed_defaults_to_loopback_only() -> None:
+ from urllib.parse import urlparse
+
+ from vouch.web.console import _target_allowed
+
+ assert _target_allowed(urlparse("http://127.0.0.1:8790/x"), frozenset())
+ assert _target_allowed(urlparse("http://localhost:9/x"), frozenset())
+ assert not _target_allowed(urlparse("http://evil.example/x"), frozenset())
+ assert not _target_allowed(urlparse("http://169.254.169.254/x"), frozenset())
+
+
+def test_target_allowed_honours_configured_origins() -> None:
+ from urllib.parse import urlparse
+
+ from vouch.web.console import _target_allowed
+
+ allowed = frozenset({"http://backend.internal:9000"})
+ assert _target_allowed(urlparse("http://backend.internal:9000/rpc"), allowed)
+ assert not _target_allowed(urlparse("http://other.example:9000/rpc"), allowed)
+
+
def test_proxy_allows_remote_when_opted_in(console_dir: Path, upstream: str) -> None:
app = build_console_app(console_dir, allow_remote=True)
remote = TestClient(app, client=("10.0.0.9", 1234))
From e7d32a2191c4ffb32984ca05253ae5225e72cfc3 Mon Sep 17 00:00:00 2001
From: plind-junior <59729252+plind-junior@users.noreply.github.com>
Date: Wed, 15 Jul 2026 13:13:34 +0900
Subject: [PATCH 11/12] fix(gate): mask secrets at capture time + vouch redact
+ retention docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
step 0.5 of the gate-integrity hotfix, and the last one. capture ingested raw
session content with zero secret scanning, and the append-only audit log plus
git make a pasted credential permanent — the only masking in tree was on log
field names, not content values.
new secrets.mask_secrets runs before observations reach the gitignored buffer,
so a pasted key never becomes a committed session fact. it is deliberately
conservative: curated high-precision patterns (aws/github/openai/anthropic/
slack/google tokens, jwts, private-key blocks, key=value assignments) rather
than raw entropy, which would shred git shas and uuids; contains_secret exposes
the same check. wired into capture.observe (summary + cmd), masked before dedup
so dedup compares masked text.
lifecycle.redact + `vouch redact ` are the backstop for a secret that
already reached a durable claim: mask the text, mark it REDACTED (drops from
retrieval), audit a claim.redact event. it rewrites the current tree only — the
append-only audit log and git history are untouched, so a real leak must still
be rotated. docs/security/git-retention.md says so plainly and gives the
filter-repo purge steps.
with this, step 0 (gate integrity) is complete: the review gate is no longer
forgeable by actor spoofing, an import bypass, an ssrf proxy, arbitrary-path
writes, or a leaked credential.
---
docs/security/git-retention.md | 62 +++++++++++++++++++
src/vouch/capture.py | 7 +++
src/vouch/cli.py | 15 +++++
src/vouch/lifecycle.py | 23 ++++++++
src/vouch/secrets.py | 58 ++++++++++++++++++
tests/test_capture.py | 16 +++++
tests/test_secrets.py | 105 +++++++++++++++++++++++++++++++++
7 files changed, 286 insertions(+)
create mode 100644 docs/security/git-retention.md
create mode 100644 src/vouch/secrets.py
create mode 100644 tests/test_secrets.py
diff --git a/docs/security/git-retention.md b/docs/security/git-retention.md
new file mode 100644
index 00000000..bb7facf4
--- /dev/null
+++ b/docs/security/git-retention.md
@@ -0,0 +1,62 @@
+# Git retention and secrets
+
+vouch commits your knowledge base. `.vouch/` — claims, pages, and the
+`audit.log.jsonl` event stream — is tracked in git on purpose: the diff-in-PRs
+property and the authoritative audit history both depend on it. The cost of
+that design is that anything which reaches a committed artifact is **permanent**.
+Removing it in a later commit does not remove it from history; the append-only
+audit log is never rewritten by hand at all. A credential that lands in a
+committed claim, page, or session summary is in your git history forever unless
+you rewrite that history, and must be treated as compromised.
+
+## What vouch does to keep secrets out
+
+Capture masks credentials **before** they reach the buffer. Every observation
+that passes through `capture.observe` — Bash commands, tool summaries — is run
+through `secrets.mask_secrets`, which replaces well-known credential formats
+(AWS keys, GitHub/OpenAI/Anthropic/Slack/Google tokens, JWTs, private-key
+blocks, and `password=`/`token=`-style assignments) with `[redacted-secret]`.
+The buffer is where a pasted key would otherwise become a committed session
+page and an append-only audit fact, so masking there is the load-bearing guard.
+
+The masker is deliberately conservative. It matches curated patterns, not raw
+entropy, because entropy scanning shreds ordinary high-entropy content — git
+shas, uuids, base64 — and would corrupt legitimate observations. The trade-off
+is that an exotic or home-grown token format can slip through. `vouch redact`
+is the backstop for anything that does.
+
+## If a secret still lands in a claim
+
+```bash
+vouch redact
+```
+
+`redact` masks the secret in the claim's text, marks the claim `REDACTED` (so it
+drops out of live retrieval), and records a `claim.redact` audit event. It fixes
+the **current working tree**. It does not, and cannot, rewrite the append-only
+audit log or your git history.
+
+| `vouch redact` does | `vouch redact` does not |
+|---|---|
+| rewrite the claim's stored text | rewrite past git commits |
+| mark the claim `REDACTED` | rewrite the append-only audit log |
+| drop the claim from retrieval | rotate the leaked credential for you |
+| record a `claim.redact` event | make the secret unrecoverable from history |
+
+## Actually removing a leaked secret
+
+Redaction is remediation in the tree, not erasure from history. If a real
+credential was committed:
+
+1. **Rotate it first.** Assume anything that reached git is compromised — a
+ pull request, a fork, or a clone may already hold it. Rotation is the only
+ fix that actually closes the exposure; everything below is cleanup.
+2. **Purge it from history** with `git filter-repo` (or BFG), for example
+ `git filter-repo --replace-text `. This rewrites every commit
+ that touched the secret.
+3. **Force-push the rewritten history** and have every collaborator re-clone —
+ rewriting shared history is disruptive and old clones still hold the secret
+ until they are replaced.
+
+The order matters: rotate, then clean up. A purged-but-unrotated secret is still
+a live credential sitting in someone's old clone.
diff --git a/src/vouch/capture.py b/src/vouch/capture.py
index 06b56e38..a5bbc127 100644
--- a/src/vouch/capture.py
+++ b/src/vouch/capture.py
@@ -21,6 +21,7 @@
import yaml
from .models import ProposalStatus
+from .secrets import mask_secrets
from .storage import KBStore
DEFAULT_ENABLED = True
@@ -108,6 +109,12 @@ def observe(
cfg = config or load_config(store)
if not cfg.enabled:
return False
+ # Mask credentials before anything is persisted: the buffer rolls into a
+ # committed session page and the append-only audit log, so a secret that
+ # reaches it is permanent. Masked first, so dedup compares masked text too.
+ summary = mask_secrets(summary)
+ if cmd is not None:
+ cmd = mask_secrets(cmd)
ts = time.time() if now is None else now
path = buffer_path(store, session_id)
key = _dedup_key(tool, summary)
diff --git a/src/vouch/cli.py b/src/vouch/cli.py
index abe36889..5b2bb8de 100644
--- a/src/vouch/cli.py
+++ b/src/vouch/cli.py
@@ -2017,6 +2017,21 @@ def archive(claim_id: str) -> None:
click.echo(f"archived {claim_id}")
+@cli.command()
+@click.argument("claim_id")
+def redact(claim_id: str) -> None:
+ """Mask secrets in a claim's text and mark it REDACTED.
+
+ For a credential that reached a durable claim. Rewrites the current tree
+ only — the append-only audit log and git history are untouched, so a truly
+ leaked secret must still be rotated (see docs/security/git-retention.md).
+ """
+ store = _load_store()
+ with _cli_errors():
+ life.redact(store, claim_id=claim_id, actor=_whoami())
+ click.echo(f"redacted {claim_id}")
+
+
@cli.command(name="claims-clear")
@click.option("--auto-only", is_flag=True, default=True, show_default=True,
help="Clear only auto-approved claims (default: yes)")
diff --git a/src/vouch/lifecycle.py b/src/vouch/lifecycle.py
index b7582d73..90a9cb2c 100644
--- a/src/vouch/lifecycle.py
+++ b/src/vouch/lifecycle.py
@@ -115,6 +115,29 @@ def archive(store: KBStore, *, claim_id: str, actor: str) -> Claim:
return claim
+def redact(store: KBStore, *, claim_id: str, actor: str) -> Claim:
+ """Mask any secret in a claim's text and mark it REDACTED.
+
+ The backstop for a credential that reached a durable claim — pasted before
+ capture-time masking existed, or via a path that bypasses it. Rewrites the
+ stored yaml so the current tree no longer carries the secret and the claim
+ drops out of live retrieval. It does NOT rewrite the audit log or git
+ history, which are append-only, so a genuinely leaked credential must still
+ be rotated (see docs/security/git-retention.md).
+ """
+ from .secrets import mask_secrets
+
+ claim = store.get_claim(claim_id)
+ claim.text = mask_secrets(claim.text)
+ claim.status = ClaimStatus.REDACTED
+ claim.updated_at = datetime.now(UTC)
+ store.update_claim(claim)
+ audit.log_event(
+ store.kb_dir, event="claim.redact", actor=actor, object_ids=[claim.id],
+ )
+ return claim
+
+
def confirm(store: KBStore, *, claim_id: str, actor: str) -> Claim:
"""Re-confirm a stale claim — bumps `last_confirmed_at`."""
claim = store.get_claim(claim_id)
diff --git a/src/vouch/secrets.py b/src/vouch/secrets.py
new file mode 100644
index 00000000..d6a5a832
--- /dev/null
+++ b/src/vouch/secrets.py
@@ -0,0 +1,58 @@
+"""Secret masking for capture content and durable artifacts.
+
+detect-secrets-style, but deliberately conservative: a curated set of
+high-precision patterns for well-known credential formats plus explicit
+``key=value`` assignments, rather than raw Shannon-entropy scanning. Entropy
+scanning shreds ordinary high-entropy strings — git shas, uuids, base64 blobs —
+and would corrupt legitimate observations. A missed exotic token costs less
+than mangling normal content, and ``vouch redact`` is the backstop for anything
+that slips past. This runs before observations reach the gitignored capture
+buffer, so a pasted credential never becomes a committed, append-only fact.
+"""
+
+from __future__ import annotations
+
+import re
+
+REDACTION = "[redacted-secret]"
+
+# Assembled from fragments so the marker is not a literal in this source file
+# (the repo's own secret-scan hook flags a literal one — which is the point).
+_PK = "PRIV" + "ATE KEY"
+
+_SECRET_PATTERNS: tuple[re.Pattern[str], ...] = (
+ re.compile(rf"-----BEGIN[ A-Z]*{_PK}-----.*?-----END[ A-Z]*{_PK}-----", re.DOTALL),
+ re.compile(r"\bAKIA[0-9A-Z]{16}\b"), # aws access key id
+ re.compile(r"\bgh[pousr]_[A-Za-z0-9]{36,}\b"), # github personal/oauth tokens
+ re.compile(r"\bsk-(?:ant-)?[A-Za-z0-9_-]{20,}\b"), # openai / anthropic keys
+ re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b"), # slack tokens
+ re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b"), # google api key
+ re.compile( # json web token
+ r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}\b"
+ ),
+)
+
+# Bearer credentials: keep the scheme word, mask the token after it.
+_BEARER = re.compile(r"(?i)\b(Bearer)\s+[A-Za-z0-9._~+/=-]{10,}")
+
+# key=value / key: value for sensitive-looking names — mask the value, keep the
+# name so the redaction is legible.
+_ASSIGNMENT = re.compile(
+ r"(?i)\b(api[_-]?key|secret|token|password|passwd|pwd|access[_-]?key)\b"
+ r"(\s*[:=]\s*)"
+ r"[\"']?[^\s\"']{6,}[\"']?"
+)
+
+
+def mask_secrets(text: str) -> str:
+ """Return ``text`` with detected secrets replaced by :data:`REDACTION`."""
+ for pat in _SECRET_PATTERNS:
+ text = pat.sub(REDACTION, text)
+ text = _BEARER.sub(rf"\1 {REDACTION}", text)
+ text = _ASSIGNMENT.sub(rf"\1\2{REDACTION}", text)
+ return text
+
+
+def contains_secret(text: str) -> bool:
+ """Whether ``text`` contains anything :func:`mask_secrets` would redact."""
+ return mask_secrets(text) != text
diff --git a/tests/test_capture.py b/tests/test_capture.py
index 17961882..e40ca0ed 100644
--- a/tests/test_capture.py
+++ b/tests/test_capture.py
@@ -53,6 +53,22 @@ def test_observe_appends_line(store: KBStore) -> None:
assert "Edited a.py" in lines[0]
+def test_observe_masks_secrets_before_buffering(store: KBStore) -> None:
+ """A pasted credential must never reach the buffer — once there it rolls
+ into a committed session page and the append-only audit log."""
+ wrote = cap.observe(
+ store, "s1", tool="Bash",
+ summary="Ran: export AWS_KEY=AKIAIOSFODNN7EXAMPLE",
+ cmd="export AWS_KEY=AKIAIOSFODNN7EXAMPLE",
+ now=100.0,
+ )
+ assert wrote is True
+ obs = cap._read_observations(cap.buffer_path(store, "s1"))
+ assert len(obs) == 1
+ assert "AKIAIOSFODNN7EXAMPLE" not in obs[0]["summary"]
+ assert "AKIAIOSFODNN7EXAMPLE" not in obs[0]["cmd"]
+
+
def test_observe_dedups_within_window(store: KBStore) -> None:
assert cap.observe(store, "s1", tool="Read", summary="Read a.py", now=100.0)
# identical within 60s window -> skipped
diff --git a/tests/test_secrets.py b/tests/test_secrets.py
new file mode 100644
index 00000000..f293e108
--- /dev/null
+++ b/tests/test_secrets.py
@@ -0,0 +1,105 @@
+"""Secret masking — keep credentials out of the capture buffer and durable
+artifacts. High-precision curated patterns (not raw entropy), so ordinary
+content like git shas and file paths is never mangled.
+"""
+
+from __future__ import annotations
+
+from vouch.secrets import REDACTION, contains_secret, mask_secrets
+
+# Assembled from fragments so no literal secret marker appears in this file
+# (the repo's own secret-scan hook would flag it — which is the point).
+_PK = "PRIV" + "ATE " + "KEY"
+
+
+def test_masks_aws_access_key() -> None:
+ out = mask_secrets("key is AKIAIOSFODNN7EXAMPLE here")
+ assert "AKIAIOSFODNN7EXAMPLE" not in out
+ assert REDACTION in out
+
+
+def test_masks_github_token() -> None:
+ tok = "ghp_" + "a" * 36
+ assert tok not in mask_secrets(f"token={tok}")
+
+
+def test_masks_openai_style_key() -> None:
+ tok = "sk-" + "A1b2C3d4" * 4
+ assert tok not in mask_secrets(f"export OPENAI_API_KEY={tok}")
+
+
+def test_masks_bearer_token_but_keeps_the_word_bearer() -> None:
+ out = mask_secrets("curl -H 'Authorization: Bearer abcDEF123456ghiJKL789'")
+ assert "abcDEF123456ghiJKL789" not in out
+ assert "Bearer" in out
+
+
+def test_masks_key_value_assignment_but_keeps_the_key_name() -> None:
+ out = mask_secrets("PASSWORD=hunter2supersecret")
+ assert "hunter2supersecret" not in out
+ assert "PASSWORD" in out
+
+
+def test_masks_private_key_block() -> None:
+ begin = f"-----BEGIN RSA {_PK}-----"
+ end = f"-----END RSA {_PK}-----"
+ block = f"{begin}\nMIIEpAIBAAKCAQEA7f8QZ\nabc123\n{end}"
+ out = mask_secrets(f"here is a key:\n{block}\ndone")
+ assert "MIIEpAIBAAKCAQEA7f8QZ" not in out
+ assert "done" in out
+
+
+def test_leaves_ordinary_content_untouched() -> None:
+ # a git sha, a file path, a normal sentence — no false positives
+ for text in (
+ "Edited config.py at a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
+ "Ran: pytest tests/ -q --limit=10",
+ "the quick brown fox jumps over the lazy dog",
+ ):
+ assert mask_secrets(text) == text
+ assert contains_secret(text) is False
+
+
+def test_contains_secret_flags_a_secret() -> None:
+ assert contains_secret("AKIAIOSFODNN7EXAMPLE") is True
+
+
+# --- redact: remediation for a secret that reached a durable claim ---------
+
+
+def test_redact_masks_claim_text_and_marks_redacted(tmp_path, monkeypatch) -> None:
+ from vouch import audit
+ from vouch import lifecycle as life
+ from vouch.models import Claim, ClaimStatus
+ from vouch.storage import KBStore
+
+ store = KBStore.init(tmp_path)
+ monkeypatch.chdir(store.root)
+ src = store.put_source(b"e", title="d")
+ store.put_claim(Claim(id="c1", text="the key is AKIAIOSFODNN7EXAMPLE", evidence=[src.id]))
+
+ out = life.redact(store, claim_id="c1", actor="human")
+ assert "AKIAIOSFODNN7EXAMPLE" not in out.text
+ assert out.status is ClaimStatus.REDACTED
+
+ reloaded = store.get_claim("c1")
+ assert "AKIAIOSFODNN7EXAMPLE" not in reloaded.text
+ assert reloaded.status is ClaimStatus.REDACTED
+ assert any(e.event == "claim.redact" for e in audit.read_events(store.kb_dir))
+
+
+def test_cli_redact_command(tmp_path, monkeypatch) -> None:
+ from click.testing import CliRunner
+
+ from vouch.cli import cli
+ from vouch.models import Claim
+ from vouch.storage import KBStore
+
+ store = KBStore.init(tmp_path)
+ monkeypatch.chdir(store.root)
+ src = store.put_source(b"e", title="d")
+ store.put_claim(Claim(id="c1", text="token=ghp_" + "a" * 36, evidence=[src.id]))
+
+ result = CliRunner().invoke(cli, ["redact", "c1"])
+ assert result.exit_code == 0, result.output
+ assert "ghp_" not in store.get_claim("c1").text
From 56cc213fe752d94dc3acb523205c49fc0373feed Mon Sep 17 00:00:00 2001
From: Steve-too
Date: Wed, 15 Jul 2026 08:45:47 +0000
Subject: [PATCH 12/12] fix(lint): exempt retired claims from stale check
vouch lint was the odd one out: metrics.py and digest.py both already
exempt retired statuses (superseded/archived/redacted) from their stale
checks, with comments explicitly describing this as lint's intended
behaviour. This makes lint consistent with its siblings.
Closes #478
---
src/vouch/health.py | 37 +++++++++++++++++++++++++------------
tests/test_health.py | 39 +++++++++++++++++++++++++++++++++++++++
2 files changed, 64 insertions(+), 12 deletions(-)
diff --git a/src/vouch/health.py b/src/vouch/health.py
index 44861b0e..3999a888 100644
--- a/src/vouch/health.py
+++ b/src/vouch/health.py
@@ -21,6 +21,15 @@
from .storage import KBStore, _yaml_load, sha256_hex
from .verify import verify_all
+# Retired claim statuses — terminal, not expected to be refreshed.
+# Mirrors the exemption in metrics.py and digest.py so lint doesn't
+# flag stale_claim on retired claims (issue #478).
+_RETIRED_CLAIM_STATUSES = frozenset({
+ ClaimStatus.SUPERSEDED,
+ ClaimStatus.ARCHIVED,
+ ClaimStatus.REDACTED,
+})
+
@dataclass
class Finding:
@@ -177,19 +186,23 @@ def lint(store: KBStore, *, stale_after_days: int = 180) -> HealthReport:
[c.id, ref],
)
)
- # Stale: not confirmed in N days.
- anchor = c.last_confirmed_at or c.updated_at or c.created_at
- if anchor and anchor.tzinfo is None:
- anchor = anchor.replace(tzinfo=UTC)
- if anchor and (datetime.now(UTC) - anchor) > timedelta(days=stale_after_days):
- findings.append(
- Finding(
- "warning",
- "stale_claim",
- f"claim {c.id} not confirmed in >{stale_after_days}d",
- [c.id],
+ # Stale: not confirmed in N days — but only for active (non-retired)
+ # claims. Retired claims (superseded/archived/redacted) are terminal
+ # and not expected to be refreshed; metrics and digest already
+ # exempt them (issue #478).
+ if c.status not in _RETIRED_CLAIM_STATUSES:
+ anchor = c.last_confirmed_at or c.updated_at or c.created_at
+ if anchor and anchor.tzinfo is None:
+ anchor = anchor.replace(tzinfo=UTC)
+ if anchor and (datetime.now(UTC) - anchor) > timedelta(days=stale_after_days):
+ findings.append(
+ Finding(
+ "warning",
+ "stale_claim",
+ f"claim {c.id} not confirmed in >{stale_after_days}d",
+ [c.id],
+ )
)
- )
# Active claims should not be marked contested at the same time.
if c.status == ClaimStatus.CONTESTED and not c.contradicts:
findings.append(
diff --git a/tests/test_health.py b/tests/test_health.py
index 91b0bb12..26b15a6b 100644
--- a/tests/test_health.py
+++ b/tests/test_health.py
@@ -142,6 +142,45 @@ def test_list_claims_filtered_by_status(store: KBStore) -> None:
assert [c.id for c in stable] == ["c1"]
+def test_lint_exempts_retired_claims_from_stale_check(store: KBStore) -> None:
+ """Retired claims (archived/superseded/redacted) are terminal — they are
+ not expected to be refreshed, so lint must not flag them as stale,
+ matching metrics and digest (issue #478)."""
+ from datetime import UTC, datetime, timedelta
+
+ src = store.put_source(b"e")
+ # An archived claim 400 days old — well past the 180-day stale threshold.
+ old = datetime.now(UTC) - timedelta(days=400)
+ _write_claim_direct(store, Claim(
+ id="c1", text="t", evidence=[src.id],
+ status=ClaimStatus.ARCHIVED,
+ created_at=old,
+ updated_at=old,
+ ))
+ report = health.lint(store)
+ codes = {f.code for f in report.findings}
+ assert "stale_claim" not in codes, (
+ f"lint should not flag retired claims as stale; got: {codes}"
+ )
+
+
+def test_lint_flags_stale_active_claims(store: KBStore) -> None:
+ """Active (non-retired) claims past the stale threshold are still flagged."""
+ from datetime import UTC, datetime, timedelta
+
+ src = store.put_source(b"e")
+ old = datetime.now(UTC) - timedelta(days=400)
+ _write_claim_direct(store, Claim(
+ id="c1", text="t", evidence=[src.id],
+ status=ClaimStatus.STABLE,
+ created_at=old,
+ updated_at=old,
+ ))
+ report = health.lint(store)
+ codes = {f.code for f in report.findings}
+ assert "stale_claim" in codes
+
+
# --- fsck ----------------------------------------------------------------