@reclaimprotocol/js-sdk 5.3.0 → 5.4.0

package/dist/index.d.ts

@@ -899,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
      *
@@ -1178,6 +1219,7 @@ declare class ReclaimProofRequest {
      * ```
      */
     getSessionId(): string;
+    private static validateInitOptions;
     private setSignature;
     private generateSignature;
     private clearInterval;
@@ -1463,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;
 /**
@@ -1576,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",
+      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,