@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/design/preview/design-guest-alias.ts

@@ -0,0 +1,64 @@
+import { join, resolve } from "node:path";
+import { previewDenied } from "../../../server/helpers/preview-asset-guard.ts";
+import { lstatOrNull, resolveDesignsRoot } from "../design-paths.ts";
+import { MANIFEST_FILE, DEFAULT_ENTRY } from "../design-manifest.ts";
+import { DEFAULT_SYSTEM_ID, systemFilesDir } from "../design-systems-paths.ts";
+import { containedFile, SYSTEMS_DIR_ALIAS, TOKENS_CSS_ALIAS, type ScopedAsset } from "./design-preview-scope.ts";
+import type { DesignRef } from "./design-preview-tokens.ts";
+
+/**
+ * The design-system files a reviewer's view may load from outside the pinned snapshot.
+ *
+ * The owner's canvas resolves `systems/<id>/<rest>` against the app's whole files folder,
+ * and for the `default` app that folder is `designs/` itself — every other design, and the
+ * live copy of this one. A reviewer gets an allow-list instead, served live:
+ * - `tokens.css`: the shared `designs/tokens.css`;
+ * - `systems/<id>/tokens.css` and `systems/<id>/kit/**`, only for the app the snapshot's
+ *   `design.json` names. For `default` those are `designs/tokens.css` and `designs/kit/**`.
+ * Everything else under `systems/` is a 403: another app, `system.json`, `DESIGN.md`, and
+ * `systems/default/<slug>/…`. A design whose slug is `kit` would make `designs/kit/` both a
+ * design and the default kit, so while one exists the default `kit/**` is refused too.
+ */
+
+const KIT_DIR = "kit";
+
+function segmentsOf(path: string): string[] {
+  if (!path || path.includes("\\") || path.includes("\0") || path.includes(":")) previewDenied();
+  const segments = path.split("/");
+  if (segments.some((s) => s === "" || s === "." || s === ".." || s.startsWith("."))) previewDenied();
+  return segments;
+}
+
+/** `designs/kit/` is a design (it has a manifest or an entry page), not only a kit folder. */
+async function kitIsADesign(root: string): Promise<boolean> {
+  const dir = join(root, KIT_DIR);
+  const [manifest, entry] = await Promise.all([lstatOrNull(join(dir, MANIFEST_FILE)), lstatOrNull(join(dir, DEFAULT_ENTRY))]);
+  return !!manifest || !!entry;
+}
+
+/**
+ * `path` (decoded, relative to the share's file root: `tokens.css` or `systems/…`) as a file
+ * a reviewer may load, for a snapshot whose app is `systemId`. Throws `{status: 403}` for
+ * anything outside the allow-list, ENOENT when an allowed file is missing.
+ */
+export async function resolveGuestAlias(design: DesignRef, systemId: string, path: string): Promise<ScopedAsset> {
+  const segments = segmentsOf(path);
+  const root = await resolveDesignsRoot(design.projectPath);
+  if (!root) previewDenied();
+  const designDir = join(root, design.slug);
+  if (segments.length === 1 && segments[0] === TOKENS_CSS_ALIAS) {
+    return { abs: await containedFile(root, join(root, TOKENS_CSS_ALIAS)), rel: `../${TOKENS_CSS_ALIAS}`, designDir };
+  }
+  if (segments[0] !== SYSTEMS_DIR_ALIAS || segments.length < 3) previewDenied();
+  const [, id, ...rest] = segments as [string, string, ...string[]];
+  if (id !== systemId) previewDenied();
+  const isTokens = rest.length === 1 && rest[0] === TOKENS_CSS_ALIAS;
+  const isKit = rest.length >= 2 && rest[0] === KIT_DIR;
+  if (!isTokens && !isKit) previewDenied();
+  if (isKit && id === DEFAULT_SYSTEM_ID && (await kitIsADesign(root))) previewDenied();
+  // Contained in the kit folder itself, not just the app's: a `kit` that is a link to some
+  // other folder under `designs/` would otherwise still pass a check against `designs/`.
+  const base = isKit ? join(systemFilesDir(root, id), KIT_DIR) : systemFilesDir(root, id);
+  const abs = await containedFile(base, resolve(base, ...(isKit ? rest.slice(1) : rest)));
+  return { abs, rel: `../${path}`, designDir };
+}

