space-data-module-sdk 0.3.1 → 0.5.3

package/src/compliance/index.js

@@ -4,12 +4,14 @@ import {
   getWasmExportNamesFromFile,
   loadManifestFromFile,
   loadComplianceConfig,
-  RecommendedCapabilityIds,
-  StandaloneWasiCapabilityIds,
   resolveManifestFiles,
   validatePluginArtifact,
   validatePluginManifest,
 } from "./pluginCompliance.js";
+import {
+  RecommendedCapabilityIds,
+  StandaloneWasiCapabilityIds,
+} from "../capabilities.js";
 import { validateManifestAgainstStandardsCatalog } from "../standards/index.js";
 
 function mergeReport(baseReport, issues) {

package/src/compliance/pluginCompliance.js

@@ -12,53 +12,10 @@ import {
   ProtocolTransportKind,
   RuntimeTarget,
 } from "../runtime/constants.js";
-
-export const RecommendedCapabilityIds = Object.freeze([
-  "clock",
-  "random",
-  "logging",
-  "timers",
-  "schedule_cron",
-  "http",
-  "tls",
-  "websocket",
-  "mqtt",
-  "tcp",
-  "udp",
-  "network",
-  "filesystem",
-  "pipe",
-  "pubsub",
-  "protocol_handle",
-  "protocol_dial",
-  "database",
-  "storage_adapter",
-  "storage_query",
-  "storage_write",
-  "context_read",
-  "context_write",
-  "process_exec",
-  "crypto_hash",
-  "crypto_sign",
-  "crypto_verify",
-  "crypto_encrypt",
-  "crypto_decrypt",
-  "crypto_key_agreement",
-  "crypto_kdf",
-  "wallet_sign",
-  "ipfs",
-  "scene_access",
-  "entity_access",
-  "render_hooks",
-]);
-
-export const StandaloneWasiCapabilityIds = Object.freeze([
-  "logging",
-  "clock",
-  "random",
-  "filesystem",
-  "pipe",
-]);
+import {
+  RecommendedCapabilityIds,
+  StandaloneWasiCapabilityIds,
+} from "../capabilities.js";
 
 const RecommendedCapabilitySet = new Set(RecommendedCapabilityIds);
 const StandaloneWasiCapabilitySet = new Set(StandaloneWasiCapabilityIds);

package/src/index.d.ts

@@ -380,14 +380,69 @@ export interface X25519Keypair {
   privateKey: Uint8Array;
 }
 
+export interface EncRecord {
+  version: number;
+  keyExchange: string;
+  symmetric: string;
+  keyDerivation: string;
+  ephemeralPublicKey: Uint8Array | null;
+  nonceStart: Uint8Array | null;
+  recipientKeyId: Uint8Array | null;
+  context: string | null;
+  schemaHash: Uint8Array | null;
+  rootType: string | null;
+  timestamp: number;
+}
+
+export interface PublicationNotice {
+  multiformatAddress: string | null;
+  publishTimestamp: string | null;
+  cid: string | null;
+  fileName: string | null;
+  fileId: string | null;
+  signature: string | null;
+  timestampSignature: string | null;
+  signatureType: string | null;
+  timestampSignatureType: string | null;
+}
+
+export interface PublicationRecordEntry {
+  standard: string | null;
+  recordType: number;
+  value: EncRecord | PublicationNotice | unknown;
+}
+
+export interface PublicationRecordCollection {
+  version: string;
+  records: PublicationRecordEntry[];
+  enc: EncRecord | null;
+  pnm: PublicationNotice | null;
+  recordCollectionBytes: Uint8Array;
+}
+
+export interface ExtractedPublicationRecordCollection
+  extends PublicationRecordCollection {
+  payloadBytes: Uint8Array;
+  protectedBytes: Uint8Array;
+  footerBytes: Uint8Array;
+  footerMagic: string;
+  recordCollectionLength: number;
+}
+
 export interface EncryptedEnvelope {
   version: number;
   scheme: string;
   context: string;
-  senderPublicKeyBase64: string;
-  saltBase64: string;
-  ivBase64: string;
-  ciphertextBase64: string;
+  protectedBlobBase64?: string | null;
+  recordCollectionBase64?: string | null;
+  ciphertextBase64?: string | null;
+  senderPublicKeyBase64?: string | null;
+  nonceStartBase64?: string | null;
+  recipientKeyIdBase64?: string | null;
+  encRecordBase64?: string | null;
+  pnmRecordBase64?: string | null;
+  saltBase64?: string | null;
+  ivBase64?: string | null;
 }
 
 export function generateX25519Keypair(): Promise<X25519Keypair>;
@@ -397,8 +452,16 @@ export function encryptBytesForRecipient(options: {
   recipientPublicKey: Uint8Array | string;
   context?: string;
   senderKeyPair?: X25519Keypair;
+  recipientKeyId?: Uint8Array | ArrayBuffer | string | null;
+  schemaHash?: Uint8Array | ArrayBuffer | string | null;
+  rootType?: string | null;
 }): Promise<EncryptedEnvelope>;
 
+export function decryptProtectedBytes(options: {
+  protectedBytes: Uint8Array | ArrayBuffer;
+  recipientPrivateKey: Uint8Array | string;
+}): Promise<Uint8Array>;
+
 export function decryptBytesFromEnvelope(options: {
   envelope: EncryptedEnvelope;
   recipientPrivateKey: Uint8Array | string;
@@ -416,6 +479,78 @@ export function decryptJsonFromEnvelope(options: {
   recipientPrivateKey: Uint8Array | string;
 }): Promise<unknown>;
 
+export function decryptPublicationRecordCollection(options: {
+  protectedBytes: Uint8Array | ArrayBuffer;
+  recipientPrivateKey: Uint8Array | string;
+}): Promise<{
+  payloadBytes: Uint8Array;
+  decryptedBytes: Uint8Array;
+  publication: ExtractedPublicationRecordCollection | null;
+}>;
+
+export const TRAILER_MAGIC_TEXT: string;
+export const TRAILER_FOOTER_LENGTH: number;
+
+export function createCidV1Raw(
+  payloadBytes: Uint8Array | ArrayBuffer,
+): Promise<string>;
+
+export function encodeEncRecord(record?: Partial<EncRecord>): Uint8Array;
+export function decodeEncRecord(
+  bytes: Uint8Array | ArrayBuffer | ArrayBufferView,
+): EncRecord;
+export function encodePnmRecord(
+  record?: Partial<PublicationNotice>,
+): Uint8Array;
+export function decodePnmRecord(
+  bytes: Uint8Array | ArrayBuffer | ArrayBufferView,
+): PublicationNotice;
+export function encodePublicationRecordCollection(options: {
+  version?: string;
+  enc?: Partial<EncRecord> | null;
+  pnm?: Partial<PublicationNotice> | null;
+}): Uint8Array;
+export function decodePublicationRecordCollection(
+  bytes: Uint8Array | ArrayBuffer | ArrayBufferView,
+): PublicationRecordCollection;
+export function appendPublicationRecordCollection(
+  payloadBytes: Uint8Array | ArrayBuffer,
+  recordCollectionBytes: Uint8Array | ArrayBuffer,
+): Uint8Array;
+export function extractPublicationRecordCollection(
+  bytes: Uint8Array | ArrayBuffer | ArrayBufferView,
+): ExtractedPublicationRecordCollection | null;
+export function stripPublicationRecordCollection(
+  bytes: Uint8Array | ArrayBuffer | ArrayBufferView,
+): Uint8Array;
+export function createPublicationNotice(options: {
+  payloadBytes: Uint8Array | ArrayBuffer;
+  cid?: string | null;
+  publishTimestamp?: string | null;
+  publishTimestampMs?: number;
+  fileName?: string | null;
+  fileId?: string | null;
+  artifactId?: string | null;
+  programId?: string | null;
+  multiformatAddress?: string | null;
+  signature?: string | null;
+  timestampSignature?: string | null;
+  signatureType?: string | null;
+  timestampSignatureType?: string | null;
+  signer?: Signer | null;
+}): Promise<PublicationNotice>;
+export function createEncryptedEnvelopePayload(options: {
+  protectedBlobBytes: Uint8Array | ArrayBuffer;
+  parsedProtectedBlob?: ExtractedPublicationRecordCollection | null;
+  enc?: EncRecord | null;
+  context?: string | null;
+  scheme?: string | null;
+  version?: number;
+}): EncryptedEnvelope;
+export function decodeProtectedBlobBase64(
+  base64: string,
+): ExtractedPublicationRecordCollection | null;
+
 // --- Compiler ---
 
 export interface CompilationResult {
@@ -424,10 +559,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;
@@ -444,6 +588,10 @@ export interface ProtectedArtifact {
     manifestHashHex: string;
     authorization: SignedEnvelope;
   };
+  publicationNotice: PublicationNotice | null;
+  publicationRecordsBytes: Uint8Array | null;
+  protectedArtifactBytes: Uint8Array;
+  protectedArtifactBase64: string;
   encrypted: boolean;
   encryptedEnvelope: EncryptedEnvelope | null;
   singleFileBundle: { wasmBytes: Uint8Array } | null;
@@ -473,7 +621,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 +716,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;
@@ -577,9 +730,24 @@ export function createSingleFileBundle(options: {
   entries?: Array<Record<string, unknown>>;
 }): Promise<{ wasmBytes: Uint8Array }>;
 
+export interface ParsedSingleFileBundle {
+  wasmBytes: Uint8Array;
+  protectedArtifactBytes: Uint8Array | null;
+  publicationRecords: ExtractedPublicationRecordCollection | null;
+  bundleBytes: Uint8Array;
+  bundle: unknown;
+  entries: Array<Record<string, unknown>>;
+  manifest: PluginManifest | null;
+  deploymentPlan: ModuleDeploymentPlan | null;
+  customSections: Array<Record<string, unknown>>;
+  canonicalWasmBytes: Uint8Array;
+  canonicalModuleHash: Uint8Array;
+  canonicalModuleHashHex: string;
+}
+
 export function parseSingleFileBundle(
   wasmBytes: Uint8Array,
-): unknown;
+): Promise<ParsedSingleFileBundle>;
 
 export function parseWasmModuleSections(
   bytes: Uint8Array,

package/src/index.js

@@ -4,6 +4,7 @@ export * from "./auth/index.js";
 export * from "./transport/index.js";
 export * from "./compiler/index.js";
 export * from "./bundle/index.js";
+export * from "./capabilities.js";
 export * from "./standards/index.js";
 export * from "./host/index.js";
 export * from "./invoke/index.js";

package/src/manifest/browser.js

@@ -0,0 +1,15 @@
+export * from "../generated/orbpro/manifest.js";
+export { PayloadWireFormat } from "../generated/orbpro/stream/payload-wire-format.js";
+export {
+  FlatBufferTypeRefT,
+  FlatBufferTypeRefT as PayloadTypeRef,
+} from "../generated/orbpro/stream/flat-buffer-type-ref.js";
+export { decodePluginManifest, encodePluginManifest } from "./codec.js";
+export { toEmbeddedPluginManifest } from "./normalize.js";
+export {
+  clonePayloadTypeRef,
+  getPayloadTypeWireFormat,
+  normalizePayloadWireFormatName,
+  payloadTypeRefsMatch,
+  selectPreferredPayloadTypeRef,
+} from "./typeRefs.js";

package/src/transport/index.js

@@ -1,4 +1,6 @@
 export {
+  decryptProtectedBytes,
+  decryptPublicationRecordCollection,
   decryptBytesFromEnvelope,
   decryptJsonFromEnvelope,
   encryptBytesForRecipient,
@@ -6,3 +8,20 @@ export {
   generateX25519Keypair,
 } from "./pki.js";
 
+export {
+  appendPublicationRecordCollection,
+  createCidV1Raw,
+  createEncryptedEnvelopePayload,
+  createPublicationNotice,
+  decodeEncRecord,
+  decodePnmRecord,
+  decodeProtectedBlobBase64,
+  decodePublicationRecordCollection,
+  encodeEncRecord,
+  encodePnmRecord,
+  encodePublicationRecordCollection,
+  extractPublicationRecordCollection,
+  stripPublicationRecordCollection,
+  TRAILER_FOOTER_LENGTH,
+  TRAILER_MAGIC_TEXT,
+} from "./records.js";

package/src/transport/pki.js

@@ -6,6 +6,8 @@ import {
   toUint8Array,
 } from "../utils/encoding.js";
 import {
+  aesCtrDecrypt,
+  aesCtrEncrypt,
   aesGcmDecrypt,
   aesGcmEncrypt,
   hkdfBytes,
@@ -13,6 +15,13 @@ import {
   x25519PublicKey,
   x25519SharedSecret,
 } from "../utils/wasmCrypto.js";
+import {
+  appendPublicationRecordCollection,
+  createEncryptedEnvelopePayload,
+  decodeEncRecord,
+  encodePublicationRecordCollection,
+  extractPublicationRecordCollection,
+} from "./records.js";
 
 function normalizePublicKey(value) {
   if (typeof value === "string") {
@@ -53,15 +62,12 @@ export async function generateX25519Keypair() {
   };
 }
 
-export async function encryptBytesForRecipient({
+async function encryptBytesLegacy({
   plaintext,
   recipientPublicKey,
   context = "space-data-module-sdk/package",
   senderKeyPair = null,
 } = {}) {
-  if (!recipientPublicKey) {
-    throw new Error("encryptBytesForRecipient requires recipientPublicKey.");
-  }
   const sender = senderKeyPair ?? (await generateX25519Keypair());
   const salt = await randomBytes(32);
   const iv = await randomBytes(12);
@@ -89,6 +95,77 @@ export async function encryptBytesForRecipient({
   };
 }
 
+export async function decryptProtectedBytes({
+  protectedBytes,
+  recipientPrivateKey,
+} = {}) {
+  const parsed = extractPublicationRecordCollection(protectedBytes);
+  if (!parsed?.enc) {
+    return toUint8Array(protectedBytes);
+  }
+  const sharedSecret = await deriveSharedSecret(
+    recipientPrivateKey,
+    parsed.enc.ephemeralPublicKey,
+  );
+  const aesKey = await deriveAesKey(
+    sharedSecret,
+    new Uint8Array(0),
+    parsed.enc.context ?? "",
+  );
+  return aesCtrDecrypt(aesKey, parsed.payloadBytes, parsed.enc.nonceStart);
+}
+
+export async function encryptBytesForRecipient({
+  plaintext,
+  recipientPublicKey,
+  context = "space-data-module-sdk/package",
+  senderKeyPair = null,
+  recipientKeyId = null,
+  schemaHash = null,
+  rootType = null,
+} = {}) {
+  if (!recipientPublicKey) {
+    throw new Error("encryptBytesForRecipient requires recipientPublicKey.");
+  }
+  const sender = senderKeyPair ?? (await generateX25519Keypair());
+  const nonceStart = await randomBytes(12);
+  const sharedSecret = await deriveSharedSecret(
+    sender.privateKey,
+    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",
+    keyDerivation: "HKDF_SHA256",
+    ephemeralPublicKey: sender.publicKey,
+    nonceStart,
+    recipientKeyId,
+    context,
+    schemaHash,
+    rootType,
+    timestamp: Date.now(),
+  };
+  const recordCollectionBytes = encodePublicationRecordCollection({ enc });
+  const protectedBlobBytes = appendPublicationRecordCollection(
+    ciphertext,
+    recordCollectionBytes,
+  );
+  return createEncryptedEnvelopePayload({
+    protectedBlobBytes,
+    parsedProtectedBlob: {
+      payloadBytes: ciphertext,
+      recordCollectionBytes,
+      enc,
+      pnm: null,
+    },
+    enc,
+    context,
+  });
+}
+
 export async function decryptBytesFromEnvelope({
   envelope,
   recipientPrivateKey,
@@ -98,6 +175,29 @@ export async function decryptBytesFromEnvelope({
       "decryptBytesFromEnvelope requires envelope and recipientPrivateKey.",
     );
   }
+  if (envelope.protectedBlobBase64) {
+    return decryptProtectedBytes({
+      protectedBytes: base64ToBytes(envelope.protectedBlobBase64),
+      recipientPrivateKey,
+    });
+  }
+  if (envelope.ciphertextBase64 && envelope.encRecordBase64) {
+    const enc = decodeEncRecord(base64ToBytes(envelope.encRecordBase64));
+    const sharedSecret = await deriveSharedSecret(
+      recipientPrivateKey,
+      enc.ephemeralPublicKey,
+    );
+    const aesKey = await deriveAesKey(
+      sharedSecret,
+      new Uint8Array(0),
+      enc.context ?? envelope.context ?? "",
+    );
+    return aesCtrDecrypt(
+      aesKey,
+      base64ToBytes(envelope.ciphertextBase64),
+      enc.nonceStart,
+    );
+  }
   const sharedSecret = await deriveSharedSecret(
     recipientPrivateKey,
     base64ToBytes(envelope.senderPublicKeyBase64),
@@ -133,3 +233,24 @@ export async function decryptJsonFromEnvelope(options = {}) {
   return JSON.parse(new TextDecoder().decode(bytes));
 }
 
+export async function decryptPublicationRecordCollection({
+  protectedBytes,
+  recipientPrivateKey,
+} = {}) {
+  const parsed = extractPublicationRecordCollection(protectedBytes);
+  if (!parsed) {
+    return {
+      payloadBytes: toUint8Array(protectedBytes),
+      decryptedBytes: toUint8Array(protectedBytes),
+      publication: null,
+    };
+  }
+  const decryptedBytes = parsed.enc
+    ? await decryptProtectedBytes({ protectedBytes, recipientPrivateKey })
+    : parsed.payloadBytes;
+  return {
+    payloadBytes: parsed.payloadBytes,
+    decryptedBytes,
+    publication: parsed,
+  };
+}