@tanstack/ai-client 0.25.2 → 0.28.0

package/dist/esm/byok/passkey.js

@@ -0,0 +1,251 @@
+import { memoryStorage } from "./storage.js";
+import { isProviderId } from "@tanstack/ai/byok";
+//#region src/byok/passkey.ts
+/**
+* Passkey-encrypted keyring storage (WebAuthn PRF → HKDF → AES-256-GCM).
+*
+* The keyring is encrypted at rest in IndexedDB with an AES-256-GCM key derived
+* from a passkey's PRF output, unwrapped on demand with a biometric/PIN tap.
+* Decryption happens entirely client-side with the user present — no server,
+* no custodian.
+*
+* Honest scope: this protects against at-rest theft (stolen device,
+* storage-dumping extension, backups). It does NOT defeat live in-page XSS —
+* an attacker running JS in the origin after the user unlocks can read the
+* decrypted keys from memory.
+*/
+var STORE_NAME = "keyring";
+var RECORD_ID = "default";
+var HKDF_INFO = "byok:keyring:v1";
+var DEFAULT_DB = "byok";
+function sanitizeKeyring(value) {
+	if (typeof value !== "object" || value === null) return {};
+	const keys = {};
+	for (const [provider, key] of Object.entries(value)) if (isProviderId(provider) && typeof key === "string" && key.length > 0) keys[provider] = key;
+	return keys;
+}
+/** Build the non-sensitive `provider → last 4` preview from a keyring. */
+function previewOf(keys) {
+	const preview = {};
+	for (const [provider, key] of Object.entries(keys)) {
+		if (!key || !isProviderId(provider)) continue;
+		preview[provider] = key.length > 4 ? key.slice(-4) : "";
+	}
+	return preview;
+}
+/**
+* Whether the current environment exposes WebAuthn. Actual PRF support can
+* only be confirmed during registration; `passkeyStorage` throws if the
+* chosen authenticator does not support PRF.
+*/
+function isPasskeyStorageSupported() {
+	return typeof globalThis !== "undefined" && typeof globalThis.PublicKeyCredential !== "undefined" && typeof globalThis.navigator !== "undefined" && typeof globalThis.navigator.credentials.create === "function";
+}
+/** Derive a non-extractable AES-256-GCM key from a 32-byte PRF output. */
+async function deriveAesKey(prfOutput) {
+	const base = await crypto.subtle.importKey("raw", prfOutput, "HKDF", false, ["deriveKey"]);
+	return crypto.subtle.deriveKey({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: /* @__PURE__ */ new Uint8Array(0),
+		info: new TextEncoder().encode(HKDF_INFO)
+	}, base, {
+		name: "AES-GCM",
+		length: 256
+	}, false, ["encrypt", "decrypt"]);
+}
+async function encryptKeyring(key, keys) {
+	const iv = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(12));
+	const plaintext = new TextEncoder().encode(JSON.stringify(keys));
+	const ciphertext = await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, key, plaintext);
+	return {
+		iv: iv.buffer,
+		ciphertext
+	};
+}
+async function decryptKeyring(key, iv, ciphertext) {
+	const plaintext = await crypto.subtle.decrypt({
+		name: "AES-GCM",
+		iv
+	}, key, ciphertext);
+	return sanitizeKeyring(JSON.parse(new TextDecoder().decode(plaintext)));
+}
+function openDb(dbName) {
+	return new Promise((resolve, reject) => {
+		const request = indexedDB.open(dbName, 1);
+		request.onupgradeneeded = () => {
+			request.result.createObjectStore(STORE_NAME, { keyPath: "id" });
+		};
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+function idbGet(dbName) {
+	return openDb(dbName).then((db) => new Promise((resolve, reject) => {
+		const request = db.transaction(STORE_NAME, "readonly").objectStore(STORE_NAME).get(RECORD_ID);
+		request.onsuccess = () => resolve(request.result ?? null);
+		request.onerror = () => reject(request.error);
+	}));
+}
+function idbPut(dbName, record) {
+	return openDb(dbName).then((db) => new Promise((resolve, reject) => {
+		const tx = db.transaction(STORE_NAME, "readwrite");
+		tx.objectStore(STORE_NAME).put(record);
+		tx.oncomplete = () => resolve();
+		tx.onerror = () => reject(tx.error);
+	}));
+}
+function idbClear(dbName) {
+	return openDb(dbName).then((db) => new Promise((resolve, reject) => {
+		const tx = db.transaction(STORE_NAME, "readwrite");
+		tx.objectStore(STORE_NAME).delete(RECORD_ID);
+		tx.oncomplete = () => resolve();
+		tx.onerror = () => reject(tx.error);
+	}));
+}
+function requirePublicKeyCredential(credential, action) {
+	if (!credential) throw new Error(`Passkey ${action} was cancelled`);
+	if (!(credential instanceof PublicKeyCredential)) throw new Error(`Unexpected credential type during ${action}`);
+	return credential;
+}
+async function registerPasskey(rpName, userName, rpId) {
+	const salt = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32));
+	const credential = requirePublicKeyCredential(await navigator.credentials.create({ publicKey: {
+		challenge: crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32)),
+		rp: rpId ? {
+			name: rpName,
+			id: rpId
+		} : { name: rpName },
+		user: {
+			id: crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)),
+			name: userName,
+			displayName: userName
+		},
+		pubKeyCredParams: [{
+			type: "public-key",
+			alg: -7
+		}, {
+			type: "public-key",
+			alg: -257
+		}],
+		authenticatorSelection: {
+			residentKey: "required",
+			userVerification: "required"
+		},
+		extensions: { prf: { eval: { first: salt } } }
+	} }), "registration");
+	const prf = credential.getClientExtensionResults().prf;
+	if (!prf?.enabled) throw new Error("This authenticator does not support the WebAuthn PRF extension");
+	return {
+		credentialId: credential.rawId,
+		salt,
+		prf: prf.results?.first
+	};
+}
+async function evaluatePrf(credentialId, salt) {
+	const result = requirePublicKeyCredential(await navigator.credentials.get({ publicKey: {
+		challenge: crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32)),
+		allowCredentials: [{
+			type: "public-key",
+			id: credentialId
+		}],
+		userVerification: "required",
+		extensions: { prf: { eval: { first: salt } } }
+	} }), "unlock").getClientExtensionResults().prf?.results?.first;
+	if (!result) throw new Error("Authenticator did not return a PRF result");
+	return result;
+}
+/**
+* Passkey-encrypted persistence. `ByokClient` treats this as `unlockable`, so
+* nothing is decrypted until the user calls `unlock()` (or saves a key, which
+* registers a passkey on first use). The derived key is cached in memory for
+* the session so repeated saves don't re-prompt.
+*/
+function passkeyStorage(options = {}) {
+	const rpName = options.rpName ?? "BYOK";
+	const userName = options.userName ?? "byok-keyring";
+	const { rpId } = options;
+	const dbName = options.dbName ?? DEFAULT_DB;
+	let cachedKey = null;
+	let cachedMeta = null;
+	async function ensureKey() {
+		if (cachedKey && cachedMeta) return {
+			key: cachedKey,
+			...cachedMeta
+		};
+		const existing = await idbGet(dbName);
+		if (existing) {
+			cachedKey = await deriveAesKey(await evaluatePrf(existing.credentialId, existing.salt));
+			cachedMeta = {
+				credentialId: existing.credentialId,
+				salt: new Uint8Array(existing.salt)
+			};
+		} else {
+			const reg = await registerPasskey(rpName, userName, rpId);
+			cachedKey = await deriveAesKey(reg.prf ?? await evaluatePrf(reg.credentialId, reg.salt));
+			cachedMeta = {
+				credentialId: reg.credentialId,
+				salt: reg.salt
+			};
+		}
+		return {
+			key: cachedKey,
+			...cachedMeta
+		};
+	}
+	return {
+		id: "passkey",
+		label: "Passkey-encrypted (this device)",
+		persistent: true,
+		unlockable: true,
+		warning: "Keys are encrypted with your passkey and unlocked with biometrics. This protects saved keys if your device is stolen, but not against code running on this page after you unlock.",
+		peek: async () => {
+			return (await idbGet(dbName))?.preview ?? {};
+		},
+		load: async () => {
+			const existing = await idbGet(dbName);
+			if (!existing) return {};
+			const { key } = await ensureKey();
+			return decryptKeyring(key, existing.iv, existing.ciphertext);
+		},
+		save: async (keys) => {
+			const existing = await idbGet(dbName);
+			if (!Object.values(keys).some(Boolean) && !existing) return;
+			const { key, credentialId, salt } = await ensureKey();
+			const { iv, ciphertext } = await encryptKeyring(key, keys);
+			await idbPut(dbName, {
+				id: RECORD_ID,
+				credentialId,
+				salt: salt.buffer,
+				iv,
+				ciphertext,
+				preview: previewOf(keys)
+			});
+		},
+		clear: async () => {
+			cachedKey = null;
+			cachedMeta = null;
+			await idbClear(dbName);
+		}
+	};
+}
+/**
+* Passkey-encrypted storage when WebAuthn is available in a secure context.
+* Otherwise session memory, with a warning — this is not an automatic PRF
+* fallback. First save still throws if the authenticator lacks PRF.
+*/
+function defaultByokStorage(options) {
+	const secure = typeof globalThis.isSecureContext !== "boolean" || globalThis.isSecureContext;
+	if (!isPasskeyStorageSupported() || !secure) return {
+		...memoryStorage(),
+		warning: "Passkeys are unavailable in this context. Keys stay in memory for this tab only."
+	};
+	return passkeyStorage(options);
+}
+//#endregion
+export { decryptKeyring, defaultByokStorage, deriveAesKey, encryptKeyring, isPasskeyStorageSupported, passkeyStorage };
+
+//# sourceMappingURL=passkey.js.map

