@reclaimprotocol/client 0.1.27 → 0.1.29

package/lib/verification-clients.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Stable names for the Verification Clients seeded by Builder.
+ *
+ * A name identifies a registry record; session creation still selects a
+ * client with that deployment's exact registered URL.
+ */
+export declare const KNOWN_VERIFICATION_CLIENTS: {
+    readonly builder: "builder";
+    readonly portals: "portals";
+    readonly verifierApp: "verifier-app";
+    readonly inAppSdk: "inapp-sdk";
+    readonly reclaimBrowserExtension: "reclaim-browser-extension";
+    readonly zkFetch: "zkfetch";
+};
+export type KnownVerificationClientName = typeof KNOWN_VERIFICATION_CLIENTS[keyof typeof KNOWN_VERIFICATION_CLIENTS];
+/** Deployment-specific registered URLs keyed by a known client name. */
+export type KnownVerificationClientUrlMap = Partial<Record<KnownVerificationClientName, string>>;

package/lib/verification-clients.js

@@ -0,0 +1,14 @@
+/**
+ * Stable names for the Verification Clients seeded by Builder.
+ *
+ * A name identifies a registry record; session creation still selects a
+ * client with that deployment's exact registered URL.
+ */
+export const KNOWN_VERIFICATION_CLIENTS = {
+    builder: 'builder',
+    portals: 'portals',
+    verifierApp: 'verifier-app',
+    inAppSdk: 'inapp-sdk',
+    reclaimBrowserExtension: 'reclaim-browser-extension',
+    zkFetch: 'zkfetch',
+};

package/lib/verify-attestor-tee.d.ts

@@ -0,0 +1,76 @@
+import type { LegacyProof as Proof } from './proof-types.ts';
+/**
+ * Result of verifying an attestor TEE attestation.
+ */
+export 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.
+ */
+export declare function verifyAttestorTeeAttestation(report: string, expectedAttestorAddress: string): Promise<AttestorTeeVerificationResult>;
+/**
+ * Configuration for verifying the attestor's TEE attestation on each
+ * witness of the proof.
+ */
+export 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[];
+};
+/**
+ * Verifies the attestor's TEE attestation for every witness of every
+ * provided proof. Throws `AttestorTeeVerificationError` on the first
+ * failure.
+ *
+ * Each witness must carry a `claimAttestation`. For each one, this:
+ *   1. Asserts `attestor_address` matches `witness.id`.
+ *   2. Asserts `claim_signature` is present in `proof.signatures`.
+ *   3. Recovers the signer of `claim_signature` from the claim data and
+ *      asserts it equals `witness.id` (binds the signature to the
+ *      attestor that the TEE attestation will cover).
+ *   4. Calls `verifyAttestorTeeAttestation` to validate the JWT against
+ *      the pinned GCP Confidential Space Root CA and the attestor-key
+ *      nonce.
+ *   5. If `expectedImageDigests` is provided, asserts the attestation's
+ *      container image digest is in the allowlist.
+ *
+ * Node-only (uses node:crypto), like `verifyTeeAttestation`.
+ *
+ * @param proofs - The proofs to verify.
+ * @param config - Optional config; see {@link AttestorTeeAttestationConfig}.
+ */
+export declare function runAttestorTeeVerification(proofs: Proof[], config?: AttestorTeeAttestationConfig): Promise<void>;

package/lib/verify-attestor-tee.js

