space-data-module-sdk 0.1.0

package/src/auth/index.js

@@ -0,0 +1,10 @@
+export { canonicalBytes, hashCanonicalValue, stableStringify } from "./canonicalize.js";
+export {
+  assertDeploymentAuthorization,
+  createDeploymentAuthorization,
+  createHdWalletSigner,
+  createHdWalletVerifier,
+  signAuthorization,
+  verifyAuthorization,
+} from "./permissions.js";
+

package/src/auth/permissions.js

@@ -0,0 +1,190 @@
+import { canonicalBytes } from "./canonicalize.js";
+import { bytesToHex, hexToBytes, toUint8Array } from "../utils/encoding.js";
+import { randomBytes, sha256Bytes } from "../utils/crypto.js";
+
+function normalizeCapabilityList(capabilities) {
+  if (!Array.isArray(capabilities)) {
+    return [];
+  }
+  return capabilities
+    .map((capability) => String(capability ?? "").trim())
+    .filter(Boolean);
+}
+
+function normalizeTarget(target = null) {
+  if (typeof target === "string") {
+    return {
+      kind: "remote",
+      id: null,
+      audience: null,
+      url: target,
+    };
+  }
+  return {
+    kind: target?.kind ?? "remote",
+    id: target?.id ?? target?.targetId ?? null,
+    audience: target?.audience ?? null,
+    url: target?.url ?? null,
+  };
+}
+
+export async function createDeploymentAuthorization(options = {}) {
+  const issuedAt = Number(options.issuedAt ?? Date.now());
+  const ttlMs = Number(options.ttlMs ?? 5 * 60 * 1000);
+  const artifact = options.artifact ?? {};
+  const target = normalizeTarget(options.target);
+
+  return {
+    version: 1,
+    action: "deploy-flow",
+    artifactId: String(artifact.artifactId ?? options.artifactId ?? "").trim(),
+    programId: String(artifact.programId ?? options.programId ?? "").trim(),
+    graphHash: artifact.graphHash ?? options.graphHash ?? null,
+    manifestHash: artifact.manifestHash ?? options.manifestHash ?? null,
+    target,
+    capabilities: normalizeCapabilityList(
+      options.capabilities ?? artifact.requiredCapabilities ?? [],
+    ),
+    issuedAt,
+    expiresAt: issuedAt + ttlMs,
+    nonce: options.nonce ?? bytesToHex(await randomBytes(16)),
+    constraints: options.constraints ?? null,
+  };
+}
+
+export function createHdWalletSigner(options = {}) {
+  if (typeof options.signDigest !== "function") {
+    throw new Error("createHdWalletSigner requires signDigest.");
+  }
+  const publicKeyHex = String(options.publicKeyHex ?? "").trim();
+  if (!publicKeyHex) {
+    throw new Error("createHdWalletSigner requires publicKeyHex.");
+  }
+  return {
+    algorithm: options.algorithm ?? "secp256k1-sha256",
+    curve: options.curve ?? "secp256k1",
+    publicKeyHex,
+    derivationPath: options.derivationPath ?? null,
+    keyId: options.keyId ?? null,
+    async sign(bytes) {
+      const digest = await sha256Bytes(bytes);
+      return toUint8Array(await options.signDigest(digest));
+    },
+  };
+}
+
+export function createHdWalletVerifier(options = {}) {
+  if (typeof options.verifyDigest !== "function") {
+    throw new Error("createHdWalletVerifier requires verifyDigest.");
+  }
+  return {
+    async verify(bytes, signature, header, payload) {
+      const digest = await sha256Bytes(bytes);
+      return options.verifyDigest(digest, signature, header, payload);
+    },
+  };
+}
+
+export async function signAuthorization({ authorization, signer }) {
+  if (!signer || typeof signer.sign !== "function") {
+    throw new Error("signAuthorization requires a signer.");
+  }
+  const payload = authorization ?? {};
+  const payloadBytes = canonicalBytes(payload);
+  const signature = await signer.sign(payloadBytes);
+  return {
+    protected: {
+      algorithm: signer.algorithm ?? "unknown",
+      curve: signer.curve ?? null,
+      publicKeyHex: signer.publicKeyHex ?? null,
+      derivationPath: signer.derivationPath ?? null,
+      keyId: signer.keyId ?? null,
+    },
+    payload,
+    signatureHex: bytesToHex(signature),
+  };
+}
+
+export async function verifyAuthorization({
+  envelope,
+  verifier,
+  now = Date.now(),
+}) {
+  if (!verifier || typeof verifier.verify !== "function") {
+    throw new Error("verifyAuthorization requires a verifier.");
+  }
+  if (!envelope?.payload || !envelope?.signatureHex) {
+    return false;
+  }
+  if (
+    typeof envelope.payload.expiresAt === "number" &&
+    envelope.payload.expiresAt < now
+  ) {
+    return false;
+  }
+  const payloadBytes = canonicalBytes(envelope.payload);
+  return verifier.verify(
+    payloadBytes,
+    hexToBytes(envelope.signatureHex),
+    envelope.protected ?? {},
+    envelope.payload,
+  );
+}
+
+export function assertDeploymentAuthorization({
+  envelope,
+  artifact,
+  target,
+  requiredCapabilities = [],
+  now = Date.now(),
+}) {
+  const payload = envelope?.payload;
+  if (!payload) {
+    throw new Error("Deployment authorization envelope is missing payload.");
+  }
+  if (payload.action !== "deploy-flow") {
+    throw new Error(`Unexpected authorization action "${payload.action}".`);
+  }
+  if (typeof payload.expiresAt === "number" && payload.expiresAt < now) {
+    throw new Error("Deployment authorization has expired.");
+  }
+  if (artifact?.artifactId && payload.artifactId !== artifact.artifactId) {
+    throw new Error("Deployment authorization artifactId mismatch.");
+  }
+  if (artifact?.programId && payload.programId !== artifact.programId) {
+    throw new Error("Deployment authorization programId mismatch.");
+  }
+  if (artifact?.graphHash && payload.graphHash !== artifact.graphHash) {
+    throw new Error("Deployment authorization graphHash mismatch.");
+  }
+  if (artifact?.manifestHash && payload.manifestHash !== artifact.manifestHash) {
+    throw new Error("Deployment authorization manifestHash mismatch.");
+  }
+
+  const normalizedTarget = normalizeTarget(target);
+  if (
+    normalizedTarget.id &&
+    payload.target?.id &&
+    normalizedTarget.id !== payload.target.id
+  ) {
+    throw new Error("Deployment authorization target id mismatch.");
+  }
+  if (
+    normalizedTarget.audience &&
+    payload.target?.audience &&
+    normalizedTarget.audience !== payload.target.audience
+  ) {
+    throw new Error("Deployment authorization target audience mismatch.");
+  }
+
+  const granted = new Set(normalizeCapabilityList(payload.capabilities));
+  for (const capability of normalizeCapabilityList(requiredCapabilities)) {
+    if (!granted.has(capability)) {
+      throw new Error(
+        `Deployment authorization missing capability "${capability}".`,
+      );
+    }
+  }
+  return true;
+}
+