package/dist/esm/byok/passkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkey.js","names":[],"sources":["../../../src/byok/passkey.ts"],"sourcesContent":["import { isProviderId } from '@tanstack/ai/byok'\nimport { memoryStorage } from './storage'\nimport type { KeyPreview, Keyring, KeyringStorage } from './storage'\n\n/**\n * Passkey-encrypted keyring storage (WebAuthn PRF → HKDF → AES-256-GCM).\n *\n * The keyring is encrypted at rest in IndexedDB with an AES-256-GCM key derived\n * from a passkey's PRF output, unwrapped on demand with a biometric/PIN tap.\n * Decryption happens entirely client-side with the user present — no server,\n * no custodian.\n *\n * Honest scope: this protects against at-rest theft (stolen device,\n * storage-dumping extension, backups). It does NOT defeat live in-page XSS —\n * an attacker running JS in the origin after the user unlocks can read the\n * decrypted keys from memory.\n */\n\nconst STORE_NAME = 'keyring'\nconst RECORD_ID = 'default'\nconst HKDF_INFO = 'byok:keyring:v1'\nconst DEFAULT_DB = 'byok'\n\ninterface StoredRecord {\n  id: string\n  /** The passkey's raw credential id, replayed in the unlock ceremony. */\n  credentialId: ArrayBuffer\n  /** Fixed per-install PRF evaluation input (not secret). */\n  salt: ArrayBuffer\n  /** AES-GCM initialization vector for this ciphertext. */\n  iv: ArrayBuffer\n  /** Encrypted keyring JSON. */\n  ciphertext: ArrayBuffer\n  /**\n   * Unencrypted presence metadata (`provider → last 4`). Non-sensitive, so it\n   * can be read via {@link KeyringStorage.peek} without an unlock ceremony to\n   * show saved keys as \"locked\" after a refresh.\n   */\n  preview: KeyPreview\n}\n\nfunction sanitizeKeyring(value: unknown): Keyring {\n  if (typeof value !== 'object' || value === null) return {}\n  const keys: Keyring = {}\n  for (const [provider, key] of Object.entries(value)) {\n    if (isProviderId(provider) && typeof key === 'string' && key.length > 0) {\n      keys[provider] = key\n    }\n  }\n  return keys\n}\n\n/** Build the non-sensitive `provider → last 4` preview from a keyring. */\nfunction previewOf(keys: Keyring): KeyPreview {\n  const preview: KeyPreview = {}\n  for (const [provider, key] of Object.entries(keys)) {\n    if (!key || !isProviderId(provider)) continue\n    // Keys of length ≤ 4 would make last-4 the whole secret — store presence only.\n    preview[provider] = key.length > 4 ? key.slice(-4) : ''\n  }\n  return preview\n}\n\n/**\n * Whether the current environment exposes WebAuthn. Actual PRF support can\n * only be confirmed during registration; `passkeyStorage` throws if the\n * chosen authenticator does not support PRF.\n */\nexport function isPasskeyStorageSupported(): boolean {\n  return (\n    typeof globalThis !== 'undefined' &&\n    typeof globalThis.PublicKeyCredential !== 'undefined' &&\n    typeof globalThis.navigator !== 'undefined' &&\n    typeof globalThis.navigator.credentials.create === 'function'\n  )\n}\n\n// ---------------------------------------------------------------------------\n// Crypto (exported for testing; the WebAuthn ceremony below feeds `deriveAesKey`)\n// ---------------------------------------------------------------------------\n\n/** Derive a non-extractable AES-256-GCM key from a 32-byte PRF output. */\nexport async function deriveAesKey(\n  prfOutput: BufferSource,\n): Promise<CryptoKey> {\n  const base = await crypto.subtle.importKey('raw', prfOutput, 'HKDF', false, [\n    'deriveKey',\n  ])\n  return crypto.subtle.deriveKey(\n    {\n      name: 'HKDF',\n      hash: 'SHA-256',\n      salt: new Uint8Array(0),\n      info: new TextEncoder().encode(HKDF_INFO),\n    },\n    base,\n    { name: 'AES-GCM', length: 256 },\n    false,\n    ['encrypt', 'decrypt'],\n  )\n}\n\nexport async function encryptKeyring(\n  key: CryptoKey,\n  keys: Keyring,\n): Promise<{ iv: ArrayBuffer; ciphertext: ArrayBuffer }> {\n  const iv = crypto.getRandomValues(new Uint8Array(12))\n  const plaintext = new TextEncoder().encode(JSON.stringify(keys))\n  const ciphertext = await crypto.subtle.encrypt(\n    { name: 'AES-GCM', iv },\n    key,\n    plaintext,\n  )\n  return { iv: iv.buffer, ciphertext }\n}\n\nexport async function decryptKeyring(\n  key: CryptoKey,\n  iv: BufferSource,\n  ciphertext: BufferSource,\n): Promise<Keyring> {\n  const plaintext = await crypto.subtle.decrypt(\n    { name: 'AES-GCM', iv },\n    key,\n    ciphertext,\n  )\n  const parsed: unknown = JSON.parse(new TextDecoder().decode(plaintext))\n  return sanitizeKeyring(parsed)\n}\n\n// ---------------------------------------------------------------------------\n// IndexedDB\n// ---------------------------------------------------------------------------\n\nfunction openDb(dbName: string): Promise<IDBDatabase> {\n  return new Promise((resolve, reject) => {\n    const request = indexedDB.open(dbName, 1)\n    request.onupgradeneeded = () => {\n      request.result.createObjectStore(STORE_NAME, { keyPath: 'id' })\n    }\n    request.onsuccess = () => resolve(request.result)\n    request.onerror = () => reject(request.error)\n  })\n}\n\nfunction idbGet(dbName: string): Promise<StoredRecord | null> {\n  return openDb(dbName).then(\n    (db) =>\n      new Promise((resolve, reject) => {\n        const request = db\n          .transaction(STORE_NAME, 'readonly')\n          .objectStore(STORE_NAME)\n          .get(RECORD_ID)\n        request.onsuccess = () => resolve(request.result ?? null)\n        request.onerror = () => reject(request.error)\n      }),\n  )\n}\n\nfunction idbPut(dbName: string, record: StoredRecord): Promise<void> {\n  return openDb(dbName).then(\n    (db) =>\n      new Promise((resolve, reject) => {\n        const tx = db.transaction(STORE_NAME, 'readwrite')\n        tx.objectStore(STORE_NAME).put(record)\n        tx.oncomplete = () => resolve()\n        tx.onerror = () => reject(tx.error)\n      }),\n  )\n}\n\nfunction idbClear(dbName: string): Promise<void> {\n  return openDb(dbName).then(\n    (db) =>\n      new Promise((resolve, reject) => {\n        const tx = db.transaction(STORE_NAME, 'readwrite')\n        tx.objectStore(STORE_NAME).delete(RECORD_ID)\n        tx.oncomplete = () => resolve()\n        tx.onerror = () => reject(tx.error)\n      }),\n  )\n}\n\n// ---------------------------------------------------------------------------\n// WebAuthn ceremonies\n// ---------------------------------------------------------------------------\n\nfunction requirePublicKeyCredential(\n  credential: Credential | null,\n  action: string,\n): PublicKeyCredential {\n  if (!credential) throw new Error(`Passkey ${action} was cancelled`)\n  if (!(credential instanceof PublicKeyCredential)) {\n    throw new Error(`Unexpected credential type during ${action}`)\n  }\n  return credential\n}\n\nasync function registerPasskey(\n  rpName: string,\n  userName: string,\n  rpId?: string,\n): Promise<{\n  credentialId: ArrayBuffer\n  salt: Uint8Array<ArrayBuffer>\n  prf?: BufferSource\n}> {\n  const salt = crypto.getRandomValues(new Uint8Array(32))\n  const credential = requirePublicKeyCredential(\n    await navigator.credentials.create({\n      publicKey: {\n        challenge: crypto.getRandomValues(new Uint8Array(32)),\n        // Omit `id` to let the browser bind the passkey to the current origin's\n        // effective domain; set it to scope across subdomains of a self-host.\n        rp: rpId ? { name: rpName, id: rpId } : { name: rpName },\n        user: {\n          id: crypto.getRandomValues(new Uint8Array(16)),\n          name: userName,\n          displayName: userName,\n        },\n        pubKeyCredParams: [\n          { type: 'public-key', alg: -7 },\n          { type: 'public-key', alg: -257 },\n        ],\n        authenticatorSelection: {\n          residentKey: 'required',\n          userVerification: 'required',\n        },\n        extensions: { prf: { eval: { first: salt } } },\n      },\n    }),\n    'registration',\n  )\n\n  const prf = credential.getClientExtensionResults().prf\n  if (!prf?.enabled) {\n    throw new Error(\n      'This authenticator does not support the WebAuthn PRF extension',\n    )\n  }\n  return { credentialId: credential.rawId, salt, prf: prf.results?.first }\n}\n\nasync function evaluatePrf(\n  credentialId: BufferSource,\n  salt: BufferSource,\n): Promise<BufferSource> {\n  const credential = requirePublicKeyCredential(\n    await navigator.credentials.get({\n      publicKey: {\n        challenge: crypto.getRandomValues(new Uint8Array(32)),\n        allowCredentials: [{ type: 'public-key', id: credentialId }],\n        userVerification: 'required',\n        extensions: { prf: { eval: { first: salt } } },\n      },\n    }),\n    'unlock',\n  )\n  const result = credential.getClientExtensionResults().prf?.results?.first\n  if (!result) {\n    throw new Error('Authenticator did not return a PRF result')\n  }\n  return result\n}\n\n// ---------------------------------------------------------------------------\n// Storage strategy\n// ---------------------------------------------------------------------------\n\nexport interface PasskeyStorageOptions {\n  /** Relying-party name shown in the passkey prompt. */\n  rpName?: string\n  /** Username label attached to the created passkey. */\n  userName?: string\n  /**\n   * WebAuthn Relying Party ID. Omit to bind the passkey to the current origin's\n   * effective domain (the default — no central/hardcoded domain). Set it to a\n   * registrable parent domain to share the credential across subdomains of your\n   * own deployment. The encrypted keyring is never portable across unrelated\n   * domains.\n   */\n  rpId?: string\n  /** IndexedDB database name. Defaults to `byok`. */\n  dbName?: string\n}\n\n/**\n * Passkey-encrypted persistence. `ByokClient` treats this as `unlockable`, so\n * nothing is decrypted until the user calls `unlock()` (or saves a key, which\n * registers a passkey on first use). The derived key is cached in memory for\n * the session so repeated saves don't re-prompt.\n */\nexport function passkeyStorage(\n  options: PasskeyStorageOptions = {},\n): KeyringStorage {\n  const rpName = options.rpName ?? 'BYOK'\n  const userName = options.userName ?? 'byok-keyring'\n  const { rpId } = options\n  const dbName = options.dbName ?? DEFAULT_DB\n\n  let cachedKey: CryptoKey | null = null\n  let cachedMeta: {\n    credentialId: ArrayBuffer\n    salt: Uint8Array<ArrayBuffer>\n  } | null = null\n\n  // Obtain the AES key, running exactly one WebAuthn ceremony if it isn't\n  // already cached for this session (unlock if a passkey exists, else register).\n  async function ensureKey(): Promise<{\n    key: CryptoKey\n    credentialId: ArrayBuffer\n    salt: Uint8Array<ArrayBuffer>\n  }> {\n    if (cachedKey && cachedMeta) {\n      return { key: cachedKey, ...cachedMeta }\n    }\n    const existing = await idbGet(dbName)\n    if (existing) {\n      const prf = await evaluatePrf(existing.credentialId, existing.salt)\n      cachedKey = await deriveAesKey(prf)\n      cachedMeta = {\n        credentialId: existing.credentialId,\n        salt: new Uint8Array(existing.salt),\n      }\n    } else {\n      const reg = await registerPasskey(rpName, userName, rpId)\n      const prf = reg.prf ?? (await evaluatePrf(reg.credentialId, reg.salt))\n      cachedKey = await deriveAesKey(prf)\n      cachedMeta = { credentialId: reg.credentialId, salt: reg.salt }\n    }\n    return { key: cachedKey, ...cachedMeta }\n  }\n\n  return {\n    id: 'passkey',\n    label: 'Passkey-encrypted (this device)',\n    persistent: true,\n    unlockable: true,\n    warning:\n      'Keys are encrypted with your passkey and unlocked with biometrics. ' +\n      'This protects saved keys if your device is stolen, but not against code ' +\n      'running on this page after you unlock.',\n    peek: async () => {\n      // Unencrypted last-4 sidecar — no key material, no unlock ceremony.\n      const existing = await idbGet(dbName)\n      return existing?.preview ?? {}\n    },\n    load: async () => {\n      const existing = await idbGet(dbName)\n      if (!existing) return {}\n      const { key } = await ensureKey()\n      return decryptKeyring(key, existing.iv, existing.ciphertext)\n    },\n    save: async (keys) => {\n      const existing = await idbGet(dbName)\n      const hasKeys = Object.values(keys).some(Boolean)\n      // First save with an empty keyring is a no-op — avoids a passkey ceremony\n      // when another storage tier writes an empty ring.\n      if (!hasKeys && !existing) return\n\n      const { key, credentialId, salt } = await ensureKey()\n      const { iv, ciphertext } = await encryptKeyring(key, keys)\n      await idbPut(dbName, {\n        id: RECORD_ID,\n        credentialId,\n        salt: salt.buffer,\n        iv,\n        ciphertext,\n        preview: previewOf(keys),\n      })\n    },\n    clear: async () => {\n      cachedKey = null\n      cachedMeta = null\n      await idbClear(dbName)\n    },\n  }\n}\n\n/**\n * Passkey-encrypted storage when WebAuthn is available in a secure context.\n * Otherwise session memory, with a warning — this is not an automatic PRF\n * fallback. First save still throws if the authenticator lacks PRF.\n */\nexport function defaultByokStorage(\n  options?: PasskeyStorageOptions,\n): KeyringStorage {\n  const secure =\n    typeof globalThis.isSecureContext !== 'boolean' ||\n    globalThis.isSecureContext\n  if (!isPasskeyStorageSupported() || !secure) {\n    return {\n      ...memoryStorage(),\n      warning:\n        'Passkeys are unavailable in this context. Keys stay in memory for this tab only.',\n    }\n  }\n  return passkeyStorage(options)\n}\n"],"mappings":"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"}

package/dist/esm/byok/resolve.d.ts

@@ -0,0 +1,8 @@
+import { ProviderId } from '@tanstack/ai/byok';
+import { ByokClient } from './client.js';
+export declare function resolveByokProviderId(byokProvider: (() => string | undefined) | undefined, ...candidates: Array<unknown>): ProviderId | undefined;
+/**
+ * Prepare and stamp headers for one resolved slug. Throws instead of
+ * attaching every stored key when the slug is missing.
+ */
+export declare function prepareResolvedByokHeaders(byok: ByokClient, provider: ProviderId | undefined): Promise<Record<string, string>>;

package/dist/esm/byok/resolve.js

@@ -0,0 +1,20 @@
+import { ByokUnresolvedProviderError, isProviderId } from "@tanstack/ai/byok";
+//#region src/byok/resolve.ts
+function resolveByokProviderId(byokProvider, ...candidates) {
+	const fromFn = byokProvider?.();
+	if (isProviderId(fromFn)) return fromFn;
+	for (const candidate of candidates) if (isProviderId(candidate)) return candidate;
+}
+/**
+* Prepare and stamp headers for one resolved slug. Throws instead of
+* attaching every stored key when the slug is missing.
+*/
+async function prepareResolvedByokHeaders(byok, provider) {
+	if (!provider) throw new ByokUnresolvedProviderError();
+	await byok.prepare(provider);
+	return byok.headers(provider);
+}
+//#endregion
+export { prepareResolvedByokHeaders, resolveByokProviderId };
+
+//# sourceMappingURL=resolve.js.map

package/dist/esm/byok/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","names":[],"sources":["../../../src/byok/resolve.ts"],"sourcesContent":["import { ByokUnresolvedProviderError, isProviderId } from '@tanstack/ai/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\nimport type { ByokClient } from './client'\n\nexport function resolveByokProviderId(\n  byokProvider: (() => string | undefined) | undefined,\n  ...candidates: Array<unknown>\n): ProviderId | undefined {\n  const fromFn = byokProvider?.()\n  if (isProviderId(fromFn)) return fromFn\n  for (const candidate of candidates) {\n    if (isProviderId(candidate)) return candidate\n  }\n  return undefined\n}\n\n/**\n * Prepare and stamp headers for one resolved slug. Throws instead of\n * attaching every stored key when the slug is missing.\n */\nexport async function prepareResolvedByokHeaders(\n  byok: ByokClient,\n  provider: ProviderId | undefined,\n): Promise<Record<string, string>> {\n  if (!provider) {\n    throw new ByokUnresolvedProviderError()\n  }\n  await byok.prepare(provider)\n  return byok.headers(provider)\n}\n"],"mappings":";;AAIA,SAAgB,sBACd,cACA,GAAG,YACqB;CACxB,MAAM,SAAS,eAAe;CAC9B,IAAI,aAAa,MAAM,GAAG,OAAO;CACjC,KAAK,MAAM,aAAa,YACtB,IAAI,aAAa,SAAS,GAAG,OAAO;AAGxC;;;;;AAMA,eAAsB,2BACpB,MACA,UACiC;CACjC,IAAI,CAAC,UACH,MAAM,IAAI,4BAA4B;CAExC,MAAM,KAAK,QAAQ,QAAQ;CAC3B,OAAO,KAAK,QAAQ,QAAQ;AAC9B"}

package/dist/esm/byok/storage.d.ts

@@ -0,0 +1,15 @@
+import { ProviderId } from '@tanstack/ai/byok';
+export type Keyring = Partial<Record<ProviderId, string>>;
+export type KeyPreview = Partial<Record<ProviderId, string>>;
+export interface KeyringStorage {
+    readonly id: string;
+    readonly label: string;
+    readonly persistent: boolean;
+    readonly unlockable?: boolean;
+    readonly warning?: string;
+    peek?: () => KeyPreview | Promise<KeyPreview>;
+    load: () => Keyring | Promise<Keyring>;
+    save: (keys: Keyring) => void | Promise<void>;
+    clear: () => void | Promise<void>;
+}
+export declare function memoryStorage(): KeyringStorage;

package/dist/esm/byok/storage.js

@@ -0,0 +1,16 @@
+//#region src/byok/storage.ts
+function memoryStorage() {
+	return {
+		id: "memory",
+		label: "Session only (not saved)",
+		persistent: false,
+		warning: "Keys stay in memory for this tab only. They are not saved across reloads.",
+		load: () => ({}),
+		save: () => {},
+		clear: () => {}
+	};
+}
+//#endregion
+export { memoryStorage };
+
+//# sourceMappingURL=storage.js.map

package/dist/esm/byok/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":[],"sources":["../../../src/byok/storage.ts"],"sourcesContent":["import type { ProviderId } from '@tanstack/ai/byok'\n\nexport type Keyring = Partial<Record<ProviderId, string>>\nexport type KeyPreview = Partial<Record<ProviderId, string>>\n\nexport interface KeyringStorage {\n  readonly id: string\n  readonly label: string\n  readonly persistent: boolean\n  readonly unlockable?: boolean\n  readonly warning?: string\n  peek?: () => KeyPreview | Promise<KeyPreview>\n  load: () => Keyring | Promise<Keyring>\n  save: (keys: Keyring) => void | Promise<void>\n  clear: () => void | Promise<void>\n}\n\nexport function memoryStorage(): KeyringStorage {\n  return {\n    id: 'memory',\n    label: 'Session only (not saved)',\n    persistent: false,\n    warning:\n      'Keys stay in memory for this tab only. They are not saved across reloads.',\n    load: () => ({}),\n    save: () => {},\n    clear: () => {},\n  }\n}\n"],"mappings":";AAiBA,SAAgB,gBAAgC;CAC9C,OAAO;EACL,IAAI;EACJ,OAAO;EACP,YAAY;EACZ,SACE;EACF,aAAa,CAAC;EACd,YAAY,CAAC;EACb,aAAa,CAAC;CAChB;AACF"}

package/dist/esm/byok.d.ts

@@ -0,0 +1,8 @@
+export { defineByok, ByokClient, EMPTY_BYOK_SNAPSHOT } from './byok/client.js';
+export type { ByokPrompt, ByokSnapshot, DefineByokOptions, KeyStatus, } from './byok/client.js';
+export { defineByokProvider } from '@tanstack/ai/byok';
+export type { ByokProvider, ByokProviderInit } from '@tanstack/ai/byok';
+export { memoryStorage } from './byok/storage.js';
+export type { KeyPreview, Keyring, KeyringStorage } from './byok/storage.js';
+export { defaultByokStorage, decryptKeyring, deriveAesKey, encryptKeyring, isPasskeyStorageSupported, passkeyStorage, } from './byok/passkey.js';
+export type { PasskeyStorageOptions } from './byok/passkey.js';

package/dist/esm/byok.js

@@ -0,0 +1,5 @@
+import { memoryStorage } from "./byok/storage.js";
+import { ByokClient, EMPTY_BYOK_SNAPSHOT, defineByok } from "./byok/client.js";
+import { decryptKeyring, defaultByokStorage, deriveAesKey, encryptKeyring, isPasskeyStorageSupported, passkeyStorage } from "./byok/passkey.js";
+import { defineByokProvider } from "@tanstack/ai/byok";
+export { ByokClient, EMPTY_BYOK_SNAPSHOT, decryptKeyring, defaultByokStorage, defineByok, defineByokProvider, deriveAesKey, encryptKeyring, isPasskeyStorageSupported, memoryStorage, passkeyStorage };

package/dist/esm/chat-client.d.ts

@@ -1,4 +1,5 @@
 import { AnyClientTool, InterruptDefinition, ModelMessage, RunAgentResumeItem, StreamChunk } from '@tanstack/ai/client';
+import { ByokClient } from './byok.js';
 import { ConnectionAdapter } from './connection-adapters.js';
 import { BoundInterrupts, ChatClientOptions, ChatClientState, ChatFetcher, ChatInterruptState, ResolvableChatInterrupt, ChatResumeState, ConnectionStatus, MultimodalContent, QueueOption, QueueStrategy, QueuedMessage, SendMessageOptions, UIMessage, WhenBusy } from './types.js';
 type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = readonly []> = {
@@ -7,6 +8,8 @@ type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClien
     /** @deprecated Use `forwardedProps` instead. */
     body?: Record<string, any>;
     forwardedProps?: Record<string, any>;
+    byok?: ByokClient;
+    byokProvider?: () => string | undefined;
     tools?: TTools;
     interrupts?: TInterrupts;
     queue?: QueueOption;
@@ -67,6 +70,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private activeResumeRunId;
     private bodyOption;
     private forwardedPropsOption;
+    private byok;
+    private byokProvider;
     private context;
     private pendingMessageBody;
     private queueConfig;
@@ -320,8 +325,12 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      *   - A MultimodalContent object with content array and optional custom ID
      * @param body - Optional body parameters to merge with the client's base body for this request.
      *               Uses shallow merge with per-message body taking priority.
-     * @param sendOptions - Per-call overrides, e.g. `{ whenBusy: 'interrupt' }` to
-     *                      override the configured queue policy for this one send.
+     * @param sendOptions - Per-call overrides. `{ whenBusy }` overrides the
+     *                      queue policy for this one send. `{ body }`
+     *                      shallow-merges with `body` and with the chat-level
+     *                      `body` / `forwardedProps`. `sendOptions.body` wins
+     *                      on key collisions. Framework hooks forward this
+     *                      object as their second argument.
      *
      * @example
      * ```ts
@@ -331,9 +340,13 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * // Text message with custom body params
      * await client.sendMessage('Hello!', { temperature: 0.7 })
      *
-     * // Per-call whenBusy override (body must still be the 2nd arg on ChatClient)
+     * // Per-call whenBusy override
      * await client.sendMessage('Urgent', undefined, { whenBusy: 'interrupt' })
      *
+     * // Per-call body via options. Same effect as the positional arg.
+     * // This is the shape the framework hooks (`useChat`, `injectChat`) forward.
+     * await client.sendMessage('Hello!', undefined, { body: { temperature: 0.7 } })
+     *
      * // Multimodal message with image
      * await client.sendMessage({
      *   content: [
@@ -378,8 +391,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private decideWhenBusy;
     private enqueueMessage;
     /**
-     * Normalize the message input to extract content and optional id.
-     * Trims string content automatically.
+     * Normalize the message input to extract content, optional id, and
+     * optional metadata. String form has no metadata. Trims string content.
      */
     private normalizeMessageInput;
     /**