feat: support encrypted REC delivery artifacts

Author: TJKoury

AGENTS.md

@@ -79,6 +79,8 @@ Every compliant module produced here should satisfy all of the following:
 - Declared capability IDs come from this repo's vocabulary.
 - Single-file delivery appends one `REC` trailer carrying `MBL` and any
   publication metadata after the wasm payload.
+- Same-file signing or encrypted binary delivery appends an SDS `REC` trailer
+  carrying standards-backed `PNM` and optional `ENC` publication records.
 - Sync guest hostcalls use the `sdn_host` import module and the bridge in
   `src/host` for sync-safe operations only.
 - The raw `sdn_host` bridge remains fail-closed and sync-only.

README.md

@@ -410,11 +410,22 @@ 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:
+extensions. The canonical runtime module is still:
 
 - valid `.wasm`
 - optionally carrying one appended SDS `REC` trailer after the wasm bytes
 
+The same-file protected delivery layout is:
+
+```text
+protected-payload-bytes || REC-flatbuffer-bytes || uint32le(REC length) || "$REC"
+```
+
+For signed-only delivery, the protected payload bytes are the wasm bytes. For
+encrypted binary delivery, the protected payload bytes are ciphertext and the
+appended `REC` trailer carries `ENC` so a loader can decrypt them back to the
+canonical wasm before runtime startup.
+
 That trailing `REC` FlatBuffer is the standards-backed container for
 publication records:
 
@@ -435,7 +446,7 @@ The loader contract is always:
    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.
+6. Strip the trailer or decrypt the protected payload bytes.
 7. Hand the remaining raw wasm bytes to the runtime.
 
 Aligned-binary payloads are a separate invoke-ABI optimization. They do not
@@ -547,9 +558,12 @@ npx space-data-module check --manifest ./manifest.json --wasm ./dist/isomorphic/
 # Compile C/C++ source and embed the manifest
 npx space-data-module compile --manifest ./manifest.json --source ./src/module.c --out ./dist/isomorphic/module.wasm
 
-# Sign and encrypt a deployment payload
+# Sign a deployment payload and print JSON metadata
 npx space-data-module protect --manifest ./manifest.json --wasm ./dist/isomorphic/module.wasm --json
 
+# Emit an encrypted binary with an appended REC trailer
+npx space-data-module protect --manifest ./manifest.json --wasm ./dist/isomorphic/module.wasm --recipient-public-key <hex> --out ./dist/module.wasm.enc
+
 # Emit a single-file bundled wasm
 npx space-data-module protect --manifest ./manifest.json --wasm ./dist/isomorphic/module.wasm --single-file-bundle --out ./dist/module.bundle.wasm
 ```

bin/space-data-module.js

@@ -106,6 +106,7 @@ function printUsage() {
   space-data-module check --manifest ./manifest.json --wasm ./dist/module.wasm
   space-data-module compile --manifest ./manifest.json --source ./src/module.c --out ./dist/module.wasm
   space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --json
+  space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --recipient-public-key <hex> --out ./dist/module.wasm.enc
   space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --single-file-bundle --out ./dist/module.bundle.wasm
 `);
 }
