@pinionengineering/prover-client 0.1.0

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire format types for the pinion-prover service.
+ *
+ * All byte fields (G1/G2 curve points, scalars, seeds) are transmitted as
+ * standard base64 strings inside JSON objects.  The Go service uses encoding/json
+ * which encodes []byte as base64 automatically.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/verify.d.ts

@@ -0,0 +1,67 @@
+/**
+ * SW-Pub proof verification.
+ *
+ * Implements the public-key verification equation from §3.3 of
+ * Shacham & Waters, "Compact Proofs of Retrievability", ASIACRYPT 2008:
+ *
+ *   e(σ, G₂) == e(Σₜ νₜ·H(λ‖idᵢₜ) + Σⱼ μⱼ·uⱼ, v)
+ *
+ * where:
+ *   σ       proof accumulator G1 point  (from server)
+ *   G₂      generator of G2
+ *   νₜ, iₜ  blinding coefficients and block indices (re-derived from seed)
+ *   H(λ‖id) SHA-256(λ‖id) mod q · G₁    (ROM hash-to-G1)
+ *   μⱼ      per-sector Z_q scalars       (from server)
+ *   uⱼ      public key G1 elements       (from client_setup)
+ *   v       V = α·G₂, public key G2 point (from client_setup)
+ *
+ * Correctness: any honest server response satisfies this equation because:
+ *   σ = Σₜ νₜ·σᵢₜ  and  σᵢ = α·(H(λ‖idᵢ) + Σⱼ fᵢⱼ·uⱼ)
+ * Substituting and using bilinearity of e gives the identity.
+ *
+ * Security: under the computational Diffie-Hellman assumption, a server
+ * cannot forge a passing response without holding the tagged blocks.
+ *
+ * Ports verifyPubCore() in storage-proofs/por/sw/pub.go.
+ */
+import type { WireClientSetup } from './types.js';
+export interface VerifyParams {
+    /**
+     * The parsed WireClientSetup from the client_setup blob.
+     * Obtain via parseClientSetup() or directly from ParsedSetup.clientSetup.
+     */
+    clientSetup: WireClientSetup;
+    /**
+     * Block IDs (CID.Bytes()) in TagList order, concatenated across all challenged
+     * roots in the same order as the roots array in the ProveRequest.
+     * These are the same byte slices stored in ParsedRoot.blockIds.
+     */
+    blockIds: Uint8Array[];
+    /**
+     * The challenge string that was sent to POST /prove.
+     * This is buildChallenge()'s return value: base64(JSON(WireChallenge)).
+     */
+    challenge: string;
+    /**
+     * Raw bytes from the POST /prove response body.
+     * Despite Content-Type: application/octet-stream, the body is JSON (WireProof).
+     */
+    proofBytes: Uint8Array;
+}
+/**
+ * Cryptographically verify a storage proof returned by pinion-prover.
+ *
+ * Returns true if and only if the pairing equation holds.  A false result means
+ * the server either does not hold the data or returned a malformed proof.
+ *
+ * This is what the website's StorageHealthContext should call instead of
+ * checking resp.ok alone — HTTP 200 only proves the server responded, not that
+ * it holds the data.
+ */
+export declare function verifyProof(params: VerifyParams): boolean;
+/**
+ * Decode a base64 client_setup blob into a WireClientSetup.
+ * The blob is base64(JSON(WireClientSetup)) — there are two layers of encoding.
+ */
+export declare function parseClientSetup(clientSetupBase64: string): WireClientSetup;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAcH,OAAO,KAAK,EAAE,eAAe,EAA4B,MAAM,YAAY,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,EAAE,eAAe,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAMzD;AAoDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,iBAAiB,EAAE,MAAM,GAAG,eAAe,CAE3E"}

package/dist/verify.js

