@reclaimprotocol/js-sdk 5.3.0 → 5.4.1

package/dist/index.d.ts

@@ -51,6 +51,22 @@ interface ExtensionMessage {
 interface WitnessData {
     id: string;
     url: string;
+    claimAttestation?: AttestorClaimAttestation;
+}
+/**
+ * Attestation produced by an attestor running inside a Trusted Execution
+ * Environment. Binds the attestor's signing key (and its signature over
+ * the claim) to a hardware-backed enclave identity.
+ *
+ * Verified by `runAttestorTeeVerification`.
+ */
+interface AttestorClaimAttestation {
+    /** ETH address of the attestor whose enclave produced the attestation. Matches `WitnessData.id`. */
+    attestor_address: string;
+    /** Attestor signature over the claim. Must equal the corresponding entry in `Proof.signatures`. */
+    claim_signature: string;
+    /** Raw attestation report. For GCP Confidential Space, a JWT (header.payload.signature). */
+    attestation_report: string;
 }
 interface ProviderClaimData {
     provider: string;
@@ -299,6 +315,59 @@ interface ResponseRedactionSpec {
     xPath: string;
 }
 
+/**
+ * Result of verifying an attestor TEE attestation.
+ */
+type AttestorTeeVerificationResult = {
+    isVerified: boolean;
+    error?: string;
+    /** sha256 image digest of the attestor container, on success. */
+    imageDigest?: string;
+};
+/**
+ * Validates a GCP Confidential Space attestation JWT produced by an
+ * attestor running in a Confidential Space VM, and asserts that the
+ * attestation binds to the given attestor address.
+ *
+ * The attestor (running inside the TEE) calls the Confidential Space
+ * launcher's attestation endpoint with two nonces:
+ *   - `attestor_public_key:<eth-address>` - binds to the signing key.
+ *   - `attestor_cert_hash:<sha256-hex>`   - binds to the live TLS cert.
+ *
+ * This function only verifies the public-key nonce. The TLS cert hash
+ * binding is informational and not checked here. Callers that need to
+ * pin to a specific attestor image should compare the returned
+ * `imageDigest` against a known-good value.
+ *
+ * The JWT signature is verified by walking the x5c certificate chain
+ * to a pinned GCP Confidential Space Root CA. No outbound network
+ * calls are made.
+ *
+ * Node-only (uses node:crypto). Mirrors the environment restriction in
+ * the existing `verifyTeeAttestation` helper.
+ *
+ * @param report - the raw JWT string (header.payload.signature).
+ * @param expectedAttestorAddress - hex ETH address (0x-prefixed or
+ *   unprefixed) that the attestation should be bound to.
+ */
+declare function verifyAttestorTeeAttestation(report: string, expectedAttestorAddress: string): Promise<AttestorTeeVerificationResult>;
+/**
+ * Configuration for verifying the attestor's TEE attestation on each
+ * witness of the proof.
+ */
+type AttestorTeeAttestationConfig = {
+    /**
+     * Optional allowlist of expected attestor container image digests
+     * (e.g. `"sha256:4906340f..."`). When provided, the attestation's
+     * `submods.container.image_digest` must be in this list.
+     *
+     * Leave undefined to skip image pinning and rely solely on the JWT
+     * chain rooting to the GCP Confidential Space Root CA + nonce
+     * binding to the attestor address.
+     */
+    expectedImageDigests?: 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.
@@ -378,6 +447,20 @@ type VerificationConfig = ValidationConfig & {
      * if TEE attestation data is missing or verification fails.
      */
     teeAttestation?: TeeAttestationConfig;
+    /**
+     * Attestor TEE attestation verification configuration.
+     * When provided, verifies that every witness on every proof has a valid
+     * `claimAttestation` from an attestor running inside a TEE (GCP
+     * Confidential Space).
+     *
+     * Independent of `teeAttestation`, which verifies the verifier-app's
+     * own TEE attestation. Both can be enabled together.
+     *
+     * The result will include `isAttestorTeeAttestationVerified` and
+     * `isVerified` will be false if any witness is missing TEE attestation
+     * data or its verification fails.
+     */
+    attestorTeeAttestation?: AttestorTeeAttestationConfig;
 };
 declare function assertValidProofsByHash(proofs: Proof[], config: ProviderHashRequirementsConfig): void;
 declare function isHttpProviderClaimParams(claimParams: unknown): claimParams is HttpProviderClaimParams;
@@ -703,6 +786,7 @@ type TrustedData = {
 type VerifyProofResultSuccess = {
     isVerified: true;
     isTeeAttestationVerified?: boolean;
+    isAttestorTeeAttestationVerified?: boolean;
     error: undefined;
     data: TrustedData[];
     publicData: any[];
@@ -710,6 +794,7 @@ type VerifyProofResultSuccess = {
 type VerifyProofResultFailure = {
     isVerified: false;
     isTeeAttestationVerified?: boolean;
+    isAttestorTeeAttestationVerified?: boolean;
     error: Error;
     data: [];
     publicData: [];
@@ -899,6 +984,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 +1304,7 @@ declare class ReclaimProofRequest {
      * ```
      */
     getSessionId(): string;
+    private static validateInitOptions;
     private setSignature;
     private generateSignature;
     private clearInterval;
@@ -1463,6 +1590,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 +1719,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 AttestorClaimAttestation, type AttestorTeeVerificationResult, 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, verifyAttestorTeeAttestation, verifyProof, verifyTeeAttestation };