@pinionengineering/prover-client 0.10.0 → 0.11.1

package/README.md

@@ -1,4 +1,4 @@
-# @pinion/prover-client
+# @pinionengineering/prover-client
 
 JavaScript / TypeScript client for **pinion-prover** storage-proof service.
 
@@ -9,22 +9,46 @@ Implements the SW-Pub challenger role:
 - Sends challenges to the prover and receives proofs
 - **Cryptographically verifies proofs** using BN254 Ate pairings
 
-Most IPFS pinning clients trust HTTP 200 as proof of storage — but a server
+Most IPFS pinning clients trust HTTP 200 as proof of storage, but a server
 can return 200 without actually holding your data.  This library closes that gap:
 the server must solve a cryptographic challenge that is **only solvable by a party
 who has the block data**, and you verify the answer with a BN254 pairing equation
 in your browser or Node.js process.
 
+Don't want to write JS? [The Go client in this same repo](../go#readme) documents a
+no-code path: export a key + roots file from the
+[dashboard](https://pinion.build), then run the same audit loop with the
+`testclient` CLI. `testclient import` followed by `testclient audit --all --loop`
+is the whole workflow, no account needed for the audit itself.
+
 ---
 
 ## Installation
 
 ```bash
-npm install @pinion/prover-client
+npm install @pinionengineering/prover-client
 ```
 
 Requires Node.js ≥ 18. Works in modern browsers with native `crypto.getRandomValues` and `atob`.
 
+### Upgrading from 0.10.x
+
+`tag()` and `prove()` are now **submit-only**: they return a job handle
+immediately (`{ jobId, ... }`) instead of blocking until the job finishes.
+Await the new `waitForTag(jobId, options?)` / `waitForProve(jobId, options?)`
+to wait for a terminal state, or poll `tagStatus(jobId)`/`proveStatus(jobId)`
+yourself. There is **no default deadline anymore**: the old hardcoded 60s
+(`prove`)/10min (`tag`) timeouts are gone, since a proof or tag job can
+legitimately take longer and the server was never designed to respect an
+arbitrary client-side ceiling. If you want the old ceiling back, it's a
+strict superset away: pass `signal: AbortSignal.timeout(ms)` to
+`waitForProve()`/`waitForTag()`/`audit()`.
+
+`audit(keyId, setup)` is unchanged in shape (still one call that submits,
+waits, and verifies) but now also accepts `pollIntervalMs`/`signal`/
+`onStatus` so you can build progress UI or cancel a long-running round; see
+its section below.
+
 ---
 
 ## How It Works
@@ -35,14 +59,17 @@ The protocol has two distinct phases:
 
 1. Call `createKey()`.  The server generates a BN254 key pair and stores the private
    scalar α.  You receive:
-   - `keyId` — identifier for this key on the server
-   - `publicKey` — the public half: `V = α·G₂` (G2 point) and `U[0..s-1]` (G1 points).
+   - `keyId`: identifier for this key on the server
+   - `publicKey`: the public half: `V = α·G₂` (G2 point) and `U[0..s-1]` (G1 points).
      These are the values needed to verify proofs; store them if you want to verify
      independently of the server later.
 
-2. Call `tag(cid, keyId)` for each pinned CID.  The server walks the IPFS DAG,
-   computes per-block authentication tags, and stores them.  It returns the **block IDs**
-   for that root — the `CID.Bytes()` of every block in the DAG, in TagList order.
+2. Call `tag(cid, keyId)` for each pinned CID, then `waitForTag(jobId)`.
+   Tagging is asynchronous. `tag()` submits the job and returns a job
+   handle immediately; the server walks the IPFS DAG, computes per-block
+   authentication tags, and stores them in the background. `waitForTag()`
+   polls until it's done and returns the **block IDs** for that root: the
+   `CID.Bytes()` of every block in the DAG, in TagList order.
 
 3. Call `getSetup(keyId)` to fetch the full setup document.  The response contains:
    - The public key (same as returned by `createKey()`)
@@ -57,7 +84,7 @@ Each audit round is independent and stateless with respect to prior rounds:
 
 1. Generate a random 32-byte seed and select `n` blocks to challenge.  Both client
    and server independently apply HMAC-SHA256 to the seed to rank all block IDs and
-   select the same `n` blocks in the same order — no extra communication needed.
+   select the same `n` blocks in the same order: no extra communication needed.
    Use `buildChallenge(n, total)` for an exact block count, or `audit()` for a
    percentage-based shorthand.
 
@@ -76,7 +103,7 @@ proof-of-storage evidence collected over time.
 ## Quick Start
 
 ```typescript
-import { PinionProverClient } from '@pinion/prover-client';
+import { PinionProverClient } from '@pinionengineering/prover-client';
 
 const client = new PinionProverClient('https://example.com/prover', {
   getToken: async () => myAuthService.getToken(),
@@ -84,11 +111,13 @@ const client = new PinionProverClient('https://example.com/prover', {
 
 // ── Setup phase ────────────────────────────────────────────────────────────
 
-// Create a key — returns the key ID and the public half of the key pair.
+// Create a key: returns the key ID and the public half of the key pair.
 const { keyId, publicKey } = await client.createKey();
 
-// Tag a pinned CID — the server walks the DAG and stores per-block auth tags.
-await client.tag('bafybeigdyrzt...', keyId);
+// Tag a pinned CID: submits the job, then waits (no default deadline) for
+// the server to walk the DAG and store per-block auth tags.
+const tagJob = await client.tag('bafybeigdyrzt...', keyId);
+await client.waitForTag(tagJob.jobId);
 
 // Fetch the setup document: public key + block ID lists for all tagged roots.
 const setup = await client.getSetup(keyId);
@@ -105,7 +134,7 @@ console.log(result.pass); // true = server cryptographically proved it holds you
 ## Examples
 
 `examples/verify.mjs` is a ready-to-run Node.js script covering the full
-flow — find-or-create a key, tag new CIDs, run one audit round:
+flow: find-or-create a key, tag new CIDs, run one audit round:
 
 ```sh
 PROVER_URL=https://hydrogen.pinion.build/prover \
@@ -159,13 +188,13 @@ The private scalar α never leaves the server.  `publicKey` is the WireClientSet
 blob decoded from base64; you can store it and pass it directly to `verifyProof()`
 without ever calling `getSetup()` again.
 
-A single key covers many CIDs — you do not need a new key per file.
+A single key covers many CIDs: you do not need a new key per file.
 
 #### `client.listKeys()` → `ChallengeKeyInfo[]`
 
 Returns all keys for the authenticated user.  Each entry includes:
-- `blocks_audited` — cumulative blocks challenged across all audit rounds for this key
-- `audit_count` — number of audit rounds completed
+- `blocks_audited`: cumulative blocks challenged across all audit rounds for this key
+- `audit_count`: number of audit rounds completed
 
 These are the long-running metrics that show how much proof-of-storage evidence
 has been accumulated over time.
@@ -178,47 +207,67 @@ Deletes a key and all associated tags.
 
 ### Setup Phase
 
-#### `client.tag(root, keyId)` → `TagResponse`
+#### `client.tag(root, keyId)` → `TagSubmission`
 
 ```typescript
-const { block_ids, block_count } = await client.tag(cid, keyId);
+const { jobId } = await client.tag(cid, keyId);
+```
+
+Instructs the server to walk the IPFS DAG for `root`, compute per-block
+authentication tags, and store them under `keyId`. The CID must be in the
+`"pinned"` lifecycle state for the authenticated account. Submits the job
+and returns immediately. This does not wait for tagging to finish.
+
+#### `client.waitForTag(jobId, options?)` → `TagResponse`
+
+```typescript
+const { block_ids, block_count } = await client.waitForTag(jobId, {
+  onProgress: (progress, status) => console.log(status, progress),
+});
 // Exactly one is populated, depending on the key's protocol:
-// block_ids:   string[] — base64(CID.Bytes()) for every block, non-chunked
+// block_ids:   string[]: base64(CID.Bytes()) for every block, non-chunked
 //              protocols only (Ateniese, Erway, BJO), in TagList order
-// block_count: number   — super-block count, chunked protocols only
-//              (SW-Priv, SW-Pub) — no per-block manifest is sent at all
+// block_count: number  : super-block count, chunked protocols only
+//              (SW-Priv, SW-Pub): no per-block manifest is sent at all
 ```
 
-Instructs the server to walk the IPFS DAG for `root`, compute per-block
-authentication tags, and store them under `keyId`.  The CID must be in the
-`"pinned"` lifecycle state for the authenticated account.
+Polls `tagStatus(jobId)` until the job reaches a terminal state. **No
+default deadline**: waits as long as tagging takes unless `options.signal`
+is given and fires first, in which case it throws `TagTimeoutError`. Throws
+`TagFailedError` if the job reaches `"tag-failed"`.
 
 For non-chunked protocols, `block_ids` is the full list of blocks for this
 root in the order both client and server will use when ranking against a
-challenge seed.  For chunked protocols, `block_count` is all the client needs
-— challenge ids are synthesized locally via `superBlockId(rootBytes, i)` for
+challenge seed.  For chunked protocols, `block_count` is all the client needs:
+challenge ids are synthesized locally via `superBlockId(rootBytes, i)` for
 `i` in `[0, block_count)`.  Call `getSetup()` after tagging to get the
 combined list/count across all roots.
 
+| `WaitForTagOptions` field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `pollIntervalMs` | `number` | `1000` | Milliseconds between status polls. |
+| `signal` | `AbortSignal` | none | Optional cancellation, no default deadline. |
+| `onProgress` | `(progress, status) => void` | none | Called after every poll with `{total_blocks, completed_blocks}` and the raw status string. |
+
 #### `client.getSetup(keyId)` → `ParsedSetup`
 
 Fetches the complete setup document for a key.
 
 ```typescript
 const setup = await client.getSetup(keyId);
-// setup.clientSetup    WireClientSetup — public key material
+// setup.clientSetup    WireClientSetup: public key material
 // setup.roots          [{ root: string, blockIds: Uint8Array[], chunked: boolean }, ...]
 // setup.totalBlocks    total block count across all roots
 ```
 
 `blockIds` is always ready to pass to `buildChallenge()`/`verifyProof()`
 regardless of protocol.  `chunked` tells you whether those ids are real
-per-block CIDs (`false`) or synthesized super-block ids (`true`) — only
+per-block CIDs (`false`) or synthesized super-block ids (`true`): only
 relevant if you need to re-derive or re-export ids yourself; synthesized ids
 are not valid CIDs and must never be round-tripped through `CID.decode()`.
 
 Call this once after tagging.  Re-call whenever you add or remove roots.
-Pass the returned `ParsedSetup` directly to `audit()` — it does not fetch
+Pass the returned `ParsedSetup` directly to `audit()`: it does not fetch
 the setup for you.
 
 #### `client.deregister(keyId, root)`
@@ -268,13 +317,17 @@ const result = await client.audit(keyId, setup, {
 |-------|------|---------|-------------|
 | `roots` | `string[]` | all roots | Subset of registered CIDs to challenge. |
 | `challengePct` | `number` | `1` | Percentage of blocks to sample (0–100). |
+| `pollIntervalMs` | `number` | `500` | Milliseconds between status polls during the wait phase. |
+| `signal` | `AbortSignal` | none | Optional cancellation, no default deadline, waits as long as the proof takes unless this fires. Pass `AbortSignal.timeout(ms)` for a fixed ceiling. |
+| `onStatus` | `(status: string) => void` | none | Called after every poll with the raw status string; proving has no per-block progress signal, unlike tagging. |
 
 Throws `PinNotActiveError` if any root is no longer in the `"pinned"` state.
-Throws `ProverError` on HTTP errors from the server.
+Throws `ProverError` on HTTP errors from the server. Throws
+`ProveTimeoutError` if `options.signal` fires before the proof completes.
 
 ---
 
-#### Low-level: `buildChallenge` + `prove` + `verifyProof`
+#### Low-level: `buildChallenge` + `prove` + `waitForProve` + `verifyProof`
 
 Use these when you need an exact block count or want full control over the
 challenge parameters.
@@ -282,7 +335,7 @@ challenge parameters.
 ##### `buildChallenge(n, totalBlocks)` → `string`
 
 ```typescript
-import { buildChallenge } from '@pinion/prover-client';
+import { buildChallenge } from '@pinionengineering/prover-client';
 
 const challenge = buildChallenge(10, setup.totalBlocks);
 // Returns base64(JSON({ suite_id: 1, seed: <32 random bytes>, c: 10, n: totalBlocks }))
@@ -292,18 +345,34 @@ Generates a random 32-byte seed and encodes a WireChallenge requesting `n` block
 out of `totalBlocks`.  Both client and server independently apply HMAC-SHA256 to
 the seed to rank all block IDs and arrive at the same `n` blocks in the same order.
 
-##### `client.prove(keyId, roots, challenge)` → `Uint8Array`
+##### `client.prove(keyId, roots, challenge)` → `ProveSubmission`
+
+```typescript
+const { jobId } = await client.prove(keyId, roots, challenge);
+```
+
+Posts the challenge to `POST /prove` and returns immediately with a job
+handle. This does not wait for the proof to be computed.
+
+##### `client.waitForProve(jobId, options?)` → `Uint8Array`
 
 ```typescript
-const proofBytes = await client.prove(keyId, roots, challenge);
+const proofBytes = await client.waitForProve(jobId, {
+  challenge, roots, // optional, but lets a thrown error carry enough to retry
+  signal: AbortSignal.timeout(60_000), // optional, no default deadline otherwise
+});
 ```
 
-Posts the challenge to `POST /prove` and returns the raw proof bytes.
+Polls `proveStatus(jobId)` until the job reaches a terminal state and
+returns the raw proof bytes. **No default deadline**: waits as long as the
+proof takes unless `options.signal` fires first, in which case it throws
+`ProveTimeoutError`. Throws `ProveFailedError` if the job reaches
+`"prove-failed"`.
 
 ##### `verifyProof(params)` → `boolean`
 
 ```typescript
-import { verifyProof } from '@pinion/prover-client';
+import { verifyProof } from '@pinionengineering/prover-client';
 
 const pass = verifyProof({
   clientSetup: setup.clientSetup,  // or publicKey from createKey()
@@ -314,26 +383,28 @@ const pass = verifyProof({
 ```
 
 Runs the BN254 pairing check locally.  Returns `true` only if
-`e(σ,G₂) == e(A,V)`.  Safe to call without a client instance — useful for
+`e(σ,G₂) == e(A,V)`.  Safe to call without a client instance: useful for
 offline verification or integration with existing infrastructure.
 
 ##### Full low-level example
 
 ```typescript
-import { PinionProverClient, buildChallenge, verifyProof } from '@pinion/prover-client';
+import { PinionProverClient, buildChallenge, verifyProof } from '@pinionengineering/prover-client';
 
 const client = new PinionProverClient(proverUrl, { getToken });
 
 // Setup phase
 const { keyId } = await client.createKey();
-await client.tag(cid, keyId);
+const tagJob = await client.tag(cid, keyId);
+await client.waitForTag(tagJob.jobId);
 const setup = await client.getSetup(keyId);
 
-// Audit phase — exact block count
+// Audit phase: exact block count
 const root     = setup.roots[0]!;
 const blockIds = root.blockIds;
-const challenge  = buildChallenge(10, blockIds.length);
-const proofBytes = await client.prove(keyId, [root.root], challenge);
+const challenge = buildChallenge(10, blockIds.length);
+const submission = await client.prove(keyId, [root.root], challenge);
+const proofBytes = await client.waitForProve(submission.jobId, { challenge, roots: [root.root] });
 
 const pass = verifyProof({
   clientSetup: setup.clientSetup,
@@ -351,7 +422,7 @@ You can verify a proof with no HTTP client at all, as long as you have the
 public key and block IDs from a prior setup call:
 
 ```typescript
-import { buildChallenge, verifyProof, parseClientSetup } from '@pinion/prover-client';
+import { buildChallenge, verifyProof, parseClientSetup } from '@pinionengineering/prover-client';
 
 const clientSetup = parseClientSetup(storedClientSetupBase64);
 
@@ -429,7 +500,7 @@ base64( JSON({ protocol, suite_id, s, l, name, v, u }) )
 | `suite_id` | `uint8` | `1` |
 | `s` | `int` | Number of sectors per block |
 | `l` | `int` | Challenge size parameter (from the SW-Pub scheme) |
-| `name` | `base64(16 bytes)` | File name λ — random, unique per key, bound into every block tag |
+| `name` | `base64(16 bytes)` | File name λ: random, unique per key, bound into every block tag |
 | `v` | `base64(128 bytes)` | Public key V = α·G₂ (G2 point, EIP-197 format) |
 | `u` | `base64(64 bytes)[]` | Public key U[0..s-1] (G1 points) |
 
@@ -460,13 +531,13 @@ e(σ, G₂) == e(Σₜ νₜ·H(λ‖idᵢₜ) + Σⱼ μⱼ·uⱼ, V)
 
 where:
 
-- `σ` — proof accumulator G1 point (from server)
-- `G₂` — G2 generator
-- `νₜ, iₜ` — blinding coefficients and block indices (re-derived from seed)
-- `H(λ‖id)` — RFC 9380 SVDW hash-to-G1 with DST `"sw-pub-v1-BN254G1_XMD:SHA-256_SVDW_RO_"`
-- `μⱼ` — per-sector Zr scalars (from server)
-- `uⱼ` — public key G1 elements (from client_setup)
-- `V` — public key `V = α·G₂` (from client_setup)
+- `σ`: proof accumulator G1 point (from server)
+- `G₂`: G2 generator
+- `νₜ, iₜ`: blinding coefficients and block indices (re-derived from seed)
+- `H(λ‖id)`: RFC 9380 SVDW hash-to-G1 with DST `"sw-pub-v1-BN254G1_XMD:SHA-256_SVDW_RO_"`
+- `μⱼ`: per-sector Zr scalars (from server)
+- `uⱼ`: public key G1 elements (from client_setup)
+- `V`: public key `V = α·G₂` (from client_setup)
 
 ### Hash-to-G1
 
@@ -481,7 +552,7 @@ points that are indistinguishable from uniform random G1 elements.
 
 The DST `"sw-pub-v1-BN254G1_XMD:SHA-256_SVDW_RO_"` is fixed for all keys and matches
 the value in `storage-proofs/por/sw/pub.go`. **Changing this DST invalidates all
-existing tags** — both sides derive H independently so they must agree.
+existing tags**: both sides derive H independently so they must agree.
 
 ### Challenge Derivation (`DeriveChallenge`)
 
@@ -514,12 +585,18 @@ npm run test:gen
 npm test
 ```
 
-The test suite verifies:
+`test/verify.test.mjs` verifies the cross-language crypto correctness:
 1. Valid proof accepted
 2. Tampered sigma rejected
 3. Wrong block IDs rejected
 4. Wrong public key rejected
 
+`test/client.test.mjs` covers `PinionProverClient`'s submit/wait polling
+model against a hand-rolled `fetch` stub: `prove()`/`tag()` submit without
+polling, `waitForProve()`/`waitForTag()` poll to completion with no
+implicit deadline, an `AbortSignal` cancels promptly, and `audit()`'s
+`onStatus`/`pollIntervalMs` options reach the underlying poll.
+
 ---
 
 ## Implementation Notes