@wishknish/knishio-client-ts 0.9.6 → 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();
@@ -4115,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"),
@@ -6915,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(),
@@ -10453,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 = [];
@@ -10515,6 +10693,9 @@ var KnishIOClient = class {
       logging,
       defaultRequestPolicy
     });
+    if (config.secretStorage) {
+      this.$__secretStorage = config.secretStorage;
+    }
   }
   /**
    * Initializes a new Knish.IO client session
@@ -10616,6 +10797,7 @@ var KnishIOClient = class {
   reset() {
     this.$__secret = "";
     this.$__bundle = "";
+    this.$__secretStorage = null;
     this.$__encrypt = false;
     this.$__cellSlug = null;
     this.$__authToken = null;
@@ -10677,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
@@ -10688,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
    */
@@ -10726,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;
@@ -10755,6 +10971,7 @@ var KnishIOClient = class {
     }));
     return new Molecule({
       secret,
+      bundle,
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
@@ -10801,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
       });
@@ -10842,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
@@ -11025,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);
     }
@@ -12162,7 +12390,297 @@ var KnishIOClient = class {
 // src/index.ts
 init_Response();
 init_exception();
-var SDK_VERSION = "0.9.6";
+
+// 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;
+  }
+  /**
+   * Whether this provider is backed by hardware (e.g. WebAuthn PRF wrapping)
+   */
+  isHardwareBacked() {
+    return this.hardwareBacked;
+  }
+  /**
+   * Check if WebCrypto subtle API is available
+   */
+  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);
+    }
+  }
+  /**
+   * Store and encrypt a master secret
+   */
+  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);
+    }
+  }
+  /**
+   * Delete a stored secret
+   */
+  async deleteSecret(bundleHash) {
+    const key = `${KEY_PREFIX}${bundleHash}`;
+    const result = await this.backend.removeItem(key);
+    return result !== false;
+  }
+  /**
+   * Check if a secret exists
+   */
+  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
+var SDK_VERSION = "0.9.7";
 var SDK_NAME = "KnishIO-Client-TS";
 var COMPATIBLE_SERVER_VERSIONS = [4, 5];
 var SDK_INFO = {
@@ -12263,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;
@@ -12308,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;
@@ -12315,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;
@@ -12358,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