@postcept/receipt 1.1.1 → 1.2.0

package/README.md

@@ -1,9 +1,15 @@
 # @postcept/receipt
 
-Reference implementation for verifying Postcept Receipts and VCR-audit badges. It
-runs anywhere JavaScript runs (browser, Node, Deno, edge), and verifying a receipt
-needs nothing from Postcept except the published public key. You don't have to
-trust an API to trust the result.
+A Postcept Receipt is a signed proof that an AI agent's high-risk action (a refund,
+a cancellation, a credit) was checked against the system of record, and of what that
+check found: verified, incomplete, duplicated, mismatched, or policy-failed. This
+is the reference library for verifying one.
+
+It runs anywhere JavaScript runs (browser, Node, Deno, edge), and verifying a
+receipt needs nothing from Postcept except the published public key. No API call,
+and no taking the agent's word for it. A valid signature proves the receipt is
+authentic and unmodified since issue. See the spec for what that does and does not
+cover.
 
 The format and signing scheme are written up in [SPEC.md](./SPEC.md). This is the
 canonical JS implementation of that spec. The Postcept API signs with a
@@ -51,6 +57,24 @@ One source of truth for the verification logic. Postcept's own site and audit to
 import this same package, and so can you. The "you don't have to trust us" claim
 only holds if the reference implementation is open and stands on its own.
 
+## Verifying a release
+
+Every published version carries a signed npm provenance statement linking the
+tarball to the commit and CI workflow that built it, plus a CycloneDX SBOM
+attached to the GitHub release.
+
+```sh
+# Check the installed package's provenance and registry signatures:
+npm audit signatures
+
+# Inspect what shipped (attached to the GitHub release):
+#   sbom.cyclonedx.json
+```
+
+The receipt format is verifiable on its own with the public key, as the spec
+describes. Release provenance is a separate check that the code you installed is
+the code this repo built.
+
 ## License
 
 MIT.

package/SPEC.md

@@ -5,10 +5,22 @@
 A Postcept Receipt is a signed, tamper-evident proof that a high-risk AI-agent
 action (a refund, a cancellation, a ticket resolution) was checked against the
 system of record and classified. This document specifies the receipt format and
-how to verify it without going through Postcept: no API call, no trust required.
+how to verify it without going through Postcept: no API call required.
 
-The point is neutrality. A customer, an auditor, or a counterparty can verify a
-receipt with nothing but the public key and the rules below.
+The point is independent verifiability. A customer, an auditor, or a counterparty
+can check a receipt with nothing but the public key and the rules below.
+
+## What a receipt proves, and what it doesn't
+
+A valid signature proves the receipt was issued by the holder of the signing key
+and has not been altered since. The named postconditions were evaluated against
+the named system of record, classified as recorded, at the recorded time, for the
+recorded tenant, in test or live mode as flagged. It does not on its own prove
+that the source system answered truthfully, that the state stayed the same after
+`valid_as_of` (a later receipt can supersede this one when re-verification finds
+the truth changed), or that the action was appropriate in the first place. Trust
+in the receipt is trust in the signing key. Verify against the published key
+registry, and pin it if your risk model calls for that.
 
 ## 1. Signature scheme
 
@@ -17,6 +29,9 @@ receipt with nothing but the public key and the rules below.
   field.
 - **Public key:** base64-encoded raw 32-byte Ed25519 public key. Fetch the current
   key from `GET /v1/signing-key`, which returns `{ algorithm, key_id, public_key }`.
+  `GET /v1/signing-keys` returns the full registry, the active key plus retired
+  keys kept published so receipts signed before a rotation stay verifiable. Pick
+  the entry whose `key_id` matches the receipt's `signing_key_id`.
 - **Key id:** `ed25519:<first-16-chars-of-url-safe-base64(public_key)>`, in
   `signing_key_id`. A receipt names the key that signed it, so old receipts stay
   verifiable after a key rotation.
@@ -37,6 +52,27 @@ receipt JSON as transmitted. To reproduce the signed bytes:
 This is what Python's `json.dumps(body, sort_keys=True, separators=(",", ":"))`
 produces.
 
