@mh-gg/base 0.1.1-alpha.20260613T085325975Z

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@mh-gg/base",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Matterhorn v0.1 app, host, player pack manifest and contract helpers.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "dependencies": {
+    "@mh-gg/event": "^0.1.1-alpha.20260613T085325975Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/capabilities.cjs

@@ -0,0 +1,113 @@
+const { fail } = require("./errors.cjs");
+const { requireObject, requireString, validateCapabilities } = require("./manifest/validators.cjs");
+
+function normalizeCapabilities(...sets) {
+  const required = new Set();
+  const optional = new Set();
+  for (const set of sets) {
+    if (!set) continue;
+    const caps = set.capabilities || set;
+    for (const capability of caps.required || caps.requires || []) required.add(requireString(capability, "capability"));
+    for (const capability of caps.optional || caps.provides || []) optional.add(requireString(capability, "capability"));
+  }
+  for (const capability of required) optional.delete(capability);
+  return { required: [...required].sort(), optional: [...optional].sort() };
+}
+
+const HIGH_RISK_CAPABILITIES = new Set(["network.fetch", "storage.attachments", "media.sfu", "ai.invoke"]);
+
+function createCapabilityPrompt(input) {
+  const value = requireObject(input, "input");
+  const capabilities = normalizeCapabilities(...(value.sources || []));
+  const granted = new Set(value.granted || []);
+  const denied = new Set(value.denied || []);
+  return {
+    publisher: value.publisher,
+    required: capabilities.required.map((capability) => ({
+      capability,
+      granted: granted.has(capability),
+      denied: denied.has(capability),
+      highRisk: HIGH_RISK_CAPABILITIES.has(capability)
+    })),
+    optional: capabilities.optional.map((capability) => ({
+      capability,
+      granted: granted.has(capability),
+      denied: denied.has(capability),
+      highRisk: HIGH_RISK_CAPABILITIES.has(capability)
+    }))
+  };
+}
+
+function evaluateCapabilityGrant(prompt) {
+  const requiredDenied = (prompt.required || []).filter((item) => item.denied || !item.granted);
+  return {
+    ok: requiredDenied.length === 0,
+    deniedRequired: requiredDenied.map((item) => item.capability),
+    granted: [...(prompt.required || []), ...(prompt.optional || [])].filter((item) => item.granted && !item.denied).map((item) => item.capability).sort(),
+    declinedOptional: (prompt.optional || []).filter((item) => item.denied || !item.granted).map((item) => item.capability).sort()
+  };
+}
+
+function formatCapabilityAudit(prompt) {
+  const lines = [];
+  if (prompt.publisher) lines.push(`Publisher: ${prompt.publisher.name || prompt.publisher.id}`);
+  for (const item of prompt.required || []) lines.push(`required ${item.highRisk ? "high-risk " : ""}${item.capability}: ${item.granted && !item.denied ? "granted" : "missing"}`);
+  for (const item of prompt.optional || []) lines.push(`optional ${item.highRisk ? "high-risk " : ""}${item.capability}: ${item.granted && !item.denied ? "granted" : "declined"}`);
+  return lines.join("\n");
+}
+
+function normalizeCapabilityInput(input) {
+  if (Array.isArray(input)) return { required: input, optional: [] };
+  const value = validateCapabilities(input || { required: [] });
+  return { required: value.required || [], optional: value.optional || [] };
+}
+
+function capabilityAudit(input = {}) {
+  const requiredOptional = normalizeCapabilityInput(input.capabilities || input);
+  const available = new Set(input.available || []);
+  const required = [...requiredOptional.required];
+  const optional = [...(requiredOptional.optional || [])];
+  const missingRequired = required.filter((capability) => !available.has(capability));
+  const missingOptional = optional.filter((capability) => !available.has(capability));
+  return {
+    ok: missingRequired.length === 0,
+    required,
+    optional,
+    available: [...available],
+    missingRequired,
+    missingOptional,
+    promptLines: [
+      ...(required.length ? [`Required: ${required.join(", ")}`] : []),
+      ...(optional.length ? [`Optional: ${optional.join(", ")}`] : []),
+      ...(missingRequired.length ? [`Missing required: ${missingRequired.join(", ")}`] : [])
+    ]
+  };
+}
+
+function enforceProductionPluginPolicy(input) {
+  const value = requireObject(input, "input");
+  const production = value.production === true;
+  if (!production) return { ok: true, mode: "development" };
+  const publisherTrusted = value.publisherTrusted !== false;
+  if (!publisherTrusted) fail("Production mode rejects untrusted publishers");
+  const { validateHostPackManifest } = require("./manifest/validators.cjs");
+  const hostPack = value.hostPack ? validateHostPackManifest(value.hostPack) : undefined;
+  if (hostPack?.runtime?.sandbox === "none" && value.remote === true) fail("Production mode rejects remote host plugins without a sandbox");
+  const prompt = value.capabilityPrompt ? value.capabilityPrompt : createCapabilityPrompt({ sources: [hostPack || {}], granted: value.grantedCapabilities || [] });
+  const grant = evaluateCapabilityGrant(prompt);
+  if (!grant.ok) fail(`Production mode requires capability grants: ${grant.deniedRequired.join(", ")}`);
+  for (const plugin of value.plugins || []) {
+    if (plugin.reduce?.constructor?.name === "AsyncFunction") fail(`Plugin ${plugin.id} has an async reducer, which is not deterministic`);
+  }
+  return { ok: true, mode: "production", granted: grant.granted };
+}
+
+module.exports = {
+  HIGH_RISK_CAPABILITIES,
+  capabilityAudit,
+  createCapabilityPrompt,
+  enforceProductionPluginPolicy,
+  evaluateCapabilityGrant,
+  formatCapabilityAudit,
+  normalizeCapabilities
+};