@@ -0,0 +1,243 @@
+import { createSignDataForClaim } from '@reclaimprotocol/attestor-core';
+/* eslint-disable @stylistic/max-len */
+import crypto, { X509Certificate } from 'node:crypto';
+import { recoverEip191Address } from "./eip191.js";
+import { ATTESTOR_NONCE_PATTERN, GCP_CONFIDENTIAL_SPACE_ISSUER, GCP_CONFIDENTIAL_SPACE_ROOT_CA, } from "./proof-trust-constants.js";
+import { legacyErrorClass } from "./proof-verification-error.js";
+const AttestorTeeVerificationError = legacyErrorClass('AttestorTeeVerificationError');
+const BROWSER_ENVIRONMENT_ERROR = 'Attestor TEE attestation verification is only supported in non-browser environments. Run verifyAttestorTeeAttestation on your server or API route.';
+function isBrowserEnvironment() {
+    if ('window' in globalThis || 'document' in globalThis) {
+        return true;
+    }
+    if (typeof navigator !== 'undefined' && typeof process === 'undefined') {
+        return true;
+    }
+    const workerGlobalScope = globalThis.WorkerGlobalScope;
+    if (typeof workerGlobalScope === 'function' &&
+        globalThis instanceof workerGlobalScope) {
+        return true;
+    }
+    return false;
+}
+function assertNonBrowserEnvironment() {
+    if (isBrowserEnvironment()) {
+        throw new Error(BROWSER_ENVIRONMENT_ERROR);
+    }
+}
+const TOKEN_CLOCK_SKEW_S = 60;
+function decodeBase64Url(input) {
+    const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+    return Buffer.from(padded, 'base64');
+}
+function normalizeAddress(address) {
+    return address.trim().toLowerCase().replace(/^0x/, '');
+}
+/**
+ * Walks the x5c certificate chain (leaf first) and verifies each link
+ * up to the pinned GCP Confidential Space Root CA. Returns the leaf
+ * certificate's public key on success.
+ */
+function verifyX5cChain(x5cChain) {
+    if (!x5cChain || x5cChain.length === 0) {
+        throw new Error('Empty x5c certificate chain');
+    }
+    const certs = x5cChain.map((b64) => new X509Certificate(`-----BEGIN CERTIFICATE-----\n${b64}\n-----END CERTIFICATE-----`));
+    const root = new X509Certificate(GCP_CONFIDENTIAL_SPACE_ROOT_CA);
+    for (let i = 0; i < certs.length - 1; i++) {
+        if (!certs[i].verify(certs[i + 1].publicKey)) {
+            throw new Error(`Certificate chain verification failed at level ${i}`);
+        }
+    }
+    const top = certs[certs.length - 1];
+    if (!top.verify(root.publicKey)) {
+        throw new Error('Certificate chain does not root to GCP Confidential Space Root CA');
+    }
+    return certs[0].publicKey;
+}
+/**
+ * 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.
+ */
+export async function verifyAttestorTeeAttestation(report, expectedAttestorAddress) {
+    try {
+        assertNonBrowserEnvironment();
+        if (!report || typeof report !== 'string') {
+            throw new Error('attestation report is empty or not a string');
+        }
+        if (!expectedAttestorAddress || typeof expectedAttestorAddress !== 'string') {
+            throw new Error('expectedAttestorAddress is required');
+        }
+        const parts = report.split('.');
+        if (parts.length !== 3) {
+            throw new Error('attestation report is not a JWT (expected 3 parts)');
+        }
+        const [headerB64, payloadB64, signatureB64] = parts;
+        const header = JSON.parse(decodeBase64Url(headerB64).toString('utf8'));
+        const payload = JSON.parse(decodeBase64Url(payloadB64).toString('utf8'));
+        if (header.alg !== 'RS256') {
+            throw new Error(`unexpected signing algorithm: ${header.alg}`);
+        }
+        if (!Array.isArray(header.x5c) || header.x5c.length === 0) {
+            throw new Error('attestation report is missing x5c certificate chain');
+        }
+        if (payload.iss !== GCP_CONFIDENTIAL_SPACE_ISSUER) {
+            throw new Error(`unexpected issuer: ${payload.iss}`);
+        }
+        const now = Math.floor(Date.now() / 1000);
+        if (typeof payload.nbf === 'number' && now + TOKEN_CLOCK_SKEW_S < payload.nbf) {
+            throw new Error(`attestation not yet valid (nbf=${payload.nbf})`);
+        }
+        if (typeof payload.exp === 'number' && now - TOKEN_CLOCK_SKEW_S > payload.exp) {
+            throw new Error(`attestation expired (exp=${payload.exp})`);
+        }
+        if (typeof payload.iat === 'number' && payload.iat > now + TOKEN_CLOCK_SKEW_S) {
+            throw new Error(`attestation issued in future (iat=${payload.iat})`);
+        }
+        const publicKey = verifyX5cChain(header.x5c);
+        const verifier = crypto.createVerify('RSA-SHA256');
+        verifier.update(`${headerB64}.${payloadB64}`);
+        if (!verifier.verify(publicKey, new Uint8Array(decodeBase64Url(signatureB64)))) {
+            throw new Error('attestation signature verification failed');
+        }
+        if (!payload.eat_nonce) {
+            throw new Error('eat_nonce claim is missing');
+        }
+        const nonces = Array.isArray(payload.eat_nonce)
+            ? payload.eat_nonce
+            : [payload.eat_nonce];
+        let attestedAddress;
+        for (const n of nonces) {
+            const m = typeof n === 'string' ? n.match(ATTESTOR_NONCE_PATTERN) : null;
+            if (m) {
+                attestedAddress = m[1];
+                break;
+            }
+        }
+        if (!attestedAddress) {
+            throw new Error(`attestor_public_key nonce not found in eat_nonce: ${JSON.stringify(payload.eat_nonce)}`);
+        }
+        if (normalizeAddress(attestedAddress) !== normalizeAddress(expectedAttestorAddress)) {
+            throw new Error(`attestor address mismatch: attestation binds to 0x${attestedAddress.toLowerCase()}, ` +
+                `expected ${expectedAttestorAddress}`);
+        }
+        const imageDigest = payload.submods?.container?.image_digest
+            ?? payload.google?.compute_engine?.image_digest;
+        return { isVerified: true, imageDigest };
+    }
+    catch (error) {
+        return {
+            isVerified: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function normalizeAttestorAddress(address) {
+    return address.trim().toLowerCase();
+}
+function normalizeSignature(sig) {
+    return sig.trim().toLowerCase();
+}
+async function verifyAttestorTeeForProof(proof, config) {
+    if (!proof.witnesses || proof.witnesses.length === 0) {
+        throw new AttestorTeeVerificationError('Proof has no witnesses');
+    }
+    const expectedDigests = config.expectedImageDigests?.map(d => d.trim());
+    const proofSignatures = new Set((proof.signatures || []).map(normalizeSignature));
+    const claimSignData = createSignDataForClaim(proof.claimData);
+    for (const witness of proof.witnesses) {
+        const att = witness.claimAttestation;
+        if (!att) {
+            throw new AttestorTeeVerificationError(`Witness ${witness.id} is missing claimAttestation`);
+        }
+        if (normalizeAttestorAddress(att.attestor_address) !== normalizeAttestorAddress(witness.id)) {
+            throw new AttestorTeeVerificationError(`claimAttestation.attestor_address ${att.attestor_address} does not match witness id ${witness.id}`);
+        }
+        if (!proofSignatures.has(normalizeSignature(att.claim_signature))) {
+            throw new AttestorTeeVerificationError(`claimAttestation.claim_signature for witness ${witness.id} is not present in proof.signatures`);
+        }
+        let recoveredSigner;
+        try {
+            recoveredSigner = recoverEip191Address(claimSignData, att.claim_signature);
+        }
+        catch (error) {
+            throw new AttestorTeeVerificationError(`Failed to recover signer from claimAttestation.claim_signature for witness ${witness.id}`, error);
+        }
+        if (normalizeAttestorAddress(recoveredSigner) !== normalizeAttestorAddress(witness.id)) {
+            throw new AttestorTeeVerificationError(`claim_signature recovers to ${recoveredSigner}, expected attestor ${witness.id}`);
+        }
+        const result = await verifyAttestorTeeAttestation(att.attestation_report, witness.id);
+        if (!result.isVerified) {
+            throw new AttestorTeeVerificationError(`Attestor TEE attestation verification failed for witness ${witness.id}: ${result.error}`);
+        }
+        if (expectedDigests && expectedDigests.length > 0) {
+            if (!result.imageDigest) {
+                throw new AttestorTeeVerificationError(`Attestor TEE attestation for witness ${witness.id} did not expose an image digest to check against expectedImageDigests`);
+            }
+            if (!expectedDigests.includes(result.imageDigest)) {
+                throw new AttestorTeeVerificationError(`Attestor image digest ${result.imageDigest} for witness ${witness.id} is not in expectedImageDigests`);
+            }
+        }
+    }
+}
+/**
+ * Verifies the attestor's TEE attestation for every witness of every
+ * provided proof. Throws `AttestorTeeVerificationError` on the first
+ * failure.
+ *
+ * Each witness must carry a `claimAttestation`. For each one, this:
+ *   1. Asserts `attestor_address` matches `witness.id`.
+ *   2. Asserts `claim_signature` is present in `proof.signatures`.
+ *   3. Recovers the signer of `claim_signature` from the claim data and
+ *      asserts it equals `witness.id` (binds the signature to the
+ *      attestor that the TEE attestation will cover).
+ *   4. Calls `verifyAttestorTeeAttestation` to validate the JWT against
+ *      the pinned GCP Confidential Space Root CA and the attestor-key
+ *      nonce.
+ *   5. If `expectedImageDigests` is provided, asserts the attestation's
+ *      container image digest is in the allowlist.
+ *
+ * Node-only (uses node:crypto), like `verifyTeeAttestation`.
+ *
+ * @param proofs - The proofs to verify.
+ * @param config - Optional config; see {@link AttestorTeeAttestationConfig}.
+ */
+export async function runAttestorTeeVerification(proofs, config = {}) {
+    if (!proofs || proofs.length === 0) {
+        throw new AttestorTeeVerificationError('No proofs provided for attestor TEE verification');
+    }
+    try {
+        for (const proof of proofs) {
+            await verifyAttestorTeeForProof(proof, config);
+        }
+    }
+    catch (error) {
+        if (error instanceof AttestorTeeVerificationError) {
+            throw error;
+        }
+        throw new AttestorTeeVerificationError('Attestor TEE attestation verification failed', error);
+    }
+}

package/lib/verify-tee.d.ts

@@ -0,0 +1,32 @@
+import type { LegacyProof as Proof } from './proof-types.ts';
+export interface TeeAttestationConfig {
+    appSecret: string;
+}
+export type TeeVerificationResult = {
+    isVerified: boolean;
+    error?: string;
+};
+/**
+ * Validates the hardware TEE attestation included in the proof.
+ * 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.
+ *
+ * This check is stateless and does not protect against replay of a previously
+ * valid proof. Callers must enforce session matching and dedup `sessionId` on
+ * their server. See the README's "Replay Protection" section.
+ *
+ * @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.
+ */
+export 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
+ */
+export declare function runTeeVerification(proofs: Proof[], config: TeeAttestationConfig): Promise<void>;