space-data-module-sdk 0.8.4 → 0.8.5

package/src/invoke/index.js

@@ -1,9 +1,13 @@
-export * from "../generated/orbpro/invoke.js";
 export {
+  INVOKE_ARENA_ALIGNMENT,
+  assertAlignedInvokeBuffer,
+  createInvokeArenaLease,
   decodePluginInvokeRequest,
   decodePluginInvokeResponse,
   encodePluginInvokeRequest,
   encodePluginInvokeResponse,
+  forwardOutputFrameAsInput,
   normalizeInvokeSurfaceName,
   normalizeInvokeSurfaces,
+  writePluginInvokeRequestToArena,
 } from "./codec.js";

package/src/licensing/index.d.ts

@@ -3,11 +3,13 @@ export {
   decodeLicensingChallengeMessage,
   decodeLicensingGrant,
   decodeLicensingProofMessage,
+  encodeUnsignedLicensingGrantForProviderSignature,
   encodeLicensingChallengeRequest,
   encodeLicensingProof,
   extractGrantModuleDescriptor,
   extractWrappedContentKey,
   validateLicensingGrant,
+  verifyLicensingGrantProviderSignature,
 } from "../index.js";
 
 export type {

package/src/licensing/index.js

@@ -3,9 +3,11 @@ export {
   decodeLicensingChallengeMessage,
   decodeLicensingGrant,
   decodeLicensingProofMessage,
+  encodeUnsignedLicensingGrantForProviderSignature,
   encodeLicensingChallengeRequest,
   encodeLicensingProof,
   extractGrantModuleDescriptor,
   extractWrappedContentKey,
   validateLicensingGrant,
+  verifyLicensingGrantProviderSignature,
 } from "./records.js";

package/src/licensing/records.js

@@ -17,6 +17,8 @@ import {
 } from "spacedatastandards.org/lib/js/LGR/main.js";
 import { LPF, licensingProofMessageType } from "spacedatastandards.org/lib/js/LPF/main.js";
 
+const PROVIDER_SIGNATURE_LENGTH = 64;
+
 export class LicensingProtocolError extends Error {
   constructor(code, message) {
     super(message);
@@ -77,6 +79,7 @@ export function encodeLicensingChallengeRequest(options) {
     providerPeerIdOffset,
     0,
     0,
+    0,
   );
   LCH.finishLCHBuffer(builder, root);
   return builder.asUint8Array();
@@ -437,6 +440,82 @@ export function validateLicensingGrant(grant, options = {}) {
   return grant;
 }
 
+export function encodeUnsignedLicensingGrantForProviderSignature(grant) {
+  if (!grant || typeof grant !== "object") {
+    throw new TypeError("grant is required");
+  }
+
+  const rawBytes = cloneOptionalBytes(grant.rawBytes);
+  if (rawBytes.length > 0) {
+    const root = LGR.getRootAsLGR(new flatbuffers.ByteBuffer(rawBytes));
+    if (root.MESSAGE_TYPE() !== licensingGrantMessageType.Granted) {
+      throw new LicensingProtocolError(
+        "invalid_grant",
+        "expected granted licensing record",
+      );
+    }
+    return encodeUnsignedGrantFromRawRoot(root, rawBytes);
+  }
+
+  return encodeUnsignedGrantFromDecodedMessage(grant);
+}
+
+export async function verifyLicensingGrantProviderSignature(grant, options = {}) {
+  const providerSignature = cloneOptionalBytes(grant?.providerSignature);
+  if (providerSignature.length !== PROVIDER_SIGNATURE_LENGTH) {
+    throw new LicensingProtocolError(
+      "invalid_grant",
+      `licensing grant provider signature must be ${PROVIDER_SIGNATURE_LENGTH} bytes`,
+    );
+  }
+  if (providerSignature.every((byte) => byte === 0)) {
+    throw new LicensingProtocolError(
+      "invalid_grant",
+      "licensing grant provider signature must not be all zeroes",
+    );
+  }
+  if (
+    Number.isFinite(options.requestedAtMs) &&
+    grant.expiresAtMs > 0 &&
+    grant.expiresAtMs <= options.requestedAtMs
+  ) {
+    throw new LicensingProtocolError(
+      "grant_expired",
+      "licensing grant has expired",
+    );
+  }
+  const status = trimOptional(grant.grantStatus)?.toLowerCase();
+  if (status === "revoked") {
+    throw new LicensingProtocolError(
+      "grant_revoked",
+      "licensing grant has been revoked",
+    );
+  }
+  if (status && status !== "active" && status !== "granted") {
+    throw new LicensingProtocolError(
+      "grant_status_invalid",
+      `licensing grant status is not active: ${status}`,
+    );
+  }
+
+  if (typeof options.verify !== "function") {
+    throw new TypeError("verifyLicensingGrantProviderSignature requires verify.");
+  }
+  const unsignedGrant = encodeUnsignedLicensingGrantForProviderSignature(grant);
+  const signatureValid = await options.verify(
+    cloneOptionalBytes(grant.grantVerifierPublicKey),
+    unsignedGrant,
+    providerSignature,
+  );
+  if (!signatureValid) {
+    throw new LicensingProtocolError(
+      "invalid_grant_signature",
+      "licensing grant provider signature verification failed",
+    );
+  }
+  return grant;
+}
+
 export function extractGrantModuleDescriptor(grant) {
   if (!grant?.moduleDescriptor) {
     throw new LicensingProtocolError(
@@ -447,6 +526,153 @@ export function extractGrantModuleDescriptor(grant) {
   return grant.moduleDescriptor;
 }
 
+function encodeUnsignedGrantFromRawRoot(root, rawBytes) {
+  const providerSignature = root.providerSignatureArray();
+  if (!providerSignature || providerSignature.length !== PROVIDER_SIGNATURE_LENGTH) {
+    throw new LicensingProtocolError(
+      "invalid_grant",
+      `licensing grant provider signature must be ${PROVIDER_SIGNATURE_LENGTH} bytes`,
+    );
+  }
+
+  const signingBytes = cloneBytes(rawBytes);
+  const signingRoot = LGR.getRootAsLGR(new flatbuffers.ByteBuffer(signingBytes));
+  signingRoot.providerSignatureArray().fill(0);
+  return signingBytes;
+}
+
+function encodeUnsignedGrantFromDecodedMessage(grant) {
+  const builder = new flatbuffers.Builder(2048);
+  const requestIdOffset = builder.createString(grant.reqId || "");
+  const moduleIdOffset = builder.createString(grant.moduleId || "");
+  const moduleVersionOffset = createOptionalString(builder, grant.moduleVersion);
+  const requesterPeerIdOffset = createOptionalString(builder, grant.requesterPeerId);
+  const requesterXpubOffset = createOptionalString(builder, grant.requesterXpub);
+  const requestedDomainOffset = createOptionalString(builder, grant.requestedDomain);
+  const grantedDomainOffset = createOptionalString(builder, grant.grantedDomain);
+  const requiredScopeOffset = createOptionalString(builder, grant.requiredScope);
+  const grantStatusOffset = createOptionalString(builder, grant.grantStatus);
+  const denialReasonOffset = createOptionalString(builder, grant.denialReason);
+  const capabilityTokenOffset = createOptionalVector(
+    builder,
+    LGR.createCapabilityTokenVector,
+    grant.capabilityToken,
+  );
+  const moduleDescriptorOffset = grant.moduleDescriptor
+    ? encodeDecodedModuleDescriptor(builder, grant.moduleDescriptor)
+    : 0;
+  const wrappedHeaderOffset = grant.wrappedContentKey?.header
+    ? encodeDecodedWrappedHeader(builder, grant.wrappedContentKey.header)
+    : 0;
+  const wrappedPayloadOffset = createOptionalVector(
+    builder,
+    LGR.createWrappedContentKeyPayloadVector,
+    grant.wrappedContentKey?.encryptedPayload,
+  );
+  const verifierPubkeyOffset = createOptionalVector(
+    builder,
+    LGR.createGrantVerifierPubkeyVector,
+    grant.grantVerifierPublicKey,
+  );
+  const providerSignatureOffset = LGR.createProviderSignatureVector(
+    builder,
+    new Uint8Array(PROVIDER_SIGNATURE_LENGTH),
+  );
+
+  LGR.startLGR(builder);
+  LGR.addMessageType(builder, licensingGrantMessageType.Granted);
+  LGR.addRequestId(builder, requestIdOffset);
+  LGR.addModuleId(builder, moduleIdOffset);
+  if (moduleVersionOffset !== 0) LGR.addModuleVersion(builder, moduleVersionOffset);
+  if (requesterPeerIdOffset !== 0) LGR.addRequesterPeerId(builder, requesterPeerIdOffset);
+  if (requesterXpubOffset !== 0) LGR.addRequesterXpub(builder, requesterXpubOffset);
+  if (requestedDomainOffset !== 0) LGR.addRequestedDomain(builder, requestedDomainOffset);
+  LGR.addRequestedTimeoutMs(builder, BigInt(grant.requestedTimeoutMs ?? 0));
+  if (grantedDomainOffset !== 0) LGR.addGrantedDomain(builder, grantedDomainOffset);
+  LGR.addGrantedTimeoutMs(builder, BigInt(grant.grantedTimeoutMs ?? 0));
+  LGR.addExpiresAt(builder, BigInt(grant.expiresAtMs ?? 0));
+  if (requiredScopeOffset !== 0) LGR.addRequiredScope(builder, requiredScopeOffset);
+  if (grantStatusOffset !== 0) LGR.addGrantStatus(builder, grantStatusOffset);
+  if (denialReasonOffset !== 0) LGR.addDenialReason(builder, denialReasonOffset);
+  if (capabilityTokenOffset !== 0) LGR.addCapabilityToken(builder, capabilityTokenOffset);
+  if (moduleDescriptorOffset !== 0) LGR.addModuleDescriptor(builder, moduleDescriptorOffset);
+  if (wrappedHeaderOffset !== 0) LGR.addWrappedContentKeyHeader(builder, wrappedHeaderOffset);
+  if (wrappedPayloadOffset !== 0) LGR.addWrappedContentKeyPayload(builder, wrappedPayloadOffset);
+  if (verifierPubkeyOffset !== 0) LGR.addGrantVerifierPubkey(builder, verifierPubkeyOffset);
+  LGR.addProviderSignature(builder, providerSignatureOffset);
+  const rootOffset = LGR.endLGR(builder);
+  LGR.finishLGRBuffer(builder, rootOffset);
+  return builder.asUint8Array();
+}
+
+function encodeDecodedModuleDescriptor(builder, descriptor) {
+  const pluginIdOffset = builder.createString(descriptor.moduleId || "");
+  const nameOffset = createOptionalString(builder, descriptor.moduleId);
+  const versionOffset = createOptionalString(builder, descriptor.moduleVersion);
+  const wasmHashOffset = createOptionalVector(builder, PLG.createWasmHashVector, descriptor.contentHash);
+  const wasmCidOffset = createOptionalString(builder, descriptor.cid);
+  const requiredScopeOffset = createOptionalString(builder, descriptor.requiredScope);
+  const keyIdOffset = createOptionalString(builder, descriptor.keyId);
+  const allowedXpubsOffset = createOptionalStringVector(
+    builder,
+    PLG.createAllowedXpubsVector,
+    descriptor.allowedXpubs ?? [],
+  );
+
+  PLG.startPLG(builder);
+  PLG.addPluginId(builder, pluginIdOffset);
+  if (nameOffset !== 0) PLG.addName(builder, nameOffset);
+  if (versionOffset !== 0) PLG.addVersion(builder, versionOffset);
+  if (wasmHashOffset !== 0) PLG.addWasmHash(builder, wasmHashOffset);
+  PLG.addWasmSize(builder, BigInt(descriptor.sizeBytes ?? 0));
+  if (wasmCidOffset !== 0) PLG.addWasmCid(builder, wasmCidOffset);
+  PLG.addEncrypted(builder, Boolean(descriptor.encrypted));
+  if (requiredScopeOffset !== 0) PLG.addRequiredScope(builder, requiredScopeOffset);
+  if (keyIdOffset !== 0) PLG.addKeyId(builder, keyIdOffset);
+  if (allowedXpubsOffset !== 0) PLG.addAllowedXpubs(builder, allowedXpubsOffset);
+  PLG.addMaxGrantTimeoutMs(builder, BigInt(descriptor.maxGrantTimeoutMs ?? 0));
+  return PLG.endPLG(builder);
+}
+
+function encodeDecodedWrappedHeader(builder, header) {
+  const ephemeralPublicKeyOffset = createOptionalVector(
+    builder,
+    ENC.createEphemeralPublicKeyVector,
+    header.ephemeralPublicKey,
+  );
+  const nonceStartOffset = createOptionalVector(
+    builder,
+    ENC.createNonceStartVector,
+    header.nonceStart,
+  );
+  const recipientKeyIdOffset = createOptionalVector(
+    builder,
+    ENC.createRecipientKeyIdVector,
+    header.recipientKeyId,
+  );
+  const contextOffset = createOptionalString(builder, header.context);
+  const schemaHashOffset = createOptionalVector(
+    builder,
+    ENC.createSchemaHashVector,
+    header.schemaHash,
+  );
+  const rootTypeOffset = createOptionalString(builder, header.rootType);
+  return ENC.createENC(
+    builder,
+    Number(header.version ?? 1),
+    normalizeKeyExchange(header.keyExchange),
+    normalizeSymmetricAlgorithm(header.symmetric),
+    normalizeKeyDerivation(header.keyDerivation),
+    ephemeralPublicKeyOffset,
+    nonceStartOffset,
+    recipientKeyIdOffset,
+    contextOffset,
+    schemaHashOffset,
+    rootTypeOffset,
+    BigInt(header.timestamp ?? 0),
+  );
+}
+
 export function extractWrappedContentKey(grant) {
   if (!grant?.wrappedContentKey) {
     throw new LicensingProtocolError(
@@ -502,7 +728,7 @@ function decodeGrantModuleDescriptor(moduleDescriptor) {
     moduleVersion: trimOptional(moduleDescriptor.VERSION()),
     requiredScope: trimOptional(moduleDescriptor.REQUIRED_SCOPE()),
     keyId: trimOptional(moduleDescriptor.KEY_ID()),
-    allowedDomains: readAllowedDomains(moduleDescriptor),
+    allowedXpubs: readAllowedXpubs(moduleDescriptor),
     maxGrantTimeoutMs: numberFromUint64(
       moduleDescriptor.MAX_GRANT_TIMEOUT_MS(),
       "moduleDescriptor.MAX_GRANT_TIMEOUT_MS",
@@ -606,6 +832,19 @@ function createOptionalString(builder, value) {
   return normalized ? builder.createString(normalized) : 0;
 }
 
+function createOptionalVector(builder, createVector, value) {
+  const bytes = cloneOptionalBytes(value);
+  return bytes.length > 0 ? createVector.call(LGR, builder, bytes) : 0;
+}
+
+function createOptionalStringVector(builder, createVector, values) {
+  const offsets = (values ?? [])
+    .map((value) => trimOptional(value))
+    .filter(Boolean)
+    .map((value) => builder.createString(value));
+  return offsets.length > 0 ? createVector.call(PLG, builder, offsets) : 0;
+}
+
 function toUint8Array(value, label) {
   if (value instanceof Uint8Array) {
     return value;
@@ -681,6 +920,46 @@ function normalizeProtocolCode(value, fallback) {
   return normalized || fallback;
 }
 
+function normalizeKeyExchange(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  switch (String(value ?? "X25519").trim().toUpperCase()) {
+    case "X25519":
+      return KeyExchange.X25519;
+    case "SECP256K1":
+      return KeyExchange.Secp256k1;
+    case "P256":
+      return KeyExchange.P256;
+    default:
+      return KeyExchange.X25519;
+  }
+}
+
+function normalizeSymmetricAlgorithm(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  switch (String(value ?? "AES_256_CTR").trim().toUpperCase()) {
+    case "AES_256_CTR":
+      return SymmetricAlgo.AES_256_CTR;
+    default:
+      return SymmetricAlgo.AES_256_CTR;
+  }
+}
+
+function normalizeKeyDerivation(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  switch (String(value ?? "HKDF_SHA256").trim().toUpperCase()) {
+    case "HKDF_SHA256":
+      return KDF.HKDF_SHA256;
+    default:
+      return KDF.HKDF_SHA256;
+  }
+}
+
 function challengeMessageTypeName(value) {
   switch (value) {
     case licensingChallengeMessageType.Request:
@@ -839,15 +1118,15 @@ function bytesToHex(bytes) {
   );
 }
 
-function readAllowedDomains(descriptor) {
-  const allowedDomains = [];
-  for (let index = 0; index < descriptor.allowedDomainsLength(); index += 1) {
-    const domain = descriptor.ALLOWED_DOMAINS(index);
-    if (domain) {
-      allowedDomains.push(domain);
+function readAllowedXpubs(descriptor) {
+  const allowedXpubs = [];
+  for (let index = 0; index < descriptor.allowedXpubsLength(); index += 1) {
+    const xpub = descriptor.ALLOWED_XPUBS(index);
+    if (xpub) {
+      allowedXpubs.push(xpub);
     }
   }
-  return allowedDomains;
+  return allowedXpubs;
 }
 
 export {

package/src/manifest/codec.js

@@ -6,12 +6,11 @@ import {
   HostCapabilityT,
   PluginFamily,
   PluginManifest,
-  PluginManifestT,
 } from "../generated/orbpro/manifest.js";
 import { normalizeInvokeSurfaceName } from "../invoke/codec.js";
 import { toUint8Array } from "../runtime/bufferLike.js";
-import { toEmbeddedPluginManifest } from "./normalize.js";
-import { decodePlgManifest, isPlgManifestBuffer } from "./plgCodec.js";
+import { legacyManifestToPlg } from "./legacyToPlg.js";
+import { decodePlgManifest, encodePlgManifest, isPlgManifestBuffer } from "./plgCodec.js";
 
 function toByteBuffer(data) {
   if (data instanceof flatbuffers.ByteBuffer) {
@@ -45,6 +44,34 @@ function normalizePluginFamilyName(value) {
   return normalizeEnumName(value, { separator: "_" });
 }
 
+function normalizePlgPluginFamilyName(value) {
+  if (typeof value === "number") {
+    switch (value) {
+      case 0:
+        return "sensor";
+      case 1:
+        return "propagator";
+      case 2:
+        return "renderer";
+      case 4:
+        return "data_source";
+      case 5:
+        return "ew";
+      case 6:
+        return "comms";
+      case 7:
+        return "physics";
+      case 8:
+        return "shader";
+      case 3:
+      default:
+        return "analysis";
+    }
+  }
+  const normalized = normalizeEnumName(value, { separator: "_" });
+  return normalized === "datasource" ? "data_source" : normalized;
+}
+
 function normalizeDrainPolicyName(value) {
   if (typeof value === "number" && typeof DrainPolicy[value] === "string") {
     return normalizeEnumName(DrainPolicy[value], { separator: "-" });
@@ -156,15 +183,42 @@ function methodFromPlgEntry(entry = {}) {
 }
 
 function normalizeDecodedPlgManifest(manifest = {}) {
-  const methods = Array.isArray(manifest.entryFunctions)
+  const methods = Array.isArray(manifest.methods) && manifest.methods.length > 0
+    ? manifest.methods.map((method) => normalizeDecodedMethod(method))
+    : Array.isArray(manifest.entryFunctions)
     ? manifest.entryFunctions.map((entry) => methodFromPlgEntry(entry)).filter(Boolean)
     : [];
+  const hostCapabilities = Array.isArray(manifest.hostCapabilities)
+    ? manifest.hostCapabilities
+    : [];
+  const capabilities = hostCapabilities.length > 0
+    ? hostCapabilities.map((entry) => {
+        if (!entry || typeof entry !== "object") {
+          return null;
+        }
+        if (entry.scope || entry.description || entry.required === false) {
+          return entry;
+        }
+        return entry.capability;
+      }).filter(Boolean)
+    : Array.isArray(manifest.capabilities)
+      ? manifest.capabilities.map((entry) => {
+          if (typeof entry === "string") {
+            return entry;
+          }
+          if (entry?.name && entry.required !== false && !entry.version) {
+            return entry.name;
+          }
+          return entry;
+        })
+      : [];
   return {
     ...manifest,
+    pluginFamily:
+      manifest.pluginFamily ?? normalizePlgPluginFamilyName(manifest.pluginType),
     methods,
-    capabilities: Array.isArray(manifest.capabilities)
-      ? manifest.capabilities
-      : [],
+    capabilities,
+    hostCapabilities,
     invokeSurfaces: Array.isArray(manifest.invokeSurfaces)
       ? manifest.invokeSurfaces
           .map((value) => normalizeInvokeSurfaceName(value))
@@ -202,11 +256,5 @@ export function decodePluginManifest(data) {
 }
 
 export function encodePluginManifest(manifest) {
-  const value =
-    manifest instanceof PluginManifestT
-      ? manifest
-      : toEmbeddedPluginManifest(manifest).manifest;
-  const builder = new flatbuffers.Builder(1024);
-  PluginManifest.finishPluginManifestBuffer(builder, value.pack(builder));
-  return builder.asUint8Array();
+  return encodePlgManifest(legacyManifestToPlg(manifest));
 }

package/src/manifest/index.js

@@ -14,9 +14,11 @@ export {
 export { legacyManifestToPlg } from "./legacyToPlg.js";
 export { toEmbeddedPluginManifest } from "./normalize.js";
 export {
+  alignedPayloadLayoutsCompatible,
   clonePayloadTypeRef,
   getPayloadTypeWireFormat,
   normalizePayloadWireFormatName,
+  payloadSchemaIdentitiesEqual,
   payloadTypeRefsMatch,
   selectPreferredPayloadTypeRef,
 } from "./typeRefs.js";