@tanstack/ai-client 0.26.0 → 0.28.0

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

@@ -0,0 +1,52 @@
+import { ProviderId } from '@tanstack/ai/byok';
+import { Keyring, KeyringStorage } from './storage.js';
+export type KeyStatus = {
+    state: 'empty';
+} | {
+    state: 'set';
+    masked: string;
+} | {
+    state: 'locked';
+    masked: string;
+} | {
+    state: 'error';
+    masked: string;
+    message: string;
+};
+export type ByokPrompt = {
+    provider: ProviderId;
+    reason: 'missing' | 'locked';
+};
+export type ByokSnapshot = {
+    status: Partial<Record<string, KeyStatus>>;
+    locked: boolean;
+    prompt: ByokPrompt | null;
+    storageError: string | null;
+};
+export interface DefineByokOptions {
+    storage?: KeyringStorage;
+}
+export declare const EMPTY_BYOK_SNAPSHOT: ByokSnapshot;
+export declare class ByokClient {
+    #private;
+    readonly storage: KeyringStorage;
+    constructor(options?: DefineByokOptions);
+    /** Resolves when constructor hydration (peek/load) finishes. */
+    ready: () => Promise<void>;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => ByokSnapshot;
+    keys(): Keyring;
+    request(provider: ProviderId, reason: ByokPrompt['reason']): void;
+    /**
+     * `true` — the server can fill any slug from env.
+     * `false` — no env coverage.
+     * A record merges per-id flags and clears the all/none boolean.
+     */
+    setServerCoverage(flags: boolean | Readonly<Record<string, boolean>>): void;
+    headers(provider?: ProviderId): Record<string, string>;
+    prepare(provider?: ProviderId): Promise<void>;
+    update(providerOrKey: ProviderId | string, key?: string): Promise<void>;
+    clear(provider?: ProviderId): Promise<void>;
+    unlock(): Promise<void>;
+}
+export declare function defineByok(options?: DefineByokOptions): ByokClient;

package/dist/esm/byok/client.js

