@pinionengineering/prover-client 0.10.0 → 0.11.1

package/dist/types.d.ts

@@ -51,17 +51,28 @@ export interface ProveResponse {
 export interface ProveJobResponse {
     job_id: string;
 }
+/**
+ * Result of prove()'s submit call: the proof job has been created and
+ * queued. Echoes challenge/roots back so a caller building progress UI (or
+ * later calling waitForProve()) doesn't have to thread them through
+ * separately.
+ */
+export interface ProveSubmission {
+    jobId: string;
+    challenge: string;
+    roots: string[];
+}
 /**
  * Raw status response from GET /prove/:job_id. This endpoint is
- * unauthenticated, same as POST /prove — job_id is a fresh, unguessable
+ * unauthenticated, same as POST /prove. job_id is a fresh, unguessable
  * identifier (or, when the request carried a challenge_id, deterministic
  * from (key_id, challenge_id)), so possession of it is the only
  * authorization this route needs.
  *
  * `status` is one of "prove-queued" | "prove-running" | "prove-done" |
  * "prove-failed". `challenge_id` echoes the value from the original
- * request. `proof` is populated only once `status` is "prove-done" — the
- * same field ProveResponse used to return synchronously. `error` is
+ * request. `proof` is populated only once `status` is "prove-done" (the
+ * same field ProveResponse used to return synchronously). `error` is
  * populated only once `status` is "prove-failed".
  */
 export interface ProveJobStatusResponse {
@@ -75,7 +86,7 @@ export interface ProveJobStatusResponse {
  * is populated: block_ids for protocols addressed by real IPFS block CID
  * (Ateniese, Erway, BJO); block_count for protocols that virtualize each root
  * into uniform super-blocks (SW-Priv, SW-Pub). For the latter, no per-block
- * manifest is sent at all — challenge ids are `rootCID.Bytes() || BE64(localIndex)`
+ * manifest is sent at all. Challenge ids are `rootCID.Bytes() || BE64(localIndex)`
  * for localIndex in [0, block_count), constructible from `root` plus this one
  * integer. See superBlockId() in challenge.ts, an exact port of SuperBlockID()
  * in ipfs-storage-proofs/superblock.go.
@@ -97,7 +108,7 @@ export interface ParsedRoot {
      * Ids ready to feed directly to buildChallenge()/verifyProof(), in order.
      * For non-chunked protocols these are real per-block CID bytes; for chunked
      * protocols (see `chunked` below) these are synthesized super-block ids
-     * (superBlockId(rootBytes, i) for i in [0, block_count)) — opaque either way
+     * (superBlockId(rootBytes, i) for i in [0, block_count)), opaque either way
      * to buildChallenge()/verifyProof(), which only need byte-identity, not
      * meaning.
      */
@@ -106,7 +117,7 @@ export interface ParsedRoot {
      * True if `blockIds` are synthesized super-block ids (chunked protocol:
      * SW-Priv, SW-Pub) rather than real per-block CIDs. Callers that need to
      * re-derive or re-export ids (e.g. writing an external client-state file)
-     * must branch on this — synthesized ids are not valid CIDs and must be
+     * must branch on this: synthesized ids are not valid CIDs and must be
      * reconstructed from `root` + a block count, never decoded as one.
      */
     chunked: boolean;
@@ -122,7 +133,7 @@ export interface ChallengeKeyInfo {
     key_id: string;
     protocol: string;
     created_at: string;
-    /** Human-readable name, if one was set. Empty for unnamed keys — a UUID
+    /** Human-readable name, if one was set. Empty for unnamed keys (a UUID
      * alone isn't usable in a UI once an account has more than one or two
      * keys, so callers should fall back to something derived from
      * created_at/key_id for display rather than assume this is always set. */
@@ -143,10 +154,10 @@ export interface UpdateKeyLabelRequest {
     label: string;
 }
 /**
- * Result of createKey() — the key ID plus the decoded public key material.
+ * Result of createKey(): the key ID plus the decoded public key material.
  *
  * `publicKey` contains the G1/G2 points needed to verify proofs locally.
- * Unlike a symmetric secret, this is the *public* half of the key pair — the
+ * Unlike a symmetric secret, this is the *public* half of the key pair. The
  * private half (α) never leaves the server.  You can safely store publicKey
  * alongside keyId so that future audits can verify proofs without trusting the
  * server to return the same key material each time.
@@ -158,13 +169,13 @@ export interface CreateKeyResult {
 }
 /**
  * Raw tag response from POST /api/v1/tag. Exactly one of block_ids/block_count
- * is populated — see RawTaggedRoot's doc comment for which protocols use which.
+ * is populated. See RawTaggedRoot's doc comment for which protocols use which.
  *
  * For non-chunked protocols, `block_ids` is the ordered list of CID strings
  * for every block in the DAG; this same list is returned by getSetup() per
- * root and is what the client uses to select which blocks to challenge — the
+ * root and is what the client uses to select which blocks to challenge. The
  * server never picks them. For chunked protocols (SW-Priv, SW-Pub),
- * `block_count` is the super-block count instead — no manifest needed.
+ * `block_count` is the super-block count instead, no manifest needed.
  */
 export interface TagResponse {
     block_ids?: string[];
@@ -174,6 +185,16 @@ export interface TagResponse {
 export interface TagJobResponse {
     job_id: string;
 }
+/**
+ * Result of tag()'s submit call: the tag job has been created and queued.
+ * Echoes root/keyId back so a caller doesn't have to thread them through
+ * separately to waitForTag() or a progress indicator.
+ */
+export interface TagSubmission {
+    jobId: string;
+    root: string;
+    keyId: string;
+}
 /** How much of an in-flight tag job has completed. */
 export interface TagJobProgress {
     total_blocks: number;
@@ -185,7 +206,7 @@ export interface TagJobProgress {
  * `status` is one of the tagstate.Lifecycle string values from pinion-prover:
  * "tag-queued" | "tag-planning" | "tag-running" | "tag-merging" | "tag-done" |
  * "tag-failed". `block_ids`/`block_count` are populated only once `status` is
- * "tag-done" — the same fields TagResponse used to return synchronously.
+ * "tag-done" (the same fields TagResponse used to return synchronously).
  * `error` is populated only once `status` is "tag-failed".
  */
 export interface TagJobStatusResponse {
@@ -196,7 +217,7 @@ export interface TagJobStatusResponse {
     error?: string;
 }
 /**
- * One entry from GET /api/v1/tag — a summary of a tag job for listing,
+ * One entry from GET /api/v1/tag: a summary of a tag job for listing,
  * without the terminal block_ids/block_count/error payload
  * TagJobStatusResponse carries.
  */
@@ -220,15 +241,15 @@ export interface TagJobListResponse {
  * cryptographic failure from one that couldn't even be evaluated:
  *
  *   - { verified: false, reason: 'pairing-mismatch' } means the pairing
- *     equation was evaluated and did not hold — the server either does not
+ *     equation was evaluated and did not hold. The server either does not
  *     hold the data or returned a deliberately bad proof. This is the only
  *     case that should ever be reported to a user as evidence of possible
  *     data loss.
  *   - { verified: false, reason: 'malformed-input', cause } means the
- *     equation was never evaluated at all — proofBytes wasn't valid
+ *     equation was never evaluated at all. proofBytes wasn't valid
  *     WireProof JSON, a curve point failed to decode, etc. This is what an
  *     infra error looks like from here: a 5xx with an HTML body, a proxy
- *     timeout page, a truncated response — none of which say anything about
+ *     timeout page, a truncated response, none of which say anything about
  *     whether the server actually holds the data.
  *
  * verifyProof() collapses both false cases into a plain `false`, which is
@@ -249,7 +270,7 @@ export interface AuditResult {
     /** true only if the pairing check e(σ,G₂) == e(A,v) passed. */
     pass: boolean;
     /**
-     * The richer verification outcome pass was derived from — check this to
+     * The richer verification outcome pass was derived from. Check this to
      * distinguish a real cryptographic failure (reason: 'pairing-mismatch')
      * from one that couldn't be evaluated at all (reason: 'malformed-input').
      * Only the former should ever be reported to a user as evidence of
@@ -260,7 +281,7 @@ export interface AuditResult {
     blocksChecked: number;
     keyId: string;
     roots: string[];
-    /** base64(JSON(WireChallenge)) used for this round — same bytes POST /prove sent. Decode with decodeChallenge(). */
+    /** base64(JSON(WireChallenge)) used for this round, same bytes POST /prove sent. Decode with decodeChallenge(). */
     challenge: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinionengineering/prover-client",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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",
@@ -20,8 +20,8 @@
     "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"
+    "test": "npm run build && node test/verify.test.mjs && node test/client.test.mjs",
+    "test:gen": "cd ../testdata/gen && go run . > ../vectors.json"
   },
   "dependencies": {
     "@noble/curves": "^1.4.0",