clay-server 4.0.0-beta.14 → 4.0.0-beta.15

package/lib/capsule-display-floor.js

@@ -0,0 +1,51 @@
+// The mandatory declarative floor element of a Capsule's Display set.
+//
+// A Capsule is Logic, Skills, and Display. Display carries no packaging duty
+// towards an agent (no Mate ever reads it), but it does carry the human's
+// sovereignty: every Capsule must ship one element the host can always render,
+// so the Capsule stays fully operable by hand with no AI in the path. That
+// element is the validated declarative tree, and it is the floor.
+//
+// Two gates follow from that, and they are gates rather than aspirations:
+//   1. Registration refuses a Capsule whose Display set lacks the floor.
+//   2. Skills go dark when the floor does. A Capsule whose floor is
+//      unavailable leaves the catalog and the control surface a Mate sees, at
+//      the same moment the human loses it.
+//
+// The only question either gate asks is the one tool-ui-spec answers: does the
+// Capsule have a declarative tree, and does that tree validate? A tree that is
+// merely sparse is still a floor. Nothing here reads a stored verdict, because
+// a stored verdict is a claim rather than the Display itself; the gate always
+// validates the actual tree.
+
+var toolUiSpec = require("./tool-ui-spec");
+
+var FLOOR_ELEMENT = "declarative";
+
+// Fails closed: a scan error, a missing ID, a missing tree, or a tree that
+// does not validate all mean the same thing to a Mate, which is no Capsule.
+function hasUsableFloor(manifest, uiTree) {
+  if (!manifest || manifest.error || !manifest.id) return false;
+  var tree = uiTree === undefined ? manifest.uiTree : uiTree;
+  if (tree === undefined || tree === null) return false;
+  try {
+    toolUiSpec.validateUiTreeForManifest(tree, manifest);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+function assertFloor(uiTree, manifest) {
+  if (uiTree === undefined || uiTree === null) {
+    throw new Error("Capsule Display must include the declarative floor element.");
+  }
+  toolUiSpec.validateUiTreeForManifest(uiTree, manifest);
+  return true;
+}
+
+module.exports = {
+  FLOOR_ELEMENT: FLOOR_ELEMENT,
+  hasUsableFloor: hasUsableFloor,
+  assertFloor: assertFloor,
+};

package/lib/capsule-frame-server.js

@@ -0,0 +1,229 @@
+// Isolated host for a Capsule's opt-in rich Display element.
+//
+// The rich element is additive Display: arbitrary rendering (canvas, WebGL)
+// with zero authority. It runs in an iframe that is sandboxed with
+// allow-scripts only and served from this dedicated listener, a distinct
+// origin from the app, so nothing of Clay's DOM, cookies, or storage is
+// reachable. Its one outward edge is postMessage to its embedder, and the
+// only thing it can ask for is the same validated act a human click requests.
+//
+// The frame document carries its own CSP, strictly tighter than the app
+// policy: default-src 'none' with a per-response script nonce. There is no
+// connect-src at all, so the frame cannot fetch, beacon, or open sockets; a
+// rich element ships self-contained. The nonce authorizes exactly two
+// scripts: the inline bridge below and the Capsule's own display.js.
+//
+// This origin serves no cookies and knows no sessions. A frame URL is gated
+// by a short-lived token issued over the user's authenticated WebSocket, and
+// each token admits one shell fetch and one display.js fetch. Whatever state
+// the host later pushes into the frame is the entire exfiltration surface,
+// chosen per element, exactly like a snapshot projection is chosen per caller.
+
+var crypto = require("crypto");
+var fs = require("fs");
+var http = require("http");
+var https = require("https");
+var path = require("path");
+var toolsRegistry = require("./tools-registry");
+
+var TOKEN_TTL_MS = 60000;
+var DISPLAY_FILE = "display.js";
+var MAX_DISPLAY_BYTES = 512 * 1024;
+
+function createCapsuleFrameServer(opts) {
+  opts = opts || {};
+  var tlsOptions = opts.tlsOptions || null;
+  var tokens = Object.create(null);
+  var server = null;
+  var listening = null;
+
+  function pruneTokens(now) {
+    var keys = Object.keys(tokens);
+    for (var i = 0; i < keys.length; i++) {
+      if (tokens[keys[i]].expiresAt <= now) delete tokens[keys[i]];
+    }
+  }
+
+  function displayPathFor(ctx, toolId) {
+    toolsRegistry.validateToolId(toolId);
+    return path.join(toolsRegistry.resolveToolsRoot(ctx), toolId, DISPLAY_FILE);
+  }
+
+  function hasRichDisplay(ctx, toolId) {
+    try {
+      return fs.existsSync(displayPathFor(ctx, toolId));
+    } catch (error) {
+      return false;
+    }
+  }
+
+  function ensureListening() {
+    if (listening) return listening;
+    server = tlsOptions ? https.createServer(tlsOptions, handleRequest) : http.createServer(handleRequest);
+    listening = new Promise(function (resolve, reject) {
+      server.once("error", reject);
+      server.listen(opts.port || 0, function () {
+        resolve(server.address().port);
+      });
+    });
+    return listening;
+  }
+
+  // Issues the one-time frame URL for a Capsule that ships a rich element.
+  // Callable only from the authenticated WebSocket side, which is what binds
+  // the anonymous frame origin to a specific user's tools root.
+  function issueFrameUrl(ctx, toolId) {
+    if (!hasRichDisplay(ctx, toolId)) {
+      return Promise.reject(new Error("This Capsule ships no rich Display element."));
+    }
+    return ensureListening().then(function (port) {
+      pruneTokens(Date.now());
+      var token = crypto.randomBytes(24).toString("hex");
+      tokens[token] = {
+        ctx: { userId: ctx.userId, multiUser: ctx.multiUser, linuxUser: ctx.linuxUser },
+        toolId: toolId,
+        expiresAt: Date.now() + TOKEN_TTL_MS,
+        shell: true,
+        display: true,
+      };
+      return { port: port, path: "/capsule/?t=" + token, secure: !!tlsOptions };
+    });
+  }
+
+  function consumeToken(token, use) {
+    if (typeof token !== "string" || !token) return null;
+    var entry = tokens[token];
+    if (!entry) return null;
+    if (entry.expiresAt <= Date.now()) {
+      delete tokens[token];
+      return null;
+    }
+    if (!entry[use]) return null;
+    entry[use] = false;
+    if (!entry.shell && !entry.display) delete tokens[token];
+    return entry;
+  }
+
+  function deny(res, code) {
+    res.writeHead(code, { "Content-Type": "text/plain; charset=utf-8", "X-Content-Type-Options": "nosniff" });
+    res.end(code === 404 ? "Not found" : "Forbidden");
+  }
+
+  // The in-frame half of the bridge. Its only capabilities are receiving
+  // state/event pushes from the embedder and asking the embedder for an act.
+  // The embedder routes that request into the same pipeline a floor button
+  // uses; nothing here can mutate anything directly.
+  function bridgeSource() {
+    return [
+      "(function () {",
+      "  \"use strict\";",
+      "  var api = {",
+      "    onState: null,",
+      "    onEvent: null,",
+      "    act: function (actionId, args) {",
+      "      window.parent.postMessage({ clayCapsuleFrame: 1, type: \"act\", actionId: String(actionId), args: args || {} }, \"*\");",
+      "    },",
+      "  };",
+      "  window.ClayCapsule = api;",
+      "  window.addEventListener(\"message\", function (event) {",
+      "    if (event.source !== window.parent) return;",
+      "    var data = event.data;",
+      "    if (!data || data.clayCapsuleFrame !== 1) return;",
+      "    if (data.type === \"state\" && typeof api.onState === \"function\") api.onState(data.state || {});",
+      "    else if (data.type === \"event\" && typeof api.onEvent === \"function\") api.onEvent(data.event || null);",
+      "  });",
+      "  window.addEventListener(\"load\", function () {",
+      "    window.parent.postMessage({ clayCapsuleFrame: 1, type: \"ready\" }, \"*\");",
+      "  });",
+      "})();",
+    ].join("\n");
+  }
+
+  function shellHtml(nonce, token) {
+    return [
+      "<!doctype html>",
+      "<html>",
+      "<head>",
+      "<meta charset=\"utf-8\">",
+      "<title>Capsule Display</title>",
+      "</head>",
+      "<body>",
+      "<script nonce=\"" + nonce + "\">" + bridgeSource() + "</script>",
+      "<script nonce=\"" + nonce + "\" src=\"/capsule/display.js?t=" + token + "\"></script>",
+      "</body>",
+      "</html>",
+    ].join("\n");
+  }
+
+  function handleRequest(req, res) {
+    if (req.method !== "GET") return deny(res, 404);
+    var parsed;
+    try {
+      parsed = new URL(req.url, "http://frame.invalid");
+    } catch (error) {
+      return deny(res, 404);
+    }
+    var token = parsed.searchParams.get("t");
+    if (parsed.pathname === "/capsule/" || parsed.pathname === "/capsule") {
+      var shellEntry = consumeToken(token, "shell");
+      if (!shellEntry) return deny(res, 403);
+      var nonce = crypto.randomBytes(16).toString("base64");
+      res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        // No connect-src, no default fallback: the frame cannot reach the
+        // network at all, and only the two nonced scripts may run. This is
+        // deliberately tighter than the app policy in every direction.
+        "Content-Security-Policy": "default-src 'none'; script-src 'nonce-" + nonce + "'; base-uri 'none'; form-action 'none'",
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Cache-Control": "no-store",
+      });
+      res.end(shellHtml(nonce, token));
+      return;
+    }
+    if (parsed.pathname === "/capsule/display.js") {
+      var displayEntry = consumeToken(token, "display");
+      if (!displayEntry) return deny(res, 403);
+      var source;
+      try {
+        var filePath = displayPathFor(displayEntry.ctx, displayEntry.toolId);
+        if (fs.statSync(filePath).size > MAX_DISPLAY_BYTES) return deny(res, 403);
+        source = fs.readFileSync(filePath, "utf8");
+      } catch (error) {
+        return deny(res, 404);
+      }
+      res.writeHead(200, {
+        "Content-Type": "text/javascript; charset=utf-8",
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Cache-Control": "no-store",
+      });
+      res.end(source);
+      return;
+    }
+    return deny(res, 404);
+  }
+
+  function close() {
+    if (!server) return Promise.resolve();
+    var closing = server;
+    server = null;
+    listening = null;
+    return new Promise(function (resolve) {
+      closing.close(function () { resolve(); });
+    });
+  }
+
+  return {
+    issueFrameUrl: issueFrameUrl,
+    hasRichDisplay: hasRichDisplay,
+    ensureListening: ensureListening,
+    close: close,
+  };
+}
+
+module.exports = {
+  DISPLAY_FILE: DISPLAY_FILE,
+  TOKEN_TTL_MS: TOKEN_TTL_MS,
+  createCapsuleFrameServer: createCapsuleFrameServer,
+};

