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

{scpe_protocol-0.2.0/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.0
+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,11 @@ 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-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">
+  <a href="https://augbastos.github.io/scpe/"><b>augbastos.github.io/scpe</b></a> — what it is, in one page
 </p>
 
 An open protocol for two questions a pull request cannot answer today: **who signed this
@@ -146,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
@@ -188,22 +202,44 @@ anchors and what a verdict is worth under each.
 Add a workflow that verifies every PR and posts a seal. Set `require` to gate merges.
 
 ```yaml
-# .github/workflows/scpe.yml — see docs/workflows/scpe.yml for the fork-safe full version
-- uses: augbastos/scpe@v0.2
+# .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.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. `v0.2` 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. It is also the first release 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.
-
-The Action uses a fork-safe two-job split: the untrusted job (which runs contributor code) holds
-no secrets; only a trusted follow-up job posts the comment. Neither level installs anything in the
+### 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
+job in `scpe-seal.yml` posts the comment. Two files is a GitHub constraint, not a preference — a
+workflow that names itself in its own `workflow_run` trigger fails to register at all. Neither
+level installs anything in the
 runner — both run stdlib-only Python straight out of the Action's own checkout, so the bytes that
 decide a merge are the bytes of the tag you pinned, not whatever a package index serves that day.
 Check out with `fetch-depth: 0`: level 2 recomputes the diff as `git diff <base>...<head>`, and the
@@ -237,16 +273,20 @@ passing all eighteen does not by itself show that the `key_source` MUST is honou
 checked by inspection. Every vector ships its own `keys` file so the suite runs offline, and no
 vector reaches the `forge` anchor.
 
-**Cost** — measured on the Python reference (Ryzen 5 5600H, Python 3.14, `local` provider):
+**Cost**
 
 | | Measured |
 |---|---|
 | 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
 
@@ -258,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 — 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
@@ -278,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.