Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,14 @@ Streamable HTTP; the v0.3 `guard` proxy adds deterministic runtime *result* insp

## [Unreleased]

### Community corpus layout (DSE-2143)

- `check --against-community` reads entries from `locks/schema-<N>/<ecosystem>/...`,
where `<N>` is the implemented lock schema (4). The schema-3 corpus written by 1.x
stays at `locks/<ecosystem>/...` and is no longer read: 2.0.0 and 2.1.0 refused every
entry there with `WRD-CONSENSUS-SCHEMA-MISMATCH`; it now reads as NOVEL until a
schema-4 entry exists. See `docs/COMMUNITY_CORPUS.md` §4.

## [2.1.0] — 2026-10-23

### Pagination (DSE-1539)
Expand Down
2 changes: 1 addition & 1 deletion SYSTEM_CONTEXT_DIAGRAM.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ sequenceDiagram
CI->>S: initialize · tools/list · resources/list · prompts/list
S-->>CI: declared surface → drift verdict vs warden.lock (unchanged path)
CI->>C: https/ssh clone @ --corpus-ref (protocol.allow=never, hooks off, "--") or local path
C-->>CI: attesters.json (discovery only) + locks/<eco>/<pkg>/<ver>/<id>.lock + .sigstore
C-->>CI: attesters.json (discovery only) + locks/schema-N/<eco>/<pkg>/<ver>/<id>.lock + .sigstore
CI->>CI: intersect with pin — unpinned id ignored (warn), divergent identity → exit 2
CI->>CI: confine paths under corpus root · size caps · schema_version == implemented
CI->>SG: verify each bundle over build_statement(overall_digest, DIRECTORY coordinate) for the pinned identity/issuer
Expand Down
13 changes: 10 additions & 3 deletions docs/COMMUNITY_CORPUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,11 +109,18 @@ written at a different `schema_version` than this mcp-warden implements is
## 4. Corpus layout

```
attesters.json discovery list (NOT the trust root)
locks/<ecosystem>/<segment>/<version>/<attester-id>.lock
locks/<ecosystem>/<segment>/<version>/<attester-id>.lock.sigstore
attesters.json discovery list (NOT the trust root)
locks/schema-<N>/<ecosystem>/<segment>/<version>/<attester-id>.lock
locks/schema-<N>/<ecosystem>/<segment>/<version>/<attester-id>.lock.sigstore
```

- `schema-<N>` is the lock `schema_version`. mcp-warden reads and writes only the
subtree for the schema it implements (`schema-4` since 2.2.0), so one append-only
corpus can carry several lock formats side by side. Schema-3 entries written by
mcp-warden 1.x sit at the legacy `locks/<ecosystem>/...` path and read as NOVEL to
2.x; a lock whose `schema_version` disagrees with its subtree is still
`WRD-CONSENSUS-SCHEMA-MISMATCH`.

- `ecosystem` ∈ `npm` | `pypi`.
- `segment` is the package name with `/` replaced by `__`, so the scoped npm package
`@example/clean` lives under `locks/npm/@example__clean/`. PyPI names are PEP 503
Expand Down
6 changes: 4 additions & 2 deletions src/mcp_warden/corpus.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@
Layout of a corpus checkout (``docs/COMMUNITY_CORPUS.md``)::

attesters.json discovery list, NOT the trust root
locks/<ecosystem>/<segment>/<version>/<attester-id>.lock
locks/<ecosystem>/<segment>/<version>/<attester-id>.lock.sigstore
locks/schema-<N>/<ecosystem>/<segment>/<version>/<attester-id>.lock
locks/schema-<N>/<ecosystem>/<segment>/<version>/<attester-id>.lock.sigstore

``<N>`` is the lock schema this mcp-warden implements; other schemas are never read.

This module owns fetching the corpus and orchestrating a run; entry verification
lives in :mod:`corpus_verify`, trust in :mod:`corpus_trust`. Every rule fails
Expand Down
10 changes: 8 additions & 2 deletions src/mcp_warden/corpus_coordinate.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,14 @@
from dataclasses import dataclass
from pathlib import PurePosixPath

from . import SCHEMA_VERSION
from .checks_supply import _is_flag, _is_local_path

#: Corpus subtree for the lock schema this mcp-warden reads and writes. Entries at
#: another schema live beside it (schema 3 at the legacy ``locks/<ecosystem>/...``)
#: and are never looked at, so an append-only corpus can carry several formats.
CORPUS_SCHEMA_DIR = f"schema-{SCHEMA_VERSION}"

