space-data-module-sdk 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",

package/src/bundle/constants.js

@@ -9,3 +9,8 @@ export const SDS_DEPLOYMENT_SECTION_NAME = "sds.deployment";
 export const SDS_DEPLOYMENT_ENTRY_ID = "deployment-plan";
 export const SDS_DEPLOYMENT_MEDIA_TYPE =
   "application/vnd.space-data.module.deployment+json";
+export const SDS_GUEST_LINK_OBJECT_ENTRY_ID = "guest-link-object";
+export const SDS_GUEST_LINK_METADATA_ENTRY_ID = "guest-link-metadata";
+export const SDS_GUEST_LINK_SECTION_NAME = "sds.guest-link";
+export const SDS_GUEST_LINK_MEDIA_TYPE =
+  "application/vnd.space-data.module.guest-link+json";

package/src/compiler/compileModule.js

@@ -30,6 +30,16 @@ import {
   generateX25519Keypair,
 } from "../transport/index.js";
 import { createSingleFileBundle } from "../bundle/index.js";
+import {
+  SDS_GUEST_LINK_MEDIA_TYPE,
+  SDS_GUEST_LINK_METADATA_ENTRY_ID,
+  SDS_GUEST_LINK_OBJECT_ENTRY_ID,
+  SDS_GUEST_LINK_SECTION_NAME,
+} from "../bundle/constants.js";
+import {
+  decodeUnsignedLeb128,
+  parseWasmModuleSections,
+} from "../bundle/wasm.js";
 import {
   base64ToBytes,
   bytesToBase64,
@@ -76,6 +86,201 @@ function buildCompilerArgs(exportedSymbols, options = {}) {
   return args;
 }
 
+function guestLinkSymbolPrefix(pluginId) {
+  const normalized = String(pluginId ?? "module");
+  const ascii = Array.from(new TextEncoder().encode(normalized))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 24);
+  return `sdm_guest_${ascii}_`;
+}
+
+function parseStrongDefinedIdentifiers(nmOutput = "") {
+  const identifiers = new Set();
+  for (const line of String(nmOutput).split(/\r?\n/)) {
+    const match = line.match(/^\S+\s+([A-Za-z])\s+(.+)$/);
+    if (!match) {
+      continue;
+    }
+    const symbolType = match[1];
+    if (!"TDBCGRSV".includes(symbolType)) {
+      continue;
+    }
+    const demangled = match[2].trim();
+    const baseName = demangled
+      .replace(/\(.*$/, "")
+      .split("::")
+      .at(-1)
+      ?.trim();
+    if (!C_IDENTIFIER.test(baseName ?? "")) {
+      continue;
+    }
+    identifiers.add(baseName);
+  }
+  return Array.from(identifiers).sort();
+}
+
+const WASM_SYM_BINDING_WEAK = 0x01;
+const WASM_SYM_BINDING_LOCAL = 0x02;
+const WASM_SYM_UNDEFINED = 0x10;
+const WASM_SYM_EXPLICIT_NAME = 0x40;
+const WASM_SYMBOL_KIND_FUNCTION = 0;
+const WASM_SYMBOL_KIND_DATA = 1;
+const WASM_SYMBOL_KIND_GLOBAL = 2;
+const WASM_SYMBOL_KIND_SECTION = 3;
+const WASM_SYMBOL_KIND_EVENT = 4;
+const WASM_SYMBOL_KIND_TABLE = 5;
+const LINKING_SYMBOL_TABLE_SUBSECTION_ID = 8;
+const textDecoder = new TextDecoder();
+
+function decodeWasmName(bytes, offset) {
+  const lengthInfo = decodeUnsignedLeb128(bytes, offset);
+  const nameStart = lengthInfo.nextOffset;
+  const nameEnd = nameStart + lengthInfo.value;
+  if (nameEnd > bytes.length) {
+    throw new Error("WASM name extends past end of symbol payload.");
+  }
+  return {
+    value: textDecoder.decode(bytes.subarray(nameStart, nameEnd)),
+    nextOffset: nameEnd,
+  };
+}
+
+function parseDefinedLinkSymbolsFromObjectBytes(objectBytes) {
+  const parsed = parseWasmModuleSections(objectBytes);
+  const linkingSection = parsed.sections.find(
+    (section) => section.id === 0 && section.name === "linking",
+  );
+  if (!linkingSection) {
+    throw new Error("Guest-link object is missing a linking custom section.");
+  }
+  const payload = linkingSection.dataBytes;
+  let offset = decodeUnsignedLeb128(payload, 0).nextOffset;
+  const identifiers = new Set();
+  while (offset < payload.length) {
+    const subsectionId = payload[offset++];
+    const sizeInfo = decodeUnsignedLeb128(payload, offset);
+    offset = sizeInfo.nextOffset;
+    const subsectionEnd = offset + sizeInfo.value;
+    if (subsectionEnd > payload.length) {
+      throw new Error("Linking subsection extends past end of payload.");
+    }
+    if (subsectionId !== LINKING_SYMBOL_TABLE_SUBSECTION_ID) {
+      offset = subsectionEnd;
+      continue;
+    }
+    let cursor = offset;
+    const countInfo = decodeUnsignedLeb128(payload, cursor);
+    cursor = countInfo.nextOffset;
+    for (let symbolIndex = 0; symbolIndex < countInfo.value; symbolIndex += 1) {
+      const kind = payload[cursor++];
+      const flagsInfo = decodeUnsignedLeb128(payload, cursor);
+      const flags = flagsInfo.value;
+      cursor = flagsInfo.nextOffset;
+      let name = "";
+      if (
+        kind === WASM_SYMBOL_KIND_FUNCTION ||
+        kind === WASM_SYMBOL_KIND_GLOBAL ||
+        kind === WASM_SYMBOL_KIND_EVENT ||
+        kind === WASM_SYMBOL_KIND_TABLE
+      ) {
+        cursor = decodeUnsignedLeb128(payload, cursor).nextOffset;
+        if (
+          (flags & WASM_SYM_UNDEFINED) === 0 ||
+          (flags & WASM_SYM_EXPLICIT_NAME) !== 0
+        ) {
+          const nameInfo = decodeWasmName(payload, cursor);
+          name = nameInfo.value;
+          cursor = nameInfo.nextOffset;
+        }
+      } else if (kind === WASM_SYMBOL_KIND_DATA) {
+        const nameInfo = decodeWasmName(payload, cursor);
+        name = nameInfo.value;
+        cursor = nameInfo.nextOffset;
+        if ((flags & WASM_SYM_UNDEFINED) === 0) {
+          cursor = decodeUnsignedLeb128(payload, cursor).nextOffset;
+          cursor = decodeUnsignedLeb128(payload, cursor).nextOffset;
+          cursor = decodeUnsignedLeb128(payload, cursor).nextOffset;
+        }
+      } else if (kind === WASM_SYMBOL_KIND_SECTION) {
+        cursor = decodeUnsignedLeb128(payload, cursor).nextOffset;
+      } else {
+        throw new Error(`Unsupported WASM linking symbol kind: ${kind}`);
+      }
+      if ((flags & WASM_SYM_UNDEFINED) !== 0) {
+        continue;
+      }
+      if ((flags & WASM_SYM_BINDING_LOCAL) !== 0) {
+        continue;
+      }
+      if ((flags & WASM_SYM_BINDING_WEAK) !== 0) {
+        continue;
+      }
+      if (!C_IDENTIFIER.test(name)) {
+        continue;
+      }
+      identifiers.add(name);
+    }
+    return Array.from(identifiers).sort();
+  }
+  throw new Error("Guest-link object is missing a symbol table subsection.");
+}
+
+function deriveGuestLinkRenameArgs({
+  objectBytes,
+  pluginId,
+  methodIds = [],
+} = {}) {
+  const identifiers = parseDefinedLinkSymbolsFromObjectBytes(objectBytes);
+  const prefix = guestLinkSymbolPrefix(pluginId);
+  const renamedIdentifiers = Array.from(
+    new Set([...identifiers, ...methodIds.filter((value) => C_IDENTIFIER.test(value))]),
+  ).sort();
+  return {
+    prefix,
+    identifiers: renamedIdentifiers,
+    renameArgs: renamedIdentifiers.map(
+      (identifier) => `-D${identifier}=${prefix}${identifier}`,
+    ),
+    methodSymbols: Object.fromEntries(
+      methodIds.map((methodId) => [methodId, `${prefix}${methodId}`]),
+    ),
+  };
+}
+
+function createGuestLinkBundleEntries(guestLink) {
+  if (!guestLink?.objectBytes || guestLink.objectBytes.length === 0) {
+    return [];
+  }
+  return [
+    {
+      entryId: SDS_GUEST_LINK_OBJECT_ENTRY_ID,
+      role: "auxiliary",
+      sectionName: SDS_GUEST_LINK_SECTION_NAME,
+      payloadEncoding: "raw-bytes",
+      mediaType: "application/wasm",
+      payload: guestLink.objectBytes,
+      description: "Prefixed guest-link wasm object for monolithic flow linking.",
+    },
+    {
+      entryId: SDS_GUEST_LINK_METADATA_ENTRY_ID,
+      role: "auxiliary",
+      sectionName: SDS_GUEST_LINK_SECTION_NAME,
+      payloadEncoding: "json-utf8",
+      mediaType: SDS_GUEST_LINK_MEDIA_TYPE,
+      payload: {
+        version: 1,
+        format: "wasm-object",
+        symbolPrefix: guestLink.symbolPrefix,
+        methodSymbols: guestLink.methodSymbols,
+        methodIds: Object.keys(guestLink.methodSymbols ?? {}),
+        language: guestLink.language,
+      },
+      description: "Guest-link metadata for monolithic flow linking.",
+    },
+  ];
+}
+
 async function getInvokeCppSupportFiles() {
   const [runtimeHeaders, schemaHeaders] = await Promise.all([
     getFlatbuffersCppRuntimeHeaders(),
@@ -114,6 +319,8 @@ function removeEmceptionDirectory(emception, directoryPath) {
 
 async function compileWithEmception(options = {}) {
   const {
+    manifest,
+    language,
     sourceCompilerCommand,
     sourceExtension,
     sourceCode,
@@ -140,6 +347,7 @@ async function compileWithEmception(options = {}) {
       const invokeHeaderPath = path.posix.join(workDir, "space_data_module_invoke.h");
       const invokeSourcePath = path.posix.join(workDir, "plugin-invoke-bridge.cpp");
       const sourceObjectPath = path.posix.join(workDir, "module.o");
+      const linkObjectPath = path.posix.join(workDir, "module-link.o");
       const manifestObjectPath = path.posix.join(workDir, "plugin-manifest-exports.o");
       const invokeObjectPath = path.posix.join(workDir, "plugin-invoke-bridge.o");
       const wasmOutputPath = path.posix.join(workDir, "module.wasm");
@@ -165,6 +373,43 @@ async function compileWithEmception(options = {}) {
             "-o",
             sourceObjectPath,
           ],
+        ];
+
+        for (const command of commands) {
+          const result = emception.run(command.join(" "));
+          if (result.returncode !== 0) {
+            throw new Error(
+              `Compilation failed with ${command[0]} (emception): ${result.stderr || result.stdout}`,
+            );
+          }
+        }
+
+        const sourceObjectBytes = new Uint8Array(emception.readFile(sourceObjectPath));
+        const guestLink = deriveGuestLinkRenameArgs({
+          objectBytes: sourceObjectBytes,
+          pluginId: manifest?.pluginId,
+          methodIds: Array.isArray(manifest?.methods)
+            ? manifest.methods.map((method) => String(method?.methodId ?? ""))
+            : [],
+        });
+
+        const linkCompileCommand = [
+          sourceCompilerCommand,
+          "-c",
+          sourcePath,
+          `-I${workDir}`,
+          ...guestLink.renameArgs,
+          "-o",
+          linkObjectPath,
+        ];
+        const linkCompileResult = emception.run(linkCompileCommand.join(" "));
+        if (linkCompileResult.returncode !== 0) {
+          throw new Error(
+            `Compilation failed with ${linkCompileCommand[0]} (emception): ${linkCompileResult.stderr || linkCompileResult.stdout}`,
+          );
+        }
+
+        const remainingCommands = [
           [
             "em++",
             "-c",
@@ -195,8 +440,7 @@ async function compileWithEmception(options = {}) {
             wasmOutputPath,
           ],
         ];
-
-        for (const command of commands) {
+        for (const command of remainingCommands) {
           const result = emception.run(command.join(" "));
           if (result.returncode !== 0) {
             throw new Error(
@@ -206,8 +450,20 @@ async function compileWithEmception(options = {}) {
         }
 
         const wasmBytes = new Uint8Array(emception.readFile(wasmOutputPath));
+        const linkObjectBytes = new Uint8Array(emception.readFile(linkObjectPath));
         await writeFile(resolvedOutputPath, wasmBytes);
-        return { wasmBytes, outputPath: resolvedOutputPath, tempDir };
+        return {
+          wasmBytes,
+          outputPath: resolvedOutputPath,
+          tempDir,
+          guestLink: {
+            format: "wasm-object",
+            language,
+            symbolPrefix: guestLink.prefix,
+            methodSymbols: guestLink.methodSymbols,
+            objectBytes: linkObjectBytes,
+          },
+        };
       } finally {
         try {
           removeEmceptionDirectory(emception, workDir);
@@ -275,6 +531,8 @@ export async function compileModuleFromSource(options = {}) {
     noEntry: includeCommandMain !== true,
   };
   const result = await compileWithEmception({
+    manifest,
+    language: compiler.language,
     sourceCompilerCommand: compiler.command,
     sourceExtension: compiler.extension,
     sourceCode,
@@ -301,6 +559,7 @@ export async function compileModuleFromSource(options = {}) {
     outputPath: resolvedOutputPath,
     tempDir,
     wasmBytes,
+    guestLink: result.guestLink,
     manifestWarnings: warnings,
     report,
   };
@@ -394,12 +653,16 @@ export async function protectModuleArtifact(options = {}) {
 
   let singleFileBundle = null;
   if (options.singleFileBundle === true) {
+    const additionalEntries = [
+      ...(Array.isArray(options.bundleEntries) ? options.bundleEntries : []),
+      ...createGuestLinkBundleEntries(options.guestLink),
+    ];
     singleFileBundle = await createSingleFileBundle({
       wasmBytes,
       manifest,
       authorization: signedAuthorization,
       transportEnvelope: encryptedEnvelope,
-      entries: options.bundleEntries,
+      entries: additionalEntries,
     });
   }
 

package/src/deployment/index.js

@@ -402,6 +402,9 @@ function buildMethodLookup(manifest) {
 }
 
 function buildExternalInterfaceLookup(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return null;
+  }
   const lookup = new Map();
   if (!Array.isArray(manifest?.externalInterfaces)) {
     return lookup;
@@ -427,6 +430,9 @@ function validateDeclaredInterface(
   externalInterfaceLookup,
   allowedDirections,
 ) {
+  if (!externalInterfaceLookup) {
+    return;
+  }
   const normalizedInterfaceId = normalizeString(interfaceId);
   if (!normalizedInterfaceId) {
     return;

package/src/index.d.ts

@@ -424,10 +424,19 @@ export interface CompilationResult {
   outputPath: string | null;
   tempDir: string | null;
   wasmBytes: Uint8Array;
+  guestLink: GuestLinkArtifact | null;
   manifestWarnings: string[];
   report: ComplianceReport;
 }
 
+export interface GuestLinkArtifact {
+  format: "wasm-object";
+  language: string;
+  symbolPrefix: string;
+  methodSymbols: Record<string, string>;
+  objectBytes: Uint8Array;
+}
+
 export interface ProtectedArtifact {
   mnemonic: string;
   signingPublicKeyHex: string;
@@ -473,7 +482,8 @@ export function protectModuleArtifact(options: {
   targetUrl?: string;
   capabilities?: string[];
   singleFileBundle?: boolean;
-  bundleEntries?: Record<string, unknown>;
+  bundleEntries?: Array<Record<string, unknown>>;
+  guestLink?: GuestLinkArtifact | null;
 }): Promise<ProtectedArtifact>;
 
 export function createRecipientKeypairHex(): Promise<{
@@ -567,6 +577,10 @@ export function validateManifestAgainstStandardsCatalog(
 
 export const SDS_BUNDLE_SECTION_NAME: string;
 export const DEFAULT_HASH_ALGORITHM: string;
+export const SDS_GUEST_LINK_OBJECT_ENTRY_ID: string;
+export const SDS_GUEST_LINK_METADATA_ENTRY_ID: string;
+export const SDS_GUEST_LINK_SECTION_NAME: string;
+export const SDS_GUEST_LINK_MEDIA_TYPE: string;
 
 export function createSingleFileBundle(options: {
   wasmBytes: Uint8Array;