package/src/compiler/compileModule.js

@@ -0,0 +1,237 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+
+import {
+  createDeploymentAuthorization,
+  createHdWalletSigner,
+  signAuthorization,
+} from "../auth/index.js";
+import { validateArtifactWithStandards } from "../compliance/index.js";
+import { generateEmbeddedManifestSource } from "../embeddedManifest.js";
+import { encodePluginManifest, toEmbeddedPluginManifest } from "../manifest/index.js";
+import {
+  encryptJsonForRecipient,
+  generateX25519Keypair,
+} from "../transport/index.js";
+import {
+  base64ToBytes,
+  bytesToBase64,
+  bytesToHex,
+  hexToBytes,
+} from "../utils/encoding.js";
+import { sha256Bytes } from "../utils/crypto.js";
+import { getWasmWallet } from "../utils/wasmCrypto.js";
+
+const execFile = promisify(execFileCallback);
+const C_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function selectCompiler(language) {
+  const normalized = String(language ?? "c").trim().toLowerCase();
+  if (normalized === "c++" || normalized === "cpp" || normalized === "cxx") {
+    return { command: "em++", extension: "cpp", language: "c++" };
+  }
+  return { command: "emcc", extension: "c", language: "c" };
+}
+
+function ensureExportableMethodIds(manifest) {
+  const invalidMethod = (Array.isArray(manifest?.methods) ? manifest.methods : []).find(
+    (method) => !C_IDENTIFIER.test(String(method?.methodId ?? "")),
+  );
+  if (invalidMethod) {
+    throw new Error(
+      `Method id "${invalidMethod.methodId}" is not a valid C export name. ` +
+        "Source compilation requires methodId values to be valid C identifiers.",
+    );
+  }
+}
+
+export async function compileModuleFromSource(options = {}) {
+  const manifest = options.manifest ?? {};
+  const sourceCode = String(options.sourceCode ?? "");
+  if (!sourceCode.trim()) {
+    throw new Error("compileModuleFromSource requires sourceCode.");
+  }
+
+  ensureExportableMethodIds(manifest);
+
+  const validation = await validateArtifactWithStandards({ manifest });
+  if (!validation.ok) {
+    const error = new Error("Manifest validation failed.");
+    error.report = validation;
+    throw error;
+  }
+
+  const compiler = selectCompiler(options.language);
+  const { manifest: embeddedManifest, warnings } = toEmbeddedPluginManifest(
+    manifest,
+  );
+  const tempDir = await mkdtemp(
+    path.join(os.tmpdir(), "space-data-module-sdk-compile-"),
+  );
+  const sourcePath = path.join(tempDir, `module.${compiler.extension}`);
+  const manifestSourcePath = path.join(tempDir, "plugin-manifest-exports.c");
+  const outputPath = path.resolve(options.outputPath ?? path.join(tempDir, "module.wasm"));
+
+  await writeFile(sourcePath, sourceCode, "utf8");
+  await writeFile(
+    manifestSourcePath,
+    generateEmbeddedManifestSource({ manifest: embeddedManifest }),
+    "utf8",
+  );
+
+  const exportedSymbols = [
+    "plugin_get_manifest_flatbuffer",
+    "plugin_get_manifest_flatbuffer_size",
+    ...new Set(
+      (Array.isArray(manifest.methods) ? manifest.methods : [])
+        .map((method) => String(method?.methodId ?? "").trim())
+        .filter(Boolean),
+    ),
+  ];
+  const linkerExports = exportedSymbols.flatMap((symbol) => [
+    "-Wl,--export=" + symbol,
+  ]);
+
+  try {
+    await execFile(compiler.command, [
+      sourcePath,
+      manifestSourcePath,
+      "-O2",
+      "--no-entry",
+      "-s",
+      "STANDALONE_WASM=1",
+      ...linkerExports,
+      "-o",
+      outputPath,
+    ]);
+  } catch (error) {
+    error.message =
+      `Compilation failed with ${compiler.command}: ` +
+      (error.stderr || error.message);
+    throw error;
+  }
+
+  const wasmBytes = await readFile(outputPath);
+  const report = await validateArtifactWithStandards({
+    manifest,
+    wasmPath: outputPath,
+  });
+
+  return {
+    compiler: compiler.command,
+    language: compiler.language,
+    outputPath,
+    tempDir,
+    wasmBytes,
+    manifestWarnings: warnings,
+    report,
+  };
+}
+
+export async function cleanupCompilation(result) {
+  if (result?.tempDir) {
+    await rm(result.tempDir, { recursive: true, force: true });
+  }
+}
+
+async function deriveSigningIdentity(mnemonic) {
+  const wallet = await getWasmWallet();
+  const resolvedMnemonic =
+    mnemonic && wallet.mnemonic.validate(mnemonic)
+      ? mnemonic
+      : wallet.mnemonic.generate(12);
+  const seed = wallet.mnemonic.toSeed(resolvedMnemonic);
+  const root = wallet.hdkey.fromSeed(seed);
+  const signingKey = wallet.getSigningKey(root, 0, 0, 0);
+  return {
+    wallet,
+    mnemonic: resolvedMnemonic,
+    signingKey,
+  };
+}
+
+export async function protectModuleArtifact(options = {}) {
+  const manifest = options.manifest ?? {};
+  const wasmBytes =
+    options.wasmBytes instanceof Uint8Array
+      ? options.wasmBytes
+      : base64ToBytes(options.wasmBase64 ?? "");
+  if (wasmBytes.length === 0) {
+    throw new Error("protectModuleArtifact requires wasmBytes or wasmBase64.");
+  }
+
+  const manifestBytes = encodePluginManifest(manifest);
+  const wasmHashHex = bytesToHex(await sha256Bytes(wasmBytes));
+  const manifestHashHex = bytesToHex(await sha256Bytes(manifestBytes));
+  const artifactId = options.artifactId ?? `module-${wasmHashHex.slice(0, 16)}`;
+  const programId = manifest.pluginId ?? artifactId;
+
+  const identity = await deriveSigningIdentity(options.mnemonic ?? null);
+  const signer = createHdWalletSigner({
+    publicKeyHex: bytesToHex(identity.signingKey.publicKey),
+    derivationPath: identity.signingKey.path,
+    keyId: artifactId,
+    async signDigest(digest) {
+      return identity.wallet.curves.secp256k1.sign(
+        digest,
+        identity.signingKey.privateKey,
+      );
+    },
+  });
+
+  const authorization = await createDeploymentAuthorization({
+    artifactId,
+    programId,
+    manifestHash: manifestHashHex,
+    graphHash: wasmHashHex,
+    target: options.targetUrl ?? options.target ?? null,
+    capabilities: options.capabilities ?? [],
+  });
+  const signedAuthorization = await signAuthorization({
+    authorization,
+    signer,
+  });
+
+  const payload = {
+    version: 1,
+    format: "space-data-module-package",
+    artifactId,
+    programId,
+    manifest,
+    manifestBase64: bytesToBase64(manifestBytes),
+    wasmBase64: bytesToBase64(wasmBytes),
+    wasmHashHex,
+    manifestHashHex,
+    authorization: signedAuthorization,
+  };
+
+  let encryptedEnvelope = null;
+  if (options.recipientPublicKeyHex) {
+    encryptedEnvelope = await encryptJsonForRecipient({
+      payload,
+      recipientPublicKey: hexToBytes(options.recipientPublicKeyHex),
+      context: "space-data-module-sdk/package",
+    });
+  }
+
+  return {
+    mnemonic: identity.mnemonic,
+    signingPublicKeyHex: bytesToHex(identity.signingKey.publicKey),
+    signingPath: identity.signingKey.path,
+    payload,
+    encrypted: Boolean(encryptedEnvelope),
+    encryptedEnvelope,
+  };
+}
+
+export async function createRecipientKeypairHex() {
+  const keypair = await generateX25519Keypair();
+  return {
+    publicKeyHex: bytesToHex(keypair.publicKey),
+    privateKeyHex: bytesToHex(keypair.privateKey),
+  };
+}
+

