@wishknish/knishio-client-ts 0.9.8 → 1.1.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import JsSHA from 'jssha';
-import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+import { ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
 import { cacheExchange, fetchExchange, subscriptionExchange, createClient as createClient$1, gql } from '@urql/core';
 import { createClient } from 'graphql-ws';
 import { pipe, subscribe } from 'wonka';
@@ -566,6 +566,14 @@ var init_SecretStorageException = __esm({
           }
         );
       }
+      /**
+       * Validation error for storage options or parameters
+       */
+      static validationError(message) {
+        return new _SecretStorageException(message, {
+          code: "VALIDATION_ERROR"
+        });
+      }
     };
   }
 });
@@ -3655,6 +3663,11 @@ var TokenUnit = class _TokenUnit {
     };
   }
 };
+var ML_KEM_PARAMS = {
+  1024: { kem: ml_kem1024, pkBytes: 1568, skBytes: 3168, ctBytes: 1568 },
+  768: { kem: ml_kem768, pkBytes: 1184, skBytes: 2400, ctBytes: 1088 }
+};
+var DEFAULT_ML_KEM_PARAMETER_SET = 1024;
 var Wallet = class _Wallet {
   token;
   balance;
@@ -3669,6 +3682,7 @@ var Wallet = class _Wallet {
   tokenUnits;
   tradeRates;
   molecules;
+  mlKemParameterSet;
   // Token metadata (populated from query responses)
   tokenName;
   tokenAmount;
@@ -3682,8 +3696,14 @@ var Wallet = class _Wallet {
     address = null,
     position = null,
     batchId = null,
-    characters = null
+    characters = null,
+    mlKemParameterSet = DEFAULT_ML_KEM_PARAMETER_SET
   } = {}) {
+    const paramSetNum = Number(mlKemParameterSet);
+    if (!ML_KEM_PARAMS[paramSetNum]) {
+      throw new Error(`KnishIO: unsupported ML-KEM parameter set ${mlKemParameterSet}; expected 1024 or 768.`);
+    }
+    this.mlKemParameterSet = paramSetNum;
     this.token = token;
     this.balance = "0";
     this.molecules = {};
@@ -3719,7 +3739,8 @@ var Wallet = class _Wallet {
     bundle = null,
     token = "USER",
     batchId = null,
-    characters = null
+    characters = null,
+    mlKemParameterSet = DEFAULT_ML_KEM_PARAMETER_SET
   }) {
     let position = null;
     if (!secret && !bundle) {
@@ -3735,7 +3756,8 @@ var Wallet = class _Wallet {
       token,
       position,
       batchId,
-      characters
+      characters,
+      mlKemParameterSet
     });
   }
   /**
@@ -3894,20 +3916,80 @@ var Wallet = class _Wallet {
     return (typeof this.position === "undefined" || this.position === null) && (typeof this.address === "undefined" || this.address === null);
   }
   // =============================================================================
-  // POST-QUANTUM CRYPTOGRAPHY - ML-KEM768 INTEGRATION
+  // POST-QUANTUM CRYPTOGRAPHY - ML-KEM INTEGRATION
   // =============================================================================
   /**
-   * Initializes the ML-KEM key pair (matches JavaScript SDK exactly)
+   * Derive an ML-KEM keypair for an arbitrary parameter set from the wallet's key seed,
+   * without mutating the wallet. The 64-byte `d‖z` seed takes no parameter-set input — only
+   * the final `keygen` call differs — so one KnishIO wallet owns both an ML-KEM-768 and an
+   * ML-KEM-1024 identity and either can be reconstructed on demand.
+   *
+   * Returns `null` when the wallet holds no key — a secret-less wallet, which is what a molecule
+   * deserializer builds for validation context. `generateSecret(null, …)` does NOT throw, so
+   * without this the wallet would derive a plausible-looking identity from a bogus seed and fail
+   * three layers down at AES-GCM instead of at the missing key. The guard lives here rather than
+   * at each call site so a new caller cannot miss it.
+   *
+   * @param parameterSet - 1024 or 768
    */
-  initializeMLKEM() {
+  deriveMlKemKeypair(parameterSet) {
+    const params = ML_KEM_PARAMS[parameterSet];
+    if (!params) {
+      throw new Error(`KnishIO: unsupported ML-KEM parameter set ${parameterSet}; expected 1024 or 768.`);
+    }
+    if (!this.key) {
+      return null;
+    }
     const seedHex = generateSecret(this.key, 128);
     const seed = new Uint8Array(64);
     for (let i = 0; i < 64; i++) {
       seed[i] = parseInt(seedHex.substr(i * 2, 2), 16);
     }
-    const { publicKey, secretKey } = ml_kem768.keygen(seed);
-    this.pubkey = this.serializeKey(publicKey);
-    this.privkey = secretKey;
+    const { publicKey, secretKey } = params.kem.keygen(seed);
+    return {
+      pubkey: this.serializeKey(publicKey),
+      privkey: secretKey,
+      params
+    };
+  }
+  /**
+   * ML-KEM parameter set implied by a serialized public key's raw byte length. FIPS 203's key
+   * lengths are disjoint (1568 bytes → ML-KEM-1024, 1184 bytes → ML-KEM-768), so a stored peer
+   * key recovers the parameter set of the session it belongs to without a wire-format change.
+   * Used by AuthToken.restore to resolve a snapshot that predates the field.
+   *
+   * @param pubkey - Base64-serialized ML-KEM public key
+   * @return 1024, 768, or null when the length matches neither
+   */
+  static mlKemParameterSetFromPubkey(pubkey) {
+    if (!pubkey) {
+      return null;
+    }
+    let byteLength;
+    try {
+      byteLength = typeof Buffer !== "undefined" ? Buffer.from(pubkey, "base64").length : atob(pubkey).length;
+    } catch {
+      return null;
+    }
+    if (byteLength === ML_KEM_PARAMS[1024].pkBytes) {
+      return 1024;
+    }
+    if (byteLength === ML_KEM_PARAMS[768].pkBytes) {
+      return 768;
+    }
+    return null;
+  }
+  /**
+   * Initializes the ML-KEM key pair (matches JavaScript SDK exactly). Only ever reached from the
+   * constructor's `secret` branch, so the derivation cannot come back empty here.
+   */
+  initializeMLKEM() {
+    const derived = this.deriveMlKemKeypair(this.mlKemParameterSet);
+    if (!derived) {
+      return;
+    }
+    this.pubkey = derived.pubkey;
+    this.privkey = derived.privkey;
   }
   // =============================================================================
   // HIGH-LEVEL MESSAGE ENCRYPTION (JavaScript SDK Compatibility)
@@ -3916,13 +3998,13 @@ var Wallet = class _Wallet {
     const messageString = JSON.stringify(message);
     const messageUint8 = new TextEncoder().encode(messageString);
     const deserializedPubkey = this.deserializeKey(recipientPubkey);
-    const ML_KEM_768_PUBLIC_KEY_BYTES = 1184;
-    if (deserializedPubkey.length !== ML_KEM_768_PUBLIC_KEY_BYTES) {
+    const params = ML_KEM_PARAMS[this.mlKemParameterSet];
+    if (deserializedPubkey.length !== params.pkBytes) {
       throw new Error(
-        `KnishIO: cannot ML-KEM-encrypt \u2014 recipient public key is ${deserializedPubkey.length} bytes, expected ${ML_KEM_768_PUBLIC_KEY_BYTES} (ML-KEM-768). The node likely did not advertise an ML-KEM public key (upgrade the validator to a PQ-transport build), or authenticate with { encrypt: false }.`
+        `KnishIO: cannot ML-KEM-encrypt \u2014 recipient public key is ${deserializedPubkey.length} bytes, expected ${params.pkBytes} (ML-KEM-${this.mlKemParameterSet}). The peer is not running ML-KEM-${this.mlKemParameterSet}; upgrade the peer, or step this client back to the other parameter set.`
       );
     }
-    const { cipherText, sharedSecret } = ml_kem768.encapsulate(deserializedPubkey);
+    const { cipherText, sharedSecret } = params.kem.encapsulate(deserializedPubkey);
     const encryptedMessage = await this.encryptWithSharedSecret(messageUint8, sharedSecret);
     return {
       cipherText: this.serializeKey(cipherText),
@@ -3934,15 +4016,37 @@ var Wallet = class _Wallet {
     return decryptedString === null ? null : JSON.parse(decryptedString);
   }
   /**
-   * ML-KEM768 decapsulate + AES-256-GCM decrypt → the RAW decrypted UTF-8 string (no JSON.parse).
+   * ML-KEM decapsulate + AES-256-GCM decrypt → the RAW decrypted UTF-8 string (no JSON.parse).
    * Shared by {@link decryptMessage} (which JSON.parses the result) and the PQ CipherHash transport
-   * ({@link decryptMyMessageML768}, which needs the raw response JSON text). PQ-transport Phase E.
+   * ({@link decryptMyMessageML}, which needs the raw response JSON text). PQ-transport Phase E.
    */
   async _mlkemDecryptToString(encryptedData) {
     const { cipherText, encryptedMessage } = encryptedData;
+    const configuredParams = ML_KEM_PARAMS[this.mlKemParameterSet];
+    const otherSet = this.mlKemParameterSet === 1024 ? 768 : 1024;
+    const deserializedCipherText = this.deserializeKey(cipherText);
+    let params = configuredParams;
+    let decapsPrivkey = this.privkey;
+    if (deserializedCipherText.length !== configuredParams.ctBytes) {
+      if (deserializedCipherText.length !== ML_KEM_PARAMS[otherSet].ctBytes) {
+        console.error(
+          `Wallet::decryptMessage() - Ciphertext length mismatch: got ${deserializedCipherText.length}, expected ${configuredParams.ctBytes}`
+        );
+        return null;
+      }
+      const derived = this.deriveMlKemKeypair(otherSet);
+      if (!derived) {
+        console.error(
+          `Wallet::decryptMessage() - cannot derive the ML-KEM-${otherSet} identity: wallet has no key`
+        );
+        return null;
+      }
+      params = derived.params;
+      decapsPrivkey = derived.privkey;
+    }
     let sharedSecret;
     try {
-      sharedSecret = ml_kem768.decapsulate(this.deserializeKey(cipherText), this.privkey);
+      sharedSecret = params.kem.decapsulate(deserializedCipherText, decapsPrivkey);
     } catch (e) {
       console.error("Wallet::decryptMessage() - Decapsulation failed", e);
       console.info("Wallet::decryptMessage() - my public key", this.pubkey);
@@ -3992,11 +4096,11 @@ var Wallet = class _Wallet {
     return this.serializeKey(bytes);
   }
   /**
-   * Post-quantum (ML-KEM768) CipherHash request envelope: a stringified single-recipient map
+   * Post-quantum (ML-KEM) CipherHash request envelope: a stringified single-recipient map
    * `{ "<hashShare(recipientPubkey)>": {cipherText, encryptedMessage} }` (object-valued, via
    * {@link encryptMessage}). Matches the Rust validator's CipherHash handler. PQ-transport Phase E.
    */
-  async encryptStringML768(message, recipientPubkey) {
+  async encryptStringML(message, recipientPubkey) {
     const envelope = await this.encryptMessage(message, recipientPubkey);
     return JSON.stringify({ [this.hashShare(recipientPubkey)]: envelope });
   }
@@ -4004,9 +4108,21 @@ var Wallet = class _Wallet {
    * Decrypt a CipherHash response map addressed to THIS wallet's ML-KEM pubkey
    * (`hashShare(this.pubkey)`) → the RAW decrypted GraphQL response JSON text (NOT JSON.parsed;
    * it replaces the HTTP response body for the normal parser). `null` if no entry / decrypt fails.
+   *
+   * A pre-bump peer addressed its envelope to `hashShare(our_768_pubkey)`, which a wallet
+   * configured at ML-KEM-1024 would never find — so the other identity's share is tried too.
+   * Without this, the permissive length dispatch in {@link _mlkemDecryptToString} is
+   * unreachable on the transport path.
    */
-  async decryptMyMessageML768(map) {
-    const envelope = map[this.hashShare(this.pubkey)];
+  async decryptMyMessageML(map) {
+    let envelope = map[this.hashShare(this.pubkey)];
+    if (!envelope) {
+      const otherSet = this.mlKemParameterSet === 1024 ? 768 : 1024;
+      const other = this.deriveMlKemKeypair(otherSet);
+      if (other) {
+        envelope = map[this.hashShare(other.pubkey)];
+      }
+    }
     if (!envelope) {
       return null;
     }
@@ -4160,7 +4276,8 @@ z.object({
   serverSdkVersion: z.number().int().min(1).optional(),
   logging: z.boolean().optional(),
   defaultRequestPolicy: z.enum(["cache-first", "cache-only", "network-only", "cache-and-network"]).nullable().optional(),
-  secretStorage: z.unknown().optional()
+  secretStorage: z.unknown().optional(),
+  mlKemParameterSet: z.union([z.literal(1024), z.literal(768)]).optional()
 }).strict();
 z.object({
   token: z.string().min(1, "Auth token cannot be empty"),
@@ -5249,6 +5366,7 @@ var Molecule = class _Molecule {
   continuIdPosition;
   parentHashes;
   local;
+  mlKemParameterSet = 1024;
   /**
    * Create new Molecule instance
    * Matches JavaScript SDK constructor signature
@@ -5260,7 +5378,8 @@ var Molecule = class _Molecule {
     remainderWallet = null,
     cellSlug = null,
     version = null,
-    continuIdPosition = null
+    continuIdPosition = null,
+    mlKemParameterSet = null
   } = {}) {
     this.status = null;
     this.molecularHash = null;
@@ -5272,6 +5391,7 @@ var Molecule = class _Molecule {
     this.continuIdPosition = continuIdPosition;
     this.atoms = [];
     this.parentHashes = [];
+    this.mlKemParameterSet = mlKemParameterSet || sourceWallet?.mlKemParameterSet || 1024;
     const versionRegistry = versions_default;
     if (version !== null && Object.prototype.hasOwnProperty.call(versionRegistry, version)) {
       this.version = String(version);
@@ -5282,7 +5402,8 @@ var Molecule = class _Molecule {
         bundle,
         token: sourceWallet.token,
         batchId: sourceWallet.batchId,
-        characters: sourceWallet.characters
+        characters: sourceWallet.characters,
+        mlKemParameterSet: this.mlKemParameterSet
       });
     } else {
       this.remainderWallet = null;
@@ -5343,7 +5464,8 @@ var Molecule = class _Molecule {
     if (!this.remainderWallet || this.remainderWallet.token !== "USER") {
       this.remainderWallet = Wallet.create({
         secret: this.secret,
-        bundle: this.bundle
+        bundle: this.bundle,
+        mlKemParameterSet: this.mlKemParameterSet
       });
     }
     const continuIdMeta = {};
@@ -5730,7 +5852,8 @@ var Molecule = class _Molecule {
     }
     const burnWallet = new Wallet({
       bundle: "0000000000000000000000000000000000000000000000000000000000000000",
-      token: this.sourceWallet.token
+      token: this.sourceWallet.token,
+      mlKemParameterSet: this.mlKemParameterSet
     });
     this.addAtom(Atom.create({
       isotope: "V",
@@ -6002,7 +6125,8 @@ var Molecule = class _Molecule {
             position: data.sourceWallet.position,
             bundle: data.sourceWallet.bundle,
             batchId: data.sourceWallet.batchId,
-            characters: data.sourceWallet.characters
+            characters: data.sourceWallet.characters,
+            mlKemParameterSet: molecule.mlKemParameterSet
           });
           molecule.sourceWallet.balance = String(data.sourceWallet.balance != null ? data.sourceWallet.balance : 0);
           molecule.sourceWallet.address = data.sourceWallet.address;
@@ -6020,7 +6144,8 @@ var Molecule = class _Molecule {
             position: data.remainderWallet.position,
             bundle: data.remainderWallet.bundle,
             batchId: data.remainderWallet.batchId,
-            characters: data.remainderWallet.characters
+            characters: data.remainderWallet.characters,
+            mlKemParameterSet: molecule.mlKemParameterSet
           });
           molecule.remainderWallet.balance = String(data.remainderWallet.balance != null ? data.remainderWallet.balance : 0);
           molecule.remainderWallet.address = data.remainderWallet.address;
@@ -6118,7 +6243,8 @@ var Molecule = class _Molecule {
       secret: this.secret,
       bundle: this.bundle,
       token: this.sourceWallet.token,
-      batchId: this.sourceWallet.batchId
+      batchId: this.sourceWallet.batchId,
+      mlKemParameterSet: this.mlKemParameterSet
     });
     if (tradeRates) {
       bufferWallet.tradeRates = tradeRates;
@@ -6389,7 +6515,7 @@ var GraphQLClient = class {
     let encryptedRequest = false;
     let requestInit = init;
     if (wallet && serverPubkey && init && typeof init.body === "string" && this.shouldEncrypt(init.body)) {
-      const hashVar = await wallet.encryptStringML768(init.body, serverPubkey);
+      const hashVar = await wallet.encryptStringML(init.body, serverPubkey);
       requestInit = { ...init, body: JSON.stringify({ query: CIPHER_HASH_QUERY, variables: { Hash: hashVar } }) };
       encryptedRequest = true;
     }
@@ -6409,7 +6535,7 @@ var GraphQLClient = class {
     if (typeof hash !== "string") {
       return new Response(text, init2);
     }
-    const decrypted = await wallet.decryptMyMessageML768(JSON.parse(hash));
+    const decrypted = await wallet.decryptMyMessageML(JSON.parse(hash));
     return new Response(decrypted != null ? decrypted : text, init2);
   }
   setAuthData({
@@ -6578,6 +6704,22 @@ var AuthToken = class _AuthToken {
     authToken.setWallet(wallet);
     return authToken;
   }
+  /**
+   * ML-KEM parameter set a restored session must use, resolved in three tiers:
+   * an explicit snapshot field, then the stored validator key's length, then ML-KEM-768.
+   *
+   * The final tier is deliberately NOT the constructor default. A snapshot with neither an
+   * explicit field nor a recognisable key can only have come from a pre-bump build, and every
+   * pre-bump build was 768-only — defaulting to 1024 would make the restored wallet advertise
+   * a public key the validator never recorded for that token.
+   */
+  static resolveMlKemParameterSet(snapshot) {
+    const explicit = snapshot.wallet?.mlKemParameterSet;
+    if (explicit) {
+      return Number(explicit) === 768 ? 768 : 1024;
+    }
+    return Wallet.mlKemParameterSetFromPubkey(snapshot.pubkey) ?? 768;
+  }
   /**
    * Restore AuthToken from snapshot
    */
@@ -6585,8 +6727,9 @@ var AuthToken = class _AuthToken {
     const wallet = new Wallet({
       secret,
       token: "AUTH",
-      position: snapshot.wallet.position,
-      characters: snapshot.wallet.characters
+      position: snapshot.wallet?.position ?? null,
+      characters: snapshot.wallet?.characters ?? null,
+      mlKemParameterSet: _AuthToken.resolveMlKemParameterSet(snapshot)
     });
     return _AuthToken.create({
       token: snapshot.token,
@@ -6654,7 +6797,9 @@ var AuthToken = class _AuthToken {
     };
   }
   /**
-   * Create snapshot for persistence
+   * Create snapshot for persistence. The wallet's ML-KEM parameter set is recorded beside its
+   * position and characters so a stepped-back ML-KEM-768 session restores as 768 rather than
+   * silently taking the constructor default.
    */
   toSnapshot() {
     return {
@@ -6665,7 +6810,8 @@ var AuthToken = class _AuthToken {
       ...this.$__wallet ? {
         wallet: {
           position: this.$__wallet.position,
-          characters: this.$__wallet.characters
+          characters: this.$__wallet.characters,
+          mlKemParameterSet: this.$__wallet.mlKemParameterSet
         }
       } : {}
     };
@@ -6962,7 +7108,8 @@ var KnishIOClientConfigSchema2 = z.object({
   // isn't rejected.
   defaultRequestPolicy: z.enum(["cache-first", "cache-only", "network-only", "cache-and-network"]).nullable().optional(),
   // Pluggable hardware envelope encryption secret storage provider
-  secretStorage: z.unknown().optional()
+  secretStorage: z.unknown().optional(),
+  mlKemParameterSet: z.union([z.literal(1024), z.literal(768)]).optional()
 }).strict();
 var EnvironmentConfigSchema = z.object({
   NODE_ENV: z.enum(["development", "production", "test"]).optional(),
@@ -10552,10 +10699,121 @@ function constantTimeCompare(a, b) {
   return result === 0;
 }
 
+// src/storage/secretEnvelope.ts
+init_SecretStorageException();
+var ENVELOPE_ALGORITHM = "AES-GCM";
+var DEFAULT_ITERATIONS = 1e5;
+var SECRET_KEY_PREFIX = "knishio:secret:";
+var RECOVERY_KEY_PREFIX = "knishio:recovery:";
+var GCM_IV_LENGTH = 12;
+var SALT_LENGTH = 16;
+var textEncoder2 = new TextEncoder();
+function uint8ArrayToBase64(bytes) {
+  let binary = "";
+  const len = bytes.byteLength;
+  for (let i = 0; i < len; i++) {
+    const byte = bytes[i];
+    if (byte !== void 0) {
+      binary += String.fromCharCode(byte);
+    }
+  }
+  return btoa(binary);
+}
+function base64ToUint8Array(base64) {
+  const binary = atob(base64);
+  const len = binary.length;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+async function deriveEnvelopeKey(passphrase, salt, iterations = DEFAULT_ITERATIONS) {
+  if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
+    throw new SecretStorageException("WebCrypto API is not available");
+  }
+  const passphraseBytes = textEncoder2.encode(passphrase);
+  try {
+    const baseKey = await globalThis.crypto.subtle.importKey(
+      "raw",
+      passphraseBytes,
+      "PBKDF2",
+      false,
+      ["deriveKey"]
+    );
+    return await globalThis.crypto.subtle.deriveKey(
+      {
+        name: "PBKDF2",
+        salt,
+        iterations,
+        hash: "SHA-256"
+      },
+      baseKey,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    );
+  } finally {
+    zeroizeBytes(passphraseBytes);
+  }
+}
+async function sealEnvelope(secret, passphrase, metadata) {
+  if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
+    throw new SecretStorageException("WebCrypto API is not available");
+  }
+  const salt = new Uint8Array(SALT_LENGTH);
+  const iv = new Uint8Array(GCM_IV_LENGTH);
+  globalThis.crypto.getRandomValues(salt);
+  globalThis.crypto.getRandomValues(iv);
+  const key = await deriveEnvelopeKey(passphrase, salt, DEFAULT_ITERATIONS);
+  const secretBytes = textEncoder2.encode(secret);
+  try {
+    const encryptedBuffer = await globalThis.crypto.subtle.encrypt(
+      {
+        name: ENVELOPE_ALGORITHM,
+        iv
+      },
+      key,
+      secretBytes
+    );
+    const ciphertext = uint8ArrayToBase64(new Uint8Array(encryptedBuffer));
+    return {
+      version: 1,
+      ciphertext,
+      iv: uint8ArrayToBase64(iv),
+      salt: uint8ArrayToBase64(salt),
+      algorithm: ENVELOPE_ALGORITHM,
+      iterations: DEFAULT_ITERATIONS,
+      metadata
+    };
+  } finally {
+    zeroizeBytes(secretBytes);
+  }
+}
+async function openEnvelope(payload, passphrase) {
+  if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
+    throw new SecretStorageException("WebCrypto API is not available");
+  }
+  const salt = base64ToUint8Array(payload.salt);
+  const iv = base64ToUint8Array(payload.iv);
+  const ciphertext = base64ToUint8Array(payload.ciphertext);
+  const key = await deriveEnvelopeKey(passphrase, salt, payload.iterations ?? DEFAULT_ITERATIONS);
+  const decryptedBuffer = await globalThis.crypto.subtle.decrypt(
+    {
+      name: ENVELOPE_ALGORITHM,
+      iv
+    },
+    key,
+    ciphertext
+  );
+  return new Uint8Array(decryptedBuffer);
+}
+
 // src/storage/MemorySecretStorageProvider.ts
 var MemorySecretStorageProvider = class {
   providerType = "memory";
   secrets = /* @__PURE__ */ new Map();
+  recoverySecrets = /* @__PURE__ */ new Map();
   /**
    * Memory storage is not hardware backed
    */
@@ -10586,6 +10844,17 @@ var MemorySecretStorageProvider = class {
       providerType: this.providerType
     };
     this.secrets.set(bundleHash, { secret, metadata });
+    if (options?.recoveryPassphrase) {
+      const recoveryMetadata = {
+        bundleHash,
+        label: options?.label,
+        createdAt: Date.now(),
+        hardwareBacked: false,
+        providerType: "webcrypto-aes-gcm"
+      };
+      const recoveryPayload = await sealEnvelope(secret, options.recoveryPassphrase, recoveryMetadata);
+      this.recoverySecrets.set(bundleHash, JSON.stringify(recoveryPayload));
+    }
   }
   /**
    * Retrieve a secret from memory
@@ -10598,6 +10867,7 @@ var MemorySecretStorageProvider = class {
    * Delete a stored secret
    */
   async deleteSecret(bundleHash) {
+    this.recoverySecrets.delete(bundleHash);
     return this.secrets.delete(bundleHash);
   }
   /**
@@ -10627,6 +10897,48 @@ var MemorySecretStorageProvider = class {
    */
   clear() {
     this.secrets.clear();
+    this.recoverySecrets.clear();
+  }
+  /**
+   * Recover a secret using its recovery envelope and restore it
+   */
+  async recoverSecret(bundleHash, recoveryPassphrase, options) {
+    if (!bundleHash) {
+      throw new SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!recoveryPassphrase) {
+      throw new SecretStorageException("Recovery passphrase cannot be empty");
+    }
+    const raw = this.recoverySecrets.get(bundleHash);
+    if (!raw) {
+      throw SecretStorageException.notFound(bundleHash);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted recovery payload format");
+    }
+    let decryptedBytes;
+    try {
+      decryptedBytes = await openEnvelope(payload, recoveryPassphrase);
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+    let secretStr;
+    try {
+      secretStr = new TextDecoder().decode(decryptedBytes);
+    } finally {
+      zeroizeBytes(decryptedBytes);
+    }
+    await this.storeSecret(bundleHash, secretStr, {
+      ...options,
+      recoveryPassphrase
+    });
   }
 };
 
@@ -10648,6 +10960,7 @@ var KnishIOClient = class {
   $__authTokenObjects = {};
   $__authToken = null;
   $__authInProcess = false;
+  $__mlKemParameterSet = 1024;
   $__remainderWallet = null;
   lastMoleculeQuery = null;
   abortControllers = /* @__PURE__ */ new Map();
@@ -10692,7 +11005,8 @@ var KnishIOClient = class {
       client,
       serverSdkVersion,
       logging,
-      defaultRequestPolicy
+      defaultRequestPolicy,
+      mlKemParameterSet: config.mlKemParameterSet ?? 1024
     });
     if (config.secretStorage) {
       this.$__secretStorage = config.secretStorage;
@@ -10708,10 +11022,12 @@ var KnishIOClient = class {
     client = null,
     serverSdkVersion = 3,
     logging = false,
-    defaultRequestPolicy = null
+    defaultRequestPolicy = null,
+    mlKemParameterSet = 1024
   }) {
     this.reset();
     this.$__logging = logging;
+    this.setMlKemParameterSet(mlKemParameterSet);
     this.$__authTokenObjects = {};
     this.setUri(uri);
     if (cellSlug) {
@@ -10732,6 +11048,17 @@ var KnishIOClient = class {
     this.$__serverSdkVersion = serverSdkVersion;
     this.$__defaultRequestPolicy = defaultRequestPolicy;
   }
+  getMlKemParameterSet() {
+    return this.$__mlKemParameterSet || 1024;
+  }
+  setMlKemParameterSet(parameterSet) {
+    const paramNum = Number(parameterSet);
+    if (![1024, 768].includes(paramNum)) {
+      throw new Error(`KnishIO: unsupported ML-KEM parameter set ${parameterSet}; expected 1024 or 768.`);
+    }
+    this.$__mlKemParameterSet = paramNum;
+    return this;
+  }
   /**
    * Get random uri from specified this.$__uris
    */
@@ -10968,7 +11295,8 @@ var KnishIOClient = class {
       bundle,
       token: "USER",
       batchId: sourceWallet.batchId,
-      characters: sourceWallet.characters
+      characters: sourceWallet.characters,
+      mlKemParameterSet: this.getMlKemParameterSet()
     }));
     return new Molecule({
       secret,
@@ -10977,7 +11305,8 @@ var KnishIOClient = class {
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
       version: this.getServerSdkVersion(),
-      continuIdPosition
+      continuIdPosition,
+      mlKemParameterSet: this.getMlKemParameterSet()
     });
   }
   /**
@@ -11089,7 +11418,8 @@ var KnishIOClient = class {
     }))?.payload();
     if (!sourceWallet) {
       sourceWallet = new Wallet({
-        secret: this.getSecret()
+        secret: this.getSecret(),
+        mlKemParameterSet: this.getMlKemParameterSet()
       });
     } else {
       sourceWallet.key = Wallet.generateKey({
@@ -11132,7 +11462,8 @@ var KnishIOClient = class {
     }
     const recipientWallet = Wallet.create({
       bundle: bundleHash,
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     });
     if (batchId !== null) {
       recipientWallet.batchId = batchId;
@@ -11199,7 +11530,8 @@ var KnishIOClient = class {
     const recipientWallets = recipients.map((recipient) => {
       const recipientWallet = Wallet.create({
         bundle: recipient.bundleHash,
-        token
+        token,
+        mlKemParameterSet: this.getMlKemParameterSet()
       });
       if (recipient.batchId !== null && recipient.batchId !== void 0) {
         recipientWallet.batchId = recipient.batchId;
@@ -11823,7 +12155,8 @@ var KnishIOClient = class {
       secret: this.getSecret(),
       bundle: this.getBundle(),
       token,
-      batchId
+      batchId,
+      mlKemParameterSet: this.getMlKemParameterSet()
     });
     await mutation.fillMolecule({
       recipientWallet,
@@ -11891,7 +12224,8 @@ var KnishIOClient = class {
     const recipientWallet = new Wallet({
       secret: this.getSecret(),
       bundle: "0000000000000000000000000000000000000000000000000000000000000000",
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     });
     await mutation.fillMolecule({
       recipientWallet,
@@ -11968,7 +12302,8 @@ var KnishIOClient = class {
     const newWallet = new Wallet({
       secret: this.getSecret(),
       bundle: this.getBundle(),
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     });
     await mutation.fillMolecule(newWallet);
     const response = await this.executeQuery(mutation);
@@ -12296,7 +12631,8 @@ var KnishIOClient = class {
     this.setSecret(secret);
     const wallet = new Wallet({
       secret,
-      token: "AUTH"
+      token: "AUTH",
+      mlKemParameterSet: this.getMlKemParameterSet()
     });
     const molecule = await this.createMolecule({
       secret,
@@ -12424,45 +12760,25 @@ var MemoryStorageBackend = class {
     return Array.from(this.store.keys());
   }
 };
-function uint8ArrayToBase64(bytes) {
-  let binary = "";
-  const len = bytes.byteLength;
-  for (let i = 0; i < len; i++) {
-    const byte = bytes[i];
-    if (byte !== void 0) {
-      binary += String.fromCharCode(byte);
-    }
-  }
-  return btoa(binary);
-}
-function base64ToUint8Array(base64) {
-  const binary = atob(base64);
-  const len = binary.length;
-  const bytes = new Uint8Array(len);
-  for (let i = 0; i < len; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return bytes;
-}
-var textEncoder2 = new TextEncoder();
 var textDecoder = new TextDecoder();
-var KEY_PREFIX = "knishio:secret:";
-var DEFAULT_ITERATIONS = 1e5;
+var KEY_PREFIX = SECRET_KEY_PREFIX;
 var WebCryptoSecretStorageProvider = class {
   providerType = "webcrypto-aes-gcm";
   backend;
   defaultPassphrase;
-  hardwareBacked;
   constructor(options = {}) {
     this.backend = options.backend ?? new MemoryStorageBackend();
     this.defaultPassphrase = options.defaultPassphrase;
-    this.hardwareBacked = options.hardwareBacked ?? false;
   }
   /**
-   * Whether this provider is backed by hardware (e.g. WebAuthn PRF wrapping)
+   * True only when this provider holds a non-exportable key inside platform-secure
+   * hardware (Android TEE/StrongBox, Secure Enclave, TPM) and learned that from the
+   * platform itself — never from a caller argument. Software envelope providers
+   * return false. The value is persisted as `metadata.hardwareBacked` in every
+   * envelope this provider writes.
    */
   isHardwareBacked() {
-    return this.hardwareBacked;
+    return false;
   }
   /**
    * Check if WebCrypto subtle API is available
@@ -12470,38 +12786,6 @@ var WebCryptoSecretStorageProvider = class {
   async isAvailable() {
     return typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.subtle !== "undefined";
   }
-  /**
-   * Derive an AES-GCM CryptoKey from a passphrase and salt using PBKDF2
-   */
-  async deriveKey(passphrase, salt, iterations = DEFAULT_ITERATIONS) {
-    if (!await this.isAvailable()) {
-      throw SecretStorageException.unavailable(this.providerType, "WebCrypto API is not available");
-    }
-    const passphraseBytes = textEncoder2.encode(passphrase);
-    try {
-      const baseKey = await globalThis.crypto.subtle.importKey(
-        "raw",
-        passphraseBytes,
-        "PBKDF2",
-        false,
-        ["deriveKey"]
-      );
-      return await globalThis.crypto.subtle.deriveKey(
-        {
-          name: "PBKDF2",
-          salt,
-          iterations,
-          hash: "SHA-256"
-        },
-        baseKey,
-        { name: "AES-GCM", length: 256 },
-        false,
-        ["encrypt", "decrypt"]
-      );
-    } finally {
-      zeroizeBytes(passphraseBytes);
-    }
-  }
   /**
    * Store and encrypt a master secret
    */
@@ -12516,44 +12800,36 @@ var WebCryptoSecretStorageProvider = class {
     if (!passphrase) {
       throw new SecretStorageException("Passphrase required for envelope encryption");
     }
-    const salt = new Uint8Array(16);
-    const iv = new Uint8Array(12);
-    globalThis.crypto.getRandomValues(salt);
-    globalThis.crypto.getRandomValues(iv);
-    const key = await this.deriveKey(passphrase, salt, DEFAULT_ITERATIONS);
-    const secretBytes = textEncoder2.encode(secret);
+    if (!await this.isAvailable()) {
+      throw SecretStorageException.unavailable(this.providerType, "WebCrypto API is not available");
+    }
     try {
-      const encryptedBuffer = await globalThis.crypto.subtle.encrypt(
-        {
-          name: "AES-GCM",
-          iv
-        },
-        key,
-        secretBytes
-      );
-      const ciphertext = uint8ArrayToBase64(new Uint8Array(encryptedBuffer));
       const metadata = {
         bundleHash,
         label: options?.label,
         createdAt: Date.now(),
-        hardwareBacked: this.hardwareBacked,
+        hardwareBacked: false,
         providerType: this.providerType
       };
-      const payload = {
-        version: 1,
-        ciphertext,
-        iv: uint8ArrayToBase64(iv),
-        salt: uint8ArrayToBase64(salt),
-        algorithm: "AES-GCM",
-        iterations: DEFAULT_ITERATIONS,
-        metadata
-      };
+      const payload = await sealEnvelope(secret, passphrase, metadata);
       await this.backend.setItem(`${KEY_PREFIX}${bundleHash}`, JSON.stringify(payload));
+      if (options?.recoveryPassphrase) {
+        const recoveryMetadata = {
+          bundleHash,
+          label: options?.label,
+          createdAt: Date.now(),
+          hardwareBacked: false,
+          providerType: "webcrypto-aes-gcm"
+        };
+        const recoveryPayload = await sealEnvelope(secret, options.recoveryPassphrase, recoveryMetadata);
+        await this.backend.setItem(`${RECOVERY_KEY_PREFIX}${bundleHash}`, JSON.stringify(recoveryPayload));
+      }
     } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
       const msg = err instanceof Error ? err.message : String(err);
       throw new SecretStorageException(`Encryption failed: ${msg}`);
-    } finally {
-      zeroizeBytes(secretBytes);
     }
   }
   /**
@@ -12574,26 +12850,20 @@ var WebCryptoSecretStorageProvider = class {
     if (!passphrase) {
       throw new SecretStorageException("Passphrase required for secret decryption");
     }
-    const salt = base64ToUint8Array(payload.salt);
-    const iv = base64ToUint8Array(payload.iv);
-    const ciphertext = base64ToUint8Array(payload.ciphertext);
+    if (!await this.isAvailable()) {
+      throw SecretStorageException.unavailable(this.providerType, "WebCrypto API is not available");
+    }
     try {
-      const key = await this.deriveKey(passphrase, salt, payload.iterations ?? DEFAULT_ITERATIONS);
-      const decryptedBuffer = await globalThis.crypto.subtle.decrypt(
-        {
-          name: "AES-GCM",
-          iv
-        },
-        key,
-        ciphertext
-      );
-      const decryptedBytes = new Uint8Array(decryptedBuffer);
+      const decryptedBytes = await openEnvelope(payload, passphrase);
       try {
         return textDecoder.decode(decryptedBytes);
       } finally {
         zeroizeBytes(decryptedBytes);
       }
     } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
       const msg = err instanceof Error ? err.message : String(err);
       throw SecretStorageException.decryptionFailed(msg);
     }
@@ -12603,7 +12873,9 @@ var WebCryptoSecretStorageProvider = class {
    */
   async deleteSecret(bundleHash) {
     const key = `${KEY_PREFIX}${bundleHash}`;
+    const recoveryKey = `${RECOVERY_KEY_PREFIX}${bundleHash}`;
     const result = await this.backend.removeItem(key);
+    await this.backend.removeItem(recoveryKey);
     return result !== false;
   }
   /**
@@ -12618,7 +12890,7 @@ var WebCryptoSecretStorageProvider = class {
    */
   async listSecrets() {
     const keys = await this.backend.keys();
-    const matchingKeys = keys.filter((k) => k.startsWith(KEY_PREFIX));
+    const matchingKeys = keys.filter((k) => k.startsWith(KEY_PREFIX) && !k.startsWith(RECOVERY_KEY_PREFIX));
     const results = [];
     for (const key of matchingKeys) {
       const raw = await this.backend.getItem(key);
@@ -12652,20 +12924,11 @@ var WebCryptoSecretStorageProvider = class {
     if (!passphrase) {
       throw new SecretStorageException("Passphrase required for secret decryption");
     }
-    const salt = base64ToUint8Array(payload.salt);
-    const iv = base64ToUint8Array(payload.iv);
-    const ciphertext = base64ToUint8Array(payload.ciphertext);
+    if (!await this.isAvailable()) {
+      throw SecretStorageException.unavailable(this.providerType, "WebCrypto API is not available");
+    }
     try {
-      const key = await this.deriveKey(passphrase, salt, payload.iterations ?? DEFAULT_ITERATIONS);
-      const decryptedBuffer = await globalThis.crypto.subtle.decrypt(
-        {
-          name: "AES-GCM",
-          iv
-        },
-        key,
-        ciphertext
-      );
-      const decryptedBytes = new Uint8Array(decryptedBuffer);
+      const decryptedBytes = await openEnvelope(payload, passphrase);
       return await withSecureBytes(decryptedBytes, async (bytes) => {
         const secretString = textDecoder.decode(bytes);
         return await fn(secretString);
@@ -12678,6 +12941,1071 @@ var WebCryptoSecretStorageProvider = class {
       throw SecretStorageException.decryptionFailed(msg);
     }
   }
+  /**
+   * Recover a secret using its recovery envelope and re-enroll it
+   */
+  async recoverSecret(bundleHash, recoveryPassphrase, options) {
+    if (!bundleHash) {
+      throw new SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!recoveryPassphrase) {
+      throw new SecretStorageException("Recovery passphrase cannot be empty");
+    }
+    const raw = await this.backend.getItem(`${RECOVERY_KEY_PREFIX}${bundleHash}`);
+    if (!raw) {
+      throw SecretStorageException.notFound(bundleHash);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted recovery payload format");
+    }
+    let decryptedBytes;
+    try {
+      decryptedBytes = await openEnvelope(payload, recoveryPassphrase);
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+    let secretStr;
+    try {
+      secretStr = textDecoder.decode(decryptedBytes);
+    } finally {
+      zeroizeBytes(decryptedBytes);
+    }
+    const storePassphrase = options?.passphrase ?? this.defaultPassphrase ?? recoveryPassphrase;
+    await this.storeSecret(bundleHash, secretStr, {
+      ...options,
+      passphrase: storePassphrase,
+      recoveryPassphrase
+    });
+  }
+};
+
+// src/storage/FileStorageBackend.ts
+init_SecretStorageException();
+var FileStorageBackend = class {
+  filePath;
+  store = /* @__PURE__ */ new Map();
+  loaded = false;
+  constructor(filePath) {
+    if (!filePath) {
+      throw new SecretStorageException("Storage file path cannot be empty");
+    }
+    this.filePath = filePath;
+  }
+  async getFs() {
+    try {
+      const fs = await import('fs/promises');
+      const path = await import('path');
+      return { fs, path };
+    } catch {
+      throw SecretStorageException.unavailable(
+        "file-storage",
+        "FileStorageBackend is only supported in Node.js environments with node:fs access"
+      );
+    }
+  }
+  async ensureLoaded() {
+    if (this.loaded) {
+      return this.store;
+    }
+    const { fs } = await this.getFs();
+    try {
+      const content = await fs.readFile(this.filePath, "utf8");
+      let parsed;
+      try {
+        parsed = JSON.parse(content);
+      } catch {
+        throw SecretStorageException.decryptionFailed("Corrupted storage file format");
+      }
+      if (parsed && typeof parsed === "object") {
+        this.store = new Map(Object.entries(parsed).map(([k, v]) => [k, String(v)]));
+      }
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const nodeErr = err;
+      if (nodeErr?.code !== "ENOENT") {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new SecretStorageException(`Failed to read storage file: ${msg}`);
+      }
+      this.store = /* @__PURE__ */ new Map();
+    }
+    this.loaded = true;
+    return this.store;
+  }
+  async persist() {
+    const { fs, path } = await this.getFs();
+    const dir = path.dirname(this.filePath);
+    if (dir && dir !== ".") {
+      await fs.mkdir(dir, { recursive: true });
+    }
+    const tmpPath = `${this.filePath}.tmp.${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const data = JSON.stringify(Object.fromEntries(this.store), null, 2);
+    try {
+      await fs.writeFile(tmpPath, data, { mode: 384, encoding: "utf8" });
+      if (typeof process !== "undefined" && process.platform !== "win32") {
+        try {
+          await fs.chmod(tmpPath, 384);
+        } catch {
+        }
+      }
+      await fs.rename(tmpPath, this.filePath);
+    } catch (err) {
+      try {
+        await fs.unlink(tmpPath);
+      } catch {
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new SecretStorageException(`Failed to persist storage file: ${msg}`);
+    }
+  }
+  async getItem(key) {
+    await this.ensureLoaded();
+    return this.store.get(key) ?? null;
+  }
+  async setItem(key, value) {
+    await this.ensureLoaded();
+    this.store.set(key, value);
+    await this.persist();
+  }
+  async removeItem(key) {
+    await this.ensureLoaded();
+    const existed = this.store.delete(key);
+    if (existed) {
+      await this.persist();
+    }
+    return existed;
+  }
+  async keys() {
+    await this.ensureLoaded();
+    return Array.from(this.store.keys());
+  }
+};
+
+// src/storage/WebStorageBackend.ts
+init_SecretStorageException();
+var WebStorageBackend = class {
+  storage;
+  prefix;
+  constructor(storage, prefix = "knishio:") {
+    if (storage) {
+      this.storage = storage;
+    } else if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      this.storage = globalThis.localStorage;
+    } else {
+      throw SecretStorageException.unavailable(
+        "web-storage",
+        "WebStorageBackend requires a Storage object or global localStorage"
+      );
+    }
+    this.prefix = prefix;
+  }
+  getItem(key) {
+    return this.storage.getItem(key);
+  }
+  setItem(key, value) {
+    this.storage.setItem(key, value);
+  }
+  removeItem(key) {
+    const existed = this.storage.getItem(key) !== null;
+    this.storage.removeItem(key);
+    return existed;
+  }
+  keys() {
+    const result = [];
+    const len = this.storage.length;
+    for (let i = 0; i < len; i++) {
+      const k = this.storage.key(i);
+      if (k !== null) {
+        if (!this.prefix || k.startsWith(this.prefix)) {
+          result.push(k);
+        }
+      }
+    }
+    return result;
+  }
+};
+
+// src/storage/WebAuthnPrfSecretStorageProvider.ts
+init_SecretStorageException();
+var PRF_SALT_LABEL = "knishio:secret-storage:webauthn-prf:v1";
+var KEK_INFO = "knishio:secret-storage:kek:v1";
+var KEY_PREFIX2 = SECRET_KEY_PREFIX;
+var GCM_IV_LENGTH2 = 12;
+var textEncoder3 = new TextEncoder();
+var textDecoder2 = new TextDecoder();
+function base64UrlEncode(bytes) {
+  return uint8ArrayToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(str) {
+  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  while (base64.length % 4 !== 0) {
+    base64 += "=";
+  }
+  return base64ToUint8Array(base64);
+}
+function toUint8Array(buf) {
+  if (buf instanceof Uint8Array) {
+    return buf;
+  }
+  if (ArrayBuffer.isView(buf)) {
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+  return new Uint8Array(buf);
+}
+async function computePrfSalt() {
+  const hash = await globalThis.crypto.subtle.digest("SHA-256", textEncoder3.encode(PRF_SALT_LABEL));
+  return new Uint8Array(hash);
+}
+async function deriveKekFromPrf(prfOutput, prfSalt) {
+  const hkdfKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    prfOutput,
+    "HKDF",
+    false,
+    ["deriveKey"]
+  );
+  return await globalThis.crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: prfSalt,
+      info: textEncoder3.encode(KEK_INFO)
+    },
+    hkdfKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+var WebAuthnPrfSecretStorageProvider = class {
+  providerType = "webauthn-prf";
+  backend;
+  rp;
+  user;
+  credentialsContainer;
+  alias;
+  cachedPassphrase;
+  constructor(options) {
+    this.backend = options.backend;
+    this.rp = options.rp;
+    this.user = options.user;
+    this.credentialsContainer = options.credentials;
+    this.alias = options.alias ?? "default";
+  }
+  get credentials() {
+    if (this.credentialsContainer) {
+      return this.credentialsContainer;
+    }
+    if (typeof globalThis.navigator !== "undefined" && globalThis.navigator.credentials) {
+      return globalThis.navigator.credentials;
+    }
+    throw SecretStorageException.unavailable(
+      this.providerType,
+      "WebAuthn credentials container is not available"
+    );
+  }
+  get recordKey() {
+    return `knishio:webauthn-prf:${this.alias}`;
+  }
+  isHardwareBacked() {
+    return false;
+  }
+  async isAvailable() {
+    const hasWebCrypto = typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.subtle !== "undefined";
+    const hasCredentials = Boolean(
+      this.credentialsContainer || typeof globalThis.navigator !== "undefined" && globalThis.navigator.credentials && typeof globalThis.PublicKeyCredential !== "undefined"
+    );
+    return hasWebCrypto && hasCredentials;
+  }
+  /**
+   * Enroll a new passkey credential with PRF support and wrap a random device passphrase
+   */
+  async enroll() {
+    const existing = await this.backend.getItem(this.recordKey);
+    if (existing) {
+      return;
+    }
+    if (!await this.isAvailable()) {
+      throw SecretStorageException.unavailable(this.providerType, "WebAuthn PRF is not available");
+    }
+    const challenge = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(challenge);
+    const credential = await this.credentials.create({
+      publicKey: {
+        rp: this.rp,
+        user: {
+          id: this.user.id,
+          name: this.user.name,
+          displayName: this.user.displayName
+        },
+        challenge,
+        pubKeyCredParams: [
+          { type: "public-key", alg: -7 },
+          { type: "public-key", alg: -257 }
+        ],
+        authenticatorSelection: {
+          residentKey: "required",
+          userVerification: "required"
+        },
+        extensions: {
+          prf: {}
+        }
+      }
+    });
+    if (!credential) {
+      throw SecretStorageException.unavailable(this.providerType, "Authenticator creation returned null");
+    }
+    const extResults = credential.getClientExtensionResults?.();
+    if (extResults?.prf?.enabled !== true) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        "authenticator does not support the PRF extension"
+      );
+    }
+    const credentialIdBytes = new Uint8Array(credential.rawId);
+    const prfSalt = await computePrfSalt();
+    const getChallenge = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(getChallenge);
+    let assertion;
+    try {
+      assertion = await this.credentials.get({
+        publicKey: {
+          challenge: getChallenge,
+          rpId: this.rp.id,
+          allowCredentials: [
+            {
+              type: "public-key",
+              id: credentialIdBytes
+            }
+          ],
+          userVerification: "required",
+          extensions: {
+            prf: {
+              eval: {
+                first: prfSalt
+              }
+            }
+          }
+        }
+      });
+    } catch (err) {
+      const isNotAllowed = err instanceof Error && err.name === "NotAllowedError" || err?.name === "NotAllowedError";
+      if (isNotAllowed) {
+        throw SecretStorageException.unavailable(
+          this.providerType,
+          "authenticator refused or credential missing"
+        );
+      }
+      throw err;
+    }
+    if (!assertion) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        "authenticator refused or credential missing"
+      );
+    }
+    const getExtResults = assertion?.getClientExtensionResults?.();
+    const firstOutput = getExtResults?.prf?.results?.first;
+    if (!firstOutput) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        "authenticator returned no PRF result"
+      );
+    }
+    const prfBytes = toUint8Array(firstOutput);
+    const kek = await deriveKekFromPrf(prfBytes, prfSalt);
+    const devicePassphraseBytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(devicePassphraseBytes);
+    const devicePassphrase = uint8ArrayToBase64(devicePassphraseBytes);
+    const iv = new Uint8Array(GCM_IV_LENGTH2);
+    globalThis.crypto.getRandomValues(iv);
+    const passphraseBytes = textEncoder3.encode(devicePassphrase);
+    try {
+      const encryptedBuffer = await globalThis.crypto.subtle.encrypt(
+        {
+          name: "AES-GCM",
+          iv
+        },
+        kek,
+        passphraseBytes
+      );
+      const record = {
+        version: 1,
+        credentialId: base64UrlEncode(credentialIdBytes),
+        iv: uint8ArrayToBase64(iv),
+        ciphertext: uint8ArrayToBase64(new Uint8Array(encryptedBuffer))
+      };
+      await this.backend.setItem(this.recordKey, JSON.stringify(record));
+      this.cachedPassphrase = devicePassphrase;
+    } finally {
+      zeroizeBytes(passphraseBytes);
+      zeroizeBytes(devicePassphraseBytes);
+    }
+  }
+  /**
+   * Unlock the device passphrase using the enrolled WebAuthn PRF credential
+   */
+  async unlock() {
+    if (this.cachedPassphrase) {
+      return this.cachedPassphrase;
+    }
+    const rawRecord = await this.backend.getItem(this.recordKey);
+    if (!rawRecord) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        "no enrolled credential; call enroll() first"
+      );
+    }
+    let record;
+    try {
+      record = JSON.parse(rawRecord);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted PRF record format");
+    }
+    const credentialIdBytes = base64UrlDecode(record.credentialId);
+    const prfSalt = await computePrfSalt();
+    const challenge = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(challenge);
+    let assertion;
+    try {
+      assertion = await this.credentials.get({
+        publicKey: {
+          challenge,
+          rpId: this.rp.id,
+          allowCredentials: [
+            {
+              type: "public-key",
+              id: credentialIdBytes
+            }
+          ],
+          userVerification: "required",
+          extensions: {
+            prf: {
+              eval: {
+                first: prfSalt
+              }
+            }
+          }
+        }
+      });
+    } catch (err) {
+      const isNotAllowed = err instanceof Error && err.name === "NotAllowedError" || err?.name === "NotAllowedError";
+      if (isNotAllowed) {
+        throw SecretStorageException.unavailable(
+          this.providerType,
+          "authenticator refused or credential missing"
+        );
+      }
+      throw err;
+    }
+    if (!assertion) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        "authenticator refused or credential missing"
+      );
+    }
+    const extResults = assertion?.getClientExtensionResults?.();
+    const firstOutput = extResults?.prf?.results?.first;
+    if (!firstOutput) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        "authenticator returned no PRF result"
+      );
+    }
+    const prfBytes = toUint8Array(firstOutput);
+    const kek = await deriveKekFromPrf(prfBytes, prfSalt);
+    const iv = base64ToUint8Array(record.iv);
+    const ciphertext = base64ToUint8Array(record.ciphertext);
+    try {
+      const decryptedBuffer = await globalThis.crypto.subtle.decrypt(
+        {
+          name: "AES-GCM",
+          iv
+        },
+        kek,
+        ciphertext
+      );
+      const decryptedBytes = new Uint8Array(decryptedBuffer);
+      try {
+        this.cachedPassphrase = textDecoder2.decode(decryptedBytes);
+        return this.cachedPassphrase;
+      } finally {
+        zeroizeBytes(decryptedBytes);
+      }
+    } catch {
+      throw SecretStorageException.decryptionFailed(
+        "wrapped device passphrase failed authentication under the enrolled credential"
+      );
+    }
+  }
+  /**
+   * Lock the provider by clearing cached passphrase material
+   */
+  lock() {
+    this.cachedPassphrase = void 0;
+  }
+  /**
+   * Unenroll the current credential, removing the stored PRF record and clearing cached passphrase
+   */
+  async unenroll() {
+    this.lock();
+    await this.backend.removeItem(this.recordKey);
+  }
+  async storeSecret(bundleHash, secret, options) {
+    if (!bundleHash) {
+      throw new SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!secret) {
+      throw new SecretStorageException("Secret cannot be empty");
+    }
+    if (options?.passphrase) {
+      throw new SecretStorageException(
+        "WebAuthnPrfSecretStorageProvider derives its passphrase from the authenticator; options.passphrase is not accepted"
+      );
+    }
+    if (!options?.recoveryPassphrase && !options?.allowUnrecoverable) {
+      throw SecretStorageException.validationError(
+        "Recovery passphrase required for non-exportable hardware key unless allowUnrecoverable is true"
+      );
+    }
+    const passphrase = await this.unlock();
+    const metadata = {
+      bundleHash,
+      label: options?.label,
+      createdAt: Date.now(),
+      hardwareBacked: false,
+      providerType: this.providerType
+    };
+    const payload = await sealEnvelope(secret, passphrase, metadata);
+    await this.backend.setItem(`${KEY_PREFIX2}${bundleHash}`, JSON.stringify(payload));
+    if (options?.recoveryPassphrase) {
+      const recoveryMetadata = {
+        bundleHash,
+        label: options?.label,
+        createdAt: Date.now(),
+        hardwareBacked: false,
+        providerType: "webcrypto-aes-gcm"
+      };
+      const recoveryPayload = await sealEnvelope(secret, options.recoveryPassphrase, recoveryMetadata);
+      await this.backend.setItem(`${RECOVERY_KEY_PREFIX}${bundleHash}`, JSON.stringify(recoveryPayload));
+    }
+  }
+  async retrieveSecret(bundleHash, options) {
+    if (options?.passphrase) {
+      throw new SecretStorageException(
+        "WebAuthnPrfSecretStorageProvider derives its passphrase from the authenticator; options.passphrase is not accepted"
+      );
+    }
+    const raw = await this.backend.getItem(`${KEY_PREFIX2}${bundleHash}`);
+    if (!raw) {
+      return null;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted payload format");
+    }
+    const passphrase = await this.unlock();
+    try {
+      const decryptedBytes = await openEnvelope(payload, passphrase);
+      try {
+        return textDecoder2.decode(decryptedBytes);
+      } finally {
+        zeroizeBytes(decryptedBytes);
+      }
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+  }
+  async withSecret(bundleHash, fn, options) {
+    if (options?.passphrase) {
+      throw new SecretStorageException(
+        "WebAuthnPrfSecretStorageProvider derives its passphrase from the authenticator; options.passphrase is not accepted"
+      );
+    }
+    const raw = await this.backend.getItem(`${KEY_PREFIX2}${bundleHash}`);
+    if (!raw) {
+      throw SecretStorageException.notFound(bundleHash);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted payload format");
+    }
+    const passphrase = await this.unlock();
+    try {
+      const decryptedBytes = await openEnvelope(payload, passphrase);
+      return await withSecureBytes(decryptedBytes, async (bytes) => {
+        const secretString = textDecoder2.decode(bytes);
+        return await fn(secretString);
+      });
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+  }
+  async deleteSecret(bundleHash) {
+    const key = `${KEY_PREFIX2}${bundleHash}`;
+    const recoveryKey = `${RECOVERY_KEY_PREFIX}${bundleHash}`;
+    const result = await this.backend.removeItem(key);
+    await this.backend.removeItem(recoveryKey);
+    return result !== false;
+  }
+  async hasSecret(bundleHash) {
+    const raw = await this.backend.getItem(`${KEY_PREFIX2}${bundleHash}`);
+    return raw !== null;
+  }
+  async listSecrets() {
+    const keys = await this.backend.keys();
+    const matchingKeys = keys.filter((k) => k.startsWith(KEY_PREFIX2) && !k.startsWith(RECOVERY_KEY_PREFIX));
+    const results = [];
+    for (const key of matchingKeys) {
+      const raw = await this.backend.getItem(key);
+      if (raw) {
+        try {
+          const payload = JSON.parse(raw);
+          if (payload.metadata) {
+            results.push(payload.metadata);
+          }
+        } catch {
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Recover a secret using its recovery envelope and re-enroll it under a fresh WebAuthn PRF credential
+   */
+  async recoverSecret(bundleHash, recoveryPassphrase, options) {
+    if (!bundleHash) {
+      throw new SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!recoveryPassphrase) {
+      throw new SecretStorageException("Recovery passphrase cannot be empty");
+    }
+    const raw = await this.backend.getItem(`${RECOVERY_KEY_PREFIX}${bundleHash}`);
+    if (!raw) {
+      throw SecretStorageException.notFound(bundleHash);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted recovery payload format");
+    }
+    let decryptedBytes;
+    try {
+      decryptedBytes = await openEnvelope(payload, recoveryPassphrase);
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+    let secretStr;
+    try {
+      secretStr = textDecoder2.decode(decryptedBytes);
+    } finally {
+      zeroizeBytes(decryptedBytes);
+    }
+    await this.storeSecret(bundleHash, secretStr, {
+      ...options,
+      recoveryPassphrase
+    });
+  }
+};
+
+// src/storage/NonExtractableKeySecretStorageProvider.ts
+init_SecretStorageException();
+var KEY_PREFIX3 = SECRET_KEY_PREFIX;
+var GCM_IV_LENGTH3 = 12;
+var textEncoder4 = new TextEncoder();
+var textDecoder3 = new TextDecoder();
+var MemoryKeyStore = class {
+  keys = /* @__PURE__ */ new Map();
+  async get(name) {
+    return this.keys.get(name);
+  }
+  async put(name, key) {
+    this.keys.set(name, key);
+  }
+  async delete(name) {
+    return this.keys.delete(name);
+  }
+};
+var IndexedDbKeyStore = class {
+  dbName;
+  storeName = "keys";
+  constructor(dbName = "knishio-secret-storage") {
+    this.dbName = dbName;
+  }
+  // Executor form intentionally retained for browser runtime compatibility with ES2022 / browsers without Promise.withResolvers polyfill
+  async getDb() {
+    if (typeof globalThis.indexedDB === "undefined") {
+      throw SecretStorageException.unavailable(
+        "webcrypto-nonextractable",
+        "IndexedDB is not available"
+      );
+    }
+    return new Promise((resolve, reject) => {
+      const request = globalThis.indexedDB.open(this.dbName, 1);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName);
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async get(name) {
+    const db = await this.getDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readonly");
+      const store = tx.objectStore(this.storeName);
+      const request = store.get(name);
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async put(name, key) {
+    const db = await this.getDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      const request = store.put(key, name);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async delete(name) {
+    const db = await this.getDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      const request = store.delete(name);
+      request.onsuccess = () => resolve(true);
+      request.onerror = () => reject(request.error);
+    });
+  }
+};
+var NonExtractableKeySecretStorageProvider = class {
+  providerType = "webcrypto-nonextractable";
+  backend;
+  keyStore;
+  alias;
+  cachedPassphrase;
+  constructor(options) {
+    this.backend = options.backend;
+    this.keyStore = options.keyStore ?? new IndexedDbKeyStore();
+    this.alias = options.alias ?? "default";
+  }
+  get recordKey() {
+    return `knishio:kek:webcrypto-nonextractable:${this.alias}`;
+  }
+  get kekStoreKey() {
+    return `knishio:kek:${this.alias}`;
+  }
+  isHardwareBacked() {
+    return false;
+  }
+  async isAvailable() {
+    return typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.subtle !== "undefined";
+  }
+  /**
+   * Unlock or initialize the device passphrase using the non-extractable KEK
+   */
+  async unlock() {
+    if (this.cachedPassphrase) {
+      return this.cachedPassphrase;
+    }
+    if (!await this.isAvailable()) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        "WebCrypto API is not available"
+      );
+    }
+    const rawRecord = await this.backend.getItem(this.recordKey);
+    if (!rawRecord) {
+      let kek2 = await this.keyStore.get(this.kekStoreKey);
+      if (!kek2) {
+        kek2 = await globalThis.crypto.subtle.generateKey(
+          { name: "AES-GCM", length: 256 },
+          false,
+          ["encrypt", "decrypt"]
+        );
+        await this.keyStore.put(this.kekStoreKey, kek2);
+      }
+      const devicePassphraseBytes = new Uint8Array(32);
+      globalThis.crypto.getRandomValues(devicePassphraseBytes);
+      const devicePassphrase = uint8ArrayToBase64(devicePassphraseBytes);
+      const iv2 = new Uint8Array(GCM_IV_LENGTH3);
+      globalThis.crypto.getRandomValues(iv2);
+      const passphraseBytes = textEncoder4.encode(devicePassphrase);
+      try {
+        const encryptedBuffer = await globalThis.crypto.subtle.encrypt(
+          {
+            name: "AES-GCM",
+            iv: iv2
+          },
+          kek2,
+          passphraseBytes
+        );
+        const record2 = {
+          version: 1,
+          iv: uint8ArrayToBase64(iv2),
+          ciphertext: uint8ArrayToBase64(new Uint8Array(encryptedBuffer))
+        };
+        await this.backend.setItem(this.recordKey, JSON.stringify(record2));
+        this.cachedPassphrase = devicePassphrase;
+        return devicePassphrase;
+      } finally {
+        zeroizeBytes(passphraseBytes);
+        zeroizeBytes(devicePassphraseBytes);
+      }
+    }
+    let record;
+    try {
+      record = JSON.parse(rawRecord);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted key record format");
+    }
+    const kek = await this.keyStore.get(this.kekStoreKey);
+    if (!kek) {
+      throw SecretStorageException.unavailable(
+        this.providerType,
+        `no non-extractable key found for alias '${this.alias}'`
+      );
+    }
+    const iv = base64ToUint8Array(record.iv);
+    const ciphertext = base64ToUint8Array(record.ciphertext);
+    try {
+      const decryptedBuffer = await globalThis.crypto.subtle.decrypt(
+        {
+          name: "AES-GCM",
+          iv
+        },
+        kek,
+        ciphertext
+      );
+      const decryptedBytes = new Uint8Array(decryptedBuffer);
+      try {
+        this.cachedPassphrase = textDecoder3.decode(decryptedBytes);
+        return this.cachedPassphrase;
+      } finally {
+        zeroizeBytes(decryptedBytes);
+      }
+    } catch {
+      throw SecretStorageException.decryptionFailed(
+        "wrapped device passphrase failed authentication under non-extractable key"
+      );
+    }
+  }
+  /**
+   * Lock the provider by clearing cached passphrase material
+   */
+  lock() {
+    this.cachedPassphrase = void 0;
+  }
+  /**
+   * Unenroll the non-extractable key, removing the stored wrapped record and KEK
+   */
+  async unenroll() {
+    this.lock();
+    await this.backend.removeItem(this.recordKey);
+    await this.keyStore.delete(this.kekStoreKey);
+  }
+  async storeSecret(bundleHash, secret, options) {
+    if (!bundleHash) {
+      throw new SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!secret) {
+      throw new SecretStorageException("Secret cannot be empty");
+    }
+    if (options?.passphrase) {
+      throw new SecretStorageException(
+        "NonExtractableKeySecretStorageProvider derives its passphrase from the non-extractable device key; options.passphrase is not accepted"
+      );
+    }
+    if (!options?.recoveryPassphrase && !options?.allowUnrecoverable) {
+      throw SecretStorageException.validationError(
+        "Recovery passphrase required for non-exportable hardware key unless allowUnrecoverable is true"
+      );
+    }
+    const passphrase = await this.unlock();
+    const metadata = {
+      bundleHash,
+      label: options?.label,
+      createdAt: Date.now(),
+      hardwareBacked: false,
+      providerType: this.providerType
+    };
+    const payload = await sealEnvelope(secret, passphrase, metadata);
+    await this.backend.setItem(`${KEY_PREFIX3}${bundleHash}`, JSON.stringify(payload));
+    if (options?.recoveryPassphrase) {
+      const recoveryMetadata = {
+        bundleHash,
+        label: options?.label,
+        createdAt: Date.now(),
+        hardwareBacked: false,
+        providerType: "webcrypto-aes-gcm"
+      };
+      const recoveryPayload = await sealEnvelope(secret, options.recoveryPassphrase, recoveryMetadata);
+      await this.backend.setItem(`${RECOVERY_KEY_PREFIX}${bundleHash}`, JSON.stringify(recoveryPayload));
+    }
+  }
+  async retrieveSecret(bundleHash, options) {
+    if (options?.passphrase) {
+      throw new SecretStorageException(
+        "NonExtractableKeySecretStorageProvider derives its passphrase from the non-extractable device key; options.passphrase is not accepted"
+      );
+    }
+    const raw = await this.backend.getItem(`${KEY_PREFIX3}${bundleHash}`);
+    if (!raw) {
+      return null;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted payload format");
+    }
+    const passphrase = await this.unlock();
+    try {
+      const decryptedBytes = await openEnvelope(payload, passphrase);
+      try {
+        return textDecoder3.decode(decryptedBytes);
+      } finally {
+        zeroizeBytes(decryptedBytes);
+      }
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+  }
+  async withSecret(bundleHash, fn, options) {
+    if (options?.passphrase) {
+      throw new SecretStorageException(
+        "NonExtractableKeySecretStorageProvider derives its passphrase from the non-extractable device key; options.passphrase is not accepted"
+      );
+    }
+    const raw = await this.backend.getItem(`${KEY_PREFIX3}${bundleHash}`);
+    if (!raw) {
+      throw SecretStorageException.notFound(bundleHash);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted payload format");
+    }
+    const passphrase = await this.unlock();
+    try {
+      const decryptedBytes = await openEnvelope(payload, passphrase);
+      return await withSecureBytes(decryptedBytes, async (bytes) => {
+        const secretString = textDecoder3.decode(bytes);
+        return await fn(secretString);
+      });
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+  }
+  async deleteSecret(bundleHash) {
+    const key = `${KEY_PREFIX3}${bundleHash}`;
+    const recoveryKey = `${RECOVERY_KEY_PREFIX}${bundleHash}`;
+    const result = await this.backend.removeItem(key);
+    await this.backend.removeItem(recoveryKey);
+    return result !== false;
+  }
+  async hasSecret(bundleHash) {
+    const raw = await this.backend.getItem(`${KEY_PREFIX3}${bundleHash}`);
+    return raw !== null;
+  }
+  async listSecrets() {
+    const keys = await this.backend.keys();
+    const matchingKeys = keys.filter((k) => k.startsWith(KEY_PREFIX3) && !k.startsWith(RECOVERY_KEY_PREFIX));
+    const results = [];
+    for (const key of matchingKeys) {
+      const raw = await this.backend.getItem(key);
+      if (raw) {
+        try {
+          const payload = JSON.parse(raw);
+          if (payload.metadata) {
+            results.push(payload.metadata);
+          }
+        } catch {
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Recover a secret using its recovery envelope and re-enroll it under a fresh non-extractable KEK
+   */
+  async recoverSecret(bundleHash, recoveryPassphrase, options) {
+    if (!bundleHash) {
+      throw new SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!recoveryPassphrase) {
+      throw new SecretStorageException("Recovery passphrase cannot be empty");
+    }
+    const raw = await this.backend.getItem(`${RECOVERY_KEY_PREFIX}${bundleHash}`);
+    if (!raw) {
+      throw SecretStorageException.notFound(bundleHash);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw SecretStorageException.decryptionFailed("Corrupted recovery payload format");
+    }
+    let decryptedBytes;
+    try {
+      decryptedBytes = await openEnvelope(payload, recoveryPassphrase);
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw SecretStorageException.decryptionFailed(msg);
+    }
+    let secretStr;
+    try {
+      secretStr = textDecoder3.decode(decryptedBytes);
+    } finally {
+      zeroizeBytes(decryptedBytes);
+    }
+    await this.storeSecret(bundleHash, secretStr, {
+      ...options,
+      recoveryPassphrase
+    });
+  }
 };
 
 // src/storage/index.ts
@@ -12688,15 +14016,14 @@ function createDefaultSecretStorage(options = {}) {
   if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.subtle !== "undefined") {
     return new WebCryptoSecretStorageProvider({
       backend: options.backend,
-      defaultPassphrase: options.defaultPassphrase,
-      hardwareBacked: options.hardwareBacked
+      defaultPassphrase: options.defaultPassphrase
     });
   }
   return new MemorySecretStorageProvider();
 }
 
 // src/index.ts
-var SDK_VERSION = "0.9.8";
+var SDK_VERSION = "1.1.0";
 var SDK_NAME = "KnishIO-Client-TS";
 var COMPATIBLE_SERVER_VERSIONS = [4, 5];
 var SDK_INFO = {
@@ -12705,7 +14032,7 @@ var SDK_INFO = {
   description: "TypeScript SDK for Knish.IO post-blockchain distributed ledger",
   compatibleServerVersions: COMPATIBLE_SERVER_VERSIONS,
   features: [
-    "Post-quantum cryptography (XMSS, ML-KEM768)",
+    "Post-quantum cryptography (XMSS, ML-KEM-1024)",
     "Cross-platform compatibility",
     "Type-safe APIs",
     "DAG-based transaction processing",
@@ -12786,6 +14113,6 @@ var KnishIO = {
   SDK_INFO
 };
 
-export { Atom, AtomIndexException, AtomMeta, AtomsMissingException, AuthToken, BaseException, COMPATIBLE_SERVER_VERSIONS, CRYPTO_CONSTANTS, CheckMolecule, DevUtils, Dot, EXCEPTION_CODES, EXCEPTION_TYPES, EXTENDED_COMPATIBILITY_TEST_VECTORS, ExceptionFactory, GraphQLClient, InvalidResponseException, KnishIO, KnishIOClient, MemorySecretStorageProvider, MemoryStorageBackend, Meta, MolecularHashMismatchException, Molecule, Mutation, MutationAppendRequest, MutationCreateMeta, MutationCreateToken, MutationCreateWallet, MutationPeering, MutationProposeMolecule, MutationRequestAuthorization, MutationRequestTokens, MutationTransferTokens, PolicyMeta, Query, QueryAtom, QueryBalance, QueryBatch, QueryContinuId, QueryEmbeddingStatus, QueryMetaType, QueryMetaTypeViaAtom, QueryWalletBundle, QueryWalletList, Response2 as Response, ResponseAppendRequest, ResponseAtom, ResponseBalance, ResponseContinuId, ResponseCreateMeta, ResponseCreateToken, ResponseCreateWallet, ResponseEmbeddingStatus, ResponseMetaType, ResponseMetaTypeViaAtom, ResponsePeering, ResponseProposeMolecule, ResponseRequestAuthorization, ResponseRequestTokens, ResponseTransferTokens, ResponseWalletBundle, ResponseWalletList, SDK_INFO, SDK_NAME, SDK_VERSION, SecretStorageException, SignatureMismatchException, TokenUnit, TransferBalanceException, Wallet, WalletCredentialException, WebCryptoSecretStorageProvider, base64ToHex, bufferToHexString, capitalize, charsetBaseConvert, chunkArray, chunkSubstr, configureSDK, constantTimeCompare, convertToBase17, createBundleHash, createDefaultSecretStorage, createMolecularHash, createPosition, createTokenSlug, createWalletAddress, deepCloning, diff, enumerateMolecularHash, generateBatchId, generateBundleHash, generateOTSSignature, generatePosition, generateSecret, generateWalletAddress, generateWalletKey, getSDKConfig, hexStringToBuffer, hexToBase64, intersect, isAtomIsotope, isBundleHash, isHex, isHexString, isMolecularHash, isNumeric, isPosition2 as isPosition, isWalletAddress2 as isWalletAddress, normalizeMolecularHash, randomString, runCompatibilityTests, runExtendedCompatibilityTests, shake256, toCamelCase, toSnakeCase, truncate, validateBundleHash, validateMolecularHashForSignature, validateOTSSignature, validatePosition, validateSecret, validateWalletAddress, verifyOTSSignature, withSecureBytes, withSecureString, zeroizeBytes };
+export { Atom, AtomIndexException, AtomMeta, AtomsMissingException, AuthToken, BaseException, COMPATIBLE_SERVER_VERSIONS, CRYPTO_CONSTANTS, CheckMolecule, DevUtils, Dot, EXCEPTION_CODES, EXCEPTION_TYPES, EXTENDED_COMPATIBILITY_TEST_VECTORS, ExceptionFactory, FileStorageBackend, GraphQLClient, IndexedDbKeyStore, InvalidResponseException, KnishIO, KnishIOClient, MemoryKeyStore, MemorySecretStorageProvider, MemoryStorageBackend, Meta, MolecularHashMismatchException, Molecule, Mutation, MutationAppendRequest, MutationCreateMeta, MutationCreateToken, MutationCreateWallet, MutationPeering, MutationProposeMolecule, MutationRequestAuthorization, MutationRequestTokens, MutationTransferTokens, NonExtractableKeySecretStorageProvider, PolicyMeta, Query, QueryAtom, QueryBalance, QueryBatch, QueryContinuId, QueryEmbeddingStatus, QueryMetaType, QueryMetaTypeViaAtom, QueryWalletBundle, QueryWalletList, RECOVERY_KEY_PREFIX, Response2 as Response, ResponseAppendRequest, ResponseAtom, ResponseBalance, ResponseContinuId, ResponseCreateMeta, ResponseCreateToken, ResponseCreateWallet, ResponseEmbeddingStatus, ResponseMetaType, ResponseMetaTypeViaAtom, ResponsePeering, ResponseProposeMolecule, ResponseRequestAuthorization, ResponseRequestTokens, ResponseTransferTokens, ResponseWalletBundle, ResponseWalletList, SDK_INFO, SDK_NAME, SDK_VERSION, SECRET_KEY_PREFIX, SecretStorageException, SignatureMismatchException, TokenUnit, TransferBalanceException, Wallet, WalletCredentialException, WebAuthnPrfSecretStorageProvider, WebCryptoSecretStorageProvider, WebStorageBackend, base64ToHex, bufferToHexString, capitalize, charsetBaseConvert, chunkArray, chunkSubstr, configureSDK, constantTimeCompare, convertToBase17, createBundleHash, createDefaultSecretStorage, createMolecularHash, createPosition, createTokenSlug, createWalletAddress, deepCloning, diff, enumerateMolecularHash, generateBatchId, generateBundleHash, generateOTSSignature, generatePosition, generateSecret, generateWalletAddress, generateWalletKey, getSDKConfig, hexStringToBuffer, hexToBase64, intersect, isAtomIsotope, isBundleHash, isHex, isHexString, isMolecularHash, isNumeric, isPosition2 as isPosition, isWalletAddress2 as isWalletAddress, normalizeMolecularHash, openEnvelope, randomString, runCompatibilityTests, runExtendedCompatibilityTests, sealEnvelope, shake256, toCamelCase, toSnakeCase, truncate, validateBundleHash, validateMolecularHashForSignature, validateOTSSignature, validatePosition, validateSecret, validateWalletAddress, verifyOTSSignature, withSecureBytes, withSecureString, zeroizeBytes };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map