@reclaimprotocol/client 0.1.27 → 0.1.28

package/lib/proof-hash.js

@@ -0,0 +1,216 @@
+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. */
+export function hashProofClaimParams(params) {
+    return canonicalProofParams(params).map((serialized) => ('0x' + bytesToHex(keccak_256(new TextEncoder().encode(serialized)))));
+}
+export function getHashFromProof(proof, hasNoPii = false) {
+    if (hasNoPii) {
+        const context = JSON.parse(proof.claimData.context);
+        if (typeof context.providerHash !== 'string' || !context.providerHash) {
+            throw new Error('Provider hash must be present in proof context');
+        }
+        return [context.providerHash];
+    }
+    const parsed = JSON.parse(proof.claimData.parameters);
+    if (!isHttpProofParams(parsed)) {
+        throw new Error('Proof has no HTTP provider params to hash');
+    }
+    return hashProofClaimParams(parsed);
+}
+export function hashRequestSpec(request) {
+    return {
+        value: hashProofClaimParams({
+            ...request,
+            body: request.bodySniff.enabled ? request.bodySniff.template : '',
+        }),
+        required: request.required,
+        multiple: request.multiple,
+    };
+}
+export function hashRequirementsFromSpecs(requestData, allowedInjectedRequestData, proofs) {
+    const templates = expandTemplates(allowedInjectedRequestData, templateParametersFromProofs(proofs));
+    return [...requestData, ...templates].map(hashRequestSpec);
+}
+export function assertValidProofHashes(proofs, requirements, hasNoPii = false) {
+    const unmatched = new Map(proofs.map((proof, index) => ([index, getHashFromProof(proof, hasNoPii)])));
+    for (const raw of requirements) {
+        const requirement = typeof raw === 'string' ? { value: raw } : raw;
+        const expected = (Array.isArray(requirement.value)
+            ? requirement.value
+            : [requirement.value]).map(normalized);
+        let found = false;
+        for (const [index, hashes] of unmatched) {
+            if (!hashes.map(normalized).some((hash) => expected.includes(hash))) {
+                continue;
+            }
+            unmatched.delete(index);
+            if (found && requirement.multiple === false) {
+                throw new Error(`Proof by hash '${expected.join(',')}' is not allowed `
+                    + 'to appear more than once');
+            }
+            found = true;
+        }
+        if (!found && requirement.required !== false) {
+            throw new Error(`Proof by required hash '${expected.join(',')}' was not found`);
+        }
+    }
+    if (unmatched.size) {
+        throw new Error(`${unmatched.size} extra proof(s) could not be validated`);
+    }
+}
+function canonicalProofParams(params) {
+    const count = params.responseMatches.length;
+    const values = [];
+    for (let mask = 0; mask < 2 ** count; mask++) {
+        let valid = true;
+        const matches = [];
+        const redactions = [];
+        for (let index = 0; index < count; index++) {
+            const match = params.responseMatches[index];
+            const redaction = params.responseRedactions[index];
+            if ((mask & (1 << index)) === 0) {
+                if (match && !match.isOptional) {
+                    valid = false;
+                }
+                continue;
+            }
+            if (match) {
+                matches.push({
+                    value: match.value ?? '',
+                    type: match.type ?? 'contains',
+                    invert: match.invert || undefined,
+                });
+            }
+            if (redaction) {
+                redactions.push({
+                    xPath: redaction.xPath ?? '',
+                    jsonPath: redaction.jsonPath ?? '',
+                    regex: redaction.regex ?? '',
+                    hash: normalizedRedactionHash(redaction.hash),
+                });
+            }
+        }
+        if (valid && matches.length) {
+            values.push(canonical({
+                url: params.url ?? '',
+                method: params.method ?? 'GET',
+                body: params.body ?? '',
+                responseMatches: matches,
+                responseRedactions: redactions,
+            }));
+        }
+    }
+    return values.length ? values : [canonical({
+            url: params.url ?? '',
+            method: params.method ?? 'GET',
+            body: params.body ?? '',
+            responseMatches: [],
+            responseRedactions: [],
+        })];
+}
+function expandTemplates(templates, parameters) {
+    const result = [];
+    for (const template of templates) {
+        const names = template.templateParams ?? [];
+        if (!names.length) {
+            result.push(template);
+            continue;
+        }
+        const present = names.filter((name) => parameters[name]?.length);
+        if (present.length !== names.length) {
+            if (template.required === false && !present.length) {
+                continue;
+            }
+            throw new Error('Not all template variables are present');
+        }
+        const length = parameters[names[0]].length;
+        if (!names.every((name) => parameters[name].length === length)) {
+            throw new Error('Not all template variables have same length');
+        }
+        const expanded = Array.from({ length }, (_, index) => substitute(template, Object.fromEntries(names.map((name) => [name, parameters[name][index]]))));
+        if (template.templateParamsMode !== 'merge') {
+            result.push(...expanded);
+            continue;
+        }
+        result.push({
+            ...template,
+            responseMatches: expanded.flatMap((item) => item.responseMatches),
+            responseRedactions: expanded.flatMap((item) => item.responseRedactions),
+        });
+    }
+    return result;
+}
+function substitute(template, parameters) {
+    const replace = (value) => Object.entries(parameters).reduce((result, [name, replacement]) => (result.split(`\${${name}}`).join(replacement)), value);
+    return {
+        ...template,
+        responseMatches: template.responseMatches.map((match) => ({
+            ...match,
+            value: replace(match.value ?? ''),
+        })),
+        responseRedactions: template.responseRedactions.map((redaction) => ({
+            ...redaction,
+            xPath: replace(redaction.xPath ?? ''),
+            jsonPath: replace(redaction.jsonPath ?? ''),
+            regex: replace(redaction.regex ?? ''),
+        })),
+    };
+}
+function templateParametersFromProofs(proofs) {
+    const combined = {};
+    for (const proof of proofs) {
+        for (const raw of [proof.claimData.parameters, proof.claimData.context]) {
+            try {
+                const parsed = JSON.parse(raw);
+                Object.assign(combined, parsed.paramValues, parsed.extractedParameters);
+            }
+            catch {
+                // A proof without template parameters is valid.
+            }
+        }
+    }
+    const result = {};
+    for (const [name, raw] of Object.entries(combined)) {
+        let value = raw;
+        if (typeof value === 'string') {
+            try {
+                value = JSON.parse(value);
+            }
+            catch { /* plain string */ }
+        }
+        if (Array.isArray(value) && value.length) {
+            result[name] = value.map(String);
+        }
+    }
+    return result;
+}
+function isHttpProofParams(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const params = value;
+    return typeof params.url === 'string'
+        && typeof params.method === 'string'
+        && ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(params.method)
+        && (params.body === null
+            || params.body === undefined
+            || typeof params.body === 'string')
+        && Array.isArray(params.responseMatches)
+        && params.responseMatches.length > 0
+        && Array.isArray(params.responseRedactions);
+}
+function normalized(value) {
+    return value.toLowerCase().trim();
+}
+/**
+ * All OPRF transports prove the same provider-level intent: the selected
+ * value is hidden behind an OPRF. Verification Clients may use the transport
+ * they implement, so transport spelling must not change the provider hash.
+ */
+function normalizedRedactionHash(value) {
+    return value === 'oprf' || value === 'oprf-mpc' || value === 'oprf-raw'
+        ? '_oprf'
+        : value || undefined;
+}

