@reclaimprotocol/client 0.1.27 → 0.1.28

package/src/tee-binding.ts

@@ -0,0 +1,192 @@
+/**
+ * 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.ts'
+import { bytesToHex } from './encoding.ts'
+import { deriveFromPrivateKey } from './keypair.ts'
+
+/** 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'
+
+/** 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 function legacyApplicationIdFromPrivateKey(privateKey: string): string {
+	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: string,
+	data: Pick<LegacyTeeNonceData, 'applicationId' | 'sessionId' | 'timestamp'>,
+): string {
+	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: string,
+	data: Pick<LegacyTeeNonceData, 'applicationId' | 'sessionId' | 'timestamp'>,
+): string {
+	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: {
+	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 {
+	const attestationNonceData: LegacyTeeNonceData = {
+		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: BuilderTeeBindingPayload,
+): string {
+	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: BuilderTeeBindingPayload,
+	organizationVerificationPrivateKey: string,
+): string {
+	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: {
+	organizationId: string
+	organizationVerificationPrivateKey: string
+	sessionId: string
+	timestamp: string
+	nonceMode?: LegacyTeeNonceMode
+}): BuilderTeeBinding {
+	const context = createLegacyTeeNonceContext(input)
+	const payload: BuilderTeeBindingPayload = {
+		organizationId: input.organizationId,
+		...context,
+	}
+	return {
+		...payload,
+		payload: builderTeeBindingPayload(payload),
+		signature: signBuilderTeeBinding(
+			payload,
+			input.organizationVerificationPrivateKey,
+		),
+	}
+}