@hienlh/ppm 0.23.14 → 0.23.16

package/src/server/routes/accounts.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import type { Context } from "hono";
-import { accountService } from "../../services/account.service.ts";
+import { accountService, OAuthLinkExpiredError } from "../../services/account.service.ts";
 import { accountSelector } from "../../services/account-selector.service.ts";
 import { pickClaudeAccount } from "../../services/account-pick.service.ts";
 import { updateAccount, getSnapshotHistory } from "../../services/db.service.ts";
@@ -154,7 +154,8 @@ accountsRoutes.post("/oauth/exchange", async (c) => {
     await refreshUsageForAccount(account.id);
     return c.json(ok(account));
   } catch (e) {
-    return c.json(err((e as Error).message), 400);
+    // 410: the link is gone, so the dialog goes back to the step that opens a new one.
+    return c.json(err((e as Error).message), e instanceof OAuthLinkExpiredError ? 410 : 400);
   }
 });
 

package/src/server/routes/chat-file-changes.ts

@@ -2,7 +2,7 @@ import { Hono, type Context } from "hono";
 import { resolve } from "node:path";
 import { ok, err } from "../../types/api.ts";
 import { getSessionProjectPath, resolveMigratedSession } from "../../services/db.service.ts";
-import { isValidBaselineSessionId, keepsSessionWrites } from "../../services/session-file-baselines/session-file-baselines.service.ts";
+import { countBaselines, isValidBaselineSessionId, keepsSessionWrites } from "../../services/session-file-baselines/session-file-baselines.service.ts";
 import {
   lineage,
   MAX_SESSION_CHANGE_PATHS,
@@ -77,6 +77,20 @@ chatFileChangesRoutes.post("/sessions/:id/file-changes", async (c) => {
   }
 });
 
+/**
+ * GET /chat/sessions/:id/file-changes/count
+ *
+ * How many files the session (and those it was branched from) kept a "before" for — an upper
+ * bound on the list, read off directory listings only. The changes bar shows it until the list
+ * itself is asked for, which can take minutes on a session that touched thousands of files.
+ */
+chatFileChangesRoutes.get("/sessions/:id/file-changes/count", (c) => {
+  const sessionId = sessionOf(c);
+  if (typeof sessionId !== "string") return sessionId;
+  const count = lineage(sessionId).reduce((n, id) => n + countBaselines(id), 0);
+  return c.json(ok({ count: Math.min(count, MAX_SESSION_CHANGE_PATHS) }));
+});
+
 /**
  * POST /chat/sessions/:id/file-changes/reviewed { files: { path, version }[], reviewed: boolean }
  *

package/src/server/routes/chat.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { resolve, join, basename } from "node:path";
 import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { unlink } from "node:fs/promises";
+import { resolveSessionDir } from "../../services/subagent-transcript-merger.ts";
 import { countLines } from "../../services/file-lines.ts";
 import { ensureUploadsDir, resolveUploadPath } from "../../services/chat-upload-storage.service.ts";
 import { chatService } from "../../services/chat.service.ts";
@@ -23,6 +24,7 @@ import { bindPickedAccount, bindRefusalReason } from "../../services/picked-acco
 import { getSessionLog } from "../../services/session-log.service.ts";
 import { parseJsonlTranscript, validateJsonlPath } from "../../services/jsonl-transcript-parser.ts";
 import { parseCompactSegment } from "../../services/compact-segment.ts";
+import { assertSessionInProject } from "../../services/agent-transcript/session-ownership.ts";
 import { aggregateTasks } from "../../services/task-status-aggregator.ts";
 import { MANY_IMAGE_DIMENSION_LIMIT, type StripMode } from "../../services/transcript-images.ts";
 import { auditTranscriptImagesFile, stripTranscriptImagesFile } from "../../services/transcript-images-file.ts";
@@ -324,30 +326,80 @@ chatRoutes.get("/sessions/:id/design", (c) => {
 });
 
 /**
- * The full parsed history of recently opened sessions, so the older pages a tab asks for
- * as it scrolls up are sliced from the parse its first page already paid for. Parsing is
- * the expensive part — minutes of CPU for a transcript in the hundreds of MB — and paying
- * it again per page would make scrolling up slower than the old load-everything was.
+ * The parsed history of recently read sessions, reused for as long as the transcript on disk
+ * is the one it was parsed from.
  *
- * Only older-page requests (`before`) read from here; a first page or a refetch always
- * parses afresh, since the transcript may have grown. Small and short-lived on purpose:
- * each entry is a whole session's messages.
+ * Re-reading a transcript is not only slow, it LEAKS on Windows: Bun keeps the memory of a
+ * large read committed after the strings are collected (measured on a 30 MB transcript:
+ * `Bun.file().text()` alone +12 MB a call, a full history read +40 MB, never returned —
+ * mimalloc's purge options change nothing). Every tab open, older page and post-turn refetch
+ * re-parsed, so a day of long chats took the server to 14 GB RSS / 59 GB committed and Bun
+ * aborted. Keyed by what the parse reads — the transcript's size and mtime, its subagent
+ * transcripts, and the fork root's, whose timestamps are overlaid — a session is now parsed
+ * once per change instead of once per ask.
+ *
+ * An older page (`before`) does not need the newest parse: between turns the list only grows
+ * at its end (the paging indexes rely on that), so it reuses the first page's parse for a short
+ * while whatever the stamp says — otherwise every page scrolled up mid-turn, while the file
+ * changes every few seconds, would be a whole parse. Only Claude transcripts are stamped;
+ * anything else is otherwise parsed per request as before.
  */
