@reclaimprotocol/js-sdk 5.2.0 → 5.3.0

package/README.md

@@ -701,20 +701,68 @@ 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.
 
-### Enabling TEE Attestation
+### Requesting TEE Attestation
 
-To request TEE attestation during proof generation, enable it during initialization:
+TEE attestation is requested by default during proof generation:
 
 ```javascript
-const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
-  acceptTeeAttestation: true,
-});
+const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID);
 ```
 
+The request includes the SDK's attestation version so the attestor can continue serving older SDK clients when newer attestation formats are introduced.
+
+To opt out, set `acceptTeeAttestation: false` during initialization.
+
 ### Verifying TEE Attestation via `verifyProof`
 
 Provide a `teeAttestation` config to require and verify TEE attestation. The application ID is derived automatically from `appSecret`. If TEE data is missing or invalid, verification will fail with a `TeeVerificationError`.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+declare const SUPPORTED_TEE_ATTESTATION_VERSIONS: readonly ["v2", "v3"];
+type TeeAttestationVersion = typeof SUPPORTED_TEE_ATTESTATION_VERSIONS[number];
 interface TeeAttestation {
-    proof_version: string;
+    proof_version: TeeAttestationVersion;
     tee_provider: string;
     tee_technology: string;
     nonce: string;
@@ -70,6 +72,7 @@ interface Context {
         applicationId: string;
         sessionId: string;
         timestamp: string;
+        attestationVersion?: TeeAttestationVersion;
     };
 }
 interface Beacon {
@@ -503,7 +506,9 @@ type ProofRequestOptions = {
      */
     metadata?: Record<string, string>;
     /**
-     * If true, generates a TEE attestation nonce during session initialization and expects a TEE attestation in the proof.
+     * Generates a TEE attestation nonce during session initialization and expects a TEE attestation in the proof.
+     *
+     * @default true
      */
     acceptTeeAttestation?: boolean;
 };
@@ -688,6 +693,8 @@ type TemplateData = {
     canAutoSubmit?: boolean;
     metadata?: Record<string, string>;
     preferredLocale?: ProofRequestOptions['preferredLocale'];
+    acceptTeeAttestation?: boolean;
+    teeAttestationVersion?: TeeAttestationVersion;
 };
 type TrustedData = {
     context: Record<string, unknown>;
@@ -765,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.
@@ -1502,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.
@@ -1558,4 +1576,4 @@ declare function isDesktopDevice(): boolean;
  */
 declare function clearDeviceCache(): void;
 
-export { type Beacon, type BeaconState, type BodySniff, ClaimCreationType, type ClaimID, type ClaimInfo, type CompleteClaimData, type Context, type CreateVerificationRequest, DeviceType, type EmbeddedFlowHandle, type ExtensionMessage, type FlowHandle, type HashRequirement, type HashableHttpProviderClaimParams, type HttpFormEntry, type HttpProviderClaimParams, type HttpRedirectionMethod, type HttpRedirectionOptions, type InitSessionResponse, type InjectedRequestSpec, type InterceptorRequestSpec, type ModalOptions, type OnError, type OnSuccess, type Proof, type ProofPropertiesJSON, type ProofRequestOptions, type ProviderClaimData, type ProviderConfigResponse, type ProviderHashRequirementSpec, type ProviderHashRequirementsConfig, type ProviderHashRequirementsResponse, type ProviderVersionConfig, type ProviderVersionInfo, RECLAIM_EXTENSION_ACTIONS, type ReclaimFlowInitOptions, type ReclaimFlowLaunchOptions, ReclaimProofRequest, type ReclaimProviderConfig, type ReclaimProviderConfigWithRequestSpec, type RequestSpec, type ResponseMatchSpec, type ResponseRedactionSpec, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TeeAttestation, type TeeAttestationConfig, TeeVerificationError, type TeeVerificationResult, type TemplateData, type TrustedData, type UpdateSessionResponse, type ValidationConfig, type ValidationConfigWithDisabledValidation, type ValidationConfigWithHash, type ValidationConfigWithProviderInformation, type VerificationConfig, type VerifyProofResult, type VerifyProofResultFailure, type VerifyProofResultSuccess, type WitnessData, assertValidProofsByHash, assertValidateProof, assertVerifiedProof, clearDeviceCache, createLinkWithTemplateData, createSignDataForClaim, fetchProviderConfigs, fetchProviderHashRequirementsBy, fetchStatusUrl, generateSpecsFromRequestSpecTemplate, getAttestors, getDeviceType, getHttpProviderClaimParamsFromProof, getIdentifierFromClaimInfo, getMobileDeviceType, getProviderHashRequirementSpecFromProviderConfig, getProviderHashRequirementsFromSpec, getProviderParamsAsCanonicalizedString, getShortenedUrl, hashProofClaimParams, hashRequestSpec, initSession, isDesktopDevice, isHttpProviderClaimParams, isMobileDevice, recoverSignersOfSignedClaim, runTeeVerification, takePairsWhereValueIsArray, takeTemplateParametersFromProofs, transformForOnchain, updateSession, verifyProof, verifyTeeAttestation };
+export { type Beacon, type BeaconState, type BodySniff, ClaimCreationType, type ClaimID, type ClaimInfo, type CompleteClaimData, type Context, type CreateVerificationRequest, DeviceType, type EmbeddedFlowHandle, type ExtensionMessage, type FlowHandle, type HashRequirement, type HashableHttpProviderClaimParams, type HttpFormEntry, type HttpProviderClaimParams, type HttpRedirectionMethod, type HttpRedirectionOptions, type InitSessionResponse, type InjectedRequestSpec, type InterceptorRequestSpec, type ModalOptions, type OnError, type OnSuccess, type Proof, type ProofPropertiesJSON, type ProofRequestOptions, type ProviderClaimData, type ProviderConfigResponse, type ProviderHashRequirementSpec, type ProviderHashRequirementsConfig, type ProviderHashRequirementsResponse, type ProviderVersionConfig, type ProviderVersionInfo, RECLAIM_EXTENSION_ACTIONS, type ReclaimFlowInitOptions, type ReclaimFlowLaunchOptions, ReclaimProofRequest, type ReclaimProviderConfig, type ReclaimProviderConfigWithRequestSpec, type RequestSpec, type ResponseMatchSpec, type ResponseRedactionSpec, SUPPORTED_TEE_ATTESTATION_VERSIONS, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TeeAttestation, type TeeAttestationConfig, type TeeAttestationVersion, TeeVerificationError, type TeeVerificationResult, type TemplateData, type TrustedData, type UpdateSessionResponse, type ValidationConfig, type ValidationConfigWithDisabledValidation, type ValidationConfigWithHash, type ValidationConfigWithProviderInformation, type VerificationConfig, type VerifyProofResult, type VerifyProofResultFailure, type VerifyProofResultSuccess, type WitnessData, assertValidProofsByHash, assertValidateProof, assertVerifiedProof, clearDeviceCache, createLinkWithTemplateData, createSignDataForClaim, fetchProviderConfigs, fetchProviderHashRequirementsBy, fetchStatusUrl, generateSpecsFromRequestSpecTemplate, getAttestors, getDeviceType, getHttpProviderClaimParamsFromProof, getIdentifierFromClaimInfo, getMobileDeviceType, getProviderHashRequirementSpecFromProviderConfig, getProviderHashRequirementsFromSpec, getProviderParamsAsCanonicalizedString, getShortenedUrl, hashProofClaimParams, hashRequestSpec, initSession, isDesktopDevice, isHttpProviderClaimParams, isMobileDevice, recoverSignersOfSignedClaim, runTeeVerification, takePairsWhereValueIsArray, takeTemplateParametersFromProofs, transformForOnchain, updateSession, verifyProof, verifyTeeAttestation };

package/dist/index.js

@@ -84,7 +84,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@reclaimprotocol/js-sdk",
-      version: "5.2.0",
+      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",
@@ -1694,6 +1694,7 @@ var EXPECTED_ISSUER = "https://confidentialcomputing.googleapis.com";
 var EXPECTED_HW_MODEL = "GCP_AMD_SEV";
 var EXPECTED_TEE_PROVIDER = "gcp";
 var EXPECTED_TEE_TECHNOLOGY = "amd-sev";
+var SUPPORTED_PROOF_VERSIONS = ["v2", "v3"];
 var TOKEN_CLOCK_SKEW_S = 60;
 var NONCE_TIMESTAMP_MAX_SKEW_MS = 10 * 60 * 1e3;
 var BROWSER_ENVIRONMENT_ERROR = "TEE attestation verification is only supported in non-browser environments. Run verifyTeeAttestation on your server or API route.";
@@ -1933,12 +1934,17 @@ function assertAudienceClaim(aud) {
   }
   throw new Error("attestation token audience is missing");
 }
+function getProofVersion(teeAttestation) {
+  var _a;
+  return (_a = teeAttestation.proof_version) != null ? _a : teeAttestation.proofVersion;
+}
 function assertProofShape(teeAttestation) {
   var _a, _b, _c;
   if (teeAttestation.error) {
     throw new Error(`${teeAttestation.error.code}: ${teeAttestation.error.message}`);
   }
-  assert(teeAttestation.proof_version === "v2", `unexpected proof version: ${teeAttestation.proof_version}`);
+  const proofVersion = getProofVersion(teeAttestation);
+  assert(typeof proofVersion === "string" && SUPPORTED_PROOF_VERSIONS.includes(proofVersion), `unexpected proof version: ${proofVersion}`);
   assert(teeAttestation.tee_provider === EXPECTED_TEE_PROVIDER, `unexpected tee provider: ${teeAttestation.tee_provider}`);
   assert(teeAttestation.tee_technology === EXPECTED_TEE_TECHNOLOGY, `unexpected tee technology: ${teeAttestation.tee_technology}`);
   assert(typeof teeAttestation.nonce === "string" && teeAttestation.nonce.length > 0, "tee attestation nonce missing");
@@ -1948,6 +1954,26 @@ function assertProofShape(teeAttestation) {
   assert(typeof ((_b = teeAttestation.verifier) == null ? void 0 : _b.image_digest) === "string" && teeAttestation.verifier.image_digest.length > 0, "verifier image digest missing");
   assert(typeof ((_c = teeAttestation.attestation) == null ? void 0 : _c.token) === "string" && teeAttestation.attestation.token.length > 0, "attestation token missing");
 }
+function computeDigestBinding(teeAttestation) {
+  return __async(this, null, function* () {
+    const proofVersion = getProofVersion(teeAttestation);
+    if (proofVersion === "v3") {
+      assert(typeof teeAttestation.workload.container_name === "string" && teeAttestation.workload.container_name.length > 0, "workload container name missing");
+      assert(typeof teeAttestation.verifier.container_name === "string" && teeAttestation.verifier.container_name.length > 0, "verifier container name missing");
+      return sha256Hex([
+        "v3",
+        `workload.container_name=${teeAttestation.workload.container_name}`,
+        `workload.image_digest=${teeAttestation.workload.image_digest}`,
+        `verifier.container_name=${teeAttestation.verifier.container_name}`,
+        `verifier.image_digest=${teeAttestation.verifier.image_digest}`
+      ].join("\n"));
+    }
+    return sha256Hex(
+      `${teeAttestation.workload.image_digest}
+${teeAttestation.verifier.image_digest}`
+    );
+  });
+}
 function verifyGcpClaims(teeAttestation, expectedNonce) {
   return __async(this, null, function* () {
     var _a;
@@ -1955,10 +1981,7 @@ function verifyGcpClaims(teeAttestation, expectedNonce) {
     assert(claims.iss === EXPECTED_ISSUER, `unexpected issuer: ${claims.iss}`);
     assertAudienceClaim(claims.aud);
     assert(Array.isArray(claims.eat_nonce), "eat_nonce claim missing");
-    const digestBinding = yield sha256Hex(
-      `${teeAttestation.workload.image_digest}
-${teeAttestation.verifier.image_digest}`
-    );
+    const digestBinding = yield computeDigestBinding(teeAttestation);
     assert(claims.eat_nonce.includes(expectedNonce), "request nonce is not present in attestation token");
     assert(claims.eat_nonce.includes(digestBinding), "digest-binding nonce is not present in attestation token");
     assert(claims.hwmodel === EXPECTED_HW_MODEL, `unexpected hwmodel: ${claims.hwmodel}`);
@@ -2025,6 +2048,7 @@ function runTeeVerification(proofs, config) {
 // src/Reclaim.ts
 var logger10 = logger_default.logger;
 var sdkVersion = require_package().version;
+var SDK_TEE_ATTESTATION_VERSION = "v3";
 function verifyProof(proofOrProofs, config) {
   return __async(this, null, function* () {
     const proofs = Array.isArray(proofOrProofs) ? proofOrProofs : [proofOrProofs];
@@ -2111,7 +2135,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
      * @returns
      */
     this.getTemplateData = () => {
-      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o;
       if (!this.signature) {
         throw new SignatureNotFoundError("Signature is not set.");
       }
@@ -2151,7 +2175,9 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
         log: (_h = (_g = this.options) == null ? void 0 : _g.log) != null ? _h : false,
         canAutoSubmit: (_j = (_i = this.options) == null ? void 0 : _i.canAutoSubmit) != null ? _j : true,
         metadata: (_k = this.options) == null ? void 0 : _k.metadata,
-        preferredLocale: (_l = this.options) == null ? void 0 : _l.preferredLocale
+        preferredLocale: (_l = this.options) == null ? void 0 : _l.preferredLocale,
+        acceptTeeAttestation: (_m = this.options) == null ? void 0 : _m.acceptTeeAttestation,
+        teeAttestationVersion: (_o = (_n = this.context.attestationNonceData) == null ? void 0 : _n.attestationVersion) != null ? _o : SDK_TEE_ATTESTATION_VERSION
       };
       return templateData;
     };
@@ -2222,6 +2248,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
    */
   static init(applicationId, appSecret, providerId, options) {
     return __async(this, null, function* () {
+      var _a;
       try {
         validateFunctionParams([
           { paramName: "applicationId", input: applicationId, isString: true },
@@ -2303,14 +2330,17 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
             }, "the constructor");
           }
         }
-        const proofRequestInstance = new _ReclaimProofRequest(applicationId, providerId, options);
+        const proofRequestOptions = __spreadProps(__spreadValues({}, options), {
+          acceptTeeAttestation: (_a = options == null ? void 0 : options.acceptTeeAttestation) != null ? _a : true
+        });
+        const proofRequestInstance = new _ReclaimProofRequest(applicationId, providerId, proofRequestOptions);
         const signature = yield proofRequestInstance.generateSignature(appSecret);
         proofRequestInstance.setSignature(signature);
         const data = yield initSession(providerId, applicationId, proofRequestInstance.timeStamp, signature, options == null ? void 0 : options.providerVersion);
         proofRequestInstance.sessionId = data.sessionId;
         proofRequestInstance.resolvedProviderVersion = data.resolvedProviderVersion;
         proofRequestInstance.context.reclaimSessionId = data.sessionId;
-        if (options == null ? void 0 : options.acceptTeeAttestation) {
+        if (proofRequestOptions.acceptTeeAttestation) {
           const attestationNonce = generateAttestationNonce(
             appSecret,
             applicationId,
@@ -2320,7 +2350,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           proofRequestInstance.setAttestationContext(attestationNonce, {
             applicationId,
             sessionId: data.sessionId,
-            timestamp: proofRequestInstance.timeStamp
+            timestamp: proofRequestInstance.timeStamp,
+            attestationVersion: SDK_TEE_ATTESTATION_VERSION
           });
         }
         return proofRequestInstance;