@reclaimprotocol/js-sdk 5.1.0 → 5.3.0-dev.1

package/README.md

@@ -37,7 +37,7 @@ Install the Reclaim Protocol SDK and a QR code generator:
 npm install @reclaimprotocol/js-sdk react-qr-code
 ```
 
-**Current SDK Version**: 4.14.0
+**Current SDK Version**: 5.2.0
 
 ## Step 3: Set up your React component
 
@@ -703,31 +703,37 @@ const { isVerified } = await verifyProof(proof, {
 
 ## 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).
+The SDK supports verifying TEE (Trusted Execution Environment) attestations included in proofs. The attestation flow verifies the Google Confidential Computing OIDC token returned by Popcorn's GCP attestor and checks that it is bound to the proof nonce, application identity, and image digests.
 
-### Enabling TEE Attestation
+### Requesting TEE Attestation
 
-To request TEE attestation during proof generation, enable it during initialization:
+TEE attestation is requested by default during proof generation:
 
 ```javascript
-const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
-  acceptTeeAttestation: true,
-});
+const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID);
 ```
 
-### Verifying TEE Attestation
+The request includes the SDK's attestation version so the attestor can continue serving older SDK clients when newer attestation formats are introduced.
+
+To opt out, set `acceptTeeAttestation: false` during initialization.
 
-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`.
+### Verifying TEE Attestation via `verifyProof`
+
+Provide a `teeAttestation` config to require and verify TEE attestation. The application ID is derived automatically from `appSecret`. 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 });
+const { isVerified, isTeeAttestationVerified, data, error } = await verifyProof(proof, {
+  hashes: ['0xAbC...'],
+  teeAttestation: {
+    appSecret: APP_SECRET,
+  },
+});
 
 if (isVerified) {
-  console.log("Proof is fully verified with hardware attestation");
-  console.log("TEE verified:", isTeeVerified);
+  console.log("Proof verified with hardware attestation");
+  console.log("TEE verified:", isTeeAttestationVerified); // always true when teeAttestation is provided and passes
   console.log("Extracted parameters:", data[0].extractedParameters);
 } else if (error instanceof TeeVerificationError) {
   console.log("TEE verification failed:", error.message);
@@ -736,27 +742,54 @@ if (isVerified) {
 }
 ```
 
-When `verifyTEE` is `true`, the result includes `isTeeVerified`. The overall `isVerified` will be `false` if TEE data is missing or TEE verification fails.
+The result includes `isTeeAttestationVerified`. It is `true` when `teeAttestation` was provided and verification passed, and `undefined` when `teeAttestation` was not requested.
 
-The TEE verification validates:
+### What TEE verification checks
+
+- **Application binding**: Derives the application ID from `appSecret` and confirms the attestation was generated for your application
 - **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
+- **Session and timestamp binding**: Verifies the nonce metadata matches the proof session and is within the allowed skew
+- **OIDC token signature**: Validates the Google Confidential Computing attestation JWT against Google's JWKS (responses are cached for 5 minutes)
+- **Platform claims**: Confirms the expected GCP confidential-computing claims (issuer, secure boot, hardware model, GCE instance metadata)
+- **Digest binding**: Confirms the workload and verifier image digests are present in the attestation token nonce list
+
+### Standalone `verifyTeeAttestation`
 
-You can also verify TEE attestation separately using the lower-level `verifyTeeAttestation` function:
+You can verify TEE attestation for a single proof without running full proof verification:
 
 ```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");
+const { isVerified, error } = await verifyTeeAttestation(proof, APP_SECRET);
+if (isVerified) {
+  console.log("TEE attestation verified");
+} else {
+  console.log("TEE verification failed:", error);
 }
 ```
 
+`appSecret` is your Reclaim application secret. The application ID is derived from it automatically.
+
+### Browser vs Server Verification
+
+TEE verification fetches Google's OIDC metadata and JWKS endpoints. In browser-only environments this may fail due to cross-origin restrictions.
+
+For web apps, verify TEE attestations on the server:
+
+```javascript
+const response = await fetch('/api/verify-tee', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ proofs }),
+});
+
+const { results } = await response.json();
+console.log(results);
+```
+
+The server route should read the app secret from environment variables only (never accept it from the client request body). See the example app for a reference implementation:
+- `example/src/app/api/verify-tee/route.ts`
+
 ## Error Handling
 
 The SDK provides specific error types for different failure scenarios. Here's how to handle them:

package/dist/index.d.ts

@@ -1,10 +1,26 @@
+declare const SUPPORTED_TEE_ATTESTATION_VERSIONS: readonly ["v2", "v3"];
+type TeeAttestationVersion = typeof SUPPORTED_TEE_ATTESTATION_VERSIONS[number];
 interface TeeAttestation {
-    workload_digest: string;
-    verifier_digest: string;
+    proof_version: TeeAttestationVersion;
+    tee_provider: string;
+    tee_technology: string;
     nonce: string;
-    snp_report: string;
-    vlek_cert: string;
     timestamp: string;
+    workload: {
+        container_name: string;
+        image_digest: string;
+    };
+    verifier: {
+        container_name: string;
+        image_digest: string;
+    };
+    attestation: {
+        token: string;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
 }
 interface Proof {
     identifier: string;
@@ -56,6 +72,7 @@ interface Context {
         applicationId: string;
         sessionId: string;
         timestamp: string;
+        attestationVersion?: TeeAttestationVersion;
     };
 }
 interface Beacon {
@@ -345,13 +362,22 @@ type ValidationConfig = ValidationConfigWithHash | ValidationConfigWithProviderI
  * Describes the comprehensive configuration required to initialize the proof verification process.
  * Aligns with `ValidationConfig` options for verifying signatures alongside proof contents.
  */
+type TeeAttestationConfig = {
+    /**
+     * Your application secret (Ethereum private key).
+     * Used to recompute the TEE attestation nonce and to derive the application ID
+     * for binding the attestation to your application.
+     */
+    appSecret: string;
+};
 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.
+     * TEE attestation verification configuration.
+     * When provided, verifies the TEE attestation included in the proof.
+     * The result will include `isTeeAttestationVerified` and `isVerified` will be false
+     * if TEE attestation data is missing or verification fails.
      */
-    verifyTEE?: boolean;
+    teeAttestation?: TeeAttestationConfig;
 };
 declare function assertValidProofsByHash(proofs: Proof[], config: ProviderHashRequirementsConfig): void;
 declare function isHttpProviderClaimParams(claimParams: unknown): claimParams is HttpProviderClaimParams;
@@ -480,7 +506,9 @@ type ProofRequestOptions = {
      */
     metadata?: Record<string, string>;
     /**
-     * If true, generates a TEE attestation nonce during session initialization and expects a TEE attestation in the proof.
+     * Generates a TEE attestation nonce during session initialization and expects a TEE attestation in the proof.
+     *
+     * @default true
      */
     acceptTeeAttestation?: boolean;
 };
@@ -665,6 +693,8 @@ type TemplateData = {
     canAutoSubmit?: boolean;
     metadata?: Record<string, string>;
     preferredLocale?: ProofRequestOptions['preferredLocale'];
+    acceptTeeAttestation?: boolean;
+    teeAttestationVersion?: TeeAttestationVersion;
 };
 type TrustedData = {
     context: Record<string, unknown>;
@@ -672,14 +702,14 @@ type TrustedData = {
 };
 type VerifyProofResultSuccess = {
     isVerified: true;
-    isTeeVerified?: boolean;
+    isTeeAttestationVerified?: boolean;
     error: undefined;
     data: TrustedData[];
     publicData: any[];
 };
 type VerifyProofResultFailure = {
     isVerified: false;
-    isTeeVerified?: boolean;
+    isTeeAttestationVerified?: boolean;
     error: Error;
     data: [];
     publicData: [];
@@ -743,8 +773,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. 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.
+ * @param config - Verification configuration that specifies required hashes, allowed extra hashes, or disables content validation. Optionally includes `teeAttestation` to require TEE attestation verification.
+ * @returns Verification result with `isVerified`, `isTeeAttestationVerified` (always boolean), extracted `data` from each proof, and optional `error` on failure. The application ID is derived from `appSecret` automatically.
  *
  * @example
  * ```typescript