@@ -0,0 +1,94 @@
+/**
+ * SW-Pub proof verification.
+ *
+ * Implements the public-key verification equation from §3.3 of
+ * Shacham & Waters, "Compact Proofs of Retrievability", ASIACRYPT 2008:
+ *
+ *   e(σ, G₂) == e(Σₜ νₜ·H(λ‖idᵢₜ) + Σⱼ μⱼ·uⱼ, v)
+ *
+ * where:
+ *   σ       proof accumulator G1 point  (from server)
+ *   G₂      generator of G2
+ *   νₜ, iₜ  blinding coefficients and block indices (re-derived from seed)
+ *   H(λ‖id) SHA-256(λ‖id) mod q · G₁    (ROM hash-to-G1)
+ *   μⱼ      per-sector Z_q scalars       (from server)
+ *   uⱼ      public key G1 elements       (from client_setup)
+ *   v       V = α·G₂, public key G2 point (from client_setup)
+ *
+ * Correctness: any honest server response satisfies this equation because:
+ *   σ = Σₜ νₜ·σᵢₜ  and  σᵢ = α·(H(λ‖idᵢ) + Σⱼ fᵢⱼ·uⱼ)
+ * Substituting and using bilinearity of e gives the identity.
+ *
+ * Security: under the computational Diffie-Hellman assumption, a server
+ * cannot forge a passing response without holding the tagged blocks.
+ *
+ * Ports verifyPubCore() in storage-proofs/por/sw/pub.go.
+ */
+import { atePairing, fp12Equal, g1Add, g1FromBytes, g1ScalarMult, g2FromBytes, bytesToBigInt, G2_BASE, } from './bn254.js';
+import { base64ToBytes, blockHashG1, deriveIndicesAndCoeffs } from './challenge.js';
+/**
+ * Cryptographically verify a storage proof returned by pinion-prover.
+ *
+ * Returns true if and only if the pairing equation holds.  A false result means
+ * the server either does not hold the data or returned a malformed proof.
+ *
+ * This is what the website's StorageHealthContext should call instead of
+ * checking resp.ok alone — HTTP 200 only proves the server responded, not that
+ * it holds the data.
+ */
+export function verifyProof(params) {
+    try {
+        return _verifyProof(params);
+    }
+    catch {
+        return false;
+    }
+}
+function _verifyProof(params) {
+    const { clientSetup, blockIds, challenge, proofBytes } = params;
+    // 1. Decode the challenge to recover the seed used for derivation.
+    const wireChal = JSON.parse(new TextDecoder().decode(base64ToBytes(challenge)));
+    const seed = base64ToBytes(wireChal.seed);
+    // 2. Re-derive indices and coefficients deterministically.
+    //    Both sides (browser + server) run this on the same (seed, ids) to agree
+    //    on which blocks were sampled without communicating the full index list.
+    const { indices, coeffs } = deriveIndicesAndCoeffs(seed, blockIds, wireChal.c);
+    // 3. Decode the proof (JSON despite the octet-stream content-type).
+    const wireProof = JSON.parse(new TextDecoder().decode(proofBytes));
+    const sigma = g1FromBytes(base64ToBytes(wireProof.sigma));
+    const mu = wireProof.mu.map((m) => bytesToBigInt(base64ToBytes(m)));
+    // 4. Decode the public key from client_setup.
+    const name = base64ToBytes(clientSetup.name);
+    const V = g2FromBytes(base64ToBytes(clientSetup.v));
+    const U = clientSetup.u.map((u) => g1FromBytes(base64ToBytes(u)));
+    // 5. Compute A = Σₜ νₜ·H(λ‖ids[iₜ]) + Σⱼ μⱼ·uⱼ  ∈ G₁
+    let A = null;
+    for (let t = 0; t < indices.length; t++) {
+        const idx = indices[t] ?? 0;
+        const nu = coeffs[t] ?? 0n;
+        const term = g1ScalarMult(blockHashG1(name, blockIds[idx] ?? new Uint8Array()), nu);
+        A = A === null ? term : g1Add(A, term);
+    }
+    for (let j = 0; j < U.length; j++) {
+        const uj = U[j];
+        const muj = mu[j];
+        if (uj === undefined || muj === undefined)
+            continue;
+        const term = g1ScalarMult(uj, muj);
+        A = A === null ? term : g1Add(A, term);
+    }
+    if (A === null)
+        return false;
+    // 6. Check e(σ, G₂) == e(A, v)
+    const lhs = atePairing(sigma, G2_BASE);
+    const rhs = atePairing(A, V);
+    return fp12Equal(lhs, rhs);
+}
+/**
+ * Decode a base64 client_setup blob into a WireClientSetup.
+ * The blob is base64(JSON(WireClientSetup)) — there are two layers of encoding.
+ */
+export function parseClientSetup(clientSetupBase64) {
+    return JSON.parse(new TextDecoder().decode(base64ToBytes(clientSetupBase64)));
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pinionengineering/prover-client",
+  "version": "0.1.0",
+  "description": "JavaScript/TypeScript client for the pinion-prover storage-proof service. Builds SW-Pub challenges and cryptographically verifies proofs using BN254 pairings.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "build:watch": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node test/verify.test.mjs",
+    "test:gen": "cd testdata/gen && go run . > ../vectors.json"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.4.0",
+    "@noble/hashes": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "pinion",
+    "ipfs",
+    "storage-proof",
+    "por",
+    "bn254",
+    "alt-bn128",
+    "shacham-waters"
+  ]
+}