package/src/services/design/preview/design-preview-html.ts

@@ -66,10 +66,23 @@ export function injectPlain(text: string, snippet: string): string {
   return injectWithoutParsing(text, snippet);
 }
 
+export interface RenderDesignHtmlOptions {
+  nonce: string | null;
+  withBridge: boolean;
+  inject?: string;
+  /** Another assembly of the bridge (a reviewer's view gets one that proposes no writes). */
+  bridgeScript?: string;
+  /**
+   * Send no stylesheet gens. They are read from the live design folder, which a page served
+   * from a snapshot must not touch, and only a page that writes styles back needs them.
+   */
+  skipCssGens?: boolean;
+}
+
 export async function renderDesignHtml(
   design: DesignRef,
   asset: ScopedAsset,
-  opts: { nonce: string | null; withBridge: boolean; inject?: string },
+  opts: RenderDesignHtmlOptions,
 ): Promise<RenderedDesignHtml> {
   const bytes = await readDesignFileSafe(asset.abs, MAX_DESIGN_SOURCE_BYTES);
   let source: DesignSource;
@@ -84,11 +97,11 @@ export async function renderDesignHtml(
   if (!opts.withBridge) return { body: opts.inject ? injectPlain(text, opts.inject) : text, gen, instrumented: false };
 
   const tag = (instrumented: boolean, cssGens: Record<string, string>): string =>
-    bridgeTag({ nonce: opts.nonce, gen, cssGens, file: asset.rel, instrumented });
+    bridgeTag({ nonce: opts.nonce, gen, cssGens, file: asset.rel, instrumented }, opts.bridgeScript);
   if (utf8 && bytes.byteLength <= INSTRUMENT_MAX_BYTES) {
     try {
       const analysis = analyzeHtml(text);
-      const cssGens = await linkedStylesheetGens(design, asset.rel, analysis.stylesheetHrefs);
+      const cssGens = opts.skipCssGens ? {} : await linkedStylesheetGens(design, asset.rel, analysis.stylesheetHrefs);
       return { body: instrumentHtml(text, tag(true, cssGens), analysis), gen, instrumented: true };
     } catch (e) {
       console.warn(`[design-preview] instrumenting ${design.slug}/${asset.rel} failed: ${(e as Error).message}`);

package/src/services/design/preview/design-preview-scope.ts

@@ -3,6 +3,8 @@ import { join, relative, resolve, sep } from "node:path";
 import { guardPreviewAsset, isInsideRoot, previewDenied } from "../../../server/helpers/preview-asset-guard.ts";
 import { resolveDesignDir, resolveDesignsRoot } from "../design-paths.ts";
 import { systemFilesDir } from "../design-systems-paths.ts";
+import { readSnapshotInfo, snapshotFilesDir } from "../design-snapshot-history.ts";
+import { DesignError } from "../design-error.ts";
 import { parseSystemsAliasTail } from "./design-systems-alias.ts";
 import type { DesignRef } from "./design-preview-tokens.ts";
 
@@ -42,7 +44,8 @@ function decodeRequestPath(encoded: string): string {
   }
 }
 
-async function containedFile(root: string, candidate: string): Promise<string> {
+/** `candidate` as its real path, refused unless both spellings stay inside `root` and pass the asset guard. */
+export async function containedFile(root: string, candidate: string): Promise<string> {
   if (!isInsideRoot(root, candidate)) previewDenied();
   guardPreviewAsset(candidate, root);
   const real = await realpath(candidate);
@@ -80,9 +83,30 @@ export async function resolveScopedPath(design: DesignRef, path: string): Promis
     const abs = await containedFile(base, candidate);
     return { abs, rel: `../${path}`, designDir };
   }
-  const prefix = `${design.slug}/`;
+  return designOwnFile(designDir, design.slug, path, designDir);
+}
+
+/** `<slug>/<rest>` resolved inside `root` (the design folder, or a snapshot's copy of it). */
+async function designOwnFile(root: string, slug: string, path: string, designDir: string): Promise<ScopedAsset> {
+  const prefix = `${slug}/`;
   if (!path.startsWith(prefix) || path.length === prefix.length) previewDenied();
-  const candidate = resolve(designDir, path.slice(prefix.length));
-  const abs = await containedFile(designDir, candidate);
-  return { abs, rel: relative(designDir, candidate).split(sep).join("/"), designDir };
+  const candidate = resolve(root, path.slice(prefix.length));
+  const abs = await containedFile(root, candidate);
+  return { abs, rel: relative(root, candidate).split(sep).join("/"), designDir };
+}
+
+/**
+ * {@link resolveScopedPath} for one snapshot's copy of the design: `<slug>/<rest>` under
+ * `.design/history/<id>/files/`, with the same containment and file-type checks. No alias
+ * is reachable through it — a snapshot holds the design's own files only. The snapshot must
+ * be one `readSnapshotInfo` accepts, which refuses a snapshot directory that is a symlink;
+ * a link anywhere else on the way (`history/`, `files/`, a file) fails the real-path check.
+ */
+export async function resolveSnapshotScopedPath(design: DesignRef, snapshotId: string, path: string): Promise<ScopedAsset> {
+  if (!path || path.includes("\\") || path.includes("\0") || path.includes(":")) previewDenied();
+  const designDir = await resolveDesignDir(design.projectPath, design.slug);
+  if (!(await readSnapshotInfo(designDir, snapshotId))) {
+    throw new DesignError(404, "ENOENT", "That version of the design no longer exists");
+  }
+  return designOwnFile(snapshotFilesDir(designDir, snapshotId), design.slug, path, designDir);
 }

package/src/services/design/share/design-share-address.ts

@@ -0,0 +1,81 @@
+import type { DesignShareAddress } from "../../../shared/design-share-types.ts";
+import { readStatus } from "../../supervisor-state.ts";
+import { tunnelService } from "../../tunnel.service.ts";
+import { getConfigValue } from "../../db.service.ts";
+import { resolveTunnelConfig } from "../../named-tunnel/named-tunnel-config.ts";
+import { shareAuthEnabled } from "./design-share-link-rules.ts";
+
+/**
+ * The public address a share link is reachable at now.
+ *
+ * Under a supervisor, `status.json` is read directly rather than through
+ * `tunnelService.getTunnelUrl()`: that keeps the last URL it saw when the supervisor nulls
+ * `shareUrl`, and a link built on it would point at a tunnel that is gone. Without a
+ * supervisor the only tunnel is one this server process started itself, which is quick.
+ *
+ * Cached for {@link ADDRESS_CACHE_MS}, because guest requests read it too.
+ */
+
+export const ADDRESS_CACHE_MS = 5000;
+
+export type ShareTunnelAddress = Pick<DesignShareAddress, "kind" | "url" | "warning">;
+
+const NONE: ShareTunnelAddress = { kind: "none", url: null, warning: null };
+let cache: { at: number; value: ShareTunnelAddress } | null = null;
+
+/** Alive, or owned by another user (`EPERM`), which is still a running process. */
+function pidAlive(pid: unknown): boolean {
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as { code?: string }).code === "EPERM";
+  }
+}
+
+function originOf(url: unknown): string | null {
+  if (typeof url !== "string" || !url) return null;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+function readTunnelAddress(): ShareTunnelAddress {
+  const status = readStatus();
+  if (pidAlive(status.supervisorPid)) {
+    const warning = typeof status.tunnelWarning === "string" && status.tunnelWarning ? status.tunnelWarning : null;
+    const url = originOf(status.shareUrl);
+    // A recorded tunnel process that has died means the URL answers nothing.
+    if (!url || (status.tunnelPid != null && !pidAlive(status.tunnelPid))) return { ...NONE, warning };
+    return { kind: status.tunnelMode === "named" ? "named" : "quick", url, warning };
+  }
+  const url = originOf(tunnelService.getTunnelUrl());
+  if (url && pidAlive(tunnelService.getTunnelPid())) return { kind: "quick", url, warning: null };
+  return NONE;
+}
+
+/** Kind, origin and warning of the current public address (cached). */
+export function getShareTunnelAddress(now = Date.now()): ShareTunnelAddress {
+  if (cache && now - cache.at < ADDRESS_CACHE_MS) return cache.value;
+  const value = readTunnelAddress();
+  cache = { at: now, value };
+  return value;
+}
+
+/** The address plus the two switches the Share dialog needs, which are read live. */
+export function getShareAddress(): DesignShareAddress {
+  return {
+    ...getShareTunnelAddress(),
+    enabled: resolveTunnelConfig(getConfigValue("tunnel")).enabled,
+    authEnabled: shareAuthEnabled(),
+  };
+}
+
+/** Forget the cached address (tests). */
+export function resetShareAddressCache(): void {
+  cache = null;
+}

package/src/services/design/share/design-share-changed-files.ts

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { SHARE_LIMITS, type DesignShareChangedFiles } from "../../../shared/design-share-types.ts";
+import { readSnapshotInfo, snapshotFilesDir } from "../design-snapshot-history.ts";
+import { readDesignTree } from "../design-snapshots.service.ts";
+import { shareError } from "./design-share-link-rules.ts";
+
+/**
+ * Which files a share link's reviewers would see differently: between two snapshots (after a
+ * re-pin), or between the pinned snapshot and the live design (before one).
+ *
+ * Both sides are read with {@link readDesignTree}, the walk a snapshot itself takes: same
+ * `.design/` exclusion, same symlink and credential refusals, same size and file caps. So the
+ * live side lists exactly what "Update to latest" would pin.
+ */
+
+/** sha256 of every file under `root`, by path relative to it; null when over the snapshot caps. */
+async function treeFileHashes(root: string): Promise<Map<string, string> | null> {
+  const tree = await readDesignTree(root);
+  if (!tree) return null;
+  return new Map(tree.files.map((f) => [f.rel, createHash("sha256").update(f.data).digest("hex")]));
+}
+
+/** Added, removed and changed paths, at most {@link SHARE_LIMITS.maxChangedFiles} names in all. */
+function diffHashes(before: Map<string, string>, after: Map<string, string>): DesignShareChangedFiles {
+  const out: DesignShareChangedFiles = { added: [], removed: [], changed: [], truncated: false };
+  let listed = 0;
+  const add = (list: string[], rel: string) => {
+    if (listed >= SHARE_LIMITS.maxChangedFiles) {
+      out.truncated = true;
+      return;
+    }
+    list.push(rel);
+    listed++;
+  };
+  for (const rel of [...after.keys()].sort()) {
+    const was = before.get(rel);
+    if (was === undefined) add(out.added, rel);
+    else if (was !== after.get(rel)) add(out.changed, rel);
+  }
+  for (const rel of [...before.keys()].sort()) {
+    if (!after.has(rel)) add(out.removed, rel);
+  }
+  return out;
+}
+
+/** A stored snapshot's file hashes; a snapshot is within the caps by construction. */
+async function snapshotHashes(designDir: string, id: string): Promise<Map<string, string>> {
+  const hashes = await treeFileHashes(snapshotFilesDir(designDir, id));
+  if (!hashes) throw shareError(409, "too-large", "The pinned version is too large to compare");
+  return hashes;
+}
+
+/**
+ * What a reviewer will see differently after a link moves from `oldId` to `newId`.
+ * Null when either snapshot is gone, since there is then nothing to compare with.
+ */
+export async function diffSnapshotFiles(designDir: string, oldId: string, newId: string): Promise<DesignShareChangedFiles | null> {
+  if (oldId === newId) return { added: [], removed: [], changed: [], truncated: false };
+  if (!(await readSnapshotInfo(designDir, oldId)) || !(await readSnapshotInfo(designDir, newId))) return null;
+  const [before, after] = await Promise.all([snapshotHashes(designDir, oldId), snapshotHashes(designDir, newId)]);
+  return diffHashes(before, after);
+}
+
+/**
+ * What a re-pin of a link pinned to `pinnedId` would change, compared with the live design
+ * files. Null when the pinned snapshot is gone. Refused (409 `too-large`) when the live design
+ * is over the snapshot caps, as the re-pin itself would be. The caller holds the design lock.
+ */
+export async function diffSnapshotWithLive(designDir: string, pinnedId: string): Promise<DesignShareChangedFiles | null> {
+  if (!(await readSnapshotInfo(designDir, pinnedId))) return null;
+  const live = await treeFileHashes(designDir);
+  if (!live) throw shareError(409, "too-large", "The design is too large to snapshot, so it cannot be re-pinned");
+  return diffHashes(await snapshotHashes(designDir, pinnedId), live);
+}

package/src/services/design/share/design-share-client-key.ts

@@ -0,0 +1,72 @@
+import { isIP } from "node:net";
+import { getShareTunnelAddress } from "./design-share-address.ts";
+
+/**
+ * Which client a reviewer's request is counted against, for the share routes' rate limits.
+ *
+ * `CF-Connecting-IP` is believed only when the request came through PPM's own tunnel: the
+ * peer is loopback (cloudflared, or the supervisor's edge forwarder, runs on this machine)
+ * and `Host` is the tunnel's public hostname (cached by the address helper, so no file is
+ * read per request). Cloudflare's edge sets that header itself; anywhere else it is
+ * whatever the client wrote. Every other request is keyed by its peer address, and loopback
+ * peers share one key, `"local"` — behind the supervisor that is every LAN and Tailscale
+ * reviewer at once, which the budgets are sized for.
+ *
+ * A LAN client can forge both headers and so pick its own key. The per-link caps ignore the
+ * key, and the limiter keeps a bounded number of keys, so that buys a forger nothing.
+ */
+
+export const LOCAL_CLIENT_KEY = "local";
+
+/** Test seam: where the current public tunnel URL comes from. */
+export const clientKeyDeps = { tunnelUrl: (): string | null => getShareTunnelAddress().url };
+
+/** What `c.env` holds when Hono runs under `Bun.serve`: the server, which knows the peer. */
+interface PeerSource {
+  requestIP?: (req: Request) => { address?: unknown } | null;
+}
+
+export interface ClientKeyInput {
+  req: Request;
+  /** Hono's `c.env`; absent when the app is called without a server (tests, `app.request`). */
+  env: unknown;
+  host: string | undefined;
+  cfConnectingIp: string | undefined;
+}
+
+function peerAddress(env: unknown, req: Request): string | null {
+  const source = env as PeerSource | null | undefined;
+  if (!source || typeof source.requestIP !== "function") return null;
+  try {
+    const address = source.requestIP(req)?.address;
+    return typeof address === "string" && isIP(address) ? address : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isLoopbackAddress(address: string): boolean {
+  const v4 = address.startsWith("::ffff:") ? address.slice(7) : address;
+  return address === "::1" || (isIP(v4) === 4 && v4.startsWith("127."));
+}
+
+/** The public tunnel's host (`name.example.com`), lower-cased, or null when there is none. */
+function tunnelHost(): string | null {
+  const url = clientKeyDeps.tunnelUrl();
+  if (!url) return null;
+  try {
+    return new URL(url).host.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+export function shareClientKey(input: ClientKeyInput): string {
+  const peer = peerAddress(input.env, input.req);
+  if (!peer) return LOCAL_CLIENT_KEY;
+  if (!isLoopbackAddress(peer)) return `ip:${peer}`;
+  const forwarded = input.cfConnectingIp?.trim();
+  const host = input.host?.trim().toLowerCase();
+  if (forwarded && host && isIP(forwarded) && host === tunnelHost()) return `cf:${forwarded.toLowerCase()}`;
+  return LOCAL_CLIENT_KEY;
+}

package/src/services/design/share/design-share-code.ts

@@ -0,0 +1,116 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeSync } from "node:fs";
+import { resolve } from "node:path";
+import { getPpmDir } from "../../ppm-dir.ts";
+
+/**
+ * Share codes are derived, never stored: `code = base64url(HMAC-SHA256(secret, "<id>.<v>"))`
+ * with a 32-byte secret in the PPM dir. The database keeps only `sha256(code)`, so the owner
+ * can copy a link again at any time, while a leaked `ppm.db` or backup opens nothing.
+ * Deleting the secret file retires every code at once (the links then need a new code).
+ */
+
+const SECRET_FILE = "design-share.key";
+const SECRET_BYTES = 32;
+/** 256 bits in unpadded base64url. */
+export const SHARE_CODE_RE = /^[A-Za-z0-9_-]{43}$/;
+
+interface CachedSecret { key: Buffer; ino: number; mtimeMs: number; size: number }
+let cached: CachedSecret | null = null;
+
+function secretPath(): string {
+  return resolve(getPpmDir(), SECRET_FILE);
+}
+
+/** Block the thread briefly: the secret is read on synchronous paths. */
+function pause(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function statOrNull(path: string): ReturnType<typeof statSync> | null {
+  try {
+    return statSync(path);
+  } catch (e) {
+    if ((e as { code?: string }).code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+/** Claim the file with `wx`, so two first uses (two processes) cannot write different keys. */
+function createSecret(path: string): boolean {
+  mkdirSync(getPpmDir(), { recursive: true });
+  let fd: number;
+  try {
+    fd = openSync(path, "wx", 0o600);
+  } catch (e) {
+    if ((e as { code?: string }).code === "EEXIST") return false;
+    throw e;
+  }
+  try {
+    writeSync(fd, randomBytes(SECRET_BYTES));
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+
+/**
+ * Read the secret, waiting out a creator that has claimed the file but not written it yet.
+ * A file that stays the wrong size was never a usable key, so no code depends on it and it
+ * is replaced.
+ */
+function readSecret(path: string): Buffer {
+  for (let attempt = 0; attempt < 50; attempt++) {
+    const data = readFileSync(path);
+    if (data.length === SECRET_BYTES) return data;
+    pause(5);
+  }
+  const tmp = `${path}.tmp-${process.pid}`;
+  const fd = openSync(tmp, "w", 0o600);
+  try {
+    writeSync(fd, randomBytes(SECRET_BYTES));
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+  return readFileSync(path);
+}
+
+/**
+ * The share secret, created on first use. Re-read whenever the file changes, so deleting it
+ * takes effect without a restart.
+ */
+export function loadSecret(): Buffer {
+  const path = secretPath();
+  let st = statOrNull(path);
+  if (cached && st && st.ino === cached.ino && st.mtimeMs === cached.mtimeMs && st.size === cached.size) {
+    return cached.key;
+  }
+  if (!st) {
+    createSecret(path);
+  }
+  const key = readSecret(path);
+  st = statSync(path);
+  cached = { key, ino: st.ino, mtimeMs: st.mtimeMs, size: st.size };
+  return key;
+}
+
+/** Forget the cached secret (tests). */
+export function resetShareSecretCache(): void {
+  cached = null;
+}
+
+export function deriveCode(linkId: string, codeVersion: number): string {
+  return createHmac("sha256", loadSecret()).update(`${linkId}.${codeVersion}`).digest("base64url");
+}
+
+export function hashCode(code: string): string {
+  return createHash("sha256").update(code).digest("hex");
+}
+
+/** Whether `code` is the one currently derived for this link (constant time). */
+export function codeMatches(code: string, linkId: string, codeVersion: number): boolean {
+  const expected = Buffer.from(deriveCode(linkId, codeVersion));
+  const given = Buffer.from(code);
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}

package/src/services/design/share/design-share-comments.service.ts

@@ -0,0 +1,162 @@
+import { createHash, randomBytes } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import type { Stats } from "node:fs";
+import type { DesignCommentGuestView, StoredDesignComment } from "../../../shared/design-comment-thread-types.ts";
+import { GUEST_KEY_RE } from "../../../shared/design-share-guest-types.ts";
+import { dotDesignDir } from "../design-paths.ts";
+import { COMMENTS_FILE, readComments } from "../comments/design-comments-store.ts";
+import { commentsRevision } from "../comments/design-comments-revision.ts";
+import { guestThreads, toGuestView, type CommentActor } from "../comments/design-comment-views.ts";
+import { addComment, deleteComment, updateComment } from "../design-comments.service.ts";
+import { addReply, deleteReply, updateReply } from "../design-comment-replies.service.ts";
+import type { ResolvedShareLink } from "./design-share-resolve.ts";
+import { assertGuestLinkOpen } from "./design-share-guest-link.ts";
+
+/**
+ * The comment service as a reviewer reaches it: identity from the browser key, the link's
+ * own threads only, and every answer in the reviewer's view (no key hashes, no snippets).
+ * Ownership, quotas and visibility are enforced by the comment services under the design
+ * lock; this layer only shapes the call and the answer.
+ *
+ * Polls are cheap: the ETag is built from a per-design revision counter, the file's `stat`
+ * and the asker, so an unchanged list is answered without reading `comments.json`, and a
+ * changed one is parsed once per change, not once per reviewer.
+ */
+
+/** Test seam: how the comment file is read and stat'ed. */
+export const guestCommentsIo = {
+  read: (designDir: string): Promise<StoredDesignComment[]> => readComments(designDir),
+  stat: (path: string): Promise<Stats> => lstat(path),
+};
+
+const BOOT_ID = randomBytes(8).toString("hex");
+const MAX_CACHED_DESIGNS = 16;
+
+interface FileStamp { mtimeMs: number; size: number; ino: number; revision: number }
+const parsed = new Map<string, { stamp: FileStamp; comments: StoredDesignComment[] }>();
+
+/** SHA-256 hex of a well-formed browser key, or null for none or a malformed one. */
+export function guestKeyHash(key: string | undefined): string | null {
+  return key && GUEST_KEY_RE.test(key) ? createHash("sha256").update(key).digest("hex") : null;
+}
+
+async function stampOf(resolved: ResolvedShareLink): Promise<FileStamp> {
+  const revision = commentsRevision(resolved.link.projectPath, resolved.link.slug);
+  try {
+    const st = await guestCommentsIo.stat(join(dotDesignDir(resolved.designDir), COMMENTS_FILE));
+    return { mtimeMs: st.mtimeMs, size: st.size, ino: Number(st.ino), revision };
+  } catch {
+    return { mtimeMs: 0, size: -1, ino: 0, revision };
+  }
+}
+
+const sameStamp = (a: FileStamp, b: FileStamp): boolean =>
+  a.mtimeMs === b.mtimeMs && a.size === b.size && a.ino === b.ino && a.revision === b.revision;
+
+function etagOf(stamp: FileStamp, resolved: ResolvedShareLink, keyHash: string | null): string {
+  const parts = [BOOT_ID, stamp.revision, stamp.mtimeMs, stamp.size, stamp.ino, resolved.link.id, resolved.link.snapshotId, keyHash?.slice(0, 16) ?? "-"];
+  return `"${createHash("sha256").update(parts.join("|")).digest("base64url").slice(0, 27)}"`;
+}
+
+/** The list's ETag for this reviewer, from one `stat`. */
+export async function guestCommentsEtag(resolved: ResolvedShareLink, keyHash: string | null): Promise<string> {
+  return etagOf(await stampOf(resolved), resolved, keyHash);
+}
+
+/**
+ * The link's threads as `keyHash`'s reviewer sees them, the version the link shows now (a
+ * page still showing another one was opened before a re-pin), and the ETag. The ETag covers
+ * the version too, so a re-pin never answers 304.
+ */
+export async function listGuestThreads(
+  resolved: ResolvedShareLink, keyHash: string | null,
+): Promise<{ threads: DesignCommentGuestView[]; versionId: string; etag: string }> {
+  const stamp = await stampOf(resolved);
+  const hit = parsed.get(resolved.designDir);
+  let comments: StoredDesignComment[];
+  if (hit && sameStamp(hit.stamp, stamp)) {
+    comments = hit.comments;
+  } else {
+    // Read after the stat: a write landing in between makes the list newer than its ETag,
+    // which only means the next poll sends it again.
+    comments = await guestCommentsIo.read(resolved.designDir);
+    parsed.delete(resolved.designDir);
+    parsed.set(resolved.designDir, { stamp, comments });
+    if (parsed.size > MAX_CACHED_DESIGNS) parsed.delete(parsed.keys().next().value!);
+  }
+  return {
+    threads: guestThreads(comments, resolved.link, keyHash ?? ""),
+    versionId: resolved.link.snapshotId,
+    etag: etagOf(stamp, resolved, keyHash),
+  };
+}
+
+function actorOf(resolved: ResolvedShareLink, keyHash: string, name?: unknown): CommentActor {
+  return { kind: "guest", linkId: resolved.link.id, keyHash, name: typeof name === "string" ? name : undefined };
+}
+
+/**
+ * A reviewer's write options: who they are, and the link checked again under the design
+ * lock, since the write may have queued behind a snapshot while the owner revoked the link.
+ */
+function guestOpts(resolved: ResolvedShareLink, keyHash: string, extra: { name?: unknown; versionId?: string } = {}) {
+  return {
+    actor: actorOf(resolved, keyHash, extra.name),
+    recheck: () => assertGuestLinkOpen(resolved, extra.versionId),
+  };
+}
+
+type Body = Record<string, unknown>;
+
+/**
+ * A new thread, pinned to the version the reviewer's page shows (`versionId`). A page left
+ * open across a re-pin still shows the old one, and its anchor means nothing in the new one,
+ * so that comment is refused (409) rather than pinned where it was not made.
+ */
+export async function addGuestComment(resolved: ResolvedShareLink, keyHash: string, body: Body): Promise<DesignCommentGuestView> {
+  const { link } = resolved;
+  // Compared under the lock with the row as it is then (after the input itself is checked),
+  // so the snapshot the comment is pinned to is the one that check confirmed.
+  const versionId = typeof body.versionId === "string" ? body.versionId : "";
+  const created = await addComment(link.projectPath, link.slug, { anchor: body.anchor, body: body.body }, {
+    ...guestOpts(resolved, keyHash, { name: body.name, versionId }), source: { snapshotId: versionId },
+  });
+  return toGuestView(created, link, keyHash);
+}
+
+export async function updateGuestComment(
+  resolved: ResolvedShareLink, keyHash: string, id: string, body: Body,
+): Promise<DesignCommentGuestView> {
+  const { link } = resolved;
+  const updated = await updateComment(link.projectPath, link.slug, id, { body: body.body }, guestOpts(resolved, keyHash));
+  return toGuestView(updated, link, keyHash);
+}
+
+export async function deleteGuestComment(resolved: ResolvedShareLink, keyHash: string, id: string): Promise<void> {
+  await deleteComment(resolved.link.projectPath, resolved.link.slug, id, guestOpts(resolved, keyHash));
+}
+
+export async function addGuestReply(
+  resolved: ResolvedShareLink, keyHash: string, threadId: string, body: Body,
+): Promise<DesignCommentGuestView> {
+  const { link } = resolved;
+  const { thread } = await addReply(link.projectPath, link.slug, threadId, { body: body.body }, guestOpts(resolved, keyHash, { name: body.name }));
+  return toGuestView(thread, link, keyHash);
+}
+
+export async function updateGuestReply(
+  resolved: ResolvedShareLink, keyHash: string, threadId: string, replyId: string, body: Body,
+): Promise<DesignCommentGuestView> {
+  const { link } = resolved;
+  const { thread } = await updateReply(link.projectPath, link.slug, threadId, replyId, { body: body.body }, guestOpts(resolved, keyHash));
+  return toGuestView(thread, link, keyHash);
+}
+
+export async function deleteGuestReply(
+  resolved: ResolvedShareLink, keyHash: string, threadId: string, replyId: string,
+): Promise<DesignCommentGuestView> {
+  const { link } = resolved;
+  const thread = await deleteReply(link.projectPath, link.slug, threadId, replyId, guestOpts(resolved, keyHash));
+  return toGuestView(thread, link, keyHash);
+}