#: Explicit ``--coordinate`` grammar: ``<ecosystem>:<name>@<version>``.
_EXPLICIT = re.compile(r"(?P<eco>npm|pypi):(?P<name>[^:]+)@(?P<ver>[^@/]+)\Z")
#: A concrete version: leading digit, then version chars (never a tag/range).
Expand All @@ -41,8 +47,8 @@ def path_segment(self) -> str:
return self.name.replace("/", "__")

def relative_dir(self) -> PurePosixPath:
"""``locks/<ecosystem>/<segment>/<version>`` inside a corpus checkout."""
return PurePosixPath("locks") / self.ecosystem / self.path_segment / self.version
"""``locks/schema-<N>/<ecosystem>/<segment>/<version>`` inside a corpus checkout."""
return PurePosixPath("locks") / CORPUS_SCHEMA_DIR / self.ecosystem / self.path_segment / self.version


def _clean(text: str) -> bool:
Expand Down
5 changes: 3 additions & 2 deletions tests/fixtures/gen_corpus.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@

sys.path.insert(0, "src")

from mcp_warden.corpus_coordinate import CORPUS_SCHEMA_DIR # noqa: E402
from mcp_warden.lockfile import read_lock # noqa: E402
from mcp_warden.signing import build_statement # noqa: E402

Expand All @@ -35,7 +36,7 @@ def attester(name: str) -> dict[str, str]:


def entry(segment: str, who: str, lock_src: Path, sidecar: str = "ok") -> None:
d = ROOT / "locks" / "npm" / segment / "1.0.0"
d = ROOT / "locks" / CORPUS_SCHEMA_DIR / "npm" / segment / "1.0.0"
d.mkdir(parents=True, exist_ok=True)
lock_path = d / f"{who}.lock"
shutil.copy(lock_src, lock_path)
Expand Down Expand Up @@ -75,7 +76,7 @@ def main() -> None:
entry("@example__nosig", "alice", CLEAN, sidecar="missing") # UNVERIFIABLE
entry("@example__corrupt", "alice", CLEAN, sidecar="corrupt") # UNVERIFIABLE
entry("@example__wrongsig", "alice", CLEAN, sidecar="wrong") # UNVERIFIABLE (verify fails)
stranger = ROOT / "locks" / "npm" / "@example__stranger" / "1.0.0" # undeclared attester
stranger = ROOT / "locks" / CORPUS_SCHEMA_DIR / "npm" / "@example__stranger" / "1.0.0" # undeclared attester
stranger.mkdir(parents=True)
shutil.copy(CLEAN, stranger / "mallory.lock")
(stranger / "mallory.lock.sigstore").write_text("{}\n")
Expand Down
32 changes: 21 additions & 11 deletions tests/test_corpus.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@
ATTESTERS = CORPUS / "attesters.json"
CLEAN_LOCK = read_lock(FIXTURES / "clean.warden.lock")
CLEAN_DIGEST = surface_digest(CLEAN_LOCK)
OTHER_DIGEST = surface_digest(read_lock(CORPUS / "locks/npm/@example__other/1.0.0/alice.lock"))
OTHER_DIGEST = surface_digest(read_lock(CORPUS / "locks/schema-4/npm/@example__other/1.0.0/alice.lock"))

CLEAN = Coordinate("npm", "@example/clean", "1.0.0")
OTHER = Coordinate("npm", "@example/other", "1.0.0")
Expand Down Expand Up @@ -164,7 +164,7 @@ def test_resolve_coordinate_from_argv(command, args, expected):
def test_explicit_coordinate_overrides_argv():
got = resolve_coordinate("node", ["./x.js"], explicit="npm:@example/clean@1.0.0")
assert got == CLEAN and got.path_segment == "@example__clean"
assert str(got.relative_dir()) == "locks/npm/@example__clean/1.0.0"
assert str(got.relative_dir()) == f"locks/schema-{SCHEMA_VERSION}/npm/@example__clean/1.0.0"


# --- trust (CSO C3) -----------------------------------------------------------
Expand Down Expand Up @@ -248,15 +248,25 @@ def test_relocated_sidecar_is_rejected(monkeypatch, tmp_path):
install_fake_verify(monkeypatch)
root = tmp_path / "corpus"
shutil.copytree(CORPUS, root)
src = root / "locks/npm/@example__clean/1.0.0"
dst = root / "locks/npm/@example__other/1.0.0"
src = root / "locks/schema-4/npm/@example__clean/1.0.0"
dst = root / "locks/schema-4/npm/@example__other/1.0.0"
shutil.copy(src / "alice.lock", dst / "alice.lock")
shutil.copy(src / "alice.lock.sigstore", dst / "alice.lock.sigstore")
with pytest.raises(CorpusError) as ei:
verified_digests(root, OTHER, consumer_pin())
assert ei.value.rule_id == RULE_UNVERIFIABLE and "signature did not verify" in str(ei.value)


