@wishknish/knishio-client-ts 1.0.0 → 1.2.0

package/src/storage/WebCryptoSecretStorageProvider.ts

@@ -49,10 +49,17 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 import type {
   ISecretStorageProvider,
   SecretStorageMetadata,
-  EncryptedSecretPayload
+  EncryptedSecretPayload,
+  StorageOptions
 } from '@/types/storage'
 import SecretStorageException from '@/exception/SecretStorageException'
 import { zeroizeBytes, withSecureBytes } from '@/libraries/secureMemory'
+import {
+  sealEnvelope,
+  openEnvelope,
+  SECRET_KEY_PREFIX,
+  RECOVERY_KEY_PREFIX
+} from './secretEnvelope'
 
 /**
  * Storage backend adapter interface (supports Memory, LocalStorage, IndexedDB, etc.)
@@ -87,64 +94,35 @@ export class MemoryStorageBackend implements IStorageBackend {
   }
 }
 
-/**
- * Helper to convert Uint8Array to base64
- */
-function uint8ArrayToBase64(bytes: Uint8Array): string {
-  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
- */
-function base64ToUint8Array(base64: string): Uint8Array {
-  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 implements ISecretStorageProvider {
   public readonly providerType = 'webcrypto-aes-gcm'
   private backend: IStorageBackend
   private defaultPassphrase?: string
-  private hardwareBacked: boolean
 
   constructor(options: {
     backend?: IStorageBackend
     defaultPassphrase?: string
-    hardwareBacked?: boolean
   } = {}) {
     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(): boolean {
-    return this.hardwareBacked
+    return false
   }
 
   /**
@@ -157,48 +135,13 @@ export default class WebCryptoSecretStorageProvider implements ISecretStoragePro
     )
   }
 
-  /**
-   * Derive an AES-GCM CryptoKey from a passphrase and salt using PBKDF2
-   */
-  private async deriveKey(passphrase: string, salt: Uint8Array, iterations = DEFAULT_ITERATIONS): Promise<CryptoKey> {
-    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: salt as BufferSource,
-          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: string,
     secret: string,
-    options?: { label?: string; passphrase?: string }
+    options?: StorageOptions
   ): Promise<void> {
     if (!bundleHash) {
       throw new SecretStorageException('Bundle hash cannot be empty')
@@ -212,49 +155,39 @@ export default class WebCryptoSecretStorageProvider implements ISecretStoragePro
       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: iv as BufferSource
-        },
-        key,
-        secretBytes
-      )
-
-      const ciphertext = uint8ArrayToBase64(new Uint8Array(encryptedBuffer))
       const metadata: SecretStorageMetadata = {
         bundleHash,
         label: options?.label,
         createdAt: Date.now(),
-        hardwareBacked: this.hardwareBacked,
+        hardwareBacked: false,
         providerType: this.providerType
       }
 
-      const payload: EncryptedSecretPayload = {
-        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: SecretStorageMetadata = {
+          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: unknown) {
+      if (err instanceof SecretStorageException) {
+        throw err
+      }
       const msg = err instanceof Error ? err.message : String(err)
       throw new SecretStorageException(`Encryption failed: ${msg}`)
-    } finally {
-      zeroizeBytes(secretBytes)
     }
   }
 
@@ -282,28 +215,21 @@ export default class WebCryptoSecretStorageProvider implements ISecretStoragePro
       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: iv as BufferSource
-        },
-        key,
-        ciphertext as BufferSource
-      )
-
-      const decryptedBytes = new Uint8Array(decryptedBuffer)
+      const decryptedBytes = await openEnvelope(payload, passphrase)
       try {
         return textDecoder.decode(decryptedBytes)
       } finally {
         zeroizeBytes(decryptedBytes)
       }
     } catch (err: unknown) {
+      if (err instanceof SecretStorageException) {
+        throw err
+      }
       const msg = err instanceof Error ? err.message : String(err)
       throw SecretStorageException.decryptionFailed(msg)
     }
@@ -314,7 +240,9 @@ export default class WebCryptoSecretStorageProvider implements ISecretStoragePro
    */
   async deleteSecret(bundleHash: string): Promise<boolean> {
     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
   }
 
@@ -331,7 +259,7 @@ export default class WebCryptoSecretStorageProvider implements ISecretStoragePro
    */
   async listSecrets(): Promise<SecretStorageMetadata[]> {
     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: SecretStorageMetadata[] = []
 
     for (const key of matchingKeys) {
@@ -376,22 +304,12 @@ export default class WebCryptoSecretStorageProvider implements ISecretStoragePro
       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: iv as BufferSource
-        },
-        key,
-        ciphertext as BufferSource
-      )
-
-      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)
@@ -404,4 +322,57 @@ export default class WebCryptoSecretStorageProvider implements ISecretStoragePro
       throw SecretStorageException.decryptionFailed(msg)
     }
   }
