scpe-protocol 0.2.1__tar.gz → 0.2.2__tar.gz

{scpe_protocol-0.2.1/scpe_protocol.egg-info → scpe_protocol-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scpe-protocol
-Version: 0.2.1
+Version: 0.2.2
 Summary: SCPE: an open protocol for verifiable provenance of any digital artifact — who signed a contribution or file, what they declared about AI use, and that nothing was tampered with, verified offline with no server and no new accounts. Ships the single-file reference verifier, its producer, and a CLI (`scpe`) that seals a pull request from it.
 Author: Augusto Bastos
 License-Expression: Apache-2.0
@@ -44,7 +44,7 @@ Dynamic: license-file
   <img alt="spec" src="https://img.shields.io/badge/spec-scpe%2F0.1-41c257?style=flat-square&labelColor=0b0b0c">
   <img alt="python" src="https://img.shields.io/badge/python-3.11%2B-41c257?style=flat-square&labelColor=0b0b0c">
   <img alt="license" src="https://img.shields.io/badge/code-Apache--2.0-41c257?style=flat-square&labelColor=0b0b0c">
-  <img alt="status" src="https://img.shields.io/badge/v0.2.1-early-d29922?style=flat-square&labelColor=0b0b0c">
+  <img alt="status" src="https://img.shields.io/badge/v0.2.2-early-d29922?style=flat-square&labelColor=0b0b0c">
 </p>
 
 <p align="center">
@@ -150,6 +150,16 @@ SLSA uses to sell levels. See [docs/LEVELS.md](docs/LEVELS.md).
    (target repo, base commit, a SHA-256 of the exact diff, an AI-use disclosure, and an
    optional attribution record) signed with the SSH key already on their GitHub profile
    (`ssh-keygen -Y sign -n scpe/0.1`). No new account.
+
+   > **The key has to be published as an authentication key.** `forge` verification reads
+   > `github.com/<login>.keys`, and GitHub serves only authentication keys there — a key added
+   > under *Signing keys* is real, is used by `git`, and **never appears at that URL**, so a
+   > contribution signed with it can only ever reach `key_source: bundled`. Add it with
+   > `gh ssh-key add <key>.pub --title scpe` (no `--type signing`). GitHub does publish signing
+   > keys, at `api.github.com/users/<login>/ssh_signing_keys`, but `<host>/<login>.keys` is the
+   > shape the fixed provider table is built on; reading the signing-key endpoint per provider is
+   > open, not decided. Filing the key in the obviously-correct place and silently losing forge
+   > verification is the first thing that went wrong for the protocol's own author.
 2. It travels inside a **normal pull request** — the diff in the branch, the ~1–2 KB signed
    attestation embedded in the PR body. Merging leaves the repo history clean.
 3. The **owner's side** re-derives everything itself, with no SCPE server involved: the diff's
@@ -194,20 +204,36 @@ Add a workflow that verifies every PR and posts a seal. Set `require` to gate me
 ```yaml
 # .github/workflows/scpe.yml — the step. Copy BOTH files from docs/workflows/ for the
 # fork-safe version: scpe.yml (verify) and its companion scpe-seal.yml (post the seal).
-- uses: augbastos/scpe@v0.2.1
+- uses: augbastos/scpe@v0.2.2
   with:
     level: "1"        # 1 = disclosure lint · 2 = signed envelope required
     require: "true"   # fail the check on anything not verifiable
 ```
 
-Pin the exact tag while the protocol is pre-1.0. Every tag here is an **immutable alias** — it
-points at one commit and is never moved, so a fix arrives as a new tag you adopt by editing the
-pin, not as a silent change under the one you already wrote. `v0.2.1` is that in practice: `v0.2`
-shipped a seal banner that read `VERIFIED` on unattested PRs and a workflow template GitHub
-refuses to register, and both were fixed by publishing a new tag rather than by moving the old
-one. The `v0.2` line is also the first in which the Action verifies the `scpe/0.1` envelope
-itself; `v0.1.x` verified a different, now-removed format, so upgrading from it is a behaviour
-change and not a patch — [docs/MIGRATION.md](docs/MIGRATION.md) has the steps.
+### Version policy
+
+Pin the exact tag while the protocol is pre-1.0.
+
+- **Every tag is an immutable alias.** It points at one commit and is never moved. A fix
+  arrives as a *new* tag you adopt by editing the pin, never as a silent change under the one
+  you already wrote. Both `v0.2.1` and `v0.2.2` exist for that reason rather than because
+  `v0.2` was re-pointed.
+- **The cost is that fixes do not reach you on their own** — including security fixes. Watch
+  the releases, or let Dependabot's `github-actions` ecosystem open the bump as a pull
+  request you can read before merging.
+- **A patch tag can change behaviour when the old behaviour was wrong.** `v0.2.2` refuses
+  contributions that `v0.2.1` accepted, because `v0.2.1` accepted some it should not have.
+  Read the [CHANGELOG](CHANGELOG.md) before moving a pin; "patch" here means the protocol
+  did not change, not that nothing did.
+- **`spec_version` is a separate number from the tag.** The protocol is `scpe/0.1` across
+  every `v0.2.x` release. See [CHANGELOG.md](CHANGELOG.md) for the three axes and why
+  reading one as the other is the easiest mistake to make here.
+- **The `v0.1.x` line is legacy, not merely old.** It verifies an envelope format that is not
+  in `spec/`, so upgrading from it is a behaviour change and not a patch —
+  [docs/MIGRATION.md](docs/MIGRATION.md) has the steps.
+
+**Which tag to be on:** `v0.2.2`. `v0.2.1` and `v0.2` accept a valid envelope replayed from
+another repository (see [SECURITY.md](SECURITY.md)); `v0.2.2` refuses it.
 
 The Action uses a fork-safe two-job split, and the two jobs live in **two files**: the untrusted
 job in `scpe.yml` (which runs contributor code) holds no secrets, and only the trusted follow-up
@@ -253,10 +279,14 @@ vector reaches the `forge` anchor.
 |---|---|
 | PR-body attestation (manifest + sig, base64) | 1.1–1.5 KB |
 | Standalone envelope (3-file / 27-line PR, zipped) | ~1.5 KB |
-| Verify wall-time | ~210 ms cold CLI · ~39 ms in a warm process |
+| Verify wall-time | ~200 ms cold process · ~31 ms warm |
 
 An `artifact` subject adds its payload size on top of ~800 B fixed overhead. Order-of-magnitude,
-single machine — not a formal benchmark suite.
+single machine — not a formal benchmark suite. Re-run it yourself rather than taking the number:
+`python tests/bench_verify.py <envelope.zip> --keys <login.keys>` prints the median of 15 runs
+for both paths. The cold figure is a fresh interpreter per run; the warm one re-verifies
+in-process, which is what a batch consumer sees after import cost is paid once. Both use the
+`flag` anchor, so no network is in the measurement.
 
 ## Where it sits
 
@@ -268,13 +298,16 @@ single machine — not a formal benchmark suite.
 - **A different layer from build provenance.** Sigstore / SLSA / in-toto attest *artifacts and
   builds*; SCPE attests a *contribution*, at the pull-request boundary.
 - **Direct prior art:** `patatt` + `b4` ([kernel.org](https://github.com/mricon/patatt)) have run
-  this exact pattern — self-sign a patch with a key the platform publishes, verify independently,
-  no CA, no server — on the Linux kernel's mailing list for years. SCPE applies the same shape to
-  the GitHub pull-request boundary.
+  this shape — the contributor self-signs a patch, the recipient verifies independently, no CA,
+  no server — on the Linux kernel's mailing list for years. They differ from SCPE in where the
+  key comes from: `patatt` keeps a keyring in the repository, so the project curates who may
+  sign; SCPE reads the keys the forge already publishes for the account, so there is nothing to
+  curate and nothing to depend on but the forge. Same shape, different trust root, applied to
+  the pull-request boundary instead of a mailing list.
 
 ## Status
 
-**v0.2.1 — early.** This is a specification plus a reference implementation (a single-file
+**v0.2.2 — early.** This is a specification plus a reference implementation (a single-file
 verifier, a producer, and a maintainer-side Action). The full test suite — including a 100-PR
 stress proof and a local end-to-end — runs on every push; the CI badge above is its live
 result. Two more independent verifiers, in Go and Rust, reach the same verdict as the Python
@@ -288,7 +321,7 @@ accept. There is **no external adoption yet**. It is not a hosted service and ne
 **`v0.1.x` is legacy: its signed-envelope path verifies a format that is not in this spec.** The
 Action at those tags checked a second envelope format that shipped inside the package and was
 deleted in `0.2.0`. A workflow still pinned there does not fail — it keeps posting seals for a
-format nothing here produces, and once `0.2.0` reaches PyPI it breaks instead, because that
+format nothing here produces — and now that `0.2.x` is on PyPI it breaks outright instead, because that
 Action resolved its verifier from the package index at run time rather than from its own
 checkout. [CHANGELOG.md](CHANGELOG.md) has what moved; [docs/MIGRATION.md](docs/MIGRATION.md)
 has what to do about it.

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2}/README.md

@@ -16,7 +16,7 @@
   <img alt="spec" src="https://img.shields.io/badge/spec-scpe%2F0.1-41c257?style=flat-square&labelColor=0b0b0c">
   <img alt="python" src="https://img.shields.io/badge/python-3.11%2B-41c257?style=flat-square&labelColor=0b0b0c">
   <img alt="license" src="https://img.shields.io/badge/code-Apache--2.0-41c257?style=flat-square&labelColor=0b0b0c">
-  <img alt="status" src="https://img.shields.io/badge/v0.2.1-early-d29922?style=flat-square&labelColor=0b0b0c">
+  <img alt="status" src="https://img.shields.io/badge/v0.2.2-early-d29922?style=flat-square&labelColor=0b0b0c">
 </p>
 
 <p align="center">
@@ -122,6 +122,16 @@ SLSA uses to sell levels. See [docs/LEVELS.md](docs/LEVELS.md).
    (target repo, base commit, a SHA-256 of the exact diff, an AI-use disclosure, and an
    optional attribution record) signed with the SSH key already on their GitHub profile
    (`ssh-keygen -Y sign -n scpe/0.1`). No new account.
+
+   > **The key has to be published as an authentication key.** `forge` verification reads
+   > `github.com/<login>.keys`, and GitHub serves only authentication keys there — a key added
+   > under *Signing keys* is real, is used by `git`, and **never appears at that URL**, so a
+   > contribution signed with it can only ever reach `key_source: bundled`. Add it with
+   > `gh ssh-key add <key>.pub --title scpe` (no `--type signing`). GitHub does publish signing
+   > keys, at `api.github.com/users/<login>/ssh_signing_keys`, but `<host>/<login>.keys` is the
+   > shape the fixed provider table is built on; reading the signing-key endpoint per provider is
+   > open, not decided. Filing the key in the obviously-correct place and silently losing forge
+   > verification is the first thing that went wrong for the protocol's own author.
 2. It travels inside a **normal pull request** — the diff in the branch, the ~1–2 KB signed
    attestation embedded in the PR body. Merging leaves the repo history clean.
 3. The **owner's side** re-derives everything itself, with no SCPE server involved: the diff's
@@ -166,20 +176,36 @@ Add a workflow that verifies every PR and posts a seal. Set `require` to gate me
 ```yaml
 # .github/workflows/scpe.yml — the step. Copy BOTH files from docs/workflows/ for the
 # fork-safe version: scpe.yml (verify) and its companion scpe-seal.yml (post the seal).
-- uses: augbastos/scpe@v0.2.1
+- uses: augbastos/scpe@v0.2.2
   with:
     level: "1"        # 1 = disclosure lint · 2 = signed envelope required
     require: "true"   # fail the check on anything not verifiable
 ```
 
-Pin the exact tag while the protocol is pre-1.0. Every tag here is an **immutable alias** — it
-points at one commit and is never moved, so a fix arrives as a new tag you adopt by editing the
-pin, not as a silent change under the one you already wrote. `v0.2.1` is that in practice: `v0.2`
-shipped a seal banner that read `VERIFIED` on unattested PRs and a workflow template GitHub
-refuses to register, and both were fixed by publishing a new tag rather than by moving the old
-one. The `v0.2` line is also the first in which the Action verifies the `scpe/0.1` envelope
-itself; `v0.1.x` verified a different, now-removed format, so upgrading from it is a behaviour
-change and not a patch — [docs/MIGRATION.md](docs/MIGRATION.md) has the steps.
+### Version policy
+
+Pin the exact tag while the protocol is pre-1.0.
+
+- **Every tag is an immutable alias.** It points at one commit and is never moved. A fix
+  arrives as a *new* tag you adopt by editing the pin, never as a silent change under the one
+  you already wrote. Both `v0.2.1` and `v0.2.2` exist for that reason rather than because
+  `v0.2` was re-pointed.
+- **The cost is that fixes do not reach you on their own** — including security fixes. Watch
+  the releases, or let Dependabot's `github-actions` ecosystem open the bump as a pull
+  request you can read before merging.
+- **A patch tag can change behaviour when the old behaviour was wrong.** `v0.2.2` refuses
+  contributions that `v0.2.1` accepted, because `v0.2.1` accepted some it should not have.
+  Read the [CHANGELOG](CHANGELOG.md) before moving a pin; "patch" here means the protocol
+  did not change, not that nothing did.
+- **`spec_version` is a separate number from the tag.** The protocol is `scpe/0.1` across
+  every `v0.2.x` release. See [CHANGELOG.md](CHANGELOG.md) for the three axes and why
+  reading one as the other is the easiest mistake to make here.
+- **The `v0.1.x` line is legacy, not merely old.** It verifies an envelope format that is not
+  in `spec/`, so upgrading from it is a behaviour change and not a patch —
+  [docs/MIGRATION.md](docs/MIGRATION.md) has the steps.
+
+**Which tag to be on:** `v0.2.2`. `v0.2.1` and `v0.2` accept a valid envelope replayed from
+another repository (see [SECURITY.md](SECURITY.md)); `v0.2.2` refuses it.
 
 The Action uses a fork-safe two-job split, and the two jobs live in **two files**: the untrusted
 job in `scpe.yml` (which runs contributor code) holds no secrets, and only the trusted follow-up
@@ -225,10 +251,14 @@ vector reaches the `forge` anchor.
 |---|---|
 | PR-body attestation (manifest + sig, base64) | 1.1–1.5 KB |
 | Standalone envelope (3-file / 27-line PR, zipped) | ~1.5 KB |
-| Verify wall-time | ~210 ms cold CLI · ~39 ms in a warm process |
+| Verify wall-time | ~200 ms cold process · ~31 ms warm |
 
 An `artifact` subject adds its payload size on top of ~800 B fixed overhead. Order-of-magnitude,
-single machine — not a formal benchmark suite.
+single machine — not a formal benchmark suite. Re-run it yourself rather than taking the number:
+`python tests/bench_verify.py <envelope.zip> --keys <login.keys>` prints the median of 15 runs
+for both paths. The cold figure is a fresh interpreter per run; the warm one re-verifies
+in-process, which is what a batch consumer sees after import cost is paid once. Both use the
+`flag` anchor, so no network is in the measurement.
 
 ## Where it sits
 
@@ -240,13 +270,16 @@ single machine — not a formal benchmark suite.
 - **A different layer from build provenance.** Sigstore / SLSA / in-toto attest *artifacts and
   builds*; SCPE attests a *contribution*, at the pull-request boundary.
 - **Direct prior art:** `patatt` + `b4` ([kernel.org](https://github.com/mricon/patatt)) have run
-  this exact pattern — self-sign a patch with a key the platform publishes, verify independently,
-  no CA, no server — on the Linux kernel's mailing list for years. SCPE applies the same shape to
-  the GitHub pull-request boundary.
+  this shape — the contributor self-signs a patch, the recipient verifies independently, no CA,
+  no server — on the Linux kernel's mailing list for years. They differ from SCPE in where the
+  key comes from: `patatt` keeps a keyring in the repository, so the project curates who may
+  sign; SCPE reads the keys the forge already publishes for the account, so there is nothing to
+  curate and nothing to depend on but the forge. Same shape, different trust root, applied to
+  the pull-request boundary instead of a mailing list.
 
 ## Status
 
-**v0.2.1 — early.** This is a specification plus a reference implementation (a single-file
+**v0.2.2 — early.** This is a specification plus a reference implementation (a single-file
 verifier, a producer, and a maintainer-side Action). The full test suite — including a 100-PR
 stress proof and a local end-to-end — runs on every push; the CI badge above is its live
 result. Two more independent verifiers, in Go and Rust, reach the same verdict as the Python
@@ -260,7 +293,7 @@ accept. There is **no external adoption yet**. It is not a hosted service and ne
 **`v0.1.x` is legacy: its signed-envelope path verifies a format that is not in this spec.** The
 Action at those tags checked a second envelope format that shipped inside the package and was
 deleted in `0.2.0`. A workflow still pinned there does not fail — it keeps posting seals for a
-format nothing here produces, and once `0.2.0` reaches PyPI it breaks instead, because that
+format nothing here produces — and now that `0.2.x` is on PyPI it breaks outright instead, because that
 Action resolved its verifier from the package index at run time rather than from its own
 checkout. [CHANGELOG.md](CHANGELOG.md) has what moved; [docs/MIGRATION.md](docs/MIGRATION.md)
 has what to do about it.

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scpe-protocol"
-version = "0.2.1"
+version = "0.2.2"
 description = "SCPE: an open protocol for verifiable provenance of any digital artifact — who signed a contribution or file, what they declared about AI use, and that nothing was tampered with, verified offline with no server and no new accounts. Ships the single-file reference verifier, its producer, and a CLI (`scpe`) that seals a pull request from it."
 readme = "README.md"
 requires-python = ">=3.11"

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2}/reference/standalone/verify_envelope.py

@@ -292,12 +292,42 @@ def fetch_keys(host: str, subject: str) -> bytes:
 
 # --------------------------------------------- allowed signers + SSHSIG (§8.5-6)
 
+def key_fingerprint(key_line: str) -> str | None:
+    """The SHA256 fingerprint OpenSSH reports for one authorized-keys line, or None."""
+    with tempfile.TemporaryDirectory(prefix="scpe-fp-") as td:
+        pub = Path(td) / "k.pub"
+        pub.write_text(key_line.strip() + "\n", encoding="utf-8")
+        proc = subprocess.run(["ssh-keygen", "-lf", str(pub)], capture_output=True)
+    if proc.returncode != 0:
+        return None
+    parts = proc.stdout.decode("utf-8", "replace").split()
+    return parts[1] if len(parts) > 1 else None
+
+
 def verify_signature(manifest_bytes: bytes, sig_bytes: bytes,
-                     subject: str, keys_bytes: bytes) -> bool:
+                     subject: str, keys_bytes: bytes,
+                     declared_fingerprint: str | None = None) -> bool:
     key_lines = [ln.strip() for ln in keys_bytes.decode("utf-8").splitlines()
                  if ln.strip()]
     if not key_lines:
         return False
+    # `contributor.key_fingerprint` is a MUST field, and §14 says the manifest *binds* it —
+    # but nothing read it, so a signed field could say anything without consequence. An
+    # account publishing keys A and B could ship a manifest naming A, sign with B, and
+    # verify: the audit record then names a key that did not sign it. Restricting the
+    # allowed signers to the declared key makes the field load-bearing, and a pass then
+    # means "the key this manifest names is published by this account AND produced this
+    # signature" rather than "some key it publishes did".
+    #
+    # A declared fingerprint absent from the published set yields `signature-invalid`, not
+    # a new status: the signature cannot be validated against the key the manifest names.
+    # That is what the `wrong-identity` vector already expects, so none of the eighteen
+    # normative expectations move.
+    if declared_fingerprint:
+        key_lines = [ln for ln in key_lines
+                     if key_fingerprint(ln) == declared_fingerprint]
+        if not key_lines:
+            return False
     signers = "".join(
         f'{subject} namespaces="{NAMESPACE}" {ln}\n' for ln in key_lines)
     with tempfile.TemporaryDirectory(prefix="scpe-verify-") as td:
@@ -453,9 +483,17 @@ def verify(path: Path, keys_file: Path | None, diff_file: Path | None,
     # anchor this verdict rests on, so `no published keys` above reports no key_source.
     key_source = source
 
-    # 5-6. allowed signers + SSHSIG
-    if not verify_signature(manifest_bytes, sig_bytes, subject, keys_bytes):
-        return R("signature-invalid", "SSHSIG verification failed")
+    # 5-6. allowed signers + SSHSIG, restricted to the key the manifest names.
+    #      The declared fingerprint is inside the signed bytes, so an attacker cannot point
+    #      it at a different key without invalidating the very signature it gates.
+    declared_fp = contributor.get("key_fingerprint") if isinstance(contributor, dict) else None
+    declared_fp = declared_fp if isinstance(declared_fp, str) and declared_fp.strip() else None
+    if not verify_signature(manifest_bytes, sig_bytes, subject, keys_bytes,
+                            declared_fingerprint=declared_fp):
+        return R("signature-invalid",
+                 "SSHSIG verification failed"
+                 if declared_fp else
+                 "SSHSIG verification failed (manifest declares no key_fingerprint)")
 
     # 7. subject integrity — dispatch on the SIGNED subject.type (SPEC §6). The
     #    signature (step 5-6) already proved the subject block is authentic, so we now

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2}/scpe/__init__.py

@@ -13,4 +13,4 @@ from a checkout (`PYTHONPATH=<action_path> python3 -m scpe.cli`), so a CI job ve
 with the exact bytes of the tag it pinned rather than whatever a package index serves
 at that moment.
 """
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2}/scpe/cli.py

@@ -30,7 +30,8 @@ import tempfile
 from pathlib import Path
 
 from reference.standalone import verify_envelope as _ref
-from scpe import __version__, results as _results, seal as _seal, testrun, verify as _verify
+from scpe import (__version__, context as _context, results as _results, seal as _seal,
+                  testrun, verify as _verify)
 from scpe.optin import init_repo
 
 
@@ -94,9 +95,18 @@ def _cmd_seal(args) -> int:
         diff = ""
         if resolved.diff is not None:
             diff = resolved.diff.read_text(encoding="utf-8", errors="replace")
+        # Read the manifest for context ONLY after the signature verified. Before that it is
+        # attacker-controlled JSON, and comparing an unauthenticated `target.repo` against
+        # the checkout would be theatre — the attacker picks both sides.
+        ctx = None
+        if result.status == _results.VERIFIED and (args.expect_repo or args.expect_base):
+            ctx = _context.check(
+                manifest=_results.signed_manifest(resolved.path),
+                repo_dir=Path(args.repo), head=args.head,
+                expect_repo=args.expect_repo, expect_base=args.expect_base)
         data = _results.build_results(
             result, path=resolved.path, diff=diff, diff_source=resolved.diff_source,
-            diff_note=resolved.note,
+            diff_note=resolved.note, context=ctx,
             # Parsed exactly like reference/level1_lint.py parses $REQUIRE, and deliberately
             # NOT an argparse `choices=` list: a caller who writes `require: True` in YAML
             # must get an informational run, not an argparse exit 2 that kills the untrusted
@@ -222,6 +232,16 @@ def main(argv: list[str] | None = None) -> int:
     sl.add_argument("--keys", default=None,
                     help="offline key list; forces key_source=flag, which the seal displays")
     sl.add_argument("--artifact", default=None, help="artifact bytes for an `artifact` subject")
+    sl.add_argument("--expect-repo", default=None, metavar="OWNER/NAME",
+                    help="require the manifest's signed target.repo to be this repository, "
+                         "case-insensitively. Without it the signed target is reported and "
+                         "never compared, which lets a valid envelope from another "
+                         "repository verify here. CI should always pass it.")
+    sl.add_argument("--expect-base", action="store_true",
+                    help="require the manifest's signed base_sha to be an ancestor of "
+                         "--head. Ancestry rather than equality: the base branch tip moves "
+                         "whenever anything merges, while the commit the contributor "
+                         "diffed from does not.")
     sl.add_argument("--run-tests", action="store_true",
                     help="run the repo's own test suite in this checkout")
     sl.add_argument("--require", default="false",

scpe_protocol-0.2.2/scpe/context.py

@@ -0,0 +1,123 @@
+"""Bind a verified envelope to the pull request it is being presented on.
+
+The signature proves the manifest is authentic and the diff digest proves the change was
+not altered. Neither proves the contribution is being presented *where it was signed for*.
+The manifest carries `subject.target.repo` and `subject.target.base_sha` precisely so that
+question can be answered, and until this module existed those two fields were read, copied
+into results.json, and never compared with anything.
+
+The gap that leaves is a replay: lift the attestation off a public pull request, open a
+pull request on a different repository whose diff normalizes to the same bytes, and the
+seal reports `verified` with the original signer's name on it. The signature is genuine,
+the digest matches, and the context is wrong. Reproduced before this was written.
+
+Two checks, deliberately of different shapes:
+
+* **repo** — string equality against the repository the workflow is running in, case-folded
+  because forges treat `Owner/Name` and `owner/name` as one repository.
+
+* **base** — *ancestry*, not equality. `github.event.pull_request.base.sha` is the tip of
+  the base branch at event time and moves whenever anyone merges anything, so demanding it
+  equal the signed `base_sha` would fail every open pull request the moment the branch
+  advanced. What the signature actually commits to is a commit the contributor diffed from,
+  and the honest question is whether that commit is in this pull request's history at all.
+  The diff digest already pins *what* changed; ancestry pins *where it came from*.
+
+Both are policy, enforced at the gate, and neither is a SPEC §8 status: the eight statuses
+are the conformance contract three implementations agree on, and a context mismatch is a
+property of the presentation rather than of the envelope. An envelope that fails these is
+still a perfectly valid envelope — somewhere else.
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ContextCheck:
+    """The outcome of binding an envelope to where it was presented.
+
+    `ok` is True when nothing contradicted the signed context — including when there was
+    nothing to check, so callers that never supply expectations behave exactly as before.
+    `checked` says whether any comparison actually ran, so a caller can tell "matched" from
+    "no expectation given" instead of reading an unqualified pass.
+    """
+
+    ok: bool
+    checked: bool
+    detail: str = ""
+
+    @property
+    def mismatch(self) -> bool:
+        return self.checked and not self.ok
+
+
+def _same_repo(signed: str, expected: str) -> bool:
+    return signed.strip().casefold() == expected.strip().casefold()
+
+
+def _is_ancestor(repo: Path, ancestor: str, descendant: str) -> bool | None:
+    """True / False, or None when git cannot answer.
+
+    None matters: with a shallow checkout the base commit is simply absent, and treating
+    "not in this clone" as "not an ancestor" would fail honest contributions on a
+    misconfigured runner. The caller reports the ambiguity instead of guessing.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "-C", str(repo), "merge-base", "--is-ancestor", ancestor, descendant],
+            capture_output=True, timeout=30)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if proc.returncode == 0:
+        return True
+    if proc.returncode == 1:
+        return False
+    return None          # 128: unknown revision, shallow clone, not a repository
+
+
+def check(*, manifest: dict, repo_dir: Path, head: str | None,
+          expect_repo: str | None, expect_base: bool) -> ContextCheck:
+    """Compare a manifest's signed target against the checkout it is presented in.
+
+    `manifest` is the SIGNED manifest — call this only after the signature verified, or the
+    values are attacker-controlled JSON. Subjects other than `code-change` carry no target
+    and are skipped: an `artifact` envelope is about bytes, not about a repository.
+    """
+    subject = manifest.get("subject")
+    subject = subject if isinstance(subject, dict) else {}
+    if subject.get("type") != "code-change":
+        return ContextCheck(ok=True, checked=False)
+
+    target = subject.get("target")
+    target = target if isinstance(target, dict) else {}
+    signed_repo = target.get("repo")
+    signed_base = target.get("base_sha")
+
+    if expect_repo:
+        if not isinstance(signed_repo, str) or not signed_repo:
+            return ContextCheck(False, True,
+                                "the manifest declares no target repository to check against")
+        if not _same_repo(signed_repo, expect_repo):
+            return ContextCheck(False, True,
+                                f"signed for {signed_repo}, presented on {expect_repo}")
+
+    if expect_base and head:
+        if not isinstance(signed_base, str) or not signed_base:
+            return ContextCheck(False, True,
+                                "the manifest declares no base commit to check against")
+        verdict = _is_ancestor(Path(repo_dir), signed_base, head)
+        if verdict is None:
+            return ContextCheck(
+                False, True,
+                f"cannot tell whether the signed base {signed_base[:12]} is in this "
+                "history — check out with fetch-depth: 0")
+        if not verdict:
+            return ContextCheck(
+                False, True,
+                f"the signed base {signed_base[:12]} is not an ancestor of this pull "
+                "request; the envelope was made against a different history")
+
+    return ContextCheck(ok=True, checked=bool(expect_repo or (expect_base and head)))

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2}/scpe/results.py

@@ -28,7 +28,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from reference.standalone import verify_envelope as _ref
-from scpe import diffinfo, seal
+from scpe import context as _context, diffinfo, seal
 from scpe.testrun import NOT_RUN
 from scpe.verify import UNAVAILABLE
 
@@ -54,6 +54,18 @@ def _display_manifest(path: Path) -> dict:
         return {}
 
 
+def signed_manifest(path: Path) -> dict:
+    """The same bytes, for callers acting on them rather than printing them.
+
+    Identical parse; a different name because the safety condition is different. Display can
+    happen whatever the verdict — an `unattested` seal still shows what the manifest claimed.
+    Acting on a field (comparing a target repository, enforcing a gate) is only sound once
+    the signature over these bytes has verified, so a caller must check that first. The two
+    names exist so the distinction is visible at every call site instead of living in a
+    comment nobody re-reads."""
+    return _display_manifest(path)
+
+
 def _dig(obj: object, *keys: str) -> object:
     """Walk nested dicts, tolerating any shape. A manifest is attacker-controlled JSON
     until the signature verifies, so every level is checked instead of assumed."""
@@ -77,10 +89,20 @@ def _provenance(ai_disclosure: object) -> str:
 
 
 def _fail_message(status: str, detail: str, *, disclosure_present: bool,
-                  key_source: str | None = None) -> str:
+                  key_source: str | None = None, context_detail: str = "") -> str:
     """The one line the trusted job posts when the gate closes. Specific by construction:
     the trusted job must never have to recompute a reason, and "not verifiable" without a
     cause is an unactionable check."""
+    if status == VERIFIED and context_detail:
+        # The hardest case to guess from outside: everything cryptographic is in order. The
+        # signature is genuine, the diff matches the digest it was signed over, the identity
+        # resolves — the envelope is just being presented somewhere other than where it was
+        # signed for. Name which, or a maintainer reads "verified" next to a red check and
+        # concludes the tool is broken.
+        return ("❌ Wrong context — the signature and the diff are both valid, but this "
+                f"envelope was not signed for this pull request: {context_detail}. A valid "
+                "envelope replayed onto another repository or another history is still a "
+                "valid envelope; it just does not attest to this contribution.")
     if status == VERIFIED and key_source == "bundled":
         # Rejected while the status says `verified`, which is the one case a maintainer will
         # not guess: the signature is genuine, it just proves nothing about the account named
@@ -106,7 +128,8 @@ def _fail_message(status: str, detail: str, *, disclosure_present: bool,
 def build_results(result: _ref.Result, *, path: Path, diff: str = "",
                   diff_source: str = UNAVAILABLE, diff_note: str = "",
                   require: bool = False, level: str = "2",
-                  tests: dict | None = None) -> dict:
+                  tests: dict | None = None,
+                  context: "_context.ContextCheck | None" = None) -> dict:
     """Project a verifier `Result` (plus the diff and test run that accompanied it) into
     the results.json contract."""
     manifest = _display_manifest(path)
@@ -146,14 +169,21 @@ def build_results(result: _ref.Result, *, path: Path, diff: str = "",
     # Level 2 implies level 1 (docs/LEVELS.md): a pass must carry BOTH a valid signature and
     # a declared AI-use mode. The verifier answers the first question only, so the second is
     # enforced here, at the gate — the layer that is allowed to have a policy.
-    would_pass = verified and disclosure_present and forge_backed
+    # The envelope must also be presented where it was signed for. A signature and a diff
+    # digest together prove the change is authentic and unaltered; they say nothing about
+    # which repository or which history it was meant for, and the manifest carries both
+    # precisely so that can be answered. See scpe/context.py — before it existed, an
+    # attestation lifted off a public pull request verified on an unrelated repository.
+    context_ok = context.ok if context is not None else True
+    context_detail = "" if context is None or context.ok else context.detail
+    would_pass = verified and disclosure_present and forge_backed and context_ok
     gate_pass = (not require) or would_pass
     # Populated whenever the contribution would NOT clear a gate, even at require=false, so
     # an informational run previews exactly what enabling the gate would say. Empty means
     # there is nothing to report — never a generic "not verifiable" a job might post anyway.
     fail_message = "" if would_pass else _fail_message(
         result.status, result.detail, disclosure_present=disclosure_present,
-        key_source=result.key_source)
+        key_source=result.key_source, context_detail=context_detail)
 
     stats = change.get("stats") if isinstance(change.get("stats"), dict) else None
     claimed_files = change.get("files_changed")
@@ -214,6 +244,13 @@ def build_results(result: _ref.Result, *, path: Path, diff: str = "",
         "target_repo": _str(target.get("repo")),
         "base_sha": _str(target.get("base_sha")),
         "head_sha": _str(change.get("head_sha")),
+        # Whether the three fields above were COMPARED with the checkout, not just copied
+        # out of the manifest. `context_checked: false` means no expectation was supplied
+        # and the signed target went unexamined — which is what every run did before
+        # scpe/context.py existed, and is why a consumer needs to be able to tell.
+        "context_checked": bool(context.checked) if context is not None else False,
+        "context_ok": context_ok,
+        "context_detail": context_detail,
 
         # ---- provenance of the numbers above, so nobody mistakes them for the protocol ----
         "risk_scan": {

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2/scpe_protocol.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scpe-protocol
-Version: 0.2.1
+Version: 0.2.2
 Summary: SCPE: an open protocol for verifiable provenance of any digital artifact — who signed a contribution or file, what they declared about AI use, and that nothing was tampered with, verified offline with no server and no new accounts. Ships the single-file reference verifier, its producer, and a CLI (`scpe`) that seals a pull request from it.
 Author: Augusto Bastos
 License-Expression: Apache-2.0
@@ -44,7 +44,7 @@ Dynamic: license-file
   <img alt="spec" src="https://img.shields.io/badge/spec-scpe%2F0.1-41c257?style=flat-square&labelColor=0b0b0c">
   <img alt="python" src="https://img.shields.io/badge/python-3.11%2B-41c257?style=flat-square&labelColor=0b0b0c">
   <img alt="license" src="https://img.shields.io/badge/code-Apache--2.0-41c257?style=flat-square&labelColor=0b0b0c">
-  <img alt="status" src="https://img.shields.io/badge/v0.2.1-early-d29922?style=flat-square&labelColor=0b0b0c">
+  <img alt="status" src="https://img.shields.io/badge/v0.2.2-early-d29922?style=flat-square&labelColor=0b0b0c">
 </p>
 
 <p align="center">
@@ -150,6 +150,16 @@ SLSA uses to sell levels. See [docs/LEVELS.md](docs/LEVELS.md).
    (target repo, base commit, a SHA-256 of the exact diff, an AI-use disclosure, and an
    optional attribution record) signed with the SSH key already on their GitHub profile
    (`ssh-keygen -Y sign -n scpe/0.1`). No new account.
+
+   > **The key has to be published as an authentication key.** `forge` verification reads
+   > `github.com/<login>.keys`, and GitHub serves only authentication keys there — a key added
+   > under *Signing keys* is real, is used by `git`, and **never appears at that URL**, so a
+   > contribution signed with it can only ever reach `key_source: bundled`. Add it with
+   > `gh ssh-key add <key>.pub --title scpe` (no `--type signing`). GitHub does publish signing
+   > keys, at `api.github.com/users/<login>/ssh_signing_keys`, but `<host>/<login>.keys` is the
+   > shape the fixed provider table is built on; reading the signing-key endpoint per provider is
+   > open, not decided. Filing the key in the obviously-correct place and silently losing forge
+   > verification is the first thing that went wrong for the protocol's own author.
 2. It travels inside a **normal pull request** — the diff in the branch, the ~1–2 KB signed
    attestation embedded in the PR body. Merging leaves the repo history clean.
 3. The **owner's side** re-derives everything itself, with no SCPE server involved: the diff's
@@ -194,20 +204,36 @@ Add a workflow that verifies every PR and posts a seal. Set `require` to gate me
 ```yaml
 # .github/workflows/scpe.yml — the step. Copy BOTH files from docs/workflows/ for the
 # fork-safe version: scpe.yml (verify) and its companion scpe-seal.yml (post the seal).
-- uses: augbastos/scpe@v0.2.1
+- uses: augbastos/scpe@v0.2.2
   with:
     level: "1"        # 1 = disclosure lint · 2 = signed envelope required
     require: "true"   # fail the check on anything not verifiable
 ```
 
-Pin the exact tag while the protocol is pre-1.0. Every tag here is an **immutable alias** — it
-points at one commit and is never moved, so a fix arrives as a new tag you adopt by editing the
-pin, not as a silent change under the one you already wrote. `v0.2.1` is that in practice: `v0.2`
-shipped a seal banner that read `VERIFIED` on unattested PRs and a workflow template GitHub
-refuses to register, and both were fixed by publishing a new tag rather than by moving the old
-one. The `v0.2` line is also the first in which the Action verifies the `scpe/0.1` envelope
-itself; `v0.1.x` verified a different, now-removed format, so upgrading from it is a behaviour
-change and not a patch — [docs/MIGRATION.md](docs/MIGRATION.md) has the steps.
+### Version policy
+
+Pin the exact tag while the protocol is pre-1.0.
+
+- **Every tag is an immutable alias.** It points at one commit and is never moved. A fix
+  arrives as a *new* tag you adopt by editing the pin, never as a silent change under the one
+  you already wrote. Both `v0.2.1` and `v0.2.2` exist for that reason rather than because
+  `v0.2` was re-pointed.
+- **The cost is that fixes do not reach you on their own** — including security fixes. Watch
+  the releases, or let Dependabot's `github-actions` ecosystem open the bump as a pull
+  request you can read before merging.
+- **A patch tag can change behaviour when the old behaviour was wrong.** `v0.2.2` refuses
+  contributions that `v0.2.1` accepted, because `v0.2.1` accepted some it should not have.
+  Read the [CHANGELOG](CHANGELOG.md) before moving a pin; "patch" here means the protocol
+  did not change, not that nothing did.
+- **`spec_version` is a separate number from the tag.** The protocol is `scpe/0.1` across
+  every `v0.2.x` release. See [CHANGELOG.md](CHANGELOG.md) for the three axes and why
+  reading one as the other is the easiest mistake to make here.
+- **The `v0.1.x` line is legacy, not merely old.** It verifies an envelope format that is not
+  in `spec/`, so upgrading from it is a behaviour change and not a patch —
+  [docs/MIGRATION.md](docs/MIGRATION.md) has the steps.
+
+**Which tag to be on:** `v0.2.2`. `v0.2.1` and `v0.2` accept a valid envelope replayed from
+another repository (see [SECURITY.md](SECURITY.md)); `v0.2.2` refuses it.
 
 The Action uses a fork-safe two-job split, and the two jobs live in **two files**: the untrusted
 job in `scpe.yml` (which runs contributor code) holds no secrets, and only the trusted follow-up
@@ -253,10 +279,14 @@ vector reaches the `forge` anchor.
 |---|---|
 | PR-body attestation (manifest + sig, base64) | 1.1–1.5 KB |
 | Standalone envelope (3-file / 27-line PR, zipped) | ~1.5 KB |
-| Verify wall-time | ~210 ms cold CLI · ~39 ms in a warm process |
+| Verify wall-time | ~200 ms cold process · ~31 ms warm |
 
 An `artifact` subject adds its payload size on top of ~800 B fixed overhead. Order-of-magnitude,
-single machine — not a formal benchmark suite.
+single machine — not a formal benchmark suite. Re-run it yourself rather than taking the number:
+`python tests/bench_verify.py <envelope.zip> --keys <login.keys>` prints the median of 15 runs
+for both paths. The cold figure is a fresh interpreter per run; the warm one re-verifies
+in-process, which is what a batch consumer sees after import cost is paid once. Both use the
+`flag` anchor, so no network is in the measurement.
 
 ## Where it sits
 
@@ -268,13 +298,16 @@ single machine — not a formal benchmark suite.
 - **A different layer from build provenance.** Sigstore / SLSA / in-toto attest *artifacts and
   builds*; SCPE attests a *contribution*, at the pull-request boundary.
 - **Direct prior art:** `patatt` + `b4` ([kernel.org](https://github.com/mricon/patatt)) have run
-  this exact pattern — self-sign a patch with a key the platform publishes, verify independently,
-  no CA, no server — on the Linux kernel's mailing list for years. SCPE applies the same shape to
-  the GitHub pull-request boundary.
+  this shape — the contributor self-signs a patch, the recipient verifies independently, no CA,
+  no server — on the Linux kernel's mailing list for years. They differ from SCPE in where the
+  key comes from: `patatt` keeps a keyring in the repository, so the project curates who may
+  sign; SCPE reads the keys the forge already publishes for the account, so there is nothing to
+  curate and nothing to depend on but the forge. Same shape, different trust root, applied to
+  the pull-request boundary instead of a mailing list.
 
 ## Status
 
-**v0.2.1 — early.** This is a specification plus a reference implementation (a single-file
+**v0.2.2 — early.** This is a specification plus a reference implementation (a single-file
 verifier, a producer, and a maintainer-side Action). The full test suite — including a 100-PR
 stress proof and a local end-to-end — runs on every push; the CI badge above is its live
 result. Two more independent verifiers, in Go and Rust, reach the same verdict as the Python
@@ -288,7 +321,7 @@ accept. There is **no external adoption yet**. It is not a hosted service and ne
 **`v0.1.x` is legacy: its signed-envelope path verifies a format that is not in this spec.** The
 Action at those tags checked a second envelope format that shipped inside the package and was
 deleted in `0.2.0`. A workflow still pinned there does not fail — it keeps posting seals for a
-format nothing here produces, and once `0.2.0` reaches PyPI it breaks instead, because that
+format nothing here produces — and now that `0.2.x` is on PyPI it breaks outright instead, because that
 Action resolved its verifier from the package index at run time rather than from its own
 checkout. [CHANGELOG.md](CHANGELOG.md) has what moved; [docs/MIGRATION.md](docs/MIGRATION.md)
 has what to do about it.

{scpe_protocol-0.2.1 → scpe_protocol-0.2.2}/scpe_protocol.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ reference/standalone/__init__.py
 reference/standalone/verify_envelope.py
 scpe/__init__.py
 scpe/cli.py
+scpe/context.py
 scpe/diffinfo.py
 scpe/optin.py
 scpe/results.py
@@ -24,6 +25,7 @@ scpe_protocol.egg-info/requires.txt
 scpe_protocol.egg-info/top_level.txt
 tests/test_action_expressions.py
 tests/test_action_yaml.py
+tests/test_context_binding.py
 tests/test_diff_resolution.py
 tests/test_differential_verifiers.py
 tests/test_disclosure.py

scpe_protocol-0.2.2/tests/test_context_binding.py

@@ -0,0 +1,195 @@
+"""A valid envelope must not verify on a pull request it was not signed for.
+
+The manifest carries `subject.target.repo` and `subject.target.base_sha` so that question
+can be answered. Before scpe/context.py they were read, copied into results.json, and never
+compared with anything — so an attestation lifted off a public pull request produced a
+`verified`, `gate_pass: true`, `key_source: forge` seal on an unrelated repository whose
+diff happened to normalize to the same bytes. The signature was genuine and the digest
+matched; only the context was wrong, and nothing looked at it.
+
+These tests are written against that scenario rather than against the implementation: each
+one builds the mismatch and asserts the gate closes with a reason a maintainer can act on.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from scpe import context as _context
+
+CODE_CHANGE = {
+    "subject": {
+        "type": "code-change",
+        "target": {"repo": "augbastos/scpe-demo", "base_sha": "a" * 40},
+        "change": {"head_sha": "b" * 40},
+    }
+}
+
+
+def _check(**kw):
+    base = dict(manifest=CODE_CHANGE, repo_dir=Path("."), head=None,
+                expect_repo=None, expect_base=False)
+    base.update(kw)
+    return _context.check(**base)
+
+
+# --- the replay this exists to stop ------------------------------------------------------
+
+def test_envelope_signed_for_another_repository_is_refused():
+    c = _check(expect_repo="attacker/other-repo")
+    assert c.mismatch
+    assert "augbastos/scpe-demo" in c.detail and "attacker/other-repo" in c.detail
+
+
+def test_matching_repository_passes_and_says_it_checked():
+    c = _check(expect_repo="augbastos/scpe-demo")
+    assert c.ok and c.checked and not c.mismatch
+
+
+def test_repository_comparison_is_case_insensitive():
+    """Forges treat Owner/Name and owner/name as one repository. Refusing on case would
+    fail honest contributions for a reason no maintainer would ever guess."""
+    assert _check(expect_repo="AugBastos/SCPE-Demo").ok
+
+
+def test_manifest_without_a_target_repo_cannot_satisfy_the_check():
+    """Absent is not a pass. An envelope that declares no target repository has nothing to
+    compare, and treating "nothing to compare" as "matches" would let an attacker opt out
+    of the check by omitting the field."""
+    m = {"subject": {"type": "code-change", "target": {}, "change": {}}}
+    c = _check(manifest=m, expect_repo="augbastos/scpe-demo")
+    assert c.mismatch
+
+
+def test_target_repo_of_the_wrong_type_is_refused():
+    m = {"subject": {"type": "code-change", "target": {"repo": 1234}, "change": {}}}
+    assert _check(manifest=m, expect_repo="augbastos/scpe-demo").mismatch
+
+
+# --- base ancestry, not base equality ----------------------------------------------------
+
+def _repo(tmp_path: Path, run) -> Path:
+    run(["git", "init", "-q", str(tmp_path)])
+    run(["git", "-C", str(tmp_path), "config", "user.email", "t@example.com"])
+    run(["git", "-C", str(tmp_path), "config", "user.name", "t"])
+    return tmp_path
+
+
+@pytest.fixture()
+def git(tmp_path):
+    import subprocess
+
+    def run(cmd, **kw):
+        return subprocess.run(cmd, capture_output=True, check=True, **kw)
+
+    def sha(repo, rev="HEAD"):
+        return subprocess.run(["git", "-C", str(repo), "rev-parse", rev],
+                              capture_output=True, text=True, check=True).stdout.strip()
+
+    repo = _repo(tmp_path, run)
+    (repo / "f.txt").write_text("one\n", encoding="utf-8")
+    run(["git", "-C", str(repo), "add", "-A"])
+    run(["git", "-C", str(repo), "commit", "-qm", "base"])
+    base = sha(repo)
+    (repo / "f.txt").write_text("two\n", encoding="utf-8")
+    run(["git", "-C", str(repo), "add", "-A"])
+    run(["git", "-C", str(repo), "commit", "-qm", "head"])
+    return repo, base, sha(repo), run, sha
+
+
+def test_signed_base_in_this_history_passes(git):
+    repo, base, head, _run, _sha = git
+    m = {"subject": {"type": "code-change",
+                     "target": {"repo": "o/n", "base_sha": base}, "change": {}}}
+    c = _context.check(manifest=m, repo_dir=repo, head=head,
+                       expect_repo=None, expect_base=True)
+    assert c.ok and c.checked
+
+
+def test_base_check_survives_the_branch_moving_on(git):
+    """The reason this is ancestry and not equality. `pull_request.base.sha` is the tip of
+    the base branch and advances whenever anything merges; the commit the contributor
+    diffed from does not. Equality would fail every open pull request after any merge."""
+    repo, base, head, run, sha = git
+    run(["git", "-C", str(repo), "checkout", "-q", "-b", "other", base])
+    (repo / "unrelated.txt").write_text("moved on\n", encoding="utf-8")
+    run(["git", "-C", str(repo), "add", "-A"])
+    run(["git", "-C", str(repo), "commit", "-qm", "someone else merged something"])
+    assert sha(repo) != base                      # the branch tip really did move
+    m = {"subject": {"type": "code-change",
+                     "target": {"repo": "o/n", "base_sha": base}, "change": {}}}
+    c = _context.check(manifest=m, repo_dir=repo, head=head,
+                       expect_repo=None, expect_base=True)
+    assert c.ok, "a moved base branch must not invalidate an honest contribution"
+
+
+def test_signed_base_from_a_foreign_history_is_refused(git):
+    repo, _base, head, _run, _sha = git
+    m = {"subject": {"type": "code-change",
+                     "target": {"repo": "o/n", "base_sha": "c" * 40}, "change": {}}}
+    c = _context.check(manifest=m, repo_dir=repo, head=head,
+                       expect_repo=None, expect_base=True)
+    assert c.mismatch
+
+
+def test_missing_base_cannot_satisfy_the_check(git):
+    repo, _base, head, _run, _sha = git
+    m = {"subject": {"type": "code-change", "target": {"repo": "o/n"}, "change": {}}}
+    c = _context.check(manifest=m, repo_dir=repo, head=head,
+                       expect_repo=None, expect_base=True)
+    assert c.mismatch
+
+
+# --- shape of the contract ---------------------------------------------------------------
+
+def test_artifact_subjects_are_out_of_scope():
+    """An `artifact` envelope is about bytes, not about a repository — there is no target to
+    compare, and inventing one would fail every artifact contribution."""
+    m = {"subject": {"type": "artifact", "artifact": {"sha256": "x"}}}
+    c = _context.check(manifest=m, repo_dir=Path("."), head=None,
+                       expect_repo="o/n", expect_base=True)
+    assert c.ok and not c.checked
+
+
+def test_no_expectation_means_nothing_was_checked():
+    """Callers that supply no expectation must behave exactly as they did before this
+    existed — and results.json has to be able to say the target went unexamined, rather
+    than implying it matched."""
+    c = _check()
+    assert c.ok and not c.checked
+
+
+# --- and the gate actually closes on it --------------------------------------------------
+
+def test_gate_closes_on_a_context_mismatch_and_names_it():
+    """The check is worth nothing if the gate ignores it. A mismatch has to reach
+    gate_pass, and the message has to distinguish this from the other refusals: everything
+    cryptographic is fine here, which is exactly why "not verifiable" would mislead."""
+    from reference.standalone.verify_envelope import Result
+    from scpe import results as _results
+
+    verified = Result("verified", "", None, profile="SCPE-C", key_source="forge")
+    bad = _context.ContextCheck(ok=False, checked=True,
+                                detail="signed for a/b, presented on c/d")
+
+    data = _results.build_results(verified, path=Path("nonexistent.zip"),
+                                  require=True, context=bad)
+    assert data["context_checked"] is True
+    assert data["context_ok"] is False
+    assert data["gate_pass"] is False, "a replayed envelope must not clear the gate"
+    assert "Wrong context" in data["fail_message"]
+    assert "signed for a/b, presented on c/d" in data["fail_message"]
+    assert data["status"] == "verified", (
+        "the envelope IS valid — the seal must not relabel it as broken, only refuse it here")
+
+
+def test_gate_still_passes_when_the_context_matches():
+    from reference.standalone.verify_envelope import Result
+    from scpe import results as _results
+
+    verified = Result("verified", "", None, profile="SCPE-C", key_source="forge")
+    ok = _context.ContextCheck(ok=True, checked=True)
+    data = _results.build_results(verified, path=Path("nonexistent.zip"),
+                                  require=True, context=ok)
+    assert data["context_ok"] is True