@hajimism/dek 0.1.0

package/src/server/auth.ts

@@ -0,0 +1,210 @@
+import { timingSafeEqual } from "node:crypto";
+import { hostname } from "node:os";
+import type { LiveEventType } from "../core/live-protocol.ts";
+
+/**
+ * Requests the dev server refuses before routing. A local server answers only to a loopback Host,
+ * so a page on another site cannot reach it by pointing its own name at 127.0.0.1 (DNS
+ * rebinding); a --remote one also to an address or this machine's own name, which is what the
+ * audience types, and to no other DNS name, which could be an attacker's. Anything that moves the deck, a WebSocket or a POST, must come from the deck's own
+ * origin or from no browser at all: `dekc goto` sends no Origin. A path that does not decode names
+ * nothing, so no route has to guard its own decodeURIComponent.
+ */
+export function requestGuard(req: Request, options: { remote: boolean }): Response | undefined {
+  let url: URL;
+  try {
+    url = new URL(req.url);
+  } catch {
+    // An HTTP/1.0 request can come with no Host at all.
+    return new Response("Bad Request: no Host\n", { status: 400 });
+  }
+  if (!servesHost(url.hostname, options.remote)) {
+    return forbidden(
+      options.remote
+        ? "unexpected Host; open the dev server at its address or this machine's name"
+        : "unexpected Host; open the dev server at 127.0.0.1 or localhost",
+    );
+  }
+  if (!decodes(url.pathname)) {
+    return new Response("Bad Request: malformed percent-encoding\n", { status: 400 });
+  }
+  const origin = req.headers.get("origin");
+  const moves = req.method !== "GET" || req.headers.get("upgrade")?.toLowerCase() === "websocket";
+  if (moves && origin !== null && !sameOrigin(origin, url)) {
+    return forbidden("cross-origin request");
+  }
+  return undefined;
+}
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"]);
+
+function servesHost(name: string, remote: boolean): boolean {
+  if (LOOPBACK_HOSTS.has(name)) {
+    return true;
+  }
+  if (!remote) {
+    return false;
+  }
+  const machine = hostname()
+    .toLowerCase()
+    .replace(/\.local$/, "");
+  return (
+    /^\d{1,3}(\.\d{1,3}){3}$/.test(name) ||
+    /^\[[0-9a-f:.]+\]$/i.test(name) ||
+    name === machine ||
+    name === `${machine}.local`
+  );
+}
+
+function sameOrigin(origin: string, url: URL): boolean {
+  try {
+    return new URL(origin).origin === url.origin;
+  } catch {
+    // "null" from a file:// page or a sandboxed frame is no origin of ours.
+    return false;
+  }
+}
+
+function decodes(pathname: string): boolean {
+  try {
+    decodeURIComponent(pathname);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function forbidden(reason: string): Response {
+  return new Response(`Forbidden: ${reason}\n`, { status: 403 });
+}
+
+/**
+ * Who may read a response. The audience sees the slides as they are shown; the presenter also
+ * sees what they are made from, and may move the deck.
+ */
+export type Exposure = "audience" | "presenter";
+
+/**
+ * What each dev server route reveals. The script, its notes, the voice read from it, moving the
+ * deck, and the marks left on its beats belong to the presenter. The server routes only by these names, so a new route does
+ * not compile until it is placed here.
+ */
+export const ROUTE_EXPOSURE = {
+  index: "audience",
+  player: "audience",
+  presenter: "presenter",
+  slide: "audience",
+  theme: "audience",
+  asset: "audience",
+  events: "audience",
+  socket: "audience",
+  voice: "presenter",
+  control: "presenter",
+  marks: "presenter",
+  missing: "audience",
+} as const satisfies Record<string, Exposure>;
+
+export type Route = keyof typeof ROUTE_EXPOSURE;
+
+/**
+ * What each `/events` message reveals. Diagnostics quote the script and name files on disk; the
+ * timeline follows the voice. A Record over every event type, so a new one must be placed here.
+ */
+export const EVENT_EXPOSURE: Record<LiveEventType, Exposure> = {
+  sync: "audience",
+  "reload-slide": "audience",
+  "reload-theme": "audience",
+  "reload-script": "audience",
+  diagnostics: "presenter",
+  timeline: "presenter",
+};
+
+/** True when a request cleared for `seen` may read what `exposure` names. */
+export function mayRead(seen: Exposure, exposure: Exposure): boolean {
+  return exposure === "audience" || seen === "presenter";
+}
+
+/** The cookie a paired phone holds instead of the password: its name, and the value it carries. */
+export type PresenterSession = { name: string; secret: string };
+
+/**
+ * The most a request may read: everything without a password, and with one, only what matching
+ * HTTP Basic credentials, a `?token=` (a WebSocket cannot send headers), or the cookie a pairing
+ * code left unlock.
+ */
+export function clearance(
+  req: Request,
+  password: string | undefined,
+  session?: PresenterSession,
+): Exposure {
+  if (!password) {
+    return "presenter";
+  }
+  if (session) {
+    const prefix = `${session.name}=`;
+    const value = req.headers
+      .get("cookie")
+      ?.split(/;\s*/)
+      .find((pair) => pair.startsWith(prefix))
+      ?.slice(prefix.length);
+    if (value !== undefined && samePassword(value, session.secret)) {
+      return "presenter";
+    }
+  }
+  const token = new URL(req.url).searchParams.get("token");
+  if (token !== null && samePassword(token, password)) {
+    return "presenter";
+  }
+  const header = req.headers.get("authorization");
+  if (header?.startsWith("Basic ")) {
+    try {
+      const decoded = atob(header.slice("Basic ".length));
+      const colon = decoded.indexOf(":");
+      if (samePassword(colon >= 0 ? decoded.slice(colon + 1) : decoded, password)) {
+        return "presenter";
+      }
+    } catch {
+      /* malformed credentials */
+    }
+  }
+  return "audience";
+}
+
+/**
+ * The answer to `?pair=<code>`: a good code becomes the presenter cookie and a redirect to the
+ * same page without it, so the code leaves the address bar and the history. Lax, not Strict:
+ * a phone opens the link from its camera, and a Strict cookie would miss the redirect after.
+ */
+export function pairingResponse(url: URL, redeemed: boolean, session: PresenterSession): Response {
+  if (!redeemed) {
+    return new Response(
+      "This QR code was used already or has expired; press Enter in the terminal where dek runs for a new one.\n",
+      { status: 403, headers: { "content-type": "text/plain; charset=utf-8" } },
+    );
+  }
+  const next = new URL(url);
+  next.searchParams.delete("pair");
+  return new Response(null, {
+    status: 303,
+    headers: {
+      location: `${next.pathname}${next.search}`,
+      "set-cookie": `${session.name}=${session.secret}; Path=/; HttpOnly; SameSite=Lax; Max-Age=43200`,
+      "cache-control": "no-store",
+    },
+  });
+}
+
+/** The answer to a request for a presenter route without the password: ask the browser for it. */
+export function unauthorized(): Response {
+  return new Response("Unauthorized\n", {
+    status: 401,
+    headers: { "WWW-Authenticate": 'Basic realm="dek presenter"' },
+  });
+}
+
+/** Compare in constant time, so response timing does not leak how much of a guess was right. */
+function samePassword(given: string, expected: string): boolean {
+  const a = new TextEncoder().encode(given);
+  const b = new TextEncoder().encode(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/src/server/deck-snapshot.ts

@@ -0,0 +1,146 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { deckPaths } from "../core/deck-paths.ts";
+import type { LiveEvent } from "../core/live-protocol.ts";
+import { listSlideFiles, type SlideSidecar } from "../core/resolve.ts";
+
+/** Modification times by name; a file that is gone is left out. */
+export type Mtimes = Record<string, number>;
+
+/** What a deck watcher compares between scans: the mtime of every file a page is made from. */
+export type DeckSnapshot = {
+  script: number;
+  theme: number;
+  /** `slides/<slug>.html`, and each sidecar kind, keyed by slug. */
+  slides: Mtimes;
+  styles: Mtimes;
+  scripts: Mtimes;
+  /** `.js` scripts, which dek does not load but lint names so the author can rename them. */
+  javascript: Mtimes;
+  /** `voice/voice.toml`, `voice/dict.toml`, and `voice/pin/*`. */
+  voice: Mtimes;
+};
+
+/** Which slides to lint: one slug, or the whole deck when it is left out. */
+export type DiagnoseScope = { slug?: string };
+
+/** What one scan found to do. */
+export type DeckChange = {
+  /** The script changed: sync its slides first. */
+  sync: boolean;
+  events: LiveEvent[];
+  diagnose?: DiagnoseScope;
+  synth: boolean;
+};
+
+export function takeSnapshot(deckDir: string): DeckSnapshot {
+  const paths = deckPaths(deckDir);
+  return {
+    script: mtime(paths.script),
+    theme: mtime(paths.theme),
+    slides: slideMtimes(deckDir),
+    styles: slideMtimes(deckDir, ".css"),
+    scripts: slideMtimes(deckDir, ".ts"),
+    javascript: slideMtimes(deckDir, ".js"),
+    voice: voiceMtimes(paths.voice),
+  };
+}
+
+/**
+ * What changed from `prev` to `next`, as the events a page hears and the work that follows.
+ * Any change counts, an older mtime too: a file restored from a copy is still an edit.
+ */
+export function diffSnapshot(prev: DeckSnapshot, next: DeckSnapshot): DeckChange {
+  const events: LiveEvent[] = [];
+  let diagnose: DiagnoseScope | undefined;
+  const lint = (scope: DiagnoseScope): void => {
+    diagnose = mergeScope(diagnose, scope);
+  };
+
+  const sync = next.script !== prev.script;
+  if (sync) {
+    lint({});
+  }
+  if (next.theme !== prev.theme || changedKeys(prev.styles, next.styles).length > 0) {
+    events.push({ type: "reload-theme" });
+    lint({});
+  }
+  // Slide scripts register once at page load, so a change reloads the page.
+  const scripts = changedKeys(prev.scripts, next.scripts);
+  if (scripts.length > 0) {
+    events.push({ type: "reload-script", slugs: scripts });
+    lint({});
+  }
+  if (changedKeys(prev.javascript, next.javascript).length > 0) {
+    lint({});
+  }
+  // A sync reloads the whole page, and the slides it writes are no edit of the author's.
+  if (!sync) {
+    const removed = Object.keys(prev.slides).filter((slug) => !(slug in next.slides));
+    if (removed.length > 0) {
+      events.push({ type: "sync", created: [], removed });
+      lint({});
+    }
+    for (const [slug, time] of Object.entries(next.slides)) {
+      if (time !== prev.slides[slug]) {
+        events.push({ type: "reload-slide", slug });
+        lint({ slug });
+      }
+    }
+  }
+  const synth = sync || changedKeys(prev.voice, next.voice).length > 0;
+  return { sync, events, ...(diagnose ? { diagnose } : {}), synth };
+}
+
+/** One slide stays one slide; two different ones, or the whole deck, lint the whole deck. */
+export function mergeScope(a: DiagnoseScope | undefined, b: DiagnoseScope): DiagnoseScope {
+  if (!a) {
+    return b;
+  }
+  return a.slug !== undefined && a.slug === b.slug ? a : {};
+}
+
+/** Mtimes of `slides/<slug><ext>`, keyed by slug; the same files lint and render read. */
+export function slideMtimes(
+  deckDir: string,
+  ext: ".html" | ".js" | SlideSidecar = ".html",
+): Mtimes {
+  return Object.fromEntries(
+    listSlideFiles(deckDir, ext).map((file) => [file.slug, mtime(file.path)]),
+  );
+}
+
+function voiceMtimes(dir: string): Mtimes {
+  const times: Mtimes = {};
+  if (!existsSync(dir)) {
+    return times;
+  }
+  for (const name of ["voice.toml", "dict.toml"]) {
+    const path = join(dir, name);
+    if (existsSync(path)) {
+      times[name] = mtime(path);
+    }
+  }
+  const pinDir = join(dir, "pin");
+  if (!existsSync(pinDir)) {
+    return times;
+  }
+  for (const name of readdirSync(pinDir)) {
+    times[`pin/${name}`] = mtime(join(pinDir, name));
+  }
+  return times;
+}
+
+/** Keys whose mtime changed, including files added or removed. */
+function changedKeys(previous: Mtimes, next: Mtimes): string[] {
+  const keys = new Set([...Object.keys(previous), ...Object.keys(next)]);
+  return [...keys].filter((key) => (previous[key] ?? 0) !== (next[key] ?? 0)).sort();
+}
+
+function mtime(path: string): number {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}

package/src/server/dev.ts

@@ -0,0 +1,251 @@
+import { join } from "node:path";
+import { DekError } from "../core/error.ts";
+import type { PlaywrightRunner } from "../core/playwright.ts";
+import { locateDeck, type Project, resolveProject } from "../core/resolve.ts";
+import { liveReloadScript, playerScript } from "../runtime/player.ts";
+import {
+  clearance,
+  mayRead,
+  pairingResponse,
+  ROUTE_EXPOSURE,
+  requestGuard,
+  unauthorized,
+} from "./auth.ts";
+import type { EventFeed } from "./hub.ts";
+import { generateRemotePassword, lanUrls } from "./lan.ts";
+import { assertNoDevServer, removeDevServerLock, writeDevServerLock } from "./lock.ts";
+import { createDevPages } from "./pages.ts";
+import { createPairings, type Pairings } from "./pairing.ts";
+import { createProjectWatch } from "./project-watch.ts";
+import { createRooms, type RoomClient } from "./rooms.ts";
+import { type RouteContext, routeRequest, type WsData } from "./routes.ts";
+import { POLL_INTERVAL_MS } from "./watch.ts";
+
+export type DevServer = {
+  url: string;
+  listenHostname: string;
+  remoteUrls: string[];
+  deckDir?: string;
+  decks: string[];
+  close: () => Promise<void>;
+  /** What the decks' watchers report, each event with its deck. */
+  events: EventFeed;
+  /** With --remote: a one-use code for a QR code that lets a phone in as the presenter. */
+  pair?: () => string;
+};
+
+export type DevServerOptions = {
+  cwd: string;
+  deck?: string;
+  port?: number;
+  visual?: boolean;
+  visualRunner?: PlaywrightRunner;
+  remote?: boolean;
+  /** The --remote password, which dek makes; never taken from the user, so never weak. */
+  password?: string;
+  /** How long a pairing code stays good; see PAIRING_TTL_MS. */
+  pairingTtlMs?: number;
+  /** How often the project and each deck are re-scanned for edits fs.watch missed. */
+  pollIntervalMs?: number;
+};
+
+/** Who may reach the server, and how a presenter proves who they are. */
+type Access = {
+  remote: boolean;
+  listenHostname: string;
+  password: string | undefined;
+  pairings: Pairings | undefined;
+  /** What a paired phone's cookie carries: new on every start, so a restart ends every pairing. */
+  sessionSecret: string;
+};
+
+/** What the routes read, all but the socket upgrade, which needs the listening server. */
+type ServedRoutes = Omit<RouteContext, "upgrade">;
+
+export async function startDevServer(options: DevServerOptions): Promise<DevServer> {
+  const project = resolveProject(options.cwd);
+  // Before the port and the watchers; writing the lock checks again, for a server that raced us.
+  assertNoDevServer(project.root);
+  const { scopedDeckName, deckDir } = serverScope(project, options);
+  const access = accessFor(options);
+  const embed = {
+    playerScript: await playerScript(),
+    liveReloadScript: liveReloadScript(),
+  };
+
+  const pages = createDevPages({
+    embed,
+    remote: access.remote,
+    password: access.password,
+    project: () => watch.project(),
+  });
+  const rooms = createRooms<RoomClient>(() => watch.project().decks);
+  const watch = createProjectWatch({
+    root: options.cwd,
+    project,
+    ...(scopedDeckName ? { scopedDeckName } : {}),
+    visual: options.visual === true,
+    ...(options.visualRunner ? { visualRunner: options.visualRunner } : {}),
+    pollIntervalMs: options.pollIntervalMs ?? POLL_INTERVAL_MS,
+    onChange: () => {
+      pages.clear();
+      // A script edit may have removed the slide or beat a room stood at.
+      rooms.reclamp();
+    },
+  });
+  const routes: ServedRoutes = {
+    ...(scopedDeckName ? { scopedDeckName } : {}),
+    ...(deckDir ? { deckDir } : {}),
+    project: watch.project,
+    hub: watch.hub,
+    rooms,
+    deckPage: pages.deckPage,
+    indexPage: pages.indexPage,
+  };
+
+  let server: Bun.Server<WsData>;
+  try {
+    server = listen(options.port, access, routes);
+  } catch (error) {
+    watch.close();
+    throw listenError(error, options.port);
+  }
+
+  const port = server.port ?? 0;
+  const url = `http://127.0.0.1:${port}/`;
+  const remoteUrls = [...new Set([url, ...(access.remote ? lanUrls(port) : [])])];
+  try {
+    writeDevServerLock(project.root, url, access.password, scopedDeckName);
+  } catch (error) {
+    watch.close();
+    await server.stop(true);
+    throw error;
+  }
+
+  const { pairings } = access;
+  return {
+    url,
+    listenHostname: access.listenHostname,
+    remoteUrls,
+    ...(deckDir ? { deckDir } : {}),
+    decks: project.decks.map((deck) => deck.name),
+    events: { listen: watch.hub.listen },
+    ...(pairings ? { pair: () => pairings.issue() } : {}),
+    async close() {
+      removeDevServerLock(project.root);
+      // Connections first: Bun never finishes stopping once two or more SSE streams were closed.
+      await server.stop(true);
+      watch.close();
+    },
+  };
+}
+
+/** The deck the server is scoped to, by --deck or by the directory it started in, if any. */
+function serverScope(
+  project: Project,
+  options: DevServerOptions,
+): { scopedDeckName: string | undefined; deckDir: string | undefined } {
+  const fromCwd = locateDeck(project.root, options.cwd);
+  const scopedDeckName = options.deck ?? fromCwd?.name;
+  if (options.deck) {
+    assertKnownDeck(project, options.deck);
+  }
+  const deckDir = scopedDeckName ? join(project.root, "decks", scopedDeckName) : fromCwd?.dir;
+  return { scopedDeckName, deckDir };
+}
+
+/** A deck that failed to parse is still one to serve: its page shows why. */
+function assertKnownDeck(project: Project, name: string): void {
+  const known =
+    project.decks.some((entry) => entry.name === name) ||
+    project.failed.some((entry) => entry.name === name);
+  if (!known) {
+    throw new DekError(`deck "${name}" not found`, {
+      path: join(project.root, "decks", name),
+      hint: "run `dekc ls`",
+    });
+  }
+}
+
+function accessFor(options: DevServerOptions): Access {
+  const remote = options.remote === true;
+  return {
+    remote,
+    listenHostname: remote ? "0.0.0.0" : "127.0.0.1",
+    // An empty one would open the presenter to the LAN.
+    password: remote ? options.password || generateRemotePassword() : options.password,
+    pairings: remote
+      ? createPairings(options.pairingTtlMs !== undefined ? { ttlMs: options.pairingTtlMs } : {})
+      : undefined,
+    sessionSecret: generateRemotePassword(32),
+  };
+}
+
+function listen(port: number | undefined, access: Access, routes: ServedRoutes) {
+  return Bun.serve<WsData>({
+    hostname: access.listenHostname,
+    port: port ?? 0,
+    // Never Bun's development error page: it shows the source and absolute paths to anyone.
+    development: false,
+    fetch: (req, server) => answer(req, server, access, routes),
+    error(error) {
+      console.error(error);
+      return new Response("Internal Server Error\n", { status: 500 });
+    },
+    websocket: roomSockets(routes.rooms),
+  });
+}
+
+/** Refuse what the guard refuses, redeem a pairing code, then route what the request may read. */
+function answer(req: Request, server: Bun.Server<WsData>, access: Access, routes: ServedRoutes) {
+  const refused = requestGuard(req, { remote: access.remote });
+  if (refused) {
+    return refused;
+  }
+  // Per port: a phone may pair with two dek servers on one machine.
+  const session = { name: `dek-presenter-${server.port}`, secret: access.sessionSecret };
+  const { pairings } = access;
+  const code = pairings && new URL(req.url).searchParams.get("pair");
+  if (pairings && typeof code === "string") {
+    return pairingResponse(new URL(req.url), pairings.redeem(code), session);
+  }
+  const routed = routeRequest(req, {
+    ...routes,
+    upgrade: (request, data) => server.upgrade(request, { data }),
+  });
+  const seen = clearance(req, access.password, access.remote ? session : undefined);
+  if (!mayRead(seen, ROUTE_EXPOSURE[routed.route])) {
+    return unauthorized();
+  }
+  return routed.respond(seen);
+}
+
+/** Each socket joins its deck's room; only a presenter's socket may move it or point in it. */
+function roomSockets(rooms: RouteContext["rooms"]): Bun.WebSocketHandler<WsData> {
+  return {
+    // A position or a point is a few dozen bytes; anything near this is neither.
+    maxPayloadLength: 4 * 1024,
+    open(ws) {
+      rooms.join(ws.data.room, ws);
+    },
+    message(ws, message) {
+      if (!ws.data.control) {
+        return;
+      }
+      const payload = typeof message === "string" ? message : new TextDecoder().decode(message);
+      rooms.relay(ws.data.room, ws, payload);
+    },
+    close(ws) {
+      rooms.leave(ws.data.room, ws);
+    },
+  };
+}
+
+function listenError(error: unknown, port: number | undefined): unknown {
+  if (port && (error as { code?: string } | null)?.code === "EADDRINUSE") {
+    return new DekError(`port ${port} is already in use`, {
+      hint: "pass another --port, or omit it to let the OS choose",
+    });
+  }
+  return error;
+}