+
+  /**
+   * Recover a secret using its recovery envelope and re-enroll it
+   */
+  async recoverSecret(
+    bundleHash: string,
+    recoveryPassphrase: string,
+    options?: { label?: string; passphrase?: string }
+  ): Promise<void> {
+    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: EncryptedSecretPayload
+    try {
+      payload = JSON.parse(raw)
+    } catch {
+      throw SecretStorageException.decryptionFailed('Corrupted recovery payload format')
+    }
+
+    let decryptedBytes: Uint8Array
+    try {
+      decryptedBytes = await openEnvelope(payload, recoveryPassphrase)
+    } catch (err: unknown) {
+      if (err instanceof SecretStorageException) {
+        throw err
+      }
+      const msg = err instanceof Error ? err.message : String(err)
+      throw SecretStorageException.decryptionFailed(msg)
+    }
+
+    let secretStr: string
+    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.ts

@@ -0,0 +1,102 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import type { IStorageBackend } from './WebCryptoSecretStorageProvider'
+import SecretStorageException from '@/exception/SecretStorageException'
+
+/**
+ * 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 implements IStorageBackend {
+  private readonly storage: Storage
+  readonly prefix: string
+
+  constructor(storage?: 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: string): string | null {
+    return this.storage.getItem(key)
+  }
+
+  setItem(key: string, value: string): void {
+    this.storage.setItem(key, value)
+  }
+
+  removeItem(key: string): boolean {
+    const existed = this.storage.getItem(key) !== null
+    this.storage.removeItem(key)
+    return existed
+  }
+
+  keys(): string[] {
+    const result: string[] = []
+    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.ts

@@ -52,6 +52,32 @@ export {
   MemoryStorageBackend,
   type IStorageBackend
 } from './WebCryptoSecretStorageProvider'
+export { default as FileStorageBackend } from './FileStorageBackend'
+export { default as WebStorageBackend } from './WebStorageBackend'
+export {
+  default as WebAuthnPrfSecretStorageProvider,
+  type WebAuthnPrfSecretStorageOptions,
+  PRF_SALT_LABEL,
+  KEK_INFO
+} from './WebAuthnPrfSecretStorageProvider'
+export {
+  default as NonExtractableKeySecretStorageProvider,
+  type NonExtractableKeyStorageOptions,
+  type IKeyStore,
+  IndexedDbKeyStore,
+  MemoryKeyStore
+} from './NonExtractableKeySecretStorageProvider'
+export {
+  sealEnvelope,
+  openEnvelope,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+  deriveEnvelopeKey,
+  ENVELOPE_ALGORITHM,
+  DEFAULT_ITERATIONS,
+  SECRET_KEY_PREFIX,
+  RECOVERY_KEY_PREFIX
+} from './secretEnvelope'
 
 import type { ISecretStorageProvider } from '@/types/storage'
 import MemorySecretStorageProvider from './MemorySecretStorageProvider'
@@ -61,7 +87,6 @@ export interface CreateSecretStorageOptions {
   type?: 'webcrypto' | 'memory'
   defaultPassphrase?: string
   backend?: IStorageBackend
-  hardwareBacked?: boolean
 }
 
 /**
@@ -79,7 +104,6 @@ export function createDefaultSecretStorage(
     return new WebCryptoSecretStorageProvider({
       backend: options.backend,
       defaultPassphrase: options.defaultPassphrase,
-      hardwareBacked: options.hardwareBacked
     })
   }