space-data-module-sdk 0.5.13 → 0.5.15

package/README.md

@@ -321,6 +321,46 @@ The reference path lives in
 Standard bundle payloads now include the optional `deployment-plan` JSON entry
 for resolved protocol installations and producer input bindings.
 
+## Publication Protection Extensions
+
+Digital signature and encrypted-delivery metadata are publication-layer
+extensions, not a second module format. The canonical module is still:
+
+- valid `.wasm`
+- optionally carrying `sds.bundle` as a wasm custom section
+- optionally carrying one appended SDS `REC` trailer after the wasm bytes
+
+That trailing `REC` FlatBuffer is the standards-backed container for
+publication records:
+
+- `PNM` is the publication notice / digital-signature record
+  - identifies the artifact
+  - carries the CID and publish timestamp
+  - carries signature metadata so a loader can verify who published the module
+- `ENC` is the encrypted-delivery record
+  - carries the X25519 / AES-CTR / HKDF parameters needed to decrypt the
+    protected transport payload
+  - does not change the canonical module ABI or manifest shape
+
+The loader contract is always:
+
+1. Start with the protected blob.
+2. Scan backward for the trailing `REC` footer.
+3. Parse `REC` using the standards-generated `REC`, `PNM`, and `ENC`
+   FlatBuffers from `spacedatastandards.org`.
+4. Resolve `PNM` for signature/publication metadata.
+5. Resolve `ENC` if the delivery was encrypted.
+6. Strip the trailer or decrypt the protected payload.
+7. Hand the remaining raw wasm bytes to the runtime.
+
+Aligned-binary payloads are a separate invoke-ABI optimization. They do not
+replace the canonical FlatBuffer schema. If a port advertises
+`wireFormat: "aligned-binary"`, it must also advertise the regular
+`wireFormat: "flatbuffer"` fallback for the same schema and file identifier in
+the same accepted type set. The publication demo in the local lab uses a
+regular `OMM.fbs` request and a `StateVector.fbs` response that advertises both
+the canonical FlatBuffer fallback and the aligned-binary layout metadata.
+
 ## Module Publication
 
 Packages that publish Space Data modules use the canonical `sdn-module`
@@ -424,10 +464,14 @@ npm run start:lab
 
 Then open `http://localhost:4318`.
 
