coderifts-verifier 0.1.0__tar.gz

coderifts_verifier-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeRifts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

coderifts_verifier-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: coderifts-verifier
+Version: 0.1.0
+Summary: Offline verifier for CodeRifts chain receipts and DSSE/in-toto envelopes. Ed25519, no network.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/coderifts/receipt-verifier
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Dynamic: license-file
+
+# coderifts-verifier (Python)
+
+Verify a CodeRifts chain receipt — or a DSSE / in-toto envelope carrying one —
+offline, in Python, without calling CodeRifts.
+
+```python
+from coderifts_verifier import unwrap, verify_receipt, keyring_from_document
+
+keyring = keyring_from_document(registry_json, "my-registry.json")
+token = unwrap(whatever_arrived)              # compact token, or DSSE -> compact
+result = verify_receipt(token, {"keyring": keyring})
+
+if result["valid"]:
+    ...
+else:
+    handle(result["status"])                  # INVALID_SIGNATURE, UNKNOWN_KEY, ...
+```
+
+Ed25519 via `cryptography`. No network on the verify path.
+
+## This is not the CodeRifts SDK
+
+Two different packages, on purpose:
+
+| | `coderifts` (SDK) | `coderifts-verifier` (this) |
+| --- | --- | --- |
+| does | calls the API to get a decision | verifies evidence you already hold |
+| crypto | none — deliberately | Ed25519 |
+| network | yes, that is the point | none on the verify path |
+
+A dependency on `cryptography` is correct here: this package checks signatures.
+The SDK stays crypto-free.
+
+## Unwrapping is not verification
+
+`unwrap` and `from_dsse` check **no signature**. An envelope wrapping a receipt
+with a bad signature unwraps cleanly and then fails `verify_receipt`, exactly as
+that compact token would have — the signature is over the compact bytes.
+
+The DSSE envelope proves **exactly what the compact receipt proves**. A standard
+container does not strengthen a claim.
+
+```python
+token = from_dsse(envelope)                   # succeeds — nothing checked yet
+verify_receipt(token, {"keyring": keyring})   # this is the verdict
+```
+
+## Cross-language agreement
+
+The signed-bytes reconstruction is byte-identical to the JavaScript verifier —
+`verify.js` says so in its own source, and `tests/xlang-vectors.json` holds
+receipts produced and verified by that implementation. The test suite asserts
+Python reaches the **same verdict on the same bytes**, for a passing receipt and
+for two distinct failure modes.
+
+Two implementations disagreeing about whether a receipt is valid is the failure
+a multi-language verifier exists to avoid, so the agreement is pinned rather than
+assumed.
+
+The verification core (`coderifts_verifier/_verify.py`) is **vendored** from the
+reference verifier, not reimplemented. The only edit is the import path for the
+vendored `arity` helper; the file is otherwise byte-identical, so there is one
+definition of what a valid receipt is rather than two that can drift.
+
+## Refusals are named
+
+`from_dsse` raises `DsseError` with a `code`:
+
+| code | when |
+| --- | --- |
+| `MALFORMED` | not an envelope; unreadable payload; zero, two, or signature-less entries; missing `encoded_payload` |
+| `UNSUPPORTED` | a `payloadType`, `predicateType`, or compact `form` this version does not implement |
+| `PREDICATE_MISMATCH` | the decoded `predicate.fields` disagree with the preserved payload segment |
+
+That last one matters: the predicate carries the payload twice, once as bytes and
+once decoded for a reader. If they disagree, the readable half describes
+something the signed half does not contain — refuse rather than hand back bytes
+that do not match the envelope someone read.
+
+## What a valid verdict proves
+
+* a holder of a key in **the keyring you supplied** signed this receipt;
+* the receipt's signed fields are unmodified;
+* per `status`: whether it is current, or was issued while a now-retired key was
+  still valid.
+
+## What it does NOT prove
+
+* **That anything happened.** A receipt is a signed statement about a decision,
+  not an observation of an effect.
+* **That the key is uncompromised.** Everything reduces to "a holder of this key
+  signed this". Custody is yours.
+* **That the receipt is the right one for what you are about to do.** Scope
+  matching — does this receipt cover THIS operation on THIS target — is the
+  caller's check, against the decision envelope. This verifies the receipt.
+* **That a human saw anything.**
+
+## Format
+
+`RECEIPT_FORMAT.md` in the reference verifier is the specification; section 9
+covers the DSSE / in-toto export. The constants here are byte-exact to it and
+pinned by a test.
+
+## Tests
+
+```bash
+python3 -m pytest tests/ -q
+```
+
+## License
+
+MIT