package/lib/capsule-pig-logic.js

@@ -0,0 +1,268 @@
+// Server-side Logic for the Pig validation Capsule.
+//
+// Logic is the single source of truth. Every state change in the game happens
+// through one of these functions and nowhere else: the die is rolled here, the
+// turn rules are enforced here, and the game record lives in the Capsule's own
+// datastore. A human button click and a Mate clay_tool_act call arrive at the
+// same act pipeline with the same rules, so neither party can break a rule the
+// other is bound by, and neither sees state the other cannot.
+//
+// The two seats are "user" and "mate". The server resolves its own actor before
+// calling in, and the human actor maps onto the user seat; seat is never read
+// from caller-supplied text.
+//
+// Rules: seats alternate turns. On your turn you may roll as often as you like;
+// each roll adds to the turn total, but rolling a 1 loses the whole turn total
+// and passes play. Holding banks the turn total into your score, and the first
+// seat to bank at least 100 points wins. A finished game is frozen until
+// someone resets it; only the user may reset a game in progress, because the
+// Capsule belongs to the human, not to the Mate.
+
+var crypto = require("crypto");
+
+var GAME_DOC_ID = "game";
+var TARGET_SCORE = 100;
+var BUST_FACE = 1;
+var USER = "user";
+var MATE = "mate";
+var SEATS = [USER, MATE];
+var SEAT_LABELS = { user: "You", mate: "Your Mate" };
+var MAX_RECENT_ROLLS = 12;
+
+// Every read-modify-write for one stored game runs to completion before the
+// next one starts. Two acts that arrive together would otherwise both validate
+// against the same turn, and the second write would silently discard the first.
+var gameLocks = Object.create(null);
+
+function runExclusive(key, operation) {
+  var previous = gameLocks[key] || Promise.resolve();
+  var settled = previous.then(operation, operation);
+  gameLocks[key] = settled.then(function () {}, function () {});
+  return settled;
+}
+
+function secureRollDie() {
+  return crypto.randomInt(1, 7);
+}
+
+function otherSeat(seat) {
+  return seat === USER ? MATE : USER;
+}
+
+function newGame() {
+  return {
+    status: "playing",
+    turn: USER,
+    scores: { user: 0, mate: 0 },
+    turnTotal: 0,
+    lastRoll: null,
+    lastActor: null,
+    winner: null,
+    target: TARGET_SCORE,
+    sequence: 0,
+    eventSeq: 0,
+    recentRolls: [],
+  };
+}
+
+function safeScore(value) {
+  return Number.isInteger(value) && value >= 0 && value <= 10000 ? value : 0;
+}
+
+// Counters are ordering, not points: they only ever grow, so they carry no
+// upper bound. eventSeq in particular must survive a reset, because a Display
+// that saw event N must treat anything at or below N as already rendered.
+function safeCounter(value) {
+  return Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+// A stored game is data, not a promise about shape. Anything unreadable is
+// replaced by a fresh game rather than trusted.
+function normalizeState(stored) {
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) return newGame();
+  if (SEATS.indexOf(stored.turn) === -1) return newGame();
+  if (stored.status !== "playing" && stored.status !== "complete") return newGame();
+  var scores = stored.scores && typeof stored.scores === "object" ? stored.scores : {};
+  var rolls = Array.isArray(stored.recentRolls) ? stored.recentRolls.slice(-MAX_RECENT_ROLLS) : [];
+  return {
+    status: stored.status,
+    turn: stored.turn,
+    scores: { user: safeScore(scores.user), mate: safeScore(scores.mate) },
+    turnTotal: safeScore(stored.turnTotal),
+    lastRoll: Number.isInteger(stored.lastRoll) ? stored.lastRoll : null,
+    lastActor: SEATS.indexOf(stored.lastActor) !== -1 ? stored.lastActor : null,
+    winner: SEATS.indexOf(stored.winner) !== -1 ? stored.winner : null,
+    target: TARGET_SCORE,
+    sequence: safeCounter(stored.sequence),
+    eventSeq: safeCounter(stored.eventSeq),
+    recentRolls: rolls.filter(function (entry) {
+      return entry && typeof entry.text === "string" && Number.isInteger(entry.face);
+    }),
+  };
+}
+
+// recentRolls holds rolls and only rolls, including a bust. Banking and winning
+// are turn outcomes rather than rolls, so they never appear here.
+function appendRoll(state, seat, face, text) {
+  var next = state.sequence + 1;
+  state.sequence = next;
+  state.recentRolls = state.recentRolls
+    .concat([{ id: "roll-" + next, seat: seat, face: face, text: text }])
+    .slice(-MAX_RECENT_ROLLS);
+}
+
+function requirePlayableTurn(state, seat) {
+  if (state.status !== "playing") {
+    throw new Error("This game is already over. Reset it to play again.");
+  }
+  if (state.turn !== seat) {
+    throw new Error("This move is out of turn: " + SEAT_LABELS[state.turn] + " to play.");
+  }
+}
+
+function roll(state, seat, rollDie) {
+  requirePlayableTurn(state, seat);
+  var face = rollDie();
+  if (!Number.isInteger(face) || face < 1 || face > 6) throw new Error("The die produced an invalid face.");
+  state.lastRoll = face;
+  state.lastActor = seat;
+  if (face === BUST_FACE) {
+    appendRoll(state, seat, face, SEAT_LABELS[seat] + " rolled a 1 and lost " + state.turnTotal + " point(s).");
+    state.turnTotal = 0;
+    state.turn = otherSeat(seat);
+    return state;
+  }
+  state.turnTotal += face;
+  appendRoll(state, seat, face, SEAT_LABELS[seat] + " rolled a " + face + " for a turn total of " + state.turnTotal + ".");
+  return state;
+}
+
+function hold(state, seat) {
+  requirePlayableTurn(state, seat);
+  var banked = state.turnTotal;
+  state.scores[seat] += banked;
+  state.lastActor = seat;
+  state.turnTotal = 0;
+  if (state.scores[seat] >= state.target) {
+    state.status = "complete";
+    state.winner = seat;
+    return state;
+  }
+  state.turn = otherSeat(seat);
+  return state;
+}
+
+function reset(state, seat) {
+  if (state.status === "playing" && seat !== USER) {
+    throw new Error("Only the user may reset a game that is still in progress.");
+  }
+  return newGame();
+}
+
+// The projection a Display renders and a Mate reads. It adds no meaning that is
+// absent from state: every derived field is a restatement of the fields above.
+// The score series exist because a progress chart binds to a collection.
+function project(state) {
+  var complete = state.status === "complete";
+  var userTurn = !complete && state.turn === USER;
+  return {
+    status: state.status,
+    turn: state.turn,
+    scores: { user: state.scores.user, mate: state.scores.mate },
+    userScoreSeries: [{ seat: SEAT_LABELS.user, value: state.scores.user }],
+    mateScoreSeries: [{ seat: SEAT_LABELS.mate, value: state.scores.mate }],
+    turnTotal: state.turnTotal,
+    turnTotalText: "Turn total " + state.turnTotal + " of " + state.target + ", " + SEAT_LABELS[state.turn] + " to play.",
+    lastRoll: state.lastRoll,
+    lastActor: state.lastActor,
+    winner: state.winner,
+    target: state.target,
+    recentRolls: state.recentRolls,
+    complete: complete,
+    userTurn: userTurn,
+    eventSeq: state.eventSeq,
+  };
+}
+
+// Causality for the live Display: {actor, action, previous, next} plus a
+// monotonic seq. Sending only the new state would make a Mate's move teleport
+// onto the human's screen; the event lets the Display replay and attribute it.
+function buildEvent(seat, actionId, previous, next) {
+  return {
+    seq: next.eventSeq,
+    actor: seat,
+    action: actionId,
+    previous: previous,
+    next: next,
+  };
+}
+
+function seatFor(context) {
+  var actor = context && context.actor;
+  if (actor === "human" || actor === USER) return USER;
+  if (actor === MATE) return MATE;
+  throw new Error("The Capsule caller seat could not be determined.");
+}
+
+// One act pipeline. The human surface and the Mate MCP surface both land here.
+function createRuntime(options) {
+  options = options || {};
+  var storage = options.storage;
+  var rollDie = typeof options.rollDie === "function" ? options.rollDie : secureRollDie;
+  var lockKey = options.lockKey || "pig";
+  if (!storage) throw new Error("The Pig Capsule requires its datastore.");
+
+  async function writeState(state) {
+    await storage.put({ _id: GAME_DOC_ID, state: state });
+    return state;
+  }
+
+  async function readState() {
+    var doc = await storage.get(GAME_DOC_ID);
+    if (!doc) return writeState(newGame());
+    return normalizeState(doc.state);
+  }
+
+  async function snapshot(context) {
+    seatFor(context);
+    return runExclusive(lockKey, async function () {
+      return project(await readState());
+    });
+  }
+
+  // An act returns {state, event}: the new projection for the caller and the
+  // causal event for every watching Display. Both are built inside the lock,
+  // so seq order on the wire is the order the rules actually ran in.
+  async function act(context, actionId, args) {
+    var seat = seatFor(context);
+    return runExclusive(lockKey, async function () {
+      var state = await readState();
+      var previous = project(state);
+      var next;
+      if (actionId === "roll") next = roll(state, seat, rollDie);
+      else if (actionId === "hold") next = hold(state, seat);
+      else if (actionId === "reset") next = reset(state, seat);
+      else throw new Error("Unknown Pig action '" + String(actionId) + "'.");
+      next.eventSeq = previous.eventSeq + 1;
+      await writeState(next);
+      var projected = project(next);
+      return { state: projected, event: buildEvent(seat, actionId, previous, projected) };
+    });
+  }
+
+  return { snapshot: snapshot, act: act };
+}
+
+module.exports = {
+  GAME_DOC_ID: GAME_DOC_ID,
+  TARGET_SCORE: TARGET_SCORE,
+  SEATS: SEATS,
+  newGame: newGame,
+  normalizeState: normalizeState,
+  project: project,
+  buildEvent: buildEvent,
+  roll: roll,
+  hold: hold,
+  reset: reset,
+  createRuntime: createRuntime,
+};

