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

package/dist/index.d.ts

@@ -266,81 +266,6 @@ interface ResponseRedactionSpec {
     xPath: string;
 }
 
-/**
- * Content validation configuration specifying essential required hashes and optional extra proofs.
- * Used to explicitly validate that a generated proof matches the exact request structure expected.
- */
-type ValidationConfigWithHash = {
-    /**
-     * Array of computed hashes that must be satisfied by the proofs.
-     *
-     * An element can be a `HashRequirement` object or a string that is equivalent to
-     * a `{ value: '<hash>', required: true, multiple: false }` as `HashRequirement`.
-     */
-    hashes: (string | HashRequirement)[];
-};
-/**
- * Content validation configuration specifying the provider id and version used in the verification session that generated the proofs.
- * Used to explicitly validate that a generated proof matches the exact request structure expected.
- *
- * See also:
- *
- * * `ReclaimProofRequest.getProviderVersion()` - With a ReclaimProofRequest object, you can get the provider id & exact version of provider used in verification session.
- */
-interface ValidationConfigWithProviderInformation {
-    /**
-     * The identifier of provider used in verifications that resulted in a proof
-     *
-     * See also:
-     *
-     * * `ReclaimProofRequest.getProviderVersion()` - With a ReclaimProofRequest object, you can get the provider id & exact version of provider used in verification session.
-     **/
-    providerId: string;
-    /**
-     * The exact version of provider used in verifications that resulted in a proof.
-     *
-     * This cannot be a version constaint or version expression. It can be undefined or left blank if proof must be validated with latest version of provider.
-     * Patches for the next provider version are also fetched and hashes from that spec is also be used to compare the hashes from proof.
-     *
-     * See also:
-     *
-     * * `ReclaimProofRequest.getProviderVersion()` - With a ReclaimProofRequest object, you can get the provider id & exact version of provider used in verification session.
-     **/
-    providerVersion?: string;
-    /**
-     * List of allowed pre-release tags.
-     * For example, if you are using AI, provide `['ai']` to allow AI patch versions of the provider.
-     */
-    allowedTags?: string[];
-}
-/**
- * Legacy configuration to completely bypass content validation during verification.
- * Warning: Using this poses a risk as it avoids strictly matching proof parameters to expected hashes.
- */
-interface ValidationConfigWithDisabledValidation {
-    dangerouslyDisableContentValidation: true;
-}
-/**
- * Represents the configuration options applied when validating proof contents, allowing
- * strict hash checking or intentionally skipping validation if flagged.
- */
-type ValidationConfig = ValidationConfigWithHash | ValidationConfigWithProviderInformation | ValidationConfigWithDisabledValidation;
-/**
- * Describes the comprehensive configuration required to initialize the proof verification process.
- * Aligns with `ValidationConfig` options for verifying signatures alongside proof contents.
- */
-type VerificationConfig = ValidationConfig;
-declare function assertValidProofsByHash(proofs: Proof[], config: ProviderHashRequirementsConfig): void;
-declare function isHttpProviderClaimParams(claimParams: unknown): claimParams is HttpProviderClaimParams;
-declare function getHttpProviderClaimParamsFromProof(proof: Proof): HttpProviderClaimParams;
-/**
- * Asserts that the proof is validated by checking the content of proof with with expectations from provider config or hash based on [options]
- * @param proofs - The proofs to validate
- * @param config - The validation config
- * @throws {ProofNotValidatedError} When the proof is not validated
- */
-declare function assertValidateProof(proofs: Proof[], config: VerificationConfig): Promise<void>;
-
 type ClaimID = ProviderClaimData['identifier'];
 type ClaimInfo = Pick<ProviderClaimData, 'context' | 'provider' | 'parameters'>;
 type CompleteClaimData = Pick<ProviderClaimData, 'owner' | 'timestampS' | 'epoch'> & ClaimInfo;