-const HISTORY_CACHE_TTL_MS = 5 * 60_000;
-const HISTORY_CACHE_MAX = 3;
-const historyCache = new Map<string, { messages: ChatMessage[]; at: number }>();
+const HISTORY_CACHE_MAX = 6;
+const OLDER_PAGE_TTL_MS = 5 * 60_000;
+const historyCache = new Map<string, { stamp: string | null; messages: ChatMessage[]; at: number }>();
 
-function rememberHistory(key: string, messages: ChatMessage[]): void {
+function rememberHistory(key: string, stamp: string | null, messages: ChatMessage[]): void {
   historyCache.delete(key);
-  historyCache.set(key, { messages, at: Date.now() });
+  historyCache.set(key, { stamp, messages, at: Date.now() });
   while (historyCache.size > HISTORY_CACHE_MAX) historyCache.delete(historyCache.keys().next().value!);
 }
 
-function recentHistory(key: string): ChatMessage[] | null {
+function cachedHistory(key: string, stamp: string | null, olderPage: boolean): ChatMessage[] | null {
   const hit = historyCache.get(key);
   if (!hit) return null;
-  if (Date.now() - hit.at > HISTORY_CACHE_TTL_MS) { historyCache.delete(key); return null; }
-  return hit.messages;
+  if (stamp !== null && hit.stamp === stamp) {
+    // Most recently used last, so the cap drops the session read longest ago.
+    historyCache.delete(key);
+    historyCache.set(key, hit);
+    return hit.messages;
+  }
+  if (olderPage && Date.now() - hit.at <= OLDER_PAGE_TTL_MS) return hit.messages;
+  return null;
+}
+
+/**
+ * What a Claude session's parse reads on disk: its transcript, and the subagent transcripts
+ * under `<id>/subagents/` that fill its Agent cards — those keep growing while the main file
+ * sits waiting on an agent (one wrote 545 records through 57 minutes of main-file silence),
+ * so stamping the main file alone froze a card on reload. Null when there is no transcript.
+ */
+function claudeTranscriptStamp(sessionId: string): string | null {
+  const dir = resolveSessionDir(sessionId, getSessionProjectPath(sessionId));
+  if (!dir) return null;
+  try {
+    const s = statSync(`${dir}.jsonl`);
+    let n = 0, bytes = 0, newest = 0;
+    try {
+      for (const f of readdirSync(join(dir, "subagents"))) {
+        const a = statSync(join(dir, "subagents", f));
+        n++; bytes += a.size; newest = Math.max(newest, a.mtimeMs);
+      }
+    } catch { /* no subagents/ yet */ }
+    return `${s.size}:${s.mtimeMs}:${n}:${bytes}:${newest}`;
+  } catch {
+    return null;
+  }
+}
+
+/** What the parsed history depends on on disk; null when that cannot be told. */
+function historyStamp(providerId: string, id: string): string | null {
+  if (providerId !== "claude") return null;
+  const own = claudeTranscriptStamp(id);
+  if (!own) return null;
+  const rootId = getRootId(id);
+  if (!rootId || rootId === id) return own;
+  const root = claudeTranscriptStamp(rootId);
+  return root ? `${own}|${root}` : null;
 }
 
 /**
@@ -398,10 +450,15 @@ chatRoutes.get("/sessions/:id/messages", async (c) => {
     const providerId = c.req.query("providerId") ?? "claude";
     const query = parseHistoryPageQuery((name) => c.req.query(name));
     const cacheKey = `${providerId}\0${id}`;
-    let all = query.before !== undefined ? recentHistory(cacheKey) : null;
+    const stamp = historyStamp(providerId, id);
+    let all = cachedHistory(cacheKey, stamp, query.before !== undefined);
     if (!all) {
+      // A parse joined in flight may have read the file before the change this request's
+      // stamp saw, so only the request that started it stores it — otherwise the end of a
+      // turn could be cached away under a stamp that says it is there, for good.
+      const joined = historyInFlight.has(cacheKey);
       all = await loadFullHistory(providerId, id);
-      if (query.limit !== undefined || query.from !== undefined) rememberHistory(cacheKey, all);
+      if (!joined && (stamp !== null || query.limit !== undefined || query.from !== undefined)) rememberHistory(cacheKey, stamp, all);
     }
     const page = pageHistory(all, query);
     // versionMap ships with the history so the `‹ n/m ›` switcher needs no
@@ -1103,6 +1160,23 @@ chatRoutes.get("/sessions/:id/tasks", async (c) => {
   }
 });
 
+/**
+ * The transcript a compact summary points at, when the path it names is not there.
+ *
+ * Claude Code builds that path from the folder the session was started or resumed in (a `cd`
+ * does not change it), so a session resumed in a subdirectory names a project folder that was
+ * never created (`…-app-tools--runtime-checkout/<id>.jsonl`) while its transcript stayed in the
+ * folder of the project it started in, and every scroll to the top answered "File not found".
+ * The file name is still the session's own, so when the named file is missing it is looked for
+ * in this project's folder, and only there. A named file that does exist is returned unchanged,
+ * as before: this scopes the fallback, not the route.
+ */
+function compactTranscriptPath(jsonlPath: string, projectPath: string): string {
+  if (existsSync(jsonlPath)) return jsonlPath;
+  const owned = assertSessionInProject({ providerId: "claude", sessionId: basename(jsonlPath, ".jsonl"), projectPath });
+  return owned.ok && owned.claude ? `${owned.claude.sessionDir}.jsonl` : jsonlPath;
+}
+
 /** GET /chat/pre-compact-messages — read and parse a JSONL transcript file (for expand-compact feature) */
 chatRoutes.get("/pre-compact-messages", async (c) => {
   try {
@@ -1119,7 +1193,7 @@ chatRoutes.get("/pre-compact-messages", async (c) => {
     // the start to the `before` record (to the end when no record has that uuid),
     // and parses only the segment it finds there, which is what it bounds. A 543MB
     // transcript answered "File too large" to every scroll up while its segments were 3MB.
-    const validated = validateJsonlPath(jsonlPath, Number.POSITIVE_INFINITY);
+    const validated = validateJsonlPath(compactTranscriptPath(jsonlPath, c.get("projectPath")), Number.POSITIVE_INFINITY);
     // One compaction segment per request: the client walks further back by
     // expanding the summary that arrives at the head of each one.
     const messages = await parseCompactSegment(validated, beforeUuid);

package/src/server/routes/database-query.ts

@@ -22,13 +22,14 @@ import { isReadOnlyQuery } from "../../services/database/readonly-check.ts";
 import { detectOperation, listQueryLogs, type QueryLogRow, type QueryOperation } from "../../services/query-audit/query-audit.service.ts";
 import { rowsToRecords } from "../../shared/db-grid.ts";
 import {
-  QUERY_HISTORY_PAGE, QUERY_SCRIPT_CONTENT_TYPE, queryRowLimit, type QueryCancelRequest, type QueryHistoryItem, type QueryHistoryResponse,
+  QUERY_HISTORY_PAGE, QUERY_SCRIPT_CONTENT_TYPE, queryRowLimit, WRONG_PASSWORD, type QueryCancelRequest, type QueryHistoryItem, type QueryHistoryResponse,
   type QueryScriptEvent, type QueryScriptRequest,
 } from "../../shared/db-query-script.ts";
 import { splitSqlScript, sqlCode } from "../../shared/split-sql-statements.ts";
 import type { DbQuerySession } from "../../types/database.ts";
 import { ok, err } from "../../types/api.ts";
 import { auditCaller, logQuery, logQueryAs } from "./query-audit-hook.ts";
+import { checkPpmPassword } from "../../services/ppm-password.ts";
 import { connAudit, connConfig, databaseParam, holdRequestOpen, requestDatabase, resolveTargetConn } from "./database-route-helpers.ts";
 
 export const databaseQueryRoutes = new Hono();
@@ -67,19 +68,26 @@ databaseQueryRoutes.post("/:id/query/script", async (c) => {
   if (statements.length === 0) return c.json(err("The script has no statements to run"), 400);
 
   const operation: QueryOperation = statements.length > 1 ? "script" : detectOperation(sqlCode(statements[0]!.sql, dialect).trim());
-  const params = { ...databaseParam(c), ...(explain ? { explain: true } : {}) };
+  // "Run with write access (once)": a readonly connection's run made writable, PPM's password typed again.
+  const writeOnce = !!body.writeOnce && !!conn.readonly && !isFileConnection(conn);
+  const params = { ...databaseParam(c), ...(explain ? { explain: true } : {}), ...(writeOnce ? { writeOnce: true } : {}) };
   const audit = {
     ...connAudit(conn), source: "editor" as const, operation, sql,
     ...(Object.keys(params).length > 0 ? { params } : {}),
   };
-  if (conn.readonly && !isReadOnlyQuery(sql, dialect)) {
+  if (writeOnce) {
+    if (!checkPpmPassword(body.writeOnce?.password)) {
+      logQuery(c, { ...audit, status: "blocked", error: WRONG_PASSWORD, durationMs: Date.now() - startedAt });
+      return c.json(err(WRONG_PASSWORD), 403);
+    }
+  } else if (conn.readonly && !isReadOnlyQuery(sql, dialect)) {
     logQuery(c, { ...audit, status: "blocked", error: READONLY_MESSAGE, durationMs: Date.now() - startedAt });
     return c.json(err(READONLY_MESSAGE), 403);
   }
 
   const key = runKey(conn, runId);
   if (runs.has(key)) return c.json(err("A run with this id is already in progress"), 409);
-  const config = connConfig(conn, requestDatabase(c));
+  const config = writeOnce ? { ...connConfig(conn, requestDatabase(c)), readonly: false } : connConfig(conn, requestDatabase(c));
   const run = new QueryScriptRun({
     sql, dialect, explain, maxRows: queryRowLimit(body.maxRows), continueOnError: body.continueOnError === true, timeoutMs: queryTimeoutMs(config),
   });
@@ -176,7 +184,8 @@ databaseQueryRoutes.get("/:id/history", (c) => {
   const search = c.req.query("search")?.trim() || undefined;
   const rows = listQueryLogs({
     ...(isFileConnection(conn) ? { fileConnection: conn.file.path } : { connectionId: conn.id }),
-    source: "editor",
+    // What an AI chat ran through PPM's database tools too, marked as an agent's.
+    source: ["editor", "ai"],
     search,
     limit: QUERY_HISTORY_PAGE,
     offset,

package/src/server/routes/database.ts

@@ -48,6 +48,8 @@ import {
 import { databaseStructureRoutes } from "./database-structure.ts";
 import { databaseImpExpRoutes, impExpJobRoutes } from "./database-impexp.ts";
 import { databaseQueryRoutes } from "./database-query.ts";
+import { dbApprovalBroker } from "../../services/db-ai-tools/db-approval-broker.ts";
+import type { DbApprovalAnswer } from "../../shared/db-ai-tools.ts";
 
 export const databaseRoutes = new Hono();
 
@@ -62,6 +64,18 @@ databaseRoutes.get("/ssh/agent", (c) => {
   return c.json(ok({ found: socket !== null, socket, user: localSshUser() }));
 });
 
+/**
+ * POST /api/db/ai-approvals/:requestId — body: `DbApprovalAnswer`. The user's answer to an AI
+ * chat's `db_execute`, from its approval card. Approving takes PPM's password; a wrong one is a
+ * 403 that leaves the approval waiting, so the card can say so and be answered again.
+ */
+databaseRoutes.post("/ai-approvals/:requestId", async (c) => {
+  const body = await c.req.json<Partial<DbApprovalAnswer>>().catch(() => null);
+  const answered = dbApprovalBroker.answer(c.req.param("requestId"), body);
+  if (!answered.ok) return c.json(err(answered.error), answered.status);
+  return c.json(ok({ approved: answered.approved }));
+});
+
 /**
  * Anything a saved connection does needs its engine's driver. Registered
  * before the routes it guards; the cached table list is read from PPM's own

package/src/server/routes/debug-crash.ts

@@ -0,0 +1,30 @@
+import type { Hono } from "hono";
+
+/**
+ * `GET /api/debug/crash` exits the server, for watching the supervisor's health check and
+ * restart UI react to a dead child. It is never on by default: being a development server is
+ * not a reason, because a dev server is routinely reachable through a tunnel, and anyone who
+ * can reach a route that exits the process can take PPM down at will.
+ *
+ * `PPM_DEBUG_CRASH_ROUTE=1` (or `true`) opts in, and the caller mounts it after the sign-in
+ * check, so even then only a signed-in user reaches it.
+ */
+export function isDebugCrashRouteEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  const v = env.PPM_DEBUG_CRASH_ROUTE?.trim().toLowerCase();
+  return v === "1" || v === "true";
+}
+
+/** Registers the route on `app` when opted in. `app` must already require sign-in on `/api/*`. */
+export function mountDebugCrashRoute(
+  app: Hono,
+  env: Record<string, string | undefined> = process.env,
+  exit: (code: number) => void = (code) => process.exit(code),
+): boolean {
+  if (!isDebugCrashRouteEnabled(env)) return false;
+  app.get("/api/debug/crash", (c) => {
+    // Answer first so the caller sees the request was taken, then exit on the next tick.
+    setTimeout(() => exit(1), 0);
+    return c.text("exiting", 202);
+  });
+  return true;
+}

package/src/server/routes/design-comments.ts

@@ -1,12 +1,19 @@
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import { ok, err } from "../../types/api.ts";
+import type { StoredDesignComment } from "../../shared/design-comment-thread-types.ts";
 import {
   addComment, deleteComment, listComments, previewElementContext, updateComment,
 } from "../../services/design/design-comments.service.ts";
+import { addReply, deleteReply, updateReply } from "../../services/design/design-comment-replies.service.ts";
+import { toOwnerView } from "../../services/design/comments/design-comment-views.ts";
+import { listShareLinksForDesign } from "../../services/design/share/design-share-links-store.ts";
+import { projectKey } from "../../services/project-name-for-path.ts";
 import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } from "./design-route-helpers.ts";
 
 /**
- * `/api/project/:projectName/designs/:slug/comments` — pinned element comments.
+ * `/api/project/:projectName/designs/:slug/comments` — pinned element comments and their
+ * replies, as the owner sees them (`DesignCommentOwnerView`): every author named, each
+ * reviewer's link by its label, and no reviewer's key hash.
  *
  * `POST /context` answers with the server-built snippet for one element without saving
  * anything, for "Send to AI" on a single element: the prompt must never carry markup the
@@ -15,9 +22,20 @@ import { designFail as fail, designJsonBody as jsonBody, type DesignRouteEnv } f
 
 export const designCommentRoutes = new Hono<DesignRouteEnv>();
 
+const slugOf = (c: Context<DesignRouteEnv>) => c.req.param("slug") ?? "";
+
+/** Labels of the design's share links by id, read once per response. */
+function linkLabels(c: Context<DesignRouteEnv>): Map<string, string> {
+  return new Map(listShareLinksForDesign(projectKey(c.get("projectPath")), slugOf(c)).map((l) => [l.id, l.label]));
+}
+
+const ownerView = (c: Context<DesignRouteEnv>, comment: StoredDesignComment) => toOwnerView(comment, linkLabels(c));
+
 designCommentRoutes.get("/", async (c) => {
   try {
-    return c.json(ok(await listComments(c.get("projectPath"), c.req.param("slug") ?? "")));
+    const comments = await listComments(c.get("projectPath"), slugOf(c));
+    const labels = linkLabels(c);
+    return c.json(ok(comments.map((comment) => toOwnerView(comment, labels))));
   } catch (e) {
     return fail(c, e);
   }
@@ -27,7 +45,7 @@ designCommentRoutes.post("/", async (c) => {
   const body = await jsonBody(c);
   if (!body) return c.json(err("Expected a JSON object"), 400);
   try {
-    return c.json(ok(await addComment(c.get("projectPath"), c.req.param("slug") ?? "", body)), 201);
+    return c.json(ok(ownerView(c, await addComment(c.get("projectPath"), slugOf(c), body))), 201);
   } catch (e) {
     return fail(c, e);
   }
@@ -37,7 +55,7 @@ designCommentRoutes.post("/context", async (c) => {
   const body = await jsonBody(c);
   if (!body) return c.json(err("Expected a JSON object"), 400);
   try {
-    return c.json(ok(await previewElementContext(c.get("projectPath"), c.req.param("slug") ?? "", body)));
+    return c.json(ok(await previewElementContext(c.get("projectPath"), slugOf(c), body)));
   } catch (e) {
     return fail(c, e);
   }
@@ -47,7 +65,7 @@ designCommentRoutes.patch("/:id", async (c) => {
   const body = await jsonBody(c);
   if (!body) return c.json(err("Expected a JSON object"), 400);
   try {
-    return c.json(ok(await updateComment(c.get("projectPath"), c.req.param("slug") ?? "", c.req.param("id"), body)));
+    return c.json(ok(ownerView(c, await updateComment(c.get("projectPath"), slugOf(c), c.req.param("id"), body))));
   } catch (e) {
     return fail(c, e);
   }
@@ -55,9 +73,40 @@ designCommentRoutes.patch("/:id", async (c) => {
 
 designCommentRoutes.delete("/:id", async (c) => {
   try {
-    await deleteComment(c.get("projectPath"), c.req.param("slug") ?? "", c.req.param("id"));
+    await deleteComment(c.get("projectPath"), slugOf(c), c.req.param("id"));
     return c.json(ok({ deleted: c.req.param("id") }));
   } catch (e) {
     return fail(c, e);
   }
 });
+
+/** Replies answer with the whole thread, so the canvas can replace it in one step. */
+designCommentRoutes.post("/:id/replies", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    const { thread } = await addReply(c.get("projectPath"), slugOf(c), c.req.param("id"), body);
+    return c.json(ok(ownerView(c, thread)), 201);
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designCommentRoutes.patch("/:id/replies/:replyId", async (c) => {
+  const body = await jsonBody(c);
+  if (!body) return c.json(err("Expected a JSON object"), 400);
+  try {
+    const { thread } = await updateReply(c.get("projectPath"), slugOf(c), c.req.param("id"), c.req.param("replyId"), body);
+    return c.json(ok(ownerView(c, thread)));
+  } catch (e) {
+    return fail(c, e);
+  }
+});
+
+designCommentRoutes.delete("/:id/replies/:replyId", async (c) => {
+  try {
+    return c.json(ok(ownerView(c, await deleteReply(c.get("projectPath"), slugOf(c), c.req.param("id"), c.req.param("replyId")))));
+  } catch (e) {
+    return fail(c, e);
+  }
+});

package/src/server/routes/design-share-address.ts

@@ -0,0 +1,20 @@
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import { getShareAddress } from "../../services/design/share/design-share-address.ts";
+
+/**
+ * `/api/design-shares` — what the Share dialog needs outside any one design: the public
+ * address links are reachable at, whether the tunnel switch is on, and whether PPM sign-in
+ * is (sharing is refused while it is off).
+ */
+
+export const designShareAddressRoutes = new Hono();
+
+designShareAddressRoutes.get("/address", (c) => {
+  try {
+    return c.json(ok(getShareAddress()));
+  } catch (e) {
+    console.error(`[design] GET /api/design-shares/address: ${(e as Error).message}`);
+    return c.json(err("Could not read the public address"), 500);
+  }
+});

package/src/server/routes/design-share-guest-comments.ts

@@ -0,0 +1,120 @@
+import type { Context, Hono } from "hono";
+import { err, ok } from "../../types/api.ts";
+import { crossOriginRefusal } from "./cross-origin-guard.ts";
+import { GUEST_KEY_HEADER, GUEST_WRITE_MAX_BYTES } from "../../shared/design-share-guest-types.ts";
+import type { DesignCommentGuestView } from "../../shared/design-comment-thread-types.ts";
+import type { ResolvedShareLink } from "../../services/design/share/design-share-resolve.ts";
+import { guestLinkOpen, resolveGuestLink } from "../../services/design/share/design-share-guest-link.ts";
+import {
+  checkShareClientWrite, takeShareRead, takeShareWrite,
+} from "../../services/design/share/design-share-rate-limit.ts";
+import {
+  addGuestComment, addGuestReply, deleteGuestComment, deleteGuestReply, guestCommentsEtag, guestKeyHash,
+  listGuestThreads, updateGuestComment, updateGuestReply,
+} from "../../services/design/share/design-share-comments.service.ts";
+import { notifyGuestWrite } from "../../services/design/share/design-share-notifier.ts";
+import { clientKeyOf, guestFail, invalidJson, readCappedText, tooManyRequests } from "./design-share-guest-shared.ts";
+
+/**
+ * `/s/<code>/comments…`: a reviewer's threads on the link, and their writes.
+ *
+ * A read needs no key (without one nothing is "mine"); `If-None-Match` is answered from the
+ * ETag before the file is read. A write needs the reviewer's key and passes the cross-origin
+ * header pair: there is no `cors()` in front of these routes, so a page on another origin
+ * cannot get the browser to send either. The client's write budget is checked before the
+ * code is looked up, and the write is counted against the client and the link before the
+ * body is read, so a stream of refused writes still costs the sender.
+ */
+
+type Body = Record<string, unknown>;
+type GuestWrite = (resolved: ResolvedShareLink, keyHash: string, body: Body) => Promise<Response>;
+
+async function guestWrite(c: Context, run: GuestWrite): Promise<Response> {
+  const refusal = crossOriginRefusal(c);
+  if (refusal) return c.json(err(refusal), 403);
+  const keyHash = guestKeyHash(c.req.header(GUEST_KEY_HEADER));
+  if (!keyHash) return c.json(err("A reviewer key is needed"), 400);
+  const clientKey = clientKeyOf(c);
+  // Write spacing is per reviewer, not per address: behind the supervisor every LAN reviewer
+  // shares one address, and a reply sent right after a colleague's comment is not a flood.
+  // The per-link cap still bounds a sender that invents keys.
+  const writerKey = `${clientKey}:${keyHash}`;
+  const early = checkShareClientWrite(writerKey);
+  if (early) return tooManyRequests(c, early);
+  const resolved = await resolveGuestLink(c.req.param("code") ?? "");
+  if (!resolved) {
+    // A code that opens nothing still costs a read, so guessing has a price.
+    takeShareRead("api", clientKey);
+    return invalidJson(c);
+  }
+  const retry = takeShareWrite(writerKey, resolved.link.id);
+  if (retry) return tooManyRequests(c, retry);
+  let body: unknown;
+  try {
+    const text = await readCappedText(c.req.raw, GUEST_WRITE_MAX_BYTES);
+    if (text === null) return c.json(err("Request too large"), 413);
+    body = text.trim() ? JSON.parse(text) : {};
+  } catch {
+    return c.json(err("Expected a JSON object"), 400);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return c.json(err("Expected a JSON object"), 400);
+  try {
+    return await run(resolved, keyHash, body as Body);
+  } catch (e) {
+    return guestFail(c, e, resolved.link.id);
+  }
+}
+
+/**
+ * Tell the owner, unless the link closed between the write and now: a revoked link's last
+ * write is not news worth a notification, and a notification would carry its threads' text.
+ */
+function notifyIfOpen(r: ResolvedShareLink, thread: DesignCommentGuestView, kind: "comment" | "reply"): void {
+  if (guestLinkOpen(r)) notifyGuestWrite(r, thread, kind);
+}
+
+export function registerGuestCommentRoutes(app: Hono): void {
+  app.get("/:code/comments", async (c) => {
+    const clientKey = clientKeyOf(c);
+    const retry = takeShareRead("api", clientKey);
+    if (retry) return tooManyRequests(c, retry);
+    const resolved = await resolveGuestLink(c.req.param("code"));
+    if (!resolved) return invalidJson(c);
+    const keyHash = guestKeyHash(c.req.header(GUEST_KEY_HEADER));
+    try {
+      const etag = await guestCommentsEtag(resolved, keyHash);
+      if (c.req.header("if-none-match") === etag) return new Response(null, { status: 304, headers: { ETag: etag } });
+      const { threads, versionId, etag: current } = await listGuestThreads(resolved, keyHash);
+      return c.json(ok({ threads, versionId }), 200, { ETag: current });
+    } catch (e) {
+      return guestFail(c, e, resolved.link.id);
+    }
+  });
+
+  // New comments and replies tell the owner; edits and deletes do not.
+  app.post("/:code/comments", (c) => guestWrite(c, async (r, key, body) => {
+    const thread = await addGuestComment(r, key, body);
+    notifyIfOpen(r, thread, "comment");
+    return c.json(ok({ thread }), 201);
+  }));
+
+  app.post("/:code/comments/:id/replies", (c) => guestWrite(c, async (r, key, body) => {
+    const thread = await addGuestReply(r, key, c.req.param("id"), body);
+    notifyIfOpen(r, thread, "reply");
+    return c.json(ok({ thread }), 201);
+  }));
+
+  app.patch("/:code/comments/:id", (c) => guestWrite(c, async (r, key, body) =>
+    c.json(ok({ thread: await updateGuestComment(r, key, c.req.param("id"), body) }))));
+
+  app.delete("/:code/comments/:id", (c) => guestWrite(c, async (r, key) => {
+    await deleteGuestComment(r, key, c.req.param("id"));
+    return c.json(ok({ deleted: c.req.param("id") }));
+  }));
+
+  app.patch("/:code/comments/:id/replies/:replyId", (c) => guestWrite(c, async (r, key, body) =>
+    c.json(ok({ thread: await updateGuestReply(r, key, c.req.param("id"), c.req.param("replyId"), body) }))));
+
+  app.delete("/:code/comments/:id/replies/:replyId", (c) => guestWrite(c, async (r, key) =>
+    c.json(ok({ thread: await deleteGuestReply(r, key, c.req.param("id"), c.req.param("replyId")) }))));
+}