@unifedev/thread-pages 0.3.2 → 1.1.0

package/src/serving/bridge-route.ts

@@ -0,0 +1,23 @@
+import type { Context } from "hono";
+import { failure } from "../domain/capabilities/protocol.ts";
+import { PageError } from "../domain/errors.ts";
+import { LIMITS } from "../domain/limits.ts";
+import { readJsonBody } from "./action-request.ts";
+import type { createDispatcher } from "./bridge/dispatcher.ts";
+import { jsonResponse } from "./responses.ts";
+
+/** `POST /bridge` — one capability invocation. */
+export function bridgeRoute(dispatch: ReturnType<typeof createDispatcher>) {
+  return async (context: Context): Promise<Response> => {
+    let body: unknown;
+    try {
+      body = await readJsonBody(context, LIMITS.capabilityPayloadBytes + 8_192);
+    } catch (error) {
+      const failed = PageError.is(error) ? error : new PageError("invalid_json", "Invalid bridge body");
+      const code = failed.code === "request_too_large" ? "request_too_large" : "invalid_json";
+      return jsonResponse({ response: failure(undefined, code, failed.message) }, failed.status);
+    }
+    const outcome = await dispatch(body);
+    return jsonResponse(outcome.body, outcome.status);
+  };
+}

package/src/serving/context.ts

@@ -0,0 +1,34 @@
+import type { CapabilityRegistry } from "../domain/capabilities/registry.ts";
+import type { RateLimiter } from "../domain/rate-limit.ts";
+import type { OutcomeMemory } from "../domain/submissions/idempotency.ts";
+import type { LiveSettings } from "../config/settings.ts";
+import type { SessionHost } from "../host/contract.ts";
+import type { PageStore } from "../pages/page-store.ts";
+import type { SiteStrategy } from "../pages/site.ts";
+import type { SelectionStore } from "./bridge/selection-store.ts";
+
+/** Everything a route or handler may need, assembled once by the composition root. */
+export interface ServingContext {
+  readonly host: SessionHost;
+  readonly pages: PageStore;
+  readonly settings: LiveSettings;
+  readonly signingKey: Uint8Array;
+  readonly site: SiteStrategy;
+  readonly routeBase: string;
+  readonly registry: CapabilityRegistry;
+  readonly rate: RateLimiter;
+  readonly submissions: OutcomeMemory<{ status: number; body: Record<string, unknown> }>;
+  readonly replies: OutcomeMemory<{ delivery: "started" | "queued" | "steered" }>;
+  readonly selections: SelectionStore;
+  /** The host application's URL for a session's conversation, origin-relative. */
+  readonly hostSessionUrl: (session: string) => string;
+  readonly now: () => number;
+}
+
+export function pageUrl(routeBase: string, session: string): string {
+  return `${routeBase}/page?session=${encodeURIComponent(session)}`;
+}
+
+export function homeUrl(routeBase: string): string {
+  return `${routeBase}/home`;
+}

package/src/serving/document-route.ts

