@reclaimprotocol/js-sdk 5.3.0-dev.1 → 5.4.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.
@@ -892,6 +899,47 @@ declare class ReclaimProofRequest {
      * ```
      */
     static init(applicationId: string, appSecret: string, providerId: string, options?: ProofRequestOptions): Promise<ReclaimProofRequest>;
+    /**
+     * Initializes a new Reclaim proof request using a signature computed externally
+     * (e.g. on a trusted backend), so `appSecret` never has to live on the client.
+     *
+     * The signature must be produced over `canonicalize({ providerId, timestamp })`
+     * using the application's `appSecret` — see `generateInitSignature()` for the
+     * exact algorithm. The same `timestamp` used at signing time must be passed here.
+     *
+     * TEE attestation: the attestation nonce depends on `sessionId`, which is only
+     * known after the backend init call. To use TEE without exposing `appSecret`,
+     * pass an async `getAttestationNonce` callback that derives the nonce on your
+     * server using `generateAttestationNonce(appSecret, applicationId, sessionId, timestamp)`.
+     * If `acceptTeeAttestation` is left enabled but no callback is provided, init throws.
+     *
+     * @param applicationId - Your Reclaim application ID
+     * @param providerId - The ID of the provider to use for proof generation
+     * @param sessionAuth - Pre-computed signature, the timestamp it was signed over,
+     *                      and an optional async callback to compute the attestation nonce.
+     * @param options - Optional configuration options for the proof request
+     *
+     * @example
+     * ```typescript
+     * // Backend (Node):
+     * const timestamp = Date.now().toString();
+     * const signature = await generateInitSignature(APP_SECRET, providerId, timestamp);
+     * // ...return { signature, timestamp } to the client...
+     *
+     * // Client:
+     * const proofRequest = await ReclaimProofRequest.initWithSignature(
+     *   applicationId,
+     *   providerId,
+     *   { signature, timestamp },
+     *   { acceptTeeAttestation: false }
+     * );
+     * ```
+     */
+    static initWithSignature(applicationId: string, providerId: string, sessionAuth: {
+        signature: string;
+        timestamp: string;
+        getAttestationNonce?: (sessionId: string) => Promise<string> | string;
+    }, options?: ProofRequestOptions): Promise<ReclaimProofRequest>;
     /**
      * Creates a ReclaimProofRequest instance from a JSON string representation
      *
@@ -1171,6 +1219,7 @@ declare class ReclaimProofRequest {
      * ```
      */
     getSessionId(): string;
+    private static validateInitOptions;
     private setSignature;
     private generateSignature;
     private clearInterval;
@@ -1456,6 +1505,22 @@ declare function updateSession(sessionId: string, status: SessionStatus): Promis
 declare function fetchStatusUrl(sessionId: string): Promise<StatusUrlResponse>;
 declare function fetchProviderConfigs(providerId: string, exactProviderVersionString: string | null | undefined, allowedTags: string[] | null | undefined): Promise<ProviderConfigResponse>;
 
+/**
+ * Computes the signature required by `initSession` over `{providerId, timestamp}`.
+ *
+ * Use this on a trusted server (where `appSecret` lives) to produce a signature
+ * that can then be passed to `ReclaimProofRequest.initWithSignature(...)` from a
+ * client that never sees the secret.
+ *
+ * @param appSecret - The application secret (private key). Must remain server-side.
+ * @param providerId - The provider id the session will be initialized against.
+ * @param timestamp - The timestamp (ms epoch as string) that will be sent with init.
+ *                    The same value MUST be passed to `initWithSignature`.
+ */
+declare function generateInitSignature(appSecret: string, providerId: string, timestamp: string): Promise<string>;
+
+declare function generateAttestationNonce(appSecret: string, applicationId: string, sessionId: string, timestamp: string): string;
+
 declare function createSignDataForClaim(data: CompleteClaimData): string;
 declare function getIdentifierFromClaimInfo(info: ClaimInfo): ClaimID;
 /**
@@ -1509,6 +1574,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.
@@ -1565,4 +1634,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, 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 };
+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, generateAttestationNonce, generateInitSignature, 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.3.0-dev.1",
+      version: "5.4.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",
@@ -203,6 +203,8 @@ __export(index_exports, {
   fetchProviderConfigs: () => fetchProviderConfigs,
   fetchProviderHashRequirementsBy: () => fetchProviderHashRequirementsBy,
   fetchStatusUrl: () => fetchStatusUrl,
+  generateAttestationNonce: () => generateAttestationNonce,
+  generateInitSignature: () => generateInitSignature,
   generateSpecsFromRequestSpecTemplate: () => generateSpecsFromRequestSpecTemplate,
   getAttestors: () => getAttestors,
   getDeviceType: () => getDeviceType,
@@ -2255,81 +2257,7 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
           { paramName: "providerId", input: providerId, isString: true },
           { paramName: "appSecret", input: appSecret, isString: true }
         ], "the constructor");
-        if (options) {
-          if (options.acceptAiProviders) {
-            validateFunctionParams([
-              { paramName: "acceptAiProviders", input: options.acceptAiProviders }
-            ], "the constructor");
-          }
-          if (options.providerVersion) {
-            validateFunctionParams([
-              { paramName: "providerVersion", input: options.providerVersion, isString: true }
-            ], "the constructor");
-          }
-          if (options.log) {
-            validateFunctionParams([
-              { paramName: "log", input: options.log }
-            ], "the constructor");
-          }
-          if (options.useAppClip) {
-            validateFunctionParams([
-              { paramName: "useAppClip", input: options.useAppClip }
-            ], "the constructor");
-          }
-          if (options.device) {
-            validateFunctionParams([
-              { paramName: "device", input: options.device, isString: true }
-            ], "the constructor");
-          }
-          if (options.useBrowserExtension) {
-            validateFunctionParams([
-              { paramName: "useBrowserExtension", input: options.useBrowserExtension }
-            ], "the constructor");
-          }
-          if (options.extensionID) {
-            validateFunctionParams([
-              { paramName: "extensionID", input: options.extensionID, isString: true }
-            ], "the constructor");
-          }
-          if (options.envUrl) {
-            validateFunctionParams([
-              { paramName: "envUrl", input: options.envUrl, isString: true }
-            ], "the constructor");
-          }
-          if (options.portalUrl) {
-            validateFunctionParams([
-              { paramName: "portalUrl", input: options.portalUrl, isString: true }
-            ], "the constructor");
-          }
-          if (options.customSharePageUrl) {
-            validateFunctionParams([
-              { paramName: "customSharePageUrl", input: options.customSharePageUrl, isString: true }
-            ], "the constructor");
-          }
-          if (options.customAppClipUrl) {
-            validateFunctionParams([
-              { paramName: "customAppClipUrl", input: options.customAppClipUrl, isString: true }
-            ], "the constructor");
-          }
-          if (options.preferredLocale) {
-            validateFunctionParams([
-              { paramName: "preferredLocale", input: options.preferredLocale, isString: true }
-            ], "the constructor");
-            validateFunctionParamsWithFn({
-              paramName: "preferredLocale",
-              input: options.preferredLocale,
-              isValid: () => {
-                try {
-                  Intl.getCanonicalLocales(options.preferredLocale);
-                  return true;
-                } catch (error) {
-                  logger10.info("Failed to canonicalize locale", error);
-                  return false;
-                }
-              }
-            }, "the constructor");
-          }
-        }
+        _ReclaimProofRequest.validateInitOptions(options, "the constructor");
         const proofRequestOptions = __spreadProps(__spreadValues({}, options), {
           acceptTeeAttestation: (_a = options == null ? void 0 : options.acceptTeeAttestation) != null ? _a : true
         });
@@ -2362,6 +2290,95 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
       }
     });
   }
+  /**
+   * Initializes a new Reclaim proof request using a signature computed externally
+   * (e.g. on a trusted backend), so `appSecret` never has to live on the client.
+   *
+   * The signature must be produced over `canonicalize({ providerId, timestamp })`
+   * using the application's `appSecret` — see `generateInitSignature()` for the
+   * exact algorithm. The same `timestamp` used at signing time must be passed here.
+   *
+   * TEE attestation: the attestation nonce depends on `sessionId`, which is only
+   * known after the backend init call. To use TEE without exposing `appSecret`,
+   * pass an async `getAttestationNonce` callback that derives the nonce on your
+   * server using `generateAttestationNonce(appSecret, applicationId, sessionId, timestamp)`.
+   * If `acceptTeeAttestation` is left enabled but no callback is provided, init throws.
+   *
+   * @param applicationId - Your Reclaim application ID
+   * @param providerId - The ID of the provider to use for proof generation
+   * @param sessionAuth - Pre-computed signature, the timestamp it was signed over,
+   *                      and an optional async callback to compute the attestation nonce.
+   * @param options - Optional configuration options for the proof request
+   *
+   * @example
+   * ```typescript
+   * // Backend (Node):
+   * const timestamp = Date.now().toString();
+   * const signature = await generateInitSignature(APP_SECRET, providerId, timestamp);
+   * // ...return { signature, timestamp } to the client...
+   *
+   * // Client:
+   * const proofRequest = await ReclaimProofRequest.initWithSignature(
+   *   applicationId,
+   *   providerId,
+   *   { signature, timestamp },
+   *   { acceptTeeAttestation: false }
+   * );
+   * ```
+   */
+  static initWithSignature(applicationId, providerId, sessionAuth, options) {
+    return __async(this, null, function* () {
+      var _a;
+      try {
+        validateFunctionParams([
+          { paramName: "applicationId", input: applicationId, isString: true },
+          { paramName: "providerId", input: providerId, isString: true },
+          { paramName: "signature", input: sessionAuth == null ? void 0 : sessionAuth.signature, isString: true },
+          { paramName: "timestamp", input: sessionAuth == null ? void 0 : sessionAuth.timestamp, isString: true }
+        ], "initWithSignature");
+        _ReclaimProofRequest.validateInitOptions(options, "initWithSignature");
+        const proofRequestOptions = __spreadProps(__spreadValues({}, options), {
+          acceptTeeAttestation: (_a = options == null ? void 0 : options.acceptTeeAttestation) != null ? _a : true
+        });
+        if (proofRequestOptions.acceptTeeAttestation && !sessionAuth.getAttestationNonce) {
+          throw new InvalidParamError(
+            "initWithSignature requires a `getAttestationNonce` callback when `acceptTeeAttestation` is enabled. Either pass `acceptTeeAttestation: false`, or provide a callback that computes the nonce server-side using `generateAttestationNonce(appSecret, applicationId, sessionId, timestamp)`."
+          );
+        }
+        const proofRequestInstance = new _ReclaimProofRequest(applicationId, providerId, proofRequestOptions);
+        proofRequestInstance.timeStamp = sessionAuth.timestamp;
+        proofRequestInstance.setSignature(sessionAuth.signature);
+        const data = yield initSession(
+          providerId,
+          applicationId,
+          sessionAuth.timestamp,
+          sessionAuth.signature,
+          options == null ? void 0 : options.providerVersion
+        );
+        proofRequestInstance.sessionId = data.sessionId;
+        proofRequestInstance.resolvedProviderVersion = data.resolvedProviderVersion;
+        proofRequestInstance.context.reclaimSessionId = data.sessionId;
+        if (proofRequestOptions.acceptTeeAttestation && sessionAuth.getAttestationNonce) {
+          const attestationNonce = yield sessionAuth.getAttestationNonce(data.sessionId);
+          validateFunctionParams(
+            [{ input: attestationNonce, paramName: "attestationNonce", isString: true }],
+            "initWithSignature"
+          );
+          proofRequestInstance.setAttestationContext(attestationNonce, {
+            applicationId,
+            sessionId: data.sessionId,
+            timestamp: sessionAuth.timestamp,
+            attestationVersion: SDK_TEE_ATTESTATION_VERSION
+          });
+        }
+        return proofRequestInstance;
+      } catch (error) {
+        console.error(error);
+        logger10.info("Failed to initialize ReclaimProofRequest with signature", error);
+        throw new InitError("Failed to initialize ReclaimProofRequest with signature", error);
+      }
+    });
+  }
   /**
    * Creates a ReclaimProofRequest instance from a JSON string representation
    *
@@ -2855,6 +2872,58 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     }
     return this.sessionId;
   }
+  static validateInitOptions(options, caller) {
+    if (!options) return;
+    if (options.acceptAiProviders) {
+      validateFunctionParams([{ paramName: "acceptAiProviders", input: options.acceptAiProviders }], caller);
+    }
+    if (options.providerVersion) {
+      validateFunctionParams([{ paramName: "providerVersion", input: options.providerVersion, isString: true }], caller);
+    }
+    if (options.log) {
+      validateFunctionParams([{ paramName: "log", input: options.log }], caller);
+    }
+    if (options.useAppClip) {
+      validateFunctionParams([{ paramName: "useAppClip", input: options.useAppClip }], caller);
+    }
+    if (options.device) {
+      validateFunctionParams([{ paramName: "device", input: options.device, isString: true }], caller);
+    }
+    if (options.useBrowserExtension) {
+      validateFunctionParams([{ paramName: "useBrowserExtension", input: options.useBrowserExtension }], caller);
+    }
+    if (options.extensionID) {
+      validateFunctionParams([{ paramName: "extensionID", input: options.extensionID, isString: true }], caller);
+    }
+    if (options.envUrl) {
+      validateFunctionParams([{ paramName: "envUrl", input: options.envUrl, isString: true }], caller);
+    }
+    if (options.portalUrl) {
+      validateFunctionParams([{ paramName: "portalUrl", input: options.portalUrl, isString: true }], caller);
+    }
+    if (options.customSharePageUrl) {
+      validateFunctionParams([{ paramName: "customSharePageUrl", input: options.customSharePageUrl, isString: true }], caller);
+    }
+    if (options.customAppClipUrl) {
+      validateFunctionParams([{ paramName: "customAppClipUrl", input: options.customAppClipUrl, isString: true }], caller);
+    }
+    if (options.preferredLocale) {
+      validateFunctionParams([{ paramName: "preferredLocale", input: options.preferredLocale, isString: true }], caller);
+      validateFunctionParamsWithFn({
+        paramName: "preferredLocale",
+        input: options.preferredLocale,
+        isValid: () => {
+          try {
+            Intl.getCanonicalLocales(options.preferredLocale);
+            return true;
+          } catch (error) {
+            logger10.info("Failed to canonicalize locale", error);
+            return false;
+          }
+        }
+      }, caller);
+    }
+  }
   // Private helper methods
   setSignature(signature) {
     try {
@@ -3533,6 +3602,33 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
     return this.jsonProofResponse;
   }
 };
+
+// src/utils/signatureUtils.ts
+var import_ethers7 = require("ethers");
+var import_canonicalize4 = __toESM(require("canonicalize"));
+function generateInitSignature(appSecret, providerId, timestamp) {
+  return __async(this, null, function* () {
+    validateFunctionParams([
+      { input: appSecret, paramName: "appSecret", isString: true },
+      { input: providerId, paramName: "providerId", isString: true },
+      { input: timestamp, paramName: "timestamp", isString: true }
+    ], "generateInitSignature");
+    try {
+      const wallet = new import_ethers7.ethers.Wallet(appSecret);
+      const canonicalData = (0, import_canonicalize4.default)({ providerId, timestamp });
+      if (!canonicalData) {
+        throw new SignatureGeneratingError("Failed to canonicalize data for signing.");
+      }
+      const messageHash = import_ethers7.ethers.keccak256(new TextEncoder().encode(canonicalData));
+      return yield wallet.signMessage(import_ethers7.ethers.getBytes(messageHash));
+    } catch (err) {
+      throw new SignatureGeneratingError(
+        `Error generating init signature for providerId: ${providerId}`,
+        err
+      );
+    }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ReclaimProofRequest,
@@ -3546,6 +3642,8 @@ var ReclaimProofRequest = class _ReclaimProofRequest {
   fetchProviderConfigs,
   fetchProviderHashRequirementsBy,
   fetchStatusUrl,
+  generateAttestationNonce,
+  generateInitSignature,
   generateSpecsFromRequestSpecTemplate,
   getAttestors,
   getDeviceType,