@@ -213,9 +214,6 @@ async function runProtect(argv) {
   if (!options.manifestPath || !options.wasmPath) {
     throw new Error("protect requires --manifest and --wasm.");
   }
-  if (options.outputPath && options.singleFileBundle !== true) {
-    throw new Error("protect only supports --out together with --single-file-bundle.");
-  }
   const manifest = await loadManifestFromFile(options.manifestPath);
   const wasmBytes = new Uint8Array(await readFile(options.wasmPath));
   const result = await protectModuleArtifact({
@@ -225,8 +223,11 @@ async function runProtect(argv) {
     mnemonic: options.mnemonic,
     singleFileBundle: options.singleFileBundle,
   });
-  if (options.singleFileBundle && options.outputPath && result.bundledWasmBytes) {
-    await writeFile(options.outputPath, result.bundledWasmBytes);
+  if (options.outputPath) {
+    await writeFile(
+      options.outputPath,
+      result.bundledWasmBytes ?? result.protectedArtifactBytes,
+    );
   }
   if (options.json) {
     console.log(JSON.stringify(result, null, 2));
@@ -235,7 +236,8 @@ async function runProtect(argv) {
     console.log(`signingPublicKeyHex=${result.signingPublicKeyHex}`);
     console.log(`encrypted=${result.encrypted}`);
     console.log(`wasmBase64Length=${bytesToBase64(wasmBytes).length}`);
-    if (result.bundledWasmBytes) {
+    console.log(`protectedArtifactBytes=${result.protectedArtifactBytes.length}`);
+    if (options.singleFileBundle && result.bundledWasmBytes) {
       console.log(`singleFileBundle=true`);
       console.log(`bundledWasmBytes=${result.bundledWasmBytes.length}`);
     }

docs/module-publication-standard.md

@@ -13,7 +13,7 @@ language package ecosystems used around the SDK runtime surface:
 
 The goal is simple: a loader should be able to inspect a package, locate the
 module artifact, and determine whether signatures or encrypted transport
-metadata are appended as SDS publication records after the module bytes or
+metadata are appended as SDS publication records in the module delivery file or
 shipped as sidecar FlatBuffers.
 
 ## Scope
@@ -28,7 +28,8 @@ In both cases the module artifact remains the same canonical format already
 defined by this repo:
 
 - a runtime payload that is valid WebAssembly bytes once any SDS publication
-  trailer has been stripped
+  trailer has been stripped and any encrypted delivery payload has been
+  decrypted
 - embedded `PluginManifest.fbs`
 - manifest accessors
   - `plugin_get_manifest_flatbuffer`
@@ -37,16 +38,20 @@ defined by this repo:
 
 ## Core Rules
 
-1. The runtime payload before any publication trailer MUST remain valid `.wasm`.
-2. If signatures or encrypted-delivery metadata are carried in the same file,
-   they MUST be appended after the wasm bytes as an SDS `REC` trailer.
-3. `REC` trailers MUST carry standards-sourced `MBL` metadata plus `PNM` and
+1. A signed-only or unencrypted artifact payload before any publication trailer
+   MUST remain valid `.wasm`.
+2. An encrypted binary delivery file MUST be encoded as encrypted payload bytes
+   followed by an appended SDS `REC` trailer. The bytes before the trailer are
+   ciphertext and are not required to validate as wasm until decrypted.
+3. If bundle, signature, or encrypted-delivery metadata are carried in the same
+   file, they MUST be appended as an SDS `REC` trailer at the end of that file.
+4. `REC` trailers MUST carry standards-sourced `MBL` metadata plus `PNM` and
    optional `ENC` records where applicable.
-4. Single-file bundle metadata MUST be read from the appended `REC` trailer,
+5. Single-file bundle metadata MUST be read from the appended `REC` trailer,
    not from an in-wasm custom section.
-5. Sidecar FlatBuffers are allowed when a package chooses not to append those
+6. Sidecar FlatBuffers are allowed when a package chooses not to append those
    metadata payloads to the module artifact.
-6. Paths in publication metadata are package-relative, never absolute.
+7. Paths in publication metadata are package-relative, never absolute.
 
 ## Publication Record Extensions
 
@@ -76,6 +81,25 @@ The runtime-facing rule stays strict:
 `MBL`, `PNM`, and `ENC` extend publication and transport handling only. They do
 not change the canonical module ABI or manifest exports.
 
+## Protected Binary Layout
+
+The official same-file protection layout is:
+
+```text
+protected-payload-bytes || REC-flatbuffer-bytes || uint32le(REC length) || "$REC"
+```
+
+For signed-only delivery, `protected-payload-bytes` are the wasm bytes. For
+encrypted delivery, `protected-payload-bytes` are ciphertext and the appended
+`REC` MUST contain an `ENC` record with the decryption parameters. Loaders MUST
+decrypt those ciphertext bytes before attempting wasm validation, manifest
+inspection, or bundle metadata parsing.
+
+The `PNM` content identity applies to the protected payload bytes as stored in
+the file. For encrypted delivery this means the `PNM.CID` identifies the
+ciphertext payload, while the decrypted bytes remain the canonical wasm module
+that is passed to the runtime.
+
 ### `PNM` digital-signature extension
 
 `PNM` carries the publication notice for the module:
@@ -437,15 +461,16 @@ A loader consuming this standard SHOULD:
 2. read `module.path`
 3. scan the artifact from the end for an appended SDS `REC` trailer
 4. resolve `PNM` / `ENC` from that trailer before runtime startup
-5. if `ENC` is present, decrypt and strip the trailer before passing bytes to
-   WasmEdge or any other runtime
-6. inspect the stripped artifact's `REC` trailer for `MBL`
-7. resolve any `package-file` metadata through relative paths
-8. validate manifest exports and any declared integrity hashes
-
-If `module.packaging` is `sds-bundled-wasm`, loaders SHOULD treat the stripped
-wasm payload as the runtime artifact and the appended `REC` trailer as the
-single-file bundle/publication metadata container.
+5. if `ENC` is present, decrypt the protected payload bytes before passing bytes
+   to WasmEdge or any other runtime
+6. if `ENC` is absent, strip the trailer and use the remaining wasm payload
+7. inspect the parsed `REC` trailer for `MBL`
+8. resolve any `package-file` metadata through relative paths
+9. validate manifest exports and any declared integrity hashes
+
+If `module.packaging` is `sds-bundled-wasm`, loaders SHOULD treat the decrypted
+or stripped wasm payload as the runtime artifact and the appended `REC` trailer
+as the single-file bundle/publication metadata container.
 
 ## Relationship To Existing Bundle Format
 

package-lock.json

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

package.json

@@ -11,6 +11,7 @@ import {
 import { normalizeInvokeSurfaceName } from "../invoke/codec.js";
 import { toUint8Array } from "../runtime/bufferLike.js";
 import { toEmbeddedPluginManifest } from "./normalize.js";
+import { decodePlgManifest, isPlgManifestBuffer } from "./plgCodec.js";
 
 function toByteBuffer(data) {
   if (data instanceof flatbuffers.ByteBuffer) {
@@ -107,7 +108,79 @@ function normalizeDecodedMethod(method = {}) {
   };
 }
 
+function typeRefFromSchemaName(schemaName) {
+  return typeof schemaName === "string" && schemaName.length > 0
+    ? { schemaName }
+    : null;
+}
+
+function portFromSchemaName(schemaName, index, direction) {
+  const typeRef = typeRefFromSchemaName(schemaName);
+  if (!typeRef) {
+    return null;
+  }
+  return {
+    portId: `${direction}-${index + 1}`,
+    acceptedTypeSets: [
+      {
+        setId: schemaName,
+        allowedTypes: [typeRef],
+      },
+    ],
+    minStreams: 0,
+    maxStreams: 1,
+    required: false,
+  };
+}
+
+function methodFromPlgEntry(entry = {}) {
+  const methodId = entry.name;
+  if (typeof methodId !== "string" || methodId.length === 0) {
+    return null;
+  }
+  const inputPorts = Array.isArray(entry.inputSchemas)
+    ? entry.inputSchemas
+        .map((schemaName, index) => portFromSchemaName(schemaName, index, "input"))
+        .filter(Boolean)
+    : [];
+  const outputPort = portFromSchemaName(entry.outputSchema, 0, "output");
+  return {
+    methodId,
+    displayName: methodId,
+    description: entry.description,
+    inputPorts,
+    outputPorts: outputPort ? [outputPort] : [],
+    maxBatch: 1,
+    drainPolicy: "single-shot",
+  };
+}
+
+function normalizeDecodedPlgManifest(manifest = {}) {
+  const methods = Array.isArray(manifest.entryFunctions)
+    ? manifest.entryFunctions.map((entry) => methodFromPlgEntry(entry)).filter(Boolean)
+    : [];
+  return {
+    ...manifest,
+    methods,
+    capabilities: Array.isArray(manifest.capabilities)
+      ? manifest.capabilities
+      : [],
+    invokeSurfaces: Array.isArray(manifest.invokeSurfaces)
+      ? manifest.invokeSurfaces
+          .map((value) => normalizeInvokeSurfaceName(value))
+          .filter(Boolean)
+      : [],
+    runtimeTargets: Array.isArray(manifest.runtimeTargets)
+      ? manifest.runtimeTargets
+      : [],
+  };
+}
+
 export function decodePluginManifest(data) {
+  const bytes = toUint8Array(data);
+  if (bytes && isPlgManifestBuffer(bytes)) {
+    return normalizeDecodedPlgManifest(decodePlgManifest(bytes));
+  }
   const bb = toByteBuffer(data);
   if (!PluginManifest.bufferHasIdentifier(bb)) {
     throw new Error("Plugin manifest buffer identifier mismatch.");

src/manifest/codec.js

@@ -682,6 +682,14 @@ static void register_env_host_functions(
       WasmEdge_ValTypeGenI32(),
       WasmEdge_ValTypeGenI32(),
       WasmEdge_ValTypeGenI32()};
+  const WasmEdge_ValType seven_i32_params[7] = {
+      WasmEdge_ValTypeGenI32(),
+      WasmEdge_ValTypeGenI32(),
+      WasmEdge_ValTypeGenI32(),
+      WasmEdge_ValTypeGenI32(),
+      WasmEdge_ValTypeGenI32(),
+      WasmEdge_ValTypeGenI32(),
+      WasmEdge_ValTypeGenI32()};
   const WasmEdge_ValType f64_return[1] = {WasmEdge_ValTypeGenF64()};
   const WasmEdge_ValType i32_return[1] = {WasmEdge_ValTypeGenI32()};
 
@@ -735,8 +743,14 @@ static void register_env_host_functions(
       "_emscripten_receive_on_main_thread_js",
       stub_receive_on_main_thread,
       runner,
-      receive_on_main_thread_param_len == 4 ? four_i32_params : five_i32_params,
-      receive_on_main_thread_param_len == 4 ? 4 : 5,
+      receive_on_main_thread_param_len == 4
+          ? four_i32_params
+          : receive_on_main_thread_param_len == 7
+              ? seven_i32_params
+              : five_i32_params,
+      receive_on_main_thread_param_len == 4
+          ? 4
+          : receive_on_main_thread_param_len == 7 ? 7 : 5,
       f64_return,
       1);
   add_host_func(
@@ -3072,7 +3086,7 @@ int main(int argc, char **argv) {
       &runner,
       import_config.receive_on_main_thread_param_len == 4
           ? 4
-          : 5,
+          : import_config.receive_on_main_thread_param_len == 7 ? 7 : 5,
       import_config.notify_mailbox_postmessage_param_len == 3
           ? 3
           : 2);

src/testing/native/wasmedge_emscripten_pthread_runner.c

@@ -127,15 +127,26 @@ test("real sibling standalone plugin artifacts load through the browser harness"
         new Set(inspection.imports.map((entry) => entry.module)),
       ).sort();
 
-      assert.equal(inspection.profile, "standalone");
-      assert.deepEqual(importedModuleNames, ["wasi_snapshot_preview1"]);
+      assert.equal(
+        inspection.profile,
+        spec.expectedIsomorphicProfile ?? "standalone",
+      );
+      assert.deepEqual(
+        importedModuleNames,
+        spec.expectedImportModules ?? ["wasi_snapshot_preview1"],
+      );
 
       const report = await validatePluginArtifact({
         manifest,
         wasmPath: spec.standaloneArtifactPath,
       });
       assert.equal(report.ok, true, JSON.stringify(report.issues, null, 2));
 
+      if (spec.skipBrowserHarness) {
+        t.skip(spec.skipBrowserHarness);
+        return;
+      }
+
       const harness = await createBrowserModuleHarness({
         wasmSource: standaloneBytes,
         surface: "command",