sdcreceipt 4.0.0__py3-none-any.whl

sdcreceipt/__init__.py

@@ -0,0 +1,22 @@
+#
+# Copyright (c) 2025, Axius SDC, Inc.
+# Licensed under the Apache License, Version 2.0.
+#
+"""
+sdcreceipt - verify and settle VSL Settlement Receipts.
+
+Three verbs and no more: `verify`, `init`, `trigger`. It is a client, not a
+product; the value is in it being small enough to read.
+
+`verify` requires no network, no account, and nothing from the issuer.
+"""
+
+#: SDC ecosystem versioning: MAJOR tracks the reference model, so a 4.x.x
+#: release targets SDC4. It starts at 4 rather than 0 for that reason, not
+#: because there were three earlier versions. MINOR is features, PATCH is
+#: fixes. An SDC5 reference model would make this 5.x.x.
+__version__ = "4.0.0"
+
+from sdcreceipt.verify import Result, verify  # noqa: F401
+
+__all__ = ["verify", "Result", "__version__"]

sdcreceipt/canonical.py

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2025, Axius SDC, Inc.
+# Licensed under the Apache License, Version 2.0.
+#
+"""
+RFC 8785 canonicalization.
+
+★ Deliberately a thin re-export rather than an implementation.
+
+A second implementation of a canonicalization scheme can disagree with the
+first, and the disagreement is silent: the bytes differ, so the hash differs,
+and the artifact reads as tampered with rather than misencoded. That converts
+a structural guarantee into a testing problem defended forever.
+
+`sdcgovernance` is Apache-2.0, on PyPI, and differential-tested against a real
+ECMAScript engine, which matters because RFC 8785 defines number formatting in
+terms of ECMAScript `Number::toString`. Reusing it means this tool and the
+issuer cannot disagree about bytes.
+
+This is a library dependency, not a service dependency. Nothing here calls
+out to anything at runtime.
+"""
+
+from sdcgovernance.jcs import canonicalize, canonicalize_bytes  # noqa: F401
+
+__all__ = ["canonicalize", "canonicalize_bytes"]

sdcreceipt/cli.py