@@ -0,0 +1,37 @@
+import type { Context } from "hono";
+import { injectKernel } from "../domain/html/document.ts";
+import { etagFor, ifNoneMatchMatches } from "../domain/revision.ts";
+import { KERNEL_RUNTIME } from "../generated/kernel-runtime.ts";
+import type { KernelConfig } from "../runtime/shared/protocol.ts";
+import type { ServingContext } from "./context.ts";
+import { baseHeaders, documentCsp, failureResponse } from "./responses.ts";
+import { eligibleSession, sessionIdFrom } from "./session-access.ts";
+
+/**
+ * `GET /document?session=<id>` — the entry document with the kernel injected,
+ * and the shell's revision poll: the ETag is the revision, the activity and
+ * source state ride along as headers. spec R2.11–R2.13, R2.17, R2.25
+ */
+export function documentRoute(serving: ServingContext) {
+  return async (context: Context): Promise<Response> => {
+    try {
+      const id = sessionIdFrom(context);
+      const session = await eligibleSession(serving, id);
+      const page = await serving.pages.load(id);
+      const headers = baseHeaders("text/html; charset=utf-8");
+      headers.set("content-security-policy", documentCsp());
+      headers.set("etag", etagFor(page.revision));
+      headers.set("x-thread-page-stale", String(page.stale));
+      headers.set("x-thread-page-activity", session.state);
+      headers.set("x-thread-page-updated-at", String(page.updatedAtMs));
+      if (ifNoneMatchMatches(context.req.header("if-none-match"), etagFor(page.revision))) {
+        return new Response(null, { status: 304, headers });
+      }
+      const config: KernelConfig = { pageRevision: page.revision, stale: page.stale };
+      const html = injectKernel(page.html, { kernel: KERNEL_RUNTIME, config, baseHref: serving.site.baseHref(id) });
+      return new Response(html, { status: 200, headers });
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "GET /document", true);
+    }
+  };
+}

package/src/serving/home-route.ts

@@ -0,0 +1,23 @@
+import type { Context } from "hono";
+import { isSessionId } from "../domain/ids.ts";
+import type { ServingContext } from "./context.ts";
+import { pageUrl } from "./context.ts";
+import { errorPage } from "./responses.ts";
+
+/** `GET /home` — a redirect to the designated home page, never a listing. spec R7.9, R7.4 */
+export function homeRoute(serving: ServingContext) {
+  return async (_context: Context): Promise<Response> => {
+    const home = serving.settings.current().homeSessionId;
+    if (!isSessionId(home)) {
+      return errorPage(
+        "No home page is set yet. A home page is an ordinary page some agent built and designated. To get one, ask any agent: “Set up my Thread Pages home page” — it runs `bb thread-page home` in a session dedicated to it and builds a hub of your sessions there. Or run `bb thread-page home` yourself in the session whose page should be home.",
+        404,
+      );
+    }
+    const session = await serving.host.sessions.get(home).catch(() => null);
+    if (!session || session.deleted || session.archived) {
+      return errorPage("The home page points at a session that no longer exists. Run `bb thread-page home` in another session, or `bb thread-page home --clear`.", 404);
+    }
+    return new Response(null, { status: 302, headers: { location: pageUrl(serving.routeBase, home), "cache-control": "no-store, max-age=0" } });
+  };
+}

package/src/serving/responses.ts

