space-data-module-sdk 0.1.0 → 0.2.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/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.

package/src/bundle/codec.js

@@ -0,0 +1,244 @@
+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 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),
+  );
+}
+
+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";