space-data-module-sdk 0.1.0 → 0.2.5

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.1.0",
+  "version": "0.2.5",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DigitalArsenal/space-data-module-sdk.git"
+  },
   "bin": {
     "space-data-module": "./bin/space-data-module.js"
   },
@@ -13,6 +18,8 @@
     "./auth": "./src/auth/index.js",
     "./transport": "./src/transport/index.js",
     "./compiler": "./src/compiler/index.js",
+    "./bundle": "./src/bundle/index.js",
+    "./invoke": "./src/invoke/index.js",
     "./standards": "./src/standards/index.js",
     "./schemas/*": "./schemas/*"
   },
@@ -24,15 +31,20 @@
   "scripts": {
     "test": "node --test",
     "start:lab": "node ./lab/server.js",
-    "check:compliance": "node ./bin/space-data-module.js check --repo-root ."
+    "check:compliance": "node ./bin/space-data-module.js check --repo-root .",
+    "generate:vectors": "node ./examples/single-file-bundle/generate-vectors.mjs",
+    "prepublishOnly": "npm test && npm run check:compliance"
   },
   "dependencies": {
+    "flatc-wasm": "25.12.19-wasm.43",
     "flatbuffers": "^25.9.23",
-    "hd-wallet-wasm": "^1.5.4",
+    "hd-wallet-wasm": "1.6.0",
+    "sdn-emception": "1.0.0",
     "spacedatastandards.org": "23.3.3-0.3.4"
   },
   "devDependencies": {
-    "express": "^4.21.2"
+    "express": "^4.21.2",
+    "flatsql": "^0.4.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/schemas/ModuleBundle.fbs

@@ -0,0 +1,108 @@
+// Space Data Module SDK - Single-file Module Bundle Schema
+//
+// Draft schema for packaging a loadable WebAssembly module together with
+// SDS-typed metadata inside one `sds.bundle` custom section.
+
+include "TypedArenaBuffer.fbs";
+
+namespace orbpro.module;
+
+/// Logical role for one payload carried in the bundle.
+enum ModuleBundleEntryRole : ubyte {
+  MANIFEST = 0,
+  AUTHORIZATION = 1,
+  SIGNATURE = 2,
+  TRANSPORT = 3,
+  ATTESTATION = 4,
+  AUXILIARY = 5
+}
+
+/// Serialization format used by an entry payload.
+enum ModulePayloadEncoding : ubyte {
+  RAW_BYTES = 0,
+  FLATBUFFER = 1,
+  JSON_UTF8 = 2,
+  CBOR = 3
+}
+
+/// Canonicalization rule applied before hashing or signature verification.
+table CanonicalizationRule {
+  /// Schema version for the canonicalization contract.
+  version: uint16 = 1;
+
+  /// Strip any custom section whose name starts with this prefix before
+  /// hashing the module for signature verification.
+  stripped_custom_section_prefix: string;
+
+  /// Name of the required root custom section carrying this bundle.
+  bundle_section_name: string;
+
+  /// Hash function identifier, for example `sha256`.
+  hash_algorithm: string;
+}
+
+/// One payload carried inside the bundle.
+table ModuleBundleEntry {
+  /// Stable bundle-local identifier.
+  entry_id: string (required, key);
+
+  /// High-level semantic role of the payload.
+  role: ModuleBundleEntryRole = AUXILIARY;
+
+  /// Optional logical section name within the bundle, for example
+  /// `sds.authorization`.
+  section_name: string;
+
+  /// SDS/shared-module schema identity when the payload is itself a
+  /// FlatBuffer.
+  type_ref: orbpro.stream.FlatBufferTypeRef;
+
+  /// Encoding used for `payload`.
+  payload_encoding: ModulePayloadEncoding = RAW_BYTES;
+
+  /// Optional media type for transitional payloads such as JSON envelopes.
+  media_type: string;
+
+  /// Implementation-defined bit flags for signed/encrypted/compressed state.
+  flags: uint32 = 0;
+
+  /// SHA-256 of the payload bytes.
+  sha256: [ubyte];
+
+  /// Embedded payload bytes. For single-file deployment this should be
+  /// populated for every entry.
+  payload: [ubyte];
+
+  /// Human-readable description for tooling and diagnostics.
+  description: string;
+}
+
+/// Metadata stored in the required `sds.bundle` custom section.
+table ModuleBundle {
+  /// Bundle schema version.
+  bundle_version: uint16 = 1;
+
+  /// Human-readable package format label.
+  module_format: string;
+
+  /// Canonicalization rule used to compute module hashes.
+  canonicalization: CanonicalizationRule;
+
+  /// SHA-256 of the wasm module after stripping `sds.*` custom sections.
+  canonical_module_hash: [ubyte];
+
+  /// SHA-256 of the canonical plugin manifest bytes.
+  manifest_hash: [ubyte];
+
+  /// Legacy ABI export retained for backward compatibility.
+  manifest_export_symbol: string;
+
+  /// Legacy ABI export retained for backward compatibility.
+  manifest_size_symbol: string;
+
+  /// Payloads embedded in the bundle.
+  entries: [ModuleBundleEntry];
+}
+
+root_type ModuleBundle;
+file_identifier "SMDB";

package/schemas/PluginInvokeRequest.fbs

@@ -0,0 +1,18 @@
+include "TypedArenaBuffer.fbs";
+
+namespace orbpro.invoke;
+
+/// Canonical invoke envelope consumed by direct ABI and command-mode execution.
+table PluginInvokeRequest {
+  /// Stable method identifier from PluginManifest.methods.
+  method_id: string (required);
+
+  /// Input frames for the invocation, routed by TypedArenaBuffer.port_id.
+  input_frames: [orbpro.stream.TypedArenaBuffer];
+
+  /// Arena backing all input frame payload bytes.
+  payload_arena: [ubyte];
+}
+
+root_type PluginInvokeRequest;
+file_identifier "PINQ";

package/schemas/PluginInvokeResponse.fbs

@@ -0,0 +1,30 @@
+include "TypedArenaBuffer.fbs";
+
+namespace orbpro.invoke;
+
+/// Canonical invoke result emitted by direct ABI and command-mode execution.
+table PluginInvokeResponse {
+  /// Method-specific status code. Zero conventionally indicates success.
+  status_code: int = 0;
+
+  /// True when the method yielded before fully draining queued work.
+  yielded: bool = false;
+
+  /// Remaining backlog, if known.
+  backlog_remaining: uint32 = 0;
+
+  /// Output frames produced by the invocation, routed by port_id.
+  output_frames: [orbpro.stream.TypedArenaBuffer];
+
+  /// Arena backing all output frame payload bytes.
+  payload_arena: [ubyte];
+
+  /// Stable machine-readable error code when invocation fails.
+  error_code: string;
+
+  /// Human-readable error message when invocation fails.
+  error_message: string;
+}
+
+root_type PluginInvokeResponse;
+file_identifier "PINS";

package/schemas/PluginManifest.fbs

@@ -33,7 +33,32 @@ enum CapabilityKind : ushort {
   STORAGE_QUERY = 7,
   SCENE_ACCESS = 8,
   ENTITY_ACCESS = 9,
-  RENDER_HOOKS = 10
+  RENDER_HOOKS = 10,
+  HTTP = 11,
+  FILESYSTEM = 12,
+  PIPE = 13,
+  NETWORK = 14,
+  DATABASE = 15,
+  STORAGE_ADAPTER = 16,
+  STORAGE_WRITE = 17,
+  WALLET_SIGN = 18,
+  IPFS = 19,
+  TLS = 20,
+  MQTT = 21,
+  WEBSOCKET = 22,
+  TCP = 23,
+  UDP = 24,
+  PROCESS_EXEC = 25,
+  CONTEXT_READ = 26,
+  CONTEXT_WRITE = 27,
+  CRYPTO_HASH = 28,
+  CRYPTO_SIGN = 29,
+  CRYPTO_VERIFY = 30,
+  CRYPTO_ENCRYPT = 31,
+  CRYPTO_DECRYPT = 32,
+  CRYPTO_KEY_AGREEMENT = 33,
+  CRYPTO_KDF = 34,
+  SCHEDULE_CRON = 35
 }
 
 /// Drain policy for methods that operate over queued stream frames.
@@ -43,6 +68,12 @@ enum DrainPolicy : ubyte {
   DRAIN_TO_EMPTY = 2
 }
 
+/// Canonical module invocation surfaces supported by an artifact.
+enum InvokeSurface : ubyte {
+  DIRECT = 0,
+  COMMAND = 1
+}
+
 /// Accepted schema family for a port.
 table AcceptedTypeSet {
   /// Stable type-set identifier.
@@ -138,6 +169,7 @@ table PluginManifest {
   schemas_used: [orbpro.stream.FlatBufferTypeRef];
   build_artifacts: [BuildArtifact];
   abi_version: uint32 = 1;
+  invoke_surfaces: [InvokeSurface];
 }
 
 root_type PluginManifest;

package/schemas/TypedArenaBuffer.fbs

@@ -1,11 +1,17 @@
 // OrbPro Plugin SDK - Typed Arena Buffer Schema
 //
-// Canonical descriptor for schema-tagged FlatBuffer frames moving through
+// Canonical descriptor for schema-tagged payload frames moving through
 // arena-backed plugin streams.
 
 namespace orbpro.stream;
 
-/// FlatBuffer schema identity for a stream frame or accepted port type.
+/// Logical payload wire format for a stream frame or accepted port type.
+enum PayloadWireFormat : ubyte {
+  Flatbuffer = 0,
+  AlignedBinary = 1
+}
+
+/// Payload schema identity for a stream frame or accepted port type.
 table FlatBufferTypeRef {
   /// Logical schema name, for example `OMM.fbs`.
   schema_name: string;
@@ -18,6 +24,21 @@ table FlatBufferTypeRef {
 
   /// True when this port/type set accepts any FlatBuffer frame.
   accepts_any_flatbuffer: bool = false;
+
+  /// Payload wire format. Defaults to regular FlatBuffer framing.
+  wire_format: PayloadWireFormat = Flatbuffer;
+
+  /// Root or layout type name for aligned-binary payloads.
+  root_type_name: string;
+
+  /// Fixed string length for aligned-binary schemas when required.
+  fixed_string_length: uint16 = 0;
+
+  /// Fixed byte length for aligned-binary payloads.
+  byte_length: uint32 = 0;
+
+  /// Required byte alignment for aligned-binary payloads.
+  required_alignment: uint16 = 0;
 }
 
 /// Ownership mode for an arena-backed frame.

package/src/bundle/codec.js

@@ -0,0 +1,268 @@
+import * as flatbuffers from "flatbuffers";
+
+import {
+  CanonicalizationRuleT,
+  ModuleBundle,
+  ModuleBundleEntryRole,
+  ModuleBundleEntryT,
+  ModuleBundleT,
+  ModulePayloadEncoding,
+} from "../generated/orbpro/module.js";
+import { FlatBufferTypeRefT } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
+import { canonicalBytes } from "../auth/canonicalize.js";
+import { toUint8Array as toBufferLikeUint8Array } from "../runtime/bufferLike.js";
+import {
+  DEFAULT_HASH_ALGORITHM,
+  DEFAULT_MANIFEST_EXPORT_SYMBOL,
+  DEFAULT_MANIFEST_SIZE_SYMBOL,
+  DEFAULT_MODULE_FORMAT,
+  SDS_BUNDLE_SECTION_NAME,
+  SDS_CUSTOM_SECTION_PREFIX,
+} from "./constants.js";
+
+const textEncoder = new TextEncoder();
+
+const ROLE_NAME_TO_ENUM = new Map([
+  ["manifest", ModuleBundleEntryRole.MANIFEST],
+  ["authorization", ModuleBundleEntryRole.AUTHORIZATION],
+  ["signature", ModuleBundleEntryRole.SIGNATURE],
+  ["transport", ModuleBundleEntryRole.TRANSPORT],
+  ["attestation", ModuleBundleEntryRole.ATTESTATION],
+  ["auxiliary", ModuleBundleEntryRole.AUXILIARY],
+]);
+
+const ROLE_ENUM_TO_NAME = new Map(
+  Array.from(ROLE_NAME_TO_ENUM, ([name, value]) => [value, name]),
+);
+
+const ENCODING_NAME_TO_ENUM = new Map([
+  ["raw-bytes", ModulePayloadEncoding.RAW_BYTES],
+  ["flatbuffer", ModulePayloadEncoding.FLATBUFFER],
+  ["json-utf8", ModulePayloadEncoding.JSON_UTF8],
+  ["cbor", ModulePayloadEncoding.CBOR],
+]);
+
+const ENCODING_ENUM_TO_NAME = new Map(
+  Array.from(ENCODING_NAME_TO_ENUM, ([name, value]) => [value, name]),
+);
+
+function toByteBuffer(data) {
+  if (data instanceof flatbuffers.ByteBuffer) {
+    return data;
+  }
+  const bytes = toBufferLikeUint8Array(data);
+  if (bytes) {
+    return new flatbuffers.ByteBuffer(bytes);
+  }
+  throw new TypeError(
+    "Expected ByteBuffer, Uint8Array, ArrayBufferView, or ArrayBuffer.",
+  );
+}
+
+function normalizeString(value, fallback = null) {
+  if (value === undefined || value === null) {
+    return fallback;
+  }
+  return String(value);
+}
+
+function normalizePayloadWireFormat(value) {
+  if (value === 1) {
+    return "aligned-binary";
+  }
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  return normalized === "aligned-binary" ? "aligned-binary" : "flatbuffer";
+}
+
+function normalizeUnsignedInteger(value, fallback = 0) {
+  const normalized = Number(value ?? fallback);
+  if (!Number.isFinite(normalized)) {
+    return fallback;
+  }
+  return Math.max(0, Math.trunc(normalized));
+}
+
+function normalizeByteArray(value, { encoding = null } = {}) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.map((byte) => Number(byte) & 0xff);
+  }
+  const bytes = toBufferLikeUint8Array(value);
+  if (bytes) {
+    return Array.from(bytes);
+  }
+  if (typeof value === "string") {
+    return Array.from(textEncoder.encode(value));
+  }
+  if (encoding === ModulePayloadEncoding.JSON_UTF8) {
+    return Array.from(canonicalBytes(value));
+  }
+  throw new TypeError(
+    "Expected payload bytes, ArrayBufferView, ArrayBuffer, string, or JSON value.",
+  );
+}
+
+function normalizeRole(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  const normalized = String(value ?? "auxiliary")
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  return ROLE_NAME_TO_ENUM.get(normalized) ?? ModuleBundleEntryRole.AUXILIARY;
+}
+
+function normalizePayloadEncoding(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  const normalized = String(value ?? "raw-bytes")
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  return (
+    ENCODING_NAME_TO_ENUM.get(normalized) ?? ModulePayloadEncoding.RAW_BYTES
+  );
+}
+
+function normalizeTypeRef(value) {
+  if (!value) {
+    return null;
+  }
+  if (value instanceof FlatBufferTypeRefT) {
+    return value;
+  }
+  return new FlatBufferTypeRefT(
+    normalizeString(value.schemaName),
+    normalizeString(value.fileIdentifier),
+    normalizeByteArray(value.schemaHash),
+    Boolean(value.acceptsAnyFlatbuffer),
+    normalizePayloadWireFormat(value.wireFormat),
+    normalizeString(value.rootTypeName),
+    normalizeUnsignedInteger(value.fixedStringLength),
+    normalizeUnsignedInteger(value.byteLength),
+    normalizeUnsignedInteger(value.requiredAlignment),
+  );
+}
+
+function normalizeCanonicalization(value = {}) {
+  if (value instanceof CanonicalizationRuleT) {
+    return value;
+  }
+  return new CanonicalizationRuleT(
+    Number(value.version ?? 1),
+    normalizeString(
+      value.strippedCustomSectionPrefix,
+      SDS_CUSTOM_SECTION_PREFIX,
+    ),
+    normalizeString(value.bundleSectionName, SDS_BUNDLE_SECTION_NAME),
+    normalizeString(value.hashAlgorithm, DEFAULT_HASH_ALGORITHM),
+  );
+}
+
+function normalizeEntry(value = {}) {
+  if (value instanceof ModuleBundleEntryT) {
+    return value;
+  }
+  const payloadEncoding = normalizePayloadEncoding(value.payloadEncoding);
+  return new ModuleBundleEntryT(
+    normalizeString(value.entryId),
+    normalizeRole(value.role),
+    normalizeString(value.sectionName),
+    normalizeTypeRef(value.typeRef),
+    payloadEncoding,
+    normalizeString(value.mediaType),
+    Number(value.flags ?? 0),
+    normalizeByteArray(value.sha256),
+    normalizeByteArray(value.payload, { encoding: payloadEncoding }),
+    normalizeString(value.description),
+  );
+}
+
+export function decodeModuleBundle(data) {
+  const bb = toByteBuffer(data);
+  if (!ModuleBundle.bufferHasIdentifier(bb)) {
+    throw new Error("Module bundle buffer identifier mismatch.");
+  }
+  return ModuleBundle.getRootAsModuleBundle(bb).unpack();
+}
+
+export function encodeModuleBundle(bundle) {
+  const value =
+    bundle instanceof ModuleBundleT
+      ? bundle
+      : new ModuleBundleT(
+          Number(bundle?.bundleVersion ?? 1),
+          normalizeString(bundle?.moduleFormat, DEFAULT_MODULE_FORMAT),
+          normalizeCanonicalization(bundle?.canonicalization),
+          normalizeByteArray(bundle?.canonicalModuleHash),
+          normalizeByteArray(bundle?.manifestHash),
+          normalizeString(
+            bundle?.manifestExportSymbol,
+            DEFAULT_MANIFEST_EXPORT_SYMBOL,
+          ),
+          normalizeString(
+            bundle?.manifestSizeSymbol,
+            DEFAULT_MANIFEST_SIZE_SYMBOL,
+          ),
+          Array.isArray(bundle?.entries)
+            ? bundle.entries.map(normalizeEntry)
+            : [],
+        );
+  const builder = new flatbuffers.Builder(1024);
+  ModuleBundle.finishModuleBundleBuffer(builder, value.pack(builder));
+  return builder.asUint8Array();
+}
+
+export function moduleBundleRoleToName(value) {
+  return ROLE_ENUM_TO_NAME.get(value) ?? "auxiliary";
+}
+
+export function moduleBundleEncodingToName(value) {
+  return ENCODING_ENUM_TO_NAME.get(value) ?? "raw-bytes";
+}
+
+export function decodeModuleBundleEntryPayload(entry) {
+  const payloadEncoding = normalizePayloadEncoding(entry?.payloadEncoding);
+  const payloadBytes = new Uint8Array(
+    normalizeByteArray(entry?.payload, { encoding: payloadEncoding }),
+  );
+  if (payloadEncoding === ModulePayloadEncoding.JSON_UTF8) {
+    return JSON.parse(new TextDecoder().decode(payloadBytes));
+  }
+  return payloadBytes;
+}
+
+export function findModuleBundleEntry(bundle, match) {
+  const entries = Array.isArray(bundle?.entries) ? bundle.entries : [];
+  if (typeof match === "number") {
+    return entries.find((entry) => entry.role === match) ?? null;
+  }
+  const normalized = String(match ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  return (
+    entries.find((entry) => entry.entryId === match) ??
+    entries.find(
+      (entry) => moduleBundleRoleToName(normalizeRole(entry.role)) === normalized,
+    ) ??
+    null
+  );
+}
+
+export {
+  CanonicalizationRuleT,
+  FlatBufferTypeRefT,
+  ModuleBundle,
+  ModuleBundleEntryRole,
+  ModuleBundleEntryT,
+  ModuleBundleT,
+  ModulePayloadEncoding,
+};

package/src/bundle/constants.js

@@ -0,0 +1,8 @@
+export const SDS_CUSTOM_SECTION_PREFIX = "sds.";
+export const SDS_BUNDLE_SECTION_NAME = "sds.bundle";
+export const DEFAULT_MODULE_FORMAT = "space-data-module";
+export const DEFAULT_HASH_ALGORITHM = "sha256";
+export const DEFAULT_MANIFEST_EXPORT_SYMBOL = "plugin_get_manifest_flatbuffer";
+export const DEFAULT_MANIFEST_SIZE_SYMBOL =
+  "plugin_get_manifest_flatbuffer_size";
+

package/src/bundle/index.js

@@ -0,0 +1,3 @@
+export * from "./constants.js";
+export * from "./codec.js";
+export * from "./wasm.js";