@reclaimprotocol/client 0.1.27 → 0.1.28

package/lib/tee-binding.d.ts

@@ -0,0 +1,82 @@
+/** The exact domain used by the legacy JS SDK's hash-based TEE nonce. */
+export declare const LEGACY_TEE_NONCE_DOMAIN = "RECLAIM_TEE_NONCE_V1";
+/** The version that legacy SDK clients put in `attestationNonceData`. */
+export declare const LEGACY_TEE_ATTESTATION_VERSION = "v3";
+/** Domain for the authenticated, Builder-specific nonce registration. */
+export declare const BUILDER_TEE_BINDING_DOMAIN = "RECLAIM_BUILDER_TEE_BINDING_V1";
+/** The exact nonce context shape preserved into an emitted legacy proof. */
+export interface LegacyTeeNonceData {
+    applicationId: string;
+    sessionId: string;
+    /** Decimal Unix milliseconds. Do not convert to Unix seconds. */
+    timestamp: string;
+    attestationVersion: typeof LEGACY_TEE_ATTESTATION_VERSION;
+}
+/** A legacy nonce and its context, forwarded unchanged by a VC. */
+export interface LegacyTeeNonceContext {
+    attestationNonce: string;
+    attestationNonceData: LegacyTeeNonceData;
+}
+export type LegacyTeeNonceMode = 'hash' | 'signature';
+/** Fields authenticated when registering a TEE binding with Builder. */
+export interface BuilderTeeBindingPayload extends LegacyTeeNonceContext {
+    organizationId: string;
+}
+/** Builder registration data. `signature` is EIP-191 / `personal_sign`. */
+export interface BuilderTeeBinding extends BuilderTeeBindingPayload {
+    payload: string;
+    signature: string;
+}
+/**
+ * Return the EIP-55 application ID a legacy verifier derives from an app
+ * secret. This is intentionally checksummed rather than the SDK's usual
+ * lowercase org address: the original SDK uses `ethers.Wallet(secret).address`.
+ */
+export declare function legacyApplicationIdFromPrivateKey(privateKey: string): string;
+/**
+ * Derive the exact 64-character lowercase nonce generated by the legacy SDK.
+ * `applicationId` is serialized byte-for-byte; it is deliberately not
+ * normalized here because legacy `generateAttestationNonce` does not normalize
+ * it either.
+ */
+export declare function deriveLegacyTeeNonce(appSecret: string, data: Pick<LegacyTeeNonceData, 'applicationId' | 'sessionId' | 'timestamp'>): string;
+/**
+ * Produce the older legacy nonce: an EIP-191 signature over
+ * `keccak256(applicationId:sessionId:timestamp)`. This is a nonce encoding,
+ * not a TEE attestation-version number; v2 and v3 attestations can carry it.
+ */
+export declare function deriveLegacySignatureTeeNonce(appSecret: string, data: Pick<LegacyTeeNonceData, 'applicationId' | 'sessionId' | 'timestamp'>): string;
+/**
+ * Create the legacy TEE context after Builder returns a session ID. Its
+ * application ID is derived from the same private key that later verifies the
+ * proof, so legacy TEE application binding succeeds without sending that key
+ * to Builder.
+ */
+export declare function createLegacyTeeNonceContext(input: {
+    organizationVerificationPrivateKey: string;
+    sessionId: string;
+    /** Decimal Unix milliseconds, typically `Date.now().toString()`. */
+    timestamp: string;
+    /** Defaults to the current hash nonce. Use `signature` for old clients. */
+    nonceMode?: LegacyTeeNonceMode;
+}): LegacyTeeNonceContext;
+/**
+ * Canonical payload for Builder TEE-binding registration. Every field is a
+ * string and the fixed field order avoids JSON canonicalization differences.
+ */
+export declare function builderTeeBindingPayload(payload: BuilderTeeBindingPayload): string;
+/** Sign a canonical Builder TEE-binding payload using EIP-191.
+ * `personal_sign` callers can use the returned signature directly. */
+export declare function signBuilderTeeBinding(payload: BuilderTeeBindingPayload, organizationVerificationPrivateKey: string): string;
+/**
+ * Create a nonce context and its signed Builder registration in one local,
+ * stateless operation. The private key appears only as a function input and is
+ * never included in the returned object.
+ */
+export declare function createBuilderTeeBinding(input: {
+    organizationId: string;
+    organizationVerificationPrivateKey: string;
+    sessionId: string;
+    timestamp: string;
+    nonceMode?: LegacyTeeNonceMode;
+}): BuilderTeeBinding;

package/lib/tee-binding.js

