@reclaimprotocol/client 0.1.29 → 0.1.32

package/lib/reclaim.js

@@ -1,26 +1,25 @@
 import { ReclaimClient } from "./client.js";
 import { loadDecryptionKey, } from "./enckeys.js";
-import { isProblemError } from "./errors.js";
 import { proofHashesFromBuilderRecipe } from "./proof-recipe.js";
 import { decryptCallback, verifyResultFull, } from "./result.js";
 import { createBuilderTeeBinding, } from "./tee-binding.js";
-/** Terminal lifecycle events selected by default for callback subscriptions. */
-export const TERMINAL_EVENTS = [
-    'verification_success',
-    'verification_rejected',
-    'verification_error',
-    'verification_cancelled',
-    'session_expired',
-];
 const SIGNED_RESULT_EVENTS = [
     'verification_success',
     'verification_rejected',
     'verification_error',
 ];
-export function createReclaim(config) {
+export const ReclaimVerification = Object.freeze({
+    create: createReclaimVerification,
+    import: importReclaimVerification,
+});
+function importReclaimVerification(serialized, config) {
+    const state = parseReclaimVerificationState(serialized);
+    return createReclaimVerification({ ...config, baseUrl: state.baseUrl });
+}
+function createReclaimVerification(config) {
     if (!config?.orgSecret) {
-        throw new Error('createReclaim requires an org secret — pass '
-            + 'createReclaim({ orgSecret: <rorg_… org secret> })');
+        throw new Error('ReclaimVerification.create requires an org secret — pass '
+            + 'ReclaimVerification.create({ orgSecret: <rorg_… org secret> })');
     }
     const client = new ReclaimClient({
         baseUrl: config.baseUrl,
@@ -32,99 +31,42 @@ export function createReclaim(config) {
     // plaintext-only consumers never touch the loader.
     const resolveKey = (input) => (input === undefined ? undefined : loadDecryptionKey(input));
     return {
+        export() {
+            return JSON.stringify({
+                version: 1,
+                baseUrl: client.baseUrl,
+            });
+        },
         api: client.call.bind(client),
         sessions: {
-            async create(input) {
-                const { teeAttestation, ...request } = input;
-                const body = {
-                    ...request,
-                    verificationClientUrl: request.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
-                };
-                const { data } = await client.call('CreateVerificationSession', {
-                    body,
-                });
-                return teeAttestation
-                    ? bindTeeNonce(data, teeAttestation)
-                    : data;
-            },
-            async bindTeeNonce(sessionId, input) {
+            create: createSession,
+            async bindTeeNonce(reclaimSessionId, input) {
                 const { data } = await client.call('GetVerificationSession', {
-                    params: { sessionId },
+                    params: { sessionId: reclaimSessionId },
                 });
                 return bindTeeNonce(data, input);
             },
-            async get(sessionId) {
+            async get(reclaimSessionId) {
                 const { data } = await client.call('GetVerificationSession', {
-                    params: { sessionId },
+                    params: { sessionId: reclaimSessionId },
                 });
                 return data;
             },
-            async listEvents(sessionId) {
+            async listEvents(reclaimSessionId) {
                 const { data } = await client.call('ListVerificationEvents', {
-                    params: { sessionId },
+                    params: { sessionId: reclaimSessionId },
                 });
                 return data.items;
             },
         },
-        callbacks: {
-            async register(input) {
-                const events = input.events ?? [...TERMINAL_EVENTS];
-                const { data } = await client.call('CreateCallbackSubscription', {
-                    body: { callbackUrl: input.callbackUrl, events },
-                });
-                return data;
-            },
-            async list() {
-                const { data } = await client.call('ListCallbackSubscriptions');
-                return data.items;
-            },
-            async remove(subscriptionId) {
-                await client.call('DeleteCallbackSubscription', {
-                    params: { subscriptionId },
-                });
-            },
-        },
-        keypair: {
-            async set(orgId, input) {
-                // Forward the eth public key as given (hex or JWK); the API stores
-                // the secp256k1 JWK + derived address.
-                const body = {
-                    ...(input.publicKeyJwk
-                        ? { publicKeyJwk: input.publicKeyJwk }
-                        : { publicKey: input.publicKey }),
-                    canEncryptResult: input.canEncryptResult ?? false,
-                    ...(input.label ? { label: input.label } : {}),
-                };
-                const { data } = await client.call('SetOrgKeypair', {
-                    params: { orgId },
-                    body,
-                });
-                return data;
-            },
-            async get(orgId) {
-                try {
-                    const { data } = await client.call('GetOrgKeypair', {
-                        params: { orgId },
-                    });
-                    return data;
-                }
-                catch (err) {
-                    // 404 ⇒ keyless org (plaintext delivery).
-                    if (isNotFound(err)) {
-                        return undefined;
-                    }
-                    throw err;
-                }
-            },
-        },
         results: {
-            async decrypt(body, credential) {
-                return decryptCallback(resolveKey(credential), body);
+            async decrypt(body, orgEthPrivateKey) {
+                return decryptCallback(resolveKey(orgEthPrivateKey), body);
             },
             verify(jws, opts) {
                 return verifyResultFull(jws, {
                     fetchImpl: config.fetch,
-                    ...withRegisteredIssuer(opts),
+                    ...withBuilderTrust(opts),
                 });
             },
             async receive(body, opts) {
@@ -145,24 +87,44 @@ export function createReclaim(config) {
                         };
                     }
                 }
-                const { credential, ...verifyOpts } = opts ?? {};
-                const key = resolveKey(credential);
+                const { orgEthPrivateKey, ...verifyOpts } = opts ?? {};
+                const key = resolveKey(orgEthPrivateKey);
                 const jws = await decryptCallback(key, body);
                 const result = await verifyResultFull(jws, {
                     fetchImpl: config.fetch,
-                    ...withRegisteredIssuer(verifyOpts),
+                    ...withBuilderTrust({ ...verifyOpts, orgEthPrivateKey }),
                 });
                 return { kind: 'result', result };
             },
         },
+        flow: Object.assign((session) => makeSessionFlow(session), {
+            async create(input) {
+                return makeSessionFlow(await createSession(input));
+            },
+        }),
     };
+    async function createSession(input) {
+        const { orgEthPrivateKey, teeNonceMode, ...request } = input;
+        const body = {
+            ...request,
+        };
+        const { data } = await client.call('CreateVerificationSession', {
+            body,
+        });
+        return orgEthPrivateKey
+            ? bindTeeNonce(data, {
+                orgEthPrivateKey,
+                teeNonceMode,
+            })
+            : data;
+    }
     async function bindTeeNonce(session, input) {
         const binding = createBuilderTeeBinding({
             organizationId: session.orgId,
-            organizationVerificationPrivateKey: input.appSecret,
+            organizationVerificationPrivateKey: input.orgEthPrivateKey,
             sessionId: session.id,
             timestamp: input.timestamp ?? Date.now().toString(),
-            nonceMode: input.nonceMode,
+            nonceMode: input.teeNonceMode,
         });
         const { data } = await client.call('BindVerificationSessionTeeNonce', {
             params: { sessionId: session.id },
@@ -202,10 +164,9 @@ export function createReclaim(config) {
                 }, proofs),
             }];
     }
-    function withRegisteredIssuer(opts = {}) {
-        const sessionId = opts.sessionId ?? opts.expectedReclaimSessionId;
-        const requestedProofValidation = opts.proofValidation
-            ?? opts.proofVerification;
+    function withBuilderTrust(opts = {}) {
+        const reclaimSessionId = opts.reclaimSessionId;
+        const requestedProofValidation = opts.proofValidation;
         const resolvedOpts = {
             ...opts,
             proofValidation: {
@@ -213,51 +174,30 @@ export function createReclaim(config) {
                 resolveProvider: requestedProofValidation?.resolveProvider
                     ?? resolvedProvider,
             },
-            ...(sessionId && !opts.resolveSession && !opts.proofRecipes
+            ...(reclaimSessionId && !opts.resolveSession && !opts.proofRecipes
                 ? { resolveSession: resolvedSession }
                 : {}),
         };
         if (opts.signerPublicKey
-            || opts.issuer
-            || opts.trustedIssuer
-            || opts.issuers?.length
             || opts.trustedIssuers?.length
-            || opts.resolveIssuers
-            || opts.issuerResolver
-            || opts.issuersByVerificationClientId
-            || opts.jwksUrl
-            || opts.jwksUrlsByVerificationClientId
-            || opts.resolveJwksUrl) {
+            || opts.jwksUrl) {
             return resolvedOpts;
         }
         return {
             ...resolvedOpts,
-            resolveIssuers: async (verificationClientId) => {
-                const session = await registeredClient(verificationClientId);
-                if (!session) {
-                    return [];
-                }
-                return session.verificationClientIssuer
-                    ? [session.verificationClientIssuer]
-                    : [];
-            },
-            resolveJwksUrl: async (verificationClientId) => {
-                const session = await registeredClient(verificationClientId);
-                return session?.verificationClientJwksUrl;
-            },
+            trustedIssuers: [client.baseUrl],
+            jwksUrl: `${client.baseUrl}/.well-known/jwks.json`,
         };
-        async function registeredClient(verificationClientId) {
-            if (!sessionId) {
-                return undefined;
-            }
-            const { data: session } = await client.call('GetVerificationSession', { params: { sessionId } });
-            if (session.verificationClientId !== verificationClientId) {
-                return undefined;
-            }
-            return session;
-        }
     }
 }
+function makeSessionFlow(session) {
+    return {
+        session,
+        async getUrl() {
+            return session.verificationUrl;
+        },
+    };
+}
 function canonicalVersion(version) {
     const base = `${version.major}.${version.minor}.${version.patch}`;
     return version.branch
@@ -279,7 +219,16 @@ function parseEventData(data) {
         return {};
     }
 }
-/** True for a `404` thrown by {@link ReclaimClient.call}. */
-function isNotFound(err) {
-    return isProblemError(err) && err.output.statusCode === 404;
+function parseReclaimVerificationState(serialized) {
+    const state = JSON.parse(serialized);
+    if (!state
+        || typeof state !== 'object'
+        || Array.isArray(state)
+        || !('version' in state)
+        || state.version !== 1
+        || !('baseUrl' in state)
+        || typeof state.baseUrl !== 'string') {
+        throw new Error('Invalid ReclaimVerification state');
+    }
+    return { version: 1, baseUrl: state.baseUrl };
 }

package/lib/request-proof.d.ts

@@ -0,0 +1,60 @@
+import type { HashRequirement, ReclaimRequestProof, TrustedData } from './proof-types.ts';
+import { type AttestorTeeAttestationConfig } from './verify-attestor-tee.ts';
+import { type TeeAttestationConfig } from './verify-tee.ts';
+export type { ReclaimRequestProof } from './proof-types.ts';
+/** A proof hash requirement accepted by `verifyRequestProof`. */
+export type ProofHashRequirement = string | HashRequirement;
+export interface ResolvedSessionProofValidation {
+    hashes?: ProofHashRequirement[];
+    providerId?: string;
+    providerVersion?: string;
+    allowedTags?: string[];
+}
+/** Exact provider requirements returned by a caller-controlled resolver. */
+export interface ResolvedProviderProofValidation {
+    hashes: ProofHashRequirement[];
+}
+/** Field names match the request spec a provider recipe declares, so a
+ *  caller configuring verification reads the same vocabulary it authored. */
+export interface VerifyRequestProofOptions {
+    hashes?: ProofHashRequirement[];
+    providerId?: string;
+    providerVersion?: string;
+    allowedTags?: string[];
+    dangerouslyDisableContentValidation?: true;
+    /** Read `providerHash` from context, while still verifying signatures. */
+    hasNoPii?: true;
+    teeAttestation?: TeeAttestationConfig;
+    attestorTeeAttestation?: AttestorTeeAttestationConfig;
+    /** Explicit trusted attestor ETH addresses. */
+    attestorAddresses?: string[];
+    /** Trusted Builder JWKS registry containing attestor-purpose keys. */
+    attestorJwksUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** Builder session id. Requires a resolver without hashes or a provider. */
+    sessionId?: string;
+    resolveSession?: (sessionId: string, proofs: ReclaimRequestProof[]) => Promise<ResolvedSessionProofValidation> | ResolvedSessionProofValidation;
+    /** Resolve an exact provider without coupling this verifier to HTTP. */
+    resolveProvider?: (providerId: string, providerVersion: string | undefined, allowedTags: string[] | undefined, proofs: ReclaimRequestProof[]) => Promise<ResolvedProviderProofValidation[]> | ResolvedProviderProofValidation[];
+    expectedSessionId?: string;
+    requireSessionBinding?: boolean;
+    expectedContext?: Record<string, unknown>;
+}
+export interface ReclaimRequestProofOutcome {
+    valid: boolean;
+    reason?: string;
+    proofHashes?: string[];
+    isTeeAttestationVerified?: boolean;
+    /** True when at least one witness's `attestation_report` verified; false
+     *  when the check ran and no witness carried one. */
+    isAttestorTeeAttestationVerified?: boolean;
+    data?: TrustedData[];
+    publicData?: unknown[];
+}
+/** Return the provider hashes encoded in an exact request proof. */
+export declare function proofHashes(proof: ReclaimRequestProof): string[];
+/**
+ * Verify exact request proofs without depending on `@reclaimprotocol/js-sdk`.
+ * The signed claim is never renamed or reconstructed.
+ */
+export declare function verifyRequestProof(proofOrProofs: ReclaimRequestProof | ReclaimRequestProof[], config: VerifyRequestProofOptions): Promise<ReclaimRequestProofOutcome>;

package/lib/request-proof.js

@@ -0,0 +1,241 @@
+import { createSignDataForClaim } from '@reclaimprotocol/attestor-core';
+import { recoverEip191Address } from "./eip191.js";
+import { fetchReclaimJwks, trustedAttestorAddresses } from "./jwks.js";
+import { assertValidProofHashes, getHashFromProof } from "./proof-hash.js";
+import { runAttestorTeeVerification, } from "./verify-attestor-tee.js";
+import { runTeeVerification } from "./verify-tee.js";
+/** Return the provider hashes encoded in an exact request proof. */
+export function proofHashes(proof) {
+    return getHashFromProof(proof);
+}
+/**
+ * Verify exact request proofs without depending on `@reclaimprotocol/js-sdk`.
+ * The signed claim is never renamed or reconstructed.
+ */
+export async function verifyRequestProof(proofOrProofs, config) {
+    const proofs = Array.isArray(proofOrProofs) ? proofOrProofs : [proofOrProofs];
+    if (!proofs.length) {
+        return { valid: false, reason: 'no-proofs' };
+    }
+    try {
+        const effective = await resolveValidation(config, proofs);
+        assertSessionAndContext(proofs, effective);
+        const trust = await resolveAttestorTrust(effective);
+        assertVerifiedSignatures(proofs, trust.addresses);
+        await assertContent(proofs, effective);
+        let isTeeAttestationVerified;
+        if (effective.teeAttestation) {
+            await runTeeVerification(proofs, effective.teeAttestation);
+            isTeeAttestationVerified = true;
+        }
+        let isAttestorTeeAttestationVerified;
+        const attestorTeeAttestation = resolveAttestorTeeAttestation(effective.attestorTeeAttestation, trust.imageDigests);
+        if (attestorTeeAttestation) {
+            // `verified` counts witnesses whose attestation report was checked.
+            // A proof whose witnesses carry no report still passes the address
+            // and signature bindings, but nothing was attested — say so rather
+            // than reporting a TEE attestation that never happened.
+            const summary = await runAttestorTeeVerification(proofs, attestorTeeAttestation);
+            isAttestorTeeAttestationVerified = summary.verified > 0;
+        }
+        return {
+            valid: true,
+            proofHashes: collectProofHashes(proofs, effective.hasNoPii),
+            isTeeAttestationVerified,
+            isAttestorTeeAttestationVerified,
+            data: proofs.map(trustedData),
+            publicData: proofs.map((proof) => proof.publicData ?? {}),
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            reason: failureReason(error),
+        };
+    }
+}
+async function resolveValidation(config, proofs) {
+    let effective = config;
+    if (config.sessionId && !hasContentValidation(config)) {
+        if (!config.resolveSession) {
+            throw new Error('session-resolver-required');
+        }
+        effective = {
+            ...config,
+            ...await config.resolveSession(config.sessionId, proofs),
+        };
+    }
+    return effective;
+}
+async function resolveAttestorTrust(config) {
+    const addresses = config.attestorAddresses?.map(normalized) ?? [];
+    const imageDigests = [];
+    if (config.attestorJwksUrl) {
+        const registry = await fetchReclaimJwks(config.attestorJwksUrl, config.fetchImpl);
+        addresses.push(...(registry['x-reclaim-attestors'] ?? []), ...trustedAttestorAddresses(registry.keys));
+        imageDigests.push(...(registry['x-reclaim-attestor-image-digests'] ?? []));
+    }
+    const unique = [...new Set(addresses)];
+    if (!unique.length) {
+        throw new Error('attestor-trust-required');
+    }
+    return {
+        addresses: unique,
+        imageDigests: [...new Set(imageDigests)],
+    };
+}
+function resolveAttestorTeeAttestation(configured, registryImageDigests) {
+    if (!registryImageDigests.length) {
+        return configured;
+    }
+    const configuredDigests = configured?.expectedImageDigests;
+    if (configuredDigests?.length) {
+        const registry = new Set(registryImageDigests);
+        const expectedImageDigests = [...new Set(configuredDigests
+                .map((digest) => digest.trim().toLowerCase())
+                .filter((digest) => registry.has(digest)))];
+        if (!expectedImageDigests.length) {
+            throw new Error('attestor-image-trust-mismatch');
+        }
+        return { ...configured, expectedImageDigests };
+    }
+    return {
+        ...configured,
+        expectedImageDigests: registryImageDigests,
+    };
+}
+function assertVerifiedSignatures(proofs, trustedAttestors) {
+    for (const proof of proofs) {
+        if (!proof.signatures?.length || !proof.witnesses?.length) {
+            throw new Error('proof-signature-missing');
+        }
+        const signData = createSignDataForClaim(proof.claimData);
+        const signers = proof.signatures.map((signature) => (normalized(recoverEip191Address(signData, signature))));
+        const witnesses = proof.witnesses.map(({ id }) => normalized(id));
+        if (witnesses.some((witness) => !trustedAttestors.includes(witness))) {
+            throw new Error('attestor-not-allowed');
+        }
+        if (!signers.some((signer) => trustedAttestors.includes(signer))) {
+            throw new Error('attestor-not-allowed');
+        }
+        if (!signers.every((signer) => witnesses.includes(signer))) {
+            throw new Error('witness-signature-mismatch');
+        }
+    }
+}
+async function assertContent(proofs, config) {
+    if (config.dangerouslyDisableContentValidation) {
+        return;
+    }
+    if (config.hashes) {
+        assertValidProofHashes(proofs, config.hashes, config.hasNoPii);
+        return;
+    }
+    if (config.providerId) {
+        if (!config.resolveProvider) {
+            throw new Error('provider-resolver-required');
+        }
+        const candidates = await config.resolveProvider(config.providerId, config.providerVersion, config.allowedTags, proofs);
+        if (!candidates.length) {
+            throw new Error('provider-not-found');
+        }
+        let lastError;
+        for (const candidate of candidates) {
+            try {
+                assertValidProofHashes(proofs, candidate.hashes, config.hasNoPii);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw lastError;
+    }
+    throw new Error('proof-validation-required');
+}
+function assertSessionAndContext(proofs, config) {
+    const expectedSessionId = config.sessionId ?? config.expectedSessionId;
+    for (const proof of proofs) {
+        if (expectedSessionId) {
+            const ids = sessionIds(proof);
+            if (ids.some((id) => id !== expectedSessionId)) {
+                throw new Error('session-mismatch');
+            }
+            if ((config.sessionId || config.requireSessionBinding) && !ids.length) {
+                throw new Error('session-missing');
+            }
+        }
+        if (!contextMatches(proof, config.expectedContext)) {
+            throw new Error('context-mismatch');
+        }
+    }
+}
+function trustedData(proof) {
+    const context = contextFrom(proof);
+    const extractedParameters = isRecord(context.extractedParameters)
+        ? Object.fromEntries(Object.entries(context.extractedParameters).map(([key, value]) => [key, String(value)]))
+        : {};
+    delete context.extractedParameters;
+    return { context, extractedParameters };
+}
+function collectProofHashes(proofs, hasNoPii) {
+    try {
+        return proofs.flatMap((proof) => getHashFromProof(proof, hasNoPii));
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasContentValidation(config) {
+    return Boolean(config.hashes
+        || config.providerId
+        || config.dangerouslyDisableContentValidation);
+}
+function failureReason(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    if (lower.includes('multiple')
+        || lower.includes('duplicate')
+        || lower.includes('more than once')) {
+        return 'duplicate-proof-hash';
+    }
+    return message || 'proof-not-verified';
+}
+function normalized(value) {
+    return value.trim().toLowerCase();
+}
+function contextFrom(proof) {
+    const raw = proof.claimData.context;
+    if (!raw) {
+        return {};
+    }
+    try {
+        const context = JSON.parse(raw);
+        return isRecord(context) ? { ...context } : {};
+    }
+    catch {
+        return {};
+    }
+}
+function sessionIds(proof) {
+    const context = contextFrom(proof);
+    const ids = [context.reclaimSessionId];
+    try {
+        const parameters = JSON.parse(proof.claimData.parameters);
+        ids.push(parameters.proxySessionId, parameters.sessionId);
+    }
+    catch {
+        // A non-HTTP claim is valid when session binding wasn't requested.
+    }
+    return ids.filter((value) => (typeof value === 'string' && value.length > 0));
+}
+function contextMatches(proof, expected) {
+    if (!expected) {
+        return true;
+    }
+    const context = contextFrom(proof);
+    return Object.entries(expected).every(([key, value]) => (JSON.stringify(context[key]) === JSON.stringify(value)));
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}