package/src/constants.cjs

@@ -0,0 +1,15 @@
+const APP_PACK_KIND = "matterhorn.app-pack";
+const HOST_PACK_KIND = "matterhorn.host-pack";
+const PLAYER_PACK_KIND = "matterhorn.player-pack";
+const PLAYER_MODES = new Set(["external", "embedded", "native", "launcher-plugin"]);
+const HOST_SANDBOXES = new Set(["none", "process", "worker", "wasm"]);
+const PUBLISHER_TRUST = new Set(["trusted", "blocked", "review"]);
+
+module.exports = {
+  APP_PACK_KIND,
+  HOST_PACK_KIND,
+  HOST_SANDBOXES,
+  PLAYER_MODES,
+  PLAYER_PACK_KIND,
+  PUBLISHER_TRUST
+};

package/src/errors.cjs

@@ -0,0 +1,12 @@
+class MatterhornManifestError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MatterhornManifestError";
+  }
+}
+
+function fail(message) {
+  throw new MatterhornManifestError(message);
+}
+
+module.exports = { MatterhornManifestError, fail };

package/src/index.cjs

@@ -0,0 +1,13 @@
+module.exports = {
+  ...require("./constants.cjs"),
+  ...require("./errors.cjs"),
+  ...require("./capabilities.cjs"),
+  ...require("./manifest/validators.cjs"),
+  ...require("./manifest/hashing.cjs"),
+  ...require("./manifest/factory.cjs"),
+  ...require("./packs/artifacts.cjs"),
+  ...require("./packs/registry.cjs"),
+  ...require("./players/index.cjs"),
+  ...require("./plugins/graph.cjs"),
+  ...require("./trust/store.cjs")
+};

package/src/manifest/factory.cjs