def test_legacy_layout_entries_are_never_read(monkeypatch, tmp_path):
# DSE-2143: schema-3 entries sit at the legacy locks/<eco>/... path. A 2.x consumer
# looks only under locks/schema-<N>/, so they are NOVEL, never a schema mismatch.
install_fake_verify(monkeypatch)
root = tmp_path / "corpus"
shutil.copytree(CORPUS, root)
(root / "locks/schema-4/npm").rename(root / "locks/npm")
assert verified_digests(root, CLEAN, consumer_pin()) == {}


@pytest.mark.parametrize("name", ["@example/nosig", "@example/corrupt", "@example/wrongsig", "@example/stranger"])
def test_bad_entries_reject_the_whole_coordinate(monkeypatch, name):
install_fake_verify(monkeypatch)
Expand Down Expand Up @@ -287,7 +297,7 @@ def test_hostile_corpus_shapes_are_unverifiable_not_tracebacks(monkeypatch, tmp_
install_fake_verify(monkeypatch)
root = tmp_path / "corpus"
shutil.copytree(CORPUS, root)
d = root / "locks/npm/@example__clean/1.0.0"
d = root / "locks/schema-4/npm/@example__clean/1.0.0"
shutil.rmtree(d)
(d / "alice.lock").mkdir(parents=True)
with pytest.raises(CorpusError) as ei:
Expand All @@ -304,7 +314,7 @@ def test_size_caps(monkeypatch, tmp_path):
install_fake_verify(monkeypatch)
root = tmp_path / "corpus"
shutil.copytree(CORPUS, root)
d = root / "locks/npm/@example__clean/1.0.0"
d = root / "locks/schema-4/npm/@example__clean/1.0.0"
for target, cap in (
(d / "alice.lock", corpus_verify.MAX_LOCK_BYTES),
(d / "alice.lock.sigstore", corpus_verify.MAX_SIDECAR_BYTES),
Expand Down Expand Up @@ -348,7 +358,7 @@ def test_schema_version_mismatch_is_distinct(monkeypatch, tmp_path):
install_fake_verify(monkeypatch)
root = tmp_path / "corpus"
shutil.copytree(CORPUS, root)
p = root / "locks/npm/@example__clean/1.0.0/alice.lock"
p = root / "locks/schema-4/npm/@example__clean/1.0.0/alice.lock"
doc = json.loads(p.read_text())
doc["schema_version"] = SCHEMA_VERSION - 1
p.write_text(json.dumps(doc))
Expand All @@ -361,7 +371,7 @@ def test_pydantic_error_text_is_reduced_to_field_paths(monkeypatch, tmp_path):
install_fake_verify(monkeypatch)
root = tmp_path / "corpus"
shutil.copytree(CORPUS, root)
p = root / "locks/npm/@example__clean/1.0.0/alice.lock"
p = root / "locks/schema-4/npm/@example__clean/1.0.0/alice.lock"
doc = json.loads(p.read_text())
doc["overall_digest"] = "SECRET-LOOKING-VALUE-THAT-MUST-NOT-ECHO"
del doc["tools"]
Expand Down Expand Up @@ -622,7 +632,7 @@ def test_fetch_unreachable_url(monkeypatch, tmp_path):

def test_fixture_sidecars_are_not_real_bundles():
# The fixture corpus must never pass REAL verification: its sidecars are fakes.
sc = CORPUS / "locks/npm/@example__clean/1.0.0/alice.lock.sigstore"
sc = CORPUS / "locks/schema-4/npm/@example__clean/1.0.0/alice.lock.sigstore"
doc = json.loads(sc.read_text())
assert doc["over"] == build_statement(CLEAN_LOCK.overall_digest, "npm:@example/clean@1.0.0").decode()
assert "mediaType" not in doc # a real sigstore bundle carries mediaType
Expand All @@ -637,8 +647,8 @@ def test_surface_digest_is_launch_independent_and_signature_covers_it():

def test_tampered_entries_under_a_valid_signature_are_rejected(monkeypatch, tmp_path):
install_fake_verify(monkeypatch)
src = CORPUS / "locks/npm/@example__clean/1.0.0"
dst = tmp_path / "locks/npm/@example__clean/1.0.0"
src = CORPUS / "locks/schema-4/npm/@example__clean/1.0.0"
dst = tmp_path / "locks/schema-4/npm/@example__clean/1.0.0"
dst.mkdir(parents=True)
shutil.copy(ATTESTERS, tmp_path / "attesters.json")
shutil.copy(src / "alice.lock.sigstore", dst / "alice.lock.sigstore")
Expand Down
Loading