@mh-gg/player-runtime 0.1.1-alpha.20260626T104441232Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @mh-gg/player-runtime
+
+Matterhorn player-side plugin runtime helpers for dispatch, optimistic state, and launch envelopes.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mh-gg/player-runtime",
+  "version": "0.1.1-alpha.20260626T104441232Z",
+  "description": "Matterhorn player-side plugin runtime helpers for dispatch, optimistic state, and launch envelopes.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "dependencies": {
+    "@mh-gg/event": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/launcher": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/protocol": "^0.1.1-alpha.20260626T104441232Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=70 --test-coverage-branches=40 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/errors.cjs

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

package/src/index.cjs

@@ -0,0 +1,13 @@
+const {
+  createOptimisticOperationManager,
+  createPlayerRuntime
+} = require("@mh-gg/launcher");
+
+module.exports = {
+  ...require("./errors.cjs"),
+  createOptimisticOperationManager,
+  createPlayerRuntime,
+  ...require("./launch/index.cjs"),
+  ...require("./operation-auth/index.cjs"),
+  ...require("./plugin-runtime/index.cjs")
+};

package/src/launch/index.cjs

@@ -0,0 +1,33 @@
+const {
+  decryptLaunchEnvelope,
+  encryptLaunchEnvelope,
+  parseExternalLaunchUrl,
+  verifyLaunchEnvelope
+} = require("@mh-gg/launcher");
+const { fail } = require("../errors.cjs");
+
+function openExternalLaunch(url, options = {}) {
+  const parsed = parseExternalLaunchUrl(url);
+  if (parsed.envelope?.kind === "matterhorn.launch-sealed" && options.playerPack) {
+    if (parsed.envelope.playerPack?.id !== options.playerPack.id || parsed.envelope.playerPack?.version !== options.playerPack.version) {
+      fail("Launch envelope is for a different player.");
+    }
+  }
+  const envelope = parsed.envelope?.kind === "matterhorn.launch-sealed"
+    ? decryptLaunchEnvelope(parsed.envelope.sealed, options.secret)
+    : parsed.envelope;
+  const verified = verifyLaunchEnvelope(envelope, {
+    now: options.now ? options.now() : Date.now(),
+    playerPack: options.playerPack,
+    appPack: options.appPack,
+    nonceStore: options.nonceStore
+  });
+  if (!verified.ok && options.allowUnverifiedLaunch !== true) fail(`Launch envelope is invalid: ${verified.reason}`);
+  return { ...parsed, envelope };
+}
+
+function sealExternalLaunchEnvelope(envelope, secret) {
+  return encryptLaunchEnvelope(envelope, secret);
+}
+
+module.exports = { openExternalLaunch, sealExternalLaunchEnvelope };

package/src/operation-auth/index.cjs

@@ -0,0 +1,55 @@
+const crypto = require("node:crypto");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+const { clone } = require("../shared/clone.cjs");
+const { ensureOperationIdentity } = require("@mh-gg/protocol");
+
+function unsignedRoomOperation(operation) {
+  const copy = clone(operation);
+  if (copy?.auth && Object.prototype.hasOwnProperty.call(copy.auth, "signature")) delete copy.auth.signature;
+  return copy;
+}
+
+function signRoomOperation(operation, privateKey, publicKey) {
+  const next = clone(operation);
+  next.auth = { ...(next.auth || {}) };
+  if (publicKey !== undefined) next.auth.publicKey = publicKey;
+  delete next.auth.signature;
+  const withIdentity = ensureOperationIdentity(next, { nodeId: next.actor?.deviceId || next.actor?.memberId || "player-auth", now: next.createdAt || Date.now() });
+  withIdentity.auth.signature = crypto.sign(null, Buffer.from(canonicalJson(unsignedRoomOperation(withIdentity))), privateKey).toString("base64url");
+  return withIdentity;
+}
+
+/**
+ * Verify an operation signature against an explicit public key the caller already trusts.
+ * This is an authenticity check only when trustedPublicKey came from a grant, member record, or pin.
+ */
+function verifyOperationAuth(operation, trustedPublicKey) {
+  if (!operation || typeof operation !== "object") return { ok: false, error: "Operation is required." };
+  if (!operation.auth || typeof operation.auth !== "object") return { ok: false, error: "Operation auth is required." };
+  if (typeof operation.auth.signature !== "string" || operation.auth.signature.length === 0) return { ok: false, error: "Operation signature is required." };
+  if (typeof trustedPublicKey !== "string" || trustedPublicKey.length === 0) return { ok: false, error: "Trusted operation public key is required." };
+  try {
+    const ok = crypto.verify(null, Buffer.from(canonicalJson(unsignedRoomOperation(operation))), trustedPublicKey, Buffer.from(operation.auth.signature, "base64url"));
+    return ok ? { ok: true } : { ok: false, error: "Operation signature is invalid." };
+  } catch (error) {
+    return { ok: false, error: error?.message || "Operation signature verification failed." };
+  }
+}
+
+/**
+ * Check only that an operation was signed by its embedded public key.
+ * This is not an authenticity check and must not be used as an authorization decision.
+ */
+function checkOperationSignatureSelfConsistent(operation) {
+  const verified = verifyOperationAuth(operation, operation?.auth?.publicKey);
+  return verified.ok
+    ? { ok: true, signedWithEmbeddedKey: true }
+    : { ...verified, signedWithEmbeddedKey: true };
+}
+
+module.exports = {
+  checkOperationSignatureSelfConsistent,
+  signRoomOperation,
+  unsignedRoomOperation,
+  verifyOperationAuth
+};