+Use the `Run Publication Demo` button to generate a protected demo artifact and
+inspect the parsed `REC`, `PNM`, and `ENC` records produced by the real
+`spacedatastandards.org` generated message classes.
+
 ## Related Projects
 
 - [`spacedatastandards.org`](https://spacedatastandards.org)
-- [`@digitalarsenal/sdn-flow`](https://github.com/DigitalArsenal/sdn-flow)
+- [`sdn-flow`](https://github.com/DigitalArsenal/sdn-flow)
 - [`hd-wallet-wasm`](https://github.com/nicktj-dev/hd-wallet-wasm)
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -40,9 +40,6 @@
     "schemas/",
     "src/"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
   "scripts": {
     "test": "node --test",
     "test:host-surfaces": "node --test test/node-host.test.js test/host-abi.test.js",

package/src/compiler/flatcSupport.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { readFile, readdir, stat } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
 import { FlatcRunner } from "flatc-wasm";
@@ -18,48 +18,6 @@ function loadFlatcRunner() {
   return flatcRunnerPromise;
 }
 
-const FLATBUFFERS_INCLUDE_ROOT_CANDIDATES = [
-  process.env.FLATBUFFERS_INCLUDE_DIR,
-  "/opt/homebrew/include",
-  "/usr/local/include",
-  "/usr/include",
-].filter(Boolean);
-
-async function findFlatbuffersIncludeRoot() {
-  for (const candidate of FLATBUFFERS_INCLUDE_ROOT_CANDIDATES) {
-    const headerPath = path.join(candidate, "flatbuffers", "flatbuffers.h");
-    try {
-      const headerStat = await stat(headerPath);
-      if (headerStat.isFile()) {
-        return candidate;
-      }
-    } catch {
-      // Try the next candidate.
-    }
-  }
-  throw new Error(
-    "Unable to locate the installed flatbuffers C++ headers. Set FLATBUFFERS_INCLUDE_DIR to the directory containing flatbuffers/flatbuffers.h.",
-  );
-}
-
-async function readDirectoryTree(rootDir, currentDir = rootDir) {
-  const entries = await readdir(currentDir, { withFileTypes: true });
-  const files = [];
-  for (const entry of entries) {
-    const fullPath = path.join(currentDir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...(await readDirectoryTree(rootDir, fullPath)));
-      continue;
-    }
-    if (!entry.isFile()) {
-      continue;
-    }
-    const relativePath = path.relative(rootDir, fullPath).split(path.sep).join("/");
-    files.push([`/${relativePath}`, await readFile(fullPath, "utf8")]);
-  }
-  return files;
-}
-
 async function loadInvokeSchemaFiles() {
   const filenames = [
     "TypedArenaBuffer.fbs",
@@ -78,10 +36,8 @@ async function loadInvokeSchemaFiles() {
 export async function getFlatbuffersCppRuntimeHeaders() {
   if (!flatbuffersCppRuntimeHeadersPromise) {
     flatbuffersCppRuntimeHeadersPromise = (async () => {
-      const includeRoot = await findFlatbuffersIncludeRoot();
-      return Object.fromEntries(
-        await readDirectoryTree(includeRoot, path.join(includeRoot, "flatbuffers")),
-      );
+      const flatc = await loadFlatcRunner();
+      return flatc.getEmbeddedRuntime("cpp");
     })();
   }
   return flatbuffersCppRuntimeHeadersPromise;

package/src/compliance/pluginCompliance.js

@@ -366,7 +366,7 @@ function validateAllowedType(type, issues, location) {
       "Allowed type fixedStringLength",
       { min: 0 },
     );
-    validateOptionalIntegerField(
+    validateIntegerField(
       issues,
       type.byteLength,
       `${location}.byteLength`,

package/src/index.d.ts

@@ -664,6 +664,8 @@ export type {
   ManifestHarnessPlan,
   ModuleHarness,
   ModuleHarnessRuntimeDescriptor,
+  PublicationProtectionDemoAlignedType,
+  PublicationProtectionDemoSummary,
   PluginInvokeProcessClient,
   PluginInvokeProcessLaunchPlan,
   WasmEdgeRunnerBuildPlan,
@@ -672,6 +674,8 @@ export type {
 export {
   buildWasmEdgeEmscriptenPthreadRunner,
   buildWasmEdgeSpawnEnv,
+  createPublicationProtectionDemoManifest,
+  createPublicationProtectionDemoSummary,
   createModuleHarness,
   createPluginInvokeProcessClient,
   describeCapabilityRuntimeSurface,

package/src/manifest/typeRefs.js

@@ -1,62 +1,31 @@
 function cloneSchemaHash(value) {
   if (value instanceof Uint8Array) {
-    return value.byteLength > 0 ? new Uint8Array(value) : undefined;
+    return new Uint8Array(value);
   }
   if (Array.isArray(value)) {
-    return value.length > 0 ? [...value] : undefined;
+    return [...value];
   }
   return value ?? undefined;
 }
 
-function normalizeNullableString(value) {
-  if (value === undefined || value === null) {
-    return null;
-  }
-  const normalized = String(value).trim();
-  return normalized.length > 0 ? normalized : null;
-}
-
-function normalizeAlignedMetadataScalar(value) {
-  if (value === undefined || value === null || value === "") {
-    return undefined;
-  }
-  const numeric = Number(value);
-  if (Number.isFinite(numeric)) {
-    return numeric === 0 ? undefined : numeric;
-  }
-  return value;
-}
-
 export function clonePayloadTypeRef(value = null) {
   if (!value || typeof value !== "object") {
-    return { acceptsAnyFlatbuffer: true, fileIdentifier: null };
+    return { acceptsAnyFlatbuffer: true };
   }
   return {
-    schemaName: normalizeNullableString(
-      value.schemaName ?? value.schema_name,
-    ),
-    fileIdentifier: normalizeNullableString(
-      value.fileIdentifier ?? value.file_identifier,
-    ),
+    schemaName: value.schemaName ?? value.schema_name ?? undefined,
+    fileIdentifier: value.fileIdentifier ?? value.file_identifier ?? undefined,
     schemaHash: cloneSchemaHash(value.schemaHash ?? value.schema_hash),
     acceptsAnyFlatbuffer: Boolean(
       value.acceptsAnyFlatbuffer ?? value.accepts_any_flatbuffer ?? false,
     ),
-    wireFormat: normalizePayloadWireFormatName(
-      value.wireFormat ?? value.wire_format,
-    ),
-    rootTypeName: normalizeNullableString(
-      value.rootTypeName ?? value.root_type_name,
-    ),
-    fixedStringLength: normalizeAlignedMetadataScalar(
-      value.fixedStringLength ?? value.fixed_string_length,
-    ),
-    byteLength: normalizeAlignedMetadataScalar(
-      value.byteLength ?? value.byte_length,
-    ),
-    requiredAlignment: normalizeAlignedMetadataScalar(
-      value.requiredAlignment ?? value.required_alignment,
-    ),
+    wireFormat: value.wireFormat ?? value.wire_format ?? undefined,
+    rootTypeName: value.rootTypeName ?? value.root_type_name ?? undefined,
+    fixedStringLength:
+      value.fixedStringLength ?? value.fixed_string_length ?? undefined,
+    byteLength: value.byteLength ?? value.byte_length ?? undefined,
+    requiredAlignment:
+      value.requiredAlignment ?? value.required_alignment ?? undefined,
   };
 }
 
@@ -64,12 +33,6 @@ export function normalizePayloadWireFormatName(value) {
   if (value === undefined || value === null || value === "") {
     return null;
   }
-  if (value === 1 || value === "1") {
-    return "aligned-binary";
-  }
-  if (value === 0 || value === "0") {
-    return "flatbuffer";
-  }
   const normalized = String(value).trim().toLowerCase().replace(/_/g, "-");
   if (normalized === "aligned-binary") {
     return "aligned-binary";

package/src/testing/index.d.ts

@@ -57,6 +57,75 @@ export interface ManifestHarnessPlan {
   scenarios: Array<HarnessInvokeScenario | HarnessRawScenario>;
 }
 
+export interface PublicationProtectionDemoAlignedType {
+  methodId: string | null;
+  portId: string | null;
+  setId: string | null;
+  schemaName: string | null;
+  fileIdentifier: string | null;
+  rootTypeName: string | null;
+  byteLength: number | null;
+  requiredAlignment: number | null;
+  hasFlatbufferFallback: boolean;
+}
+
+export interface PublicationProtectionDemoSummary {
+  manifest: PluginManifest;
+  recTrailer: {
+    fileIdentifier: string;
+    version: string | null;
+    recordCount: number;
+    recordStandards: Array<string | null>;
+    usesStandardsFlatbuffers: boolean;
+    records: Array<Record<string, unknown>>;
+  };
+  alignedBinaryContract: PublicationProtectionDemoAlignedType[];
+  signedOnly: {
+    artifactId: string;
+    encrypted: boolean;
+    trailer: PublicationProtectionDemoSummary["recTrailer"];
+    recordStandards: Array<string | null>;
+    pnm: {
+      fileName: string | null;
+      fileId: string | null;
+      cid: string | null;
+      hasSignature: boolean;
+      signatureType: string | null;
+      publishTimestamp: string | null;
+    } | null;
+    enc: null;
+    envelope: null;
+  };
+  encryptedDelivery: {
+    artifactId: string;
+    encrypted: boolean;
+    trailer: PublicationProtectionDemoSummary["recTrailer"];
+    recordStandards: Array<string | null>;
+    pnm: {
+      fileName: string | null;
+      fileId: string | null;
+      cid: string | null;
+      hasSignature: boolean;
+      signatureType: string | null;
+      publishTimestamp: string | null;
+    } | null;
+    enc: {
+      context: string | null;
+      rootType: string | null;
+      keyExchange: string | null;
+      symmetric: string | null;
+      keyDerivation: string | null;
+      nonceLength: number;
+      ephemeralPublicKeyLength: number;
+    } | null;
+    envelope: {
+      scheme: string | null;
+      hasEncRecord: boolean;
+      hasPnmRecord: boolean;
+    } | null;
+  };
+}
+
 export interface PluginInvokeProcessLaunchPlan {
   command: string;
   args: string[];
@@ -124,6 +193,18 @@ export function describeCapabilityRuntimeSurface(
   capability: string,
 ): CapabilityRuntimeSurface;
 
+export function createPublicationProtectionDemoManifest(): PluginManifest;
+
+export function createPublicationProtectionDemoSummary(options?: {
+  manifest?: PluginManifest;
+  wasmBytes?: Uint8Array;
+  mnemonic?: string | null;
+  recipient?: {
+    publicKeyHex: string;
+    privateKeyHex: string;
+  };
+}): Promise<PublicationProtectionDemoSummary>;
+
 export function generateManifestHarnessPlan(options: {
   manifest: PluginManifest;
   includeOptionalInputs?: boolean;

package/src/testing/index.js

@@ -3,6 +3,10 @@ import { Buffer } from "node:buffer";
 import { encodePluginInvokeRequest } from "../invoke/codec.js";
 import { normalizeInvokeSurfaces } from "../invoke/index.js";
 import { selectPreferredPayloadTypeRef } from "../manifest/typeRefs.js";
+export {
+  createPublicationProtectionDemoManifest,
+  createPublicationProtectionDemoSummary,
+} from "./publicationProtectionDemo.js";
 export {
   buildWasmEdgeSpawnEnv,
   createPluginInvokeProcessClient,

package/src/testing/publicationProtectionDemo.js

@@ -0,0 +1,271 @@
+import * as flatbuffers from "flatbuffers";
+
+import { createRecipientKeypairHex, protectModuleArtifact } from "../compiler/compileModule.js";
+import { extractPublicationRecordCollection } from "../transport/records.js";
+import { REC } from "spacedatastandards.org/lib/js/REC/REC.js";
+import { Record } from "spacedatastandards.org/lib/js/REC/Record.js";
+import { PNM } from "spacedatastandards.org/lib/js/PNM/main.js";
+import { ENC } from "spacedatastandards.org/lib/js/ENC/main.js";
+
+const MINIMAL_WASM_BYTES = Uint8Array.of(
+  0x00,
+  0x61,
+  0x73,
+  0x6d,
+  0x01,
+  0x00,
+  0x00,
+  0x00,
+);
+
+export function createPublicationProtectionDemoManifest() {
+  return {
+    pluginId: "com.digitalarsenal.examples.publication-protection-demo",
+    name: "Publication Protection Demo",
+    version: "0.1.0",
+    pluginFamily: "propagator",
+    capabilities: ["clock", "crypto_sign", "crypto_encrypt"],
+    externalInterfaces: [],
+    methods: [
+      {
+        methodId: "propagate",
+        displayName: "Propagate",
+        inputPorts: [
+          {
+            portId: "request",
+            acceptedTypeSets: [
+              {
+                setId: "omm-request",
+                allowedTypes: [
+                  {
+                    schemaName: "OMM.fbs",
+                    fileIdentifier: "$OMM",
+                  },
+                ],
+              },
+            ],
+            minStreams: 1,
+            maxStreams: 1,
+            required: true,
+          },
+        ],
+        outputPorts: [
+          {
+            portId: "state",
+            acceptedTypeSets: [
+              {
+                setId: "state-vector",
+                allowedTypes: [
+                  {
+                    schemaName: "StateVector.fbs",
+                    fileIdentifier: "STVC",
+                  },
+                  {
+                    schemaName: "StateVector.fbs",
+                    fileIdentifier: "STVC",
+                    wireFormat: "aligned-binary",
+                    rootTypeName: "StateVector",
+                    byteLength: 72,
+                    requiredAlignment: 8,
+                  },
+                ],
+              },
+            ],
+            minStreams: 1,
+            maxStreams: 1,
+            required: true,
+          },
+        ],
+        maxBatch: 32,
+        drainPolicy: "drain-to-empty",
+      },
+    ],
+    schemasUsed: [
+      {
+        schemaName: "OMM.fbs",
+        fileIdentifier: "$OMM",
+      },
+      {
+        schemaName: "StateVector.fbs",
+        fileIdentifier: "STVC",
+      },
+      {
+        schemaName: "StateVector.fbs",
+        fileIdentifier: "STVC",
+        wireFormat: "aligned-binary",
+        rootTypeName: "StateVector",
+        byteLength: 72,
+        requiredAlignment: 8,
+      },
+    ],
+  };
+}
+
+function summarizeAlignedBinaryContract(manifest = {}) {
+  const summaries = [];
+  for (const method of Array.isArray(manifest.methods) ? manifest.methods : []) {
+    const ports = [
+      ...(Array.isArray(method.inputPorts) ? method.inputPorts : []),
+      ...(Array.isArray(method.outputPorts) ? method.outputPorts : []),
+    ];
+    for (const port of ports) {
+      for (const typeSet of Array.isArray(port.acceptedTypeSets)
+        ? port.acceptedTypeSets
+        : []) {
+        const allowedTypes = Array.isArray(typeSet.allowedTypes)
+          ? typeSet.allowedTypes
+          : [];
+        for (const allowedType of allowedTypes) {
+          if (allowedType?.wireFormat !== "aligned-binary") {
+            continue;
+          }
+          const hasFlatbufferFallback = allowedTypes.some(
+            (candidate) =>
+              (candidate?.wireFormat ?? "flatbuffer") === "flatbuffer" &&
+              candidate?.schemaName === allowedType.schemaName &&
+              candidate?.fileIdentifier === allowedType.fileIdentifier,
+          );
+          summaries.push({
+            methodId: method.methodId ?? null,
+            portId: port.portId ?? null,
+            setId: typeSet.setId ?? null,
+            schemaName: allowedType.schemaName ?? null,
+            fileIdentifier: allowedType.fileIdentifier ?? null,
+            rootTypeName: allowedType.rootTypeName ?? null,
+            byteLength: allowedType.byteLength ?? null,
+            requiredAlignment: allowedType.requiredAlignment ?? null,
+            hasFlatbufferFallback,
+          });
+        }
+      }
+    }
+  }
+  return summaries;
+}
+
+function parseStandardsRec(recordCollectionBytes) {
+  const recBuffer = new flatbuffers.ByteBuffer(recordCollectionBytes);
+  const rec = REC.getRootAsREC(recBuffer);
+  const records = [];
+  for (let index = 0; index < rec.recordsLength(); index += 1) {
+    const record = rec.RECORDS(index, new Record());
+    if (!record) {
+      continue;
+    }
+    const standard = record.standard() ?? null;
+    if (standard === "PNM") {
+      const pnm = record.value(new PNM());
+      records.push({
+        standard,
+        fileIdentifier: "$PNM",
+        fileName: pnm?.FILE_NAME() ?? null,
+        fileId: pnm?.FILE_ID() ?? null,
+        cid: pnm?.CID() ?? null,
+        hasSignature: Boolean(pnm?.SIGNATURE()),
+      });
+      continue;
+    }
+    if (standard === "ENC") {
+      const enc = record.value(new ENC());
+      records.push({
+        standard,
+        fileIdentifier: "$ENC",
+        context: enc?.CONTEXT() ?? null,
+        rootType: enc?.ROOT_TYPE() ?? null,
+        nonceLength: enc?.nonceStartLength() ?? 0,
+        ephemeralPublicKeyLength: enc?.ephemeralPublicKeyLength() ?? 0,
+      });
+      continue;
+    }
+    records.push({
+      standard,
+      fileIdentifier: null,
+    });
+  }
+  return {
+    fileIdentifier: "$REC",
+    version: rec.version() ?? null,
+    recordCount: records.length,
+    recordStandards: records.map((record) => record.standard),
+    usesStandardsFlatbuffers: REC.bufferHasIdentifier(
+      new flatbuffers.ByteBuffer(recordCollectionBytes),
+    ),
+    records,
+  };
+}
+
+function summarizeProtectedArtifact(protectedArtifact) {
+  const parsed = extractPublicationRecordCollection(
+    protectedArtifact.protectedArtifactBytes,
+  );
+  if (!parsed) {
+    throw new Error("Protected artifact is missing the REC publication trailer.");
+  }
+  const trailer = parseStandardsRec(parsed.recordCollectionBytes);
+  return {
+    artifactId: protectedArtifact.payload.artifactId,
+    encrypted: protectedArtifact.encrypted,
+    trailer,
+    recordStandards: trailer.recordStandards,
+    pnm: parsed.pnm
+      ? {
+          fileName: parsed.pnm.fileName ?? null,
+          fileId: parsed.pnm.fileId ?? null,
+          cid: parsed.pnm.cid ?? null,
+          hasSignature: Boolean(parsed.pnm.signature),
+          signatureType: parsed.pnm.signatureType ?? null,
+          publishTimestamp: parsed.pnm.publishTimestamp ?? null,
+        }
+      : null,
+    enc: parsed.enc
+      ? {
+          context: parsed.enc.context ?? null,
+          rootType: parsed.enc.rootType ?? null,
+          keyExchange: parsed.enc.keyExchange ?? null,
+          symmetric: parsed.enc.symmetric ?? null,
+          keyDerivation: parsed.enc.keyDerivation ?? null,
+          nonceLength: parsed.enc.nonceStart?.length ?? 0,
+          ephemeralPublicKeyLength: parsed.enc.ephemeralPublicKey?.length ?? 0,
+        }
+      : null,
+    envelope: protectedArtifact.encryptedEnvelope
+      ? {
+          scheme: protectedArtifact.encryptedEnvelope.scheme ?? null,
+          hasEncRecord: Boolean(
+            protectedArtifact.encryptedEnvelope.encRecordBase64,
+          ),
+          hasPnmRecord: Boolean(
+            protectedArtifact.encryptedEnvelope.pnmRecordBase64,
+          ),
+        }
+      : null,
+  };
+}
+
+export async function createPublicationProtectionDemoSummary(options = {}) {
+  const manifest = options.manifest ?? createPublicationProtectionDemoManifest();
+  const wasmBytes =
+    options.wasmBytes instanceof Uint8Array
+      ? options.wasmBytes
+      : MINIMAL_WASM_BYTES;
+  const recipient = options.recipient ?? (await createRecipientKeypairHex());
+  const signedOnly = await protectModuleArtifact({
+    manifest,
+    wasmBytes,
+    mnemonic: options.mnemonic ?? null,
+  });
+  const encryptedDelivery = await protectModuleArtifact({
+    manifest,
+    wasmBytes,
+    mnemonic: options.mnemonic ?? null,
+    recipientPublicKeyHex: recipient.publicKeyHex,
+  });
+
+  return {
+    manifest,
+    recTrailer: parseStandardsRec(signedOnly.publicationRecordsBytes),
+    alignedBinaryContract: summarizeAlignedBinaryContract(manifest),
+    signedOnly: summarizeProtectedArtifact(signedOnly),
+    encryptedDelivery: summarizeProtectedArtifact(encryptedDelivery),
+  };
+}

package/src/transport/records.js

@@ -612,13 +612,7 @@ export function decodePublicationRecordCollection(bytes) {
     const recordType =
       typeof recordTable.valueType === "function"
         ? recordTable.valueType()
-        : typeof recordTable.value_type === "function"
-          ? recordTable.value_type()
-          : (() => {
-              throw new TypeError(
-                "REC Record wrapper is missing both valueType() and value_type() accessors.",
-              );
-            })();
+        : recordTable.value_type();
     const standard =
       normalizeStringField(recordTable.standard()) ??
       STANDARD_BY_RECORD_TYPE[recordType] ??