space-data-module-sdk 0.8.4 → 0.8.5

package/src/transport/pki.js

@@ -1,13 +1,14 @@
 import { canonicalBytes } from "../auth/canonicalize.js";
+import * as flatbuffers from "flatbuffers";
+import { KMF, keyMaterialAlgorithm, keyMaterialEncoding, keyMaterialRole } from "spacedatastandards.org/lib/js/KMF/main.js";
 import {
   base64ToBytes,
   bytesToBase64,
+  bytesToHex,
   hexToBytes,
   toUint8Array,
 } from "../utils/encoding.js";
 import {
-  aesCtrDecrypt,
-  aesCtrEncrypt,
   aesGcmDecrypt,
   aesGcmEncrypt,
   hkdfBytes,
@@ -19,10 +20,36 @@ import {
   appendPublicationRecordCollection,
   createEncryptedEnvelopePayload,
   decodeEncRecord,
+  encodeEncRecord,
   encodePublicationRecordCollection,
   extractPublicationRecordCollection,
 } from "./records.js";
 
+const GCM_TAG_LENGTH = 16;
+
+// The authenticated payload layout is ciphertext || 16-byte GCM tag. The ENC
+// FlatBuffer schema has no dedicated tag field, so the tag travels appended to
+// the ciphertext, mirroring the packed layout already used by the legacy
+// salt-based envelope format.
+function splitGcmPayload(payloadBytes) {
+  const payload = toUint8Array(payloadBytes);
+  if (payload.length < GCM_TAG_LENGTH) {
+    throw new Error("AES-256-GCM protected payload is truncated.");
+  }
+  return {
+    ciphertext: payload.subarray(0, payload.length - GCM_TAG_LENGTH),
+    tag: payload.subarray(payload.length - GCM_TAG_LENGTH),
+  };
+}
+
+function assertGcmEncRecord(enc) {
+  if (enc?.symmetric !== "AES_256_GCM") {
+    throw new Error(
+      `Unsupported ENC symmetric algorithm "${enc?.symmetric}"; only AES_256_GCM is supported.`,
+    );
+  }
+}
+
 function normalizePublicKey(value) {
   if (typeof value === "string") {
     return hexToBytes(value);
@@ -53,6 +80,130 @@ async function deriveAesKey(sharedSecret, salt, context) {
   );
 }
 
+function normalizeOptionalBytes(value) {
+  if (value === null || value === undefined) {
+    return new Uint8Array(0);
+  }
+  if (typeof value === "string") {
+    return hexToBytes(value);
+  }
+  return toUint8Array(value);
+}
+
+function normalizeRequiredString(value, name) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new Error(`${name} is required.`);
+  }
+  return normalized;
+}
+
+function normalizeArtifactBinding(artifact = {}) {
+  const listingId = normalizeRequiredString(artifact.listingId, "artifact.listingId");
+  const moduleId = normalizeRequiredString(artifact.moduleId, "artifact.moduleId");
+  const version = normalizeRequiredString(artifact.version, "artifact.version");
+  const encryptedCid = normalizeRequiredString(
+    artifact.encryptedCid,
+    "artifact.encryptedCid",
+  );
+  const providerId = normalizeRequiredString(artifact.providerId, "artifact.providerId");
+  const policyId = normalizeRequiredString(artifact.policyId, "artifact.policyId");
+  const keyEpoch = normalizeRequiredString(artifact.keyEpoch, "artifact.keyEpoch");
+  const contentKeyId =
+    String(artifact.contentKeyId ?? "").trim() ||
+    `${listingId}:${moduleId}:${version}:${keyEpoch}`;
+  const encryptedHash = normalizeOptionalBytes(artifact.encryptedHash);
+  if (encryptedHash.length !== 32) {
+    throw new Error("artifact.encryptedHash must be 32 bytes.");
+  }
+  const manifestHash = normalizeOptionalBytes(artifact.manifestHash);
+  if (manifestHash.length !== 32) {
+    throw new Error("artifact.manifestHash must be 32 bytes.");
+  }
+  return {
+    listingId,
+    moduleId,
+    version,
+    encryptedCid,
+    encryptedHash: bytesToHex(encryptedHash),
+    providerId,
+    policyId,
+    keyEpoch,
+    manifestHash: bytesToHex(manifestHash),
+    contentKeyId,
+  };
+}
+
+export function createMarketplaceContentAad(artifact = {}) {
+  const binding = normalizeArtifactBinding(artifact);
+  return canonicalBytes({
+    encryptedCid: binding.encryptedCid,
+    encryptedHash: binding.encryptedHash,
+    keyEpoch: binding.keyEpoch,
+    listingId: binding.listingId,
+    manifestHash: binding.manifestHash,
+    moduleId: binding.moduleId,
+    policyId: binding.policyId,
+    providerId: binding.providerId,
+    version: binding.version,
+  });
+}
+
+function createWrapAad({ artifact, recipient, algorithm }) {
+  return canonicalBytes({
+    algorithm,
+    contentKeyId: artifact.contentKeyId,
+    encryptedCid: artifact.encryptedCid,
+    expiresAtMs: Number(recipient.expiresAtMs ?? 0),
+    grantId: normalizeRequiredString(recipient.grantId, "recipient.grantId"),
+    keyEpoch: artifact.keyEpoch,
+    providerId: artifact.providerId,
+    recipientKeyId: normalizeRequiredString(
+      recipient.recipientKeyId,
+      "recipient.recipientKeyId",
+    ),
+    scope: normalizeRequiredString(recipient.scope, "recipient.scope"),
+  });
+}
+
+function encodeContentKeyMaterial({ keyId, keyBytes, expiresAtMs }) {
+  const builder = new flatbuffers.Builder(256);
+  const keyIdOffset = builder.createString(keyId);
+  const keyBytesOffset = KMF.createKeyBytesVector(builder, keyBytes);
+  const root = KMF.createKMF(
+    builder,
+    keyIdOffset,
+    keyMaterialRole.PublicationContent,
+    keyMaterialAlgorithm.Aes256Gcm,
+    keyMaterialEncoding.RawBytes,
+    keyBytesOffset,
+    1,
+    BigInt(Number(expiresAtMs ?? 0)),
+  );
+  KMF.finishKMFBuffer(builder, root);
+  return builder.asUint8Array();
+}
+
+function decodeContentKeyMaterial(bytes) {
+  const payload = toUint8Array(bytes);
+  const bb = new flatbuffers.ByteBuffer(payload);
+  if (!KMF.bufferHasIdentifier(bb)) {
+    throw new Error("Wrapped marketplace content key payload is not a KMF record.");
+  }
+  const kmf = KMF.getRootAsKMF(bb);
+  if (kmf.ROLE() !== keyMaterialRole.PublicationContent) {
+    throw new Error("Wrapped marketplace key material is not a publication content key.");
+  }
+  if (kmf.ALGORITHM() !== keyMaterialAlgorithm.Aes256Gcm) {
+    throw new Error("Wrapped marketplace key material is not an AES-256-GCM key.");
+  }
+  const keyBytes = kmf.keyBytesArray();
+  if (!keyBytes || keyBytes.length !== 32) {
+    throw new Error("Wrapped marketplace content key must be 32 bytes.");
+  }
+  return new Uint8Array(keyBytes);
+}
+
 export async function generateX25519Keypair() {
   const privateKey = await randomBytes(32);
   const publicKey = await x25519PublicKey(privateKey);
@@ -62,6 +213,121 @@ export async function generateX25519Keypair() {
   };
 }
 
