@wishknish/knishio-client-js 0.9.4 → 1.1.0

package/src/storage/WebCryptoSecretStorageProvider.js

@@ -48,6 +48,14 @@ License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 
 import SecretStorageException from '../exception/SecretStorageException.js'
 import { zeroizeBytes, withSecureBytes } from '../libraries/secureMemory.js'
+import {
+  sealEnvelope,
+  openEnvelope,
+  deriveEnvelopeKey,
+  DEFAULT_ITERATIONS,
+  SECRET_KEY_PREFIX,
+  RECOVERY_KEY_PREFIX
+} from './secretEnvelope.js'
 
 /**
  * Default in-memory backend for WebCrypto encrypted payloads
@@ -74,67 +82,34 @@ export class MemoryStorageBackend {
   }
 }
 
-/**
- * Helper to convert Uint8Array to base64
- *
- * @param {Uint8Array} bytes
- * @returns {string}
- */
-function uint8ArrayToBase64 (bytes) {
-  let binary = ''
-  const len = bytes.byteLength
-  for (let i = 0; i < len; i++) {
-    const byte = bytes[i]
-    if (byte !== undefined) {
-      binary += String.fromCharCode(byte)
-    }
-  }
-  return btoa(binary)
-}
-
-/**
- * Helper to convert base64 to Uint8Array
- *
- * @param {string} base64
- * @returns {Uint8Array}
- */
-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
-}
-
-const textEncoder = new TextEncoder()
 const textDecoder = new TextDecoder()
-const KEY_PREFIX = 'knishio:secret:'
-const DEFAULT_ITERATIONS = 100000
+const KEY_PREFIX = SECRET_KEY_PREFIX
 
 /**
- * Hardware-compatible envelope encryption secret storage provider
- * Uses WebCrypto AES-GCM (256-bit) with PBKDF2-HMAC-SHA256 key derivation
+ * Software envelope-encryption secret storage provider: WebCrypto AES-256-GCM with PBKDF2-HMAC-SHA256.
+ * Writes the cross-SDK envelope format; never hardware-backed.
  */
 export default class WebCryptoSecretStorageProvider {
   /**
-   * @param {{ backend?: object, defaultPassphrase?: string, hardwareBacked?: boolean }} [options]
+   * @param {{ backend?: object, defaultPassphrase?: string }} [options]
    */
   constructor (options = {}) {
     this.providerType = 'webcrypto-aes-gcm'
     this.backend = options.backend || new MemoryStorageBackend()
     this.defaultPassphrase = options.defaultPassphrase
-    this.hardwareBacked = options.hardwareBacked || false
   }
 
   /**
-   * Whether this provider is backed by hardware
+   * 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.
    *
    * @returns {boolean}
    */
   isHardwareBacked () {
-    return this.hardwareBacked
+    return false
   }
 
   /**
@@ -161,32 +136,7 @@ export default class WebCryptoSecretStorageProvider {
     if (!await this.isAvailable()) {
       throw SecretStorageException.unavailable(this.providerType, 'WebCrypto API is not available')
     }
-
-    const passphraseBytes = textEncoder.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 await deriveEnvelopeKey(passphrase, salt, iterations)
   }
 
   /**
@@ -210,49 +160,39 @@ export default class WebCryptoSecretStorageProvider {
       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 = textEncoder.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)
     }
   }
 
@@ -280,29 +220,21 @@ export default class WebCryptoSecretStorageProvider {
     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)
     }
@@ -316,7 +248,9 @@ export default class WebCryptoSecretStorageProvider {
    */
   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
   }
 
@@ -338,7 +272,7 @@ export default class WebCryptoSecretStorageProvider {
    */
   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) {
@@ -385,22 +319,12 @@ export default class WebCryptoSecretStorageProvider {
       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)
@@ -413,4 +337,58 @@ export default class WebCryptoSecretStorageProvider {
       throw SecretStorageException.decryptionFailed(msg)
     }
   }
+
+  /**
+   * Recover a secret using its recovery envelope and re-enroll it
+   *
+   * @param {string} bundleHash
+   * @param {string} recoveryPassphrase
+   * @param {{ label?: string, passphrase?: string }} [options]
+   * @returns {Promise<void>}
+   */
+  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
+    })
+  }
 }

package/src/storage/WebStorageBackend.js

@@ -0,0 +1,117 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
+*/
+
+import SecretStorageException from '../exception/SecretStorageException.js'
+
+/**
+ * Browser persistent storage backend wrapping Web Storage (localStorage or sessionStorage).
+ * Adapts the Web Storage API (length + key(i)) to IStorageBackend.keys(), filtering
+ * by a prefix (defaults to 'knishio:') so unrelated items are ignored.
+ */
+export default class WebStorageBackend {
+  /**
+   * @param {Storage} [storage]
+   * @param {string} [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
+  }
+
+  /**
+   * @param {string} key
+   * @returns {string|null}
+   */
+  getItem (key) {
+    return this.storage.getItem(key)
+  }
+
+  /**
+   * @param {string} key
+   * @param {string} value
+   */
+  setItem (key, value) {
+    this.storage.setItem(key, value)
+  }
+
+  /**
+   * @param {string} key
+   * @returns {boolean}
+   */
+  removeItem (key) {
+    const existed = this.storage.getItem(key) !== null
+    this.storage.removeItem(key)
+    return existed
+  }
+
+  /**
+   * @returns {string[]}
+   */
+  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
+  }
+}

package/src/storage/index.js

@@ -51,6 +51,29 @@ export {
   default as WebCryptoSecretStorageProvider,
   MemoryStorageBackend
 } from './WebCryptoSecretStorageProvider.js'
+export { default as FileStorageBackend } from './FileStorageBackend.js'
+export { default as WebStorageBackend } from './WebStorageBackend.js'
+export {
+  default as WebAuthnPrfSecretStorageProvider,
+  PRF_SALT_LABEL,
+  KEK_INFO
+} from './WebAuthnPrfSecretStorageProvider.js'
+export {
+  default as NonExtractableKeySecretStorageProvider,
+  IndexedDbKeyStore,
+  MemoryKeyStore
+} from './NonExtractableKeySecretStorageProvider.js'
+export {
+  sealEnvelope,
+  openEnvelope,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+  deriveEnvelopeKey,
+  ENVELOPE_ALGORITHM,
+  DEFAULT_ITERATIONS,
+  SECRET_KEY_PREFIX,
+  RECOVERY_KEY_PREFIX
+} from './secretEnvelope.js'
 
 import MemorySecretStorageProvider from './MemorySecretStorageProvider.js'
 import WebCryptoSecretStorageProvider from './WebCryptoSecretStorageProvider.js'
@@ -58,7 +81,7 @@ import WebCryptoSecretStorageProvider from './WebCryptoSecretStorageProvider.js'
 /**
  * Factory function to create a secret storage provider
  *
- * @param {{ type?: 'webcrypto'|'memory', defaultPassphrase?: string, backend?: object, hardwareBacked?: boolean }} [options]
+ * @param {{ type?: 'webcrypto'|'memory', defaultPassphrase?: string, backend?: object }} [options]
  * @returns {object}
  */
 export function createDefaultSecretStorage (options = {}) {
@@ -70,8 +93,7 @@ export 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
     })
   }