@@ -752,7 +782,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(), verifyTEE: true });
+ * const { isVerified, isTeeAttestationVerified, data } = await verifyProof(proof, { ...request.getProviderVersion(), teeAttestation: { appSecret: APP_SECRET } });
  *
  * // Or, by manually providing the details:
  *
@@ -1469,11 +1499,30 @@ declare function hashProofClaimParams(params: HttpProviderClaimParams): string |
  */
 declare function getProviderParamsAsCanonicalizedString(params: HttpProviderClaimParams): string[];
 
+type TeeVerificationResult = {
+    isVerified: boolean;
+    error?: string;
+};
 /**
  * Validates the hardware TEE attestation included in the proof.
- * Throws an error if the attestation is invalid or compromised.
+ * Derives the application ID from `appSecret` and verifies the attestation
+ * was generated for your application.
+ * Returns a result object with `isVerified` and an optional `error` message.
+ *
+ * @param proof - The proof containing TEE attestation data
+ * @param appSecret - Your application secret (Ethereum private key). Used to
+ *   derive the application ID and recompute the attestation nonce.
+ */
+declare function verifyTeeAttestation(proof: Proof, appSecret: string): Promise<TeeVerificationResult>;
+/**
+ * Verifies TEE attestation for all proofs.
+ * Throws `TeeVerificationError` if any proof is missing TEE data or fails verification.
+ *
+ * @param proofs - The proofs to verify
+ * @param config - TEE attestation configuration containing the app secret
+ * @throws {TeeVerificationError} When TEE data is missing or verification fails
  */
-declare function verifyTeeAttestation(proof: Proof, expectedApplicationId?: string): Promise<boolean>;
+declare function runTeeVerification(proofs: Proof[], config: TeeAttestationConfig): Promise<void>;
 
 declare const TeeVerificationError: {
     new (message?: string, innerError?: unknown | undefined): {
@@ -1516,4 +1565,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, 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 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, 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 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 };