package/lib/proof-recipe.d.ts

@@ -0,0 +1,18 @@
+import type { components } from './types/openapi.gen.ts';
+import type { LegacyProof } from './proof-types.ts';
+type RequestSelection = components['schemas']['RequestSelection'];
+type RequestSelectionTemplate = components['schemas']['RequestSelectionTemplate'];
+/** Resolved Builder provider recipe returned for a verification session. */
+export interface BuilderProofRecipe {
+    providerId: string;
+    resolvedVersion: string;
+    initialUrl: string;
+    requests: RequestSelection[];
+    allowedJsRequests?: RequestSelectionTemplate[];
+}
+/**
+ * Derive the exact hash requirements consumed by legacy `verifyProof` 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 {};

package/lib/proof-recipe.js

@@ -0,0 +1,37 @@
+import { hashRequirementsFromSpecs, } from "./proof-hash.js";
+/**
+ * Derive the exact hash requirements consumed by legacy `verifyProof` from a
+ * resolved Builder recipe. Builder's fixed requests are required once each.
+ */
+export function proofHashesFromBuilderRecipe(recipe, proofs) {
+    return hashRequirementsFromSpecs(recipe.requests.map((request) => toRequestSpec(request, { required: true, multiple: false })), (recipe.allowedJsRequests ?? []).map((request) => toRequestSpec(request, {
+        required: request.required,
+        multiple: request.multiple,
+        templateParams: request.templateParams,
+        templateParamsMode: request.templateParamsMode,
+    })), proofs);
+}
+function toRequestSpec(request, flags) {
+    return {
+        url: request.url,
+        urlType: request.url.includes('{{') ? 'TEMPLATE' : 'CONSTANT',
+        method: request.method,
+        bodySniff: {
+            enabled: request.requestBodyTemplate !== undefined,
+            template: request.requestBodyTemplate ?? '',
+        },
+        responseMatches: (request.responseMatches ?? []).map((match) => ({
+            type: match.type,
+            value: match.value,
+            invert: undefined,
+            isOptional: match.isOptional,
+        })),
+        responseRedactions: (request.responseRedactions ?? []).map((redaction) => ({
+            ...(redaction.hash ? { hash: redaction.hash } : {}),
+            jsonPath: redaction.jsonPath ?? '',
+            regex: redaction.regex ?? '',
+            xPath: redaction.xPath ?? '',
+        })),
+        ...flags,
+    };
+}