coderifts_verifier-0.1.0/README.md

@@ -0,0 +1,112 @@
+# coderifts-verifier (Python)
+
+Verify a CodeRifts chain receipt — or a DSSE / in-toto envelope carrying one —
+offline, in Python, without calling CodeRifts.
+
+```python
+from coderifts_verifier import unwrap, verify_receipt, keyring_from_document
+
+keyring = keyring_from_document(registry_json, "my-registry.json")
+token = unwrap(whatever_arrived)              # compact token, or DSSE -> compact
+result = verify_receipt(token, {"keyring": keyring})
+
+if result["valid"]:
+    ...
+else:
+    handle(result["status"])                  # INVALID_SIGNATURE, UNKNOWN_KEY, ...
+```
+
+Ed25519 via `cryptography`. No network on the verify path.
+
+## This is not the CodeRifts SDK
+
+Two different packages, on purpose:
+
+| | `coderifts` (SDK) | `coderifts-verifier` (this) |
+| --- | --- | --- |
+| does | calls the API to get a decision | verifies evidence you already hold |
+| crypto | none — deliberately | Ed25519 |
+| network | yes, that is the point | none on the verify path |
+
+A dependency on `cryptography` is correct here: this package checks signatures.
+The SDK stays crypto-free.
+
+## Unwrapping is not verification
+
+`unwrap` and `from_dsse` check **no signature**. An envelope wrapping a receipt
+with a bad signature unwraps cleanly and then fails `verify_receipt`, exactly as
+that compact token would have — the signature is over the compact bytes.
+
+The DSSE envelope proves **exactly what the compact receipt proves**. A standard
+container does not strengthen a claim.
+
+```python
+token = from_dsse(envelope)                   # succeeds — nothing checked yet
+verify_receipt(token, {"keyring": keyring})   # this is the verdict
+```
+
+## Cross-language agreement
+
+The signed-bytes reconstruction is byte-identical to the JavaScript verifier —
+`verify.js` says so in its own source, and `tests/xlang-vectors.json` holds
+receipts produced and verified by that implementation. The test suite asserts
+Python reaches the **same verdict on the same bytes**, for a passing receipt and
+for two distinct failure modes.
+
+Two implementations disagreeing about whether a receipt is valid is the failure
+a multi-language verifier exists to avoid, so the agreement is pinned rather than
+assumed.
+
+The verification core (`coderifts_verifier/_verify.py`) is **vendored** from the
+reference verifier, not reimplemented. The only edit is the import path for the
+vendored `arity` helper; the file is otherwise byte-identical, so there is one
+definition of what a valid receipt is rather than two that can drift.
+
+## Refusals are named
+
+`from_dsse` raises `DsseError` with a `code`:
+
+| code | when |
+| --- | --- |
+| `MALFORMED` | not an envelope; unreadable payload; zero, two, or signature-less entries; missing `encoded_payload` |
+| `UNSUPPORTED` | a `payloadType`, `predicateType`, or compact `form` this version does not implement |
+| `PREDICATE_MISMATCH` | the decoded `predicate.fields` disagree with the preserved payload segment |
+
+That last one matters: the predicate carries the payload twice, once as bytes and
+once decoded for a reader. If they disagree, the readable half describes
+something the signed half does not contain — refuse rather than hand back bytes
+that do not match the envelope someone read.
+
+## What a valid verdict proves
+
+* a holder of a key in **the keyring you supplied** signed this receipt;
+* the receipt's signed fields are unmodified;
+* per `status`: whether it is current, or was issued while a now-retired key was
+  still valid.
+
+## What it does NOT prove
+
+* **That anything happened.** A receipt is a signed statement about a decision,
+  not an observation of an effect.
+* **That the key is uncompromised.** Everything reduces to "a holder of this key
+  signed this". Custody is yours.
+* **That the receipt is the right one for what you are about to do.** Scope
+  matching — does this receipt cover THIS operation on THIS target — is the
+  caller's check, against the decision envelope. This verifies the receipt.
+* **That a human saw anything.**
+
+## Format
+
+`RECEIPT_FORMAT.md` in the reference verifier is the specification; section 9
+covers the DSSE / in-toto export. The constants here are byte-exact to it and
+pinned by a test.
+
+## Tests
+
+```bash
+python3 -m pytest tests/ -q
+```
+
+## License
+
+MIT

