@reclaimprotocol/js-sdk 5.0.0-dev.1 → 5.0.0-dev.3

package/README.md

@@ -99,7 +99,7 @@ function App() {
           setProofs(proofs);
         }
       },
-      onFailure: (error) => {
+      onError: (error) => {
         console.error("Verification failed", error);
       },
     });
@@ -181,7 +181,7 @@ async function handleCreateClaim() {
           setProofs(proofs);
         }
       },
-      onFailure: (error) => {
+      onError: (error) => {
         console.error("Verification failed", error);
       },
     });
@@ -193,17 +193,57 @@ async function handleCreateClaim() {
 
 ### How triggerReclaimFlow() Works
 
-The `triggerReclaimFlow()` method automatically detects the user's environment and chooses the optimal verification method:
+The `triggerReclaimFlow()` method supports two verification modes via `verificationMode`:
+
+- **`'portal'` (default)**: Opens the portal URL for remote browser verification. Opens in a new tab by default, or embedded in an iframe when `target` is provided.
+- **`'app'`**: Verifier app flow via the share page. Uses App Clip on iOS if `useAppClip` is `true`.
+
+The method returns a `FlowHandle` that lets you close the flow programmatically:
+
+```javascript
+// Portal flow (default) — opens in new tab
+const handle = await reclaimProofRequest.triggerReclaimFlow();
+handle.tab;    // Window reference to the opened tab
+handle.close(); // close tab and stop polling
+
+// Embedded — portal loads inside a DOM element as an iframe
+const handle = await reclaimProofRequest.triggerReclaimFlow({
+  target: document.getElementById('reclaim-container')
+});
+handle.iframe; // HTMLIFrameElement reference
+handle.iframe?.style.height = '700px'; // customize the iframe
+handle.close(); // remove iframe and stop polling
+
+// Verifier app flow
+const handle = await reclaimProofRequest.triggerReclaimFlow({ verificationMode: 'app' });
+handle.close(); // stop polling
+```
 
 #### On Desktop Browsers:
 
-1. **Browser Extension First**: If the Reclaim browser extension is installed, it will use the extension for a seamless in-browser verification experience.
-2. **QR Code Fallback**: If the extension is not available, it automatically displays a QR code modal for mobile scanning.
+1. **Embedded mode**: If `target` is provided, the portal loads in an iframe inside the target element.
+2. **Browser Extension**: If the Reclaim browser extension is installed and no `target` is set, it will use the extension.
+3. **Portal mode** (no extension, no target): Opens the portal in a new tab.
+4. **App mode** (no extension): Shows QR code modal with share page URL.
+
+#### On Mobile Devices (portal mode):
+
+Opens the portal in a new tab, or in an iframe if `target` is provided.
 
-#### On Mobile Devices:
+#### On Mobile Devices (app mode):
 
-1. **iOS Devices**: Automatically redirects to the Reclaim App Clip for native iOS verification.
-2. **Android Devices**: Automatically redirects to the Reclaim Instant App for native Android verification.
+1. **All platforms**: Redirects to the verifier app.
+2. **iOS with `useAppClip: true`**: Redirects to the Reclaim App Clip instead.
+
+The same `verificationMode` option works with `getRequestUrl()`:
+
+```javascript
+// Portal URL (default)
+const url = await reclaimProofRequest.getRequestUrl();
+
+// Verifier app URL
+const url = await reclaimProofRequest.getRequestUrl({ verificationMode: 'app' });
+```
 
 ### Browser Extension Support
 
@@ -264,10 +304,10 @@ await reclaimProofRequest.triggerReclaimFlow();
 ### Benefits of the New Flow:
 
 1. **Platform Adaptive**: Automatically chooses the best verification method for each platform
-2. **User-Friendly**: Provides the most seamless experience possible for each user
-3. **Simplified Integration**: Single method call handles all verification scenarios
+2. **Embeddable**: Embed the portal directly in your page via iframe with `{ target: element }`
+3. **Controllable**: Returns a `FlowHandle` to close the flow or access the iframe at any time
 4. **Extension Support**: Leverages browser extension for desktop users when available
-5. **Mobile Optimized**: Native app experiences on mobile devices
+5. **Mobile Optimized**: Verifier app experiences on mobile devices
 
 ## Step 6: Run your application
 
@@ -289,7 +329,7 @@ Your Reclaim SDK demo should now be running. Click the "Create Claim" button to
 
 4. **Verification**: The `onSuccess` is called when verification is successful, providing the proof data. When using a custom callback url, the proof is returned to the callback url and we get an empty array instead of a proof.
 
-5. **Handling Failures**: The `onFailure` is called if verification fails, allowing you to handle errors gracefully.
+5. **Handling Failures**: The `onError` is called if verification fails, allowing you to handle errors gracefully.
 
 ## Advanced Configuration
 
@@ -324,17 +364,17 @@ Redirection with body:
 
    - **url**: The URL where users should be redirected after successful proof generation.
    - **method** (optional): The redirection method to use. Allowed options: `GET` (default) and `POST`. 
-     *Note: `POST` form redirection is only supported in In-Browser SDK.*
+     *Note: `POST` form redirection is only supported in Portal flow.*
    - **body** (optional): List of name-value pairs to be sent as the body of the form request.
      - When `method` is `POST`, `body` is sent with `application/x-www-form-urlencoded` content type.
      - When `method` is `GET`, if `body` is set, it is sent as query parameters.
-     *Note: Sending `body` on redirection is only supported in In-Browser SDK.*
+     *Note: Sending `body` on redirection is only supported in Portal flow.*
 
 ```javascript
 reclaimProofRequest.setRedirectUrl(
   "https://example.com/redirect",
-  "POST", // In-Browser SDK only
-  [{ name: "foo", value: "bar" }]  // In-Browser SDK only
+  "POST", // Portal flow only
+  [{ name: "foo", value: "bar" }]  // Portal flow only
 );
 ```
 
@@ -350,17 +390,17 @@ Redirection with body:
 
    - **url**: The URL where users should be redirected after an error which aborts the verification process.
    - **method** (optional): The redirection method to use. Allowed options: `GET` (default) and `POST`.
-     *Note: `POST` form redirection is only supported in In-Browser SDK.*
+     *Note: `POST` form redirection is only supported in Portal flow.*
    - **body** (optional): List of name-value pairs to be sent as the body of the form request.
      - When `method` is `POST`, `body` is sent with `application/x-www-form-urlencoded` content type.
      - When `method` is `GET`, if `body` is set, it is sent as query parameters.
-     *Note: Sending `body` on redirection is only supported in In-Browser SDK.*
+     *Note: Sending `body` on redirection is only supported in Portal flow.*
   
 ```javascript
 reclaimProofRequest.setCancelRedirectUrl(
   "https://example.com/error-redirect",
-  "POST",  // In-Browser SDK only
-  [{ name: "error_code", value: "1001" }]  // In-Browser SDK only
+  "POST",  // Portal flow only
+  [{ name: "error_code", value: "1001" }]  // Portal flow only
 );
 ```
 
@@ -371,6 +411,7 @@ reclaimProofRequest.setCancelRedirectUrl(
 
    By default, proofs are sent as HTTP `POST` with `Content-Type` as `application/x-www-form-urlencoded`. Pass function argument `jsonProofResponse` as `true` to send proofs with `Content-Type` as `application/json`.
 
+   ```javascript
    reclaimProofRequest.setAppCallbackUrl("https://example.com/callback", true);
    ```
 
@@ -431,33 +472,51 @@ For more details about response format, check out [official documentation of Err
    const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
      useBrowserExtension: true, // Enable browser extension support (default: true)
      extensionID: "custom-extension-id", // Custom extension identifier
-     useAppClip: true, // Enable mobile app clips (default: true)
+     useAppClip: false, // Enable mobile app clips (default: false)
      log: true, // Enable troubleshooting mode and more verbose logging for debugging
    });
    ```
 
-9. **Custom Share Page and App Clip URLs**:
-   You can customize the share page and app clip URLs for your app:
+9. **Custom Portal URL and App Clip URLs**:
+   You can customize the portal/share page and app clip URLs for your app:
 
 ```javascript
 const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
-  customSharePageUrl: "https://your-custom-domain.com/verify", // Custom share page URL
+  portalUrl: "https://your-custom-domain.com/verify", // Custom URL for both portal and app modes
   customAppClipUrl: "https://appclip.apple.com/id?p=your.custom.app.clip", // Custom iOS App Clip URL
   // ... other options
 });
 ```
 
+> **Defaults:**
+> - Portal mode: `https://portal.reclaimprotocol.org` — remote browser verification
+> - App mode: `https://share.reclaimprotocol.org` — redirects to the verifier app
+>
+> Setting `portalUrl` overrides both modes. The previous `customSharePageUrl` is deprecated but still supported — if both are provided, `portalUrl` takes precedence. `useAppClip` defaults to `false`.
+
 10. **Platform-Specific Flow Control**:
-   The `triggerReclaimFlow()` method provides intelligent platform detection, but you can still use traditional methods for custom flows:
+   Both `triggerReclaimFlow()` and `getRequestUrl()` support `verificationMode`:
 
    ```javascript
-   // Traditional approach with manual QR code handling
-   const requestUrl = await reclaimProofRequest.getRequestUrl();
-   // Display your own QR code implementation
+   // Portal flow (default) — opens in new tab
+   const handle = await reclaimProofRequest.triggerReclaimFlow();
+   handle.tab;    // Window reference
+   handle.close(); // close tab, stop polling
+
+   // Embedded portal — loads inside a DOM element
+   const handle = await reclaimProofRequest.triggerReclaimFlow({
+     target: document.getElementById('container')
+   });
+   handle.iframe; // HTMLIFrameElement reference
+   handle.close(); // remove iframe, stop polling
 
-   // Or use the new streamlined approach
-   await reclaimProofRequest.triggerReclaimFlow();
-   // Automatically handles platform detection and optimal user experience
+   // Verifier app flow
+   const handle = await reclaimProofRequest.triggerReclaimFlow({ verificationMode: 'app' });
+   handle.close(); // stop polling
+
+   // getRequestUrl also supports verificationMode
+   const portalUrl = await reclaimProofRequest.getRequestUrl();
+   const appUrl = await reclaimProofRequest.getRequestUrl({ verificationMode: 'app' });
    ```
 
 11. **Exporting and Importing SDK Configuration**:
@@ -550,34 +609,153 @@ These options allow you to securely process proofs or cancellations on your serv
 
 ## Proof Verification
 
-The SDK provides a `verifyProof` function to manually verify proofs. This is useful when you need to validate proofs outside of the normal flow:
+The SDK provides a `verifyProof` function to manually verify proofs cryptographically on your backend. This involves validating the attestor signatures and enforcing that the proof matches the expected requirements.
+
+Here are the possible ways to use `verifyProof`, from beginner to advanced:
+
+### 1. Simple Verification
+The easiest way is to use `request.getProviderVersion()` which returns the provider ID and exact version used in the session — pass it directly as the config:
 
 ```javascript
 import { verifyProof } from "@reclaimprotocol/js-sdk";
 
-// Verify a single proof
-const isValid = await verifyProof(proof);
-if (isValid) {
+// Using getProviderVersion() — recommended
+const providerVersion = reclaimProofRequest.getProviderVersion();
+const { isVerified, data, error } = await verifyProof(proof, providerVersion);
+if (isVerified) {
   console.log("Proof is valid");
+  console.log("Context:", data[0].context);
+  console.log("Extracted parameters:", data[0].extractedParameters);
 } else {
-  console.log("Proof is invalid");
+  console.log("Proof is invalid, reason:", error);
+}
+```
+
+Or, by manually providing the provider details:
+```javascript
+const { isVerified, data } = await verifyProof(proof, {
+  providerId: "YOUR_PROVIDER_ID",
+  // The exact provider version used in the session.
+  providerVersion: "1.0.0",
+  // Optionally provide tags. For example, this can be `['ai']` when you want to allow patches from ai.
+  allowedTags: ["ai"]
+});
+```
+
+Or, with a known hash:
+```javascript
+const { isVerified, data, error } = await verifyProof(proof, { hashes: ['0xAbC...'] });
+```
+
+### 2. Intermediate: Strict Hash Verification
+
+If you want to avoid network requests, you can manually feed the expected cryptographic hashes your system allows.
+
+```javascript
+// Verify a proof against a known, strict expected hash
+const { isVerified, data } = await verifyProof(proof, {
+  hashes: ['0x1abc2def3456...']
+});
+```
+
+### 3. Advanced: Multiple Proofs and Optional Matches
+When building advanced use-cases, you might process multiple distinct proofs at once or deal with providers that yield a few valid hash possibilities (e.g., due to optional data fields).
+
+```javascript
+const result = await verifyProof([proof1, proof2, sameAsProof2], {
+  hashes: [
+    // A string hash is equivalent to an object with { value: '...', required: true, multiple: true }.
+    '0xStrictHash123...',
+    {
+       // An array 'value' means that 1 proof can have any 1 matching hash
+       // from this list, typically because of optional variables in the original request.
+       value: ['0xOptHash1...', '0xOptHashA...'],
+       // 'multiple' being true (which is the default) means any proof matching this hash
+       // is allowed to appear multiple times in the list of proofs you are verifying.
+       multiple: true
+    },
+    {
+       value: '0xE33...',
+       // 'required: false' means there can be 0 proofs matching this hash.
+       // Such proofs may be optionally present in the list of proofs.
+       // (By default, 'required' is true).
+       required: false
+    }
+  ]
+});
+
+if (result.isVerified) {
+  result.data.forEach((d, i) => {
+    console.log(`Proof ${i + 1} context:`, d.context);
+    console.log(`Proof ${i + 1} params:`, d.extractedParameters);
+  });
 }
+```
+
+### 4. Danger Zone: Disabled Content Validation
+If you only want to verify the attestor signature but wish to dangerously bypass the parameter/content match (Not Recommended):
+
+```javascript
+const { isVerified } = await verifyProof(proof, {
+  dangerouslyDisableContentValidation: true
+});
+```
+
+## TEE Attestation Verification
+
+The SDK supports verifying TEE (Trusted Execution Environment) attestations included in proofs. This provides hardware-level assurance that the proof was generated inside a secure enclave (AMD SEV-SNP).
+
+### Enabling TEE Attestation
+
+To request TEE attestation during proof generation, enable it during initialization:
 