@@ -0,0 +1,206 @@
+#
+# Copyright (c) 2025, Axius SDC, Inc.
+# Licensed under the Apache License, Version 2.0.
+#
+"""
+Command line interface.
+
+    sdcreceipt verify  receipt.json --keys keys.json
+    sdcreceipt init    --key-id https://vendor.example/.well-known/vsl-key.json
+    sdcreceipt trigger receipt.json --key party.pem --key-id <id>
+
+`verify` exits 0 only if every check passed, so it composes in a shell without
+anyone having to parse the output.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from sdcreceipt import __version__
+from sdcreceipt.party import (
+    PartyError,
+    generate_key,
+    key_document,
+    load_key_set_file,
+    load_private_key,
+    publication_path,
+    sign_trigger,
+    write_private_key,
+)
+from sdcreceipt.verify import verify
+
+
+def _load_json(path: Path, what: str) -> dict:
+    try:
+        return json.loads(path.read_text())
+    except FileNotFoundError:
+        raise SystemExit(f"error: no {what} at {path}")
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"error: {path} is not valid JSON: {exc}")
+
+
+def cmd_verify(args) -> int:
+    receipt = _load_json(Path(args.receipt), "receipt")
+
+    issuer_keys = {}
+    party_keys = None
+    if args.keys:
+        try:
+            keyset = load_key_set_file(Path(args.keys))
+        except PartyError as exc:
+            raise SystemExit(f"error: {exc}")
+        # One file may carry both; the Receipt says which id is which.
+        issuer_ids = {s.get("key_id") for s in receipt.get("signatures", [])}
+        issuer_keys = {k: v for k, v in keyset.items() if k in issuer_ids}
+        party_keys = {k: v for k, v in keyset.items() if k not in issuer_ids} or None
+
+    schema = _load_json(Path(args.schema), "schema") if args.schema else None
+    governance = (
+        _load_json(Path(args.governance), "governance receipt")
+        if args.governance
+        else None
+    )
+    payload = Path(args.payload).read_bytes() if args.payload else None
+
+    result = verify(
+        receipt,
+        issuer_keys=issuer_keys,
+        party_keys=party_keys,
+        schema=schema,
+        governance_receipt=governance,
+        payload=payload,
+    )
+
+    print(result)
+    if result.ok:
+        print("\nVERIFIED")
+        return 0
+
+    print(f"\nNOT VERIFIED - {len(result.failures)} check(s) failed")
+    if not args.keys:
+        print(
+            "\nNo --keys given, so no signature could be checked. Fetch the "
+            "issuer's published key set and pass it; never take a key from a "
+            "location inside the Receipt."
+        )
+    return 1
+
+
+def cmd_init(args) -> int:
+    key_id = args.key_id
+    try:
+        publish_at = publication_path(key_id)
+    except PartyError as exc:
+        raise SystemExit(f"error: {exc}")
+
+    key = generate_key()
+    private_path = Path(args.out)
+    document_path = private_path.with_name(private_path.stem + "-key-document.json")
+
+    try:
+        write_private_key(key, private_path)
+    except PartyError as exc:
+        raise SystemExit(f"error: {exc}")
+
+    document_path.write_text(json.dumps(key_document(key, key_id), indent=2) + "\n")
+
+    print(f"private key      {private_path}  (mode 0600, keep it)")
+    print(f"key document     {document_path}")
+    print()
+    print("Publish the key document so it is reachable, unauthenticated, at:")
+    print(f"  {publish_at}")
+    print()
+    print(
+        "Until it is reachable there, a verifier cannot resolve your triggers.\n"
+        "Give the issuer this key_id when the settlement is created:\n"
+        f"  {key_id}"
+    )
+    return 0
+
+
+def cmd_trigger(args) -> int:
+    receipt = _load_json(Path(args.receipt), "receipt")
+
+    try:
+        key = load_private_key(Path(args.key))
+        trigger = sign_trigger(key, receipt, args.key_id)
+    except PartyError as exc:
+        raise SystemExit(f"error: {exc}")
+
+    body = json.dumps(trigger, indent=2)
+
+    if not args.submit:
+        # Default: print and stop. Signing is inert and pipeable; submitting
+        # is a side effect and should be asked for.
+        print(body)
+        print(
+            "\n# Not submitted. Send it with --submit <url>, or pipe this to "
+            "whatever you use.",
+            file=sys.stderr,
+        )
+        return 0
+
+    import urllib.error
+    import urllib.request
+
+    request = urllib.request.Request(
+        args.submit,
+        data=body.encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            print(response.read().decode("utf-8"))
+        return 0
+    except urllib.error.HTTPError as exc:
+        print(f"error: {exc.code} from {args.submit}", file=sys.stderr)
+        print(exc.read().decode("utf-8", errors="replace"), file=sys.stderr)
+        return 1
+    except urllib.error.URLError as exc:
+        print(f"error: could not reach {args.submit}: {exc.reason}", file=sys.stderr)
+        return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sdcreceipt",
+        description="Verify and settle VSL Settlement Receipts.",
+    )
+    parser.add_argument("--version", action="version", version=f"sdcreceipt {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("verify", help="verify a Receipt (no network, no account)")
+    p.add_argument("receipt")
+    p.add_argument("--keys", help="published key set, JSON")
+    p.add_argument("--schema", help="the published JSON Schema")
+    p.add_argument("--governance", help="the governance Receipt, if held")
+    p.add_argument("--payload", help="the payload, if held")
+    p.set_defaults(func=cmd_verify)
+
+    p = sub.add_parser("init", help="generate a keypair and the document to publish")
+    p.add_argument("--key-id", required=True, help="https:// URL or did:web: identifier")
+    p.add_argument("--out", default="vsl-party.pem", help="private key path")
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("trigger", help="sign a trigger for a settlement")
+    p.add_argument("receipt")
+    p.add_argument("--key", required=True, help="your private key")
+    p.add_argument("--key-id", required=True, help="your key_id, as listed on the settlement")
+    p.add_argument("--submit", metavar="URL", help="POST it rather than printing it")
+    p.set_defaults(func=cmd_trigger)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sdcreceipt/party.py

@@ -0,0 +1,223 @@
+#
+# Copyright (c) 2025, Axius SDC, Inc.
+# Licensed under the Apache License, Version 2.0.
+#
+"""
+The party side: hold a key, publish it, sign a trigger.
+
+A settlement identifies each party by a ``key_id`` that **the party controls**,
+either an ``https://`` URL or a ``did:web:`` identifier. That keeps
+verification independent of the issuer, and it means the party has to publish
+one JSON file. This module reduces that to a single command.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec, utils
+
+from sdcreceipt.verify import trigger_message
+
+#: Owner read/write only. A private key readable by other accounts on a shared
+#: machine is a private key you no longer control.
+PRIVATE_KEY_MODE = stat.S_IRUSR | stat.S_IWUSR
+
+
+class PartyError(Exception):
+    """Raised when key material or a settlement is not usable."""
+
+
+def generate_key() -> ec.EllipticCurvePrivateKey:
+    """A P-256 key, which is what ES256 means."""
+    return ec.generate_private_key(ec.SECP256R1())
+
+
+def private_key_pem(key: ec.EllipticCurvePrivateKey) -> bytes:
+    """
+    Serialize a private key, unencrypted.
+
+    Unencrypted is a deliberate, narrow choice: a passphrase this tool prompts
+    for would be typed into scripts and CI, which is worse than a file with
+    correct permissions and an honest warning. Use a KMS or an HSM if the key
+    matters more than that, and this tool will sign with whatever key you
+    hand it.
+    """
+    return key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def public_key_pem(key) -> str:
+    public = key.public_key() if hasattr(key, "public_key") else key
+    return public.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode("ascii")
+
+
+def write_private_key(key: ec.EllipticCurvePrivateKey, path: Path) -> Path:
+    """Write a private key with owner-only permissions, refusing to clobber."""
+    if path.exists():
+        raise PartyError(
+            f"{path} already exists. Refusing to overwrite a private key: if "
+            "it is in use, replacing it invalidates every signature made with "
+            "it. Move it aside deliberately if you mean to rotate."
+        )
+    path.write_bytes(private_key_pem(key))
+    os.chmod(path, PRIVATE_KEY_MODE)
+    return path
+
+
+def load_private_key(path: Path) -> ec.EllipticCurvePrivateKey:
+    """Load a P-256 private key, warning if the file is world-readable."""
+    try:
+        key = serialization.load_pem_private_key(path.read_bytes(), password=None)
+    except Exception as exc:
+        raise PartyError(f"Could not read a private key from {path}: {exc}") from exc
+
+    if not isinstance(key, ec.EllipticCurvePrivateKey) or not isinstance(
+        key.curve, ec.SECP256R1
+    ):
+        raise PartyError(
+            f"{path} is not an ECDSA P-256 key, which is the only curve VSL "
+            "signatures use (alg ES256)."
+        )
+    return key
+
+
+def key_document(key, key_id: str) -> dict[str, Any]:
+    """
+    The document a party publishes at their ``key_id``.
+
+    Shaped like the issuer's published key set so one verifier reads both.
+    """
+    return {
+        "issuer": key_id,
+        "keys": [
+            {
+                "key_id": key_id,
+                "algorithm": "EC_SIGN_P256_SHA256",
+                "alg": "ES256",
+                "public_key_pem": public_key_pem(key),
+                "status": "active",
+            }
+        ],
+    }
+
+
+def publication_path(key_id: str) -> str:
+    """
+    Where the key document has to be reachable for `key_id` to resolve.
+
+    Returned so `init` can tell the operator exactly what to publish, rather
+    than leaving them to infer it from a specification.
+    """
+    if key_id.startswith("https://"):
+        return key_id
+    if key_id.startswith("did:web:"):
+        remainder = key_id[len("did:web:"):]
+        segments = remainder.split(":")
+        domain = segments[0].replace("%3A", ":")
+        if len(segments) == 1:
+            return f"https://{domain}/.well-known/did.json"
+        return f"https://{domain}/{'/'.join(segments[1:])}/did.json"
+    raise PartyError(
+        f"Unsupported key_id {key_id!r}. It must be an https URL or a did:web "
+        "identifier, so that you control it and verification does not route "
+        "through the issuer."
+    )
+
+
+def sign_trigger(
+    key: ec.EllipticCurvePrivateKey, receipt: dict[str, Any], key_id: str
+) -> dict[str, Any]:
+    """
+    Produce a trigger for a Receipt.
+
+    Signs ``{condition_hash, receipt_id}``. Both are fixed before either party
+    signs, so the two can sign alone and in any order, while the signature
+    still cannot be replayed into another settlement.
+
+    Raises:
+        PartyError: If `key_id` is not a party to this settlement, which is
+            worth catching here rather than after a round trip.
+    """
+    settlement = receipt.get("settlement")
+    if not settlement:
+        raise PartyError("This Receipt has no settlement block to trigger.")
+
+    parties = settlement.get("parties", [])
+    if key_id not in parties:
+        raise PartyError(
+            f"{key_id} is not a party to this settlement. Listed parties:\n  "
+            + "\n  ".join(parties)
+        )
+
+    already = {t.get("key_id") for t in settlement.get("triggers", [])}
+    if key_id in already:
+        raise PartyError(
+            f"{key_id} has already triggered this settlement. A second "
+            "trigger adds no authorization."
+        )
+
+    message = trigger_message(receipt["receipt_id"], settlement["condition_hash"])
+    der = key.sign(message, ec.ECDSA(hashes.SHA256()))
+    r, s = utils.decode_dss_signature(der)
+
+    import base64
+
+    raw = r.to_bytes(32, "big") + s.to_bytes(32, "big")
+    signature = base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+    from datetime import datetime, timezone
+
+    return {
+        "receipt_id": receipt["receipt_id"],
+        "key_id": key_id,
+        "signature": signature,
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+
+
+def load_key_set(document: dict[str, Any]) -> dict[str, Any]:
+    """
+    Turn a published key document into ``{key_id: public_key}``.
+
+    Accepts the issuer key-set shape and a did:web DID document, so a party
+    does not have to publish a second document just for this tool.
+    """
+    keys: dict[str, Any] = {}
+
+    for entry in document.get("keys", []):
+        pem = entry.get("public_key_pem")
+        if pem and entry.get("key_id"):
+            keys[entry["key_id"]] = serialization.load_pem_public_key(
+                pem.encode("ascii")
+            )
+
+    for method in document.get("verificationMethod", []):
+        pem = method.get("publicKeyPem")
+        if pem and method.get("id"):
+            keys[method["id"]] = serialization.load_pem_public_key(pem.encode("ascii"))
+
+    if not keys:
+        raise PartyError(
+            "No usable keys in that document. Expected a `keys` array with "
+            "key_id and public_key_pem, or a DID document verificationMethod."
+        )
+    return keys
+
+
+def load_key_set_file(path: Path) -> dict[str, Any]:
+    try:
+        return load_key_set(json.loads(path.read_text()))
+    except json.JSONDecodeError as exc:
+        raise PartyError(f"{path} is not valid JSON: {exc}") from exc

sdcreceipt/verify.py

@@ -0,0 +1,311 @@
+#
+# Copyright (c) 2025, Axius SDC, Inc.
+# Licensed under the Apache License, Version 2.0.
+#
+"""
+Verify a VSL Settlement Receipt.
+
+Implements the published verification procedure. Nothing here contacts a
+network or requires an account: keys are supplied by the caller, because the
+procedure permits verifying from a key retained earlier. **If this module ever
+needs to fetch something to do its job, the property it exists to demonstrate
+has quietly stopped being true.**
+
+★ Keys are parameters, and that is a security property rather than a
+convenience. The caller decides which keys are acceptable *before* this reads
+the Receipt, so a Receipt cannot nominate the key used to judge it. Resolving
+a key from a location carried inside the artifact lets a forged document name
+the forger's key and verify against it. Do not add an overload that fetches.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from typing import Any
+
+from sdcreceipt.canonical import canonicalize_bytes
+
+#: Excluded from `receipt_hash`. Signatures sign the hash, so they cannot be
+#: inside it, and triggers are appended after hashing so the parties can sign
+#: independently and out of order.
+HASH_EXCLUDED = ("receipt_hash", "signatures")
+
+
+@dataclass
+class Check:
+    name: str
+    passed: bool
+    detail: str = ""
+
+    def __str__(self) -> str:
+        return f"{'PASS' if self.passed else 'FAIL'}  {self.name}: {self.detail}"
+
+
+@dataclass
+class Result:
+    """
+    Every check that ran, not just the first failure.
+
+    Stopping early tells an implementer one thing per run, and hides the case
+    that matters most: a Receipt whose signature verifies but whose governance
+    binding does not.
+    """
+
+    checks: list[Check] = field(default_factory=list)
+
+    def record(self, name: str, passed: bool, detail: str = "") -> None:
+        self.checks.append(Check(name, passed, detail))
+
+    @property
+    def ok(self) -> bool:
+        return bool(self.checks) and all(c.passed for c in self.checks)
+
+    @property
+    def failures(self) -> list[Check]:
+        return [c for c in self.checks if not c.passed]
+
+    def __str__(self) -> str:
+        return "\n".join(str(c) for c in self.checks)
+
+
+def canonical_content(receipt: dict[str, Any]) -> bytes:
+    """The exact bytes `receipt_hash` commits to."""
+    content = {k: v for k, v in receipt.items() if k not in HASH_EXCLUDED}
+    if "settlement" in content:
+        content["settlement"] = {
+            k: v for k, v in receipt["settlement"].items() if k != "triggers"
+        }
+    return canonicalize_bytes(content)
+
+
+def receipt_digest(receipt: dict[str, Any]) -> bytes:
+    """
+    The 32 raw bytes a signature covers.
+
+    Identical to the value `receipt_hash` records in hex, so a verifier
+    computes it once and uses it for both checks.
+    """
+    return hashlib.sha256(canonical_content(receipt)).digest()
+
+
+def trigger_message(receipt_id: str, condition_hash: str) -> bytes:
+    """
+    What a party signs to trigger a settlement.
+
+    `receipt_id` is included deliberately: a signature over `condition_hash`
+    alone is replayable into any other Receipt sharing that release condition,
+    and repeat trading relationships reuse conditions as a matter of course.
+    """
+    return canonicalize_bytes(
+        {"condition_hash": condition_hash, "receipt_id": receipt_id}
+    )
+
+
+def _b64url_to_raw(value: str) -> bytes:
+    import base64
+
+    raw = base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+    if len(raw) != 64:
+        raise ValueError(
+            f"expected a 64-byte P1363 signature, got {len(raw)} bytes "
+            "(a DER signature is variable length and will not be 64)"
+        )
+    return raw
+
+
+def _verify_ecdsa(public_key, message: bytes, signature: str, *, prehashed: bool) -> str:
+    """Return "" on success, or the reason it failed."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.asymmetric import ec, utils
+
+    try:
+        raw = _b64url_to_raw(signature)
+    except Exception as exc:
+        return f"malformed signature: {exc}"
+
+    algorithm = (
+        ec.ECDSA(utils.Prehashed(hashes.SHA256()))
+        if prehashed
+        else ec.ECDSA(hashes.SHA256())
+    )
+    try:
+        public_key.verify(
+            utils.encode_dss_signature(
+                int.from_bytes(raw[:32], "big"), int.from_bytes(raw[32:], "big")
+            ),
+            message,
+            algorithm,
+        )
+    except InvalidSignature:
+        return "does not verify against the stated key"
+    return ""
+
+
+def verify(
+    receipt: dict[str, Any],
+    *,
+    issuer_keys: dict[str, Any],
+    party_keys: dict[str, Any] | None = None,
+    schema: dict[str, Any] | None = None,
+    governance_receipt: dict[str, Any] | None = None,
+    payload: bytes | None = None,
+) -> Result:
+    """
+    Run the verification procedure over one Receipt.
+
+    Args:
+        receipt: The Receipt.
+        issuer_keys: ``{key_id: public_key}``. Held or fetched beforehand.
+        party_keys: ``{key_id: public_key}`` for triggers. Omit to skip that
+            step, which is legitimate when the keys are not held.
+        schema: The published JSON Schema, to check shape first.
+        governance_receipt: The governance Receipt, if held.
+        payload: The payload, if held.
+    """
+    result = Result()
+
+    if schema is not None:
+        import jsonschema
+
+        errors = sorted(
+            jsonschema.Draft202012Validator(schema).iter_errors(receipt),
+            key=lambda e: list(e.absolute_path),
+        )
+        result.record(
+            "schema",
+            not errors,
+            "conforms" if not errors else f"{len(errors)} violation(s): {errors[0].message}",
+        )
+        if errors:
+            return result
+
+    recomputed = hashlib.sha256(canonical_content(receipt)).hexdigest()
+    matches = recomputed == receipt.get("receipt_hash")
+    result.record(
+        "receipt_hash",
+        matches,
+        "matches the canonical content"
+        if matches
+        else (
+            f"recorded {receipt.get('receipt_hash')} but content hashes to "
+            f"{recomputed}. If this is your only failure, suspect "
+            "canonicalization: RFC 8785 renders an integral float as 1, not 1.0"
+        ),
+    )
+
+    digest = receipt_digest(receipt)
+    for signature in receipt.get("signatures", []):
+        key_id = signature.get("key_id", "")
+        label = f"signature[{key_id}]"
+
+        if signature.get("alg") != "ES256":
+            result.record(label, False, f"alg is {signature.get('alg')!r}, expected ES256")
+            continue
+
+        key = issuer_keys.get(key_id)
+        if key is None:
+            result.record(
+                label,
+                False,
+                f"no key held for {key_id!r}. Resolve it from the published "
+                "key set, never from a location inside the Receipt",
+            )
+            continue
+
+        reason = _verify_ecdsa(key, digest, signature.get("sig", ""), prehashed=True)
+        result.record(label, not reason, reason or "verifies over receipt_hash")
+
+    if not receipt.get("signatures"):
+        result.record("signatures", False, "the Receipt carries no signature")
+
+    settlement = receipt.get("settlement", {})
+    parties = settlement.get("parties", [])
+    triggers = settlement.get("triggers", [])
+
+    if party_keys is not None:
+        message = trigger_message(
+            receipt.get("receipt_id", ""), settlement.get("condition_hash", "")
+        )
+        for trig in triggers:
+            key_id = trig.get("key_id", "")
+            label = f"trigger[{key_id}]"
+
+            if key_id not in parties:
+                result.record(label, False, f"{key_id!r} is not a listed party")
+                continue
+
+            key = party_keys.get(key_id)
+            if key is None:
+                result.record(label, False, f"no key held for party {key_id!r}")
+                continue
+
+            reason = _verify_ecdsa(
+                key, message, trig.get("signature", ""), prehashed=False
+            )
+            result.record(
+                label,
+                not reason,
+                reason or "verifies over {condition_hash, receipt_id}",
+            )
+            if reason:
+                result.checks[-1].detail += (
+                    ". If it is well formed, check whether it belongs to a "
+                    "different Receipt sharing this release condition"
+                )
+
+        duplicated = len(triggers) != len({t.get("key_id") for t in triggers})
+        result.record(
+            "triggers.unique",
+            not duplicated,
+            "one trigger per party"
+            if not duplicated
+            else "a party appears more than once, overstating agreement",
+        )
+
+    complete = bool(parties) and {t.get("key_id") for t in triggers} >= set(parties)
+    result.record(
+        "settlement.complete",
+        complete,
+        "every listed party has triggered"
+        if complete
+        else f"awaiting {sorted(set(parties) - {t.get('key_id') for t in triggers})}",
+    )
+
+    if governance_receipt is not None:
+        expected = receipt.get("governance", {}).get("receipt_hash")
+        actual = governance_receipt.get("receipt_hash")
+        result.record(
+            "governance.receipt_hash",
+            actual == expected,
+            "binds the governance Receipt that produced the verdict"
+            if actual == expected
+            else (
+                f"commits to {expected} but the held Receipt is {actual}. "
+                "The verdict is signed and unsupported"
+            ),
+        )
+
+        verdict = receipt.get("governance", {}).get("decision")
+        held = governance_receipt.get("decision")
+        result.record(
+            "governance.decision",
+            verdict == held,
+            f"matches ({verdict})"
+            if verdict == held
+            else f"Receipt says {verdict!r}, governance Receipt says {held!r}",
+        )
+
+    if payload is not None:
+        expected = receipt.get("payload_hash")
+        actual = hashlib.sha256(payload).hexdigest()
+        result.record(
+            "payload_hash",
+            actual == expected,
+            "commits to the payload held"
+            if actual == expected
+            else f"recorded {expected} but the payload hashes to {actual}",
+        )
+
+    return result

sdcreceipt-4.0.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: sdcreceipt
+Version: 4.0.0
+Summary: Verify and settle VSL Settlement Receipts. No account, no network for verification.
+Author: Axius SDC, Inc.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/SemanticDataCharter/sdcreceipt
+Keywords: vsl,settlement,receipt,xmldsig,rfc8785,sdc
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sdcgovernance>=4.2.0
+Requires-Dist: cryptography>=42.0
+Provides-Extra: schema
+Requires-Dist: jsonschema>=4.20; extra == "schema"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: jsonschema>=4.20; extra == "dev"
+Dynamic: license-file
+
+# sdcreceipt
+
+Verify and settle VSL Settlement Receipts.
+
+**Verification needs no account, no network, and nothing from the issuer.**
+That is the point of the tool: a claim that anyone can check a Receipt
+independently is worth exactly as much as the ability to do it.
+
+Apache-2.0.
+
+```bash
+pip install sdcreceipt
+```
+
+## Three verbs
+
+```bash
+# Check a Receipt you were sent. Offline.
+sdcreceipt verify receipt.json --keys issuer-keys.json
+
+# Set yourself up as a party: keypair + the document to publish.
+sdcreceipt init --key-id https://vendor.example/.well-known/vsl-key.json
+
+# Authorize a settlement you are a party to.
+sdcreceipt trigger receipt.json --key vsl-party.pem \
+    --key-id https://vendor.example/.well-known/vsl-key.json
+```
+
+`verify` exits 0 only if every check passed, so it composes in a shell without
+anyone parsing output.
+
+There will not be a fourth verb. This is a client, not a product, and its
+value is in being small enough to read.
+
+---
+
+## If you were sent a Receipt
+
+You do not need an account with anyone.
+
+```bash
+pip install sdcreceipt
+curl -O https://sdcstudio.axius-sdc.com/.well-known/sdcstudio-signing-keys.json
+sdcreceipt verify receipt.json --keys sdcstudio-signing-keys.json
+```
+
+Every check is reported, not just the first failure:
+
+```
+PASS  schema: conforms
+PASS  receipt_hash: matches the canonical content
+PASS  signature[sdcstudio-signing-key-v1]: verifies over receipt_hash
+PASS  trigger[https://vendor.example/.well-known/vsl-key.json]: verifies
+PASS  settlement.complete: every listed party has triggered
+
+VERIFIED
+```
+
+A Receipt carries **hash commitments, never the payload**. So verification
+tells you a conformant, authorized, dual-triggered exchange occurred, without
+anyone having to disclose what was exchanged. If you also hold the payload or
+the governance Receipt, pass them and those get checked too:
+
+```bash
+sdcreceipt verify receipt.json --keys keys.json \
+    --payload manifest.xml --governance governance-receipt.json
+```
+
+## If you need to become a party
+
+A settlement identifies each party by a `key_id` that **you** control. That is
+deliberate: it means verifying your signature does not route through the
+issuer, so nobody has to stay alive for your old signatures to keep meaning
+something.
+
+```bash
+sdcreceipt init --key-id https://vendor.example/.well-known/vsl-key.json
+```
+
+That writes a private key (mode `0600`) and a key document, and tells you the
+exact URL the document must be reachable at. Publishing one JSON file is the
+whole onboarding requirement.
+
+Then, when you are sent a Receipt to authorize:
+
+```bash
+sdcreceipt trigger receipt.json --key vsl-party.pem --key-id <your key_id>
+```
+
+It prints a signed trigger and stops. **Signing is inert; submitting is a side
+effect**, so you send it yourself, or add `--submit <url>`.
+
+---
+
+## ★ Never take the verification key from the document
+
+> The set of keys you will accept is decided **before** you read the document,
+> and the document cannot change it.
+
+`ds:RetrievalMethod` in XML-Signature, `jku` and `x5u` in JOSE, and their
+equivalents elsewhere all say *"here is where my key lives."* That pointer was
+written by whoever produced the document, so following it asks the document to
+nominate the key that will judge it. A forged document nominates the forger's
+key and verification "succeeds."
+
+The failure is quiet. A pointer can name a domain that was correct when the
+document was signed and has since lapsed; anyone who registers it can serve a
+key at that path, and nothing about the document looks wrong — because nothing
+about it *is* wrong. The verifier was asked where to look and did as it was
+told.
+
+This tool cannot make that mistake: `verify` takes keys as arguments and has
+no code path that fetches one. That is a security property, not an
+inconvenience.
+
+The same applies to party keys, with a corollary rather than an exemption.
+Those `key_id`s *are* URIs the counterparty controls, deliberately. Resolve
+them over HTTPS only, only for identifiers already recorded in a Receipt you
+trust, and keep a copy — a party who later loses a domain must not be able to
+change what their old signatures mean.
+
+---
+
+## Conformance
+
+`tests/conformance/` ships the issuer's published vectors, and the suite runs
+this implementation against them.
+
+Ten vectors. **Every invalid one encodes a defect that was actually made**,
+not a hypothetical: a DER signature where ES256 requires P1363, a signature
+over the hex text of `receipt_hash` rather than its raw bytes, a governance
+binding that does not match the evidence held, a trigger replayed from another
+Receipt sharing the same release condition, and so on. Failing one for the
+wrong reason does not count — the manifest names the check that must break.
+
+```bash
+pytest
+```
+
+**On independence, honestly.** Passing these vectors shows this tool agrees
+with the issuer's published expectations, and that it never drifted from them.
+It is *not* an independent re-derivation: this implementation and the issuer's
+share design and history. The vectors are most valuable to someone writing a
+verifier from the specification alone, which is what they are published for.
+
+## Building your own
+
+You do not have to use this tool, and the specification does not depend on it.
+If you are writing a verifier:
+
+**Do not write a second canonicalizer.** Use `sdcgovernance` or another
+conformant RFC 8785 implementation. A second implementation can disagree with
+the first, and the disagreement is silent: the bytes differ, so the hash
+differs, and the artifact reads as tampered with rather than misencoded. This
+tool re-exports `sdcgovernance.jcs` for exactly that reason and adds nothing.
+
+**Refuse rather than guess.** Integers beyond ±(2⁵³−1) cannot round-trip
+through an IEEE 754 double, and `NaN`/`Infinity` have no JSON representation.
+Emitting something for those produces a hash that looks fine and fails only in
+someone else's verifier.
+
+**Report every check.** Stopping at the first failure hides the case that
+matters most: a Receipt whose signature verifies but whose governance binding
+does not.
+
+**Check the curve.** A signature verified against a key on an unexpected curve
+proves nothing about the party you believe signed.
+
+## Versioning
+
+MAJOR tracks the **SDC reference model**, so a `4.x.x` release targets SDC4.
+It starts at 4 rather than 0 because of that convention, not because there
+were three earlier versions. MINOR is features, PATCH is fixes. An SDC5
+reference model would make this `5.x.x`.
+
+The same scheme is used by `sdcvalidator`, `sdcgovernance` and the rest of the
+family, so a version number tells you which reference model an artifact
+targets without looking anything up.
+
+Note that the **Receipt format version is separate** and independent: a
+Receipt says `"version": "1.0"`, which is the frozen wire format, not this
+package.
+
+## Dependencies
+
+`sdcgovernance` for canonicalization and `cryptography` for ECDSA, both
+Apache-2.0-compatible libraries. `jsonschema` is optional and only needed for
+`--schema`.
+
+These are **library** dependencies. Nothing here calls a service, and
+`verify` makes no network request at all.

sdcreceipt-4.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sdcreceipt/__init__.py,sha256=HwPI883tuViDEDCcFFXc9oMYcR9uBC97Sjgb4wmn7OE,771
+sdcreceipt/canonical.py,sha256=bj_uih8ue4mt2Yta6ocjFoxYP-lyKNEiRUuDjdfUQTA,991
+sdcreceipt/cli.py,sha256=90DWZzg-24HG6HumARpw7IaG1tJ1S_MrwXHJ7cDyp68,6601
+sdcreceipt/party.py,sha256=aEcS0dmxT_hGJdcV5td_oFhMzksZZQtN-kcpTKvalpo,7609
+sdcreceipt/verify.py,sha256=Rstys3ebZk5usuEGBrnZ0hCDfptI1uI2ExQuoDEHhsM,10464
+sdcreceipt-4.0.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+sdcreceipt-4.0.0.dist-info/METADATA,sha256=OBcTuIbTFkZ_5bKBptfa9dw81OU3dPHaAB599yusygI,7837
+sdcreceipt-4.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sdcreceipt-4.0.0.dist-info/entry_points.txt,sha256=cvW-ifbjP8fI1RjYb92cUG-b5c_hOJmIm7YCTkws28k,51
+sdcreceipt-4.0.0.dist-info/top_level.txt,sha256=9VQe_SVo6LhxHG_Ibub8z7ktonhRc9FlRvMSaMMM1lE,11
+sdcreceipt-4.0.0.dist-info/RECORD,,

sdcreceipt-4.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sdcreceipt-4.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sdcreceipt = sdcreceipt.cli:main

sdcreceipt-4.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sdcreceipt-4.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sdcreceipt