@reclaimprotocol/js-sdk 5.3.0-dev.1 → 5.3.0

package/README.md

@@ -701,6 +701,52 @@ const { isVerified } = await verifyProof(proof, {
 });
 ```
 
+### Replay Protection
+
+Proofs are submitted by the user, so the server must not trust any field on the proof in isolation. `verifyProof` (and `verifyTeeAttestation`) cryptographically bind a proof to a specific session, but **the SDK is stateless** — it cannot tell whether the same valid proof has already been verified. Preventing replay is the caller's responsibility.
+
+**What the SDK guarantees**
+
+The `attestationNonce` baked into the proof context is computed as `keccak256("RECLAIM_TEE_NONCE_V1" : applicationId : sessionId : timestamp : appSecret)`. When you call `verifyProof` with `teeAttestation: { appSecret }`, the SDK:
+
+- Recomputes the nonce from `(applicationId, sessionId, timestamp)` in the proof context using **your** `appSecret` and asserts it matches — only the holder of the app secret can mint a valid nonce, so the user cannot rebind a proof to a different `sessionId` or `applicationId`.
+- Confirms the recomputed nonce appears in the TEE attestation token's `eat_nonce` (signed by Google's Confidential Computing OIDC issuer), so the TEE-signed binding cannot be forged either.
+- Asserts the `applicationId` in the nonce data matches the address derived from `appSecret`, and that `sessionId` in the nonce data agrees with `reclaimSessionId` in `claimData.context` and `proxySessionId`/`sessionId` in `claimData.parameters`.
+- Asserts `claimData.timestampS` is within 10 minutes of the nonce timestamp.
+
+In short: the user cannot mutate `sessionId`, `applicationId`, or `timestamp` on a proof without invalidating it. They *can*, however, resubmit the same valid proof.
+
+**What you must do on your server**
+
+1. **Use a session you initiated.** Call `ReclaimProofRequest.init(...)` and `getSessionId()` server-side (or record the `sessionId` returned to your callback). When verifying, reject any proof whose `sessionId` you did not issue.
+2. **Dedupe by `sessionId`.** Persist accepted `sessionId`s (e.g., a unique index in your DB or a TTL cache) and reject a `sessionId` that has already been verified. This is the primary replay defense.
+3. **Require `teeAttestation`** in `verifyProof` for any flow where replay or tampering matters — without it, the cryptographic binding to `appSecret` is not checked.
+4. **Enforce a freshness window.** Reject proofs whose `claimData.timestampS` is older than your business policy allows (the SDK only enforces a 10-minute skew between the nonce timestamp and claim timestamp, not absolute freshness).
+
+```javascript
+// Pseudocode for a server-side verification handler
+const expectedSessionId = await loadSessionForUser(req.user); // session you created
+const sessionId = JSON.parse(proof.claimData.context).reclaimSessionId;
+
+if (sessionId !== expectedSessionId) {
+  throw new Error("session mismatch");
+}
+if (await db.consumedSessions.has(sessionId)) {
+  throw new Error("proof already used"); // replay
+}
+
+const { isVerified, error } = await verifyProof(proof, {
+  ...providerVersion,
+  teeAttestation: { appSecret: process.env.APP_SECRET },
+});
+if (!isVerified) throw error;
+
+await db.consumedSessions.add(sessionId); // mark consumed atomically
+```
+
+> [!WARNING]
+> Without server-side session tracking and dedup, a malicious user can submit the same valid proof repeatedly. The cryptographic checks in `verifyProof` are necessary but not sufficient for replay protection.
+
 ## TEE Attestation Verification
 
 The SDK supports verifying TEE (Trusted Execution Environment) attestations included in proofs. The attestation flow verifies the Google Confidential Computing OIDC token returned by Popcorn's GCP attestor and checks that it is bound to the proof nonce, application identity, and image digests.

package/dist/index.d.ts

@@ -772,6 +772,13 @@ type ProviderHashRequirementsResponse = {
  * * `getProviderHashRequirementsFromSpec()` - To get the expected proof hash requirements from a provider spec.
  * * All 3 functions above are alternatives of each other and result from these functions can be directly used as `config` parameter in this function for proof validation.
  *
+ * Replay protection: this function is stateless. It verifies that a proof is cryptographically
+ * bound to a specific `sessionId`/`applicationId` (via the `appSecret`-keyed attestation nonce
+ * when `teeAttestation` is provided) but does not track which proofs have already been
+ * verified. Callers must (a) verify the proof's `sessionId` matches a session they initiated
+ * and (b) persist accepted `sessionId`s and reject duplicates. See the README's
+ * "Replay Protection" section for details.
+ *
  * @param proofOrProofs - A single proof object or an array of proof objects to be verified.
  * @param config - Verification configuration that specifies required hashes, allowed extra hashes, or disables content validation. Optionally includes `teeAttestation` to require TEE attestation verification.
  * @returns Verification result with `isVerified`, `isTeeAttestationVerified` (always boolean), extracted `data` from each proof, and optional `error` on failure. The application ID is derived from `appSecret` automatically.
@@ -1509,6 +1516,10 @@ type TeeVerificationResult = {
  * was generated for your application.
  * Returns a result object with `isVerified` and an optional `error` message.
  *
+ * This check is stateless and does not protect against replay of a previously
+ * valid proof. Callers must enforce session matching and dedup `sessionId` on
+ * their server. See the README's "Replay Protection" section.
+ *
  * @param proof - The proof containing TEE attestation data
  * @param appSecret - Your application secret (Ethereum private key). Used to
  *   derive the application ID and recompute the attestation nonce.

package/dist/index.js

@@ -84,7 +84,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@reclaimprotocol/js-sdk",
-      version: "5.3.0-dev.1",
+      version: "5.3.0",
       description: "Designed to request proofs from the Reclaim protocol and manage the flow of claims and witness interactions.",
       main: "dist/index.js",
       types: "dist/index.d.ts",