space-data-module-sdk 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# Space Data Module SDK
+
+A unified SDK for building, validating, signing, and deploying **WebAssembly plugin modules** that run anywhere on the [Space Data Network](https://digitalarsenal.github.io/space-data-network/) — from [OrbPro](https://orbpro.ai) desktops to SDN peer nodes, ground stations, and browsers.
+
+The space domain has a fragmentation problem: every platform ships its own plugin format, its own manifest schema, its own packaging conventions. A propagator written for one system can't run on another without a rewrite. This SDK solves that by defining a **single canonical module format** — a WebAssembly binary with an embedded [FlatBuffers](https://digitalarsenal.github.io/flatbuffers/) manifest — that every runtime in the ecosystem understands.
+
+Modules declare **typed streaming ports** that accept data conforming to [spacedatastandards.org](https://spacedatastandards.org) schemas (OMM, CAT, EPM, CDM, and 40+ others). A propagator that consumes OMM messages and emits state vectors works identically whether it's running inside OrbPro's 3D scene, processing data on an SDN relay node, or executing at the edge on a ground station.
+
+<p align="center">
+  <img src="docs/architecture.svg" alt="Architecture overview" width="820" />
+</p>
+
+## How It Works
+
+The SDK handles the full module lifecycle — from source code to a signed, encrypted, deployment-ready package:
+
+<p align="center">
+  <img src="docs/module-lifecycle.svg" alt="Module lifecycle" width="820" />
+</p>
+
+1. **Author** a JSON manifest declaring your module's identity, methods, typed I/O ports, host capabilities, and the [spacedatastandards.org](https://spacedatastandards.org) schemas it consumes and produces.
+2. **Compile** your C/C++ source (via Emscripten) into a `.wasm` binary with the manifest automatically embedded as a FlatBuffers blob that runtimes can read at load time.
+3. **Validate** the manifest and artifact against compliance rules — correct port declarations, canonical capability IDs, required WASM ABI exports (`plugin_get_manifest_flatbuffer`, `plugin_get_manifest_flatbuffer_size`), and schema resolution against the standards catalog.
+4. **Sign** the package with an HD-wallet-derived secp256k1 key, producing a deployment authorization that binds the manifest hash, WASM hash, target, and granted capabilities.
+5. **Protect** the signed package by encrypting it for a specific recipient using X25519 key agreement + AES-256-GCM, so modules can be transported securely across the network.
+
+## Manifest & Typed Ports
+
+Every module carries a manifest that declares **what data it can process**. Methods expose typed input and output ports, and each port declares the FlatBuffer schemas it accepts — referencing standards by schema name and file identifier:
+
+<p align="center">
+  <img src="docs/manifest-structure.svg" alt="Manifest structure" width="820" />
+</p>
+
+This means runtimes can **automatically wire modules together** — connecting a propagator's `CAT` output to a conjunction screener's `CAT` input — without any glue code. The type system ensures only compatible modules get connected.
+
+## Ecosystem
+
+This SDK is one piece of the Space Data Network stack:
+
+| Project | Role |
+|---|---|
+| [Space Data Network](https://digitalarsenal.github.io/space-data-network/) | Peer-to-peer network for space data exchange |
+| [spacedatastandards.org](https://spacedatastandards.org) | 40+ canonical FlatBuffer schemas for space operations data (OMM, EPM, CAT, CDM, etc.) |
+| [FlatBuffers schemas](https://digitalarsenal.github.io/flatbuffers/) | Binary serialization layer used across the entire network |
+| [OrbPro](https://orbpro.ai) | Space domain awareness platform — one of the runtimes that hosts these modules |
+| [hd-wallet-wasm](https://github.com/nicktj-dev/hd-wallet-wasm) | HD wallet primitives for module signing and identity |
+
+## Install
+
+```bash
+npm install space-data-module-sdk
+```
+
+## Quick Start
+
+```js
+import {
+  encodeManifest, decodeManifest,   // FlatBuffers manifest codec
+  checkCompliance,                   // validate against standards
+  signManifest, verifyManifest,      // HD wallet auth
+  encryptPayload, decryptPayload,    // X25519 + AES-256-GCM transport
+  compileModule,                     // source-to-wasm compilation
+} from "space-data-module-sdk";
+```
+
+### Subpath Exports
+
+Each subsystem is available as a standalone import:
+
+```js
+import { encodeManifest } from "space-data-module-sdk/manifest";
+import { checkCompliance } from "space-data-module-sdk/compliance";
+import { signManifest }    from "space-data-module-sdk/auth";
+import { encryptPayload }  from "space-data-module-sdk/transport";
+import { compileModule }   from "space-data-module-sdk/compiler";
+import { resolveStandard } from "space-data-module-sdk/standards";
+```
+
+## CLI
+
+Every SDK operation is also available from the command line:
+
+```bash
+# Validate a manifest + wasm pair against compliance rules
+npx space-data-module check --manifest ./manifest.json --wasm ./dist/module.wasm
+
+# Compile C/C++ source to a wasm module with embedded manifest
+npx space-data-module compile --manifest ./manifest.json --source ./src/module.c --out ./dist/module.wasm
+
+# Sign and encrypt a module package for transport
+npx space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --json
+```
+
+## Module Lab
+
+An interactive browser tool for compiling, validating, and packaging modules — useful for exploring the manifest format and testing modules without touching the CLI.
+
+```bash
+npm run start:lab
+# http://localhost:4318
+```
+
+## Plugin Families
+
+Modules declare a `pluginFamily` that tells runtimes what role they serve:
+
+| Family | Purpose |
+|---|---|
+| `sensor` | Ingest raw data feeds (radar, optical, RF) |
+| `propagator` | Orbit propagation and state prediction |
+| `renderer` | 3D visualization and scene rendering |
+| `analysis` | Data processing, filtering, aggregation |
+| `data_source` | External data connectors |
+| `comms` | Communications link modeling |
+| `shader` | GPU shader programs |
+| `sdf` | Signed distance field geometry |
+| `infrastructure` | Network and platform services |
+| `flow` | Multi-module data flow orchestration |
+| `bridge` | Cross-runtime adapters |
+
+## Host Capabilities
+
+Modules request host capabilities by name. The runtime grants or denies them at load time based on the deployment authorization:
+
+`clock` `random` `timers` `http` `network` `filesystem` `pipe` `pubsub` `protocol_handle` `protocol_dial` `database` `storage_adapter` `storage_query` `storage_write` `wallet_sign` `ipfs` `scene_access` `render_hooks`
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+Requires Node.js >= 20. Compilation requires [Emscripten](https://emscripten.org/) (`emcc`/`em++`) on `PATH`.
+
+## License
+
+See [LICENSE](LICENSE).

package/bin/space-data-module.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import process from "node:process";
+import { readFile, writeFile } from "node:fs/promises";
+
+import {
+  compileModuleFromSource,
+  loadComplianceConfig,
+  protectModuleArtifact,
+  resolveManifestFiles,
+  validateArtifactWithStandards,
+  validateManifestWithStandards,
+  loadManifestFromFile,
+} from "../src/index.js";
+import { bytesToBase64 } from "../src/utils/encoding.js";
+
+async function main(argv) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "check":
+      return runCheck(rest);
+    case "compile":
+      return runCompile(rest);
+    case "protect":
+      return runProtect(rest);
+    default:
+      printUsage();
+      return command ? 1 : 0;
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    json: false,
+    repoRoot: process.cwd(),
+    manifestPath: null,
+    wasmPath: null,
+    sourcePath: null,
+    language: "c",
+    outputPath: null,
+    recipientPublicKeyHex: null,
+    mnemonic: null,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    switch (value) {
+      case "--json":
+        options.json = true;
+        break;
+      case "--repo-root":
+        options.repoRoot = path.resolve(requireValue(argv, ++index, value));
+        break;
+      case "--manifest":
+        options.manifestPath = path.resolve(requireValue(argv, ++index, value));
+        break;
+      case "--wasm":
+        options.wasmPath = path.resolve(requireValue(argv, ++index, value));
+        break;
+      case "--source":
+        options.sourcePath = path.resolve(requireValue(argv, ++index, value));
+        break;
+      case "--language":
+        options.language = requireValue(argv, ++index, value);
+        break;
+      case "--out":
+        options.outputPath = path.resolve(requireValue(argv, ++index, value));
+        break;
+      case "--recipient-public-key":
+        options.recipientPublicKeyHex = requireValue(argv, ++index, value);
+        break;
+      case "--mnemonic":
+        options.mnemonic = requireValue(argv, ++index, value);
+        break;
+      default:
+        throw new Error(`Unknown argument: ${value}`);
+    }
+  }
+
+  return options;
+}
+
+function requireValue(argv, index, flagName) {
+  const value = argv[index];
+  if (!value) {
+    throw new Error(`${flagName} requires a value.`);
+  }
+  return value;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  space-data-module check --repo-root .
+  space-data-module check --manifest ./manifest.json --wasm ./dist/module.wasm
+  space-data-module compile --manifest ./manifest.json --source ./src/module.c --out ./dist/module.wasm
+  space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --json
+`);
+}
+
+function printReport(report) {
+  console.log(`${report.ok ? "PASS" : "FAIL"} ${report.sourceName}`);
+  for (const issue of report.issues) {
+    console.log(
+      `  ${issue.severity.toUpperCase()} ${issue.code}: ${issue.message}`,
+    );
+  }
+  if (report.issues.length === 0) {
+    console.log("  No issues found.");
+  }
+}
+
+async function runCheck(argv) {
+  const options = parseArgs(argv);
+  if (options.manifestPath) {
+    const manifest = await loadManifestFromFile(options.manifestPath);
+    const report = options.wasmPath
+      ? await validateArtifactWithStandards({
+          manifest,
+          manifestPath: options.manifestPath,
+          wasmPath: options.wasmPath,
+        })
+      : await validateManifestWithStandards(manifest, {
+          sourceName: options.manifestPath,
+        });
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      printReport(report);
+    }
+    return report.ok ? 0 : 1;
+  }
+
+  const manifestPaths = await resolveManifestFiles(options.repoRoot);
+  if (manifestPaths.length === 0) {
+    const loadedConfig = await loadComplianceConfig(options.repoRoot);
+    if (loadedConfig?.config?.allowEmpty === true) {
+      if (!options.json) {
+        console.log(
+          `No manifests configured under ${options.repoRoot}; allowEmpty=true so the check passes.`,
+        );
+      }
+      return 0;
+    }
+    console.error(`No manifest.json files found under ${options.repoRoot}`);
+    return 1;
+  }
+  const reports = [];
+  for (const manifestPath of manifestPaths) {
+    const manifest = await loadManifestFromFile(manifestPath);
+    reports.push(
+      await validateManifestWithStandards(manifest, { sourceName: manifestPath }),
+    );
+  }
+  if (options.json) {
+    console.log(JSON.stringify(reports, null, 2));
+  } else {
+    reports.forEach(printReport);
+  }
+  return reports.every((report) => report.ok) ? 0 : 1;
+}
+
+async function runCompile(argv) {
+  const options = parseArgs(argv);
+  if (!options.manifestPath || !options.sourcePath || !options.outputPath) {
+    throw new Error("compile requires --manifest, --source, and --out.");
+  }
+  const manifest = await loadManifestFromFile(options.manifestPath);
+  const sourceCode = await readFile(options.sourcePath, "utf8");
+  const result = await compileModuleFromSource({
+    manifest,
+    sourceCode,
+    language: options.language,
+    outputPath: options.outputPath,
+  });
+  await writeFile(options.outputPath, result.wasmBytes);
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          outputPath: options.outputPath,
+          manifestWarnings: result.manifestWarnings,
+          report: result.report,
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log(`Wrote ${options.outputPath}`);
+    result.manifestWarnings.forEach((warning) =>
+      console.log(`  WARNING ${warning}`),
+    );
+    printReport(result.report);
+  }
+  return result.report.ok ? 0 : 1;
+}
+
+async function runProtect(argv) {
+  const options = parseArgs(argv);
+  if (!options.manifestPath || !options.wasmPath) {
+    throw new Error("protect requires --manifest and --wasm.");
+  }
+  const manifest = await loadManifestFromFile(options.manifestPath);
+  const wasmBytes = new Uint8Array(await readFile(options.wasmPath));
+  const result = await protectModuleArtifact({
+    manifest,
+    wasmBytes,
+    recipientPublicKeyHex: options.recipientPublicKeyHex,
+    mnemonic: options.mnemonic,
+  });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`artifactId=${result.payload.artifactId}`);
+    console.log(`signingPublicKeyHex=${result.signingPublicKeyHex}`);
+    console.log(`encrypted=${result.encrypted}`);
+    console.log(`wasmBase64Length=${bytesToBase64(wasmBytes).length}`);
+  }
+  return 0;
+}
+
+main(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exitCode = exitCode;
+  })
+  .catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "space-data-module-sdk",
+  "version": "0.1.0",
+  "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
+  "type": "module",
+  "bin": {
+    "space-data-module": "./bin/space-data-module.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./manifest": "./src/manifest/index.js",
+    "./compliance": "./src/compliance/index.js",
+    "./auth": "./src/auth/index.js",
+    "./transport": "./src/transport/index.js",
+    "./compiler": "./src/compiler/index.js",
+    "./standards": "./src/standards/index.js",
+    "./schemas/*": "./schemas/*"
+  },
+  "files": [
+    "bin/",
+    "schemas/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start:lab": "node ./lab/server.js",
+    "check:compliance": "node ./bin/space-data-module.js check --repo-root ."
+  },
+  "dependencies": {
+    "flatbuffers": "^25.9.23",
+    "hd-wallet-wasm": "^1.5.4",
+    "spacedatastandards.org": "23.3.3-0.3.4"
+  },
+  "devDependencies": {
+    "express": "^4.21.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/schemas/PluginManifest.fbs

@@ -0,0 +1,144 @@
+// OrbPro Plugin SDK - Plugin Manifest Schema
+//
+// Canonical manifest for unified OrbPro + SDN plugins.
+
+include "TypedArenaBuffer.fbs";
+
+namespace orbpro.manifest;
+
+/// Canonical plugin family.
+enum PluginFamily : ubyte {
+  SENSOR = 0,
+  PROPAGATOR = 1,
+  RENDERER = 2,
+  ANALYSIS = 3,
+  DATA_SOURCE = 4,
+  COMMS = 5,
+  SHADER = 6,
+  SDF = 7,
+  INFRASTRUCTURE = 8,
+  FLOW = 9,
+  BRIDGE = 10
+}
+
+/// Host capability requested by a plugin.
+enum CapabilityKind : ushort {
+  CLOCK = 0,
+  RANDOM = 1,
+  LOGGING = 2,
+  TIMERS = 3,
+  PUBSUB = 4,
+  PROTOCOL_DIAL = 5,
+  PROTOCOL_HANDLE = 6,
+  STORAGE_QUERY = 7,
+  SCENE_ACCESS = 8,
+  ENTITY_ACCESS = 9,
+  RENDER_HOOKS = 10
+}
+
+/// Drain policy for methods that operate over queued stream frames.
+enum DrainPolicy : ubyte {
+  SINGLE_SHOT = 0,
+  DRAIN_UNTIL_YIELD = 1,
+  DRAIN_TO_EMPTY = 2
+}
+
+/// Accepted schema family for a port.
+table AcceptedTypeSet {
+  /// Stable type-set identifier.
+  set_id: string (required);
+
+  /// Specific FlatBuffer types accepted by the set.
+  allowed_types: [orbpro.stream.FlatBufferTypeRef];
+
+  /// Human-readable explanation of the accepted schema family.
+  description: string;
+}
+
+/// One input or output port on a method.
+table PortManifest {
+  /// Stable port identifier within the method.
+  port_id: string (required);
+
+  /// Human-readable name for UIs.
+  display_name: string;
+
+  /// Type sets accepted on this port.
+  accepted_type_sets: [AcceptedTypeSet];
+
+  /// Minimum number of streams that must be connected.
+  min_streams: uint16 = 1;
+
+  /// Maximum number of streams that may be connected.
+  max_streams: uint16 = 1;
+
+  /// Whether the port must be connected for invocation.
+  required: bool = true;
+
+  /// Optional human-readable description.
+  description: string;
+}
+
+/// One host capability dependency.
+table HostCapability {
+  capability: CapabilityKind;
+  scope: string;
+  required: bool = true;
+  description: string;
+}
+
+/// Timer entry declared by a plugin.
+table TimerSpec {
+  timer_id: string (required);
+  method_id: string (required);
+  input_port_id: string;
+  default_interval_ms: uint64;
+  description: string;
+}
+
+/// Protocol handler declared by a plugin.
+table ProtocolSpec {
+  protocol_id: string (required);
+  method_id: string (required);
+  input_port_id: string;
+  output_port_id: string;
+  description: string;
+}
+
+/// Build artifact emitted by the plugin toolchain.
+table BuildArtifact {
+  artifact_id: string (required);
+  kind: string;
+  path: string (required);
+  target: string;
+  entry_symbol: string;
+}
+
+/// Canonical method declaration.
+table MethodManifest {
+  method_id: string (required);
+  display_name: string;
+  input_ports: [PortManifest];
+  output_ports: [PortManifest];
+  max_batch: uint32 = 1;
+  drain_policy: DrainPolicy = DRAIN_UNTIL_YIELD;
+  description: string;
+}
+
+/// Canonical plugin manifest.
+table PluginManifest {
+  plugin_id: string (required, key);
+  name: string;
+  version: string;
+  plugin_family: PluginFamily = ANALYSIS;
+  methods: [MethodManifest];
+  capabilities: [HostCapability];
+  timers: [TimerSpec];
+  protocols: [ProtocolSpec];
+  schemas_used: [orbpro.stream.FlatBufferTypeRef];
+  build_artifacts: [BuildArtifact];
+  abi_version: uint32 = 1;
+}
+
+root_type PluginManifest;
+file_identifier "PMAN";

package/schemas/TypedArenaBuffer.fbs

@@ -0,0 +1,78 @@
+// OrbPro Plugin SDK - Typed Arena Buffer Schema
+//
+// Canonical descriptor for schema-tagged FlatBuffer frames moving through
+// arena-backed plugin streams.
+
+namespace orbpro.stream;
+
+/// FlatBuffer schema identity for a stream frame or accepted port type.
+table FlatBufferTypeRef {
+  /// Logical schema name, for example `OMM.fbs`.
+  schema_name: string;
+
+  /// Optional 4-byte FlatBuffer file identifier.
+  file_identifier: string;
+
+  /// Optional schema hash bytes for stronger compatibility checks.
+  schema_hash: [ubyte];
+
+  /// True when this port/type set accepts any FlatBuffer frame.
+  accepts_any_flatbuffer: bool = false;
+}
+
+/// Ownership mode for an arena-backed frame.
+enum BufferOwnership : ubyte {
+  BORROWED = 0,
+  PRODUCER_OWNED = 1,
+  HOST_OWNED = 2,
+  SHARED = 3
+}
+
+/// Mutability contract for an arena-backed frame.
+enum BufferMutability : ubyte {
+  IMMUTABLE = 0,
+  APPEND_ONLY = 1,
+  MUTABLE = 2
+}
+
+/// Runtime descriptor for one FlatBuffer frame stored in an arena.
+table TypedArenaBuffer {
+  /// Runtime schema identity for this frame.
+  type_ref: FlatBufferTypeRef;
+
+  /// Port that produced or will consume this frame.
+  port_id: string;
+
+  /// Required alignment of the underlying frame bytes.
+  alignment: uint16 = 8;
+
+  /// Frame byte offset from the arena base.
+  offset: uint32;
+
+  /// Frame size in bytes.
+  size: uint32;
+
+  /// Ownership contract for the buffer.
+  ownership: BufferOwnership = BORROWED;
+
+  /// Generation counter for stale-reference detection.
+  generation: uint32;
+
+  /// Mutability contract for downstream consumers.
+  mutability: BufferMutability = IMMUTABLE;
+
+  /// Flow/runtime trace identifier.
+  trace_id: uint64;
+
+  /// Logical stream identifier.
+  stream_id: uint32;
+
+  /// Monotonic frame sequence number within a stream.
+  sequence: uint64;
+
+  /// True if this frame closes the stream.
+  end_of_stream: bool = false;
+}
+
+root_type TypedArenaBuffer;
+file_identifier "TABF";

package/src/auth/canonicalize.js

@@ -0,0 +1,72 @@
+import { bytesToBase64 } from "../utils/encoding.js";
+import { sha256Bytes } from "../utils/crypto.js";
+
+function normalizeCanonicalValue(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (
+    value === null ||
+    typeof value === "boolean" ||
+    typeof value === "string"
+  ) {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("Canonical payloads cannot contain non-finite numbers.");
+    }
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (
+    value instanceof Uint8Array ||
+    value instanceof ArrayBuffer ||
+    ArrayBuffer.isView(value)
+  ) {
+    return {
+      __type: "bytes",
+      base64: bytesToBase64(
+        value instanceof Uint8Array
+          ? value
+          : new Uint8Array(
+              value.buffer ?? value,
+              value.byteOffset ?? 0,
+              value.byteLength ?? value.byteLength,
+            ),
+      ),
+    };
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      const normalized = normalizeCanonicalValue(item);
+      return normalized === undefined ? null : normalized;
+    });
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value)
+      .filter(([, nestedValue]) => nestedValue !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, nestedValue]) => [key, normalizeCanonicalValue(nestedValue)]);
+    return Object.fromEntries(entries);
+  }
+  throw new TypeError(`Unsupported canonical value type: ${typeof value}`);
+}
+
+export function stableStringify(value) {
+  return JSON.stringify(normalizeCanonicalValue(value));
+}
+
+export function canonicalBytes(value) {
+  return new TextEncoder().encode(stableStringify(value));
+}
+
+export async function hashCanonicalValue(value) {
+  return sha256Bytes(canonicalBytes(value));
+}
+