package/src/compiler/index.js

@@ -0,0 +1,7 @@
+export {
+  cleanupCompilation,
+  compileModuleFromSource,
+  createRecipientKeypairHex,
+  protectModuleArtifact,
+} from "./compileModule.js";
+

package/src/compliance/index.js

@@ -0,0 +1,56 @@
+import {
+  findManifestFiles,
+  getWasmExportNames,
+  getWasmExportNamesFromFile,
+  loadManifestFromFile,
+  loadComplianceConfig,
+  RecommendedCapabilityIds,
+  resolveManifestFiles,
+  validatePluginArtifact,
+  validatePluginManifest,
+} from "./pluginCompliance.js";
+import { validateManifestAgainstStandardsCatalog } from "../standards/index.js";
+
+function mergeReport(baseReport, issues) {
+  const mergedIssues = [...baseReport.issues, ...issues];
+  const errors = mergedIssues.filter((issue) => issue.severity === "error");
+  const warnings = mergedIssues.filter((issue) => issue.severity === "warning");
+  return {
+    ...baseReport,
+    ok: errors.length === 0,
+    issues: mergedIssues,
+    errors,
+    warnings,
+  };
+}
+
+export async function validateManifestWithStandards(manifest, options = {}) {
+  const baseReport = validatePluginManifest(manifest, options);
+  const standards = await validateManifestAgainstStandardsCatalog(
+    manifest,
+    options,
+  );
+  return mergeReport(baseReport, standards.issues);
+}
+
+export async function validateArtifactWithStandards(options = {}) {
+  const baseReport = await validatePluginArtifact(options);
+  const standards = await validateManifestAgainstStandardsCatalog(
+    options.manifest,
+    { sourceName: baseReport.sourceName },
+  );
+  return mergeReport(baseReport, standards.issues);
+}
+
+export {
+  findManifestFiles,
+  getWasmExportNames,
+  getWasmExportNamesFromFile,
+  loadManifestFromFile,
+  loadComplianceConfig,
+  RecommendedCapabilityIds,
+  resolveManifestFiles,
+  validatePluginArtifact,
+  validatePluginManifest,
+};
+