@swal/vault 0.0.0-stage → 0.2.0

package/src/sealedPack.ts

@@ -0,0 +1,306 @@
+// sealedPack.ts — core reusable vault (antes en gara-g app-pwa)
+// Extraído a cores/swal-vault para reuso en gara-g, hosteler-ia, flota, cualquier app SWAL.
+// 100% cifrado: AES-256-GCM + Shamir 2-of-3 sobre DEK + SHA256 content_hash + Ed25519.
+// Cloudflare nunca ve plaintext, solo ciphertext+shares+hash.
+// Pay-per-use: costo solo si se sube a R2; mesh-only gratis (replica P2P en otros nodos gara-g).
+
+import {
+  bs, concatBytes, fromBase64, fromHex, randomBytes, randomInt, sha256, sha256Sync, toBase64, toHex, utf8,
+} from './bytes.js';
+
+const subtle = () => globalThis.crypto.subtle;
+
+// Cadena de anclaje por defecto (sin dependencia de @swal/econ-sdk; el vault es puro).
+const _econChain = 'polygon';
+const _econChainId = 137;
+
+/** Version de formato del pack. Ausente = legado (sin AAD). 2 = metadatos ligados como AAD de AES-GCM. */
+export const PACK_VERSION = 2;
+
+/**
+ * Lista blanca de metadatos que pueden viajar EN CLARO junto al pack. Todo lo que no este aqui
+ * se rechaza al sellar (salvo `extraClearKeys` explicito): los metadatos no van cifrados.
+ */
+export const CLEAR_METADATA_KEYS: readonly string[] = [
+  'vehicleId', 'entityId', 'entity', 'appId', 'instanceId', 'timestamp', 'recordCount', 'deviceId',
+];
+
+export interface DEKShare {
+  index: number;
+  value: string;
+}
+
+export interface SealedPackMetadata {
+  vehicleId?: string;
+  entityId?: string;
+  entity?: string;
+  appId?: string;
+  instanceId?: string;
+  timestamp: number;
+  recordCount?: number;
+  deviceId?: string;
+  // extensible para cualquier modelo negocio: gara-g vehicle, hosteler order, etc.
+  [k: string]: unknown;
+}
+
+export interface SealedPack {
+  /** Version de formato. Ausente = legado sin AAD. */
+  v?: number;
+  id: string;
+  content_hash: string;
+  ciphertext: string;
+  iv: string;
+  tag: string;
+  shares: DEKShare[];
+  signature: string;
+  publicKey: string;
+  metadata: SealedPackMetadata;
+  chain: string;
+  chainId: number;
+}
+
+function mod257(n: number): number {
+  const r = n % 257;
+  return r < 0 ? r + 257 : r;
+}
+function modInverse257(n: number): number {
+  const a = mod257(n);
+  if (a === 0) throw new Error('Division by zero GF257');
+  let res = 1;
+  let base = a;
+  let exp = 255;
+  while (exp > 0) {
+    if (exp % 2 === 1) res = (res * base) % 257;
+    base = (base * base) % 257;
+    exp = Math.floor(exp / 2);
+  }
+  return res;
+}
+
+export function splitDEK(dek: Uint8Array): DEKShare[] {
+  if (dek.length !== 32) throw new Error('DEK 32 bytes');
+  const s1 = new Uint8Array(32);
+  const s2 = new Uint8Array(32);
+  const s3 = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    const secret = dek[i];
+    let a1: number, y1: number, y2: number, y3: number;
+    do {
+      a1 = randomInt(1, 257);
+      y1 = mod257(secret + a1 * 1);
+      y2 = mod257(secret + a1 * 2);
+      y3 = mod257(secret + a1 * 3);
+    } while (y1 === 256 || y2 === 256 || y3 === 256);
+    s1[i] = y1;
+    s2[i] = y2;
+    s3[i] = y3;
+  }
+  return [
+    { index: 1, value: toBase64(s1) },
+    { index: 2, value: toBase64(s2) },
+    { index: 3, value: toBase64(s3) },
+  ];
+}
+
+export function reconstructDEK(shares: DEKShare[]): Uint8Array {
+  if (shares.length < 2) throw new Error('At least 2 shares are required to reconstruct DEK');
+  const s1 = shares[0], s2 = shares[1];
+  const x1 = s1.index, x2 = s2.index;
+  if (x1 === x2) throw new Error('shares duplicate x');
+  const y1 = fromBase64(s1.value);
+  const y2 = fromBase64(s2.value);
+  if (y1.length !== 32 || y2.length !== 32) throw new Error('share length 32');
+  const num1 = mod257(-x2), den1 = mod257(x1 - x2), L1 = mod257(num1 * modInverse257(den1));
+  const num2 = mod257(-x1), den2 = mod257(x2 - x1), L2 = mod257(num2 * modInverse257(den2));
+  const dek = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) dek[i] = mod257(y1[i] * L1 + y2[i] * L2);
+  return dek;
+}
+
+function canonicalJson(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(',')}]`;
+  if (v && typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    return `{${Object.keys(o).sort().filter((k) => o[k] !== undefined)
+      .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(v) ?? 'null';
+}
+
+/** AAD de AES-GCM (v2): los metadatos quedan autenticados; alterarlos rompe el descifrado. */
+function metadataAad(metadata: SealedPackMetadata): Uint8Array {
+  return utf8(`swal-vault/v${PACK_VERSION}|${canonicalJson(metadata)}`);
+}
+
+function assertMetadataWhitelisted(metadata: SealedPackMetadata, extra: readonly string[]): void {
+  const allowed = new Set([...CLEAR_METADATA_KEYS, ...extra]);
+  for (const k of Object.keys(metadata)) {
+    if (!allowed.has(k)) {
+      throw new Error(`Metadato "${k}" no esta en la lista blanca de metadatos en claro (usa extraClearKeys si es intencional)`);
+    }
+  }
+}
+
+function contentHashInput(ciphertext: Uint8Array, metadata: SealedPackMetadata): Uint8Array {
+  return concatBytes(ciphertext, utf8(JSON.stringify(metadata, Object.keys(metadata).sort())));
+}
+
+/**
+ * @deprecated Usa `computeContentHashAsync` (WebCrypto). Se mantiene sincrono (SHA-256 JS puro)
+ * solo por compatibilidad; produce el mismo resultado.
+ */
+export function computeContentHash(ciphertext: Uint8Array, metadata: SealedPackMetadata): string {
+  return '0x' + toHex(sha256Sync(contentHashInput(ciphertext, metadata)));
+}
+
+export async function computeContentHashAsync(ciphertext: Uint8Array, metadata: SealedPackMetadata): Promise<string> {
+  return '0x' + toHex(await sha256(contentHashInput(ciphertext, metadata)));
+}
+
+// ── Frontera de confianza: qué NO puede vivir en la nube ─────────────────────────
+//
+// El reparto es Shamir 2-de-3: con DOS shares cualquiera se reconstruye la DEK. Por tanto la nube
+// (R2 + D1 + KV) **nunca** puede acumular 2 shares, o el operador podria leer los datos y la
+// promesa "el operador no puede leer" seria falsa.
+//
+// Reparto correcto:
+//   * share x=1 -> DISPOSITIVO (nunca se sube)
+//   * share x=2 -> RECUPERACION (nunca se sube; se entrega al usuario en el alta)
+//   * share x=3 -> KV (unico share que la nube puede tener)
+//
+// Asi R2+D1+KV juntos suman 1 share y no alcanzan el umbral.
+
+/** Umbral de Shamir: shares necesarias para reconstruir. */
+export const SHAMIR_THRESHOLD = 2;
+
+/** Indice del unico share que puede residir en la nube. */
+export const CLOUD_SHARE_INDEX = 3;
+
+/** Devuelve una copia del pack SIN shares, apta para almacenar en la nube. */
+export function packWithoutShares(pack: SealedPack): SealedPack {
+  return { ...pack, shares: [] };
+}
+
+/** El share que puede subirse a KV (x=3). `null` si no existe. */
+export function cloudBoundShare(shares: DEKShare[]): DEKShare | null {
+  return shares.find((s) => s.index === CLOUD_SHARE_INDEX) ?? null;
+}
+
+/**
+ * Guarda de la frontera: lanza si la nube acumularia el umbral o mas shares.
+ * Se usa antes de subir nada, para fallar cerrado en vez de filtrar la clave.
+ */
+export function assertCloudSharesSafe(cloudShareCount: number): void {
+  if (cloudShareCount >= SHAMIR_THRESHOLD) {
+    throw new Error(
+      `E2EE: la nube no puede acumular ${cloudShareCount} shares (umbral ${SHAMIR_THRESHOLD}). ` +
+        'Deja en el dispositivo los shares 1 y 2 y sube solo el 3.',
+    );
+  }
+}
+
+/**
+ * Par de claves Ed25519. Acepta CryptoKeyPair (WebCrypto) o, por compat, el par de
+ * `KeyObject` de node (se detecta por duck-typing, sin depender de modulos de node).
+ */
+export type SealedPackKeyPair =
+  | CryptoKeyPair
+  | { privateKey: { export(o: { type: 'pkcs8'; format: 'der' }): Uint8Array }; publicKey: { export(o: { type: 'spki'; format: 'der' }): Uint8Array } };
+
+async function resolveKeyPair(kp?: SealedPackKeyPair): Promise<{ priv: CryptoKey; pubSpki: Uint8Array }> {
+  if (!kp) {
+    const pair = (await subtle().generateKey({ name: 'Ed25519' }, true, ['sign', 'verify'])) as CryptoKeyPair;
+    return { priv: pair.privateKey, pubSpki: new Uint8Array(await subtle().exportKey('spki', pair.publicKey)) };
+  }
+  const priv = kp.privateKey as any;
+  if (typeof priv.export === 'function') {
+    const pkcs8 = new Uint8Array(priv.export({ type: 'pkcs8', format: 'der' }));
+    const pubSpki = new Uint8Array((kp.publicKey as any).export({ type: 'spki', format: 'der' }));
+    return { priv: await subtle().importKey('pkcs8', bs(pkcs8), { name: 'Ed25519' }, false, ['sign']), pubSpki };
+  }
+  return { priv: priv as CryptoKey, pubSpki: new Uint8Array(await subtle().exportKey('spki', kp.publicKey as CryptoKey)) };
+}
+
+async function aesKey(dek: Uint8Array, usage: 'encrypt' | 'decrypt'): Promise<CryptoKey> {
+  return subtle().importKey('raw', bs(dek), { name: 'AES-GCM' }, false, [usage]);
+}
+
+export async function createSealedPack(
+  payload: Uint8Array,
+  metadata: SealedPackMetadata,
+  keyPair?: SealedPackKeyPair,
+  options: { extraClearKeys?: string[] } = {},
+): Promise<SealedPack> {
+  assertMetadataWhitelisted(metadata, options.extraClearKeys ?? []);
+  const dek = randomBytes(32);
+  const iv = randomBytes(12);
+  // WebCrypto devuelve ciphertext||tag(16); se separan para mantener el formato del pack.
+  const sealed = new Uint8Array(
+    await subtle().encrypt({ name: 'AES-GCM', iv: bs(iv), tagLength: 128, additionalData: bs(metadataAad(metadata)) }, await aesKey(dek, 'encrypt'), bs(payload)),
+  );
+  const ct = sealed.subarray(0, sealed.length - 16);
+  const tag = sealed.subarray(sealed.length - 16);
+  const shares = splitDEK(dek);
+  const contentHash = await computeContentHashAsync(ct, metadata);
+  const { priv, pubSpki } = await resolveKeyPair(keyPair);
+  const sig = new Uint8Array(await subtle().sign({ name: 'Ed25519' }, priv, bs(utf8(contentHash))));
+  return {
+    v: PACK_VERSION,
+    id: `pack-${globalThis.crypto.randomUUID()}`,
+    content_hash: contentHash,
+    ciphertext: toBase64(ct),
+    iv: toBase64(iv),
+    tag: toBase64(tag),
+    shares,
+    signature: toHex(sig),
+    publicKey: toHex(pubSpki),
+    metadata,
+    chain: _econChain,
+    chainId: _econChainId,
+  };
+}
+
+export async function unpackSealedPack(pack: SealedPack, shares: DEKShare[]): Promise<Uint8Array> {
+  const dek = reconstructDEK(shares);
+  const ct = fromBase64(pack.ciphertext);
+  const iv = fromBase64(pack.iv);
+  const tag = fromBase64(pack.tag);
+  if (pack.v !== undefined && pack.v !== PACK_VERSION) throw new Error(`Version de pack no soportada: ${pack.v}`);
+  // Legado (sin `v`): sin AAD. Un pack v2 al que se le quita `v` falla por tag al no coincidir el AAD.
+  const params: AesGcmParams = { name: 'AES-GCM', iv: bs(iv), tagLength: 128 };
+  if (pack.v === PACK_VERSION) params.additionalData = bs(metadataAad(pack.metadata));
+  const dec = await subtle().decrypt(
+    params,
+    await aesKey(dek, 'decrypt'),
+    bs(concatBytes(ct, tag)),
+  );
+  return new Uint8Array(dec);
+}
+
+export async function verifySealedPackHash(pack: SealedPack): Promise<boolean> {
+  const exp = await computeContentHashAsync(fromBase64(pack.ciphertext), pack.metadata);
+  return exp.toLowerCase() === pack.content_hash.toLowerCase();
+}
+
+/** Verifica la firma Ed25519 del content_hash con la publicKey del pack. */
+export async function verifySealedPackSignature(pack: SealedPack): Promise<boolean> {
+  try {
+    const key = await subtle().importKey('spki', bs(fromHex(pack.publicKey)), { name: 'Ed25519' }, false, ['verify']);
+    return await subtle().verify({ name: 'Ed25519' }, key, bs(fromHex(pack.signature)), bs(utf8(pack.content_hash)));
+  } catch {
+    return false;
+  }
+}
+
+// Helper generico para cualquier entity (no solo vehicle)
+export function packMetadataForEntity(entity: string, id: string, appId: string, instanceId: string): SealedPackMetadata {
+  return { entity, entityId: id, appId, instanceId, timestamp: Date.now() };
+}
+
+/**
+ * @deprecated Eliminado: la version anterior fabricaba un `walletAddress` falso (0x + prefijo de la
+ * publicKey) y emitia eventos con el. El anclaje real en Polygon aun no esta implementado.
+ */
+export function registerOnPolygon(_pack: SealedPack, _bus?: unknown): never {
+  throw new Error('registerOnPolygon: not implemented');
+}

package/src/web/vault-client.ts

@@ -0,0 +1,348 @@
+// web/vault-client.ts — VaultClient para navegador (PWA). Solo WebCrypto + IndexedDB.
+// Nunca realiza peticiones de red. Nada sale del dispositivo salvo lo que el llamador decida
+// hacer con el share de recuperacion o con la meshKey.
+//
+// Modelo de claves:
+//   * identidad de dispositivo: ECDSA P-256, CryptoKey NO extraible guardada en IndexedDB.
+//   * KEK (AES-GCM, no extraible): derivada de passphrase (PBKDF2-SHA256) o de passkey PRF (HKDF).
+//   * meshKey (32 bytes): se guarda siempre envuelta (AES-GCM) con la KEK.
+//   * recuperacion: Shamir 2-de-3 sobre la meshKey; share 1 queda en el dispositivo,
+//     share 2 se muestra una sola vez al usuario, share 3 se devuelve para custodia opcional.
+
+import { bs, fromBase64Url, randomBytes, sha256, toBase64Url, utf8 } from '../bytes.js';
+import { reconstructDEK, splitDEK, type DEKShare } from '../sealedPack.js';
+
+export const MIN_PBKDF2_ITERATIONS = 310_000;
+export const DEFAULT_PBKDF2_ITERATIONS = 600_000;
+
+export class VaultError extends Error {
+  constructor(
+    public code: 'LOCKED' | 'BAD_KEY' | 'BAD_FORMAT' | 'NO_PASSKEY' | 'SHARE_ALREADY_SHOWN' | 'NO_MESH_KEY' | 'BAD_PARAMS',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'VaultError';
+  }
+}
+
+/** Proveedor de salida PRF de un passkey (inyectable; por defecto usa WebAuthn). */
+export interface PasskeyPrfProvider {
+  /** Devuelve >=32 bytes deterministas para `salt`, o lanza si el autenticador no soporta PRF. */
+  getPrfOutput(salt: Uint8Array): Promise<Uint8Array>;
+}
+
+export interface VaultClientOptions {
+  storage: 'idb';
+  dbName?: string;
+  pbkdf2Iterations?: number;
+  passkey?: PasskeyPrfProvider;
+  /** Para WebAuthn por defecto. */
+  rpId?: string;
+}
+
+export interface DeviceIdentity {
+  deviceId: string;
+  /** SPKI en base64url. */
+  publicKey: string;
+  publicKeyJwk: JsonWebKey;
+}
+
+export type UnlockOptions = { passphrase: string } | { passkey: true };
+
+export interface MeshKey {
+  /** Bytes crudos (32). Evita retenerlos mas de lo necesario. */
+  raw: Uint8Array;
+  /** CryptoKey AES-GCM no extraible, derivada de los mismos bytes. */
+  key: CryptoKey;
+}
+
+export interface VaultClient {
+  getDeviceIdentity(): Promise<DeviceIdentity>;
+  sign(data: Uint8Array): Promise<Uint8Array>;
+  verify(publicKeyJwk: JsonWebKey, data: Uint8Array, signature: Uint8Array): Promise<boolean>;
+
+  /** Disponibilidad probable de passkeys (la confirmacion de PRF solo ocurre al usarlo). */
+  isPasskeyPrfAvailable(): boolean;
+  /** Deriva la KEK (passphrase o passkey PRF) y la mantiene en memoria. */
+  unlock(opts: UnlockOptions): Promise<void>;
+  /** Como unlock, pero con passkey si hay soporte; si no, usa passphrase. */
+  unlockPreferPasskey(passphrase: string): Promise<'passkey' | 'passphrase'>;
+  lock(): void;
+  isUnlocked(): boolean;
+
+  wrapKey(raw32: Uint8Array, kek?: CryptoKey): Promise<string>;
+  unwrapKey(wrapped: string, kek?: CryptoKey): Promise<Uint8Array>;
+
+  getOrCreateMeshKey(): Promise<MeshKey>;
+  /** Devuelve el share de recuperacion (x=2) UNA sola vez; luego lanza SHARE_ALREADY_SHOWN. */
+  exportRecoveryShare(): Promise<{ recoveryShare: DEKShare; cloudShare: DEKShare }>;
+  /** Reconstruye la meshKey con el share de recuperacion + el share del dispositivo. */
+  recoverMeshKey(recoveryShare: DEKShare): Promise<Uint8Array>;
+  /** Recupera la meshKey y la re-envuelve con una nueva passphrase. */
+  resetPassphrase(recoveryShare: DEKShare, newPassphrase: string): Promise<void>;
+}
+
+// ── IndexedDB mini wrapper ────────────────────────────────────────────────────
+
+const STORE = 'kv';
+
+function openDb(name: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(name, 1);
+    req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function tx<T>(db: IDBDatabase, mode: IDBTransactionMode, fn: (s: IDBObjectStore) => IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const t = db.transaction(STORE, mode);
+    const r = fn(t.objectStore(STORE));
+    t.oncomplete = () => resolve(r.result);
+    t.onerror = () => reject(t.error);
+    t.onabort = () => reject(t.error);
+  });
+}
+
+// ── Primitivas ────────────────────────────────────────────────────────────────
+
+const subtle = () => globalThis.crypto.subtle;
+
+async function kekFromPassphrase(passphrase: string, salt: Uint8Array, iterations: number): Promise<CryptoKey> {
+  const base = await subtle().importKey('raw', bs(utf8(passphrase.normalize('NFKC'))), 'PBKDF2', false, ['deriveKey']);
+  return subtle().deriveKey(
+    { name: 'PBKDF2', hash: 'SHA-256', salt: bs(salt), iterations },
+    base,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+async function kekFromPrf(prf: Uint8Array, salt: Uint8Array): Promise<CryptoKey> {
+  const base = await subtle().importKey('raw', bs(prf), 'HKDF', false, ['deriveKey']);
+  return subtle().deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: bs(salt), info: bs(utf8('swal-vault/kek/v1')) },
+    base,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+/** Formato: "v1.<iv b64url>.<ct+tag b64url>" */
+async function wrapWith(raw: Uint8Array, kek: CryptoKey): Promise<string> {
+  const iv = randomBytes(12);
+  const ct = new Uint8Array(await subtle().encrypt({ name: 'AES-GCM', iv: bs(iv) }, kek, bs(raw)));
+  return `v1.${toBase64Url(iv)}.${toBase64Url(ct)}`;
+}
+
+async function unwrapWith(wrapped: string, kek: CryptoKey): Promise<Uint8Array> {
+  const parts = wrapped.split('.');
+  if (parts.length !== 3 || parts[0] !== 'v1') throw new VaultError('BAD_FORMAT', 'formato de clave envuelta invalido');
+  try {
+    const pt = await subtle().decrypt(
+      { name: 'AES-GCM', iv: bs(fromBase64Url(parts[1])) },
+      kek,
+      bs(fromBase64Url(parts[2])),
+    );
+    return new Uint8Array(pt);
+  } catch {
+    throw new VaultError('BAD_KEY', 'no se pudo desenvolver la clave (KEK incorrecta o datos alterados)');
+  }
+}
+
+type Kv = {
+  get: <T>(k: string) => Promise<T | undefined>;
+  put: (k: string, v: unknown) => Promise<void>;
+};
+
+function defaultPasskeyProvider(kv: Kv, rpId?: string): PasskeyPrfProvider | undefined {
+  if (typeof PublicKeyCredential === 'undefined' || !globalThis.navigator?.credentials) return undefined;
+  return {
+    async getPrfOutput(salt) {
+      const cred = globalThis.navigator.credentials;
+      const idRaw = await kv.get<Uint8Array>('passkeyCredId');
+      const ext = { prf: { eval: { first: salt } } } as AuthenticationExtensionsClientInputs;
+      let credential: PublicKeyCredential | null;
+      if (!idRaw) {
+        credential = (await cred.create({
+          publicKey: {
+            rp: { name: 'SWAL Vault', ...(rpId ? { id: rpId } : {}) },
+            user: { id: bs(randomBytes(16)), name: 'swal-vault', displayName: 'SWAL Vault' },
+            challenge: bs(randomBytes(32)),
+            pubKeyCredParams: [{ type: 'public-key', alg: -7 }, { type: 'public-key', alg: -257 }],
+            authenticatorSelection: { residentKey: 'preferred', userVerification: 'required' },
+            extensions: { prf: {} } as AuthenticationExtensionsClientInputs,
+          },
+        })) as PublicKeyCredential | null;
+        if (!credential) throw new VaultError('NO_PASSKEY', 'creacion de passkey cancelada');
+        if (!(credential.getClientExtensionResults() as any).prf?.enabled)
+          throw new VaultError('NO_PASSKEY', 'el autenticador no soporta PRF');
+        await kv.put('passkeyCredId', new Uint8Array(credential.rawId));
+      }
+      const id = (await kv.get<Uint8Array>('passkeyCredId'))!;
+      const asr = (await cred.get({
+        publicKey: {
+          challenge: bs(randomBytes(32)),
+          allowCredentials: [{ type: 'public-key', id: bs(id) }],
+          userVerification: 'required',
+          extensions: ext,
+          ...(rpId ? { rpId } : {}),
+        },
+      })) as PublicKeyCredential | null;
+      const first = (asr?.getClientExtensionResults() as any)?.prf?.results?.first as ArrayBuffer | undefined;
+      if (!first) throw new VaultError('NO_PASSKEY', 'el passkey no devolvio salida PRF');
+      return new Uint8Array(first);
+    },
+  };
+}
+
+// ── Fabrica ───────────────────────────────────────────────────────────────────
+
+export function createVaultClient(opts: VaultClientOptions): VaultClient {
+  if (opts.storage !== 'idb') throw new VaultError('BAD_PARAMS', "solo storage: 'idb' esta soportado");
+  const iterations = opts.pbkdf2Iterations ?? DEFAULT_PBKDF2_ITERATIONS;
+  if (iterations < MIN_PBKDF2_ITERATIONS)
+    throw new VaultError('BAD_PARAMS', `pbkdf2Iterations debe ser >= ${MIN_PBKDF2_ITERATIONS}`);
+  const dbName = opts.dbName ?? 'swal-vault';
+
+  let dbp: Promise<IDBDatabase> | null = null;
+  const db = () => (dbp ??= openDb(dbName));
+  const get = async <T>(k: string): Promise<T | undefined> => (await tx(await db(), 'readonly', (s) => s.get(k))) as T | undefined;
+  const put = async (k: string, v: unknown): Promise<void> => {
+    await tx(await db(), 'readwrite', (s) => s.put(v, k));
+  };
+
+  const passkey = opts.passkey ?? defaultPasskeyProvider({ get, put }, opts.rpId);
+
+  let kek: CryptoKey | null = null;
+  const needKek = (k?: CryptoKey): CryptoKey => {
+    const v = k ?? kek;
+    if (!v) throw new VaultError('LOCKED', 'vault bloqueado: llama unlock() primero');
+    return v;
+  };
+
+  async function salt(): Promise<Uint8Array> {
+    let s = await get<Uint8Array>('kekSalt');
+    if (!s) {
+      s = randomBytes(16);
+      await put('kekSalt', s);
+    }
+    return s;
+  }
+
+  async function deriveKek(o: UnlockOptions): Promise<CryptoKey> {
+    const s = await salt();
+    if ('passkey' in o) {
+      if (!passkey) throw new VaultError('NO_PASSKEY', 'passkeys no disponibles en este entorno');
+      return kekFromPrf(await passkey.getPrfOutput(s), s);
+    }
+    return kekFromPassphrase(o.passphrase, s, iterations);
+  }
+
+  async function toMeshKey(raw: Uint8Array): Promise<MeshKey> {
+    const key = await subtle().importKey('raw', bs(raw), { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+    return { raw, key };
+  }
+
+  const self: VaultClient = {
+    async getDeviceIdentity() {
+      let pair = await get<CryptoKeyPair>('deviceKeyPair');
+      if (!pair) {
+        pair = (await subtle().generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign', 'verify'])) as CryptoKeyPair;
+        await put('deviceKeyPair', pair);
+      }
+      const spki = new Uint8Array(await subtle().exportKey('spki', pair.publicKey));
+      const publicKeyJwk = await subtle().exportKey('jwk', pair.publicKey);
+      return {
+        deviceId: toBase64Url((await sha256(spki)).subarray(0, 16)),
+        publicKey: toBase64Url(spki),
+        publicKeyJwk,
+      };
+    },
+
+    async sign(data) {
+      await self.getDeviceIdentity();
+      const pair = (await get<CryptoKeyPair>('deviceKeyPair'))!;
+      return new Uint8Array(await subtle().sign({ name: 'ECDSA', hash: 'SHA-256' }, pair.privateKey, bs(data)));
+    },
+
+    async verify(jwk, data, signature) {
+      const key = await subtle().importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+      return subtle().verify({ name: 'ECDSA', hash: 'SHA-256' }, key, bs(signature), bs(data));
+    },
+
+    isPasskeyPrfAvailable: () => !!passkey,
+
+    async unlock(o) {
+      const candidate = await deriveKek(o);
+      // Si ya existe meshKey, valida la KEK (falla con BAD_KEY si es incorrecta).
+      const wrapped = await get<string>('meshKeyWrapped');
+      if (wrapped) await unwrapWith(wrapped, candidate);
+      kek = candidate;
+    },
+
+    async unlockPreferPasskey(passphrase) {
+      if (passkey) {
+        try {
+          await self.unlock({ passkey: true });
+          return 'passkey';
+        } catch (e) {
+          if (!(e instanceof VaultError) || e.code !== 'NO_PASSKEY') {
+            // cancelacion del usuario u otro error de WebAuthn: cae a passphrase
+          }
+        }
+      }
+      await self.unlock({ passphrase });
+      return 'passphrase';
+    },
+
+    lock() {
+      kek = null;
+    },
+    isUnlocked: () => kek !== null,
+
+    wrapKey: (raw32, k) => {
+      if (raw32.length !== 32) throw new VaultError('BAD_PARAMS', 'se esperan 32 bytes');
+      return wrapWith(raw32, needKek(k));
+    },
+    unwrapKey: (wrapped, k) => unwrapWith(wrapped, needKek(k)),
+
+    async getOrCreateMeshKey() {
+      const k = needKek();
+      const wrapped = await get<string>('meshKeyWrapped');
+      if (wrapped) return toMeshKey(await unwrapWith(wrapped, k));
+      const raw = randomBytes(32);
+      await put('meshKeyWrapped', await wrapWith(raw, k));
+      return toMeshKey(raw);
+    },
+
+    async exportRecoveryShare() {
+      const { raw } = await self.getOrCreateMeshKey();
+      if (await get<boolean>('recoveryShown'))
+        throw new VaultError('SHARE_ALREADY_SHOWN', 'el share de recuperacion ya se mostro y no puede repetirse');
+      const [device, recoveryShare, cloudShare] = splitDEK(raw);
+      await put('deviceShare', device); // un solo share no revela nada (umbral 2)
+      await put('recoveryShown', true);
+      return { recoveryShare, cloudShare };
+    },
+
+    async recoverMeshKey(recoveryShare) {
+      const device = await get<DEKShare>('deviceShare');
+      if (!device) throw new VaultError('NO_MESH_KEY', 'no hay share de dispositivo');
+      return reconstructDEK([device, recoveryShare]);
+    },
+
+    async resetPassphrase(recoveryShare, newPassphrase) {
+      const raw = await self.recoverMeshKey(recoveryShare);
+      const s = randomBytes(16);
+      const newKek = await kekFromPassphrase(newPassphrase, s, iterations);
+      await put('kekSalt', s);
+      await put('meshKeyWrapped', await wrapWith(raw, newKek));
+      kek = newKek;
+    },
+  };
+  return self;
+}