space-data-module-sdk 0.5.22 → 0.6.1

package/src/index.d.ts

@@ -409,6 +409,18 @@ export interface RuntimeHost {
   rows: FlatSqlRuntimeStore;
   regions: RuntimeRegionStore;
   moduleRegistry: RuntimeModuleRegistry;
+  listCapabilities(): string[];
+  listSupportedCapabilities(): string[];
+  listOperations(): string[];
+  hasCapability(capability: string): boolean;
+  getCapability(capability: string): Record<string, (...args: any[]) => unknown> | null;
+  registerCapability(
+    capability: string,
+    adapter: Record<string, (...args: any[]) => unknown>,
+  ): Record<string, (...args: any[]) => unknown>;
+  unregisterCapability(capability: string): boolean;
+  invokeCapability(operation: string, params?: Record<string, any>): Promise<unknown>;
+  invoke(operation: string, params?: Record<string, any>): Promise<unknown>;
 }
 
 export function createFlatBufferStreamIngestor(options?: {
@@ -1117,13 +1129,21 @@ export interface BrowserEdgeShims {
     now(): number;
     timeOrigin: number;
   };
+  network?: Record<string, (...args: any[]) => unknown> | null;
+  ipfs?: Record<string, (...args: any[]) => unknown> | null;
+  walletSign?: Record<string, (...args: any[]) => unknown> | null;
+  protocolHandle?: Record<string, (...args: any[]) => unknown> | null;
+  protocolDial?: Record<string, (...args: any[]) => unknown> | null;
   filesystem?: BrowserFilesystemShim;
+  filesystemRoot?: string;
+  capabilityAdapters?: Record<string, Record<string, (...args: any[]) => unknown>>;
 }
 
 export interface BrowserHostOptions {
   capabilities?: string[];
   edgeShims?: BrowserEdgeShims;
   contextStore?: Map<string, Map<string, unknown>>;
+  wasmWallet?: unknown;
   fetch?: (...args: any[]) => Promise<any>;
   WebSocket?: any;
   crypto?: any;
@@ -1133,6 +1153,12 @@ export interface BrowserHostOptions {
   };
   filesystem?: BrowserFilesystemShim;
   filesystemRoot?: string;
+  network?: Record<string, (...args: any[]) => unknown> | null;
+  ipfs?: Record<string, (...args: any[]) => unknown> | null;
+  walletSign?: Record<string, (...args: any[]) => unknown> | null;
+  protocolHandle?: Record<string, (...args: any[]) => unknown> | null;
+  protocolDial?: Record<string, (...args: any[]) => unknown> | null;
+  capabilityAdapters?: Record<string, Record<string, (...args: any[]) => unknown>>;
 }
 
 export interface NodeHostOptions {
@@ -1156,6 +1182,40 @@ export interface NodeHostOptions {
   contextStore?: NodeHostContextStore;
   fetch?: (...args: any[]) => Promise<any>;
   WebSocket?: any;
+  filesystem?: {
+    resolvePath(path: string): string;
+    readFile(
+      path: string,
+      options?: { encoding?: string | null },
+    ): Promise<string | Uint8Array>;
+    writeFile(
+      path: string,
+      value: Uint8Array | ArrayBuffer | ArrayBufferView | string,
+      options?: { encoding?: string | null },
+    ): Promise<{ path: string }>;
+    appendFile(
+      path: string,
+      value: Uint8Array | ArrayBuffer | ArrayBufferView | string,
+      options?: { encoding?: string | null },
+    ): Promise<{ path: string }>;
+    deleteFile(path: string): Promise<{ path: string }>;
+    mkdir(
+      path: string,
+      options?: { recursive?: boolean },
+    ): Promise<{ path: string }>;
+    readdir(path?: string): Promise<NodeHostFilesystemEntry[]>;
+    stat(path: string): Promise<NodeHostFilesystemStat>;
+    rename(
+      fromPath: string,
+      toPath: string,
+    ): Promise<{ from: string; to: string }>;
+  } | null;
+  network?: Record<string, (...args: any[]) => unknown> | null;
+  ipfs?: Record<string, (...args: any[]) => unknown> | null;
+  walletSign?: Record<string, (...args: any[]) => unknown> | null;
+  protocolHandle?: Record<string, (...args: any[]) => unknown> | null;
+  protocolDial?: Record<string, (...args: any[]) => unknown> | null;
+  capabilityAdapters?: Record<string, Record<string, (...args: any[]) => unknown>>;
 }
 
 export class HostCapabilityError extends Error {
@@ -1468,16 +1528,51 @@ export class BrowserHost {
   crypto: {
     sha256(data: Uint8Array | ArrayBuffer | ArrayBufferView | string): Promise<Uint8Array>;
     sha512(data: Uint8Array | ArrayBuffer | ArrayBufferView | string): Promise<Uint8Array>;
+    hkdf(options: {
+      ikm: Uint8Array | ArrayBuffer | ArrayBufferView | number[];
+      salt: Uint8Array | ArrayBuffer | ArrayBufferView | number[];
+      info?: Uint8Array | ArrayBuffer | ArrayBufferView | number[];
+      length: number;
+    }): Promise<Uint8Array>;
     aesGcmEncrypt(options: {
       key: Uint8Array | ArrayBuffer | ArrayBufferView;
       plaintext: Uint8Array | ArrayBuffer | ArrayBufferView;
       iv?: Uint8Array | ArrayBuffer | ArrayBufferView;
-    }): Promise<{ ciphertext: Uint8Array; iv: Uint8Array | ArrayBuffer | ArrayBufferView }>;
+      aad?: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | null;
+    }): Promise<{
+      ciphertext: Uint8Array;
+      tag: Uint8Array;
+      iv: Uint8Array | ArrayBuffer | ArrayBufferView;
+    }>;
     aesGcmDecrypt(options: {
       key: Uint8Array | ArrayBuffer | ArrayBufferView;
       ciphertext: Uint8Array | ArrayBuffer | ArrayBufferView;
+      tag: Uint8Array | ArrayBuffer | ArrayBufferView;
       iv: Uint8Array | ArrayBuffer | ArrayBufferView;
+      aad?: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | null;
     }): Promise<Uint8Array>;
+    generateX25519Keypair(): Promise<X25519Keypair>;
+    x25519PublicKey(
+      privateKey: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+    ): Promise<Uint8Array>;
+    x25519SharedSecret(
+      privateKey: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+      publicKey: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+    ): Promise<Uint8Array>;
+    ed25519: {
+      publicKeyFromSeed(
+        seed: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+      ): Promise<Uint8Array>;
+      sign(
+        message: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+        seed: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+      ): Promise<Uint8Array>;
+      verify(
+        message: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+        signature: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+        publicKey: Uint8Array | ArrayBuffer | ArrayBufferView | number[],
+      ): Promise<boolean>;
+    };
   };
   filesystem: BrowserFilesystemShim;
   constructor(options?: BrowserHostOptions);
@@ -1576,6 +1671,7 @@ export interface BrowserModuleHarness {
   host: BrowserHost;
   bridge: HostcallBridge | null;
   wasi: BrowserWasiShim;
+  callHost(operation: string, params?: Record<string, any>): Promise<unknown>;
   invokeRaw(
     requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView,
   ): Promise<Uint8Array>;
@@ -1594,7 +1690,7 @@ export interface BrowserModuleHarness {
 export function detectArtifactProfile(wasmModule: WebAssembly.Module): string;
 export function createBrowserModuleHarness(options?: {
   wasmSource: Uint8Array | ArrayBuffer | string | WebAssembly.Module | unknown;
-  host?: BrowserHost;
+  host?: BrowserHost | RuntimeHost | Record<string, unknown>;
   hostOptions?: BrowserHostOptions;
   args?: string[];
   env?: Record<string, string>;
@@ -1665,7 +1761,7 @@ export function createModuleFlatBufferStreamPump(options: {
 }): ModuleFlatBufferStreamPump;
 export function loadModule(options?: {
   wasmSource: Uint8Array | ArrayBuffer | string | WebAssembly.Module | unknown;
-  host?: BrowserHost;
+  host?: BrowserHost | RuntimeHost | Record<string, unknown>;
   hostOptions?: BrowserHostOptions;
   args?: string[];
   env?: Record<string, string | undefined>;

package/src/runtime-host/index.js

@@ -3,15 +3,105 @@ import { createFlatBufferStreamIngestor } from "./flatbufferStreamIngestor.js";
 import { createRuntimeRegionStore } from "./runtimeRegionStore.js";
 import { createModuleRegistry } from "./moduleRegistry.js";
 
+function normalizeCapabilityId(capability) {
+  const normalized = String(capability ?? "").trim();
+  if (!normalized) {
+    throw new TypeError("Capability id is required.");
+  }
+  return normalized;
+}
+
+function createCapabilityRegistry(capabilities = {}) {
+  const entries =
+    capabilities instanceof Map
+      ? capabilities.entries()
+      : Object.entries(capabilities ?? {});
+  const registry = new Map();
+  for (const [capability, adapter] of entries) {
+    registry.set(normalizeCapabilityId(capability), adapter);
+  }
+  return registry;
+}
+
+function listCapabilityOperations(capabilities) {
+  const operations = new Set();
+  for (const [capabilityId, adapter] of capabilities.entries()) {
+    if (!adapter || typeof adapter !== "object") {
+      continue;
+    }
+    const methodIds = Object.keys(adapter).filter(
+      (methodId) => typeof adapter[methodId] === "function" && methodId !== "invoke",
+    );
+    if (methodIds.length > 0) {
+      for (const methodId of methodIds) {
+        operations.add(`${capabilityId}.${methodId}`);
+      }
+      continue;
+    }
+    if (typeof adapter.invoke === "function") {
+      operations.add(`${capabilityId}.invoke`);
+    }
+  }
+  return Array.from(operations).sort();
+}
+
 export function createRuntimeHost(options = {}) {
   const rows = options.rows ?? createFlatSqlRuntimeStore();
   const regions = options.regions ?? createRuntimeRegionStore();
   const moduleRegistry = options.moduleRegistry ?? createModuleRegistry();
+  const capabilities = createCapabilityRegistry(options.capabilities);
 
   return {
     rows,
     regions,
     moduleRegistry,
+    listCapabilities() {
+      return Array.from(capabilities.keys()).sort();
+    },
+    listSupportedCapabilities() {
+      return Array.from(capabilities.keys()).sort();
+    },
+    listOperations() {
+      return listCapabilityOperations(capabilities);
+    },
+    hasCapability(capability) {
+      return capabilities.has(normalizeCapabilityId(capability));
+    },
+    getCapability(capability) {
+      return capabilities.get(normalizeCapabilityId(capability)) ?? null;
+    },
+    registerCapability(capability, adapter) {
+      const normalized = normalizeCapabilityId(capability);
+      capabilities.set(normalized, adapter);
+      return adapter;
+    },
+    unregisterCapability(capability) {
+      return capabilities.delete(normalizeCapabilityId(capability));
+    },
+    async invokeCapability(operation, params = {}) {
+      const normalized = normalizeCapabilityId(operation);
+      const separator = normalized.indexOf(".");
+      const capabilityId =
+        separator >= 0 ? normalized.slice(0, separator) : normalized;
+      const methodId =
+        separator >= 0 ? normalized.slice(separator + 1) : "invoke";
+      const adapter = capabilities.get(capabilityId);
+      if (!adapter || typeof adapter !== "object") {
+        throw new Error(`Runtime host capability "${capabilityId}" is not registered.`);
+      }
+      if (typeof adapter[methodId] === "function") {
+        return adapter[methodId](params);
+      }
+      if (typeof adapter.invoke === "function") {
+        return adapter.invoke(methodId, params);
+      }
+      throw new Error(
+        `Runtime host capability "${capabilityId}" does not implement "${methodId}" or invoke().`,
+      );
+    },
+    async invoke(operation, params = {}) {
+      return this.invokeCapability(operation, params);
+    },
   };
 }
 

package/src/testing/browserModuleHarness.js

@@ -14,9 +14,11 @@
 
 import { createBrowserWasiShim, WasiExitError } from "../host/wasiShim.js";
 import { createBrowserHost } from "../host/browserHost.js";
+import { getWasmWallet } from "../utils/wasmCrypto.js";
 import {
   createJsonHostcallBridge,
-  createNodeHostSyncDispatcher,
+  createAsyncHostDispatcher,
+  createHostSyncDispatcher,
   DEFAULT_HOSTCALL_IMPORT_MODULE,
 } from "../host/abi.js";
 import {
@@ -90,7 +92,7 @@ async function instantiateBrowserModule(options = {}) {
   let instance = null;
   let bridge = null;
   if (needsHostBridge) {
-    const dispatch = createNodeHostSyncDispatcher(options.host);
+    const dispatch = createHostSyncDispatcher(options.host);
     bridge = createJsonHostcallBridge({
       dispatch,
       getMemory: () => instance.exports.memory,
@@ -125,8 +127,20 @@ async function instantiateBrowserModule(options = {}) {
  * @param {string} [options.surface] - "direct" or "command" (default: auto-detect).
  */
 export async function createBrowserModuleHarness(options = {}) {
-  const host = options.host ?? createBrowserHost(options.hostOptions);
   const wasmModule = await compileWasmModule(options.wasmSource);
+  const moduleImports = WebAssembly.Module.imports(wasmModule);
+  const needsHostBridge = moduleImports.some(
+    (entry) => entry.module === DEFAULT_HOSTCALL_IMPORT_MODULE,
+  );
+  const hostOptions =
+    !options.host && needsHostBridge && !options.hostOptions?.wasmWallet
+      ? {
+          ...options.hostOptions,
+          wasmWallet: await getWasmWallet(),
+        }
+      : options.hostOptions;
+  const host = options.host ?? createBrowserHost(hostOptions);
+  const dispatchHost = createAsyncHostDispatcher(host);
 
   const profile = detectArtifactProfile(wasmModule);
   const moduleExports = WebAssembly.Module.exports(wasmModule);
@@ -238,6 +252,10 @@ export async function createBrowserModuleHarness(options = {}) {
     return decodePluginInvokeResponse(responseBytes);
   }
 
+  async function callHost(operation, params = {}) {
+    return dispatchHost(operation, params);
+  }
+
   function readManifest() {
     const getBytesExport =
       instance.exports[DefaultManifestExports.pluginBytesSymbol];
@@ -267,6 +285,7 @@ export async function createBrowserModuleHarness(options = {}) {
     host,
     bridge,
     wasi,
+    callHost,
     invoke,
     invokeRaw,
     readManifest,

package/src/testing/index.d.ts

@@ -335,6 +335,7 @@ export interface BrowserModuleHarness {
     stdout: Uint8Array;
     stderr: Uint8Array;
   };
+  callHost(operation: string, params?: Record<string, any>): Promise<unknown>;
   invokeRaw(
     requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView,
   ): Promise<Uint8Array>;

package/src/testing/index.js

@@ -98,6 +98,7 @@ const CapabilitySurfaceMatrix = Object.freeze({
     notes: [
       "WASI preopens are the preferred cross-runtime filesystem surface.",
       "The sync hostcall ABI currently exposes filesystem.resolvePath only.",
+      "Awaited filesystem reads and writes live on the generic async host boundary shared by NodeHost, BrowserHost, runtime-host capability registries, and harness callHost dispatch.",
     ],
   }),
   pipe: Object.freeze({
@@ -120,7 +121,8 @@ const CapabilitySurfaceMatrix = Object.freeze({
     syncHostcall: false,
     nodeHostApi: true,
     notes: [
-      "The coarse network capability maps to host-side HTTP/TCP/UDP/TLS/WebSocket services today.",
+      "The coarse network capability maps to async host-side HTTP/TCP/UDP/TLS/WebSocket services.",
+      "Browser and Node harnesses can await the same capability surface through BrowserHost.invoke(), loadModule(...).callHost(...), and createBrowserModuleHarness(...).callHost(...).",
       "Pure WASI guests cannot reach that surface through the current sync hostcall ABI.",
       "WasmEdge provides non-blocking socket-oriented extensions that can serve as the standard server-side max-WASI target.",
     ],
@@ -198,6 +200,42 @@ const CapabilitySurfaceMatrix = Object.freeze({
       "WasmEdge TLS support provides a practical no-wrapper server-side target for guest HTTPS/TLS logic.",
     ],
   }),
+  ipfs: Object.freeze({
+    capability: "ipfs",
+    wasi: false,
+    standaloneWasi: false,
+    wasmedge: false,
+    syncHostcall: false,
+    nodeHostApi: true,
+    notes: [
+      "IPFS access is available through the generic async host boundary and browser/module harness dispatch.",
+      "Pure WASM guests cannot reach that surface through the current sync hostcall ABI.",
+    ],
+  }),
+  protocol_handle: Object.freeze({
+    capability: "protocol_handle",
+    wasi: false,
+    standaloneWasi: false,
+    wasmedge: false,
+    syncHostcall: false,
+    nodeHostApi: true,
+    notes: [
+      "Protocol registration is available through the generic async host boundary and browser/module harness dispatch.",
+      "Pure WASM guests cannot reach that surface through the current sync hostcall ABI.",
+    ],
+  }),
+  protocol_dial: Object.freeze({
+    capability: "protocol_dial",
+    wasi: false,
+    standaloneWasi: false,
+    wasmedge: false,
+    syncHostcall: false,
+    nodeHostApi: true,
+    notes: [
+      "Protocol dialing is available through the generic async host boundary and browser/module harness dispatch.",
+      "Pure WASM guests cannot reach that surface through the current sync hostcall ABI.",
+    ],
+  }),
   context_read: Object.freeze({
     capability: "context_read",
     wasi: false,