@@ -0,0 +1,300 @@
+import { memoryStorage } from "./storage.js";
+import { ByokBlockedError, byokHeaderName, isProviderId, maskKey } from "@tanstack/ai/byok";
+//#region src/byok/client.ts
+var EMPTY_BYOK_SNAPSHOT = {
+	status: {},
+	locked: false,
+	prompt: null,
+	storageError: null
+};
+function requireProviderId(value) {
+	if (!isProviderId(value)) throw new Error(`Invalid BYOK provider id: ${value}`);
+	return value;
+}
+function errorMessage(error, fallback) {
+	return error instanceof Error && error.message.length > 0 ? error.message : fallback;
+}
+function isByokCeremonyCancel(error) {
+	if (typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "NotAllowedError") return true;
+	if (error instanceof Error) {
+		if (error.name === "NotAllowedError") return true;
+		const message = error.message.toLowerCase();
+		return message.includes("cancelled") || message.includes("not allowed");
+	}
+	return false;
+}
+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;
+}
+var ByokClient = class {
+	storage;
+	#keys = {};
+	#statuses = {};
+	#locked;
+	#prompt = null;
+	#coverageAll = false;
+	#coverage = {};
+	#listeners = /* @__PURE__ */ new Set();
+	#snapshot;
+	#storageError = null;
+	#ready;
+	constructor(options = {}) {
+		this.storage = options.storage ?? memoryStorage();
+		this.#locked = Boolean(this.storage.unlockable);
+		this.#snapshot = this.#buildSnapshot();
+		this.#ready = this.#hydrate();
+	}
+	/** Resolves when constructor hydration (peek/load) finishes. */
+	ready = () => this.#ready;
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	};
+	getSnapshot = () => this.#snapshot;
+	#buildSnapshot() {
+		return {
+			status: { ...this.#statuses },
+			locked: this.#locked,
+			prompt: this.#prompt,
+			storageError: this.#storageError
+		};
+	}
+	keys() {
+		return { ...this.#keys };
+	}
+	request(provider, reason) {
+		this.#prompt = {
+			provider: requireProviderId(provider),
+			reason
+		};
+		this.#emit();
+	}
+	/**
+	* `true` — the server can fill any slug from env.
+	* `false` — no env coverage.
+	* A record merges per-id flags and clears the all/none boolean.
+	*/
+	setServerCoverage(flags) {
+		if (typeof flags === "boolean") {
+			this.#coverageAll = flags;
+			this.#coverage = {};
+			return;
+		}
+		this.#coverageAll = false;
+		this.#coverage = {
+			...this.#coverage,
+			...flags
+		};
+	}
+	#hasCoverage(provider) {
+		return this.#coverageAll || this.#coverage[provider] === true;
+	}
+	headers(provider) {
+		const headers = {};
+		if (provider) {
+			requireProviderId(provider);
+			const key = this.#keys[provider];
+			if (key) headers[byokHeaderName(provider)] = key;
+			return headers;
+		}
+		for (const [id, key] of Object.entries(this.#keys)) if (key) headers[byokHeaderName(id)] = key;
+		return headers;
+	}
+	async prepare(provider) {
+		await this.#ready;
+		if (this.storage.unlockable && this.#locked) await this.unlock();
+		if (!provider) return;
+		requireProviderId(provider);
+		if (this.#keys[provider]) return;
+		if (this.#hasCoverage(provider)) return;
+		this.request(provider, "missing");
+		throw new ByokBlockedError(provider, "missing");
+	}
+	async update(providerOrKey, key) {
+		await this.#ready;
+		let provider;
+		let nextKey;
+		if (key === void 0) {
+			if (!this.#prompt) throw new Error("byok.update(key) cannot run when prompt is null");
+			provider = this.#prompt.provider;
+			nextKey = providerOrKey;
+		} else {
+			provider = requireProviderId(providerOrKey);
+			nextKey = key;
+		}
+		nextKey = nextKey.trim();
+		if (nextKey.length === 0) throw new Error("BYOK key must be non-empty");
+		if (this.storage.unlockable && this.#locked) await this.unlock();
+		const previousKeys = this.#keys;
+		const previousStatuses = { ...this.#statuses };
+		const previousLocked = this.#locked;
+		const previousPrompt = this.#prompt;
+		const previousStorageError = this.#storageError;
+		const next = {
+			...this.#keys,
+			[provider]: nextKey
+		};
+		try {
+			await this.storage.save(next);
+		} catch (error) {
+			this.#keys = previousKeys;
+			this.#statuses = previousStatuses;
+			this.#locked = previousLocked;
+			this.#prompt = previousPrompt;
+			this.#storageError = previousStorageError;
+			this.#statuses[provider] = {
+				state: "error",
+				masked: maskKey(nextKey),
+				message: errorMessage(error, `Failed to persist ${provider} key`)
+			};
+			this.#emit();
+			throw error;
+		}
+		this.#keys = next;
+		this.#statuses[provider] = {
+			state: "set",
+			masked: maskKey(nextKey)
+		};
+		this.#locked = false;
+		this.#prompt = null;
+		this.#storageError = null;
+		this.#emit();
+	}
+	async clear(provider) {
+		await this.#ready;
+		if (provider) {
+			requireProviderId(provider);
+			if (this.storage.unlockable && this.#locked) await this.unlock();
+			const previousKeys = this.#keys;
+			const previousStatuses = { ...this.#statuses };
+			const next = { ...this.#keys };
+			delete next[provider];
+			try {
+				await this.storage.save(next);
+			} catch (error) {
+				this.#keys = previousKeys;
+				this.#statuses = previousStatuses;
+				this.#emit();
+				throw error;
+			}
+			this.#keys = next;
+			delete this.#statuses[provider];
+			this.#emit();
+			return;
+		}
+		const previousKeys = this.#keys;
+		const previousStatuses = this.#statuses;
+		const previousLocked = this.#locked;
+		const previousPrompt = this.#prompt;
+		try {
+			await this.storage.clear();
+		} catch (error) {
+			this.#keys = previousKeys;
+			this.#statuses = previousStatuses;
+			this.#locked = previousLocked;
+			this.#prompt = previousPrompt;
+			this.#emit();
+			throw error;
+		}
+		this.#keys = {};
+		this.#statuses = {};
+		this.#locked = false;
+		this.#prompt = null;
+		this.#storageError = null;
+		this.#emit();
+	}
+	async unlock() {
+		await this.#ready;
+		if (!this.storage.unlockable) return;
+		try {
+			const loaded = sanitizeKeyring(await this.storage.load());
+			this.#keys = {
+				...loaded,
+				...this.#keys
+			};
+			for (const [id, value] of Object.entries(loaded)) {
+				if (!isProviderId(id) || !value) continue;
+				const existing = this.#statuses[id];
+				if (!existing || existing.state === "locked") this.#statuses[id] = {
+					state: "set",
+					masked: maskKey(value)
+				};
+			}
+			this.#locked = false;
+			this.#storageError = null;
+			this.#emit();
+		} catch (error) {
+			if (isByokCeremonyCancel(error)) {
+				const provider = this.#lockedProvider();
+				if (provider) {
+					this.request(provider, "locked");
+					throw new ByokBlockedError(provider, "locked");
+				}
+			}
+			this.#storageError = errorMessage(error, "Failed to unlock keyring");
+			this.#emit();
+			throw error instanceof Error ? error : new Error(String(error));
+		}
+	}
+	#lockedProvider() {
+		if (this.#prompt && isProviderId(this.#prompt.provider)) return this.#prompt.provider;
+		for (const [id, status] of Object.entries(this.#statuses)) if (status?.state === "locked" && isProviderId(id)) return id;
+	}
+	async #hydrate() {
+		if (this.storage.unlockable) {
+			if (!this.storage.peek) return;
+			try {
+				const preview = await this.storage.peek();
+				for (const [id, last4] of Object.entries(preview)) {
+					if (!isProviderId(id) || this.#statuses[id]) continue;
+					this.#statuses[id] = {
+						state: "locked",
+						masked: last4 ? last4 : "••"
+					};
+				}
+				this.#locked = Object.keys(preview).length > 0;
+				this.#storageError = null;
+				this.#emit();
+			} catch (error) {
+				this.#storageError = errorMessage(error, "Failed to read keyring");
+				this.#emit();
+			}
+			return;
+		}
+		try {
+			const loaded = sanitizeKeyring(await this.storage.load());
+			this.#keys = {
+				...loaded,
+				...this.#keys
+			};
+			for (const [id, value] of Object.entries(loaded)) {
+				if (!isProviderId(id) || !value) continue;
+				this.#statuses[id] = {
+					state: "set",
+					masked: maskKey(value)
+				};
+			}
+			this.#storageError = null;
+			this.#emit();
+		} catch (error) {
+			this.#storageError = errorMessage(error, "Failed to read keyring");
+			this.#emit();
+		}
+	}
+	#emit() {
+		this.#snapshot = this.#buildSnapshot();
+		for (const listener of this.#listeners) listener();
+	}
+};
+function defineByok(options = {}) {
+	return new ByokClient(options);
+}
+//#endregion
+export { ByokClient, EMPTY_BYOK_SNAPSHOT, defineByok };
+
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":["#listeners","#ready","#locked","#snapshot","#buildSnapshot","#hydrate","#statuses","#prompt","#storageError","#keys","#emit","#coverageAll","#coverage","#hasCoverage","#lockedProvider"],"sources":["../../../src/byok/client.ts"],"sourcesContent":["import {\n  ByokBlockedError,\n  byokHeaderName,\n  isProviderId,\n  maskKey,\n} from '@tanstack/ai/byok'\nimport { memoryStorage } from './storage'\nimport type { ProviderId } from '@tanstack/ai/byok'\nimport type { Keyring, KeyringStorage } from './storage'\n\nexport type KeyStatus =\n  | { state: 'empty' }\n  | { state: 'set'; masked: string }\n  | { state: 'locked'; masked: string }\n  | { state: 'error'; masked: string; message: string }\n\nexport type ByokPrompt = {\n  provider: ProviderId\n  reason: 'missing' | 'locked'\n}\n\nexport type ByokSnapshot = {\n  status: Partial<Record<string, KeyStatus>>\n  locked: boolean\n  prompt: ByokPrompt | null\n  storageError: string | null\n}\n\nexport interface DefineByokOptions {\n  storage?: KeyringStorage\n}\n\nexport const EMPTY_BYOK_SNAPSHOT: ByokSnapshot = {\n  status: {},\n  locked: false,\n  prompt: null,\n  storageError: null,\n}\n\nfunction requireProviderId(value: string): ProviderId {\n  if (!isProviderId(value)) {\n    throw new Error(`Invalid BYOK provider id: ${value}`)\n  }\n  return value\n}\n\nfunction errorMessage(error: unknown, fallback: string): string {\n  return error instanceof Error && error.message.length > 0\n    ? error.message\n    : fallback\n}\n\nfunction isByokCeremonyCancel(error: unknown): boolean {\n  if (\n    typeof DOMException !== 'undefined' &&\n    error instanceof DOMException &&\n    error.name === 'NotAllowedError'\n  ) {\n    return true\n  }\n  if (error instanceof Error) {\n    if (error.name === 'NotAllowedError') return true\n    const message = error.message.toLowerCase()\n    return message.includes('cancelled') || message.includes('not allowed')\n  }\n  return false\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\nexport class ByokClient {\n  readonly storage: KeyringStorage\n  #keys: Keyring = {}\n  #statuses: Partial<Record<string, KeyStatus>> = {}\n  #locked: boolean\n  #prompt: ByokPrompt | null = null\n  #coverageAll = false\n  #coverage: Record<string, boolean> = {}\n  readonly #listeners = new Set<() => void>()\n  #snapshot: ByokSnapshot\n  #storageError: string | null = null\n  readonly #ready: Promise<void>\n\n  constructor(options: DefineByokOptions = {}) {\n    this.storage = options.storage ?? memoryStorage()\n    this.#locked = Boolean(this.storage.unlockable)\n    this.#snapshot = this.#buildSnapshot()\n    this.#ready = this.#hydrate()\n  }\n\n  /** Resolves when constructor hydration (peek/load) finishes. */\n  ready = (): Promise<void> => this.#ready\n\n  subscribe = (listener: () => void): (() => void) => {\n    this.#listeners.add(listener)\n    return () => {\n      this.#listeners.delete(listener)\n    }\n  }\n\n  getSnapshot = (): ByokSnapshot => this.#snapshot\n\n  #buildSnapshot(): ByokSnapshot {\n    return {\n      status: { ...this.#statuses },\n      locked: this.#locked,\n      prompt: this.#prompt,\n      storageError: this.#storageError,\n    }\n  }\n\n  keys(): Keyring {\n    return { ...this.#keys }\n  }\n\n  request(provider: ProviderId, reason: ByokPrompt['reason']): void {\n    this.#prompt = { provider: requireProviderId(provider), reason }\n    this.#emit()\n  }\n\n  /**\n   * `true` — the server can fill any slug from env.\n   * `false` — no env coverage.\n   * A record merges per-id flags and clears the all/none boolean.\n   */\n  setServerCoverage(flags: boolean | Readonly<Record<string, boolean>>): void {\n    if (typeof flags === 'boolean') {\n      this.#coverageAll = flags\n      this.#coverage = {}\n      return\n    }\n    this.#coverageAll = false\n    this.#coverage = { ...this.#coverage, ...flags }\n  }\n\n  #hasCoverage(provider: string): boolean {\n    return this.#coverageAll || this.#coverage[provider] === true\n  }\n\n  headers(provider?: ProviderId): Record<string, string> {\n    const headers: Record<string, string> = {}\n    if (provider) {\n      requireProviderId(provider)\n      const key = this.#keys[provider]\n      if (key) headers[byokHeaderName(provider)] = key\n      return headers\n    }\n    for (const [id, key] of Object.entries(this.#keys)) {\n      if (key) headers[byokHeaderName(id)] = key\n    }\n    return headers\n  }\n\n  async prepare(provider?: ProviderId): Promise<void> {\n    await this.#ready\n    if (this.storage.unlockable && this.#locked) {\n      await this.unlock()\n    }\n    if (!provider) return\n    requireProviderId(provider)\n    if (this.#keys[provider]) return\n    if (this.#hasCoverage(provider)) return\n    this.request(provider, 'missing')\n    throw new ByokBlockedError(provider, 'missing')\n  }\n\n  async update(\n    providerOrKey: ProviderId | string,\n    key?: string,\n  ): Promise<void> {\n    await this.#ready\n    let provider: ProviderId\n    let nextKey: string\n    if (key === undefined) {\n      if (!this.#prompt) {\n        throw new Error('byok.update(key) cannot run when prompt is null')\n      }\n      provider = this.#prompt.provider\n      nextKey = providerOrKey\n    } else {\n      provider = requireProviderId(providerOrKey)\n      nextKey = key\n    }\n    nextKey = nextKey.trim()\n    if (nextKey.length === 0) {\n      throw new Error('BYOK key must be non-empty')\n    }\n    if (this.storage.unlockable && this.#locked) {\n      await this.unlock()\n    }\n    const previousKeys = this.#keys\n    const previousStatuses = { ...this.#statuses }\n    const previousLocked = this.#locked\n    const previousPrompt = this.#prompt\n    const previousStorageError = this.#storageError\n    const next = { ...this.#keys, [provider]: nextKey }\n    try {\n      await this.storage.save(next)\n    } catch (error) {\n      this.#keys = previousKeys\n      this.#statuses = previousStatuses\n      this.#locked = previousLocked\n      this.#prompt = previousPrompt\n      this.#storageError = previousStorageError\n      this.#statuses[provider] = {\n        state: 'error',\n        masked: maskKey(nextKey),\n        message: errorMessage(error, `Failed to persist ${provider} key`),\n      }\n      this.#emit()\n      throw error\n    }\n    this.#keys = next\n    this.#statuses[provider] = { state: 'set', masked: maskKey(nextKey) }\n    this.#locked = false\n    this.#prompt = null\n    this.#storageError = null\n    this.#emit()\n  }\n\n  async clear(provider?: ProviderId): Promise<void> {\n    await this.#ready\n    if (provider) {\n      requireProviderId(provider)\n      if (this.storage.unlockable && this.#locked) {\n        await this.unlock()\n      }\n      const previousKeys = this.#keys\n      const previousStatuses = { ...this.#statuses }\n      const next = { ...this.#keys }\n      delete next[provider]\n      try {\n        await this.storage.save(next)\n      } catch (error) {\n        this.#keys = previousKeys\n        this.#statuses = previousStatuses\n        this.#emit()\n        throw error\n      }\n      this.#keys = next\n      delete this.#statuses[provider]\n      this.#emit()\n      return\n    }\n    const previousKeys = this.#keys\n    const previousStatuses = this.#statuses\n    const previousLocked = this.#locked\n    const previousPrompt = this.#prompt\n    try {\n      await this.storage.clear()\n    } catch (error) {\n      this.#keys = previousKeys\n      this.#statuses = previousStatuses\n      this.#locked = previousLocked\n      this.#prompt = previousPrompt\n      this.#emit()\n      throw error\n    }\n    this.#keys = {}\n    this.#statuses = {}\n    this.#locked = false\n    this.#prompt = null\n    this.#storageError = null\n    this.#emit()\n  }\n\n  async unlock(): Promise<void> {\n    await this.#ready\n    if (!this.storage.unlockable) return\n    try {\n      const loaded = sanitizeKeyring(await this.storage.load())\n      this.#keys = { ...loaded, ...this.#keys }\n      for (const [id, value] of Object.entries(loaded)) {\n        if (!isProviderId(id) || !value) continue\n        const existing = this.#statuses[id]\n        if (!existing || existing.state === 'locked') {\n          this.#statuses[id] = { state: 'set', masked: maskKey(value) }\n        }\n      }\n      this.#locked = false\n      this.#storageError = null\n      this.#emit()\n    } catch (error) {\n      if (isByokCeremonyCancel(error)) {\n        const provider = this.#lockedProvider()\n        if (provider) {\n          this.request(provider, 'locked')\n          throw new ByokBlockedError(provider, 'locked')\n        }\n      }\n      this.#storageError = errorMessage(error, 'Failed to unlock keyring')\n      this.#emit()\n      throw error instanceof Error ? error : new Error(String(error))\n    }\n  }\n\n  #lockedProvider(): ProviderId | undefined {\n    if (this.#prompt && isProviderId(this.#prompt.provider)) {\n      return this.#prompt.provider\n    }\n    for (const [id, status] of Object.entries(this.#statuses)) {\n      if (status?.state === 'locked' && isProviderId(id)) return id\n    }\n    return undefined\n  }\n\n  async #hydrate(): Promise<void> {\n    if (this.storage.unlockable) {\n      if (!this.storage.peek) return\n      try {\n        const preview = await this.storage.peek()\n        for (const [id, last4] of Object.entries(preview)) {\n          if (!isProviderId(id) || this.#statuses[id]) continue\n          this.#statuses[id] = {\n            state: 'locked',\n            masked: last4 ? last4 : '••',\n          }\n        }\n        this.#locked = Object.keys(preview).length > 0\n        this.#storageError = null\n        this.#emit()\n      } catch (error) {\n        this.#storageError = errorMessage(error, 'Failed to read keyring')\n        this.#emit()\n      }\n      return\n    }\n    try {\n      const loaded = sanitizeKeyring(await this.storage.load())\n      this.#keys = { ...loaded, ...this.#keys }\n      for (const [id, value] of Object.entries(loaded)) {\n        if (!isProviderId(id) || !value) continue\n        this.#statuses[id] = { state: 'set', masked: maskKey(value) }\n      }\n      this.#storageError = null\n      this.#emit()\n    } catch (error) {\n      this.#storageError = errorMessage(error, 'Failed to read keyring')\n      this.#emit()\n    }\n  }\n\n  #emit(): void {\n    this.#snapshot = this.#buildSnapshot()\n    for (const listener of this.#listeners) listener()\n  }\n}\n\nexport function defineByok(options: DefineByokOptions = {}): ByokClient {\n  return new ByokClient(options)\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,43 @@
+import { Keyring, KeyringStorage } from './storage.js';
+/**
+ * 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.
+ */
+export declare function isPasskeyStorageSupported(): boolean;
+/** Derive a non-extractable AES-256-GCM key from a 32-byte PRF output. */
+export declare function deriveAesKey(prfOutput: BufferSource): Promise<CryptoKey>;
+export declare function encryptKeyring(key: CryptoKey, keys: Keyring): Promise<{
+    iv: ArrayBuffer;
+    ciphertext: ArrayBuffer;
+}>;
+export declare function decryptKeyring(key: CryptoKey, iv: BufferSource, ciphertext: BufferSource): Promise<Keyring>;
+export interface PasskeyStorageOptions {
+    /** Relying-party name shown in the passkey prompt. */
+    rpName?: string;
+    /** Username label attached to the created passkey. */
+    userName?: string;
+    /**
+     * WebAuthn Relying Party ID. Omit to bind the passkey to the current origin's
+     * effective domain (the default — no central/hardcoded domain). Set it to a
+     * registrable parent domain to share the credential across subdomains of your
+     * own deployment. The encrypted keyring is never portable across unrelated
+     * domains.
+     */
+    rpId?: string;
+    /** IndexedDB database name. Defaults to `byok`. */
+    dbName?: string;
+}
+/**
+ * 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.
+ */
+export declare function passkeyStorage(options?: PasskeyStorageOptions): KeyringStorage;
+/**
+ * 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.
+ */
+export declare function defaultByokStorage(options?: PasskeyStorageOptions): KeyringStorage;

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