@looop-games/cli 0.1.34 → 0.1.36

package/lib/static-server.mjs

@@ -12,8 +12,31 @@ import http from 'node:http';
 import { EventEmitter } from 'node:events';
 import { readdirSync, readFileSync, statSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { extname, join, normalize, sep } from 'node:path';
+import { gunzipSync } from 'node:zlib';
 import { injectHeadTags, rewriteHtmlScripts, rewriteJsImports, PLATFORM_URL, TOOLBOX_URL } from './inject.mjs';
 import { WHOAMI_PATH } from './ports.mjs';
+import {
+  writeSegment, stitchStream, streamDir, listRecordings, latestRecording, deleteRecording, setKept,
+  DEV_SEGMENT_PATH, DEV_REPLAYS_PATH,
+} from './replay-store.mjs';
+
+// `?replay=<id>` resolves to `.looop/replays/<id>.json` (replaySourceUrl in the
+// engine's replay transport). Nothing writes that FILE — the room writes the
+// stream's segments in a directory beside it — so the dev server answers the
+// path by stitching the directory. That is what makes watching a session back
+// a paste-the-URL operation with no fetch step in front of it.
+// Anchored at the game's own mount rather than "anywhere a path happens to end
+// this way": the handler ignores the prefix, so a loose pattern would serve the
+// project's recordings from any URL that ended in one.
+const REPLAY_URL_RE = /^\/games\/[^/]+\/\.looop\/replays\/([a-z0-9][a-z0-9-]{0,63})\.json$/;
+
+// The one stream id nobody owns. `?replay=last` is what makes watching a
+// session back typeable by a human — the alternative is copying a base36
+// timestamp off a console line, on the phone that just played. It can never
+// collide with a real recording: stream ids are minted as
+// `<base36 ms>-<base36 counter>` (shared/ui/room/entity/recorder.js), so every
+// one of them carries a dash and none of them is a word.
+const LATEST_ALIAS = 'last';
 
 const RELOAD_CLIENT = `<script>
 (() => {
@@ -39,6 +62,75 @@ const WATCH_EXTS = new Set(['.html', '.css', '.js', '.mjs', '.json', '.svg', '.p
 // payload from filling the disk — reports are small JSON summaries.
 export const AGENT_INBOX_PATH = '/__looop/agent-inbox';
 const AGENT_INBOX_MAX_BYTES = 2 * 1024 * 1024;
+// What a segment may weigh ON THE WIRE. The room gzips anything big, and a
+// keyframe segment always is — a segment's size is the size of the world it
+// snapshots, which no room-side event cap can bound — so this is a bound on
+// COMPRESSED bytes, where a real game's 1.13 MB keyframe arrives as ~60 KB.
+const SEGMENT_MAX_BYTES = 1024 * 1024;
+// And what it may weigh once inflated. The compressed bound says nothing about
+// this: a few hundred KB of repeated bytes expands to gigabytes, and with the
+// endpoint unauthenticated by design the expansion ratio is the sender's to
+// choose. Sized well above the largest plausible keyframe (a 356-entity world
+// is 1.13 MB) so that only an attack, never a big game, meets it.
+const SEGMENT_MAX_INFLATED_BYTES = 32 * 1024 * 1024;
+// What the `keep` toggle may weigh: it is one boolean.
+const KEEP_MAX_BYTES = 1024;
+
+// The name this server was reached by, and whether that name could have been
+// pointed here by somebody else.
+//
+// A literal IP address and `localhost` cannot be aimed at this machine by a
+// stranger — they are not resolved by anyone's DNS. A registrable HOSTNAME can:
+// the attacker publishes `evil.example A 127.0.0.1` (or rebinds it after the
+// page loads), the creator visits it, and the browser now considers the dev
+// server same-origin — Origin and Host agree because the attacker chose both.
+// Requiring the host to be a literal is what makes the check below compare
+// something an attacker does not control.
+//
+// The phone case survives unchanged: a phone on the wifi reaches this server at
+// `http://192.168.x.y:<port>`, which is a literal.
+function trustedHost(header) {
+  const host = String(header ?? '').replace(/:\d+$/, '').toLowerCase();
+  if (host === 'localhost') return true;
+  if (host.startsWith('[') && host.endsWith(']')) return true;   // literal IPv6
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return true;          // literal IPv4
+  if (host.endsWith('.local')) return true;                      // mDNS — resolved on the wire, not by DNS
+  return false;
+}
+
+// Whether a request came from a page this dev server itself serves.
+//
+// The dev server binds every interface — it prints a LAN URL so a phone can
+// play — so "it is localhost" is not a trust boundary: any device on the same
+// wifi can reach it, and a hostile page in the creator's own browser can fire a
+// no-preflight POST at it (a CORS "simple" content-type skips the preflight,
+// and CORS gates reading a response, never the server-side write). A browser
+// stamps Origin on anything cross-origin; a non-browser caller sends none and
+// passes, at the same trust level as anything else already running on the
+// machine.
+//
+// Two conditions, and the second is not redundant: an Origin that MATCHES the
+// Host proves nothing on its own, because a hostname aimed at this machine
+// gives an attacker both halves at once (see trustedHost).
+//
+// `requireOrigin` turns the absent-header case from pass into fail, and is what
+// separates "a page this server served" from "any program that can reach this
+// port". A browser attaches Origin to every request whose method is not GET or
+// HEAD, same-origin ones included — so on the MUTATING verbs the header is free
+// to demand and refuses every non-browser caller. A GET cannot demand it: a
+// same-origin GET carries no Origin either, so the game page fetching its own
+// recording would be refused along with everything else.
+//
+// It is deliberately NOT applied to segment ingest. A multiplayer room posts
+// its segments from a partykit worker, which is not a served page and has no
+// Origin to send; requiring one there would silently stop multiplayer sessions
+// being recorded at all.
+function sameOrigin(req, { requireOrigin = false } = {}) {
+  if (!trustedHost(req.headers.host)) return false;
+  const origin = req.headers.origin;
+  if (!origin) return !requireOrigin;
+  return origin === `http://${req.headers.host}`;
+}
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -113,6 +205,11 @@ export function createStaticServer({
   // import map + globalThis.__LOOOP_SKELETON__ so startGame() can boot. Null for
   // a v1 game (no bare `looop` import, no skeleton).
   skeleton = null,
+  // The engine version this server serves, stamped onto every agent-inbox
+  // file as `engine`. A report is read off disk later against whatever the
+  // game is pinned to THEN; the server is the only side that knows what it
+  // was when the report was made (the page has no version of its own).
+  engineVersion = null,
 }) {
   // The injected skeleton is LIVE, not frozen at startup: a v2 hot-reload
   // rebuilds the room with a fresh skeleton, and `setSkeleton` below pushes that
@@ -139,6 +236,16 @@ export function createStaticServer({
     } catch {
       return null;
     }
+    // `.looop/` is the game's private working directory, not part of the site.
+    // It holds the agent inbox (reports an agent reads as trusted) and the
+    // recorded sessions (which carry every player's entity seed, every
+    // non-replicated field, and every participant's account id — strictly more
+    // than any single live client is ever sent). This server binds every
+    // interface and stamps `Access-Control-Allow-Origin: *`, so serving that
+    // tree would hand it to any page in the creator's browser and to anything
+    // on the same wifi. Recordings are readable, but only through the stitched
+    // route below, which checks the origin.
+    if (/(?:^|\/)\.looop(?:\/|$)/.test(decoded)) return null;
     for (const { url, dir } of table) {
       if (!decoded.startsWith(url)) continue;
       const rest = decoded.slice(url.length).replace(/^\/+/, '');
@@ -224,6 +331,223 @@ export function createStaticServer({
     res.end(buf);
   }
 
+  // The engine bundle's shared/ tree — the LAST mount at /shared/, because the
+  // game's overrides dir shadows ahead of it. Stitching a recording goes
+  // through that engine's own reassembler rather than a copy here, so a
+  // recording is always read back by the engine that wrote it.
+  const engineSharedDir = table.filter((m) => m.url === '/shared/').at(-1)?.dir ?? null;
+
+  // A posted segment's JSON, inflating it when the room sent it gzipped.
+  //
+  // Two ways to know it is gzipped, because two senders reach here and only one
+  // of them can set headers: a normal flush is a fetch and says
+  // `content-encoding: gzip`, while the tail a page ships on `pagehide` may go
+  // out as a beacon, which carries a body and no headers of its own. So the
+  // header is honoured when present and the gzip magic number is sniffed when
+  // it is not. A body that CLAIMS gzip and is not gzip is an error rather than
+  // a fallback — silently accepting it would mean the two ends disagree about
+  // the wire format and neither ever finds out.
+  function readSegmentBody(req, buf) {
+    const declared = String(req.headers['content-encoding'] ?? '').toLowerCase().includes('gzip');
+    const sniffed = buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b;
+    if (!declared && !sniffed) return buf.toString('utf8');
+    try {
+      return gunzipSync(buf, { maxOutputLength: SEGMENT_MAX_INFLATED_BYTES }).toString('utf8');
+    } catch (e) {
+      throw new Error(`segment could not be decompressed: ${e?.message ?? e}`);
+    }
+  }
+
+  async function receiveSegment(req, res) {
+    // Only the page (or room) this server itself serves may write, and only up
+    // to a bounded size — the same two defences the agent inbox above carries,
+    // for the same two reasons. The dev server binds every interface (it prints
+    // a LAN URL for phones), so "it is localhost" is not a boundary: a hostile
+    // website in the creator's browser can fire a no-preflight POST at it (a
+    // CORS "simple" content-type skips the preflight, and CORS gates reading
+    // the response, never the server-side write), and any device on the same
+    // wifi can just send one. Both would otherwise author files inside the
+    // creator's game folder, without limit.
+    if (!sameOrigin(req)) {
+      res.writeHead(403, { 'Content-Type': 'text/plain' });
+      return res.end('cross-origin post rejected');
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+      size += c.length;
+      if (size > SEGMENT_MAX_BYTES) {
+        res.writeHead(413, { 'Content-Type': 'text/plain', Connection: 'close' });
+        return res.end(`segment too large (max ${SEGMENT_MAX_BYTES} bytes)`);
+      }
+      chunks.push(c);
+    }
+    try {
+      const out = writeSegment(projectDir, JSON.parse(readSegmentBody(req, Buffer.concat(chunks))));
+      return sendBody(res, 200, JSON.stringify(out), 'application/json');
+    } catch (e) {
+      // A rejected segment must name its reason: the room logs this line, and
+      // "the recording is missing" with no cause is the expensive version.
+      return sendBody(res, 400, JSON.stringify({ error: String(e?.message ?? e) }), 'application/json');
+    }
+  }
+
+  const wholeFilePath = (stream) => join(projectDir, '.looop', 'replays', `${stream}.json`);
+
+  async function serveReplay(res, requested) {
+    // `last` is resolved here rather than in the browser because only this side
+    // knows what is on disk — the transport turns a bare id into this path and
+    // has no directory to consult.
+    let stream = requested;
+    // Resolved AFTER the whole-file lane below has had its chance: a recording
+    // pulled in from elsewhere is served as a file, and `last.json` is a
+    // plausible name for a downloaded one. The alias must not shadow a file
+    // somebody deliberately put there.
+    if (requested === LATEST_ALIAS && !existsSync(wholeFilePath(requested))) {
+      stream = latestRecording(projectDir);
+      if (!stream) {
+        return sendBody(
+          res, 404,
+          JSON.stringify({ error: 'no recordings yet in this game — play a session under `looop dev` first, then ?replay=last watches it back' }),
+          'application/json',
+        );
+      }
+    }
+    // The transport shows whatever comes back verbatim, so the two ways this
+    // fails have to be told apart. "There is no such session here" sends the
+    // reader to the machine that played it; a stitcher that refuses (a pinned
+    // engine older than recordings) is a different problem entirely, and
+    // reporting it as a missing recording would have them hunting for files
+    // that are sitting right there.
+    // A recording that arrived as a whole FILE (one pulled from elsewhere, rather
+    // than one this machine recorded) wins over the segments beside it. Read
+    // here rather than served from the static mount, because that mount does
+    // not serve `.looop/` at all — see resolveUrl.
+    const asFile = wholeFilePath(stream);
+    if (existsSync(asFile)) return sendBody(res, 200, readFileSync(asFile), 'application/json');
+    let body = null;
+    try {
+      body = engineSharedDir ? await stitchStream(projectDir, stream, engineSharedDir) : null;
+    } catch (e) {
+      return sendBody(res, 404, JSON.stringify({ error: String(e?.message ?? e) }), 'application/json');
+    }
+    if (!body) {
+      // Two different answers, and sending the wrong one is expensive. A stream
+      // that is HERE but has not cut its first keyframe yet is a not-yet: the
+      // files are on this disk, in front of the person reading. Telling them to
+      // go and find the machine that played it would send them somewhere else
+      // entirely, for a recording that will be watchable in a few seconds.
+      const here = existsSync(join(projectDir, '.looop', 'replays', stream));
+      return sendBody(
+        res,
+        404,
+        JSON.stringify({
+          error: here
+            ? `session ${stream} has not been written far enough to watch yet — a recording becomes watchable a few seconds in, so give it a moment and reload`
+            : `no recording for session ${stream} in this game's .looop/replays/ — it is recorded on the machine that played it`,
+        }),
+        'application/json',
+      );
+    }
+    return sendBody(res, 200, body, 'application/json');
+  }
+
+  // ── the sessions lane: what recordings exist, and what to do with one ─────
+  //
+  // The person who just played is holding a browser, and on a phone that is the
+  // only surface there is — so the list of their own recordings has to be
+  // answerable to the page. It rides the same `/__looop/` lane the segments
+  // arrive on rather than a mount of its own, because `.looop/` is deliberately
+  // not served as files (see resolveUrl) and must not start being.
+  //
+  //   GET    /__looop/replays              every recording, newest first
+  //   DELETE /__looop/replays/<stream>     remove one, whole
+  //   POST   /__looop/replays/<stream>/keep  { keep: bool } — pin against the prune
+  async function handleReplaysApi(req, res, urlPath) {
+    // Deleting a recording and pinning one are destructive and permanent; the
+    // list is a read. So the mutating verbs demand the Origin a browser always
+    // sends, and the read does not — see sameOrigin for why a GET cannot.
+    const mutating = req.method !== 'GET' && req.method !== 'HEAD';
+    if (!sameOrigin(req, { requireOrigin: mutating })) {
+      res.writeHead(403, { 'Content-Type': 'text/plain' });
+      return res.end(mutating
+        ? 'this endpoint is only for the page this dev server serves'
+        : 'cross-origin request rejected');
+    }
+    const rest = urlPath.slice(DEV_REPLAYS_PATH.length);
+    // Deliberately NOT sendBody: that stamps `Access-Control-Allow-Origin: *`
+    // for the static mounts, and on these bodies it would mean the origin check
+    // above is the only thing between a cross-origin page and a creator's
+    // session list — no second layer at all.
+    const json = (status, body) => {
+      const buf = Buffer.from(JSON.stringify(body));
+      res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': buf.length,
+        'Cache-Control': 'no-store, must-revalidate',
+      });
+      res.end(buf);
+    };
+
+    if (rest === '' || rest === '/') {
+      if (req.method !== 'GET') {
+        res.writeHead(405, { 'Content-Type': 'text/plain' });
+        return res.end('405');
+      }
+      return json(200, { recordings: listRecordings(projectDir) });
+    }
+
+    const m = /^\/([^/]+)(\/keep)?$/.exec(rest);
+    if (!m) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      return res.end('404');
+    }
+    // The id came off a URL and is about to become a path. `streamDir` is the
+    // one place that decides what a stream id may look like, and it refuses
+    // rather than sanitizes — so a bad id is a 400 with its reason, not a
+    // plausible directory somewhere else.
+    let stream;
+    try {
+      stream = decodeURIComponent(m[1]);
+      streamDir(projectDir, stream);
+    } catch (e) {
+      return json(400, { error: String(e?.message ?? e) });
+    }
+
+    if (m[2]) {
+      if (req.method !== 'POST') {
+        res.writeHead(405, { 'Content-Type': 'text/plain' });
+        return res.end('405');
+      }
+      const chunks = [];
+      let size = 0;
+      for await (const c of req) {
+        size += c.length;
+        if (size > KEEP_MAX_BYTES) {
+          res.writeHead(413, { 'Content-Type': 'text/plain', Connection: 'close' });
+          return res.end('body too large');
+        }
+        chunks.push(c);
+      }
+      let keep;
+      try {
+        keep = JSON.parse(Buffer.concat(chunks).toString('utf8'))?.keep === true;
+      } catch {
+        return json(400, { error: 'expected a JSON body of { keep: true } or { keep: false }' });
+      }
+      if (!setKept(projectDir, stream, keep)) return json(404, { error: `no recording ${stream}` });
+      return json(200, { stream, kept: keep });
+    }
+
+    if (req.method !== 'DELETE') {
+      res.writeHead(405, { 'Content-Type': 'text/plain' });
+      return res.end('405');
+    }
+    if (!deleteRecording(projectDir, stream)) return json(404, { error: `no recording ${stream}` });
+    log(`replays: deleted ${stream}`);
+    return json(200, { stream, deleted: true });
+  }
+
   function handleSse(res) {
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
@@ -264,8 +588,7 @@ export function createStaticServer({
     // client is served from this server, so its Origin equals our host.
     // Non-browser callers (curl, node) send no Origin and pass — same trust
     // level as anything else already running on the creator's machine/LAN.
-    const origin = req.headers.origin;
-    if (origin && origin !== `http://${req.headers.host}`) {
+    if (!sameOrigin(req)) {
       res.writeHead(403, { 'Content-Type': 'text/plain' });
       return res.end('cross-origin post rejected');
     }
@@ -304,6 +627,7 @@ export function createStaticServer({
         mkdirSync(inboxDir, { recursive: true });
         const selfIgnore = join(inboxDir, '.gitignore');
         if (!existsSync(selfIgnore)) writeFileSync(selfIgnore, '*\n');
+        if (engineVersion) envelope.engine = engineVersion;
         const d = new Date();
         const p = (n, w = 2) => String(n).padStart(w, '0');
         const stamp = `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}-${p(d.getMinutes())}-${p(d.getSeconds())}-${p(d.getMilliseconds(), 3)}`;
@@ -338,6 +662,49 @@ export function createStaticServer({
         'application/json',
       );
     }
+    // The dev recording lane. A room posts its closed segments here and they
+    // land in the game's .looop/replays/ — no auth, because in dev the room,
+    // the folder and the player are the same machine and nothing crosses a
+    // trust boundary. A published room has no ingest lane at all yet (see
+    // sessionIngestUrlFor) and never reaches this.
+    if (urlPath === DEV_SEGMENT_PATH) {
+      if (!projectDir) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        return res.end('404');
+      }
+      if (req.method !== 'POST') {
+        res.writeHead(405, { 'Content-Type': 'text/plain' });
+        return res.end('405');
+      }
+      return receiveSegment(req, res);
+    }
+    if (projectDir && (urlPath === DEV_REPLAYS_PATH || urlPath.startsWith(`${DEV_REPLAYS_PATH}/`))) {
+      // Caught here because this handler is async and its promise is returned,
+      // not awaited: an unhandled rejection inside it takes the whole dev server
+      // down, with the creator's game on it. The panel polls this route every
+      // few seconds while a prune, or a delete from another tab, can be removing
+      // the very directories it is walking — so a transient ENOENT is a normal
+      // event on this lane, not an exceptional one.
+      return handleReplaysApi(req, res, urlPath).catch((e) => {
+        log(`replays: ${e?.message ?? e}`);
+        if (res.headersSent) return res.end();
+        return sendBody(res, 500, JSON.stringify({ error: String(e?.message ?? e) }), 'application/json');
+      });
+    }
+    const replayMatch = projectDir && req.method === 'GET' && REPLAY_URL_RE.exec(urlPath);
+    if (replayMatch) {
+      // Same-origin only, for what it carries (see the `.looop/` note in
+      // resolveUrl). A browser sends Origin on a cross-origin GET of a
+      // fetch/XHR; the game page fetching its own recording does not, or sends
+      // ours. Non-browser callers pass, at the same trust level as anything
+      // else already running on the machine.
+      if (!sameOrigin(req)) {
+        res.writeHead(403, { 'Content-Type': 'text/plain' });
+        return res.end('cross-origin read rejected');
+      }
+      return serveReplay(res, replayMatch[1]);
+    }
+
     if (urlPath === '/' || urlPath === '/index.html') {
       res.writeHead(302, { Location: gameEntry });
       return res.end();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,6 +22,7 @@
   "dependencies": {
     "cross-spawn": "^7.0.6",
     "esbuild": "^0.28.0",
+    "hyparquet-writer": "^0.16.9",
     "partykit": "^0.0.115"
   }
 }