+### Constraints and rejection
+
+The scheme is injective over the value domain the signing bodies use, given these
+constraints. A compliant verifier MUST reject anything outside them rather than
+guess.
+
+- **Numbers** are finite integers or decimals. `NaN`, `Infinity`, and `-Infinity`
+  are not valid JSON and MUST be rejected, not serialized.
+- **Strings** are valid UTF-8. Every code point outside printable ASCII is
+  `\uXXXX`-escaped (surrogate pairs for astral characters), so the signed bytes
+  are pure ASCII regardless of transport encoding.
+- **Malformed input**, such as a non-base64 signature or public key, a
+  wrong-length key, or a missing signed field, MUST cause verification to return
+  `false` rather than throw. Both reference implementations do this.
+
+Cross-language parity is checked from both sides against one fixed source of
+truth. The golden vectors in `test/vectors/` carry a public key and a signature
+over specific canonical bytes. The TypeScript suite verifies them and the Python
+implementation verifies byte-identical copies, so a canonicalization drift in
+either language fails its own vector test, not only the other's.
+
 ### Timestamps
 
 Timestamps are ISO-8601 UTC. The signer emits a trailing `Z`
@@ -95,6 +131,50 @@ field is treated as version 1.
 }
 ```
 
+### Version 3 (dual-signature)
+
+v3 adds the fields that were server-asserted metadata in v2 to the signed body,
+so they become tamper-evident, and adds an optional observation role. A v3 receipt
+has two signatures that verify independently.
+
+- **Evaluation role.** Postcept's signature (the receipt's `signature` field) over
+  the v3 signing body. This is what `verifyReceipt` checks.
+- **Observation role.** Present only when a customer-side relay produced the source
+  observation. The relay signs its observation envelope, and the receipt binds
+  `{relay_id, key_id, digest, signature}` where `digest = "sha256:" + hex(sha256(
+  canonicalize(envelope_signing_body)))` and `signature` is the relay's signature
+  over that envelope. `verifyObservation(receipt, envelopeSigningBody, relayKey)`
+  confirms the digest matches and the relay signature verifies. Neither signer can
+  forge the other's statement. The relay attests it observed the source, and
+  Postcept attests it evaluated that observation.
+
+The v3 signing body is the v2 body with `version: "3"` plus:
+
+```jsonc
+{
+  // ...all v2 fields...
+  "version": "3",
+  "algorithm": "ed25519",                 // the signature scheme, now signed
+  "signing_key_id": "ed25519:...",        // the key that signed, now signed
+  "canonicalization": "postcept-canonical-json-v1",  // the scheme in §2, now signed
+  "supersedes": "<receipt_id | null>",
+  "contract_digest": "sha256:... | null",
+  "lifecycle": "finalized | pending_finality | ... | null",
+  "safe_to_claim_complete": true,        // or false / null
+  "correlation_strength": "deterministic | heuristic | ... | null",
+  "observation": {                        // null when no relay produced the source
+    "relay_id": "rly_...",
+    "key_id": "ed25519:...",
+    "digest": "sha256:...",
+    "signature": "<base64 relay signature over the envelope>"
+  }
+}
+```
+
+v3 issuance is gated on the server. v1 and v2 receipts remain valid forever, and
+the verifier dispatches on `version`. A verifier MAY require the observation role
+(for high-assurance, relay-only acceptance) or accept evaluation-only receipts.
+
 ## 4. Verification algorithm
 
 ```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { asciiJson, base64ToBytes, canonicalize, TIMESTAMP_SPELLINGS } from "./canonical.js";
-export { type Postcondition, type Receipt, receiptSigningBody, verifyReceipt } from "./receipt.js";
+export { CANONICALIZATION_SCHEME, type Observation, type Postcondition, type Receipt, receiptSigningBody, verifyObservation, verifyReceipt, } from "./receipt.js";
 export { type AuditBadge, badgeSigningBody, verifyBadge } from "./badge.js";
 export { type ConsistencyProof, type InclusionProof, type SignedTreeHead, receiptLeafHash, verifyConsistency, verifyInclusion, verifyReceiptInLog, verifySignedTreeHead, } from "./transparency.js";
 export { type EvidenceExportLike, type EvidenceManifest, evidenceContentDigest, verifyEvidenceExport, verifyEvidenceManifest, } from "./evidence.js";