package/lib/proof-trust-constants.d.ts

@@ -0,0 +1,3 @@
+export declare const GCP_CONFIDENTIAL_SPACE_ROOT_CA = "-----BEGIN CERTIFICATE-----\n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\nuyT5CnJulxSC5CT1\n-----END CERTIFICATE-----";
+export declare const ATTESTOR_NONCE_PATTERN: RegExp;
+export declare const GCP_CONFIDENTIAL_SPACE_ISSUER = "https://confidentialcomputing.googleapis.com";

package/lib/proof-trust-constants.js

@@ -0,0 +1,43 @@
+/* eslint-disable @stylistic/max-len */
+// GCP Confidential Space Root CA — pinned. Rotates infrequently
+// (current cert valid 2024-2034). Used to verify attestor TEE attestation JWTs.
+export const GCP_CONFIDENTIAL_SPACE_ROOT_CA = `-----BEGIN CERTIFICATE-----
+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
+uyT5CnJulxSC5CT1
+-----END CERTIFICATE-----`;
+// Matches an `attestor_public_key:0x<40-hex>` entry in a GCP Confidential
+// Space attestation JWT's `eat_nonce` claim.
+export const ATTESTOR_NONCE_PATTERN = /^attestor_public_key:0x([0-9a-fA-F]{40})$/;
+// Expected `iss` claim on GCP Confidential Space attestation JWTs.
+export const GCP_CONFIDENTIAL_SPACE_ISSUER = 'https://confidentialcomputing.googleapis.com';

package/lib/proof-types.d.ts

