@wishknish/knishio-client-ts 0.9.6 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "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/KnishIOClient.ts

@@ -128,6 +128,8 @@ import {
   SignatureMismatchException,
   AtomIndexException
 } from '@/exception'
+import type { ISecretStorageProvider } from '@/types/storage'
+import MemorySecretStorageProvider from '@/storage/MemorySecretStorageProvider'
 
 // Type imports
 import type {
@@ -150,6 +152,7 @@ import type {
 export default class KnishIOClient {
   private $__secret: string = ''
   private $__bundle: string = ''
+  private $__secretStorage: ISecretStorageProvider | null = null
   private $__cellSlug: string | null = null
   private $__encrypt: boolean = false
   private $__uris: string[] = []
@@ -185,6 +188,7 @@ export default class KnishIOClient {
     serverSdkVersion?: number
     logging?: boolean
     defaultRequestPolicy?: RequestPolicy | null
+    secretStorage?: ISecretStorageProvider | null
   }) {
     // Phase 2 Enhancement: Use standardized configuration validation
     const standardValidationResult = ConfigValidator.validateClientConfig(config)
@@ -236,6 +240,10 @@ export default class KnishIOClient {
       logging,
       defaultRequestPolicy
     })
+
+    if (config.secretStorage) {
+      this.$__secretStorage = config.secretStorage
+    }
   }
 
   /**
@@ -365,6 +373,7 @@ export default class KnishIOClient {
   reset(): void {
     this.$__secret = ''
     this.$__bundle = ''
+    this.$__secretStorage = null
     this.$__encrypt = false
     this.$__cellSlug = null
     this.$__authToken = null
@@ -434,7 +443,7 @@ export default class KnishIOClient {
    * Returns whether a secret is stored for this session
    */
   hasSecret(): boolean {
-    return !!this.$__secret && this.$__secret.length > 0
+    return (!!this.$__secret && this.$__secret.length > 0) || (!!this.$__secretStorage && !!this.$__bundle && this.$__bundle.length > 0)
   }
 
   /**
@@ -447,6 +456,36 @@ export default class KnishIOClient {
     return this.$__secret
   }
 
+  /**
+   * Sets the secret storage provider and optionally sets the bundle hash
+   */
+  setSecretStorage(storage: ISecretStorageProvider, bundleHash?: string): void {
+    this.$__secretStorage = storage
+    if (bundleHash) {
+      this.$__bundle = bundleHash
+    }
+  }
+
+  /**
+   * Returns current secret storage provider
+   */
+  getSecretStorage(): ISecretStorageProvider | null {
+    return this.$__secretStorage
+  }
+
+  /**
+   * Asynchronously retrieves the secret from storage or returns in-memory secret
+   */
+  async retrieveSecret(options?: { passphrase?: string }): Promise<string | null> {
+    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
    */
@@ -495,6 +534,14 @@ export default class KnishIOClient {
   } = {}): Promise<Molecule> {
     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()
 
@@ -547,6 +594,7 @@ export default class KnishIOClient {
 
     return new Molecule({
       secret,
+      bundle,
       sourceWallet,
       remainderWallet: this.getRemainderWallet()!,
       cellSlug: this.getCellSlug(),
@@ -612,8 +660,9 @@ export default class KnishIOClient {
     // Guard with $__authInProcess to prevent recursive auth refresh
     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
       })
@@ -673,6 +722,13 @@ export default class KnishIOClient {
   setSecret(secret: string): void {
     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)
+    }
   }
 
   /**
@@ -924,6 +980,11 @@ export default class KnishIOClient {
       secret = generateSecret(seed)
     }
 
+    // Retrieve secret from storage provider if available
+    if (secret === null && this.$__secretStorage && this.$__bundle) {
+      secret = await this.$__secretStorage.retrieveSecret(this.$__bundle)
+    }
+
     // Set cell slug if provided
     if (cellSlug) {
       this.setCellSlug(cellSlug)

package/src/exception/SecretStorageException.ts

@@ -0,0 +1,97 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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 BaseException, { type BaseExceptionOptions } from './BaseException'
+
+/**
+ * Exception thrown when a secret storage or hardware envelope encryption operation fails
+ */
+export default class SecretStorageException extends BaseException {
+  constructor(message = 'Secret storage operation failed', options: BaseExceptionOptions = {}) {
+    super('WALLET_CREDENTIAL_ERROR', message, {
+      code: 'SECRET_STORAGE_ERROR',
+      ...options
+    })
+  }
+
+  /**
+   * Secret not found for the requested bundle hash
+   */
+  static notFound(bundleHash: string): SecretStorageException {
+    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?: string): SecretStorageException {
+    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: string, reason?: string): SecretStorageException {
+    return new SecretStorageException(
+      `Secret storage provider '${provider}' is unavailable: ${reason || 'Hardware or API not accessible'}`,
+      {
+        code: 'STORAGE_UNAVAILABLE',
+        details: { provider, reason }
+      }
+    )
+  }
+}

package/src/exception/index.ts

@@ -62,6 +62,7 @@ export { default as MolecularHashMismatchException } from './MolecularHashMismat
 export { default as SignatureMismatchException } from './SignatureMismatchException'
 export { default as TransferBalanceException } from './TransferBalanceException'
 export { default as WalletCredentialException } from './WalletCredentialException'
+export { default as SecretStorageException } from './SecretStorageException'
 export { default as InvalidResponseException } from './InvalidResponseException'
 
 // Additional exceptions (now implemented)

package/src/index.ts

@@ -261,12 +261,39 @@ export {
   SignatureMismatchException,
   TransferBalanceException,
   WalletCredentialException,
+  SecretStorageException,
   InvalidResponseException,
   ExceptionFactory,
   EXCEPTION_TYPES,
   EXCEPTION_CODES
 } from './exception'
 
+// =============================================================================
+// SECRET STORAGE & HARDWARE ENVELOPE ENCRYPTION
+// =============================================================================
+
+export {
+  MemorySecretStorageProvider,
+  WebCryptoSecretStorageProvider,
+  MemoryStorageBackend,
+  createDefaultSecretStorage,
+  type IStorageBackend,
+  type CreateSecretStorageOptions
+} from './storage'
+
+export {
+  zeroizeBytes,
+  withSecureBytes,
+  withSecureString,
+  constantTimeCompare
+} from './libraries/secureMemory'
+
+export type {
+  SecretStorageMetadata,
+  EncryptedSecretPayload,
+  ISecretStorageProvider
+} from './types/storage'
+
 // =============================================================================
 // TYPE DEFINITIONS
 // =============================================================================
@@ -362,7 +389,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 = '0.9.6'
+export const SDK_VERSION = '0.9.7'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 

package/src/libraries/secureMemory.ts

@@ -0,0 +1,121 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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
+*/
+
+/**
+ * Memory hygiene and zeroization utilities for sensitive cryptographic material
+ */
+
+const textEncoder = new TextEncoder()
+
+/**
+ * Overwrite byte array contents with zeros
+ */
+export function zeroizeBytes(buffer: Uint8Array | number[]): void {
+  if (buffer instanceof Uint8Array) {
+    buffer.fill(0)
+  } else if (Array.isArray(buffer)) {
+    for (let i = 0; i < buffer.length; i++) {
+      buffer[i] = 0
+    }
+  }
+}
+
+/**
+ * Execute a callback with a byte buffer and guarantee zeroization upon completion
+ */
+export async function withSecureBytes<T>(
+  bytes: Uint8Array,
+  fn: (bytes: Uint8Array) => Promise<T> | T
+): Promise<T> {
+  try {
+    return await fn(bytes)
+  } finally {
+    zeroizeBytes(bytes)
+  }
+}
+
+/**
+ * Execute a callback with a secret string, ensuring temporary byte buffers are cleared
+ */
+export async function withSecureString<T>(
+  secret: string,
+  fn: (cleanSecret: string) => Promise<T> | T
+): Promise<T> {
+  const bytes = textEncoder.encode(secret)
+  try {
+    return await fn(secret)
+  } finally {
+    zeroizeBytes(bytes)
+  }
+}
+
+/**
+ * Constant-time comparison of two byte arrays or strings to prevent timing attacks
+ */
+export function constantTimeCompare(
+  a: Uint8Array | string,
+  b: Uint8Array | string
+): boolean {
+  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
+  }
+
+  // Zeroize temporary buffers if they were converted from strings
+  if (typeof a === 'string') zeroizeBytes(bytesA)
+  if (typeof b === 'string') zeroizeBytes(bytesB)
+
+  return result === 0
+}

package/src/schemas/index.ts

@@ -207,7 +207,8 @@ export const KnishIOClientConfigSchema = z.object({
   socket: z.unknown().optional(),
   serverSdkVersion: z.number().int().min(1).optional(),
   logging: z.boolean().optional(),
-  defaultRequestPolicy: z.enum(['cache-first', 'cache-only', 'network-only', 'cache-and-network']).nullable().optional()
+  defaultRequestPolicy: z.enum(['cache-first', 'cache-only', 'network-only', 'cache-and-network']).nullable().optional(),
+  secretStorage: z.unknown().optional()
 }).strict()
 
 // =============================================================================

package/src/storage/MemorySecretStorageProvider.ts

@@ -0,0 +1,156 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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 { ISecretStorageProvider, SecretStorageMetadata } from '@/types/storage'
+import SecretStorageException from '@/exception/SecretStorageException'
+import { withSecureString } from '@/libraries/secureMemory'
+
+interface MemorySecretEntry {
+  secret: string
+  metadata: SecretStorageMetadata
+}
+
+/**
+ * In-memory secret storage provider
+ * Used for testing, headless runners, and backward-compatible fallback
+ */
+export default class MemorySecretStorageProvider implements ISecretStorageProvider {
+  public readonly providerType = 'memory'
+  private secrets: Map<string, MemorySecretEntry> = new Map()
+
+  /**
+   * Memory storage is not hardware backed
+   */
+  isHardwareBacked(): boolean {
+    return false
+  }
+
+  /**
+   * Memory storage is always available
+   */
+  async isAvailable(): Promise<boolean> {
+    return true
+  }
+
+  /**
+   * Store a secret in memory
+   */
+  async storeSecret(
+    bundleHash: string,
+    secret: string,
+    options?: { label?: string; passphrase?: string }
+  ): Promise<void> {
+    if (!bundleHash) {
+      throw new SecretStorageException('Bundle hash cannot be empty')
+    }
+    if (!secret) {
+      throw new SecretStorageException('Secret cannot be empty')
+    }
+
+    const metadata: SecretStorageMetadata = {
+      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: string): Promise<string | null> {
+    const entry = this.secrets.get(bundleHash)
+    return entry ? entry.secret : null
+  }
+
+  /**
+   * Delete a stored secret
+   */
+  async deleteSecret(bundleHash: string): Promise<boolean> {
+    return this.secrets.delete(bundleHash)
+  }
+
+  /**
+   * Check if a secret exists
+   */
+  async hasSecret(bundleHash: string): Promise<boolean> {
+    return this.secrets.has(bundleHash)
+  }
+
+  /**
+   * List all stored secret metadata
+   */
+  async listSecrets(): Promise<SecretStorageMetadata[]> {
+    return Array.from(this.secrets.values()).map(entry => ({ ...entry.metadata }))
+  }
+
+  /**
+   * Execute callback with unwrapped secret and ensure cleanup
+   */
+  async withSecret<T>(
+    bundleHash: string,
+    fn: (secret: string) => Promise<T> | T
+  ): Promise<T> {
+    const entry = this.secrets.get(bundleHash)
+    if (!entry) {
+      throw SecretStorageException.notFound(bundleHash)
+    }
+
+    return withSecureString(entry.secret, fn)
+  }
+
+  /**
+   * Clear all secrets from memory
+   */
+  clear(): void {
+    this.secrets.clear()
+  }
+}