sdcreceipt-ts

Verify VSL Settlement Receipts, sign settlement triggers and request Receipts from an issuer in TypeScript, with the same results as sdcreceipt, the reference implementation.

Conforms to:

• the VSL conformance kit 1.1: all 17 Receipt vectors, each invalid one failing on the check the manifest names, and all 5 key-document cases;
• sdcgovernance's vectors: all 21 RFC 8785 vectors, and the decision-table and governance-Receipt vectors (every table hash, all 37 evaluations, all 9 governance Receipts).

CI runs both, pinned to a fixed commit and release.

It runs in Node (20 or later), Deno and browsers. Verifying and signing need no network and no account. You supply the keys, so a Receipt can never nominate the key it is judged by. Only settle reaches an issuer.

import { assembleKeys, verify } from 'sdcreceipt-ts';

// Key documents, each in the role YOU assign. Never from a location inside the Receipt.
const keys = await assembleKeys([
  { role: 'issuer', document: issuerKeyDocument },  // https://sdcstudio.axius-sdc.com/.well-known/sdcstudio-signing-keys.json
  { role: 'party', document: vendorKeyDocument },
  { role: 'party', document: buyerKeyDocument },
]);

const result = await verify(receipt, { ...keys, governanceReceipt, payload });
result.ok;        // true only if every check passed
result.checks;    // every check that ran, passed or not: receipt_hash, signature[...], trigger[...], ...

What verify checks:

• receipt_hash: recomputed over the RFC 8785 canonical content.
• Signatures: every issuer signature over the 32-byte digest. That's ES256 for Receipt 1.0, and both ES256 and ML-DSA-65 (FIPS 204) for Receipt 1.1.
• Triggers: each party's trigger over {condition_hash, receipt_id}, with the check that no party triggered twice.
• Governance binding and payload hash: checked when you hold the governance Receipt and the payload.

It reports every check, never only the first failure. A settled Receipt checked without party keys does not verify: settlement.complete is recorded as unestablished, never decided by comparing key_id strings.

What assembleKeys refuses:

• a key_id that two documents publish;
• a key_id listed twice in one document;
• one key in both roles.

A key marked revoked fails any signature it made.

Signing a trigger (the party side)

import { generateKey, keyDocument, signTrigger } from 'sdcreceipt-ts';

const { privateKey, publicKey } = await generateKey();          // ECDSA P-256 (ES256)
const published = await keyDocument(publicKey, myKeyId);         // publish this at your key_id
const trigger = await signTrigger(privateKey, receipt, myKeyId); // returned, never submitted

Keys exchange as PKCS#8 and SPKI PEM (privateKeyPem, loadPrivateKey), the files sdcreceipt reads and writes. Triggers move both ways: sdcreceipt verifies a trigger signed here, and this library verifies one sdcreceipt signed.

Requesting a Receipt (settle)

import { settle, splitResponse, SettleRejected } from 'sdcreceipt-ts';

try {
  const answer = await settle(payloadXml, {
    token: process.env.SDCRECEIPT_TOKEN!,   // an SDCStudio API token; the endpoint defaults to SDCStudio's
    targetState: 'shipped',                 // currentState defaults to the payload's own <current-state>
    condition: { on: 'goods received' },    // hashed by the issuer, never stored
    parties: [vendorKeyId, buyerKeyId],     // at least two, each a key_id its party controls
  });
  const { receipt } = splitResponse(answer); // the signed Receipt, out of the issuer's envelope
} catch (e) {
  if (e instanceof SettleRejected) console.log(e.explain()); // the transitions that would have worked
}

This is the one function

... View full README on GitHub