package/dist/index.js

@@ -2,7 +2,7 @@
 // and VCR-audit badges. Works in the browser, Node, Deno, and edge runtimes. See
 // SPEC.md for the format and signing scheme.
 export { asciiJson, base64ToBytes, canonicalize, TIMESTAMP_SPELLINGS } from "./canonical.js";
-export { receiptSigningBody, verifyReceipt } from "./receipt.js";
+export { CANONICALIZATION_SCHEME, receiptSigningBody, verifyObservation, verifyReceipt, } from "./receipt.js";
 export { badgeSigningBody, verifyBadge } from "./badge.js";
 export { receiptLeafHash, verifyConsistency, verifyInclusion, verifyReceiptInLog, verifySignedTreeHead, } from "./transparency.js";
 export { evidenceContentDigest, verifyEvidenceExport, verifyEvidenceManifest, } from "./evidence.js";

package/dist/receipt.d.ts

@@ -22,11 +22,23 @@ export interface Receipt {
     algorithm?: string;
     signing_key_id?: string;
     signature: string;
+    supersedes?: string | null;
+    contract_digest?: string | null;
+    lifecycle?: string | null;
+    safe_to_claim_complete?: boolean | null;
+    correlation_strength?: string | null;
+    observation_relay_id?: string | null;
+    observation_key_id?: string | null;
+    observation_digest?: string | null;
+    observation_signature?: string | null;
 }
-/**
- * The exact subset of a receipt the signature covers, by version. `ts` applies a
- * timestamp spelling so the caller can retry "Z" vs "+00:00" (see verifyReceipt).
- */
+export interface Observation {
+    relay_id: string | null;
+    key_id: string | null;
+    digest: string | null;
+    signature: string | null;
+}
+export declare const CANONICALIZATION_SCHEME = "postcept-canonical-json-v1";
 export declare function receiptSigningBody(r: Receipt, ts: (s: string) => string): Record<string, unknown>;
 /**
  * Verify a receipt's Ed25519 signature against a published public key (base64 raw
@@ -34,3 +46,4 @@ export declare function receiptSigningBody(r: Receipt, ts: (s: string) => string
  * input instead of throwing.
  */
 export declare function verifyReceipt(receipt: Receipt, publicKeyB64: string): Promise<boolean>;
+export declare function verifyObservation(receipt: Receipt, envelopeSigningBody: Record<string, unknown>, relayPublicKeyB64: string): Promise<boolean>;

package/dist/receipt.js

@@ -1,34 +1,68 @@
 // The signed receipt object and its verification. Reference implementation of the
 // open standard in SPEC.md.
 import * as ed from "@noble/ed25519";
-import { base64ToBytes, canonicalize, TIMESTAMP_SPELLINGS } from "./canonical.js";
+import { base64ToBytes, canonicalize, sha256Hex, TIMESTAMP_SPELLINGS } from "./canonical.js";
+// Stable identifier for the canonical-JSON scheme (sorted keys, no whitespace,
+// non-ASCII and control characters escaped). Bound into the v3 signing body so the
+// signature covers which scheme produced the bytes. Matches CANONICALIZATION_SCHEME
+// in the control plane. Bump both together if the scheme ever changes.
+export const CANONICALIZATION_SCHEME = "postcept-canonical-json-v1";
 /**
  * The exact subset of a receipt the signature covers, by version. `ts` applies a
  * timestamp spelling so the caller can retry "Z" vs "+00:00" (see verifyReceipt).
  */