+export async function protectMarketplaceContent({
+  plaintext,
+  artifact,
+  recipients = [],
+  contentKey = null,
+  contentNonce = null,
+  providerWrapKeyPair = null,
+  wrapNonce = null,
+} = {}) {
+  if (!Array.isArray(recipients) || recipients.length === 0) {
+    throw new Error("protectMarketplaceContent requires at least one recipient.");
+  }
+  const binding = normalizeArtifactBinding(artifact);
+  const keyBytes = contentKey ? toUint8Array(contentKey) : await randomBytes(32);
+  if (keyBytes.length !== 32) {
+    throw new Error("Marketplace content keys must be 32 bytes.");
+  }
+  const nonce = contentNonce ? toUint8Array(contentNonce) : await randomBytes(12);
+  if (nonce.length !== 12) {
+    throw new Error("AES-256-GCM content encryption requires a 12-byte nonce.");
+  }
+  const aad = createMarketplaceContentAad(binding);
+  const encrypted = await aesGcmEncrypt(
+    keyBytes,
+    toUint8Array(plaintext),
+    nonce,
+    aad,
+  );
+  const wrappedKeys = [];
+  for (const recipient of recipients) {
+    const sender = providerWrapKeyPair ?? (await generateX25519Keypair());
+    const recipientPublicKey = normalizePublicKey(recipient.publicKey);
+    const wrapIv = wrapNonce ? toUint8Array(wrapNonce) : await randomBytes(12);
+    if (wrapIv.length !== 12) {
+      throw new Error("AES-256-GCM key wrapping requires a 12-byte nonce.");
+    }
+    const wrapAad = createWrapAad({
+      artifact: binding,
+      recipient,
+      algorithm: "X25519-HKDF-SHA256-AES-256-GCM-KMF",
+    });
+    const sharedSecret = await deriveSharedSecret(
+      sender.privateKey,
+      recipientPublicKey,
+    );
+    const wrapContext = `marketplace-content-key:${binding.providerId}:${binding.contentKeyId}:${recipient.recipientKeyId}`;
+    const wrapKey = await deriveAesKey(sharedSecret, new Uint8Array(0), wrapContext);
+    const keyMaterial = encodeContentKeyMaterial({
+      keyId: binding.contentKeyId,
+      keyBytes,
+      expiresAtMs: recipient.expiresAtMs,
+    });
+    const wrapped = await aesGcmEncrypt(wrapKey, keyMaterial, wrapIv, wrapAad);
+    wrappedKeys.push({
+      algorithm: "X25519-HKDF-SHA256-AES-256-GCM-KMF",
+      contentKeyId: binding.contentKeyId,
+      recipientPeerId: normalizeRequiredString(
+        recipient.recipientPeerId,
+        "recipient.recipientPeerId",
+      ),
+      recipientKeyId: normalizeRequiredString(
+        recipient.recipientKeyId,
+        "recipient.recipientKeyId",
+      ),
+      providerId: binding.providerId,
+      encryptedCid: binding.encryptedCid,
+      grantId: normalizeRequiredString(recipient.grantId, "recipient.grantId"),
+      scope: normalizeRequiredString(recipient.scope, "recipient.scope"),
+      expiresAtMs: Number(recipient.expiresAtMs ?? 0),
+      providerEphemeralPublicKey: sender.publicKey,
+      nonce: wrapIv,
+      aad: wrapAad,
+      ciphertext: wrapped.ciphertext,
+      tag: wrapped.tag,
+    });
+  }
+  return {
+    algorithm: "AES-256-GCM",
+    contentKeyId: binding.contentKeyId,
+    artifact: binding,
+    aad,
+    encryptedPayload: {
+      algorithm: "AES-256-GCM",
+      nonce,
+      aad,
+      ciphertext: encrypted.ciphertext,
+      tag: encrypted.tag,
+    },
+    wrappedKeys,
+  };
+}
+
+export async function decryptMarketplaceContentKeyWrap({
+  wrap,
+  recipientPrivateKey,
+} = {}) {
+  if (!wrap) {
+    throw new Error("decryptMarketplaceContentKeyWrap requires wrap.");
+  }
+  const sharedSecret = await deriveSharedSecret(
+    recipientPrivateKey,
+    wrap.providerEphemeralPublicKey,
+  );
+  const wrapContext = `marketplace-content-key:${wrap.providerId}:${wrap.contentKeyId}:${wrap.recipientKeyId}`;
+  const wrapKey = await deriveAesKey(sharedSecret, new Uint8Array(0), wrapContext);
+  const keyMaterial = await aesGcmDecrypt(
+    wrapKey,
+    wrap.ciphertext,
+    wrap.tag,
+    wrap.nonce,
+    wrap.aad,
+  );
+  return decodeContentKeyMaterial(keyMaterial);
+}
+
 async function encryptBytesLegacy({
   plaintext,
   recipientPublicKey,
@@ -103,6 +369,7 @@ export async function decryptProtectedBytes({
   if (!parsed?.enc) {
     return toUint8Array(protectedBytes);
   }
+  assertGcmEncRecord(parsed.enc);
   const sharedSecret = await deriveSharedSecret(
     recipientPrivateKey,
     parsed.enc.ephemeralPublicKey,
@@ -112,7 +379,14 @@ export async function decryptProtectedBytes({
     new Uint8Array(0),
     parsed.enc.context ?? "",
   );
-  return aesCtrDecrypt(aesKey, parsed.payloadBytes, parsed.enc.nonceStart);
+  const { ciphertext, tag } = splitGcmPayload(parsed.payloadBytes);
+  return aesGcmDecrypt(
+    aesKey,
+    ciphertext,
+    tag,
+    parsed.enc.nonceStart,
+    encodeEncRecord(parsed.enc),
+  );
 }
 
 export async function encryptBytesForRecipient({
@@ -134,11 +408,10 @@ export async function encryptBytesForRecipient({
     recipientPublicKey,
   );
   const aesKey = await deriveAesKey(sharedSecret, new Uint8Array(0), context);
-  const ciphertext = await aesCtrEncrypt(aesKey, toUint8Array(plaintext), nonceStart);
   const enc = {
     version: 1,
     keyExchange: "X25519",
-    symmetric: "AES_256_CTR",
+    symmetric: "AES_256_GCM",
     keyDerivation: "HKDF_SHA256",
     ephemeralPublicKey: sender.publicKey,
     nonceStart,
@@ -148,15 +421,29 @@ export async function encryptBytesForRecipient({
     rootType,
     timestamp: Date.now(),
   };
+  // The encoded ENC record doubles as the GCM AAD so every delivery parameter
+  // (context, schema hash, root type, recipient key id, nonce, ephemeral key)
+  // is authenticated alongside the ciphertext. encodeEncRecord() is
+  // deterministic for a normalized record, so decrypt paths recompute the
+  // identical bytes from the parsed ENC record.
+  const { ciphertext, tag } = await aesGcmEncrypt(
+    aesKey,
+    toUint8Array(plaintext),
+    nonceStart,
+    encodeEncRecord(enc),
+  );
+  const payloadBytes = new Uint8Array(ciphertext.length + tag.length);
+  payloadBytes.set(ciphertext, 0);
+  payloadBytes.set(tag, ciphertext.length);
   const recordCollectionBytes = encodePublicationRecordCollection({ enc });
   const protectedBlobBytes = appendPublicationRecordCollection(
-    ciphertext,
+    payloadBytes,
     recordCollectionBytes,
   );
   return createEncryptedEnvelopePayload({
     protectedBlobBytes,
     parsedProtectedBlob: {
-      payloadBytes: ciphertext,
+      payloadBytes,
       recordCollectionBytes,
       enc,
       pnm: null,
@@ -182,7 +469,9 @@ export async function decryptBytesFromEnvelope({
     });
   }
   if (envelope.ciphertextBase64 && envelope.encRecordBase64) {
-    const enc = decodeEncRecord(base64ToBytes(envelope.encRecordBase64));
+    const encRecordBytes = base64ToBytes(envelope.encRecordBase64);
+    const enc = decodeEncRecord(encRecordBytes);
+    assertGcmEncRecord(enc);
     const sharedSecret = await deriveSharedSecret(
       recipientPrivateKey,
       enc.ephemeralPublicKey,
@@ -192,11 +481,10 @@ export async function decryptBytesFromEnvelope({
       new Uint8Array(0),
       enc.context ?? envelope.context ?? "",
     );
-    return aesCtrDecrypt(
-      aesKey,
+    const { ciphertext, tag } = splitGcmPayload(
       base64ToBytes(envelope.ciphertextBase64),
-      enc.nonceStart,
     );
+    return aesGcmDecrypt(aesKey, ciphertext, tag, enc.nonceStart, encRecordBytes);
   }
   const sharedSecret = await deriveSharedSecret(
     recipientPrivateKey,

package/src/transport/records.js

@@ -40,8 +40,14 @@ const KEY_EXCHANGE_NAME_BY_VALUE = Object.freeze(
     Object.entries(KEY_EXCHANGE_BY_NAME).map(([name, value]) => [value, name]),
   ),
 );
+// AES_256_GCM is not yet published in the spacedatastandards.org generated
+// SymmetricAlgo enum (which only defines AES_256_CTR = 0). The SYMMETRIC field
+// is a plain byte on the wire, so value 1 is encoded directly until the schema
+// publishes the enum member.
+const SYMMETRIC_ALGO_AES_256_GCM = 1;
 const SYMMETRIC_ALGO_BY_NAME = Object.freeze({
   AES_256_CTR: SymmetricAlgo.AES_256_CTR,
+  AES_256_GCM: SYMMETRIC_ALGO_AES_256_GCM,
 });
 const SYMMETRIC_ALGO_NAME_BY_VALUE = Object.freeze(
   Object.fromEntries(
@@ -429,12 +435,15 @@ function normalizeSymmetricAlgorithm(value) {
   if (typeof value === "number") {
     return value;
   }
-  return SYMMETRIC_ALGO_BY_NAME[
-    String(value ?? "AES_256_CTR")
-      .trim()
-      .replace(/[^A-Za-z0-9]+/g, "_")
-      .toUpperCase()
-  ] ?? SymmetricAlgo.AES_256_CTR;
+  const normalized = String(value ?? "AES_256_GCM")
+    .trim()
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .toUpperCase();
+  const resolved = SYMMETRIC_ALGO_BY_NAME[normalized];
+  if (resolved === undefined) {
+    throw new Error(`Unsupported ENC symmetric algorithm "${value}".`);
+  }
+  return resolved;
 }
 
 function normalizeKdf(value) {
@@ -834,7 +843,7 @@ export function createEncryptedEnvelopePayload(options = {}) {
   const envelope = {
     version: Number(options.version ?? 2),
     scheme:
-      normalizeStringField(options.scheme) ?? "x25519-hkdf-aes-256-ctr-rec",
+      normalizeStringField(options.scheme) ?? "x25519-hkdf-aes-256-gcm-rec",
     context: normalizeStringField(options.context ?? enc?.context) ?? "",
     protectedBlobBase64: bytesToBase64(protectedBlob),
     recordCollectionBase64: parsed

package/src/utils/ecdsaDer.js

@@ -0,0 +1,106 @@
+/**
+ * DER <-> raw conversion for secp256k1 ECDSA signatures.
+ *
+ * The shared WASM crypto backend (hd-wallet-wasm) produces and consumes
+ * raw 64-byte (r || s) signatures. EPM SIGNATURE bytes, however, are
+ * ECDSA-DER encoded (SEQUENCE { INTEGER r, INTEGER s }). These helpers
+ * bridge the two encodings so the host-crypto ABI can honor the DER
+ * contract while calling the raw-signature WASM primitives.
+ */
+
+import { toUint8Array } from "./encoding.js";
+
+const RAW_SIGNATURE_LENGTH = 64;
+const COMPONENT_LENGTH = 32;
+
+function encodeDerInteger(component) {
+  // Strip superfluous leading zero bytes, keeping at least one byte.
+  let start = 0;
+  while (start < component.length - 1 && component[start] === 0) {
+    start += 1;
+  }
+  let value = component.subarray(start);
+  // DER integers are signed; prepend 0x00 when the high bit is set so the
+  // value is not interpreted as negative.
+  if ((value[0] & 0x80) !== 0) {
+    const padded = new Uint8Array(value.length + 1);
+    padded.set(value, 1);
+    value = padded;
+  }
+  const encoded = new Uint8Array(value.length + 2);
+  encoded[0] = 0x02; // INTEGER
+  encoded[1] = value.length;
+  encoded.set(value, 2);
+  return encoded;
+}
+
+/**
+ * Encode a raw 64-byte (r || s) secp256k1 ECDSA signature as DER.
+ */
+export function rawSignatureToDer(rawSignature) {
+  const bytes = toUint8Array(rawSignature);
+  if (bytes.length !== RAW_SIGNATURE_LENGTH) {
+    throw new Error(
+      `secp256k1 raw signature must be ${RAW_SIGNATURE_LENGTH} bytes, received ${bytes.length}.`,
+    );
+  }
+  const r = encodeDerInteger(bytes.subarray(0, COMPONENT_LENGTH));
+  const s = encodeDerInteger(bytes.subarray(COMPONENT_LENGTH, RAW_SIGNATURE_LENGTH));
+  const body = new Uint8Array(r.length + s.length);
+  body.set(r, 0);
+  body.set(s, r.length);
+  // Signature bodies never exceed 127 bytes, so short-form length is safe.
+  const der = new Uint8Array(body.length + 2);
+  der[0] = 0x30; // SEQUENCE
+  der[1] = body.length;
+  der.set(body, 2);
+  return der;
+}
+
+function normalizeComponent(component) {
+  let start = 0;
+  while (start < component.length - 1 && component[start] === 0) {
+    start += 1;
+  }
+  const value = component.subarray(start);
+  if (value.length > COMPONENT_LENGTH) {
+    throw new Error("Invalid DER signature: integer component exceeds 32 bytes.");
+  }
+  const out = new Uint8Array(COMPONENT_LENGTH);
+  out.set(value, COMPONENT_LENGTH - value.length);
+  return out;
+}
+
+function readDerInteger(bytes, offset) {
+  if (bytes[offset] !== 0x02) {
+    throw new Error("Invalid DER signature: expected INTEGER.");
+  }
+  const length = bytes[offset + 1];
+  const start = offset + 2;
+  const end = start + length;
+  if (end > bytes.length) {
+    throw new Error("Invalid DER signature: INTEGER length exceeds bounds.");
+  }
+  return { value: bytes.subarray(start, end), next: end };
+}
+
+/**
+ * Decode a DER-encoded secp256k1 ECDSA signature into raw 64-byte (r || s).
+ */
+export function derSignatureToRaw(derSignature) {
+  const bytes = toUint8Array(derSignature);
+  if (bytes.length < 8 || bytes[0] !== 0x30) {
+    throw new Error("Invalid DER signature: expected SEQUENCE.");
+  }
+  let offset = 2;
+  if ((bytes[1] & 0x80) !== 0) {
+    // Long-form length; skip the length-of-length bytes.
+    offset = 2 + (bytes[1] & 0x7f);
+  }
+  const rPart = readDerInteger(bytes, offset);
+  const sPart = readDerInteger(bytes, rPart.next);
+  const raw = new Uint8Array(RAW_SIGNATURE_LENGTH);
+  raw.set(normalizeComponent(rPart.value), 0);
+  raw.set(normalizeComponent(sPart.value), COMPONENT_LENGTH);
+  return raw;
+}

package/src/utils/wasmCrypto.js

@@ -116,46 +116,3 @@ export async function aesGcmDecrypt(key, ciphertext, tag, iv, aad = null) {
     aad ? toUint8Array(aad) : undefined,
   );
 }
-
-function normalizeCtrIv(nonceStart) {
-  const nonce = toUint8Array(nonceStart);
-  if (nonce.length !== 12) {
-    throw new Error("AES-256-CTR expects a 12-byte NONCE_START value.");
-  }
-  const iv = new Uint8Array(16);
-  iv.set(nonce, 0);
-  return iv;
-}
-
-async function getAesCtrApi() {
-  const wallet = await getWasmWallet();
-  const aesCtr = wallet?.aesCtr;
-  if (
-    !aesCtr ||
-    typeof aesCtr.encrypt !== "function" ||
-    typeof aesCtr.decrypt !== "function"
-  ) {
-    throw new Error(
-      "hd-wallet-wasm aesCtr API is unavailable; cannot process ENC payloads.",
-    );
-  }
-  return aesCtr;
-}
-
-export async function aesCtrEncrypt(key, plaintext, nonceStart) {
-  const aesCtr = await getAesCtrApi();
-  return aesCtr.encrypt(
-    toUint8Array(key),
-    toUint8Array(plaintext),
-    normalizeCtrIv(nonceStart),
-  );
-}
-
-export async function aesCtrDecrypt(key, ciphertext, nonceStart) {
-  const aesCtr = await getAesCtrApi();
-  return aesCtr.decrypt(
-    toUint8Array(key),
-    toUint8Array(ciphertext),
-    normalizeCtrIv(nonceStart),
-  );
-}

package/templates/gpu-module/README.md

@@ -0,0 +1,48 @@
+# GPU Module Template
+
+This template is the SDK starting point for modules that can use WebGPU in the
+browser and Dawn in a native WasmEdge host while keeping a portable CPU
+fallback.
+
+## Files
+
+- `include/space_data_gpu_abi.h`: shared C/C++ layout ABI for GPU-capable
+  module code and host adapters.
+- `manifest.json`: starter manifest showing the `gpu_compute` capability.
+
+## Runtime Shape
+
+Keep the canonical module artifact at:
+
+```text
+dist/isomorphic/module.wasm
+```
+
+That artifact must run without GPU access. Put optional GPU adapters beside it:
+
+```text
+dist/browser/module.js
+dist/wasmedge/gpu-host.{so,dylib,dll}
+```
+
+The browser adapter owns WebGPU. The WasmEdge host extension owns Dawn. The
+module owns correctness, fallback, and final result validation.
+
+## C++ Integration
+
+Include the ABI header from module or host code:
+
+```cpp
+#include "space_data_gpu_abi.h"
+```
+
+Use `SdnGpuSplitF64` for double-like values that must cross into WGSL as two
+`f32` values:
+
+```cpp
+SdnGpuVec3SplitF64 position = sdn_gpu_split_vec3_f64(x_km, y_km, z_km);
+```
+
+Use the dispatch/result descriptor structs for host adapter boundaries. Do not
+store raw pointers in manifests, publication metadata, or durable runtime
+records.