@@ -0,0 +1,81 @@
+import { PageError, errorText } from "../domain/errors.ts";
+import { escapeHtml } from "../domain/html/escape.ts";
+import type { HostLogger } from "../host/types.ts";
+
+/** Response helpers and the two content security policies. spec R2.41–R2.43, 03 */
+
+export function baseHeaders(contentType: string): Headers {
+  return new Headers({
+    "cache-control": "no-store, max-age=0",
+    "content-type": contentType,
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff",
+    "permissions-policy": "camera=(), microphone=(), geolocation=(), payment=(), usb=()",
+  });
+}
+
+/** The trusted shell: nothing runs but our nonced script and style. */
+export function shellCsp(nonce: string): string {
+  return [
+    "default-src 'none'",
+    "base-uri 'none'",
+    "connect-src 'self'",
+    "form-action 'none'",
+    "frame-ancestors 'self'",
+    "frame-src 'self'",
+    `script-src 'nonce-${nonce}'`,
+    `style-src 'nonce-${nonce}'`,
+    "img-src 'self' data:",
+  ].join("; ");
+}
+
+/**
+ * The document: open network and arbitrary code (spec R3.4, R3.11), no
+ * frames (embedding is deferred), no plugins, same-origin bases only, and
+ * the sandbox restated so it holds even if the frame attribute did not.
+ */
+export function documentCsp(): string {
+  return [
+    "default-src * data: blob: 'unsafe-inline' 'unsafe-eval'",
+    "script-src * data: blob: 'unsafe-inline' 'unsafe-eval'",
+    "style-src * data: blob: 'unsafe-inline'",
+    "img-src * data: blob:",
+    "font-src * data: blob:",
+    "media-src * data: blob:",
+    "connect-src * data: blob:",
+    "worker-src * blob: data:",
+    "frame-src 'none'",
+    "child-src blob:",
+    "object-src 'none'",
+    "base-uri 'self'",
+    "sandbox allow-scripts allow-forms",
+  ].join("; ");
+}
+
+export function jsonResponse(value: unknown, status = 200, extra?: Record<string, string>): Response {
+  const headers = baseHeaders("application/json; charset=utf-8");
+  for (const [key, entry] of Object.entries(extra ?? {})) headers.set(key, entry);
+  return new Response(JSON.stringify(value), { status, headers });
+}
+
+export function errorJson(error: PageError): Response {
+  return jsonResponse({ ok: false, code: error.code, message: error.message }, error.status);
+}
+
+export function errorPage(message: string, status: number): Response {
+  const headers = baseHeaders("text/html; charset=utf-8");
+  headers.set("content-security-policy", "default-src 'none'; style-src 'unsafe-inline'; sandbox");
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Thread Page</title><style>body{max-width:42rem;margin:4rem auto;padding:0 1rem;font:16px/1.5 system-ui,sans-serif;color:CanvasText;background:Canvas}h1{font-size:1.4rem}</style></head><body><main><h1>Thread Page</h1><p>${escapeHtml(message)}</p></main></body></html>`;
+  return new Response(html, { status, headers });
+}
+
+/** Turns any failure into a response, logging the cause when it is not a page error. */
+export function failureResponse(error: unknown, log: HostLogger, where: string, asPage: boolean): Response {
+  if (PageError.is(error)) {
+    if (error.cause !== undefined) log.warn(`${where}: ${error.code}: ${errorText(error.cause)}`);
+    return asPage ? errorPage(error.message, error.status) : errorJson(error);
+  }
+  log.warn(`${where}: ${errorText(error)}`);
+  const generic = new PageError("handler_error", "Something went wrong serving this page.");
+  return asPage ? errorPage(generic.message, 500) : errorJson(generic);
+}

package/src/serving/routes.ts

@@ -0,0 +1,26 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { createDispatcher } from "./bridge/dispatcher.ts";
+import { ALL_HANDLERS } from "./bridge/handlers/index.ts";
+import { bridgeRoute } from "./bridge-route.ts";
+import type { ServingContext } from "./context.ts";
+import { documentRoute } from "./document-route.ts";
+import { homeRoute } from "./home-route.ts";
+import { shellRoute } from "./shell-route.ts";
+import { submitRoute } from "./submit-route.ts";
+import { uploadRoute } from "./upload-route.ts";
+
+/**
+ * The route table. spec 02 §Routes
+ *
+ * Every route uses the host's "local" auth: the reader's existing session
+ * with bb, plus the action token where an effect is possible.
+ */
+export function registerRoutes(bb: BbPluginApi, serving: ServingContext): void {
+  const dispatch = createDispatcher(serving, ALL_HANDLERS);
+  bb.http.route("GET", "/page", shellRoute(serving), { auth: "local" });
+  bb.http.route("GET", "/document", documentRoute(serving), { auth: "local" });
+  bb.http.route("GET", "/home", homeRoute(serving), { auth: "local" });
+  bb.http.route("POST", "/submit", submitRoute(serving), { auth: "local" });
+  bb.http.route("POST", "/upload", uploadRoute(serving), { auth: "local" });
+  bb.http.route("POST", "/bridge", bridgeRoute(dispatch), { auth: "local" });
+}

package/src/serving/session-access.ts

@@ -0,0 +1,22 @@
+import type { Context } from "hono";
+import { describeIneligible, ineligibleReason } from "../domain/eligibility.ts";
+import { PageError, PUBLIC_MESSAGES } from "../domain/errors.ts";
+import { isSessionId } from "../domain/ids.ts";
+import type { SessionRecord } from "../host/types.ts";
+import type { ServingContext } from "./context.ts";
+
+/** Shared first steps of every route: which session, does it exist, may it have a page. */
+export function sessionIdFrom(context: Context): string {
+  const url = new URL(context.req.url);
+  const candidate = url.searchParams.get("session") ?? url.searchParams.get("threadId");
+  if (!isSessionId(candidate)) throw new PageError("invalid_session", PUBLIC_MESSAGES.invalidSession);
+  return candidate;
+}
+
+export async function eligibleSession(serving: ServingContext, id: string): Promise<SessionRecord> {
+  const session = await serving.host.sessions.get(id);
+  if (!session) throw new PageError("not_found", "That session does not exist.");
+  const reason = ineligibleReason(session);
+  if (reason) throw new PageError("ineligible", `${PUBLIC_MESSAGES.ineligible} (${describeIneligible(reason)}.)`);
+  return session;
+}

package/src/serving/shell-html.ts

@@ -0,0 +1,77 @@
+import { escapeHtml } from "../domain/html/escape.ts";
+import { SHELL_RUNTIME } from "../generated/shell-runtime.ts";
+import type { ShellConfig } from "../runtime/shared/protocol.ts";
+
+/**
+ * The trusted shell document: title bar, home link, working indicator,
+ * status, reload control, the sandboxed frame and the confirmation dialog.
+ * Identical wherever the page is read. spec R2.14–R2.16
+ */
+export interface ShellView {
+  nonce: string;
+  title: string;
+  homeUrl: string | null;
+  working: boolean;
+  config: ShellConfig;
+}
+
+const SHELL_CSS = `
+:root{color-scheme:light dark;font:14px/1.4 ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;--bg:#f7f7f5;--surface:#fff;--ink:#17181b;--muted:#676c75;--line:#dfe0e3;--accent:#315fc5;--warn:#a54312}
+@media(prefers-color-scheme:dark){:root{--bg:#111216;--surface:#191b20;--ink:#eeeef0;--muted:#a5a9b1;--line:#30333a;--accent:#91aff1;--warn:#efa879}}
+*{box-sizing:border-box}html,body{height:100%;margin:0;background:var(--bg);color:var(--ink)}
+.shell{display:grid;grid-template-rows:auto 1fr;height:100%;min-height:100dvh}
+.bar{display:flex;align-items:center;gap:.75rem;min-height:2.5rem;padding:.45rem max(.7rem,env(safe-area-inset-right)) .45rem max(.7rem,env(safe-area-inset-left));border-bottom:1px solid var(--line);background:var(--surface)}
+.home{flex:none;color:var(--muted);text-decoration:none;font-weight:600;white-space:nowrap}.home:hover{color:var(--ink)}
+.title{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-weight:600}
+.status{margin-left:auto;color:var(--muted);text-align:right}.status[data-tone=warn]{color:var(--warn)}
+.work{flex:none;display:none;align-items:center;gap:.4rem;color:var(--muted)}.work[data-visible=true]{display:inline-flex}
+.work .dot{width:.5rem;height:.5rem;border-radius:50%;background:var(--accent)}
+@media(prefers-reduced-motion:no-preference){.work[data-visible=true] .dot{animation:tp-pulse 1.4s ease-in-out infinite}}
+@keyframes tp-pulse{0%,100%{opacity:1}50%{opacity:.25}}
+button.reload{display:none;padding:.25rem .55rem;border:1px solid var(--line);border-radius:.4rem;color:var(--ink);background:var(--bg);cursor:pointer}button.reload[data-visible=true]{display:inline-block}
+iframe{display:block;width:100%;height:100%;border:0;background:var(--bg)}
+dialog{margin:auto;max-width:min(30rem,calc(100vw - 2rem));padding:1.15rem 1.25rem;border:1px solid var(--line);border-radius:.75rem;color:var(--ink);background:var(--surface)}
+dialog::backdrop{background:rgb(0 0 0 / .45)}dialog h2{margin:0 0 .5rem;font-size:1rem}dialog p{margin:0 0 1rem;color:var(--muted);overflow-wrap:anywhere}
+dialog .row{display:flex;gap:.5rem;justify-content:flex-end}dialog button{padding:.4rem .8rem;border:1px solid var(--line);border-radius:.4rem;color:var(--ink);background:var(--bg);cursor:pointer}
+dialog button[value=confirm]{color:#fff;background:var(--accent);border-color:var(--accent)}
+`;
+
+export function renderShell(view: ShellView): string {
+  const title = escapeHtml(view.title);
+  const nonce = escapeHtml(view.nonce);
+  const config = escapeHtml(JSON.stringify(view.config));
+  const working = view.working && view.config.workingLabel ? "true" : "false";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<meta name="color-scheme" content="light dark">
+<title>${title}</title>
+<style nonce="${nonce}">${SHELL_CSS}</style>
+</head>
+<body>
+<div class="shell">
+  <header class="bar">
+    ${view.homeUrl ? `<a class="home" href="${escapeHtml(view.homeUrl)}" title="All sessions">← Sessions</a>` : ""}
+    <span class="title">${title}</span>
+    <span class="work" role="status" data-shell-working data-visible="${working}"><span class="dot" aria-hidden="true"></span><span>${escapeHtml(view.config.workingLabel)}</span></span>
+    <span class="status" role="status" data-shell-status${view.config.stale ? ' data-tone="warn"' : ""}>${view.config.stale ? "Offline copy — read-only" : ""}</span>
+    <button type="button" class="reload" data-shell-reload aria-label="Reload updated page">Reload</button>
+  </header>
+  <iframe title="${title}" sandbox="allow-scripts allow-forms" referrerpolicy="no-referrer"></iframe>
+</div>
+<dialog aria-labelledby="tp-confirm-title">
+  <form method="dialog">
+    <h2 id="tp-confirm-title">Confirm this action</h2>
+    <p></p>
+    <div class="row">
+      <button type="button" value="cancel">Cancel</button>
+      <button type="button" value="confirm">Confirm</button>
+    </div>
+  </form>
+</dialog>
+<script nonce="${nonce}" data-config="${config}">${SHELL_RUNTIME}</script>
+</body>
+</html>`;
+}

package/src/serving/shell-route.ts

@@ -0,0 +1,51 @@
+import { randomBytes } from "node:crypto";
+import type { Context } from "hono";
+import { isSessionId } from "../domain/ids.ts";
+import { LIMITS } from "../domain/limits.ts";
+import { mintActionToken } from "../domain/tokens/action-token.ts";
+import type { ServingContext } from "./context.ts";
+import { homeUrl } from "./context.ts";
+import { baseHeaders, failureResponse, shellCsp } from "./responses.ts";
+import { renderShell } from "./shell-html.ts";
+import { eligibleSession, sessionIdFrom } from "./session-access.ts";
+
+/** `GET /page?session=<id>` — the shell for one page. spec 02 §The shell */
+export function shellRoute(serving: ServingContext) {
+  return async (context: Context): Promise<Response> => {
+    try {
+      const id = sessionIdFrom(context);
+      const session = await eligibleSession(serving, id);
+      const page = await serving.pages.load(id);
+      const now = serving.now();
+      const { token, payload } = mintActionToken({ session: id, revision: page.revision, now }, serving.signingKey);
+      const nonce = randomBytes(18).toString("base64url");
+      const settings = serving.settings.current();
+      const home = isSessionId(settings.homeSessionId) && settings.homeSessionId !== id ? homeUrl(serving.routeBase) : null;
+      const html = renderShell({
+        nonce,
+        title: session.title,
+        homeUrl: home,
+        working: session.state === "working",
+        config: {
+          actionToken: token,
+          pageRevision: page.revision,
+          expiresAt: payload.exp,
+          documentUrl: serving.site.documentUrl(id),
+          submitUrl: `${serving.routeBase}/submit`,
+          uploadUrl: `${serving.routeBase}/upload`,
+          bridgeUrl: `${serving.routeBase}/bridge`,
+          workingLabel: settings.workingLabel,
+          stale: page.stale,
+          pollMs: LIMITS.shellPollMs,
+          maxUploadBytes: LIMITS.uploadFileBytes,
+          maxUploads: LIMITS.uploadsPerForm,
+        },
+      });
+      const headers = baseHeaders("text/html; charset=utf-8");
+      headers.set("content-security-policy", shellCsp(nonce));
+      return new Response(html, { status: 200, headers });
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "GET /page", true);
+    }
+  };
+}

package/src/serving/signing-key.ts

@@ -0,0 +1,25 @@
+import { randomBytes } from "node:crypto";
+import { errorText } from "../domain/errors.ts";
+import type { SessionHost } from "../host/contract.ts";
+
+const KEY = "signing-key:v3";
+
+/** The token signing key: 32 random bytes, generated on first use, persisted, never logged. spec R2.8 */
+export async function loadSigningKey(host: SessionHost): Promise<Uint8Array> {
+  try {
+    const stored = await host.kv.get(KEY);
+    if (typeof stored === "string" && /^[A-Za-z0-9_-]{43}$/.test(stored)) {
+      const decoded = Buffer.from(stored, "base64url");
+      if (decoded.byteLength === 32) return decoded;
+    }
+  } catch (error) {
+    host.log.warn(`signing key: could not read the stored key: ${errorText(error)}`);
+  }
+  const generated = randomBytes(32);
+  try {
+    await host.kv.set(KEY, generated.toString("base64url"));
+  } catch (error) {
+    host.log.warn(`signing key: could not persist; open pages will need a reload after the next plugin reload: ${errorText(error)}`);
+  }
+  return generated;
+}

package/src/serving/submit-route.ts

@@ -0,0 +1,47 @@
+import type { Context } from "hono";
+import { PageError, PUBLIC_MESSAGES } from "../domain/errors.ts";
+import { LIMITS } from "../domain/limits.ts";
+import { sha256Hex } from "../domain/revision.ts";
+import { formatSubmissionMessage } from "../domain/submissions/message.ts";
+import { parseSubmission } from "../domain/submissions/parse.ts";
+import { acquireRate, readJsonBody, requireActionToken } from "./action-request.ts";
+import type { ServingContext } from "./context.ts";
+import { failureResponse, jsonResponse } from "./responses.ts";
+import { eligibleSession } from "./session-access.ts";
+
+/** `POST /submit` — one form submission becomes one message. spec R2.32–R2.37 */
+export function submitRoute(serving: ServingContext) {
+  return async (context: Context): Promise<Response> => {
+    let release: (() => void) | null = null;
+    try {
+      const body = await readJsonBody(context, LIMITS.submissionBodyBytes);
+      const submission = parseSubmission(body);
+      if (!submission) throw new PageError("invalid_request", "Invalid submission");
+      const token = requireActionToken(serving, submission.actionToken);
+      if (submission.pageRevision !== token.revision) throw new PageError("stale_page", PUBLIC_MESSAGES.stalePage);
+      release = acquireRate(serving, token.session);
+      const now = serving.now();
+      const fingerprint = sha256Hex(JSON.stringify({ revision: submission.pageRevision, title: submission.title, answers: submission.answers, files: submission.files }));
+      const remembered = serving.submissions.remember(
+        `${token.session}:${submission.submissionId}`,
+        fingerprint,
+        async () => {
+          await eligibleSession(serving, token.session);
+          const page = await serving.pages.load(token.session);
+          if (page.stale) throw new PageError("unavailable", PUBLIC_MESSAGES.staleCopy);
+          if (page.revision !== token.revision) throw new PageError("stale_page", PUBLIC_MESSAGES.stalePage);
+          const sent = await serving.host.sessions.send(token.session, formatSubmissionMessage(submission), "queue");
+          return { status: 200, body: { ok: true, delivery: sent.delivery } };
+        },
+        now,
+      );
+      if (remembered.kind === "conflict") throw new PageError("conflict", "This submission id was already used with different answers");
+      const outcome = await remembered.outcome;
+      return jsonResponse(outcome.body, outcome.status);
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "POST /submit", false);
+    } finally {
+      release?.();
+    }
+  };
+}

package/src/serving/upload-route.ts

@@ -0,0 +1,46 @@
+import { randomBytes } from "node:crypto";
+import type { Context } from "hono";
+import { PageError, PUBLIC_MESSAGES } from "../domain/errors.ts";
+import { LIMITS, mebibytes } from "../domain/limits.ts";
+import { UPLOAD_DIR, uploadFileName } from "../pages/layout.ts";
+import { acquireRate, readJsonBody, requireActionToken } from "./action-request.ts";
+import type { ServingContext } from "./context.ts";
+import { failureResponse, jsonResponse } from "./responses.ts";
+import { eligibleSession } from "./session-access.ts";
+
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/**
+ * `POST /upload` — one attached file, base64 in a JSON envelope (the host's
+ * "local" auth refuses raw bodies), stored under a host-generated name in the
+ * page's uploads directory. spec R4.19–R4.24
+ */
+export function uploadRoute(serving: ServingContext) {
+  const maxBody = Math.ceil((LIMITS.uploadFileBytes * 4) / 3) + 8_192;
+  return async (context: Context): Promise<Response> => {
+    let release: (() => void) | null = null;
+    try {
+      const body = await readJsonBody(context, maxBody);
+      if (!body || typeof body !== "object" || Array.isArray(body)) throw new PageError("invalid_request", "Invalid upload envelope");
+      const envelope = body as Record<string, unknown>;
+      const token = requireActionToken(serving, envelope.actionToken);
+      if (typeof envelope.content !== "string" || !BASE64.test(envelope.content)) throw new PageError("invalid_request", "Attachment content must be base64");
+      release = acquireRate(serving, token.session);
+      await eligibleSession(serving, token.session);
+      const page = await serving.pages.load(token.session);
+      if (page.stale) throw new PageError("unavailable", PUBLIC_MESSAGES.staleCopy);
+      const bytes = Buffer.from(envelope.content, "base64");
+      if (bytes.byteLength === 0) throw new PageError("invalid_request", "The file is empty");
+      if (bytes.byteLength > LIMITS.uploadFileBytes) throw new PageError("request_too_large", `Attachments must be at most ${mebibytes(LIMITS.uploadFileBytes)}`);
+      const name = uploadFileName(typeof envelope.name === "string" ? envelope.name : "upload", serving.now(), randomBytes(3).toString("hex"));
+      const location = await serving.host.sessions.storage(token.session);
+      const outcome = await serving.host.files.write(location, `${UPLOAD_DIR}/${name}`, bytes, { onlyIfAbsent: true });
+      if (outcome !== "written") throw new PageError("conflict", "The attachment could not be stored under a fresh name; try again");
+      return jsonResponse({ ok: true, name, path: `${UPLOAD_DIR}/${name}`, sizeBytes: bytes.byteLength });
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "POST /upload", false);
+    } finally {
+      release?.();
+    }
+  };
+}

package/tsconfig.json

@@ -1,15 +1,19 @@
 {
   "compilerOptions": {
+    "strict": true,
     "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
+    "types": ["node"],
     "noEmit": true,
+    "skipLibCheck": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
-    "types": ["node"]
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "allowImportingTsExtensions": true
   },
-  "include": ["*.ts"]
+  "include": ["server.ts", "src", "test", "scripts"]
 }