+function receiptSigningBodyV2(r, ts) {
+    return {
+        version: "2",
+        id: r.id,
+        org_id: r.org_id ?? null,
+        operation_id: r.operation_id,
+        agent_id: r.agent_id,
+        action: r.action,
+        connectors_checked: r.connectors_checked,
+        test: r.test ?? false,
+        postconditions: (r.postconditions ?? []).map((p) => ({
+            name: p.name,
+            category: p.category ?? null,
+            status: p.status,
+            expected: p.expected ?? null,
+            actual: p.actual ?? null,
+        })),
+        result: r.result,
+        issued_at: ts(r.issued_at),
+        valid_as_of: r.valid_as_of ? ts(r.valid_as_of) : null,
+    };
+}
 export function receiptSigningBody(r, ts) {
-    if (r.version === "2") {
+    if (r.version === "3") {
+        // v3 extends the v2 body with the fields that were server-asserted metadata
+        // in v2, plus the observation role when a relay produced the source.
+        const v2 = receiptSigningBodyV2(r, ts);
         return {
-            version: "2",
-            id: r.id,
-            org_id: r.org_id ?? null,
-            operation_id: r.operation_id,
-            agent_id: r.agent_id,
-            action: r.action,
-            connectors_checked: r.connectors_checked,
-            test: r.test ?? false,
-            postconditions: (r.postconditions ?? []).map((p) => ({
-                name: p.name,
-                category: p.category ?? null,
-                status: p.status,
-                expected: p.expected ?? null,
-                actual: p.actual ?? null,
-            })),
-            result: r.result,
-            issued_at: ts(r.issued_at),
-            valid_as_of: r.valid_as_of ? ts(r.valid_as_of) : null,
+            ...v2,
+            version: "3",
+            // Bind the signature metadata into the protected content (see CANONICALIZATION_SCHEME).
+            algorithm: r.algorithm ?? "ed25519",
+            signing_key_id: r.signing_key_id ?? null,
+            canonicalization: CANONICALIZATION_SCHEME,
+            supersedes: r.supersedes ?? null,
+            contract_digest: r.contract_digest ?? null,
+            lifecycle: r.lifecycle ?? null,
+            safe_to_claim_complete: r.safe_to_claim_complete ?? null,
+            correlation_strength: r.correlation_strength ?? null,
+            observation: r.observation_signature != null
+                ? {
+                    relay_id: r.observation_relay_id ?? null,
+                    key_id: r.observation_key_id ?? null,
+                    digest: r.observation_digest ?? null,
+                    signature: r.observation_signature,
+                }
+                : null,
         };
     }
+    if (r.version === "2") {
+        return receiptSigningBodyV2(r, ts);
+    }
     // Legacy v1 body (name + status only).
     return {
         id: r.id,
@@ -62,3 +96,26 @@ export async function verifyReceipt(receipt, publicKeyB64) {
         return false;
     }
 }
+// The observation role of a v3 receipt. `verifyReceipt` checks the evaluation
+// role, where Postcept signed the result. This checks the source observation:
+// given the original relay envelope's signing body, that it hashes to the digest
+// in the receipt and that the relay's signature verifies against the relay's
+// public key. The two roles together show that the relay observed the source and
+// Postcept evaluated it, with neither able to forge the other's statement.
+// Returns false, never throws, if there is no observation role or anything fails.
+export async function verifyObservation(receipt, envelopeSigningBody, relayPublicKeyB64) {
+    try {
+        if (receipt.observation_signature == null || receipt.observation_digest == null)
+            return false;
+        const canonical = new TextEncoder().encode(canonicalize(envelopeSigningBody));
+        const digest = `sha256:${await sha256Hex(canonical)}`;
+        if (digest !== receipt.observation_digest)
+            return false;
+        const sig = base64ToBytes(receipt.observation_signature);
+        const pub = base64ToBytes(relayPublicKeyB64);
+        return await ed.verifyAsync(sig, canonical, pub);
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@postcept/receipt",
-  "version": "1.1.1",
-  "description": "Reference implementation for verifying Postcept Receipts and VCR-audit badges, independently and in any environment.",
+  "version": "1.2.0",
+  "description": "Independently verify a Postcept Receipt, the signed proof that an AI agent's high-risk action actually happened in the system of record. Runs anywhere, needs only the public key.",
   "license": "MIT",
   "author": "Postcept",
   "type": "module",