@postcept/receipt 1.0.1 → 1.1.0

package/README.md

@@ -6,7 +6,7 @@ needs nothing from Postcept except the published public key. You don't have to
 trust an API to trust the result.
 
 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
+canonical JS implementation of that spec. The Postcept API signs with a
 byte-identical implementation in Python.
 
 ## Install
@@ -39,6 +39,7 @@ on untrusted data.
 | `verifyBadge` | Verify a VCR-audit badge. |
 | `verifyReceiptInLog` | Verify a receipt's transparency-log inclusion and signed tree head. |
 | `verifyInclusion` / `verifySignedTreeHead` | Verify a Merkle inclusion proof or an STH on its own. |
+| `verifyConsistency` | Verify the log only appended between two signed tree heads. |
 | `receiptSigningBody` | The exact body the signature covers, for anyone re-implementing this. |
 | `badgeSigningBody` | The badge signing body. |
 | `canonicalize` | Deterministic JSON encoding (sorted keys, ASCII-escaped). |

package/SPEC.md

@@ -28,10 +28,10 @@ receipt JSON as transmitted. To reproduce the signed bytes:
 
 1. Build the signing body object for the receipt's `version` (§3).
 2. Encode it as **canonical JSON**:
-   - object keys sorted lexicographically (by UTF-16 code unit);
-   - no insignificant whitespace (separators `,` and `:`);
-   - every non-ASCII character escaped as `\uXXXX` (i.e. `ensure_ascii`);
-   - numbers as their shortest round-trip form; integers without a decimal point.
+   - object keys sorted lexicographically (by UTF-16 code unit)
+   - no insignificant whitespace (separators `,` and `:`)
+   - every non-ASCII character escaped as `\uXXXX` (i.e. `ensure_ascii`)
+   - numbers as their shortest round-trip form, integers without a decimal point.
 3. UTF-8 encode the resulting string. Those are the signed bytes.
 
 This is what Python's `json.dumps(body, sort_keys=True, separators=(",", ":"))`
@@ -131,7 +131,7 @@ same way across languages even at whole-number rates.
 ## 6. Machine-readable schema
 
 A JSON Schema for the receipt object ships at `@postcept/receipt/schema`
-(`schema/receipt.schema.json`). It validates shape only; §2 to §4 govern the
+(`schema/receipt.schema.json`). It validates shape only. §2 to §4 govern the
 signature.
 
 ## 7. Transparency log
@@ -153,6 +153,16 @@ removed or back-dated, without taking Postcept's word for it.
   `GET /v1/transparency/proof/{receipt_id}`. Verify it by recomputing the root from
   the leaf and audit path, comparing to the STH `root_hash`, then checking the STH
   signature.
-
-Reference: `verifyReceiptInLog`, `verifyInclusion`, `verifySignedTreeHead`,
-`receiptLeafHash` in this package.
+- **Consistency proof:** `{ first_size, second_size, first_root, second_root, proof
+  [hex], sth }`. Served at `GET /v1/transparency/consistency?first={m}&second={n}`
+  (`second` defaults to the current tree size). It proves the log at `second_size`
+  is an append-only extension of the log at `first_size`. The earlier leaves are
+  unchanged, and nothing was removed, reordered, or back-dated (RFC 6962 §2.1.2). A
+  holder of an earlier signed tree head fetches a proof against it: verify the proof
+  connects the two roots, then check that `first_root` equals the root they
+  remembered and that the returned head is validly signed. Without this, inclusion
+  proofs alone only bind a receipt to *whatever* root the operator serves now. The
+  consistency proof is what makes "append-only" checkable rather than trusted.
+
+Reference: `verifyReceiptInLog`, `verifyInclusion`, `verifyConsistency`,
+`verifySignedTreeHead`, `receiptLeafHash` in this package.

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 { type AuditBadge, badgeSigningBody, verifyBadge } from "./badge.js";
-export { type InclusionProof, type SignedTreeHead, receiptLeafHash, verifyInclusion, verifyReceiptInLog, verifySignedTreeHead, } from "./transparency.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

@@ -4,5 +4,5 @@
 export { asciiJson, base64ToBytes, canonicalize, TIMESTAMP_SPELLINGS } from "./canonical.js";
 export { receiptSigningBody, verifyReceipt } from "./receipt.js";
 export { badgeSigningBody, verifyBadge } from "./badge.js";
-export { receiptLeafHash, verifyInclusion, verifyReceiptInLog, verifySignedTreeHead, } from "./transparency.js";
+export { receiptLeafHash, verifyConsistency, verifyInclusion, verifyReceiptInLog, verifySignedTreeHead, } from "./transparency.js";
 export { evidenceContentDigest, verifyEvidenceExport, verifyEvidenceManifest, } from "./evidence.js";

package/dist/transparency.d.ts

@@ -15,10 +15,30 @@ export interface InclusionProof {
     audit_path: string[];
     sth: SignedTreeHead;
 }
