Sdcreceipt

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.

pip install sdcreceipt

Four verbs

# Check a Receipt you were sent. Offline.

sdcreceipt verify receipt.json --issuer-keys issuer-keys.json --party-keys party-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

Ask an issuer for a Receipt. The one verb that needs an account.

sdcreceipt settle payload.xml \ --party https://vendor.example/.well-known/vsl-key.json \ --party did:web:partner.example

settle prompts for anything it needs and was not given, except current_state, which defaults to the payload's own . It writes the Receipt to --out (or stdout), ready for verify and trigger; --response FILE also keeps the issuer's whole answer (the governance decision and the charge). A DENY is issued and signed but accepts no triggers, and settle says so. Two of its fields are not guessable and never were: the release condition is hashed by the issuer and never stored, and current_state/target_state come from a governance workflow defined in a schema the issuer holds, not you.

If the issuer refuses the transition it answers with the ones it would have accepted, and settle prints them:

Governance evaluation produced no Receipt. Decision was DENY

From 'draft' you can go to: review

This model's workflow: standard: draft -> review -> published

It exits 2 there, and 1 on a real failure, so a script can tell "ask again differently" from "something is broken".

verify exits 0 only if every check passed, so it composes in a shell without anyone parsing output.

That is the whole surface. This is a client, not a product, and its value is in being small enough to read.

Try it without reading anything

python examples/settle.py

One settlement end to end: two parties, two signatures, verified offline. No account, no network, no API key. See examples/.

For an agent

Three of the four verbs over MCP, in the same package:

sdcreceipt-mcp --key vsl-party.pem \

--key-id https://vendor.example/.well-known/vsl-key.json

Exposes verify_receipt, sign_trigger and settle. Each is advertised only when the server has what it needs, so a tool is never offered whose every call would fail.

Two deliberate omissions, and they are the security posture rather than an oversight (see also SECURITY.md):

• No key generation. A private key generated inside an agent session has no clear custody story. init stays a human act at a terminal.
• No submission. sign_trigger returns a signed trigger for you to submit. Submitting takes a destination from the caller, and a signed trigger plus an arbitrary host is the combination worth refusing.

settle is available when the server is started with --endpoint and a token, and it is the only tool that reaches the network. The endpoint is fixed at start-up exactly like the key, so a caller can never redirect where a payload goes. No tool takes a URL, and that is the invariant to keep if this ever grows another one.

The signing key is given at start-up, never in a tool call, so it does not travel through the conversation.

---

If you were sent a Receipt

You do not need an account with anyone. You need the issuer's published key document and, for a settled Receipt, each party's. The Receipt names the parties by the URIs they publish their keys at; the issuer's key document is at a fixed well-known path.

pip install sdcreceipt

curl -o receipt.json https://sdcstudio.axius-sdc.com/api/v1/vsl/receipt/ # or the file you were sent curl -O https://sdcstudio.axius-sdc.com/.well-known/sdcstudio-signing-keys.json curl -o vendor-keys.json https://vendor.example/.well-known/vsl-key.json curl -o partner-keys.json https://partner.example/.well-known/did.json sdcreceipt verify receipt.json --issuer-keys sdcstudio-signing-keys.json \ --party-keys vendor-keys.json --party-keys partner-keys.json

The issuer's document checks the issuer's signatures; each party's document checks only that party's trigger. The roles come from your command line, never from the Receipt, and a key_id that two documents claim is refused. Since 4.3.3 the old --keys flag is refused: it pooled every document, which let a party's own document supply an issuer key (GHSA-gwhr-82j5-883w).

After the checks, verify lists what VERIFIED does not cover: trigger timestamps are not signed, key validity windows are not compared with the Receipt's time, a chain link (previous_hash) is not followed, and the payload and governance Receipt are checked only if you pass them.

Every check is reported, not just the first failure:

PASS  receipt_hash: matches the canonical content

PASS signature[sdcstudio-signing-key-v1]: verifies over receipt_hash (ES256) PASS signature[sdcstudio-pq-signing-key-v1]: verifies over receipt_hash (ML-DSA-65) PASS signatures.algorithms: carries every signature version 1.1 requires (ES256, ML-DSA-65) PASS trigger[https://vendor.example/.well-known/vsl-key.json]: verifies over {condition_hash, receipt_id} PASS trigger[did:web:partner.example]: verifies over {condition_hash, receipt_id} PASS triggers.unique: one trigger per party PASS settlement.complete: every listed party has triggered

VERIFIED

With only the issuer's document, the issuer signature and the hashes are checked and settlement.complete is recorded as unestablished, so the Receipt does not verify: whether every party triggered is a claim about authorization, and no trigger signature was checked. That is the correct answer, not a defect. Pass --schema settlement-receipt-1.0.schema.json (or -1.1, matching the Receipt's version) as well to check the shape first (pip install 'sdcreceipt[schema]').

Receipt 1.1 (since 4.3.0) is 1.0 signed twice: an ES256 and an ML-DSA-65 (FIPS 204, post-quantum) signature by the issuer over the same 32-byte digest. Every listed signature must verify, and a Receipt that says 1.1 must carry both; a 1.0 Receipt keeps verifying exactly as before. The issuer's key document lists both keys, each with its alg. ML-DSA-65 verification comes from cryptography 48 or later, which this tool requires.

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:

sdcreceipt verify receipt.json --issuer-keys issuer-keys.json --party-keys party-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.

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:

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 .

---

★ 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_ids *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.

Supply them, too. Party keys are optional in the sense that the issuer signature and the payload hash can be checked without them, and not in the sense that a settled Receipt means anything without them. Whether every party triggered is a claim about authorization, so with no key to check a signature against, settlement.complete is recorded as unestablished rather than passed and the Receipt does not verify. Before 4.2.1 it passed on a comparison of key_id strings alone, which reported VERIFIED over fabricated triggers.

---

Conformance

tests/conformance/ ships the issuer's published vectors, and the suite runs this implementation against them.

Sixteen vectors, eleven at Receipt 1.0 and five at 1.1 (each checked against the schema its own version names). 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.

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.

The canonicalization underneath them is a different case, and it has been checked against an independent implementation. Every hash in a Receipt is taken over RFC 8785 canonical bytes, so agreement on canonicalization is what the rest of the verification rests on. In September 2026 that agreement was tested in both directions with the MTCP project (Ahmad Abby), which implements RFC 8785 using Trail of Bits rfc8785 rather than sdcgovernance:

• MTCP's five published vectors were run against sdcgovernance.jcs. Byte-for-byte agreement on the canonical string and on SHA-256, for every vector. The set is a clean regeneration published 9 September 2026, carrying synthetic values in the real schema: audit_record, evaluation_summary, score_record, sensor_calibration and arabic_content. It supersedes the four-vector set of 1 September, and the field carrying the ca