-// Verify multiple proofs
-const areValid = await verifyProof([proof1, proof2, proof3]);
-if (areValid) {
-  console.log("All proofs are valid");
+```javascript
+const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
+  acceptTeeAttestation: true,
+});
+```
+
+### Verifying TEE Attestation
+
+Set `verifyTEE: true` in the config to require and verify TEE attestation. If TEE data is missing or invalid, verification will fail with a `TeeVerificationError`.
+
+```javascript
+import { verifyProof, TeeVerificationError } from "@reclaimprotocol/js-sdk";
+
+// Set verifyTEE in config to require TEE verification
+const { isVerified, isTeeVerified, data, error } = await verifyProof(proof, { hashes: ['0xAbC...'], verifyTEE: true });
+
+if (isVerified) {
+  console.log("Proof is fully verified with hardware attestation");
+  console.log("TEE verified:", isTeeVerified);
+  console.log("Extracted parameters:", data[0].extractedParameters);
+} else if (error instanceof TeeVerificationError) {
+  console.log("TEE verification failed:", error.message);
 } else {
-  console.log("One or more proofs are invalid");
+  console.log("Proof verification failed:", error);
 }
 ```
 
-The `verifyProof` function:
+When `verifyTEE` is `true`, the result includes `isTeeVerified`. The overall `isVerified` will be `false` if TEE data is missing or TEE verification fails.
+
+The TEE verification validates:
+- **Nonce binding**: Ensures the attestation nonce matches the proof context
+- **Application ID**: Confirms the attestation was generated for your application (optional)
+- **Timestamp**: Verifies the attestation timestamp is within an acceptable range of the proof timestamp
+- **SNP report**: Validates the AMD SEV-SNP hardware attestation report
+- **VLEK certificate**: Verifies the certificate chain against AMD's root of trust
+- **Report data**: Confirms the workload and verifier digests match the attestation
 
-- Accepts either a single proof or an array of proofs
-- Returns a boolean indicating if the proof(s) are valid
-- Verifies signatures, witness integrity, and claim data
-- Handles both standalone and blockchain-based proofs
+You can also verify TEE attestation separately using the lower-level `verifyTeeAttestation` function:
+
+```javascript
+import { verifyTeeAttestation } from "@reclaimprotocol/js-sdk";
+
+const isTeeValid = await verifyTeeAttestation(proof, APP_ID);
+if (isTeeValid) {
+  console.log("TEE attestation verified — proof was generated in a secure enclave");
+}
+```
 
 ## Error Handling
 
@@ -628,6 +806,10 @@ try {
 - `ProofSubmissionFailedError`: Proof submission to callback failed
 - `ErrorDuringVerificationError`: An abort error during verification which was caused by the user aborting the verification process or provider's JS script raising a validation error
 
+## Example Repos
+
+- [Reclaim Demo Website](https://github.com/reclaimprotocol/reclaim-demo-website-v3)
+
 ## Next Steps
 
 Explore the [Reclaim Protocol documentation](https://docs.reclaimprotocol.org/) for more advanced features and best practices for integrating the SDK into your production applications.