coderifts_verifier-0.1.0/coderifts_verifier/__init__.py

@@ -0,0 +1,62 @@
+"""CodeRifts offline verifier for Python.
+
+Verify a CodeRifts chain receipt, or a DSSE / in-toto envelope carrying one,
+without calling CodeRifts. Offline Ed25519 against a keyring you pin.
+
+    from coderifts_verifier import unwrap, verify_receipt
+
+    token = unwrap(whatever_arrived)        # compact token, or DSSE -> compact
+    result = verify_receipt(token, {"keyring": my_keyring})
+    if result["valid"]:
+        ...
+
+UNWRAPPING IS NOT VERIFICATION. ``unwrap`` / ``from_dsse`` check no signature: a
+DSSE envelope wrapping a bad receipt unwraps cleanly and then fails
+``verify_receipt``, exactly as that compact token would have. The DSSE proves
+exactly what the compact receipt proves -- a standard container does not
+strengthen a claim.
+
+The verification core (``_verify.py``) is VENDORED from the reference JS/Python
+verifier rather than reimplemented, so there is one definition of what a valid
+receipt is. Its signed-bytes reconstruction is byte-identical to ``verify.js``;
+the cross-language tests pin that against shared vectors.
+"""
+
+from ._verify import (  # noqa: F401
+    canonical_json,
+    derive_status,
+    keyring_from_document,
+    reconstruct_signed_input,
+    verify_chain,
+    verify_receipt,
+)
+from .dsse import (  # noqa: F401
+    FORM_ATTESTATION,
+    FORM_RECEIPT,
+    PAYLOAD_TYPE,
+    PREDICATE_TYPE,
+    STATEMENT_TYPE,
+    DsseError,
+    from_dsse,
+    looks_like_dsse,
+    unwrap,
+)
+
+__all__ = [
+    "verify_receipt",
+    "verify_chain",
+    "from_dsse",
+    "unwrap",
+    "looks_like_dsse",
+    "DsseError",
+    "keyring_from_document",
+    "canonical_json",
+    "derive_status",
+    "reconstruct_signed_input",
+    "PAYLOAD_TYPE",
+    "STATEMENT_TYPE",
+    "PREDICATE_TYPE",
+    "FORM_RECEIPT",
+    "FORM_ATTESTATION",
+]
+__version__ = "0.1.0"

coderifts_verifier-0.1.0/coderifts_verifier/_from_commit.py

