@wishknish/knishio-client-ts 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "productName": "Knish.IO TypeScript SDK Client",
   "description": "TypeScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs with enhanced type safety.",
   "license": "GPL-3.0-or-later",

package/src/exception/SecretStorageException.ts

@@ -94,4 +94,13 @@ export default class SecretStorageException extends BaseException {
       }
     )
   }
+
+  /**
+   * Validation error for storage options or parameters
+   */
+  static validationError(message: string): SecretStorageException {
+    return new SecretStorageException(message, {
+      code: 'VALIDATION_ERROR'
+    })
+  }
 }

package/src/index.ts

@@ -275,10 +275,23 @@ export {
 export {
   MemorySecretStorageProvider,
   WebCryptoSecretStorageProvider,
+  WebAuthnPrfSecretStorageProvider,
+  NonExtractableKeySecretStorageProvider,
+  IndexedDbKeyStore,
+  MemoryKeyStore,
   MemoryStorageBackend,
+  FileStorageBackend,
+  WebStorageBackend,
   createDefaultSecretStorage,
+  sealEnvelope,
+  openEnvelope,
+  SECRET_KEY_PREFIX,
+  RECOVERY_KEY_PREFIX,
   type IStorageBackend,
-  type CreateSecretStorageOptions
+  type IKeyStore,
+  type CreateSecretStorageOptions,
+  type WebAuthnPrfSecretStorageOptions,
+  type NonExtractableKeyStorageOptions
 } from './storage'
 
 export {
@@ -291,6 +304,7 @@ export {
 export type {
   SecretStorageMetadata,
   EncryptedSecretPayload,
+  StorageOptions,
   ISecretStorageProvider
 } from './types/storage'
 
@@ -389,7 +403,7 @@ export {
 // MUST equal package.json's "version". The CI `version consistency` job enforces this via
 // .github/scripts/check-version.sh, which parses this exact line — keep the literal form
 // `export const SDK_VERSION = '<semver>'` intact so the gate can read it.
-export const SDK_VERSION = '1.0.0'
+export const SDK_VERSION = '1.2.0'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 

package/src/libraries/GraphQLClient.ts

@@ -55,6 +55,7 @@ import {
 } from '@urql/core'
 import { createClient as createWSClient } from 'graphql-ws'
 import { pipe, subscribe } from 'wonka'
+import { CodeException } from '@/exception'
 import type {
   GraphQLClient as IGraphQLClient,
   GraphQLRequest,
@@ -200,17 +201,29 @@ export default class GraphQLClient implements IGraphQLClient {
   private async cipherFetch(input: any, init: any): Promise<Response> {
     const wallet = this.$__wallet
     const serverPubkey = this.$__pubkey
-    let encryptedRequest = false
+    // Non-null only on the encrypted path, so the response decrypt needs no assertion.
+    let cipherWallet: Wallet | null = null
     let requestInit = init
 
-    if (wallet && serverPubkey && init && typeof init.body === 'string' && this.shouldEncrypt(init.body)) {
+    // Decide the bypass FIRST, then demand the keys: a bypassed operation (`__schema`,
+    // `ContinuId`, `AccessToken`, U-isotope `ProposeMolecule`) must still go out in plaintext or
+    // the auth bootstrap would deadlock encrypting to a server pubkey it has not learned yet.
+    // Anything else on an encryption-enabled client fails closed rather than silently
+    // downgrading to plaintext (matches PHP Cipher.php / Kotlin HttpClient).
+    if (init && typeof init.body === 'string' && this.shouldEncrypt(init.body)) {
+      if (!wallet) {
+        throw new CodeException('Authorized wallet missing.')
+      }
+      if (!serverPubkey) {
+        throw new CodeException('Server public key missing.')
+      }
       const hashVar = await wallet.encryptStringML(init.body, serverPubkey)
       requestInit = { ...init, body: JSON.stringify({ query: CIPHER_HASH_QUERY, variables: { Hash: hashVar } }) }
-      encryptedRequest = true
+      cipherWallet = wallet
     }
 
     const response = await fetch(input, requestInit)
-    if (!encryptedRequest) {
+    if (!cipherWallet) {
       return response
     }
 
@@ -228,7 +241,7 @@ export default class GraphQLClient implements IGraphQLClient {
       // Plaintext (e.g. a validator-side error response) — pass through unchanged.
       return new Response(text, init2)
     }
-    const decrypted = await wallet!.decryptMyMessageML(JSON.parse(hash))
+    const decrypted = await cipherWallet.decryptMyMessageML(JSON.parse(hash))
     return new Response(decrypted != null ? decrypted : text, init2)
   }
 

package/src/storage/FileStorageBackend.ts

@@ -0,0 +1,176 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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'
+
+/**
+ * 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 implements IStorageBackend {
+  readonly filePath: string
+  private store: Map<string, string> = new Map()
+  private loaded = false
+
+  constructor(filePath: string) {
+    if (!filePath) {
+      throw new SecretStorageException('Storage file path cannot be empty')
+    }
+    this.filePath = filePath
+  }
+
+  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(): Promise<Map<string, string>> {
+    if (this.loaded) {
+      return this.store
+    }
+
+    const { fs } = await this.getFs()
+
+    try {
+      const content = await fs.readFile(this.filePath, 'utf8')
+      let parsed: Record<string, unknown>
+      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: unknown) {
+      if (err instanceof SecretStorageException) {
+        throw err
+      }
+      // If file does not exist (ENOENT), treat as empty map
+      const nodeErr = err as { code?: string }
+      if (nodeErr?.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(): Promise<void> {
+    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 errors if file system does not support it
+        }
+      }
+      await fs.rename(tmpPath, this.filePath)
+    } catch (err: unknown) {
+      try {
+        await fs.unlink(tmpPath)
+      } catch {
+        // Ignore unlink cleanup error
+      }
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new SecretStorageException(`Failed to persist storage file: ${msg}`)
+    }
+  }
+
+  async getItem(key: string): Promise<string | null> {
+    await this.ensureLoaded()
+    return this.store.get(key) ?? null
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    await this.ensureLoaded()
+    this.store.set(key, value)
+    await this.persist()
+  }
+
+  async removeItem(key: string): Promise<boolean> {
+    await this.ensureLoaded()
+    const existed = this.store.delete(key)
+    if (existed) {
+      await this.persist()
+    }
+    return existed
+  }
+
+  async keys(): Promise<string[]> {
+    await this.ensureLoaded()
+    return Array.from(this.store.keys())
+  }
+}

package/src/storage/MemorySecretStorageProvider.ts

@@ -46,9 +46,15 @@ Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
 License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 */
 
-import type { ISecretStorageProvider, SecretStorageMetadata } from '@/types/storage'
+import type {
+  ISecretStorageProvider,
+  SecretStorageMetadata,
+  EncryptedSecretPayload,
+  StorageOptions
+} from '@/types/storage'
 import SecretStorageException from '@/exception/SecretStorageException'
-import { withSecureString } from '@/libraries/secureMemory'
+import { withSecureString, zeroizeBytes } from '@/libraries/secureMemory'
+import { sealEnvelope, openEnvelope } from './secretEnvelope'
 
 interface MemorySecretEntry {
   secret: string
@@ -62,6 +68,7 @@ interface MemorySecretEntry {
 export default class MemorySecretStorageProvider implements ISecretStorageProvider {
   public readonly providerType = 'memory'
   private secrets: Map<string, MemorySecretEntry> = new Map()
+  private recoverySecrets: Map<string, string> = new Map()
 
   /**
    * Memory storage is not hardware backed
@@ -83,7 +90,7 @@ export default class MemorySecretStorageProvider implements ISecretStorageProvid
   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')
@@ -101,6 +108,18 @@ export default class MemorySecretStorageProvider implements ISecretStorageProvid
     }
 
     this.secrets.set(bundleHash, { secret, metadata })
+
+    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)
+      this.recoverySecrets.set(bundleHash, JSON.stringify(recoveryPayload))
+    }
   }
 
   /**
@@ -115,6 +134,7 @@ export default class MemorySecretStorageProvider implements ISecretStorageProvid
    * Delete a stored secret
    */
   async deleteSecret(bundleHash: string): Promise<boolean> {
+    this.recoverySecrets.delete(bundleHash)
     return this.secrets.delete(bundleHash)
   }
 
@@ -152,5 +172,57 @@ export default class MemorySecretStorageProvider implements ISecretStorageProvid
    */
   clear(): void {
     this.secrets.clear()
+    this.recoverySecrets.clear()
+  }
+
+  /**
+   * Recover a secret using its recovery envelope and restore it
+   */
+  async recoverSecret(
+    bundleHash: string,
+    recoveryPassphrase: string,
+    options?: { label?: 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 = this.recoverySecrets.get(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 = new TextDecoder().decode(decryptedBytes)
+    } finally {
+      zeroizeBytes(decryptedBytes)
+    }
+
+    await this.storeSecret(bundleHash, secretStr, {
+      ...options,
+      recoveryPassphrase
+    })
   }
 }