@@ -0,0 +1,72 @@
+const { fail } = require("../errors.cjs");
+const { assertManifestIntegrity, manifestHash } = require("./hashing.cjs");
+const { playerSupportsApp } = require("../players/index.cjs");
+const { requireArray, requireObject, validateAppPackManifest, validateHostPackManifest, validatePlayerPackManifest } = require("./validators.cjs");
+
+function createAppPackManifest(input) {
+  return JSON.parse(JSON.stringify(validateAppPackManifest(input)));
+}
+
+function createHostPackManifest(input) {
+  return JSON.parse(JSON.stringify(validateHostPackManifest(input)));
+}
+
+function createPlayerPackManifest(input) {
+  return JSON.parse(JSON.stringify(validatePlayerPackManifest(input)));
+}
+
+function createPackBundle(input) {
+  const value = requireObject(input, "input");
+  const appPack = validateAppPackManifest(value.appPack);
+  const hostPack = validateHostPackManifest(value.hostPack);
+  const playerPacks = requireArray(value.playerPacks, "playerPacks", { nonEmpty: true }).map((player, index) => validatePlayerPackManifest(player, `playerPacks[${index}]`));
+
+  if (hostPack.appPackId !== appPack.id) fail("Host pack appPackId does not match app pack");
+  assertManifestIntegrity(hostPack, appPack.hostPack.integrity);
+
+  const refs = new Map(appPack.playerPacks.map((playerRef) => [playerRef.id, playerRef]));
+  for (const playerPack of playerPacks) {
+    const ref = refs.get(playerPack.id);
+    if (!ref) fail(`Player pack ${playerPack.id} is not referenced by app pack`);
+    assertManifestIntegrity(playerPack, ref.integrity);
+    if (!playerSupportsApp(playerPack, appPack)) fail(`Player pack ${playerPack.id} does not support app pack ${appPack.id}`);
+  }
+
+  if (hostPack.compatibility.appProtocolHash !== appPack.compatibility.appProtocolHash) {
+    fail("Host pack appProtocolHash does not match app pack");
+  }
+
+  return {
+    appPack: JSON.parse(JSON.stringify(appPack)),
+    hostPack: JSON.parse(JSON.stringify(hostPack)),
+    playerPacks: playerPacks.map((playerPack) => JSON.parse(JSON.stringify(playerPack))),
+    appPackHash: manifestHash(appPack),
+    hostPackHash: manifestHash(hostPack),
+    playerPackHashes: Object.fromEntries(playerPacks.map((playerPack) => [playerPack.id, manifestHash(playerPack)])),
+    contract: {
+      appPackId: appPack.id,
+      appPackVersion: appPack.version,
+      appPackHash: manifestHash(appPack),
+      appProtocolHash: appPack.compatibility.appProtocolHash,
+      hostPackId: hostPack.id,
+      hostPackHash: manifestHash(hostPack),
+      playerPackIds: playerPacks.map((playerPack) => playerPack.id)
+    }
+  };
+}
+
+function verifyPackBundle(input) {
+  try {
+    return { ok: true, bundle: createPackBundle(input) };
+  } catch (error) {
+    return { ok: false, error: error?.message || String(error) };
+  }
+}
+
+module.exports = {
+  createAppPackManifest,
+  createHostPackManifest,
+  createPackBundle,
+  createPlayerPackManifest,
+  verifyPackBundle
+};

package/src/manifest/hashing.cjs