@@ -0,0 +1,62 @@
+/** Exact legacy proof structures carried inside Builder result envelopes. */
+export interface LegacyProof {
+    identifier: string;
+    claimData: LegacyClaimData;
+    signatures: string[];
+    witnesses: LegacyWitness[];
+    extractedParameterValues: unknown;
+    publicData?: unknown;
+    taskId?: number;
+    teeAttestation?: TeeAttestation | string;
+}
+export interface LegacyClaimData {
+    provider: string;
+    parameters: string;
+    owner: string;
+    timestampS: number;
+    context: string;
+    identifier: string;
+    epoch: number;
+}
+export interface LegacyWitness {
+    id: string;
+    url: string;
+    claimAttestation?: AttestorClaimAttestation;
+}
+export interface AttestorClaimAttestation {
+    attestor_address: string;
+    claim_signature: string;
+    attestation_report: string;
+}
+export interface TeeAttestation {
+    proof_version?: 'v2' | 'v3';
+    proofVersion?: 'v2' | 'v3';
+    tee_provider: string;
+    tee_technology: string;
+    nonce: 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;
+    };
+}
+export interface TrustedData {
+    context: Record<string, unknown>;
+    extractedParameters: Record<string, string>;
+}
+export interface HashRequirement {
+    value: string | string[];
+    required?: boolean;
+    multiple?: boolean;
+}

package/lib/proof-types.js

@@ -0,0 +1 @@
+export {};

package/lib/proof-verification-error.d.ts

@@ -0,0 +1,13 @@
+export declare function legacyErrorClass(name: string): {
+    new (message?: string, innerError?: unknown): {
+        readonly innerError?: unknown;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};

package/lib/proof-verification-error.js

@@ -0,0 +1,11 @@
+export function legacyErrorClass(name) {
+    return class extends Error {
+        constructor(message, innerError) {
+            super(innerError
+                ? `${message ?? ''} caused by ${String(innerError)}`
+                : message);
+            this.name = name;
+            this.innerError = innerError;
+        }
+    };
+}

package/lib/reclaim.d.ts

@@ -25,13 +25,14 @@ import type { components } from './types/openapi.gen.ts';
 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'];
-/** The three terminal events a subscription can receive. */
-export declare const TERMINAL_EVENTS: readonly ["verification_success", "verification_rejected", "verification_error"];
+/** 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[];
@@ -44,8 +45,24 @@ export interface CreateSessionInput {
         version?: string;
     }[];
     context: Record<string, unknown>;
-    /** URL with a `{sessionId}` placeholder the end-user opens. */
+    /** Exact registered Verification Client base URL. 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.
+     *  Session creation returns only after Builder stores the signed binding. */
+    teeAttestation?: CreateSessionTeeAttestation;
+}
+/** Options intentionally mirror legacy `verifyProof`'s `teeAttestation`
+ *  vocabulary. `timestamp` is decimal Unix milliseconds; omit it to use now. */
+export interface CreateSessionTeeAttestation {
+    appSecret: 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;
 }
 /** Input for `keypair.set`: the org's eth public key as uncompressed hex
  *  (`publicKey`, the form wallets/ethers emit) OR as a secp256k1 JWK
@@ -79,6 +96,11 @@ export interface Reclaim {
         /** 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>;
+        /** Add the immutable legacy-compatible TEE context after session
+         *  creation. Normally use
+         *  `sessions.create({ teeAttestation: { appSecret } })`; 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[]>;
     };
@@ -86,7 +108,7 @@ export interface Reclaim {
         /** 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 three terminal events. */
+         *  `events` defaults to all terminal lifecycle events. */
         register(input: Partial<RegisterCallbackInput> & Pick<RegisterCallbackInput, 'callbackUrl'>): Promise<CallbackSubscription>;
         list(): Promise<CallbackSubscription[]>;
         remove(subscriptionId: string): Promise<void>;
@@ -106,7 +128,7 @@ export interface Reclaim {
          *  the delivery is encrypted. */
         decrypt(body: CallbackBody, credential?: DecryptionKeyInput): Promise<Jws>;
         /** Verify a decrypted JWS: JWKS discovery, ES256K signature,
-         *  `reclaimSessionId`/`aud`/`exp`, nested attestor proofs. */
+         *  `reclaimSessionId`/`aud`, any legacy `exp`, and exact legacy 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