@wishknish/knishio-client-js 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "productName": "Knish.IO Javascript SDK Client",
   "description": "JavaScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs.",

package/src/exception/SecretStorageException.js

@@ -92,4 +92,14 @@ export default class SecretStorageException extends BaseException {
   static unavailable (provider, reason = 'Hardware or API not accessible') {
     return new SecretStorageException(`Secret storage provider '${provider}' is unavailable: ${reason}`)
   }
+
+  /**
+   * Factory method: validation error
+   *
+   * @param {string} message
+   * @returns {SecretStorageException}
+   */
+  static validationError (message) {
+    return new SecretStorageException(message)
+  }
 }

package/src/index.js

@@ -330,8 +330,18 @@ export {
 export {
   MemorySecretStorageProvider,
   WebCryptoSecretStorageProvider,
+  WebAuthnPrfSecretStorageProvider,
+  NonExtractableKeySecretStorageProvider,
+  IndexedDbKeyStore,
+  MemoryKeyStore,
   MemoryStorageBackend,
-  createDefaultSecretStorage
+  FileStorageBackend,
+  WebStorageBackend,
+  createDefaultSecretStorage,
+  sealEnvelope,
+  openEnvelope,
+  SECRET_KEY_PREFIX,
+  RECOVERY_KEY_PREFIX
 } from './storage/index.js'
 
 export {

package/src/storage/FileStorageBackend.js

@@ -0,0 +1,199 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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'
+
+/**
+ * Node-only persistent file storage backend.
+ * Stores key-value entries in a JSON file with restrictive permissions (0o600).
+ * Uses temporary file writing followed by atomic rename to prevent corruption.
+ */
+export default class FileStorageBackend {
+  /**
+   * @param {string} filePath
+   */
+  constructor (filePath) {
+    if (!filePath) {
+      throw new SecretStorageException('Storage file path cannot be empty')
+    }
+    this.filePath = filePath
+    this.store = new Map()
+    this.loaded = false
+  }
+
+  /**
+   * @private
+   */
+  async getFs () {
+    try {
+      // Platform-specific: node:fs and node:path do not exist in browser runtimes
+      // and cannot be statically imported without breaking browser bundles.
+      const fs = await import('node:fs/promises')
+      const path = await import('node:path')
+      return { fs, path }
+    } catch {
+      throw SecretStorageException.unavailable(
+        'file-storage',
+        'FileStorageBackend is only supported in Node.js environments with node:fs access'
+      )
+    }
+  }
+
+  /**
+   * @private
+   */
+  async ensureLoaded () {
+    if (this.loaded) {
+      return this.store
+    }
+
+    const { fs } = await this.getFs()
+
+    try {
+      const content = await fs.readFile(this.filePath, 'utf8')
+      let parsed
+      try {
+        parsed = JSON.parse(content)
+      } catch {
+        throw SecretStorageException.decryptionFailed('Corrupted storage file format')
+      }
+
+      if (parsed && typeof parsed === 'object') {
+        this.store = new Map(Object.entries(parsed).map(([k, v]) => [k, String(v)]))
+      }
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err
+      }
+      if (err?.code !== 'ENOENT') {
+        const msg = err instanceof Error ? err.message : String(err)
+        throw new SecretStorageException(`Failed to read storage file: ${msg}`)
+      }
+      this.store = new Map()
+    }
+
+    this.loaded = true
+    return this.store
+  }
+
+  /**
+   * @private
+   */
+  async persist () {
+    const { fs, path } = await this.getFs()
+
+    const dir = path.dirname(this.filePath)
+    if (dir && dir !== '.') {
+      await fs.mkdir(dir, { recursive: true })
+    }
+
+    const tmpPath = `${this.filePath}.tmp.${Date.now()}_${Math.random().toString(36).slice(2)}`
+    const data = JSON.stringify(Object.fromEntries(this.store), null, 2)
+
+    try {
+      await fs.writeFile(tmpPath, data, { mode: 0o600, encoding: 'utf8' })
+      if (typeof process !== 'undefined' && process.platform !== 'win32') {
+        try {
+          await fs.chmod(tmpPath, 0o600)
+        } catch {
+          // Ignore chmod error if file system does not support it
+        }
+      }
+      await fs.rename(tmpPath, this.filePath)
+    } catch (err) {
+      try {
+        await fs.unlink(tmpPath)
+      } catch {
+        // Ignore cleanup error
+      }
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new SecretStorageException(`Failed to persist storage file: ${msg}`)
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<string|null>}
+   */
+  async getItem (key) {
+    await this.ensureLoaded()
+    return this.store.get(key) ?? null
+  }
+
+  /**
+   * @param {string} key
+   * @param {string} value
+   * @returns {Promise<void>}
+   */
+  async setItem (key, value) {
+    await this.ensureLoaded()
+    this.store.set(key, value)
+    await this.persist()
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async removeItem (key) {
+    await this.ensureLoaded()
+    const existed = this.store.delete(key)
+    if (existed) {
+      await this.persist()
+    }
+    return existed
+  }
+
+  /**
+   * @returns {Promise<string[]>}
+   */
+  async keys () {
+    await this.ensureLoaded()
+    return Array.from(this.store.keys())
+  }
+}

package/src/storage/MemorySecretStorageProvider.js

@@ -47,7 +47,8 @@ License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
 
 import SecretStorageException from '../exception/SecretStorageException.js'
-import { withSecureString } from '../libraries/secureMemory.js'
+import { withSecureString, zeroizeBytes } from '../libraries/secureMemory.js'
+import { sealEnvelope, openEnvelope } from './secretEnvelope.js'
 
 /**
  * In-memory secret storage provider
@@ -57,6 +58,7 @@ export default class MemorySecretStorageProvider {
   constructor () {
     this.providerType = 'memory'
     this.secrets = new Map()
+    this.recoverySecrets = new Map()
   }
 
   /**
@@ -102,6 +104,18 @@ export default class MemorySecretStorageProvider {
     }
 
     this.secrets.set(bundleHash, { secret, metadata })
+
+    if (options.recoveryPassphrase) {
+      const recoveryMetadata = {
+        bundleHash,
+        label: options.label,
+        createdAt: Date.now(),
+        hardwareBacked: false,
+        providerType: 'webcrypto-aes-gcm'
+      }
+      const recoveryPayload = await sealEnvelope(secret, options.recoveryPassphrase, recoveryMetadata)
+      this.recoverySecrets.set(bundleHash, JSON.stringify(recoveryPayload))
+    }
   }
 
   /**
@@ -122,6 +136,7 @@ export default class MemorySecretStorageProvider {
    * @returns {Promise<boolean>}
    */
   async deleteSecret (bundleHash) {
+    this.recoverySecrets.delete(bundleHash)
     return this.secrets.delete(bundleHash)
   }
 
@@ -166,5 +181,58 @@ export default class MemorySecretStorageProvider {
    */
   clear () {
     this.secrets.clear()
+    this.recoverySecrets.clear()
+  }
+
+  /**
+   * Recover a secret using its recovery envelope and restore it
+   *
+   * @param {string} bundleHash
+   * @param {string} recoveryPassphrase
+   * @param {{ label?: 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 = this.recoverySecrets.get(bundleHash)
+    if (!raw) {
+      throw SecretStorageException.notFound(bundleHash)
+    }
+
+    let payload
+    try {
+      payload = JSON.parse(raw)
+    } catch {
+      throw SecretStorageException.decryptionFailed('Corrupted recovery payload format')
+    }
+
+    let decryptedBytes
+    try {
+      decryptedBytes = await openEnvelope(payload, recoveryPassphrase)
+    } catch (err) {
+      if (err instanceof SecretStorageException) {
+        throw err
+      }
+      const msg = err instanceof Error ? err.message : String(err)
+      throw SecretStorageException.decryptionFailed(msg)
+    }
+
+    let secretStr
+    try {
+      secretStr = new TextDecoder().decode(decryptedBytes)
+    } finally {
+      zeroizeBytes(decryptedBytes)
+    }
+
+    await this.storeSecret(bundleHash, secretStr, {
+      ...options,
+      recoveryPassphrase
+    })
   }
 }