@@ -0,0 +1,112 @@
+/**
+ * Stateless helpers for registering an organization-owned, legacy-compatible
+ * TEE nonce with Builder after a verification session exists. The organization
+ * verification private key is used only locally: it derives the legacy app ID,
+ * produces the nonce, and signs the Builder registration payload.
+ */
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { signEip191 } from "./eip191.js";
+import { bytesToHex } from "./encoding.js";
+import { deriveFromPrivateKey } from "./keypair.js";
+/** The exact domain used by the legacy JS SDK's hash-based TEE nonce. */
+export const LEGACY_TEE_NONCE_DOMAIN = 'RECLAIM_TEE_NONCE_V1';
+/** The version that legacy SDK clients put in `attestationNonceData`. */
+export const LEGACY_TEE_ATTESTATION_VERSION = 'v3';
+/** Domain for the authenticated, Builder-specific nonce registration. */
+export const BUILDER_TEE_BINDING_DOMAIN = 'RECLAIM_BUILDER_TEE_BINDING_V1';
+/**
+ * Return the EIP-55 application ID a legacy verifier derives from an app
+ * secret. This is intentionally checksummed rather than the SDK's usual
+ * lowercase org address: the original SDK uses `ethers.Wallet(secret).address`.
+ */
+export function legacyApplicationIdFromPrivateKey(privateKey) {
+    const address = deriveFromPrivateKey(privateKey).address.slice(2);
+    const addressHash = bytesToHex(keccak_256(new TextEncoder().encode(address)));
+    const checksummed = [...address].map((char, index) => (Number.parseInt(addressHash[index], 16) >= 8
+        ? char.toUpperCase()
+        : char)).join('');
+    return '0x' + checksummed;
+}
+/**
+ * Derive the exact 64-character lowercase nonce generated by the legacy SDK.
+ * `applicationId` is serialized byte-for-byte; it is deliberately not
+ * normalized here because legacy `generateAttestationNonce` does not normalize
+ * it either.
+ */
+export function deriveLegacyTeeNonce(appSecret, data) {
+    const payload = [
+        LEGACY_TEE_NONCE_DOMAIN,
+        data.applicationId,
+        data.sessionId,
+        data.timestamp,
+        appSecret,
+    ].join(':');
+    return bytesToHex(keccak_256(new TextEncoder().encode(payload)));
+}
+/**
+ * Produce the older legacy nonce: an EIP-191 signature over
+ * `keccak256(applicationId:sessionId:timestamp)`. This is a nonce encoding,
+ * not a TEE attestation-version number; v2 and v3 attestations can carry it.
+ */
+export function deriveLegacySignatureTeeNonce(appSecret, data) {
+    const message = [data.applicationId, data.sessionId, data.timestamp].join(':');
+    return signEip191(keccak_256(new TextEncoder().encode(message)), appSecret);
+}
+/**
+ * Create the legacy TEE context after Builder returns a session ID. Its
+ * application ID is derived from the same private key that later verifies the
+ * proof, so legacy TEE application binding succeeds without sending that key
+ * to Builder.
+ */
+export function createLegacyTeeNonceContext(input) {
+    const attestationNonceData = {
+        applicationId: legacyApplicationIdFromPrivateKey(input.organizationVerificationPrivateKey),
+        sessionId: input.sessionId,
+        timestamp: input.timestamp,
+        attestationVersion: LEGACY_TEE_ATTESTATION_VERSION,
+    };
+    return {
+        attestationNonce: input.nonceMode === 'signature'
+            ? deriveLegacySignatureTeeNonce(input.organizationVerificationPrivateKey, attestationNonceData)
+            : deriveLegacyTeeNonce(input.organizationVerificationPrivateKey, attestationNonceData),
+        attestationNonceData,
+    };
+}
+/**
+ * Canonical payload for Builder TEE-binding registration. Every field is a
+ * string and the fixed field order avoids JSON canonicalization differences.
+ */
+export function builderTeeBindingPayload(payload) {
+    const { organizationId, attestationNonce, attestationNonceData } = payload;
+    return [
+        BUILDER_TEE_BINDING_DOMAIN,
+        organizationId,
+        attestationNonceData.sessionId,
+        attestationNonceData.applicationId,
+        attestationNonceData.timestamp,
+        attestationNonceData.attestationVersion,
+        attestationNonce,
+    ].join(':');
+}
+/** Sign a canonical Builder TEE-binding payload using EIP-191.
+ * `personal_sign` callers can use the returned signature directly. */
+export function signBuilderTeeBinding(payload, organizationVerificationPrivateKey) {
+    return signEip191(builderTeeBindingPayload(payload), organizationVerificationPrivateKey);
+}
+/**
+ * Create a nonce context and its signed Builder registration in one local,
+ * stateless operation. The private key appears only as a function input and is
+ * never included in the returned object.
+ */
+export function createBuilderTeeBinding(input) {
+    const context = createLegacyTeeNonceContext(input);
+    const payload = {
+        organizationId: input.organizationId,
+        ...context,
+    };
+    return {
+        ...payload,
+        payload: builderTeeBindingPayload(payload),
+        signature: signBuilderTeeBinding(payload, input.organizationVerificationPrivateKey),
+    };
+}