@wishknish/knishio-client-ts 0.9.5 → 0.9.7

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/mutation/MutationReplenishToken.ts

@@ -0,0 +1,28 @@
+/*
+        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 MutationProposeMolecule from './MutationProposeMolecule'
+
+/**
+ * Mutation for replenishing a non-finite token supply.
+ *
+ * The JS SDK submits replenishment through `MutationProposeMolecule` directly
+ * (KnishIOClient.js:2226-2230), but that class is abstract here because it declares
+ * `fillMolecule`. This subclass exists to provide the concrete type; it inherits the identical
+ * `ProposeMolecule(molecule: $molecule)` document from the base, so the request on the wire is
+ * the same one the JS SDK sends.
+ *
+ * `fillMolecule` is intentionally a no-op: KnishIOClient.replenishToken builds the V-atom pair
+ * via Molecule.replenishToken, then signs and checks the molecule, before this mutation is
+ * constructed. There is nothing left to fill.
+ */
+export default class MutationReplenishToken extends MutationProposeMolecule {
+  override fillMolecule(): void {
+    // Intentionally empty — the molecule arrives fully built, signed and checked.
+  }
+}

package/src/schemas/index.ts

@@ -117,7 +117,7 @@ export const MetaIdSchema = z.string()
   .brand<'MetaId'>()
 
 export const BatchIdSchema = z.string()
-  .min(1, 'Batch ID cannot be empty')
+  .regex(/^[0-9a-fA-F]{64}$/, 'Batch ID must be 64 hexadecimal characters')
   .brand<'BatchId'>()
 
 export const CellSlugSchema = z.string()
@@ -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()
+  }
+}