@reclaimprotocol/js-sdk 4.15.0 → 5.0.0-dev.0

package/dist/index.d.ts

@@ -37,6 +37,7 @@ interface ProviderClaimData {
 interface Context {
     contextAddress: string;
     contextMessage: string;
+    reclaimSessionId: string;
 }
 interface Beacon {
     getState(epoch?: number): Promise<BeaconState>;
@@ -49,9 +50,117 @@ type BeaconState = {
     nextEpochTimestampS: number;
 };
 
+/**
+ * The structured hash requirements configuration used during proof verification and content validation.
+ */
+type ProviderHashRequirementsConfig = {
+    /**
+     * Array of computed hash requirements that must be satisfied by the proofs.
+     */
+    hashes: HashRequirement[];
+};
+/**
+ * Describes a hash requirement for a proof.
+ */
+type HashRequirement = {
+    /**
+     * The hash value to match
+     */
+    value: string;
+    /**
+     * Whether the hash is required to be present in the proof.
+     * Defaults to true
+     */
+    required?: boolean;
+    /**
+     * Whether the hash can appear multiple times in the proof.
+     * Defaults to false
+     */
+    multiple?: boolean;
+};
+/**
+ * Specific marker interface for intercepted request specifications.
+ */
+interface InterceptorRequestSpec extends RequestSpec {
+}
+/**
+ * Specific marker interface for injected request specifications.
+ */
+interface InjectedRequestSpec extends RequestSpec {
+}
+/**
+ * Represents the properties and validation steps for an HTTP request involved in a Reclaim proof.
+ */
+interface RequestSpec {
+    /** The URL or generic path of the HTTP request */
+    url: string;
+    /** Type or representation of the URL */
+    urlType: string;
+    /** The HTTP method used for the request */
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Identifies and captures the request body if enabled */
+    bodySniff: BodySniff;
+    /** Required matching configurations for the HTTP response */
+    responseMatches: ResponseMatchSpec[];
+    /** Redaction rules applied to the HTTP response before passing to attestors */
+    responseRedactions: ResponseRedactionSpec[];
+    /**
+     * Whether request matching this spec is required and always expected in list of proofs
+     * Defaults to true.
+     */
+    required?: boolean;
+    /**
+     * Whether request matching this spec is allowed to appear multiple times in list of proofs.
+     * Defaults to false.
+     */
+    multiple?: boolean;
+}
+/**
+ * Defines the configuration for identifying/sniffing the request body.
+ */
+interface BodySniff {
+    /** Indicates whether body sniffing is enabled */
+    enabled: boolean;
+    /** The template string used to match or capture the body */
+    template: string;
+}
+/**
+ * Specifies a rule to match against a string in response to validate proof content.
+ */
+interface ResponseMatchSpec {
+    /** If true, the match condition is reversed */
+    invert: boolean | undefined;
+    /** If true, the match condition is optional and won't fail if absent */
+    isOptional: boolean | undefined;
+    /** The matching mechanism, typically regex or simple string containment */
+    type: "regex" | "contains";
+    /** The pattern or value to look for in the response */
+    value: string;
+}
+/**
+ * Specifies redaction rules for obscuring sensitive parts of the response.
+ */
+interface ResponseRedactionSpec {
+    /** Optional hashing method applied to the redacted content (e.g., 'oprf') */
+    hash?: "oprf" | undefined;
+    /** JSON path for locating the value to redact */
+    jsonPath: string;
+    /** RegEx applied to correctly parse and extract/redact value */
+    regex: string;
+    /** XPath for XML/HTML matching configuration */
+    xPath: string;
+}
+
 type ClaimID = ProviderClaimData['identifier'];
 type ClaimInfo = Pick<ProviderClaimData, 'context' | 'provider' | 'parameters'>;
 type CompleteClaimData = Pick<ProviderClaimData, 'owner' | 'timestampS' | 'epoch'> & ClaimInfo;
+interface HttpProviderClaimParams {
+    body: string;
+    method: RequestSpec['method'];
+    responseMatches: ResponseMatchSpec[];
+    responseRedactions: ResponseRedactionSpec[];
+    url: string;
+}
 type SignedClaim = {
     claim: CompleteClaimData;
     signatures: Uint8Array[];
@@ -264,37 +373,109 @@ type TemplateData = {
     metadata?: Record<string, string>;
     preferredLocale?: ProofRequestOptions['preferredLocale'];
 };
+type ProviderVersionConfig = {
+    major?: number;
+    minor?: number;
+    patch?: number;
+    prereleaseTag?: string;
+    prereleaseNumber?: number;
+};
 type StatusUrlResponse = {
     message: string;
     session?: {
         id: string;
         appId: string;
         httpProviderId: string[];
+        providerId: string;
+        providerVersionString: string;
         sessionId: string;
         proofs?: Proof[];
         statusV2: string;
     };
     providerId?: string;
 };
+type ProviderConfigResponse = {
+    message: string;
+    providers?: ReclaimProviderConfig;
+    providerId?: string;
+    providerVersionString?: string;
+};
+interface ReclaimProviderConfig {
+    loginUrl: string;
+    customInjection: string;
+    geoLocation: string;
+    injectionType: string;
+    disableRequestReplay: boolean;
+    verificationType: string;
+    requestData: InterceptorRequestSpec[];
+    allowedInjectedRequestData: InjectedRequestSpec[];
+}
+
+/**
+ * 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)[];
+};
+/**
+ * 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 | 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;
 
 /**
- * Verifies one or more Reclaim proofs by validating signatures and witness information
+ * Verifies one or more Reclaim proofs by validating signatures, verifying witness information,
+ * and performing content validation against the expected configuration.
  *
- * @param proofOrProofs - A single proof object or an array of proof objects to verify
- * @param allowAiWitness - Optional flag to allow AI witness verification. Defaults to false
- * @returns Promise<boolean> - Returns true if all proofs are valid, false otherwise
- * @throws {SignatureNotFoundError} When proof has no signatures
- * @throws {ProofNotVerifiedError} When identifier mismatch occurs
+ * See also:
+ *
+ * * `ReclaimProofRequest.getProviderHashRequirements()` - To get the expected proof hash requirements for a proof request.
+ * * `fetchProviderHashRequirementsBy()` - To get the expected proof hash requirements for a provider version by providing providerId and exactProviderVersionString.
+ * * `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.
+ *
+ * @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.
+ * @returns Promise<boolean> - Returns `true` if all proofs are successfully verified and validated, `false` otherwise.
+ * @throws {ProofNotVerifiedError} When signature validation or identifier mismatch occurs.
+ * @throws {ProofNotValidatedError} When no proofs are provided, when the configuration is missing, or when proof content does not match the expectations set in the config.
  *
  * @example
  * ```typescript
- * const isValid = await verifyProof(proof);
- * const areAllValid = await verifyProof([proof1, proof2, proof3]);
- * const isValidWithAI = await verifyProof(proof, true);
+ * // Validate a single proof against expected hash
+ * const isValid = await verifyProof(proof, { hashes: ['0xAbC...'] });
+ *
+ * // Validate multiple proofs
+ * const areAllValid = await verifyProof([proof1, proof2], {
+ *   hashes: ['0xAbC...', '0xF22..'],
+ * });
+ *
+ * // Validate 1 required proofs, any number of multiple with same hash, and one optional
+ * const areAllValid = await verifyProof([proof1, proof2, sameAsProof2], {
+ *   hashes: ['0xAbC...', { value: '0xF22..', multiple: true }, { value: '0xE33..', required: false }],
+ * });
  * ```
  */
-declare function verifyProof(proofOrProofs: Proof | Proof[], allowAiWitness?: boolean): Promise<boolean>;
-declare function assertValidProof(proofOrProofs: Proof | Proof[], allowAiWitness?: boolean): Promise<void>;
+declare function verifyProof(proofOrProofs: Proof | Proof[], config: VerificationConfig): Promise<boolean>;
 /**
  * Transforms a Reclaim proof into a format suitable for on-chain verification
  *
@@ -728,6 +909,16 @@ declare class ReclaimProofRequest {
     private showQRCodeModal;
     private redirectToInstantApp;
     private redirectToAppClip;
+    /**
+     * Fetches the provider config that was used for this session and returns the hash requirements
+     *
+     * See also:
+     * * `fetchProviderHashRequirementsBy()` - An alternative of this function to get the expected hashes for a provider version by providing providerId and exactProviderVersionString. The result can be provided in verifyProof function's `config` parameter for proof validation.
+     * * `getProviderHashRequirementsFromSpec()` - An alternative of this function to get the expected hashes from a provider spec. The result can be provided in verifyProof function's `config` parameter for proof validation.
+     *
+     * @returns A promise that resolves to a ProviderHashRequirementsConfig
+     */
+    getProviderHashRequirements(): Promise<ProviderHashRequirementsConfig>;
     /**
      * Starts the proof request session and monitors for proof submission
      *
@@ -822,4 +1013,4 @@ declare function isDesktopDevice(): boolean;
  */
 declare function clearDeviceCache(): void;
 
-export { type Beacon, type BeaconState, ClaimCreationType, type ClaimID, type ClaimInfo, type CompleteClaimData, type Context, type CreateVerificationRequest, DeviceType, type ExtensionMessage, type HttpFormEntry, type HttpRedirectionMethod, type HttpRedirectionOptions, type InitSessionResponse, type ModalOptions, type OnError, type OnSuccess, type Proof, type ProofPropertiesJSON, type ProofRequestOptions, type ProviderClaimData, RECLAIM_EXTENSION_ACTIONS, type ReclaimFlowLaunchOptions, ReclaimProofRequest, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TemplateData, type UpdateSessionResponse, type WitnessData, assertValidProof, clearDeviceCache, getDeviceType, getMobileDeviceType, isDesktopDevice, isMobileDevice, transformForOnchain, verifyProof };
+export { type Beacon, type BeaconState, ClaimCreationType, type ClaimID, type ClaimInfo, type CompleteClaimData, type Context, type CreateVerificationRequest, DeviceType, type ExtensionMessage, type HttpFormEntry, type HttpProviderClaimParams, type HttpRedirectionMethod, type HttpRedirectionOptions, type InitSessionResponse, type ModalOptions, type OnError, type OnSuccess, type Proof, type ProofPropertiesJSON, type ProofRequestOptions, type ProviderClaimData, type ProviderConfigResponse, type ProviderVersionConfig, RECLAIM_EXTENSION_ACTIONS, type ReclaimFlowLaunchOptions, ReclaimProofRequest, type ReclaimProviderConfig, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TemplateData, type UpdateSessionResponse, type WitnessData, clearDeviceCache, getDeviceType, getMobileDeviceType, isDesktopDevice, isMobileDevice, transformForOnchain, verifyProof };