+export interface ConsistencyProof {
+    first_size: number;
+    second_size: number;
+    first_root: string;
+    second_root: string;
+    proof: string[];
+    sth: SignedTreeHead;
+}
 /** The RFC 6962 leaf hash for a receipt (hex), reconstructible from the receipt. */
 export declare function receiptLeafHash(receipt: Receipt): Promise<string>;
 /** Verify a Merkle inclusion proof against its signed root. */
 export declare function verifyInclusion(proof: InclusionProof): Promise<boolean>;
+/**
+ * Verify an RFC 6962 consistency proof. It shows the log at `second_size` is an
+ * append-only extension of the log at `first_size`, with nothing removed,
+ * reordered, or back-dated. Confirms the proof connects `first_root` to
+ * `second_root`, and that `second_root` matches the signed head. Check the head's
+ * signature separately with verifySignedTreeHead, and compare `first_root` against
+ * the earlier head you saved.
+ *
+ * The walk is the RFC 9162 §2.1.4.2 verification algorithm. The awaits fold sibling
+ * hashes in sequence, so they cannot run in parallel.
+ */
+export declare function verifyConsistency(proof: ConsistencyProof): Promise<boolean>;
 /** Verify the signed tree head's Ed25519 signature against the published key. */
 export declare function verifySignedTreeHead(sth: SignedTreeHead, publicKeyB64: string): Promise<boolean>;
 /**

package/dist/transparency.js

@@ -42,6 +42,71 @@ export async function verifyInclusion(proof) {
         return false;
     }
 }
+const isPowerOfTwo = (n) => (n & (n - 1)) === 0;
+/**
+ * Verify an RFC 6962 consistency proof. It shows the log at `second_size` is an
+ * append-only extension of the log at `first_size`, with nothing removed,
+ * reordered, or back-dated. Confirms the proof connects `first_root` to
+ * `second_root`, and that `second_root` matches the signed head. Check the head's
+ * signature separately with verifySignedTreeHead, and compare `first_root` against
+ * the earlier head you saved.
+ *
+ * The walk is the RFC 9162 §2.1.4.2 verification algorithm. The awaits fold sibling
+ * hashes in sequence, so they cannot run in parallel.
+ */
+/* eslint-disable no-await-in-loop */
+export async function verifyConsistency(proof) {
+    try {
+        const first = proof.first_size;
+        const second = proof.second_size;
+        if (bytesToHex(hexToBytes(proof.second_root)) !== proof.sth.root_hash)
+            return false;
+        if (first < 0 || first > second)
+            return false;
+        if (first === second)
+            return proof.proof.length === 0 && proof.first_root === proof.second_root;
+        if (first === 0)
+            return proof.proof.length === 0;
+        const nodes = proof.proof.map(hexToBytes);
+        // A power-of-two prefix has no left-hand sibling in the path, so its own root is
+        // the seed the walk starts from.
+        if (isPowerOfTwo(first))
+            nodes.unshift(hexToBytes(proof.first_root));
+        if (nodes.length === 0)
+            return false;
+        let fn = first - 1;
+        let sn = second - 1;
+        while (fn & 1) {
+            fn >>= 1;
+            sn >>= 1;
+        }
+        let fr = nodes[0];
+        let sr = nodes[0];
+        for (let i = 1; i < nodes.length; i += 1) {
+            const c = nodes[i];
+            if (sn === 0)
+                return false;
+            if (fn & 1 || fn === sn) {
+                fr = await nodeHash(c, fr);
+                sr = await nodeHash(c, sr);
+                while ((fn & 1) === 0 && fn !== 0) {
+                    fn >>= 1;
+                    sn >>= 1;
+                }
+            }
+            else {
+                sr = await nodeHash(sr, c);
+            }
+            fn >>= 1;
+            sn >>= 1;
+        }
+        return sn === 0 && bytesToHex(fr) === proof.first_root && bytesToHex(sr) === proof.second_root;
+    }
+    catch {
+        return false;
+    }
+}
+/* eslint-enable no-await-in-loop */
 /** Verify the signed tree head's Ed25519 signature against the published key. */
 export async function verifySignedTreeHead(sth, publicKeyB64) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postcept/receipt",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Reference implementation for verifying Postcept Receipts and VCR-audit badges, independently and in any environment.",
   "license": "MIT",
   "author": "Postcept",

package/schema/receipt.schema.json

@@ -17,7 +17,7 @@
     "signature"
   ],
   "properties": {
-    "id": { "type": "string", "description": "Receipt id, e.g. pcpt_rcpt_…" },
+    "id": { "type": "string", "description": "Receipt id, e.g. pcpt_rcpt_..." },
     "org_id": {
       "type": ["string", "null"],
       "description": "The organization the receipt belongs to (signed in v2)."
@@ -58,7 +58,7 @@
       "enum": ["1", "2"],
       "description": "Signing-body version. Absent is treated as \"1\"."
     },
-    "signing_key_id": { "type": "string", "description": "Key fingerprint, e.g. ed25519:…" },
+    "signing_key_id": { "type": "string", "description": "Key fingerprint, e.g. ed25519:..." },
     "signature": {
       "type": "string",
       "description": "Base64 Ed25519 signature over the canonical signing body for this version."