space-data-module-sdk 0.5.14 → 0.5.15

package/src/testing/processInvoke.js

@@ -0,0 +1,226 @@
+import { spawn } from "node:child_process";
+import { Buffer } from "node:buffer";
+import { once } from "node:events";
+import path from "node:path";
+import process from "node:process";
+
+import {
+  decodePluginInvokeResponse,
+  encodePluginInvokeRequest,
+} from "../invoke/index.js";
+import { toUint8Array } from "../runtime/bufferLike.js";
+
+function formatProcessFailure(message, stderrChunks = [], cause = null) {
+  const stderrText = Buffer.concat(stderrChunks).toString("utf8").trim();
+  const details = stderrText ? `${message}\n${stderrText}` : message;
+  return cause ? new Error(details, { cause }) : new Error(details);
+}
+
+function createLengthPrefixedRequest(bytes) {
+  const payload = Buffer.from(bytes);
+  const prefix = Buffer.allocUnsafe(4);
+  prefix.writeUInt32LE(payload.length, 0);
+  return Buffer.concat([prefix, payload]);
+}
+
+function normalizeLaunchPlan(options = {}) {
+  if (options.launchPlan) {
+    return {
+      ...options.launchPlan,
+      args: Array.isArray(options.launchPlan.args) ? options.launchPlan.args : [],
+    };
+  }
+  return {
+    command: options.command ?? null,
+    args: Array.isArray(options.args) ? options.args : [],
+    env: options.env ?? process.env,
+    cwd: options.cwd ?? process.cwd(),
+  };
+}
+
+export function buildWasmEdgeSpawnEnv(baseEnv = process.env) {
+  const env = { ...baseEnv };
+  delete env.DYLD_LIBRARY_PATH;
+  delete env.DYLD_FALLBACK_LIBRARY_PATH;
+  delete env.DYLD_FRAMEWORK_PATH;
+  delete env.DYLD_FALLBACK_FRAMEWORK_PATH;
+  delete env.LIBRARY_PATH;
+  return env;
+}
+
+export function resolveWasmEdgePluginLaunchPlan(options = {}) {
+  const wasmPath =
+    typeof options.wasmPath === "string" && options.wasmPath.trim().length > 0
+      ? path.resolve(options.wasmPath)
+      : null;
+  if (!wasmPath) {
+    throw new Error("resolveWasmEdgePluginLaunchPlan requires a wasmPath.");
+  }
+
+  const invokeArgs =
+    Array.isArray(options.invokeArgs) && options.invokeArgs.length > 0
+      ? [...options.invokeArgs]
+      : ["--serve-plugin-invoke"];
+
+  if (options.wasmEdgeRunnerBinary) {
+    return {
+      command: options.wasmEdgeRunnerBinary,
+      args: [wasmPath, ...invokeArgs],
+      env: buildWasmEdgeSpawnEnv(options.env),
+      wasmPath,
+    };
+  }
+
+  return {
+    command: options.wasmEdgeBinary ?? "wasmedge",
+    args: [
+      ...(options.enableThreads === false ? [] : ["--enable-threads"]),
+      wasmPath,
+      ...invokeArgs,
+    ],
+    env: buildWasmEdgeSpawnEnv(options.env),
+    wasmPath,
+  };
+}
+
+export async function createPluginInvokeProcessClient(options = {}) {
+  const launchPlan = normalizeLaunchPlan(options);
+  if (
+    typeof launchPlan.command !== "string" ||
+    launchPlan.command.trim().length === 0
+  ) {
+    throw new Error("createPluginInvokeProcessClient requires a command.");
+  }
+
+  const child = spawn(launchPlan.command, launchPlan.args, {
+    cwd: launchPlan.cwd ?? process.cwd(),
+    env: launchPlan.env ?? process.env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  let stdoutBuffer = Buffer.alloc(0);
+  const stderrChunks = [];
+  const pending = [];
+  let closed = false;
+  let closeError = null;
+  let expectedShutdown = false;
+
+  function rejectPending(error) {
+    while (pending.length > 0) {
+      pending.shift().reject(error);
+    }
+  }
+
+  function drainResponses() {
+    while (pending.length > 0 && stdoutBuffer.length >= 4) {
+      const responseLength = stdoutBuffer.readUInt32LE(0);
+      if (stdoutBuffer.length < 4 + responseLength) {
+        return;
+      }
+      const responseBytes = stdoutBuffer.subarray(4, 4 + responseLength);
+      stdoutBuffer = stdoutBuffer.subarray(4 + responseLength);
+      pending.shift().resolve(new Uint8Array(responseBytes));
+    }
+  }
+
+  child.stdout.on("data", (chunk) => {
+    stdoutBuffer = Buffer.concat([stdoutBuffer, Buffer.from(chunk)]);
+    drainResponses();
+  });
+  child.stderr.on("data", (chunk) => {
+    stderrChunks.push(Buffer.from(chunk));
+  });
+  child.on("error", (error) => {
+    closeError = formatProcessFailure(
+      "Failed to launch plugin invoke process.",
+      stderrChunks,
+      error,
+    );
+    rejectPending(closeError);
+  });
+
+  const closePromise = once(child, "close").then(([code, signal]) => {
+    closed = true;
+    if (!expectedShutdown && (code !== 0 || signal !== null)) {
+      closeError = formatProcessFailure(
+        `Plugin invoke process exited unexpectedly with ${
+          signal ? `signal ${signal}` : `code ${code}`
+        }.`,
+        stderrChunks,
+      );
+      rejectPending(closeError);
+      throw closeError;
+    }
+    if (!expectedShutdown && code !== 0) {
+      closeError = formatProcessFailure(
+        `Plugin invoke process exited with code ${code}.`,
+        stderrChunks,
+      );
+      rejectPending(closeError);
+      throw closeError;
+    }
+  });
+
+  async function invokeRaw(requestBytes) {
+    if (closeError) {
+      throw closeError;
+    }
+    if (closed) {
+      throw formatProcessFailure(
+        "Plugin invoke process is already closed.",
+        stderrChunks,
+      );
+    }
+
+    const normalizedRequest = toUint8Array(requestBytes);
+    if (!normalizedRequest) {
+      throw new TypeError(
+        "Expected Uint8Array, ArrayBufferView, or ArrayBuffer request bytes.",
+      );
+    }
+
+    return new Promise((resolve, reject) => {
+      pending.push({ resolve, reject });
+      child.stdin.write(createLengthPrefixedRequest(normalizedRequest), (error) => {
+        if (!error) {
+          return;
+        }
+        const pendingIndex = pending.findIndex((entry) => entry.resolve === resolve);
+        if (pendingIndex >= 0) {
+          pending.splice(pendingIndex, 1);
+        }
+        reject(
+          formatProcessFailure(
+            "Failed to send PluginInvokeRequest to child process.",
+            stderrChunks,
+            error,
+          ),
+        );
+      });
+    });
+  }
+
+  return {
+    launchPlan,
+
+    async invoke(request = {}) {
+      const requestBytes = encodePluginInvokeRequest(request);
+      const responseBytes = await invokeRaw(requestBytes);
+      return decodePluginInvokeResponse(responseBytes);
+    },
+
+    invokeRaw,
+
+    async destroy() {
+      expectedShutdown = true;
+      if (!closed) {
+        child.kill();
+      }
+      try {
+        await closePromise;
+      } catch {
+        // Best-effort shutdown: callers only need pending requests cleared.
+      }
+    },
+  };
+}

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

@@ -277,7 +277,27 @@ function validateEncTable(table, buffer, label) {
     maxLength: 32,
   });
   assertOptionalStringField(buffer, tableMeta, 22, `${label} root type`);
-  const record = normalizeEncTable(table.unpack());
+  const timestamp = table.TIMESTAMP();
+  const record = {
+    version: Number(table.VERSION()),
+    keyExchange:
+      KEY_EXCHANGE_NAME_BY_VALUE[table.KEY_EXCHANGE()] ??
+      String(table.KEY_EXCHANGE()),
+    symmetric:
+      SYMMETRIC_ALGO_NAME_BY_VALUE[table.SYMMETRIC()] ??
+      String(table.SYMMETRIC()),
+    keyDerivation:
+      KDF_NAME_BY_VALUE[table.KEY_DERIVATION()] ??
+      String(table.KEY_DERIVATION()),
+    ephemeralPublicKey: normalizeByteField(table.ephemeralPublicKeyArray()),
+    nonceStart: normalizeByteField(table.nonceStartArray()),
+    recipientKeyId: normalizeByteField(table.recipientKeyIdArray()),
+    context: normalizeStringField(table.CONTEXT()),
+    schemaHash: normalizeByteField(table.schemaHashArray()),
+    rootType: normalizeStringField(table.ROOT_TYPE()),
+    timestamp:
+      timestamp === undefined || timestamp === null ? 0 : Number(timestamp),
+  };
   if (!record.ephemeralPublicKey?.length) {
     throw new Error(`${label} is missing the ephemeral public key.`);
   }
@@ -316,7 +336,17 @@ function validatePnmTable(table, buffer, label) {
   assertOptionalStringField(buffer, tableMeta, 16, `${label} timestamp signature`);
   assertOptionalStringField(buffer, tableMeta, 18, `${label} signature type`);
   assertOptionalStringField(buffer, tableMeta, 20, `${label} timestamp signature type`);
-  const record = normalizePnmTable(table.unpack());
+  const record = {
+    multiformatAddress: normalizeStringField(table.MULTIFORMAT_ADDRESS()),
+    publishTimestamp: normalizeStringField(table.PUBLISH_TIMESTAMP()),
+    cid: normalizeStringField(table.CID()),
+    fileName: normalizeStringField(table.FILE_NAME()),
+    fileId: normalizeStringField(table.FILE_ID()),
+    signature: normalizeStringField(table.SIGNATURE()),
+    timestampSignature: normalizeStringField(table.TIMESTAMP_SIGNATURE()),
+    signatureType: normalizeStringField(table.SIGNATURE_TYPE()),
+    timestampSignatureType: normalizeStringField(table.TIMESTAMP_SIGNATURE_TYPE()),
+  };
   if (
     !record.multiformatAddress &&
     !record.publishTimestamp &&
@@ -426,48 +456,6 @@ function pnmTableFromObject(record = {}) {
   );
 }
 
-function normalizeEncTable(table) {
-  if (!table) {
-    return null;
-  }
-  return {
-    version: Number(table.VERSION ?? 1),
-    keyExchange:
-      KEY_EXCHANGE_NAME_BY_VALUE[table.KEY_EXCHANGE] ?? String(table.KEY_EXCHANGE),
-    symmetric:
-      SYMMETRIC_ALGO_NAME_BY_VALUE[table.SYMMETRIC] ?? String(table.SYMMETRIC),
-    keyDerivation:
-      KDF_NAME_BY_VALUE[table.KEY_DERIVATION] ?? String(table.KEY_DERIVATION),
-    ephemeralPublicKey: normalizeByteField(table.EPHEMERAL_PUBLIC_KEY),
-    nonceStart: normalizeByteField(table.NONCE_START),
-    recipientKeyId: normalizeByteField(table.RECIPIENT_KEY_ID),
-    context: normalizeStringField(table.CONTEXT),
-    schemaHash: normalizeByteField(table.SCHEMA_HASH),
-    rootType: normalizeStringField(table.ROOT_TYPE),
-    timestamp:
-      table.TIMESTAMP === undefined || table.TIMESTAMP === null
-        ? 0
-        : Number(table.TIMESTAMP),
-  };
-}
-
-function normalizePnmTable(table) {
-  if (!table) {
-    return null;
-  }
-  return {
-    multiformatAddress: normalizeStringField(table.MULTIFORMAT_ADDRESS),
-    publishTimestamp: normalizeStringField(table.PUBLISH_TIMESTAMP),
-    cid: normalizeStringField(table.CID),
-    fileName: normalizeStringField(table.FILE_NAME),
-    fileId: normalizeStringField(table.FILE_ID),
-    signature: normalizeStringField(table.SIGNATURE),
-    timestampSignature: normalizeStringField(table.TIMESTAMP_SIGNATURE),
-    signatureType: normalizeStringField(table.SIGNATURE_TYPE),
-    timestampSignatureType: normalizeStringField(table.TIMESTAMP_SIGNATURE_TYPE),
-  };
-}
-
 function readFooterLength(bytes) {
   const view = toUint8Array(bytes);
   if (view.length < TRAILER_FOOTER_LENGTH) {
@@ -601,7 +589,6 @@ export function decodePublicationRecordCollection(bytes) {
   if (recordTables.length === 0) {
     throw new Error("REC trailer does not contain any records.");
   }
-  const collection = collectionTable.unpack();
   const records = [];
   let enc = null;
   let pnm = null;
@@ -622,10 +609,12 @@ export function decodePublicationRecordCollection(bytes) {
       8,
       `REC trailer record ${index} standard`,
     );
-    const unpackedRecord = collection.RECORDS[index];
-    const recordType = recordTable.value_type();
+    const recordType =
+      typeof recordTable.valueType === "function"
+        ? recordTable.valueType()
+        : recordTable.value_type();
     const standard =
-      normalizeStringField(unpackedRecord?.standard) ??
+      normalizeStringField(recordTable.standard()) ??
       STANDARD_BY_RECORD_TYPE[recordType] ??
       null;
     const expectedStandard =
@@ -644,10 +633,7 @@ export function decodePublicationRecordCollection(bytes) {
     if (!valueMeta) {
       throw new Error(`REC trailer record ${index} is missing a value.`);
     }
-    let value =
-      standard === "ENC" || standard === "PNM"
-        ? null
-        : unpackedRecord?.value ?? null;
+    let value = null;
     if (standard === "ENC") {
       const encTable = recordTable.value(new ENC());
       if (!encTable) {
@@ -684,7 +670,9 @@ export function decodePublicationRecordCollection(bytes) {
     });
   }
   return {
-    version: normalizeStringField(collection.version) ?? DEFAULT_RECORD_COLLECTION_VERSION,
+    version:
+      normalizeStringField(collectionTable.version()) ??
+      DEFAULT_RECORD_COLLECTION_VERSION,
     records,
     enc,
     pnm,