@reclaimprotocol/client 0.1.29 → 0.1.31

package/lib/legacy-proof.d.ts

@@ -44,6 +44,8 @@ export interface LegacyProofOutcome {
     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[];

package/lib/legacy-proof.js

@@ -20,8 +20,8 @@ export async function verifyProof(proofOrProofs, config) {
     try {
         const effective = await resolveValidation(config, proofs);
         assertSessionAndContext(proofs, effective);
-        const attestors = await resolveTrustedAttestors(effective);
-        assertVerifiedSignatures(proofs, attestors);
+        const trust = await resolveAttestorTrust(effective);
+        assertVerifiedSignatures(proofs, trust.addresses);
         await assertContent(proofs, effective);
         let isTeeAttestationVerified;
         if (effective.teeAttestation) {
@@ -29,9 +29,14 @@ export async function verifyProof(proofOrProofs, config) {
             isTeeAttestationVerified = true;
         }
         let isAttestorTeeAttestationVerified;
-        if (effective.attestorTeeAttestation) {
-            await runAttestorTeeVerification(proofs, effective.attestorTeeAttestation);
-            isAttestorTeeAttestationVerified = true;
+        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,
@@ -62,17 +67,42 @@ async function resolveValidation(config, proofs) {
     }
     return effective;
 }
-async function resolveTrustedAttestors(config) {
+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 unique;
+    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) {

package/lib/proof-hash.d.ts

@@ -1,4 +1,4 @@
-import type { HashRequirement, LegacyProof } from './proof-types.ts';
+import type { HashRequirement, ReclaimRequestProof } from './proof-types.ts';
 export interface HttpProofParams {
     url: string;
     method: string;
@@ -27,9 +27,9 @@ export interface ProofRequestSpec extends HttpProofParams {
     templateParams?: string[];
     templateParamsMode?: 'separate' | 'merge';
 }
-/** Exact legacy canonical HTTP-provider hashes, including optional matches. */
+/** Exact canonical HTTP-provider hashes, including optional matches. */
 export declare function hashProofClaimParams(params: HttpProofParams): string[];
-export declare function getHashFromProof(proof: LegacyProof, hasNoPii?: boolean): string[];
+export declare function getHashFromProof(proof: ReclaimRequestProof, hasNoPii?: boolean): string[];
 export declare function hashRequestSpec(request: ProofRequestSpec): HashRequirement;
-export declare function hashRequirementsFromSpecs(requestData: ProofRequestSpec[], allowedInjectedRequestData: ProofRequestSpec[], proofs: LegacyProof[]): HashRequirement[];
-export declare function assertValidProofHashes(proofs: LegacyProof[], requirements: Array<string | HashRequirement>, hasNoPii?: boolean): void;
+export declare function hashRequirementsFromSpecs(requestData: ProofRequestSpec[], allowedInjectedRequestData: ProofRequestSpec[], proofs: ReclaimRequestProof[]): HashRequirement[];
+export declare function assertValidProofHashes(proofs: ReclaimRequestProof[], requirements: Array<string | HashRequirement>, hasNoPii?: boolean): void;

package/lib/proof-hash.js

@@ -1,7 +1,7 @@
 import { keccak_256 } from '@noble/hashes/sha3.js';
 import { canonicalJson as canonical } from "./canonical.js";
 import { bytesToHex } from "./encoding.js";
-/** Exact legacy canonical HTTP-provider hashes, including optional matches. */
+/** Exact canonical HTTP-provider hashes, including optional matches. */
 export function hashProofClaimParams(params) {
     return canonicalProofParams(params).map((serialized) => ('0x' + bytesToHex(keccak_256(new TextEncoder().encode(serialized)))));
 }

package/lib/proof-recipe.d.ts

@@ -1,5 +1,5 @@
 import type { components } from './types/openapi.gen.ts';
-import type { LegacyProof } from './proof-types.ts';
+import type { ReclaimRequestProof } from './proof-types.ts';
 type RequestSelection = components['schemas']['RequestSelection'];
 type RequestSelectionTemplate = components['schemas']['RequestSelectionTemplate'];
 /** Resolved Builder provider recipe returned for a verification session. */
@@ -11,8 +11,8 @@ export interface BuilderProofRecipe {
     allowedJsRequests?: RequestSelectionTemplate[];
 }
 /**
- * Derive the exact hash requirements consumed by legacy `verifyProof` from a
+ * Derive the exact hash requirements consumed by `verifyRequestProof` from a
  * resolved Builder recipe. Builder's fixed requests are required once each.
  */
-export declare function proofHashesFromBuilderRecipe(recipe: BuilderProofRecipe, proofs: LegacyProof[]): import("./proof-types.ts").HashRequirement[];
+export declare function proofHashesFromBuilderRecipe(recipe: BuilderProofRecipe, proofs: ReclaimRequestProof[]): import("./proof-types.ts").HashRequirement[];
 export {};

package/lib/proof-recipe.js

@@ -1,6 +1,6 @@
 import { hashRequirementsFromSpecs, } from "./proof-hash.js";
 /**
- * Derive the exact hash requirements consumed by legacy `verifyProof` from a
+ * Derive the exact hash requirements consumed by `verifyRequestProof` from a
  * resolved Builder recipe. Builder's fixed requests are required once each.
  */
 export function proofHashesFromBuilderRecipe(recipe, proofs) {

package/lib/proof-types.d.ts

@@ -1,15 +1,19 @@
-/** Exact legacy proof structures carried inside Builder result envelopes. */
-export interface LegacyProof {
+/** Exact proof structure for one verified request, carried inside Builder
+ *  result envelopes. Every Verification Client — the in-app SDK, the browser
+ *  extension, portals, and Builder's own client — emits this shape. */
+export interface ReclaimRequestProof {
     identifier: string;
-    claimData: LegacyClaimData;
+    claimData: RequestClaimData;
     signatures: string[];
-    witnesses: LegacyWitness[];
+    witnesses: RequestWitness[];
     extractedParameterValues: unknown;
     publicData?: unknown;
     taskId?: number;
-    teeAttestation?: TeeAttestation | string;
+    /** Client-specific legacy TEE data. Verification validates a supported
+     * representation only when TEE verification is requested. */
+    teeAttestation?: unknown;
 }
-export interface LegacyClaimData {
+export interface RequestClaimData {
     provider: string;
     parameters: string;
     owner: string;
@@ -18,15 +22,38 @@ export interface LegacyClaimData {
     identifier: string;
     epoch: number;
 }
-export interface LegacyWitness {
+export interface RequestWitness {
     id: string;
     url: string;
     claimAttestation?: AttestorClaimAttestation;
 }
+/**
+ * Which kind of attestation a witness carries.
+ *
+ * `embedded-attestor` — the in-app SDK and the browser extension. The attestor
+ * signs the claim and, on a TEE run, may also return its own
+ * `attestation_report`.
+ *
+ * `confidential-space` — portals. The browser runtime signs the claim inside a
+ * GCP Confidential Space and returns `tee_attestation`, bound to the claim
+ * through `context.attestationNonce`.
+ */
+export type ClaimAttestationType = 'embedded-attestor' | 'confidential-space';
 export interface AttestorClaimAttestation {
+    type: ClaimAttestationType;
     attestor_address: string;
     claim_signature: string;
-    attestation_report: string;
+    /** `embedded-attestor` only, and optional even then: the attestor's own GCP
+     *  Confidential Space attestation (an RS256 JWT). Attestors in production
+     *  sign claims without returning one, so a witness routinely carries only
+     *  the address and the claim signature. */
+    attestation_report?: string;
+    /** `confidential-space` only: the same payload legacy proofs carry in the
+     *  proof's top-level `teeAttestation`, and typed the same way. It comes
+     *  from an external producer and is preserved verbatim, so callers validate
+     *  it at runtime — `verifyTeeAttestation` does — rather than trusting a
+     *  shape the wire does not guarantee. */
+    tee_attestation?: unknown;
 }
 export interface TeeAttestation {
     proof_version?: 'v2' | 'v3';

package/lib/reclaim.d.ts

@@ -1,20 +1,19 @@
 /**
  * Declarative entry point for the consumer SDK. The ONLY config is the org
  * secret (`rorg_…`) — it authenticates every call and identifies the org
- * server-side. Everything else is passed where it's actually used: the `orgId`
- * to the org-scoped `keypair.set`/`get`, and the eth decryption key to
- * `results.decrypt`/`receive` (only when results arrive encrypted):
+ * server-side. Pass the optional organization ETH private key only to the
+ * operation that needs it:
  *
- *   const reclaim = createReclaim({ orgSecret })
- *   // one-time setup:
- *   await reclaim.callbacks.register({ callbackUrl })
- *   // enable encryption (eth public key, hex):
- *   await reclaim.keypair.set(orgId, { publicKey, canEncryptResult: true })
- *   const session = await reclaim.sessions.create({ providers, context })
+ *   const reclaim = ReclaimVerification.create({ orgSecret })
+ *   const session = await reclaim.sessions.create({
+ *   	providers,
+ *   	context,
+ *   	orgEthPrivateKey, // optional TEE session binding
+ *   })
  *   // …end-user completes session.verificationUrl…
  *   const outcome = await reclaim.results.receive(callbackBody, {
- *   	credential: ethPrivateKeyHex, // omit for plaintext
- *   	expectedReclaimSessionId: session.id,
+ *   	orgEthPrivateKey, // optional decryption and TEE proof verification
+ *   	reclaimSessionId: session.id,
  *   })
  *
  * Built by composition over the package's pure helpers (`decryptCallback`,
@@ -26,17 +25,9 @@ import { ReclaimClient } from './client.ts';
 import { type DecryptionKeyInput } from './enckeys.ts';
 import { type CallbackBody, type Jws, type VerifyResultFullOptions, type VerifyResultFullOutcome } from './result.ts';
 import { type LegacyTeeNonceMode } from './tee-binding.ts';
-type CallbackSubscription = components['schemas']['CallbackSubscription'];
 type VerificationSession = components['schemas']['VerificationSession'];
 type VerificationEvent = components['schemas']['VerificationEvent'];
 type VerificationEventRecord = components['schemas']['VerificationEventRecord'];
-type OrgKeypair = components['schemas']['OrgKeypair'];
-/** Terminal lifecycle events selected by default for callback subscriptions. */
-export declare const TERMINAL_EVENTS: readonly ["verification_success", "verification_rejected", "verification_error", "verification_cancelled", "session_expired"];
-export interface RegisterCallbackInput {
-    callbackUrl: string;
-    events: VerificationEvent[];
-}
 export interface CreateSessionInput {
     /** Providers to verify, in run order. The end-user proves each (one browser
      *  session) and one combined result is delivered; all are required. */
@@ -45,32 +36,34 @@ export interface CreateSessionInput {
         version?: string;
     }[];
     context: Record<string, unknown>;
-    /** Exact registered Verification Client base URL. It may contain a
+    /** Exact registered Verification Client base URL. Defaults to the Portal.
+     *  It may contain a
      *  `{sessionId}` placeholder; Builder otherwise adds the session id as a
      *  query parameter. Open the returned `verificationUrl`, not this base
      *  URL. */
-    verificationClientUrl: string;
-    /** Optional legacy-compatible TEE session binding. The app secret is the
-     *  organization's verification private key and never leaves this process.
+    verificationClientUrl?: string;
+    /** Optional legacy-compatible TEE session binding. The organization's ETH
+     *  private key never leaves this process.
      *  Session creation returns only after Builder stores the signed binding. */
-    teeAttestation?: CreateSessionTeeAttestation;
+    orgEthPrivateKey?: string;
+    /** Override the legacy TEE nonce mode when binding a session. */
+    teeNonceMode?: LegacyTeeNonceMode;
+    /** Opt this session into diagnostic mode: more event detail, including
+     *  personal data such as the claimant's IP addresses. Builder builds
+     *  `verificationUrl` with `diag=1` for a diagnostic session — do not
+     *  append `diag` to the URL directly, since Builder strips it and derives
+     *  the parameter from this flag instead. Treat a diagnostic
+     *  `verificationUrl` as sensitive. */
+    diagnostics?: boolean;
 }
-/** Options intentionally mirror legacy `verifyProof`'s `teeAttestation`
- *  vocabulary. `timestamp` is decimal Unix milliseconds; omit it to use now. */
-export interface CreateSessionTeeAttestation {
-    appSecret: string;
+/** Input for explicitly binding a session's legacy-compatible TEE context. */
+export interface BindSessionTeeNonceInput {
+    orgEthPrivateKey: string;
     timestamp?: string;
     /** `hash` is the default. Use `signature` only for an older Verification
      * Client that expects the 65-byte EIP-191 nonce. */
-    nonceMode?: LegacyTeeNonceMode;
+    teeNonceMode?: LegacyTeeNonceMode;
 }
-/** Input for `keypair.set`: the org's eth public key as uncompressed hex
- *  (`publicKey`, the form wallets/ethers emit) OR as a secp256k1 JWK
- *  (`publicKeyJwk`); keep the matching eth private key to decrypt results.
- *  `canEncryptResult` toggles ECIES encryption (default off). The two request
- *  shapes are the spec's `OrgKeypairRequest` union members, relaxed to optional
- *  so the SDK caller supplies just one key form. */
-export type SetKeypairInput = Partial<components['schemas']['OrgKeypairHexRequest']> & Partial<components['schemas']['OrgKeypairJwkRequest']>;
 export interface ReclaimConfig {
     /** The org secret (`rorg_…`). Authenticates ALL API calls and identifies
      *  the org server-side. The only required config. */
@@ -82,62 +75,75 @@ export interface ReclaimConfig {
     /** Extra headers merged into every request. */
     headers?: Record<string, string>;
 }
+/** Serializable SDK configuration.
+ *  Credentials and runtime hooks are omitted. */
+export interface ReclaimVerificationState {
+    version: 1;
+    baseUrl: string;
+}
+/** Runtime-only values required to restore serialized SDK configuration. */
+export type ImportReclaimVerificationConfig = Omit<ReclaimConfig, 'baseUrl'>;
 /** Options for `results.receive` — the verification options plus an optional
  *  eth decryption key (the org's eth private key as `0x`-hex). The key is
  *  needed only when the delivery is an ECIES ciphertext. */
-export type ReceiveOptions = VerifyResultFullOptions & {
-    credential?: DecryptionKeyInput;
-};
-export interface Reclaim {
+export type ReceiveOptions = VerifyResultFullOptions;
+/** A thin backend-side handle on a session's `verificationUrl` — see
+ *  `reclaim.flow`. Not the browser launcher: this holds no device
+ *  detection or launch mechanism, only the URL the browser needs. The
+ *  browser-only `ReclaimFlow.from(session)` in
+ *  `@reclaimprotocol/client/launch` is the counterpart that actually
+ *  resolves how to open it. */
+export interface SessionFlow {
+    /** `session.verificationUrl`. A `Promise` so backend code calling this
+     *  doesn't need to special-case it against the browser `ReclaimFlow`'s
+     *  `getUrl()`, which does real async work. */
+    getUrl(): Promise<string>;
+    readonly session: VerificationSession;
+}
+/** `reclaim.flow(session)` wraps a session already created via
+ *  `sessions.create`/`sessions.get`; `reclaim.flow.create(input)` creates one
+ *  and wraps it in the same step. */
+export interface ReclaimFlowFactory {
+    (session: VerificationSession): SessionFlow;
+    create(input: CreateSessionInput): Promise<SessionFlow>;
+}
+export interface ReclaimVerification {
+    /** Serialize non-secret configuration. Credentials, headers, and custom
+     *  fetch implementations are never included. */
+    export(): string;
     /** Typed escape hatch: `reclaim.api('OperationId', args)` for any spec
      *  operation. */
     api: ReclaimClient['call'];
     sessions: {
         /** Create a verification session. `verificationClientUrl` defaults to
-         *  the Builder's own `/v/{sessionId}` page. */
-        create(input: Omit<CreateSessionInput, 'verificationClientUrl'> & Partial<Pick<CreateSessionInput, 'verificationClientUrl'>>): Promise<VerificationSession>;
+         *  the Portal, `VerificationClient.portals`. */
+        create(input: CreateSessionInput): Promise<VerificationSession>;
         /** Add the immutable legacy-compatible TEE context after session
          *  creation. Normally use
-         *  `sessions.create({ teeAttestation: { appSecret } })`; this method
+         *  `sessions.create({ orgEthPrivateKey })`; this method
          *  supports retrying or explicitly orchestrating the two-step flow. */
-        bindTeeNonce(sessionId: string, input: CreateSessionTeeAttestation): Promise<VerificationSession>;
-        get(sessionId: string): Promise<VerificationSession>;
-        listEvents(sessionId: string): Promise<VerificationEventRecord[]>;
-    };
-    callbacks: {
-        /** Register a callback subscription (one-time setup). Delivery is scoped
-         *  to the token's org; results are ECIES-encrypted to the org's eth key
-         *  when `canEncryptResult` is enabled (see `keypair.set`), else plaintext.
-         *  `events` defaults to all terminal lifecycle events. */
-        register(input: Partial<RegisterCallbackInput> & Pick<RegisterCallbackInput, 'callbackUrl'>): Promise<CallbackSubscription>;
-        list(): Promise<CallbackSubscription[]>;
-        remove(subscriptionId: string): Promise<void>;
-    };
-    keypair: {
-        /** Set/rotate org `orgId`'s single eth encryption keypair. When
-         *  `canEncryptResult` is enabled, terminal results are delivered as an
-         *  ECIES ciphertext encrypted to it. */
-        set(orgId: string, input: SetKeypairInput): Promise<OrgKeypair>;
-        /** Get org `orgId`'s encryption keypair, or `undefined` when none is set
-         *  (the org is keyless ⇒ plaintext delivery). */
-        get(orgId: string): Promise<OrgKeypair | undefined>;
+        bindTeeNonce(reclaimSessionId: string, input: BindSessionTeeNonceInput): Promise<VerificationSession>;
+        get(reclaimSessionId: string): Promise<VerificationSession>;
+        listEvents(reclaimSessionId: string): Promise<VerificationEventRecord[]>;
     };
     results: {
         /** Decrypt a callback body (ECIES ciphertext or plaintext JWS) to the
-         *  signed JWS. Pass the eth `credential` (`0x`-hex private key) only when
-         *  the delivery is encrypted. */
-        decrypt(body: CallbackBody, credential?: DecryptionKeyInput): Promise<Jws>;
+         *  signed JWS. Pass `orgEthPrivateKey` only when the delivery is
+         *  encrypted. */
+        decrypt(body: CallbackBody, orgEthPrivateKey?: DecryptionKeyInput): Promise<Jws>;
         /** Verify a decrypted JWS: JWKS discovery, ES256K signature,
-         *  `reclaimSessionId`/`aud`, any legacy `exp`, and exact legacy proofs. */
+         *  `reclaimSessionId`/`aud`, any legacy `exp`, and exact proofs. */
         verify(jws: Jws, opts?: VerifyResultFullOptions): Promise<VerifyResultFullOutcome>;
         /** Handle any callback delivery in one call — the 90% path. Branches on
          *  the envelope's `event`: a terminal event is decrypted (with
-         *  `opts.credential` when encrypted) + verified into a `result`; a
+         *  `opts.orgEthPrivateKey` when encrypted) and verified into a `result`; a
          *  non-terminal event is returned as a plaintext (unsigned) `event`
          *  notification without decryption. (A raw JWE/JWS body with no envelope
          *  `event` is treated as a terminal result.) */
         receive(body: CallbackBody, opts?: ReceiveOptions): Promise<ReceivedDelivery>;
     };
+    /** `reclaim.flow(session)` — see `ReclaimFlowFactory`. */
+    flow: ReclaimFlowFactory;
 }
 /** Outcome of `results.receive` — a verified terminal result or a plaintext
  *  non-terminal progress notification. Branch on `kind`. */
@@ -149,5 +155,10 @@ export type ReceivedDelivery = {
     event: VerificationEvent;
     eventData: Record<string, unknown>;
 };
-export declare function createReclaim(config: ReclaimConfig): Reclaim;
+export declare const ReclaimVerification: Readonly<{
+    create: typeof createReclaimVerification;
+    import: typeof importReclaimVerification;
+}>;
+declare function importReclaimVerification(serialized: string, config: ImportReclaimVerificationConfig): ReclaimVerification;
+declare function createReclaimVerification(config: ReclaimConfig): ReclaimVerification;
 export {};