@wishknish/knishio-client-ts 0.9.5 → 0.9.7

package/dist/index.cjs

@@ -527,6 +527,55 @@ var init_TransferBalanceException = __esm({
   }
 });
 
+// src/exception/SecretStorageException.ts
+exports.SecretStorageException = void 0;
+var init_SecretStorageException = __esm({
+  "src/exception/SecretStorageException.ts"() {
+    init_BaseException();
+    exports.SecretStorageException = class _SecretStorageException extends exports.BaseException {
+      constructor(message = "Secret storage operation failed", options = {}) {
+        super("WALLET_CREDENTIAL_ERROR", message, {
+          code: "SECRET_STORAGE_ERROR",
+          ...options
+        });
+      }
+      /**
+       * Secret not found for the requested bundle hash
+       */
+      static notFound(bundleHash) {
+        return new _SecretStorageException(`Secret not found for bundle: ${bundleHash}`, {
+          code: "SECRET_NOT_FOUND",
+          details: { bundleHash }
+        });
+      }
+      /**
+       * Decryption failed (wrong passphrase or corrupted payload)
+       */
+      static decryptionFailed(reason) {
+        return new _SecretStorageException(
+          `Failed to decrypt master secret: ${reason || "Invalid passphrase or corrupted ciphertext"}`,
+          {
+            code: "DECRYPTION_FAILED",
+            details: { reason }
+          }
+        );
+      }
+      /**
+       * Provider is unavailable in current platform
+       */
+      static unavailable(provider, reason) {
+        return new _SecretStorageException(
+          `Secret storage provider '${provider}' is unavailable: ${reason || "Hardware or API not accessible"}`,
+          {
+            code: "STORAGE_UNAVAILABLE",
+            details: { provider, reason }
+          }
+        );
+      }
+    };
+  }
+});
+
 // src/exception/InvalidResponseException.ts
 exports.InvalidResponseException = void 0;
 var init_InvalidResponseException = __esm({
@@ -989,6 +1038,7 @@ var init_exception = __esm({
     init_SignatureMismatchException();
     init_TransferBalanceException();
     init_WalletCredentialException();
+    init_SecretStorageException();
     init_InvalidResponseException();
     init_BalanceInsufficientException();
     init_BatchIdException();
@@ -2178,11 +2228,9 @@ function verifyOTSSignature(otsFragments, molecularHash, signingAddress) {
     const base17Hash = convertToBase17(molecularHash);
     const enumerated = enumerateMolecularHash(base17Hash);
     const normalized = normalizeMolecularHash(enumerated);
-    let ots = otsFragments;
+    const ots = otsFragments;
     if (ots.length !== 2048) {
-      if (ots.length !== 2048) {
-        return false;
-      }
+      return false;
     }
     const otsChunks = [];
     for (let i = 0; i < ots.length; i += CRYPTO_CONSTANTS.KEY_FRAGMENT_SIZE) {
@@ -2685,6 +2733,123 @@ var Meta = class {
     });
   }
 };
+
+// src/libraries/array.ts
+function deepCloning(o, h) {
+  let i;
+  let r;
+  let x;
+  const t = [Array, Date, Number, String, Boolean];
+  const s = Object.prototype.toString;
+  h = h || [];
+  for (i = 0; i < h.length; i += 2) {
+    if (o === h[i]) {
+      return h[i + 1];
+    }
+  }
+  if (!r && o && typeof o === "object") {
+    r = {};
+    for (i = 0; i < t.length; i++) {
+      if (s.call(o) === s.call(x = new t[i](o))) {
+        r = i ? x : [];
+      }
+    }
+    h.push(o, r);
+    for (i in o) {
+      if (Object.prototype.hasOwnProperty.call(o, i)) {
+        r[i] = deepCloning(o[i], h);
+      }
+    }
+  }
+  return r || o;
+}
+function chunkArray(arr, size) {
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+function diff(...arrays) {
+  return [].concat(...arrays.map((arr, i) => {
+    const others = arrays.slice(0);
+    others.splice(i, 1);
+    const unique = [...new Set([].concat(...others))];
+    return arr.filter((item) => !unique.includes(item));
+  }));
+}
+function intersect(...arrays) {
+  if (arrays.length === 0) return [];
+  if (arrays.length === 1) return arrays[0];
+  return arrays.reduce(
+    (first, second) => first.filter((item) => second.includes(item))
+  );
+}
+
+// src/core/PolicyMeta.ts
+var PolicyMeta = class _PolicyMeta {
+  policy;
+  /**
+   * Create new PolicyMeta instance
+   * Matches JavaScript SDK constructor signature exactly
+   */
+  constructor(policy = {}, metaKeys = []) {
+    this.policy = _PolicyMeta.normalizePolicy(policy);
+    this.fillDefault(metaKeys);
+  }
+  /**
+   * Normalize policy object structure
+   * Matches JavaScript SDK normalizePolicy method exactly
+   */
+  static normalizePolicy(policy = {}) {
+    const policyMeta = {};
+    for (const [policyKey, value] of Object.entries(policy)) {
+      if (value !== null && ["read", "write"].includes(policyKey)) {
+        policyMeta[policyKey] = {};
+        for (const [key, content] of Object.entries(value)) {
+          policyMeta[policyKey][key] = content;
+        }
+      }
+    }
+    return policyMeta;
+  }
+  /**
+   * Fill default policy values for metadata keys
+   * Matches JavaScript SDK fillDefault method exactly
+   */
+  fillDefault(metaKeys = []) {
+    const readPolicy = Array.from(this.policy).filter((item) => item.action === "read");
+    const writePolicy = Array.from(this.policy).filter((item) => item.action === "write");
+    for (const [type, value] of Object.entries({
+      read: readPolicy,
+      write: writePolicy
+    })) {
+      const policyKey = value.map((item) => item.key);
+      if (!this.policy[type]) {
+        this.policy[type] = {};
+      }
+      for (const key of diff(metaKeys, policyKey)) {
+        if (!this.policy[type][key]) {
+          this.policy[type][key] = type === "write" && !["characters", "pubkey"].includes(key) ? ["self"] : ["all"];
+        }
+      }
+    }
+  }
+  /**
+   * Get the policy object
+   * Matches JavaScript SDK get method exactly
+   */
+  get() {
+    return this.policy;
+  }
+  /**
+   * Convert policy to JSON string
+   * Matches JavaScript SDK toJson method exactly
+   */
+  toJson() {
+    return JSON.stringify(this.get());
+  }
+};
 var AtomMeta = class _AtomMeta {
   meta;
   /**
@@ -2780,8 +2945,9 @@ var AtomMeta = class _AtomMeta {
    * @return This instance for chaining
    */
   addPolicy(policy) {
+    const policyMeta = new PolicyMeta(policy, Object.keys(this.meta));
     this.merge({
-      policy: JSON.stringify(policy)
+      policy: policyMeta.toJson()
     });
     return this;
   }
@@ -3414,6 +3580,87 @@ function createMolecularHash(value) {
   }
   return value;
 }
+
+// src/core/TokenUnit.ts
+var TokenUnit = class _TokenUnit {
+  id;
+  name;
+  metas;
+  /**
+   * Create new TokenUnit instance
+   * Matches JavaScript SDK constructor signature exactly
+   */
+  constructor(id, name, metas) {
+    this.id = id;
+    this.name = name;
+    this.metas = metas || {};
+  }
+  /**
+   * Create TokenUnit from GraphQL response data
+   * Matches JavaScript SDK createFromGraphQL method exactly
+   */
+  static createFromGraphQL(data) {
+    let metas = data.metas || {};
+    if (Array.isArray(metas) && metas.length) {
+      try {
+        metas = JSON.parse(metas);
+        if (!metas) {
+          metas = {};
+        }
+      } catch (error) {
+        metas = {};
+      }
+    }
+    return new _TokenUnit(
+      data.id,
+      data.name,
+      metas
+    );
+  }
+  /**
+   * Create TokenUnit from database array data
+   * Matches JavaScript SDK createFromDB method exactly
+   */
+  static createFromDB(data) {
+    return new _TokenUnit(
+      data[0],
+      data[1],
+      data.length > 2 ? data[2] : {}
+    );
+  }
+  /**
+   * Get fragment zone from metadata
+   * Matches JavaScript SDK getFragmentZone method exactly
+   */
+  getFragmentZone() {
+    return this.metas.fragmentZone || null;
+  }
+  /**
+   * Get fused token units from metadata
+   * Matches JavaScript SDK getFusedTokenUnits method exactly
+   */
+  getFusedTokenUnits() {
+    return this.metas.fusedTokenUnits || null;
+  }
+  /**
+   * Convert to data array format
+   * Matches JavaScript SDK toData method exactly
+   */
+  toData() {
+    return [this.id, this.name, this.metas];
+  }
+  /**
+   * Convert to GraphQL response format
+   * Matches JavaScript SDK toGraphQLResponse method exactly
+   */
+  toGraphQLResponse() {
+    return {
+      id: this.id,
+      name: this.name,
+      metas: JSON.stringify(this.metas)
+    };
+  }
+};
 var Wallet = class _Wallet {
   token;
   balance;
@@ -3554,11 +3801,13 @@ var Wallet = class _Wallet {
     return typeof maybeBundleHash === "string" && isBundleHash(maybeBundleHash);
   }
   /**
-   * Get formatted token units from raw data
-   * Stub implementation for now
+   * Map raw token-unit tuples to TokenUnit instances.
+   * Matches JS SDK Wallet.getTokenUnits (Wallet.js:190-196). The serialised shape reaches hashed
+   * atom meta via AtomMeta.setAtomWallet -> JSON.stringify(getTokenUnitsData()), so returning raw
+   * tuples here would diverge from every other SDK.
    */
   static getTokenUnits(unitsData) {
-    return unitsData;
+    return unitsData.map((unitData) => TokenUnit.createFromDB(unitData));
   }
   /**
    * Create a remainder wallet for transactions
@@ -3855,7 +4104,7 @@ zod.z.string().regex(base17HashRegex, "Molecular hash must be base17 format (0-9
 var TokenSlugSchema = zod.z.string().min(1, "Token slug cannot be empty").max(64, "Token slug cannot exceed 64 characters").transform((val) => val.toUpperCase()).brand();
 var MetaTypeSchema = zod.z.string().min(1, "Meta type cannot be empty").max(256, "Meta type cannot exceed 256 characters").brand();
 var MetaIdSchema = zod.z.string().min(1, "Meta ID cannot be empty").brand();
-var BatchIdSchema = zod.z.string().min(1, "Batch ID cannot be empty").brand();
+var BatchIdSchema = zod.z.string().regex(/^[0-9a-fA-F]{64}$/, "Batch ID must be 64 hexadecimal characters").brand();
 var CellSlugSchema = zod.z.string().min(1, "Cell slug cannot be empty").max(64, "Cell slug cannot exceed 64 characters").brand();
 var AtomIsotopeSchema = zod.z.enum(["C", "V", "U", "T", "M", "I", "R", "B", "F"], {
   error: "Invalid atom isotope. Must be one of: C, V, U, T, M, I, R, B, F"
@@ -3916,7 +4165,8 @@ zod.z.object({
   socket: zod.z.unknown().optional(),
   serverSdkVersion: zod.z.number().int().min(1).optional(),
   logging: zod.z.boolean().optional(),
-  defaultRequestPolicy: zod.z.enum(["cache-first", "cache-only", "network-only", "cache-and-network"]).nullable().optional()
+  defaultRequestPolicy: zod.z.enum(["cache-first", "cache-only", "network-only", "cache-and-network"]).nullable().optional(),
+  secretStorage: zod.z.unknown().optional()
 }).strict();
 zod.z.object({
   token: zod.z.string().min(1, "Auth token cannot be empty"),
@@ -4179,58 +4429,6 @@ var RuleArgumentException = class extends exports.BaseException {
 };
 var RuleArgumentException_default = RuleArgumentException;
 
-// src/libraries/array.ts
-function deepCloning(o, h) {
-  let i;
-  let r;
-  let x;
-  const t = [Array, Date, Number, String, Boolean];
-  const s = Object.prototype.toString;
-  h = h || [];
-  for (i = 0; i < h.length; i += 2) {
-    if (o === h[i]) {
-      return h[i + 1];
-    }
-  }
-  if (!r && o && typeof o === "object") {
-    r = {};
-    for (i = 0; i < t.length; i++) {
-      if (s.call(o) === s.call(x = new t[i](o))) {
-        r = i ? x : [];
-      }
-    }
-    h.push(o, r);
-    for (i in o) {
-      if (Object.prototype.hasOwnProperty.call(o, i)) {
-        r[i] = deepCloning(o[i], h);
-      }
-    }
-  }
-  return r || o;
-}
-function chunkArray(arr, size) {
-  const chunks = [];
-  for (let i = 0; i < arr.length; i += size) {
-    chunks.push(arr.slice(i, i + size));
-  }
-  return chunks;
-}
-function diff(...arrays) {
-  return [].concat(...arrays.map((arr, i) => {
-    const others = arrays.slice(0);
-    others.splice(i, 1);
-    const unique = [...new Set([].concat(...others))];
-    return arr.filter((item) => !unique.includes(item));
-  }));
-}
-function intersect(...arrays) {
-  if (arrays.length === 0) return [];
-  if (arrays.length === 1) return arrays[0];
-  return arrays.reduce(
-    (first, second) => first.filter((item) => second.includes(item))
-  );
-}
-
 // src/instance/rules/Callback.ts
 init_exception();
 var CallbackParamsSchema = zod.z.object({
@@ -5561,6 +5759,51 @@ var Molecule = class _Molecule {
     }));
     return this;
   }
+  /**
+   * Replenishes non-finite token supplies.
+   * Matches JS SDK Molecule.replenishToken (Molecule.js:521-566) exactly.
+   *
+   * Two orderings here are load-bearing for the molecular hash and must not be reordered:
+   * the remainder balance is computed BEFORE the source balance is overwritten, and the
+   * source V-atom is added BEFORE the remainder V-atom.
+   */
+  replenishToken({
+    amount,
+    units = []
+  }) {
+    if (amount < 0) {
+      throw new NegativeAmountException("Molecule::replenishToken() - Amount to replenish must be positive!");
+    }
+    if (!this.sourceWallet || !this.remainderWallet) {
+      throw new Error("Source and remainder wallets required for token replenishment");
+    }
+    if (units.length) {
+      const formatted = Wallet.getTokenUnits(units);
+      this.remainderWallet.tokenUnits = this.sourceWallet.tokenUnits;
+      for (const unit of formatted) {
+        this.remainderWallet.tokenUnits.push(unit);
+      }
+      this.remainderWallet.balance = String(this.remainderWallet.tokenUnits.length);
+      this.sourceWallet.tokenUnits = formatted;
+      this.sourceWallet.balance = String(this.sourceWallet.tokenUnits.length);
+    } else {
+      this.remainderWallet.balance = String(Number(this.sourceWallet.balance) + amount);
+      this.sourceWallet.balance = String(amount);
+    }
+    this.addAtom(Atom.create({
+      isotope: "V",
+      wallet: this.sourceWallet,
+      value: Number(this.sourceWallet.balance)
+    }));
+    this.addAtom(Atom.create({
+      isotope: "V",
+      wallet: this.remainderWallet,
+      value: Number(this.remainderWallet.balance),
+      metaType: "walletBundle",
+      metaId: this.remainderWallet.bundle
+    }));
+    return this;
+  }
   /**
    * Initialize authorization request
    * Creates U-isotope (authorization) atom for requesting auth token
@@ -6095,16 +6338,27 @@ var GraphQLClient = class {
     return core.createClient({
       url: serverUri,
       exchanges,
-      // PQ-transport Phase E: when encryption is on, route fetch through the CipherHash wrapper
-      // (encrypt the request body to the validator's ML-KEM pubkey, decrypt the response).
-      // Omitted → urql uses the global fetch (plaintext).
-      ...this.cipherLink ? { fetch: ((input, init) => this.cipherFetch(input, init)) } : {},
+      // urql 5 had no default and always POSTed; urql 6 defaults to 'within-url-limit', which
+      // URL-encodes short queries and sends NO body. That would silently disable the CipherHash
+      // envelope below — cipherFetch's `typeof init.body === 'string'` guard fails on a GET, so
+      // the query would leave as plaintext URL parameters with no error. Pin POST explicitly.
+      preferGetMethod: false,
+      // Always route through our own fetch. Two reasons: (1) PQ-transport Phase E — when
+      // encryption is on, cipherFetch wraps the request body in the CipherHash envelope and
+      // decrypts the response; (2) the 60s timeout. urql's makeFetchSource unconditionally
+      // overwrites init.signal with its own AbortController, so a signal returned from
+      // fetchOptions() is discarded and never fired. Combining it here is the only place it
+      // survives.
+      fetch: ((input, init) => {
+        const timeoutSignal = AbortSignal.timeout(6e4);
+        const signal = init?.signal && typeof AbortSignal.any === "function" ? AbortSignal.any([init.signal, timeoutSignal]) : init?.signal ?? timeoutSignal;
+        const timedInit = { ...init, signal };
+        return this.cipherLink ? this.cipherFetch(input, timedInit) : fetch(input, timedInit);
+      }),
       fetchOptions: () => ({
         headers: {
           "X-Auth-Token": this.$__authToken
-        },
-        // Add 60 second timeout
-        signal: AbortSignal.timeout(6e4)
+        }
       })
     });
   }
@@ -6617,12 +6871,12 @@ var TokenSlugSchema2 = createBrandedSchema(
 );
 var BatchIdSchema2 = createBrandedSchema(
   "BatchId",
-  // v3's `.uuid()` regex, inlined verbatim. Zod 4's `z.uuid()` additionally enforces the
-  // RFC 9562 version/variant nibbles and would reject batch IDs v3 accepted.
-  zod.z.string().regex(
-    /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/,
-    "Invalid batch ID format"
-  )
+  // 64 hex characters. generateBatchId (src/libraries/crypto.ts) returns either
+  // shake256(molecularHash + index, 256) — 256 bits, 64 hex chars — or randomString(64) over the
+  // alphabet 'abcdef0123456789'. A UUID shape matches nothing this SDK can produce, so the
+  // previous 8-4-4-4-12 regex rejected every real batch ID. Agrees with isBatchId in
+  // src/types/guards.ts.
+  zod.z.string().regex(/^[0-9a-fA-F]{64}$/, "Invalid batch ID format")
 );
 var CellSlugSchema2 = createBrandedSchema(
   "CellSlug",
@@ -6712,7 +6966,9 @@ var KnishIOClientConfigSchema2 = zod.z.object({
   // Optional default urql request policy for reads (server/sync clients pass
   // 'network-only'). Permitted by the strict schema so the constructor option
   // isn't rejected.
-  defaultRequestPolicy: zod.z.enum(["cache-first", "cache-only", "network-only", "cache-and-network"]).nullable().optional()
+  defaultRequestPolicy: zod.z.enum(["cache-first", "cache-only", "network-only", "cache-and-network"]).nullable().optional(),
+  // Pluggable hardware envelope encryption secret storage provider
+  secretStorage: zod.z.unknown().optional()
 }).strict();
 var EnvironmentConfigSchema = zod.z.object({
   NODE_ENV: zod.z.enum(["development", "production", "test"]).optional(),
@@ -7487,127 +7743,44 @@ var ConfigValidator = class _ConfigValidator {
       duration
     });
     if (this.performanceMetrics.length > 1e3) {
-      this.performanceMetrics = this.performanceMetrics.slice(-1e3);
-    }
-  }
-  /**
-   * Clean up validation cache
-   */
-  cleanupCache() {
-    if (this.validationCache.size > 500) {
-      const entries = Array.from(this.validationCache.entries());
-      const toKeep = entries.slice(-250);
-      this.validationCache.clear();
-      toKeep.forEach(([key, value]) => this.validationCache.set(key, value));
-    }
-  }
-  /**
-   * Get validation statistics
-   */
-  getValidationStats() {
-    const recent = this.performanceMetrics.slice(-100);
-    const avgTime = recent.reduce((sum, m) => sum + m.duration, 0) / recent.length || 0;
-    return {
-      totalValidations: this.performanceMetrics.length,
-      cacheSize: this.validationCache.size,
-      averageValidationTime: Math.round(avgTime * 100) / 100,
-      recentValidations: recent.length
-    };
-  }
-  /**
-   * Clear validation cache and metrics
-   */
-  clearCache() {
-    this.validationCache.clear();
-    this.performanceMetrics = [];
-  }
-};
-
-// src/response/ResponseBalance.ts
-init_Response();
-
-// src/core/TokenUnit.ts
-var TokenUnit = class _TokenUnit {
-  id;
-  name;
-  metas;
-  /**
-   * Create new TokenUnit instance
-   * Matches JavaScript SDK constructor signature exactly
-   */
-  constructor(id, name, metas) {
-    this.id = id;
-    this.name = name;
-    this.metas = metas || {};
-  }
-  /**
-   * Create TokenUnit from GraphQL response data
-   * Matches JavaScript SDK createFromGraphQL method exactly
-   */
-  static createFromGraphQL(data) {
-    let metas = data.metas || {};
-    if (Array.isArray(metas) && metas.length) {
-      try {
-        metas = JSON.parse(metas);
-        if (!metas) {
-          metas = {};
-        }
-      } catch (error) {
-        metas = {};
-      }
-    }
-    return new _TokenUnit(
-      data.id,
-      data.name,
-      metas
-    );
-  }
-  /**
-   * Create TokenUnit from database array data
-   * Matches JavaScript SDK createFromDB method exactly
-   */
-  static createFromDB(data) {
-    return new _TokenUnit(
-      data[0],
-      data[1],
-      data.length > 2 ? data[2] : {}
-    );
-  }
-  /**
-   * Get fragment zone from metadata
-   * Matches JavaScript SDK getFragmentZone method exactly
-   */
-  getFragmentZone() {
-    return this.metas.fragmentZone || null;
-  }
-  /**
-   * Get fused token units from metadata
-   * Matches JavaScript SDK getFusedTokenUnits method exactly
-   */
-  getFusedTokenUnits() {
-    return this.metas.fusedTokenUnits || null;
+      this.performanceMetrics = this.performanceMetrics.slice(-1e3);
+    }
   }
   /**
-   * Convert to data array format
-   * Matches JavaScript SDK toData method exactly
+   * Clean up validation cache
    */
-  toData() {
-    return [this.id, this.name, this.metas];
+  cleanupCache() {
+    if (this.validationCache.size > 500) {
+      const entries = Array.from(this.validationCache.entries());
+      const toKeep = entries.slice(-250);
+      this.validationCache.clear();
+      toKeep.forEach(([key, value]) => this.validationCache.set(key, value));
+    }
   }
   /**
-   * Convert to GraphQL response format
-   * Matches JavaScript SDK toGraphQLResponse method exactly
+   * Get validation statistics
    */
-  toGraphQLResponse() {
+  getValidationStats() {
+    const recent = this.performanceMetrics.slice(-100);
+    const avgTime = recent.reduce((sum, m) => sum + m.duration, 0) / recent.length || 0;
     return {
-      id: this.id,
-      name: this.name,
-      metas: JSON.stringify(this.metas)
+      totalValidations: this.performanceMetrics.length,
+      cacheSize: this.validationCache.size,
+      averageValidationTime: Math.round(avgTime * 100) / 100,
+      recentValidations: recent.length
     };
   }
+  /**
+   * Clear validation cache and metrics
+   */
+  clearCache() {
+    this.validationCache.clear();
+    this.performanceMetrics = [];
+  }
 };
 
 // src/response/ResponseBalance.ts
+init_Response();
 var ResponseBalance = class _ResponseBalance extends exports.Response {
   /**
    * Class constructor
@@ -10116,6 +10289,12 @@ var MutationAppendRequest = class extends MutationProposeMolecule {
   }
 };
 
+// src/mutation/MutationReplenishToken.ts
+var MutationReplenishToken = class extends MutationProposeMolecule {
+  fillMolecule() {
+  }
+};
+
 // src/subscribe/Subscribe.ts
 init_exception();
 var Subscribe = class {
@@ -10327,9 +10506,134 @@ var ActiveSessionSubscribe = class extends Subscribe {
 
 // src/KnishIOClient.ts
 init_exception();
+
+// src/storage/MemorySecretStorageProvider.ts
+init_SecretStorageException();
+
+// src/libraries/secureMemory.ts
+var textEncoder = new TextEncoder();
+function zeroizeBytes(buffer) {
+  if (buffer instanceof Uint8Array) {
+    buffer.fill(0);
+  } else if (Array.isArray(buffer)) {
+    for (let i = 0; i < buffer.length; i++) {
+      buffer[i] = 0;
+    }
+  }
+}
+async function withSecureBytes(bytes, fn) {
+  try {
+    return await fn(bytes);
+  } finally {
+    zeroizeBytes(bytes);
+  }
+}
+async function withSecureString(secret, fn) {
+  const bytes = textEncoder.encode(secret);
+  try {
+    return await fn(secret);
+  } finally {
+    zeroizeBytes(bytes);
+  }
+}
+function constantTimeCompare(a, b) {
+  const bytesA = typeof a === "string" ? textEncoder.encode(a) : a;
+  const bytesB = typeof b === "string" ? textEncoder.encode(b) : b;
+  let result = bytesA.length === bytesB.length ? 0 : 1;
+  const len = Math.min(bytesA.length, bytesB.length);
+  for (let i = 0; i < len; i++) {
+    const byteA = bytesA[i] ?? 0;
+    const byteB = bytesB[i] ?? 0;
+    result |= byteA ^ byteB;
+  }
+  if (typeof a === "string") zeroizeBytes(bytesA);
+  if (typeof b === "string") zeroizeBytes(bytesB);
+  return result === 0;
+}
+
+// src/storage/MemorySecretStorageProvider.ts
+var MemorySecretStorageProvider = class {
+  providerType = "memory";
+  secrets = /* @__PURE__ */ new Map();
+  /**
+   * Memory storage is not hardware backed
+   */
+  isHardwareBacked() {
+    return false;
+  }
+  /**
+   * Memory storage is always available
+   */
+  async isAvailable() {
+    return true;
+  }
+  /**
+   * Store a secret in memory
+   */
+  async storeSecret(bundleHash, secret, options) {
+    if (!bundleHash) {
+      throw new exports.SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!secret) {
+      throw new exports.SecretStorageException("Secret cannot be empty");
+    }
+    const metadata = {
+      bundleHash,
+      label: options?.label,
+      createdAt: Date.now(),
+      hardwareBacked: false,
+      providerType: this.providerType
+    };
+    this.secrets.set(bundleHash, { secret, metadata });
+  }
+  /**
+   * Retrieve a secret from memory
+   */
+  async retrieveSecret(bundleHash) {
+    const entry = this.secrets.get(bundleHash);
+    return entry ? entry.secret : null;
+  }
+  /**
+   * Delete a stored secret
+   */
+  async deleteSecret(bundleHash) {
+    return this.secrets.delete(bundleHash);
+  }
+  /**
+   * Check if a secret exists
+   */
+  async hasSecret(bundleHash) {
+    return this.secrets.has(bundleHash);
+  }
+  /**
+   * List all stored secret metadata
+   */
+  async listSecrets() {
+    return Array.from(this.secrets.values()).map((entry) => ({ ...entry.metadata }));
+  }
+  /**
+   * Execute callback with unwrapped secret and ensure cleanup
+   */
+  async withSecret(bundleHash, fn) {
+    const entry = this.secrets.get(bundleHash);
+    if (!entry) {
+      throw exports.SecretStorageException.notFound(bundleHash);
+    }
+    return withSecureString(entry.secret, fn);
+  }
+  /**
+   * Clear all secrets from memory
+   */
+  clear() {
+    this.secrets.clear();
+  }
+};
+
+// src/KnishIOClient.ts
 var KnishIOClient = class {
   $__secret = "";
   $__bundle = "";
+  $__secretStorage = null;
   $__cellSlug = null;
   $__encrypt = false;
   $__uris = [];
@@ -10389,6 +10693,9 @@ var KnishIOClient = class {
       logging,
       defaultRequestPolicy
     });
+    if (config.secretStorage) {
+      this.$__secretStorage = config.secretStorage;
+    }
   }
   /**
    * Initializes a new Knish.IO client session
@@ -10490,6 +10797,7 @@ var KnishIOClient = class {
   reset() {
     this.$__secret = "";
     this.$__bundle = "";
+    this.$__secretStorage = null;
     this.$__encrypt = false;
     this.$__cellSlug = null;
     this.$__authToken = null;
@@ -10551,7 +10859,7 @@ var KnishIOClient = class {
    * Returns whether a secret is stored for this session
    */
   hasSecret() {
-    return !!this.$__secret && this.$__secret.length > 0;
+    return !!this.$__secret && this.$__secret.length > 0 || !!this.$__secretStorage && !!this.$__bundle && this.$__bundle.length > 0;
   }
   /**
    * Returns the stored secret
@@ -10562,6 +10870,33 @@ var KnishIOClient = class {
     }
     return this.$__secret;
   }
+  /**
+   * Sets the secret storage provider and optionally sets the bundle hash
+   */
+  setSecretStorage(storage, bundleHash) {
+    this.$__secretStorage = storage;
+    if (bundleHash) {
+      this.$__bundle = bundleHash;
+    }
+  }
+  /**
+   * Returns current secret storage provider
+   */
+  getSecretStorage() {
+    return this.$__secretStorage;
+  }
+  /**
+   * Asynchronously retrieves the secret from storage or returns in-memory secret
+   */
+  async retrieveSecret(options) {
+    if (this.$__secret && this.$__secret.length > 0) {
+      return this.$__secret;
+    }
+    if (this.$__secretStorage && this.$__bundle && this.$__bundle.length > 0) {
+      return await this.$__secretStorage.retrieveSecret(this.$__bundle, options);
+    }
+    return null;
+  }
   /**
    * Returns whether a bundle hash is being stored for this session
    */
@@ -10600,6 +10935,13 @@ var KnishIOClient = class {
     remainderWallet = null
   } = {}) {
     this.log("info", "KnishIOClient::createMolecule() - Creating a new molecule...");
+    if (!secret) {
+      if (this.$__secret && this.$__secret.length > 0) {
+        secret = this.getSecret();
+      } else if (this.$__secretStorage && this.$__bundle && this.$__bundle.length > 0) {
+        secret = await this.$__secretStorage.retrieveSecret(this.$__bundle);
+      }
+    }
     secret = secret || this.getSecret();
     bundle = bundle || this.getBundle();
     let continuIdPosition = null;
@@ -10629,6 +10971,7 @@ var KnishIOClient = class {
     }));
     return new Molecule({
       secret,
+      bundle,
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
@@ -10675,8 +11018,9 @@ var KnishIOClient = class {
   async executeQuery(query, variables = null, context = {}) {
     if (this.$__authToken && this.$__authToken.isExpired() && !this.$__authInProcess) {
       this.log("info", "KnishIOClient::executeQuery() - Access token is expired. Getting new one...");
+      const authSecret = this.$__secret || await this.retrieveSecret() || "";
       await this.requestAuthToken({
-        secret: this.$__secret,
+        secret: authSecret,
         cellSlug: this.$__cellSlug,
         encrypt: this.$__encrypt
       });
@@ -10716,6 +11060,13 @@ var KnishIOClient = class {
   setSecret(secret) {
     this.$__secret = secret;
     this.$__bundle = generateBundleHash(secret);
+    if (!this.$__secretStorage) {
+      const memStorage = new MemorySecretStorageProvider();
+      memStorage.storeSecret(this.$__bundle, secret);
+      this.$__secretStorage = memStorage;
+    } else {
+      this.$__secretStorage.storeSecret(this.$__bundle, secret);
+    }
   }
   /**
    * Sets the auth token for this session
@@ -10899,6 +11250,9 @@ var KnishIOClient = class {
     if (secret === null && seed) {
       secret = generateSecret(seed);
     }
+    if (secret === null && this.$__secretStorage && this.$__bundle) {
+      secret = await this.$__secretStorage.retrieveSecret(this.$__bundle);
+    }
     if (cellSlug) {
       this.setCellSlug(cellSlug);
     }
@@ -11549,20 +11903,42 @@ var KnishIOClient = class {
     return response;
   }
   /**
-   * Replenish tokens
+   * Replenish a non-finite token supply.
+   * Matches JS SDK KnishIOClient.replenishToken (KnishIOClient.js:2195-2231).
    */
   async replenishToken({
     token,
     amount = null,
     units = null,
-    sourceWallet: _sourceWallet = null
+    sourceWallet = null
   }) {
     this.log("info", `KnishIOClient::replenishToken() - Replenishing ${amount || "units"} of ${token}...`);
-    return this.requestTokens({
-      token,
-      amount,
-      units
+    if (!sourceWallet) {
+      sourceWallet = (await this.queryBalance({ token }))?.payload();
+    }
+    if (!sourceWallet) {
+      throw new exports.TransferBalanceException("Source wallet is missing or invalid.");
+    }
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret());
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    });
+    molecule.replenishToken({
+      amount: Number(amount ?? 0),
+      units: units ?? []
     });
+    molecule.sign({ bundle: this.getBundle() });
+    molecule.check();
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationReplenishToken,
+      molecule
+    });
+    const response = await this.executeQuery(mutation);
+    if (!response) {
+      throw new CodeException("Token replenishment failed");
+    }
+    return response;
   }
   /**
    * Fuse token units
@@ -12013,75 +12389,298 @@ var KnishIOClient = class {
 
 // src/index.ts
 init_Response();
+init_exception();
 
-// src/core/PolicyMeta.ts
-var PolicyMeta = class _PolicyMeta {
-  policy;
+// src/storage/WebCryptoSecretStorageProvider.ts
+init_SecretStorageException();
+var MemoryStorageBackend = class {
+  store = /* @__PURE__ */ new Map();
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    return this.store.delete(key);
+  }
+  keys() {
+    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 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;
+  }
   /**
-   * Create new PolicyMeta instance
-   * Matches JavaScript SDK constructor signature exactly
+   * Whether this provider is backed by hardware (e.g. WebAuthn PRF wrapping)
    */
-  constructor(policy = {}, metaKeys = []) {
-    this.policy = _PolicyMeta.normalizePolicy(policy);
-    this.fillDefault(metaKeys);
+  isHardwareBacked() {
+    return this.hardwareBacked;
   }
   /**
-   * Normalize policy object structure
-   * Matches JavaScript SDK normalizePolicy method exactly
+   * Check if WebCrypto subtle API is available
    */
-  static normalizePolicy(policy = {}) {
-    const policyMeta = {};
-    for (const [policyKey, value] of Object.entries(policy)) {
-      if (value !== null && ["read", "write"].includes(policyKey)) {
-        policyMeta[policyKey] = {};
-        for (const [key, content] of Object.entries(value)) {
-          policyMeta[policyKey][key] = content;
-        }
-      }
+  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 exports.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);
     }
-    return policyMeta;
   }
   /**
-   * Fill default policy values for metadata keys
-   * Matches JavaScript SDK fillDefault method exactly
+   * Store and encrypt a master secret
    */
-  fillDefault(metaKeys = []) {
-    const readPolicy = Array.from(this.policy).filter((item) => item.action === "read");
-    const writePolicy = Array.from(this.policy).filter((item) => item.action === "write");
-    for (const [type, value] of Object.entries({
-      read: readPolicy,
-      write: writePolicy
-    })) {
-      const policyKey = value.map((item) => item.key);
-      if (!this.policy[type]) {
-        this.policy[type] = {};
-      }
-      for (const key of diff(metaKeys, policyKey)) {
-        if (!this.policy[type][key]) {
-          this.policy[type][key] = type === "write" && !["characters", "pubkey"].includes(key) ? ["self"] : ["all"];
-        }
+  async storeSecret(bundleHash, secret, options) {
+    if (!bundleHash) {
+      throw new exports.SecretStorageException("Bundle hash cannot be empty");
+    }
+    if (!secret) {
+      throw new exports.SecretStorageException("Secret cannot be empty");
+    }
+    const passphrase = options?.passphrase ?? this.defaultPassphrase;
+    if (!passphrase) {
+      throw new exports.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);
+    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,
+        providerType: this.providerType
+      };
+      const payload = {
+        version: 1,
+        ciphertext,
+        iv: uint8ArrayToBase64(iv),
+        salt: uint8ArrayToBase64(salt),
+        algorithm: "AES-GCM",
+        iterations: DEFAULT_ITERATIONS,
+        metadata
+      };
+      await this.backend.setItem(`${KEY_PREFIX}${bundleHash}`, JSON.stringify(payload));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new exports.SecretStorageException(`Encryption failed: ${msg}`);
+    } finally {
+      zeroizeBytes(secretBytes);
+    }
+  }
+  /**
+   * Retrieve and decrypt the master secret
+   */
+  async retrieveSecret(bundleHash, options) {
+    const raw = await this.backend.getItem(`${KEY_PREFIX}${bundleHash}`);
+    if (!raw) {
+      return null;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw exports.SecretStorageException.decryptionFailed("Corrupted payload format");
+    }
+    const passphrase = options?.passphrase ?? this.defaultPassphrase;
+    if (!passphrase) {
+      throw new exports.SecretStorageException("Passphrase required for secret decryption");
+    }
+    const salt = base64ToUint8Array(payload.salt);
+    const iv = base64ToUint8Array(payload.iv);
+    const ciphertext = base64ToUint8Array(payload.ciphertext);
+    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);
+      try {
+        return textDecoder.decode(decryptedBytes);
+      } finally {
+        zeroizeBytes(decryptedBytes);
       }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw exports.SecretStorageException.decryptionFailed(msg);
     }
   }
   /**
-   * Get the policy object
-   * Matches JavaScript SDK get method exactly
+   * Delete a stored secret
    */
-  get() {
-    return this.policy;
+  async deleteSecret(bundleHash) {
+    const key = `${KEY_PREFIX}${bundleHash}`;
+    const result = await this.backend.removeItem(key);
+    return result !== false;
   }
   /**
-   * Convert policy to JSON string
-   * Matches JavaScript SDK toJson method exactly
+   * Check if a secret exists
    */
-  toJson() {
-    return JSON.stringify(this.get());
+  async hasSecret(bundleHash) {
+    const raw = await this.backend.getItem(`${KEY_PREFIX}${bundleHash}`);
+    return raw !== null;
+  }
+  /**
+   * List all stored secret metadata
+   */
+  async listSecrets() {
+    const keys = await this.backend.keys();
+    const matchingKeys = keys.filter((k) => k.startsWith(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;
+  }
+  /**
+   * Execute callback with unwrapped secret, zeroizing the decrypted buffer upon completion
+   */
+  async withSecret(bundleHash, fn, options) {
+    const raw = await this.backend.getItem(`${KEY_PREFIX}${bundleHash}`);
+    if (!raw) {
+      throw exports.SecretStorageException.notFound(bundleHash);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      throw exports.SecretStorageException.decryptionFailed("Corrupted payload format");
+    }
+    const passphrase = options?.passphrase ?? this.defaultPassphrase;
+    if (!passphrase) {
+      throw new exports.SecretStorageException("Passphrase required for secret decryption");
+    }
+    const salt = base64ToUint8Array(payload.salt);
+    const iv = base64ToUint8Array(payload.iv);
+    const ciphertext = base64ToUint8Array(payload.ciphertext);
+    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);
+      return await withSecureBytes(decryptedBytes, async (bytes) => {
+        const secretString = textDecoder.decode(bytes);
+        return await fn(secretString);
+      });
+    } catch (err) {
+      if (err instanceof exports.SecretStorageException) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw exports.SecretStorageException.decryptionFailed(msg);
+    }
   }
 };
 
+// src/storage/index.ts
+function createDefaultSecretStorage(options = {}) {
+  if (options.type === "memory") {
+    return new MemorySecretStorageProvider();
+  }
+  if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.subtle !== "undefined") {
+    return new WebCryptoSecretStorageProvider({
+      backend: options.backend,
+      defaultPassphrase: options.defaultPassphrase,
+      hardwareBacked: options.hardwareBacked
+    });
+  }
+  return new MemorySecretStorageProvider();
+}
+
 // src/index.ts
-init_exception();
-var SDK_VERSION = "0.9.5";
+var SDK_VERSION = "0.9.7";
 var SDK_NAME = "KnishIO-Client-TS";
 var COMPATIBLE_SERVER_VERSIONS = [4, 5];
 var SDK_INFO = {
@@ -12182,6 +12781,8 @@ exports.EXTENDED_COMPATIBILITY_TEST_VECTORS = EXTENDED_COMPATIBILITY_TEST_VECTOR
 exports.GraphQLClient = GraphQLClient;
 exports.KnishIO = KnishIO;
 exports.KnishIOClient = KnishIOClient;
+exports.MemorySecretStorageProvider = MemorySecretStorageProvider;
+exports.MemoryStorageBackend = MemoryStorageBackend;
 exports.Meta = Meta;
 exports.Molecule = Molecule;
 exports.Mutation = Mutation;
@@ -12227,6 +12828,7 @@ exports.SDK_NAME = SDK_NAME;
 exports.SDK_VERSION = SDK_VERSION;
 exports.TokenUnit = TokenUnit;
 exports.Wallet = Wallet;
+exports.WebCryptoSecretStorageProvider = WebCryptoSecretStorageProvider;
 exports.base64ToHex = base64ToHex;
 exports.bufferToHexString = bufferToHexString;
 exports.capitalize = capitalize;
@@ -12234,8 +12836,10 @@ exports.charsetBaseConvert = charsetBaseConvert;
 exports.chunkArray = chunkArray;
 exports.chunkSubstr = chunkSubstr;
 exports.configureSDK = configureSDK;
+exports.constantTimeCompare = constantTimeCompare;
 exports.convertToBase17 = convertToBase17;
 exports.createBundleHash = createBundleHash;
+exports.createDefaultSecretStorage = createDefaultSecretStorage;
 exports.createMolecularHash = createMolecularHash;
 exports.createPosition = createPosition;
 exports.createTokenSlug = createTokenSlug;
@@ -12277,5 +12881,8 @@ exports.validatePosition = validatePosition;
 exports.validateSecret = validateSecret;
 exports.validateWalletAddress = validateWalletAddress;
 exports.verifyOTSSignature = verifyOTSSignature;
+exports.withSecureBytes = withSecureBytes;
+exports.withSecureString = withSecureString;
+exports.zeroizeBytes = zeroizeBytes;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map