@reclaimprotocol/client 0.1.26 → 0.1.28

package/lib/reclaim.js

@@ -1,11 +1,21 @@
 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";
-/** The three terminal events a subscription can receive. */
+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) {
     if (!config?.orgSecret) {
@@ -25,14 +35,23 @@ export function createReclaim(config) {
         api: client.call.bind(client),
         sessions: {
             async create(input) {
+                const { teeAttestation, ...request } = input;
                 const body = {
-                    ...input,
-                    verificationClientUrl: input.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
+                    ...request,
+                    verificationClientUrl: request.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
                 };
                 const { data } = await client.call('CreateVerificationSession', {
                     body,
                 });
-                return data;
+                return teeAttestation
+                    ? bindTeeNonce(data, teeAttestation)
+                    : data;
+            },
+            async bindTeeNonce(sessionId, input) {
+                const { data } = await client.call('GetVerificationSession', {
+                    params: { sessionId },
+                });
+                return bindTeeNonce(data, input);
             },
             async get(sessionId) {
                 const { data } = await client.call('GetVerificationSession', {
@@ -103,7 +122,10 @@ export function createReclaim(config) {
                 return decryptCallback(resolveKey(credential), body);
             },
             verify(jws, opts) {
-                return verifyResultFull(jws, { fetchImpl: config.fetch, ...opts });
+                return verifyResultFull(jws, {
+                    fetchImpl: config.fetch,
+                    ...withRegisteredIssuer(opts),
+                });
             },
             async receive(body, opts) {
                 // A delivery envelope tagged with a non-terminal event carries a
@@ -114,7 +136,7 @@ export function createReclaim(config) {
                     && !(body instanceof ArrayBuffer)) {
                     const env = body;
                     if (env.event
-                        && !TERMINAL_EVENTS.includes(env.event)) {
+                        && !SIGNED_RESULT_EVENTS.includes(env.event)) {
                         const decoded = parseEventData(env.data);
                         return {
                             kind: 'event',
@@ -128,12 +150,121 @@ export function createReclaim(config) {
                 const jws = await decryptCallback(key, body);
                 const result = await verifyResultFull(jws, {
                     fetchImpl: config.fetch,
-                    ...verifyOpts,
+                    ...withRegisteredIssuer(verifyOpts),
                 });
                 return { kind: 'result', result };
             },
         },
     };
+    async function bindTeeNonce(session, input) {
+        const binding = createBuilderTeeBinding({
+            organizationId: session.orgId,
+            organizationVerificationPrivateKey: input.appSecret,
+            sessionId: session.id,
+            timestamp: input.timestamp ?? Date.now().toString(),
+            nonceMode: input.nonceMode,
+        });
+        const { data } = await client.call('BindVerificationSessionTeeNonce', {
+            params: { sessionId: session.id },
+            body: {
+                attestationNonce: binding.attestationNonce,
+                attestationNonceData: binding.attestationNonceData,
+                signature: binding.signature,
+            },
+        });
+        return data;
+    }
+    async function resolvedSession(id) {
+        const { data } = await client.call('GetVerificationRecipe', { params: { sessionId: id } });
+        return { recipes: data.recipes };
+    }
+    async function resolvedProvider(providerId, providerVersion, _allowedTags, proofs) {
+        let exactVersion = providerVersion;
+        if (!exactVersion) {
+            const { data: provider } = await client.call('GetProvider', {
+                params: { providerId },
+            });
+            if (!provider.latestVersion) {
+                throw new Error(`Provider ${providerId} has no live version`);
+            }
+            exactVersion = canonicalVersion(provider.latestVersion);
+        }
+        const { data: version } = await client.call('GetProviderVersion', {
+            params: { providerId, version: exactVersion },
+        });
+        return [{
+                hashes: proofHashesFromBuilderRecipe({
+                    providerId,
+                    resolvedVersion: exactVersion,
+                    initialUrl: version.initialUrl,
+                    requests: version.requests,
+                    allowedJsRequests: version.allowedJsRequests,
+                }, proofs),
+            }];
+    }
+    function withRegisteredIssuer(opts = {}) {
+        const sessionId = opts.sessionId ?? opts.expectedReclaimSessionId;
+        const requestedProofValidation = opts.proofValidation
+            ?? opts.proofVerification;
+        const resolvedOpts = {
+            ...opts,
+            proofValidation: {
+                ...requestedProofValidation,
+                resolveProvider: requestedProofValidation?.resolveProvider
+                    ?? resolvedProvider,
+            },
+            ...(sessionId && !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) {
+            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;
+            },
+        };
+        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 canonicalVersion(version) {
+    const base = `${version.major}.${version.minor}.${version.patch}`;
+    return version.branch
+        ? `${base}-${version.branch}${version.buildNumber === undefined
+            ? ''
+            : `.${version.buildNumber}`}`
+        : base;
 }
 /** Non-terminal `data` is a base64-encoded JSON `{ event, eventData }`. */
 function parseEventData(data) {
@@ -148,12 +279,7 @@ function parseEventData(data) {
         return {};
     }
 }
-/** True for a `404` thrown by {@link ReclaimClient.call} — a Boom error whose
- *  `output.statusCode` is 404 (see ./errors.ts). */
+/** True for a `404` thrown by {@link ReclaimClient.call}. */
 function isNotFound(err) {
-    if (typeof err !== 'object' || err === null) {
-        return false;
-    }
-    const boom = err;
-    return boom.output?.statusCode === 404 || boom.statusCode === 404;
+    return isProblemError(err) && err.output.statusCode === 404;
 }

package/lib/result.d.ts

@@ -1,6 +1,9 @@
 import type { components } from './types/openapi.gen.ts';
 import type { DecryptionKey } from './enckeys.ts';
 import { type Jwk } from './jwks.ts';
+import { type LegacyVerifyProofOptions, type ProofHashRequirement } from './legacy-proof.ts';
+import { type BuilderProofRecipe } from './proof-recipe.ts';
+import type { TrustedData } from './proof-types.ts';
 export interface Jws {
     payload: string;
     signatures: {
@@ -77,18 +80,62 @@ export declare function decodeJwsPayload(jws: Jws): Record<string, unknown>;
  */
 export declare function verifyJwsSignature(jws: Jws, signerPublicKey: string): boolean;
 export interface VerifyResultFullOptions {
+    /** Builder session id. Alias for `expectedReclaimSessionId`. */
+    sessionId?: string;
     /** The `reclaimSessionId` the consumer expects (mismatch fails). */
     expectedReclaimSessionId?: string;
     /** The consumer's `orgId`; the result's `aud` must match it. */
     expectedAud?: string;
     /** Allowlist of trusted attestor ETH addresses (lowercased compared). */
     attestorAddresses?: string[];
+    /** One explicitly trusted Verification Client issuer. */
+    issuer?: string;
+    /** Alias for `issuer`. */
+    trustedIssuer?: string;
+    /** Explicitly trusted Verification Client issuers. */
+    issuers?: string[];
+    /** Alias for `issuers`, retained for security-focused callers. */
+    trustedIssuers?: string[];
+    /** Resolve registered issuer URLs for the signed session's client id. */
+    resolveIssuers?: (verificationClientId: string) => Promise<readonly string[]> | readonly string[];
+    /** Alias for `resolveIssuers`. */
+    issuerResolver?: (verificationClientId: string) => Promise<readonly string[]> | readonly string[];
+    /** Registered issuer URLs keyed by `verificationClientId`. */
+    issuersByVerificationClientId?: Record<string, string[]>;
+    /** Explicit trusted JWKS URL. This value must come from your registry. */
+    jwksUrl?: string;
+    /** Trusted JWKS URLs keyed by `verificationClientId`. */
+    jwksUrlsByVerificationClientId?: Record<string, string>;
+    /** Resolve a registered JWKS URL for the signed session's client id. */
+    resolveJwksUrl?: (verificationClientId: string) => Promise<string | undefined> | string | undefined;
+    /** Legacy-compatible proof validation options applied to all proofs. */
+    proofValidation?: LegacyVerifyProofOptions;
+    /** Alias for `proofValidation`. */
+    proofVerification?: LegacyVerifyProofOptions;
+    /** Per-provider overrides for sessions containing different providers. */
+    proofValidationByProviderId?: Record<string, LegacyVerifyProofOptions>;
+    /** Legacy-compatible hash requirements, for the common simple case. */
+    hashes?: ProofHashRequirement[];
+    /** Resolved Builder recipes, used to derive strict proof hashes offline. */
+    proofRecipes?: BuilderProofRecipe[];
+    /** Resolve a Builder session and its immutable, resolved recipes. */
+    resolveSession?: (sessionId: string) => Promise<{
+        recipes: BuilderProofRecipe[];
+    }> | {
+        recipes: BuilderProofRecipe[];
+    };
     /** Override the VC signer key instead of JWKS discovery via header `iss`. */
     signerPublicKey?: string;
     /** Injectable fetch (for JWKS); defaults to global `fetch`. */
     fetchImpl?: typeof fetch;
-    /** Override "now" (unix seconds) for `exp` checks. */
+    /** Override "now" (Unix seconds) when checking a legacy result's `exp`. */
     now?: number;
+    /**
+     * Accept a legacy Builder result that contains an expired `exp` claim.
+     * New Builder results don't include `exp`; use this only while consuming
+     * older stored results whose signatures and proofs must remain verifiable.
+     */
+    ignoreExpiration?: boolean;
 }
 export interface ResultProofOutcome {
     /** Which provider this proof belongs to (results grouped per provider). */
@@ -97,6 +144,10 @@ export interface ResultProofOutcome {
     proofValid: boolean;
     reason?: string;
     attestorAddress?: string;
+    /** Trusted only when `proofValid` is true. */
+    data?: TrustedData;
+    /** Provider-supplied data. It isn't cryptographically validated. */
+    publicData?: unknown;
 }
 export interface VerifyResultFullOutcome extends VerifyResultOutcome {
     proofs?: ResultProofOutcome[];
@@ -126,11 +177,12 @@ export declare class ResultVerificationError extends Error {
     constructor(outcome: VerifyResultFullOutcome);
 }
 /**
- * Full consumer verification: discovers the Verification Client's signing key
- * via JWKS (header `iss`/`kid`), verifies the top-level JWS, checks
- * `reclaimSessionId`/`aud`/`exp`, then verifies each result's nested attestor
- * proof and its `content_hash`. Network access (JWKS) makes this async; use
- * {@link verifyResult} for the offline primitive.
+ * Full consumer verification: resolves a trusted, registered issuer before
+ * using JWKS (header `iss`/`kid`), verifies the top-level JWS, checks
+ * `reclaimSessionId`/`aud` and any legacy `exp`, then verifies each exact
+ * legacy proof.
+ * Network access (JWKS and optional provider resolution) makes this async.
+ * Use {@link verifyResult} for the offline primitive.
  */
 export declare function verifyResultFull(jws: Jws, opts?: VerifyResultFullOptions): Promise<VerifyResultFullOutcome>;
 /** Decrypt-and-verify in one step. */