@@ -0,0 +1,96 @@
+"""1961 TAG 1 -- finding the receipt that belongs to a commit (Python side).
+
+Byte-for-byte the same convention as ``receipt-verifier/receipt-from-commit.js``: the
+``CodeRifts-Receipt`` git trailer, or ``.coderifts/receipts/<full-sha>.json``. See
+``receipt-verifier/docs/receipt-commit-binding.md`` for why both exist and why the trailer wins.
+
+WARNING -- THE CARRIER PROVES NOTHING. Whichever one delivers the token, the token is then
+verified exactly as if it had been pasted on the command line. A forged sidecar yields
+INVALID_SIGNATURE, not a false pass. The sidecar is a POINTER; the signature is the authority.
+"""
+
+import json
+import os
+import pathlib
+import subprocess
+
+TRAILER_KEY = "CodeRifts-Receipt"
+SIDECAR_DIR = os.path.join(".coderifts", "receipts")
+
+
+def _git(args, cwd):
+    return subprocess.run(
+        ["git", *args], cwd=cwd, capture_output=True, text=True, check=True,
+    ).stdout.strip()
+
+
+def resolve_sha(ref, cwd):
+    """Abbreviations collide, and a verifier resolving one itself would be guessing which commit
+    the operator meant. Git knows; ask it."""
+    return _git(["rev-parse", ref + "^{commit}"], cwd)
+
+
+def receipt_from_trailer(sha, cwd):
+    raw = _git(["log", "-1", "--format=%%(trailers:key=%s,valueonly)" % TRAILER_KEY, sha], cwd)
+    if not raw:
+        return None
+    # Unfold: git wraps long trailer values, and a receipt token is long. A token has no
+    # whitespace in it, so joining the trimmed lines is lossless.
+    token = "".join(line.strip() for line in raw.splitlines())
+    return token or None
+
+
+def receipt_from_sidecar(sha, cwd):
+    """A MALFORMED SIDECAR IS NOT "NO SIDECAR".
+
+    Treating it as absent would let a corrupted pointer fall through to the trailer, or to
+    "nothing found" -- both of which read as an innocent absence rather than the broken file it is.
+    """
+    path = pathlib.Path(cwd) / SIDECAR_DIR / (sha + ".json")
+    if not path.exists():
+        return None
+    try:
+        doc = json.loads(path.read_text())
+    except Exception as e:
+        raise ValueError("sidecar %s is not valid JSON: %s" % (path, e))
+    token = (doc or {}).get("receipt") or (doc or {}).get("token")
+    if not token:
+        raise ValueError('sidecar %s has no "receipt" field' % path)
+    return {"token": str(token), "envelope": (doc or {}).get("envelope"), "file": str(path)}
+
+
+def receipt_for_commit(ref, cwd=None):
+    """Returns {sha, token, envelope, carrier}. Raises on anything that is not a clean find.
+
+    WARNING -- TRAILER WINS, BUT A DISAGREEMENT IS REFUSED RATHER THAN RESOLVED. The trailer is
+    inside the commit object and the sidecar is a file anyone can edit, so where both exist the
+    immutable one is authoritative. When they DISAGREE, silently preferring the trailer would hide
+    precisely the tampering the precedence rule exists to make visible.
+    """
+    cwd = cwd or os.getcwd()
+    try:
+        sha = resolve_sha(ref, cwd)
+    except subprocess.CalledProcessError as e:
+        raise ValueError("cannot resolve %s in %s: %s" % (ref, cwd, (e.stderr or "").splitlines()[:1]))
+
+    trailer = receipt_from_trailer(sha, cwd)
+    sidecar = receipt_from_sidecar(sha, cwd)
+
+    if trailer and sidecar:
+        if trailer != sidecar["token"]:
+            raise ValueError(
+                "receipt conflict for %s: the commit trailer and %s carry DIFFERENT receipts. "
+                "The trailer is covered by the commit SHA and the sidecar is not, so they should "
+                "never disagree -- resolve it deliberately rather than letting one win silently."
+                % (sha, sidecar["file"])
+            )
+        return {"sha": sha, "token": trailer, "envelope": sidecar["envelope"], "carrier": "both"}
+    if trailer:
+        return {"sha": sha, "token": trailer, "envelope": None, "carrier": "trailer"}
+    if sidecar:
+        return {"sha": sha, "token": sidecar["token"], "envelope": sidecar["envelope"], "carrier": "sidecar"}
+
+    raise ValueError(
+        "no receipt attached to %s: no %s trailer and no %s/%s.json. That means no receipt was "
+        "ATTACHED -- it does not mean none exists." % (sha, TRAILER_KEY, SIDECAR_DIR, sha)
+    )