@@ -369,7 +294,6 @@ type CreateVerificationRequest = {
 type StartSessionParams = {
     onSuccess: OnSuccess;
     onError: OnError;
-    verificationConfig?: VerificationConfig;
 };
 type OnSuccess = (proof?: Proof | Proof[]) => void;
 type OnError = (error: Error) => void;
@@ -456,7 +380,7 @@ type ReclaimFlowLaunchOptions = {
      * Verification mode for the flow.
      *
      * - `'portal'`: Opens the portal URL in the browser (remote browser verification).
-     * - `'app'`: Native app flow via the share page. If `useAppClip` is `true`, uses App Clip on iOS.
+     * - `'app'`: Verifier app flow via the share page. If `useAppClip` is `true`, uses App Clip on iOS.
      *
      * Can be set at call time via `triggerReclaimFlow({ verificationMode })` or `getRequestUrl({ verificationMode })`,
      * or at init time via `launchOptions: { verificationMode }`.
@@ -464,7 +388,28 @@ type ReclaimFlowLaunchOptions = {
      * @default 'portal'
      */
     verificationMode?: 'app' | 'portal';
+    /**
+     * Target DOM element to embed the verification flow in an iframe.
+     * When provided, the portal opens inside the element instead of a new tab.
+     * Use `closeEmbeddedFlow()` to remove the iframe programmatically.
+     *
+     * Only applies to portal mode.
+     */
+    target?: HTMLElement;
+};
+/**
+ * Handle returned by `triggerReclaimFlow` to control the launched flow.
+ */
+type FlowHandle = {
+    /** Closes the flow (removes iframe, closes tab, stops polling) */
+    close: () => void;
+    /** The iframe element when using embedded mode, `undefined` otherwise */
+    iframe?: HTMLIFrameElement;
+    /** The tab/window reference when using new tab mode, `undefined` otherwise */
+    tab?: Window | null;
 };
+/** Alias for `FlowHandle` */
+type EmbeddedFlowHandle = FlowHandle;
 type ModalOptions = {
     title?: string;
     description?: string;
@@ -544,7 +489,7 @@ type HttpRedirectionMethod = 'GET' | 'POST';
 /**
  * Options for HTTP redirection.
  *
- * Only supported by In-Browser SDK.
+ * Only supported by Portal flow.
  * On other SDKs, this will be ignored and a GET redirection will be performed with the URL.
  *
  * @since 4.11.0
@@ -597,13 +542,15 @@ type TemplateData = {
     metadata?: Record<string, string>;
     preferredLocale?: ProofRequestOptions['preferredLocale'];
 };
+type TrustedData = {
+    context: Record<string, unknown>;
+    extractedParameters: Record<string, string>;
+};
 type VerifyProofResult = {
     isVerified: boolean;
     isTeeVerified?: boolean;
-    data: {
-        context: Record<string, unknown>;
-        extractedParameters: Record<string, string>;
-    }[];
+    data: TrustedData[];
+    error?: Error;
 };
 type ProviderVersionConfig = {
     major?: number;
@@ -653,6 +600,88 @@ type ProviderHashRequirementsResponse = {
     providerVersionString?: string;
 };
 
+/**
+ * Content validation configuration specifying essential required hashes and optional extra proofs.
+ * Used to explicitly validate that a generated proof matches the exact request structure expected.
+ */
+type ValidationConfigWithHash = {
+    /**
+     * Array of computed hashes that must be satisfied by the proofs.
+     *
+     * An element can be a `HashRequirement` object or a string that is equivalent to
+     * a `{ value: '<hash>', required: true, multiple: false }` as `HashRequirement`.
+     */
+    hashes: (string | HashRequirement)[];
+};
+/**
+ * Content validation configuration specifying the provider id and version used in the verification session that generated the proofs.
+ * Used to explicitly validate that a generated proof matches the exact request structure expected.
+ *
+ * See also:
+ *
+ * * `ReclaimProofRequest.getProviderVersion()` - With a ReclaimProofRequest object, you can get the provider id & exact version of provider used in verification session.
+ */
+interface ValidationConfigWithProviderInformation {
+    /**
+     * The identifier of provider used in verifications that resulted in a proof
+     *
+     * See also:
+     *
+     * * `ReclaimProofRequest.getProviderVersion()` - With a ReclaimProofRequest object, you can get the provider id & exact version of provider used in verification session.
+     **/
+    providerId: string;
+    /**
+     * The exact version of provider used in verifications that resulted in a proof.
+     *
+     * This cannot be a version constaint or version expression. It can be undefined or left blank if proof must be validated with latest version of provider.
+     * Patches for the next provider version are also fetched and hashes from that spec is also be used to compare the hashes from proof.
+     *
+     * See also:
+     *
+     * * `ReclaimProofRequest.getProviderVersion()` - With a ReclaimProofRequest object, you can get the provider id & exact version of provider used in verification session.
+     **/
+    providerVersion?: string;
+    /**
+     * List of allowed pre-release tags.
+     * For example, if you are using AI, provide `['ai']` to allow AI patch versions of the provider.
+     */
+    allowedTags?: string[];
+}
+/**
+ * Legacy configuration to completely bypass content validation during verification.
+ * Warning: Using this poses a risk as it avoids strictly matching proof parameters to expected hashes.
+ */
+interface ValidationConfigWithDisabledValidation {
+    dangerouslyDisableContentValidation: true;
+}
+/**
+ * Represents the configuration options applied when validating proof contents, allowing
+ * strict hash checking or intentionally skipping validation if flagged.
+ */
+type ValidationConfig = ValidationConfigWithHash | ValidationConfigWithProviderInformation | ValidationConfigWithDisabledValidation;
+/**
+ * Describes the comprehensive configuration required to initialize the proof verification process.
+ * Aligns with `ValidationConfig` options for verifying signatures alongside proof contents.
+ */
+type VerificationConfig = ValidationConfig & {
+    /**
+     * If true, verifies TEE (Trusted Execution Environment) attestation included in the proof.
+     * When enabled, the result will include `isTeeVerified` and `isVerified` will be false
+     * if TEE data is missing or TEE verification fails.
+     */
+    verifyTEE?: boolean;
+};
+declare function assertValidProofsByHash(proofs: Proof[], config: ProviderHashRequirementsConfig): void;
+declare function isHttpProviderClaimParams(claimParams: unknown): claimParams is HttpProviderClaimParams;
+declare function getHttpProviderClaimParamsFromProof(proof: Proof): HttpProviderClaimParams;
+/**
+ * Asserts that the proof is validated by checking the content of proof with with expectations from provider config or hash based on [options]
+ * @param proofs - The proofs to validate
+ * @param config - The validation config
+ * @throws {ProofNotValidatedError} When the proof is not validated
+ */
+declare function assertValidateProof(proofs: Proof[], config: VerificationConfig): Promise<void>;
+
 /**
  * Verifies one or more Reclaim proofs by validating signatures, verifying witness information,
  * and performing content validation against the expected configuration.
@@ -665,9 +694,8 @@ type ProviderHashRequirementsResponse = {
  * * 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.
  *
  * @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.
- * @param verifyTEE - If `true`, requires and verifies TEE attestation on the proofs. Verification fails if TEE data is missing or invalid.
- * @returns Verification result with `isVerified`, extracted `data` from each proof, and `isTeeVerified` when `verifyTEE` is `true`
+ * @param config - Verification configuration that specifies required hashes, allowed extra hashes, or disables content validation. Optionally includes `verifyTEE` to require TEE attestation verification.
+ * @returns Verification result with `isVerified`, extracted `data` from each proof, optional `error` on failure, and `isTeeVerified` when `verifyTEE` is enabled.
  *
  * @example
  * ```typescript
@@ -675,7 +703,7 @@ type ProviderHashRequirementsResponse = {
  * const { isVerified, data } = await verifyProof(proof, request.getProviderVersion());
  *
  * // With TEE attestation verification (fails if TEE data is missing or invalid)
- * const { isVerified, isTeeVerified, data } = await verifyProof(proof, request.getProviderVersion(), true);
+ * const { isVerified, isTeeVerified, data } = await verifyProof(proof, { ...request.getProviderVersion(), verifyTEE: true });
  *
  * // Or, by manually providing the details:
  *
@@ -713,7 +741,7 @@ type ProviderHashRequirementsResponse = {
  * });
  * ```
  */
-declare function verifyProof(proofOrProofs: Proof | Proof[], config: VerificationConfig, verifyTEE?: boolean): Promise<VerifyProofResult>;
+declare function verifyProof(proofOrProofs: Proof | Proof[], config: VerificationConfig): Promise<VerifyProofResult>;
 /**
  * Transforms a Reclaim proof into a format suitable for on-chain verification
  *
@@ -756,7 +784,10 @@ declare class ReclaimProofRequest {
     private templateData;
     private extensionID;
     private customSharePageUrl?;
+    private appSharePageUrl;
     private customAppClipUrl?;
+    private portalTab?;
+    private portalIframe?;
     private modalOptions?;
     private modal?;
     private readonly FAILURE_TIMEOUT;
@@ -832,11 +863,11 @@ declare class ReclaimProofRequest {
      *
      * @param url - The URL where users should be redirected after successful proof generation
      * @param method - The redirection method that should be used for redirection. Allowed options: `GET`, and `POST`.
-     * `POST` form redirection is only supported in In-Browser SDK.
+     * `POST` form redirection is only supported in Portal flow.
      * @param body - List of name-value pairs to be sent as the body of the form request.
      * `When `method` is set to `POST`, `body` will be sent with 'application/x-www-form-urlencoded' content type.
      * When `method` is set to `GET`, if `body` is set then `body` will be sent as query parameters.
-     * Sending `body` on redirection is only supported in In-Browser SDK.
+     * Sending `body` on redirection is only supported in Portal flow.
      *
      * @throws {InvalidParamError} When URL is invalid
      *
@@ -889,11 +920,11 @@ declare class ReclaimProofRequest {
      *
      * @param url - The URL where users should be redirected after an error which aborts the verification process
      * @param method - The redirection method that should be used for redirection. Allowed options: `GET`, and `POST`.
-     * `POST` form redirection is only supported in In-Browser SDK.
+     * `POST` form redirection is only supported in Portal flow.
      * @param body - List of name-value pairs to be sent as the body of the form request.
      * When `method` is set to `POST`, `body` will be sent with 'application/x-www-form-urlencoded' content type.
      * When `method` is set to `GET`, if `body` is set then `body` will be sent as query parameters.
-     * Sending `body` on redirection is only supported in In-Browser SDK.
+     * Sending `body` on redirection is only supported in Portal flow.
      * @throws {InvalidParamError} When URL is invalid
      *
      * @example
@@ -1066,7 +1097,24 @@ declare class ReclaimProofRequest {
     private clearInterval;
     private setAttestationContext;
     private applyAttestationContext;
+    private encodeTemplateData;
     private buildSharePageUrl;
+    private openPortalTab;
+    private closePortalTab;
+    private embedPortalIframe;
+    /**
+     * Closes the embedded portal iframe and stops the session polling.
+     *
+     * Call this to programmatically cancel the embedded verification flow
+     * that was started with `triggerReclaimFlow({ target: element })`.
+     * Also called automatically when verification succeeds or fails.
+     *
+     * @example
+     * ```typescript
+     * proofRequest.closeEmbeddedFlow();
+     * ```
+     */
+    closeEmbeddedFlow(): void;
     /**
      * Exports the Reclaim proof verification request as a JSON string
      *
@@ -1109,7 +1157,7 @@ declare class ReclaimProofRequest {
      * // Portal URL (default)
      * const url = await proofRequest.getRequestUrl();
      *
-     * // Native app flow URL
+     * // Verifier app flow URL
      * const url = await proofRequest.getRequestUrl({ verificationMode: 'app' });
      * ```
      */
@@ -1118,8 +1166,9 @@ declare class ReclaimProofRequest {
      * Triggers the appropriate Reclaim verification flow based on device type and configuration.
      *
      * Defaults to portal mode (remote browser verification). Pass `{ verificationMode: 'app' }`
-     * for native app flow via the share page.
+     * for verifier app flow via the share page.
      *
+     * - **Embedded iframe**: Pass `{ target: element }` to embed the portal inside a DOM element instead of a new tab
      * - Desktop: browser extension takes priority in both modes
      * - Desktop portal mode (no extension): opens portal in new tab
      * - Desktop app mode (no extension): shows QR code modal with share page URL
@@ -1127,15 +1176,22 @@ declare class ReclaimProofRequest {
      * - Mobile app mode: opens share page (or App Clip on iOS if `useAppClip` is `true`)
      *
      * @param launchOptions - Optional launch configuration to override default behavior
-     * @returns Promise<void>
+     * @returns Promise<FlowHandle> - Handle to control the flow (close, access iframe)
      * @throws {SignatureNotFoundError} When signature is not set
      *
      * @example
      * ```typescript
-     * // Portal flow (default)
-     * await proofRequest.triggerReclaimFlow();
+     * // Portal flow (default) — opens in new tab
+     * const handle = await proofRequest.triggerReclaimFlow();
+     * handle.tab;   // Window reference to the opened tab
+     * handle.close(); // close tab and stop polling
+     *
+     * // Embed portal in an iframe inside a DOM element
+     * const handle = await proofRequest.triggerReclaimFlow({ target: document.getElementById('reclaim-container') });
+     * handle.iframe; // HTMLIFrameElement reference
+     * handle.close(); // remove iframe and stop polling
      *
-     * // Native app flow
+     * // Verifier app flow
      * await proofRequest.triggerReclaimFlow({ verificationMode: 'app' });
      *
      * // App Clip on iOS (requires useAppClip: true at init)
@@ -1149,7 +1205,7 @@ declare class ReclaimProofRequest {
      * await request.triggerReclaimFlow(); // uses 'app' mode from init
      * ```
      */
-    triggerReclaimFlow(launchOptions?: ReclaimFlowLaunchOptions): Promise<void>;
+    triggerReclaimFlow(launchOptions?: ReclaimFlowLaunchOptions): Promise<FlowHandle>;
     /**
      * Checks if the Reclaim browser extension is installed and available
      *
@@ -1233,7 +1289,7 @@ declare class ReclaimProofRequest {
      * });
      * ```
      */
-    startSession({ onSuccess, onError, verificationConfig }: StartSessionParams): Promise<void>;
+    startSession({ onSuccess, onError }: StartSessionParams): Promise<void>;
     /**
      * Closes the QR code modal if it is currently open
      *
@@ -1326,6 +1382,20 @@ declare function fetchProviderConfigs(providerId: string, exactProviderVersionSt
  */
 declare function verifyTeeAttestation(proof: Proof, expectedApplicationId?: string): Promise<boolean>;
 
+declare const TeeVerificationError: {
+    new (message?: string, innerError?: unknown | undefined): {
+        innerError?: unknown | undefined;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+
 /**
  * Highly accurate device type detection - returns only 'desktop' or 'mobile'
  * Uses multiple detection methods and scoring system for maximum accuracy
@@ -1353,4 +1423,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 ExtensionMessage, 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 ReclaimFlowLaunchOptions, ReclaimProofRequest, type ReclaimProviderConfig, type RequestSpec, type ResponseMatchSpec, type ResponseRedactionSpec, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TeeAttestation, type TemplateData, type UpdateSessionResponse, type ValidationConfig, type ValidationConfigWithDisabledValidation, type ValidationConfigWithHash, type ValidationConfigWithProviderInformation, type VerificationConfig, type VerifyProofResult, type WitnessData, assertValidProofsByHash, assertValidateProof, assertVerifiedProof, clearDeviceCache, createLinkWithTemplateData, fetchProviderConfigs, fetchProviderHashRequirementsBy, fetchStatusUrl, generateSpecsFromRequestSpecTemplate, getAttestors, getDeviceType, getHttpProviderClaimParamsFromProof, getMobileDeviceType, getProviderHashRequirementsFromSpec, getShortenedUrl, hashRequestSpec, initSession, isDesktopDevice, isHttpProviderClaimParams, isMobileDevice, recoverSignersOfSignedClaim, 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 ReclaimFlowLaunchOptions, ReclaimProofRequest, type ReclaimProviderConfig, type RequestSpec, type ResponseMatchSpec, type ResponseRedactionSpec, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TeeAttestation, TeeVerificationError, type TemplateData, type TrustedData, type UpdateSessionResponse, type ValidationConfig, type ValidationConfigWithDisabledValidation, type ValidationConfigWithHash, type ValidationConfigWithProviderInformation, type VerificationConfig, type VerifyProofResult, type WitnessData, assertValidProofsByHash, assertValidateProof, assertVerifiedProof, clearDeviceCache, createLinkWithTemplateData, fetchProviderConfigs, fetchProviderHashRequirementsBy, fetchStatusUrl, generateSpecsFromRequestSpecTemplate, getAttestors, getDeviceType, getHttpProviderClaimParamsFromProof, getMobileDeviceType, getProviderHashRequirementsFromSpec, getShortenedUrl, hashRequestSpec, initSession, isDesktopDevice, isHttpProviderClaimParams, isMobileDevice, recoverSignersOfSignedClaim, takePairsWhereValueIsArray, takeTemplateParametersFromProofs, transformForOnchain, updateSession, verifyProof, verifyTeeAttestation };