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

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,144 @@ type BeaconState = {
     nextEpochTimestampS: number;
 };
 
+/**
+ * Transforms a raw provider hash requirement specification into a structured configuration for proof validation.
+ * It computes the proof hashes for both required and allowed extra requests to correctly match uploaded proofs.
+ *
+ * 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.
+ * * `ReclaimProofRequest.getProviderHashRequirements()` - An alternative of this function to get the expected hashes for a proof request. The result can be provided in verifyProof function's `config` parameter for proof validation.
+ *
+ * @param spec - The raw provider specifications including required and allowed requests.
+ * @returns A structured configuration containing computed required and allowed hashes for validation.
+ */
+declare function getProviderHashRequirementsFromSpec(spec: ProviderHashRequirementSpec): ProviderHashRequirementsConfig;
+/**
+ * Computes the claim hash for a specific request specification based on its properties.
+ *
+ * @param request - The HTTP request specification (e.g., URL, method, sniffs).
+ * @returns A string representing the hashed proof claim parameters.
+ */
+declare function hashRequestSpec(request: RequestSpec): HashRequirement;
+/**
+ * Represents the raw specification of hash requirements provided by a provider's configuration.
+ */
+interface ProviderHashRequirementSpec {
+    /** List of request specs that can match with HTTP requests to create a proof using Reclaim Protocol */
+    requests: RequestSpec[] | undefined;
+}
+/**
+ * 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 +400,119 @@ 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;
+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): void;
 
 /**
- * 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.
+ *
+ * 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 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
+ * @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 +946,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
      *
@@ -795,6 +1023,79 @@ declare class ReclaimProofRequest {
     getJsonProofResponse(): boolean;
 }
 
+/**
+ * Retrieves a shortened URL for the given URL
+ * @param url - The URL to be shortened
+ * @returns A promise that resolves to the shortened URL, or the original URL if shortening fails
+ */
+declare function getShortenedUrl(url: string): Promise<string>;
+/**
+ * Creates a link with embedded template data
+ * @param templateData - The data to be embedded in the link
+ * @param sharePagePath - The path to the share page (optional)
+ * @returns A promise that resolves to the created link (shortened if possible)
+ */
+declare function createLinkWithTemplateData(templateData: TemplateData, sharePagePath?: string): Promise<string>;
+/**
+ * Retrieves the list of witnesses for a given claim
+ */
+declare function getAttestors(): Promise<WitnessData[]>;
+/**
+ * Recovers the signers' addresses from a signed claim
+ * @param claim - The signed claim object
+ * @param signatures - The signatures associated with the claim
+ * @returns An array of recovered signer addresses
+ */
+declare function recoverSignersOfSignedClaim({ claim, signatures }: SignedClaim): string[];
+/**
+ * Asserts that the proof is verified by checking the signatures and witness information
+ * @param proof - The proof to verify
+ * @param attestors - The attestors to check against
+ * @throws {ProofNotVerifiedError} When the proof is not verified
+ */
+declare function assertVerifiedProof(proof: Proof, attestors: WitnessData[]): Promise<void>;
+
+/**
+ * Initializes a session with the provided parameters
+ * @param providerId - The ID of the provider
+ * @param appId - The ID of the application
+ * @param timestamp - The timestamp of the request
+ * @param signature - The signature for authentication
+ * @returns A promise that resolves to an InitSessionResponse
+ * @throws InitSessionError if the session initialization fails
+ */
+declare function initSession(providerId: string, appId: string, timestamp: string, signature: string, versionNumber?: string): Promise<InitSessionResponse>;
+/**
+ * Updates the status of an existing session
+ * @param sessionId - The ID of the session to update
+ * @param status - The new status of the session
+ * @returns A promise that resolves to the update response
+ * @throws UpdateSessionError if the session update fails
+ */
+declare function updateSession(sessionId: string, status: SessionStatus): Promise<any>;
+/**
+ * Fetches the status URL for a given session ID
+ * @param sessionId - The ID of the session to fetch the status URL for
+ * @returns A promise that resolves to a StatusUrlResponse
+ * @throws StatusUrlError if the status URL fetch fails
+ */
+declare function fetchStatusUrl(sessionId: string): Promise<StatusUrlResponse>;
+declare function fetchProviderConfig(providerId: string, exactProviderVersionString: string): Promise<ProviderConfigResponse>;
+/**
+ * Fetches the provider configuration by the providerId and its version; and constructs the robust hash requirements needed for proof validation.
+ * It resolves both explicitly required HTTP requests and allowed injected requests based on the provider version.
+ *
+ * See also:
+ *
+ * * `ReclaimProofRequest.getProviderHashRequirements()` - An alternative of this function to get the expected hashes for a proof request. 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.
+ *
+ * @param providerId - The unique identifier of the selected provider.
+ * @param exactProviderVersion - The specific version string of the provider configuration to ensure deterministic validation.
+ * @returns A promise that resolves to `ProviderHashRequirementsConfig` representing the expected hashes for proof validation.
+ */
+declare function fetchProviderHashRequirementsBy(providerId: string, exactProviderVersion: string): Promise<ProviderHashRequirementsConfig>;
+
 /**
  * Highly accurate device type detection - returns only 'desktop' or 'mobile'
  * Uses multiple detection methods and scoring system for maximum accuracy
@@ -822,4 +1123,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, type BodySniff, ClaimCreationType, type ClaimID, type ClaimInfo, type CompleteClaimData, type Context, type CreateVerificationRequest, DeviceType, type ExtensionMessage, type HashRequirement, 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 ProviderVersionConfig, RECLAIM_EXTENSION_ACTIONS, type ReclaimFlowLaunchOptions, ReclaimProofRequest, type ReclaimProviderConfig, type RequestSpec, type ResponseMatchSpec, type ResponseRedactionSpec, type SerializableModalOptions, SessionStatus, type SignedClaim, type StartSessionParams, type StatusUrlResponse, type TemplateData, type UpdateSessionResponse, type ValidationConfig, type ValidationConfigWithDisabledValidation, type ValidationConfigWithHash, type VerificationConfig, type WitnessData, assertValidProofsByHash, assertValidateProof, assertVerifiedProof, clearDeviceCache, createLinkWithTemplateData, fetchProviderConfig, fetchProviderHashRequirementsBy, fetchStatusUrl, getAttestors, getDeviceType, getHttpProviderClaimParamsFromProof, getMobileDeviceType, getProviderHashRequirementsFromSpec, getShortenedUrl, hashRequestSpec, initSession, isDesktopDevice, isHttpProviderClaimParams, isMobileDevice, recoverSignersOfSignedClaim, transformForOnchain, updateSession, verifyProof };