@@ -0,0 +1,73 @@
+const crypto = require("node:crypto");
+const { canonicalJson, sha256Hex } = require("@mh-gg/event");
+const { fail } = require("../errors.cjs");
+const { isObject, requireHash, requireObject, requireString, validateSignatures } = require("./validators.cjs");
+
+function sha256Bytes(bytes) {
+  return `sha256-${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function hashCanonical(value) {
+  return `sha256-${sha256Hex(canonicalJson(value))}`;
+}
+
+function stripManifestSignatures(manifest) {
+  const copy = JSON.parse(JSON.stringify(manifest));
+  if (isObject(copy.trust)) delete copy.trust.signatures;
+  return copy;
+}
+
+function manifestHash(manifest) {
+  return hashCanonical(stripManifestSignatures(manifest));
+}
+
+function assertManifestIntegrity(manifest, expectedHash) {
+  const expected = requireHash(expectedHash, "expectedHash");
+  const hash = manifestHash(manifest);
+  if (hash !== expected) fail(`Manifest integrity mismatch: expected ${expected}, got ${hash}`);
+  return { ok: true, hash };
+}
+
+function signManifest(manifest, privateKey, publicKey) {
+  const signature = crypto.sign(null, Buffer.from(manifestHash(manifest)), privateKey).toString("base64url");
+  const signed = JSON.parse(JSON.stringify(manifest));
+  signed.trust = {
+    ...(isObject(signed.trust) ? signed.trust : {}),
+    signatures: [{ publicKey: requireString(publicKey, "publicKey"), signature }]
+  };
+  return signed;
+}
+
+function signaturePublicKeyAllowed(publicKey, options = {}) {
+  if (Array.isArray(options.allowedPublicKeys) && !options.allowedPublicKeys.includes(publicKey)) return false;
+  if (typeof options.isTrustedPublicKey === "function" && !options.isTrustedPublicKey(publicKey)) return false;
+  return true;
+}
+
+function verifySignedManifest(manifest, options = {}) {
+  const trust = requireObject(manifest.trust, "trust");
+  const signatures = validateSignatures(trust.signatures);
+  const hash = manifestHash(manifest);
+
+  for (const signature of signatures) {
+    if (!signaturePublicKeyAllowed(signature.publicKey, options)) continue;
+    try {
+      if (crypto.verify(null, Buffer.from(hash), signature.publicKey, Buffer.from(signature.signature, "base64url"))) {
+        return { ok: true, hash, publicKey: signature.publicKey };
+      }
+    } catch {
+      // Bad key material is treated the same as a bad signature.
+    }
+  }
+  return { ok: false, hash };
+}
+
+module.exports = {
+  assertManifestIntegrity,
+  hashCanonical,
+  manifestHash,
+  sha256Bytes,
+  signManifest,
+  stripManifestSignatures,
+  verifySignedManifest
+};

package/src/manifest/validators.cjs

@@ -0,0 +1,203 @@
+const { APP_PACK_KIND, HOST_PACK_KIND, HOST_SANDBOXES, PLAYER_MODES, PLAYER_PACK_KIND } = require("../constants.cjs");
+const { fail } = require("../errors.cjs");
+
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function requireObject(value, name) {
+  if (!isObject(value)) fail(`${name} must be an object`);
+  return value;
+}
+
+function requireString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") fail(`${name} must be a non-empty string`);
+  return value;
+}
+
+function requireHash(value, name) {
+  const text = requireString(value, name);
+  if (!text.startsWith("sha256-") || text.length <= "sha256-".length) fail(`${name} must be a sha256 hash`);
+  return text;
+}
+
+function requireArray(value, name, options = {}) {
+  if (!Array.isArray(value)) fail(`${name} must be an array`);
+  if (options.nonEmpty && value.length === 0) fail(`${name} must not be empty`);
+  return value;
+}
+
+function requireStringArray(value, name) {
+  return requireArray(value, name).map((item, index) => requireString(item, `${name}[${index}]`));
+}
+
+function requireKind(manifest, kind) {
+  if (manifest.kind !== kind) fail(`Expected kind ${kind}`);
+}
+
+function validatePublisherRef(value, name = "publisher") {
+  const publisher = requireObject(value, name);
+  requireString(publisher.id, `${name}.id`);
+  requireString(publisher.name, `${name}.name`);
+  requireString(publisher.publicKey, `${name}.publicKey`);
+  return publisher;
+}
+
+function validateSignatures(value, name = "trust.signatures") {
+  return requireArray(value, name, { nonEmpty: true }).map((signature, index) => {
+    const item = requireObject(signature, `${name}[${index}]`);
+    requireString(item.publicKey, `${name}[${index}].publicKey`);
+    requireString(item.signature, `${name}[${index}].signature`);
+    return item;
+  });
+}
+
+function validateTrust(value, options = {}) {
+  const trust = requireObject(value, "trust");
+  if (options.createdAt) requireString(trust.createdAt, "trust.createdAt");
+  validateSignatures(trust.signatures);
+  return trust;
+}
+
+function validateCapabilities(value, name = "capabilities") {
+  const capabilities = requireObject(value, name);
+  requireStringArray(capabilities.required, `${name}.required`);
+  if (capabilities.optional !== undefined) requireStringArray(capabilities.optional, `${name}.optional`);
+  return capabilities;
+}
+
+function validatePackRef(value, name) {
+  const ref = requireObject(value, name);
+  requireString(ref.url, `${name}.url`);
+  requireHash(ref.integrity, `${name}.integrity`);
+  return ref;
+}
+
+function validateRecommendedFor(value, name) {
+  if (value === undefined) return undefined;
+  const recommended = requireObject(value, name);
+  if (recommended.devices !== undefined) requireStringArray(recommended.devices, `${name}.devices`);
+  if (recommended.roles !== undefined) requireStringArray(recommended.roles, `${name}.roles`);
+  if (recommended.groups !== undefined) requireStringArray(recommended.groups, `${name}.groups`);
+  return recommended;
+}
+
+function validateAppPlayerRef(value, name) {
+  const ref = validatePackRef(value, name);
+  requireString(ref.id, `${name}.id`);
+  requireString(ref.name, `${name}.name`);
+  validateRecommendedFor(ref.recommendedFor, `${name}.recommendedFor`);
+  return ref;
+}
+
+function validateCompatibility(value, name, requiredHashes) {
+  const compatibility = requireObject(value, name);
+  for (const field of requiredHashes) requireHash(compatibility[field], `${name}.${field}`);
+  return compatibility;
+}
+
+function validateAppPackManifest(value) {
+  const manifest = requireObject(value, "app pack");
+  requireKind(manifest, APP_PACK_KIND);
+  requireString(manifest.id, "id");
+  requireString(manifest.name, "name");
+  requireString(manifest.version, "version");
+  validatePublisherRef(manifest.publisher);
+  requireString(manifest.matterhornVersion, "matterhornVersion");
+  validatePackRef(manifest.hostPack, "hostPack");
+  requireArray(manifest.playerPacks, "playerPacks", { nonEmpty: true }).forEach((player, index) => {
+    validateAppPlayerRef(player, `playerPacks[${index}]`);
+  });
+  validateCompatibility(manifest.compatibility, "compatibility", ["appProtocolHash", "operationSchemaHash", "stateSchemaHash"]);
+  if (manifest.compatibility.eventSchemaHash !== undefined) requireHash(manifest.compatibility.eventSchemaHash, "compatibility.eventSchemaHash");
+  validateCapabilities(manifest.capabilities);
+  validateTrust(manifest.trust, { createdAt: true });
+  return manifest;
+}
+
+function validateHostPluginRef(value, name) {
+  const ref = requireObject(value, name);
+  requireString(ref.id, `${name}.id`);
+  requireString(ref.version, `${name}.version`);
+  requireString(ref.source, `${name}.source`);
+  requireHash(ref.integrity, `${name}.integrity`);
+  if (ref.dependsOn !== undefined) {
+    requireArray(ref.dependsOn, `${name}.dependsOn`).forEach((dependency, index) => {
+      const item = requireObject(dependency, `${name}.dependsOn[${index}]`);
+      requireString(item.id, `${name}.dependsOn[${index}].id`);
+      if (item.version !== undefined) requireString(item.version, `${name}.dependsOn[${index}].version`);
+      if (item.optional !== undefined && typeof item.optional !== "boolean") fail(`${name}.dependsOn[${index}].optional must be a boolean`);
+    });
+  }
+  if (ref.conflictsWith !== undefined) requireStringArray(ref.conflictsWith, `${name}.conflictsWith`);
+  if (ref.capabilities !== undefined) validateCapabilities(ref.capabilities, `${name}.capabilities`);
+  return ref;
+}
+
+function validateHostPackManifest(value) {
+  const manifest = requireObject(value, "host pack");
+  requireKind(manifest, HOST_PACK_KIND);
+  requireString(manifest.id, "id");
+  requireString(manifest.appPackId, "appPackId");
+  requireString(manifest.version, "version");
+  requireArray(manifest.plugins, "plugins", { nonEmpty: true }).forEach((plugin, index) => {
+    validateHostPluginRef(plugin, `plugins[${index}]`);
+  });
+  validateCompatibility(manifest.compatibility, "compatibility", ["appProtocolHash", "pluginGraphHash"]);
+  const runtime = requireObject(manifest.runtime, "runtime");
+  requireString(runtime.minMatterhornVersion, "runtime.minMatterhornVersion");
+  if (runtime.sandbox !== undefined && !HOST_SANDBOXES.has(runtime.sandbox)) fail("runtime.sandbox is invalid");
+  validateCapabilities(manifest.capabilities);
+  validateTrust(manifest.trust);
+  return manifest;
+}
+
+function validatePlayerSupport(value, name) {
+  const support = requireObject(value, name);
+  requireString(support.appPackId, `${name}.appPackId`);
+  requireString(support.appPackRange, `${name}.appPackRange`);
+  requireHash(support.appProtocolHash, `${name}.appProtocolHash`);
+  if (support.pluginIds !== undefined) requireStringArray(support.pluginIds, `${name}.pluginIds`);
+  return support;
+}
+
+function validatePlayerPackManifest(value) {
+  const manifest = requireObject(value, "player pack");
+  requireKind(manifest, PLAYER_PACK_KIND);
+  requireString(manifest.id, "id");
+  requireString(manifest.name, "name");
+  requireString(manifest.version, "version");
+  validatePublisherRef(manifest.publisher);
+  const entrypoints = requireObject(manifest.entrypoints, "entrypoints");
+  requireString(entrypoints.default, "entrypoints.default");
+  for (const field of ["admin", "mobile", "kiosk", "embedded"]) {
+    if (entrypoints[field] !== undefined) requireString(entrypoints[field], `entrypoints.${field}`);
+  }
+  requireArray(manifest.supports, "supports", { nonEmpty: true }).forEach((support, index) => {
+    validatePlayerSupport(support, `supports[${index}]`);
+  });
+  validateRecommendedFor(manifest.recommendedFor, "recommendedFor");
+  if (!PLAYER_MODES.has(manifest.mode)) fail("mode is invalid");
+  const trust = validateTrust(manifest.trust);
+  if (trust.integrity !== undefined) requireHash(trust.integrity, "trust.integrity");
+  return manifest;
+}
+
+module.exports = {
+  isObject,
+  requireArray,
+  requireHash,
+  requireObject,
+  requireString,
+  requireStringArray,
+  validateAppPackManifest,
+  validateCapabilities,
+  validateHostPackManifest,
+  validateHostPluginRef,
+  validatePackRef,
+  validatePlayerPackManifest,
+  validatePlayerSupport,
+  validatePublisherRef,
+  validateSignatures,
+  validateTrust
+};