package/src/plugin-runtime/index.cjs

@@ -0,0 +1,60 @@
+const {
+  createOptimisticOperationManager,
+  createPlayerRuntime,
+  verifyLaunchEnvelope
+} = require("@mh-gg/launcher");
+const { fail } = require("../errors.cjs");
+const { clone } = require("../shared/clone.cjs");
+
+function createPlayerPluginRuntime(options = {}) {
+  if (!options.playerPlugin || typeof options.playerPlugin !== "object") fail("playerPlugin is required");
+  if (!options.launchEnvelope || typeof options.launchEnvelope !== "object") fail("launchEnvelope is required");
+  const verified = verifyLaunchEnvelope(options.launchEnvelope, { now: options.now ? options.now() : Date.now() });
+  if (!verified.ok && options.allowUnverifiedLaunch !== true) fail(`Launch envelope is invalid: ${verified.reason}`);
+
+  const hostClient = options.hostClient;
+  if (!hostClient || typeof hostClient.sendOperation !== "function") fail("hostClient.sendOperation is required");
+  const operationRuntime = createPlayerRuntime({
+    room: options.launchEnvelope.room,
+    appPack: options.launchEnvelope.appPack,
+    actor: options.actor || options.launchEnvelope.actor || { memberId: "anonymous", deviceId: "device", role: "guest" },
+    credentialGrant: options.launchEnvelope.credentialGrant,
+    now: options.now,
+    signOperation: options.signOperation,
+    sendOperation: (operation) => hostClient.sendOperation(operation)
+  });
+  const optimistic = createOptimisticOperationManager(options.initialState || {}, options.playerPlugin.optimisticReducers || {});
+
+  return {
+    playerPlugin: options.playerPlugin,
+    launchEnvelope: clone(options.launchEnvelope),
+    pending: operationRuntime.pending,
+    state: optimistic,
+    dispatch: async (draft) => {
+      const operation = await operationRuntime.buildOperationAsync(draft);
+      optimistic.apply(operation);
+      operationRuntime.pending.set(operation.id, { operation, status: "pending" });
+      try {
+        const result = await hostClient.sendOperation(operation);
+        operationRuntime.pending.set(operation.id, { operation, status: "accepted", result });
+        if (result?.state !== undefined) optimistic.ack(operation.id, result.state);
+        else optimistic.ack(operation.id);
+        return result;
+      } catch (error) {
+        operationRuntime.pending.set(operation.id, { operation, status: "rejected", error: error?.message || String(error) });
+        optimistic.reject(operation.id);
+        throw error;
+      }
+    },
+    action(name, ...args) {
+      const fn = options.playerPlugin.actions?.[name];
+      if (typeof fn !== "function") fail(`Player action ${name} is not available`);
+      return fn({ dispatch: this.dispatch }, ...args);
+    },
+    snapshot() {
+      return optimistic.getState();
+    }
+  };
+}
+
+module.exports = { createPlayerPluginRuntime };

package/src/shared/clone.cjs

@@ -0,0 +1,5 @@
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+module.exports = { clone };