package/lib/capsule-server-runtimes.js

@@ -0,0 +1,41 @@
+// Trusted server-runtime Logic for shipped Capsules.
+//
+// A server Capsule's Logic runs in this process rather than in a browser
+// worker, so it stays available with no home screen open and owns randomness
+// and hidden state the client must never hold. Only Capsules shipped in
+// lib/capsules/ can claim the server runtime (see tools-registry
+// isTrustedServerRuntime), and only IDs listed here resolve to real Logic.
+//
+// A runtime is created per call. State lives in the Capsule's datastore, never
+// in this module, so nothing here is shared between users.
+
+var path = require("path");
+var toolStorage = require("./tool-storage");
+var toolsRegistry = require("./tools-registry");
+var pigLogic = require("./capsule-pig-logic");
+var tictactoeLogic = require("./capsule-tictactoe-logic");
+
+var RUNTIME_FACTORIES = {
+  pig: pigLogic.createRuntime,
+  tictactoe: tictactoeLogic.createRuntime,
+};
+
+function hasRuntime(toolId) {
+  return Object.prototype.hasOwnProperty.call(RUNTIME_FACTORIES, toolId);
+}
+
+function createRuntime(toolId, ctx, options) {
+  if (!hasRuntime(toolId)) return null;
+  var settings = Object.assign({}, options || {});
+  if (!settings.storage) settings.storage = toolStorage.createToolStorage(ctx, toolId);
+  // One stored game, one serialization key, no matter how many runtime
+  // instances are created for it.
+  if (!settings.lockKey) settings.lockKey = path.join(toolsRegistry.resolveToolsRoot(ctx), toolId);
+  return RUNTIME_FACTORIES[toolId](settings);
+}
+
+module.exports = {
+  hasRuntime: hasRuntime,
+  createRuntime: createRuntime,
+  ids: Object.keys(RUNTIME_FACTORIES),
+};