@hienlh/ppm 0.22.10 → 0.23.0

package/src/services/design/design-tool-policy.ts

@@ -0,0 +1,111 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/**
+ * Permission policy for a design session in `acceptEdits` mode: file reads, searches,
+ * writes and edits are auto-approved while their target resolves inside the project, and
+ * every other tool — shell, web, MCP, subagents, anything unknown — goes to the user.
+ *
+ * Fail-closed throughout: a missing project root, a path that is not a string, or a path
+ * that cannot be resolved all answer "ask". The check follows symlinks (realpath), so a
+ * link inside the project pointing outside it is treated as the outside path it is.
+ */
+export type DesignToolDecision = "allow" | "ask";
+
+/** Tool → the input field naming its target, and whether that field may be omitted
+ *  (Glob/Grep default to the session cwd, which is the project root). */
+const FILE_TOOLS: Record<string, { field: string; optional: boolean }> = {
+  Read: { field: "file_path", optional: false },
+  Write: { field: "file_path", optional: false },
+  Edit: { field: "file_path", optional: false },
+  Glob: { field: "path", optional: true },
+  Grep: { field: "path", optional: true },
+};
+
+export function designToolDecision(
+  toolName: string,
+  input: unknown,
+  projectPath: string | undefined,
+): DesignToolDecision {
+  const spec = FILE_TOOLS[toolName];
+  if (!spec || !projectPath) return "ask";
+  if (!input || typeof input !== "object") return "ask";
+  const record = input as Record<string, unknown>;
+
+  const root = canonicalPath(projectPath);
+  if (!root) return "ask";
+
+  // Glob's pattern is itself a path expression: `../../**` or `/etc/*` would enumerate
+  // outside the project even with no `path` given.
+  if (toolName === "Glob") {
+    const pattern = record.pattern;
+    if (typeof pattern !== "string" || !pattern || patternLeavesRoot(pattern)) return "ask";
+  }
+
+  const target = record[spec.field];
+  if (target === undefined || target === null || target === "") {
+    return spec.optional ? "allow" : "ask";
+  }
+  if (typeof target !== "string") return "ask";
+
+  const resolved = canonicalPath(resolve(projectPath, expandHome(target)));
+  if (!resolved) return "ask";
+  return isInside(resolved, root) ? "allow" : "ask";
+}
+
+/** `~` is expanded the way a shell would, so `~/.ssh` is judged as the home directory it
+ *  names rather than as a folder called `~` inside the project. */
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+function patternLeavesRoot(pattern: string): boolean {
+  if (isAbsolute(pattern) || /^[a-zA-Z]:/.test(pattern) || pattern.startsWith("~")) return true;
+  return pattern.split(/[\\/]/).includes("..");
+}
+
+/**
+ * Realpath of the path, or of its nearest existing ancestor with the missing tail
+ * re-appended — a Write usually targets a file that does not exist yet, and its parent
+ * directories may not either. Null when nothing along the chain resolves.
+ */
+function canonicalPath(path: string): string | null {
+  const tail: string[] = [];
+  let current = resolve(path);
+  for (;;) {
+    try {
+      const real = realpathSync.native(current);
+      return tail.length ? join(real, ...tail.reverse()) : real;
+    } catch {
+      // Something is there but cannot be resolved — typically a dangling symlink, which
+      // a Write would follow to wherever it points. Only a truly absent entry may be
+      // replaced by its parent.
+      if (entryExists(current)) return null;
+      const parent = dirname(current);
+      if (parent === current) return null;
+      tail.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+function entryExists(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isInside(target: string, root: string): boolean {
+  const caseFold = process.platform === "win32" || process.platform === "darwin";
+  const a = caseFold ? target.toLowerCase() : target;
+  const b = caseFold ? root.toLowerCase() : root;
+  const rel = relative(b, a);
+  if (rel === "") return true;
+  return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+}

package/src/services/design/design-turn-snapshot.ts

@@ -0,0 +1,80 @@
+import { getSessionDesignSlug, getSessionProjectPath } from "../db.service.ts";
+import { isValidDesignSlug } from "./design-slug.ts";
+import { designLockKey, detachFromDesignLocks } from "./design-lock.ts";
+import { snapshotDesign } from "./design-snapshots.service.ts";
+
+/**
+ * Snapshot a design after each turn of its design session.
+ *
+ * Called from `chatService.sendMessage` on every `done` and on every terminal background
+ * task notification, so turns from the WebSocket, `ppm chat send`, the scheduler and the
+ * bots are all covered. Work an agent started in the background can keep writing after
+ * the turn's `done`, which is why its completion schedules a snapshot too.
+ *
+ * Debounced per design: a turn's `done` followed shortly by its background task finishing
+ * produces one snapshot of the final state, not two. The timer is deliberately left
+ * referenced so a one-shot CLI process stays alive long enough to take it.
+ */
+
+export const TURN_SNAPSHOT_DEBOUNCE_MS = 2000;
+
+interface Pending {
+  timer: ReturnType<typeof setTimeout>;
+  fire: () => void;
+}
+
+const pending = new Map<string, Pending>();
+const inFlight = new Set<Promise<void>>();
+let debounceMs = TURN_SNAPSHOT_DEBOUNCE_MS;
+
+/** Test seam for the debounce interval. */
+export function setTurnSnapshotDebounceForTests(ms: number | null): void {
+  debounceMs = ms ?? TURN_SNAPSHOT_DEBOUNCE_MS;
+}
+
+/**
+ * Schedule a `turn` snapshot for the session's design. A no-op for an ordinary session
+ * (no design slug) or one with no known project. Never throws: a snapshot problem must not
+ * disturb the turn that triggered it.
+ */
+export function scheduleTurnSnapshot(sessionId: string, projectPath?: string | null): void {
+  try {
+    const slug = getSessionDesignSlug(sessionId);
+    if (!slug || !isValidDesignSlug(slug)) return;
+    const project = projectPath || getSessionProjectPath(sessionId);
+    if (!project) return;
+    const key = designLockKey(project, slug);
+    const existing = pending.get(key);
+    if (existing) clearTimeout(existing.timer);
+
+    const run = async (): Promise<void> => {
+      pending.delete(key);
+      try {
+        await snapshotDesign(project, slug, "turn", { sessionId });
+      } catch (e) {
+        console.warn(`[design] turn snapshot of ${slug} failed: ${(e as Error).message}`);
+      }
+    };
+    const fire = (): void => {
+      const job = detachFromDesignLocks(run);
+      inFlight.add(job);
+      void job.finally(() => inFlight.delete(job));
+    };
+    pending.set(key, { timer: setTimeout(fire, debounceMs), fire });
+  } catch (e) {
+    console.warn(`[design] could not schedule a turn snapshot for ${sessionId}: ${(e as Error).message}`);
+  }
+}
+
+/** Run every pending snapshot now and wait for all of them, in flight ones included. */
+export async function flushTurnSnapshots(): Promise<void> {
+  for (const job of [...pending.values()]) {
+    clearTimeout(job.timer);
+    job.fire();
+  }
+  await Promise.all([...inFlight]);
+}
+
+export function pendingTurnSnapshotCount(): number {
+  return pending.size;
+}

package/src/services/design/design-tweaks-commit.service.ts

@@ -0,0 +1,138 @@
+import { join } from "node:path";
+import { DESIGN_GEN_RE } from "../../shared/design-types.ts";
+import {
+  MAX_TWEAKS, TWEAK_VAR_RE, parseTweaks, sanitizeTweakValue, type ParsedTweaks,
+} from "../../shared/design-tweaks.ts";
+import { withRecoveredDesign } from "./design-restore-journal.ts";
+import { resolveDesignDir, lstatOrNull } from "./design-paths.ts";
+import { MANIFEST_FILE, isSafeEntry, parseManifest } from "./design-manifest.ts";
+import { snapshotDesign } from "./design-snapshots.service.ts";
+import { DesignError } from "./design-error.ts";
+import { readDesignSource, writeDesignSource } from "./source/design-source-file.ts";
+import { styleSources } from "./source/design-style-sources.ts";
+import { planTweakPatches, type PlannedTweak } from "./source/tweak-patch-plan.ts";
+import { takeDesignWrite } from "./design-write-rate-limit.ts";
+import { changedSpan, recordEdit, type EditSpan } from "./design-edit-undo-journal.ts";
+
+/**
+ * "Apply" in the Tweaks panel: write the chosen values into the design's stylesheets.
+ *
+ * The request carries only variable names and values, never a position or a file to write:
+ * the server re-reads the manifest, validates each value against its tweak's allowlist,
+ * works out which declaration wins on screen (see `tweak-patch-plan.ts`) and splices only
+ * that. Every design file it reads must still have the gen the canvas reported for it —
+ * the entry HTML and each linked stylesheet — or the whole commit is a 409 naming the file,
+ * so a canvas that is behind an agent's edit can never have its view written back over it.
+ * The `before-edit` snapshot is taken only once the commit is known to go through, and a
+ * commit that writes counts against the design's canvas write limit. Every file it changes
+ * is journaled as one undo entry, so Undo reverts this Apply and nothing an AI turn did since.
+ */
+
+const MAX_MANIFEST_BYTES = 256 * 1024;
+
+export interface TweakCommitInput {
+  entry: string;
+  gens: Record<string, string>;
+  values: Record<string, string>;
+}
+
+export interface TweakCommitResult {
+  /** Current gen of every design file the commit read, rewritten ones included. */
+  gens: Record<string, string>;
+  /** Undoes this commit's writes; null when nothing was written or it was too large to journal. */
+  undoId: string | null;
+}
+
+export interface DesignTweaksInfo extends ParsedTweaks {
+  /** False when `design.json` is missing or not a JSON object; the panel is then hidden. */
+  manifestValid: boolean;
+}
+
+/** A stale gen: the design changed since the canvas loaded it. */
+export class StaleTweakGenError extends DesignError {
+  constructor(readonly file: string, readonly currentGen: string) {
+    super(409, "ESTALE", `${file} changed since the canvas loaded it`);
+  }
+}
+
+const bad = (message: string): DesignError => new DesignError(400, "EBADTWEAK", message);
+type Raw = Record<string, unknown>;
+const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+
+async function readTweaksIn(designDir: string, slug: string): Promise<DesignTweaksInfo> {
+  const path = join(designDir, MANIFEST_FILE);
+  const st = await lstatOrNull(path);
+  if (!st?.isFile() || st.size > MAX_MANIFEST_BYTES) return { manifestValid: false, tweaks: [], errors: [] };
+  let raw: string;
+  try {
+    raw = (await readDesignSource(path, { maxBytes: MAX_MANIFEST_BYTES })).text;
+  } catch (e) {
+    if (e instanceof DesignError && e.status === 422) return { manifestValid: false, tweaks: [], errors: [] };
+    throw e;
+  }
+  const parsed = parseManifest(raw, { slug, now: new Date(0).toISOString() });
+  return { manifestValid: parsed.valid, ...parseTweaks(parsed.manifest.extra.tweaks) };
+}
+
+/** The tweak controls `design.json` declares, with the reasons any entry was skipped. */
+export async function readDesignTweaks(projectPath: string, slug: string): Promise<DesignTweaksInfo> {
+  return readTweaksIn(await resolveDesignDir(projectPath, slug), slug);
+}
+
+export function parseTweakCommitInput(input: unknown): TweakCommitInput {
+  if (!isRaw(input)) throw bad("Expected a JSON object");
+  if (!isSafeEntry(input.entry)) throw bad("entry must be an HTML file of the design");
+  if (!isRaw(input.gens) || Object.keys(input.gens).length > 64) throw bad("gens must map files to gens");
+  const gens: Record<string, string> = {};
+  for (const [file, gen] of Object.entries(input.gens)) {
+    if (file.length > 512 || typeof gen !== "string" || !DESIGN_GEN_RE.test(gen)) throw bad("gens must map files to gens");
+    gens[file] = gen;
+  }
+  if (!isRaw(input.values)) throw bad("values must map variables to values");
+  const entries = Object.entries(input.values);
+  if (entries.length === 0) throw bad("Nothing to apply");
+  if (entries.length > MAX_TWEAKS) throw bad(`At most ${MAX_TWEAKS} values per commit`);
+  const values: Record<string, string> = {};
+  for (const [name, value] of entries) {
+    if (!TWEAK_VAR_RE.test(name) || typeof value !== "string") throw bad(`Invalid value for ${name.slice(0, 60)}`);
+    values[name] = value;
+  }
+  return { entry: input.entry, gens, values };
+}
+
+export async function commitTweaks(projectPath: string, slug: string, raw: unknown): Promise<TweakCommitResult> {
+  const input = parseTweakCommitInput(raw);
+  return withRecoveredDesign(projectPath, slug, async (designDir) => {
+    const { tweaks } = await readTweaksIn(designDir, slug);
+    const planned: PlannedTweak[] = Object.entries(input.values).map(([name, value]) => {
+      const def = tweaks.find((t) => t.var === name);
+      if (!def) throw bad(`${name} is not a tweak of this design`);
+      const safe = sanitizeTweakValue(def, value);
+      if (safe === null) throw bad(`"${def.label}" cannot be set to that value`);
+      return { def, value: safe };
+    });
+
+    const loaded = await styleSources({ projectPath, slug }, input.entry);
+    for (const [file, { source, outside }] of loaded.files) {
+      // The shared tokens.css is never written and the canvas holds no gen for it.
+      if (!outside && input.gens[file] !== source.gen) throw new StaleTweakGenError(file, source.gen);
+    }
+    const texts = new Map([...loaded.files].map(([file, f]) => [file, f.source.text] as const));
+    const patches = planTweakPatches(input.entry, loaded.sources, texts, planned);
+
+    const gens: Record<string, string> = {};
+    for (const [file, { source, outside }] of loaded.files) if (!outside) gens[file] = source.gen;
+    if (patches.size === 0) return { gens, undoId: null };
+    takeDesignWrite(projectPath, slug);
+    await snapshotDesign(projectPath, slug, "before-edit");
+    const spans: EditSpan[] = [];
+    const written: Record<string, string> = {};
+    for (const [file, text] of patches) {
+      const f = loaded.files.get(file)!;
+      gens[file] = written[file] = await writeDesignSource(f.abs, text, { bom: f.source.bom });
+      const span = changedSpan(file, f.source.text, text);
+      if (span) spans.push(span);
+    }
+    return { gens, undoId: recordEdit(projectPath, slug, spans, written) };
+  });
+}

package/src/services/design/design-write-rate-limit.ts

@@ -0,0 +1,51 @@
+import { DesignError } from "./design-error.ts";
+import { designLockKey } from "./design-lock.ts";
+
+/**
+ * How often the canvas may write into one design: at most one write per 500 ms and 30 per
+ * minute, counted per design across every device and tab.
+ *
+ * Canvas writes are proposed by a frame that runs the page's own scripts. The parent only
+ * forwards a proposal after a real user gesture, but a page that posts one on the back of
+ * every click the user makes would still get through, so the server caps the stream as
+ * well: whatever gets past the parent is bounded, and each write is undoable. Only writes
+ * that are about to happen are counted — a refused or stale request costs nothing — so the
+ * check runs under the design lock, right before the file is written.
+ */
+
+export const WRITE_MIN_INTERVAL_MS = 500;
+export const WRITES_PER_MINUTE = 30;
+const WINDOW_MS = 60_000;
+
+/** Test seam: the clock the limiter reads. */
+export const designWriteClock = { now: (): number => Date.now() };
+
+const recent = new Map<string, number[]>();
+
+function sweep(now: number): void {
+  for (const [key, times] of recent) {
+    if (times.length === 0 || now - times[times.length - 1]! >= WINDOW_MS) recent.delete(key);
+  }
+}
+
+/** Counts one write, or throws a 429 without counting it. */
+export function takeDesignWrite(projectPath: string, slug: string): void {
+  const now = designWriteClock.now();
+  sweep(now);
+  const key = designLockKey(projectPath, slug);
+  const times = (recent.get(key) ?? []).filter((t) => now - t < WINDOW_MS);
+  const last = times[times.length - 1];
+  if (last !== undefined && now - last < WRITE_MIN_INTERVAL_MS) {
+    throw new DesignError(429, "rate-limited", "Too many canvas edits at once; wait a moment and try again");
+  }
+  if (times.length >= WRITES_PER_MINUTE) {
+    throw new DesignError(429, "rate-limited", `At most ${WRITES_PER_MINUTE} canvas edits a minute; wait a moment and try again`);
+  }
+  times.push(now);
+  recent.set(key, times);
+}
+
+/** Forget every count; for tests. */
+export function resetDesignWriteLimits(): void {
+  recent.clear();
+}

package/src/services/design/export/css-url-inline.ts

@@ -0,0 +1,130 @@
+import { posix } from "node:path";
+import { isLocalHref } from "../preview/html-instrument.ts";
+import { TOKENS_CSS_REL, type ReadAsset } from "./design-export-asset-reader.ts";
+
+/**
+ * Local asset inlining for the standalone-HTML export: CSS `url()`s and `@import`s become
+ * `data:` URIs, so the one exported file works offline.
+ *
+ * A reference resolves against the file it is written in — a stylesheet's `url()` against
+ * that stylesheet, not against the HTML — and must stay inside the design folder (the
+ * shared `../tokens.css` is the one allowed step out; it sits inside `designs/`). Absolute,
+ * scheme and fragment references are left exactly as they are: CDN links are allowed in a
+ * design and are not local. Every asset read is charged to one shared {@link InlineBudget};
+ * a missing, refused or over-budget asset keeps its original reference and adds a warning,
+ * so an export never fails because of one link.
+ */
+
+export interface InlineBudget {
+  /** Largest single asset, in bytes. */
+  perAsset: number;
+  /** Bytes still allowed across the whole export; decremented as assets are inlined. */
+  remaining: number;
+}
+
+export interface InlineContext {
+  readAsset: ReadAsset;
+  budget: InlineBudget;
+  warnings: string[];
+}
+
+const MIME: Record<string, string> = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp",
+  ".avif": "image/avif", ".svg": "image/svg+xml", ".ico": "image/x-icon", ".mp4": "video/mp4", ".webm": "video/webm",
+  ".mov": "video/quicktime", ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg", ".m4a": "audio/mp4",
+  ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf", ".css": "text/css",
+  ".js": "text/javascript", ".mjs": "text/javascript", ".json": "application/json", ".vtt": "text/vtt",
+};
+
+export function mimeForPath(rel: string): string {
+  return MIME[posix.extname(rel).toLowerCase()] ?? "application/octet-stream";
+}
+
+export function toDataUri(rel: string, bytes: Uint8Array): string {
+  return `data:${mimeForPath(rel)};base64,${Buffer.from(bytes).toString("base64")}`;
+}
+
+export type ResolvedRef = { rel: string; suffix: string } | { outside: true } | null;
+
+/**
+ * A reference written in a file under `baseDir` (design-relative, `""` for the design root),
+ * as a design-relative path plus its `#fragment`. Null when it is not a local reference at all.
+ */
+export function resolveDesignRef(ref: string, baseDir: string): ResolvedRef {
+  if (!isLocalHref(ref)) return null;
+  const hash = ref.indexOf("#");
+  const suffix = hash >= 0 ? ref.slice(hash) : "";
+  let path = (hash >= 0 ? ref.slice(0, hash) : ref).split("?")[0]!.trim();
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+    return { outside: true };
+  }
+  if (!path || path.includes("\\") || path.includes("\0")) return { outside: true };
+  const rel = posix.normalize(posix.join(baseDir, path));
+  if (rel === TOKENS_CSS_REL) return { rel, suffix };
+  if (rel === ".." || rel.startsWith("../") || rel.startsWith("/") || rel.split("/").some((s) => s.startsWith("."))) {
+    return { outside: true };
+  }
+  return { rel, suffix };
+}
+
+const sizeLabel = (bytes: number): string =>
+  (bytes >= 1048576 ? `${Math.round(bytes / 1048576)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB`);
+
+/** Reads one asset for inlining, charging the budget; null (with a warning) when it cannot be. */
+export async function loadInlineAsset(rel: string, ctx: InlineContext): Promise<Uint8Array | null> {
+  const result = await ctx.readAsset(rel, ctx.budget.perAsset);
+  if (!result.ok) {
+    ctx.warnings.push(result.reason === "missing" ? `${rel}: not found, left linked`
+      : result.reason === "too-large" ? `${rel}: larger than ${sizeLabel(ctx.budget.perAsset)}, left linked`
+      : `${rel}: not readable from the design folder, left linked`);
+    return null;
+  }
+  if (result.bytes.byteLength > ctx.budget.remaining) {
+    ctx.warnings.push(`${rel}: the export's size limit is used up, left linked`);
+    return null;
+  }
+  ctx.budget.remaining -= result.bytes.byteLength;
+  return result.bytes;
+}
+
+// `@import url(x)` / `@import "x"` first, so the url() of an import is inlined as CSS.
+const REF_RE = /@import\s+(?:url\(\s*(["']?)([^"')]*)\1\s*\)|(["'])([^"']*)\3)|url\(\s*(["']?)([^"')]*?)\5\s*\)/gi;
+const MAX_IMPORT_DEPTH = 4;
+
+/**
+ * `css` with every local `url()` turned into a data URI and every local `@import` replaced
+ * by a data URI of the imported sheet, itself inlined against its own folder.
+ */
+export async function inlineCssUrls(css: string, cssFileDir: string, ctx: InlineContext, depth = 0): Promise<string> {
+  const out: string[] = [];
+  let cursor = 0;
+  for (const m of css.matchAll(REF_RE)) {
+    const isImport = m[0].charAt(0) === "@";
+    const ref = isImport ? (m[2] ?? m[4] ?? "") : (m[6] ?? "");
+    const resolved = resolveDesignRef(ref, cssFileDir);
+    if (!resolved) continue;
+    if ("outside" in resolved) {
+      ctx.warnings.push(`${ref}: outside the design folder, left linked`);
+      continue;
+    }
+    if (isImport && depth >= MAX_IMPORT_DEPTH) {
+      ctx.warnings.push(`${resolved.rel}: @import nested too deeply, left linked`);
+      continue;
+    }
+    const bytes = await loadInlineAsset(resolved.rel, ctx);
+    if (!bytes) continue;
+    let replacement: string;
+    if (isImport) {
+      const inner = await inlineCssUrls(new TextDecoder().decode(bytes), posix.dirname(resolved.rel), ctx, depth + 1);
+      replacement = `@import url("${toDataUri(resolved.rel, new TextEncoder().encode(inner))}")`;
+    } else {
+      replacement = `url("${toDataUri(resolved.rel, bytes)}${resolved.suffix}")`;
+    }
+    out.push(css.slice(cursor, m.index), replacement);
+    cursor = m.index! + m[0].length;
+  }
+  out.push(css.slice(cursor));
+  return out.join("");
+}

package/src/services/design/export/design-export-asset-reader.ts

@@ -0,0 +1,57 @@
+import { realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { assertNotPpmDir, isCredentialPath } from "../../fs-path-guard.service.ts";
+import { guardPreviewAsset, isInsideRoot } from "../../../server/helpers/preview-asset-guard.ts";
+import { lstatOrNull } from "../design-paths.ts";
+import { readDesignFileSafe, SafeWalkError } from "../design-safe-walk.ts";
+
+/**
+ * How the standalone-HTML export reads the files a page links: by path relative to the
+ * design folder, through the same guards as everything else that reads a design tree.
+ *
+ * A design is written by an agent, so a link in it can point anywhere. A file is read only
+ * when it is inside the design folder (or is the shared `../tokens.css`), is a web asset by
+ * extension, sits under no dot-directory, is a regular file and not a symlink, still resolves
+ * inside after `realpath`, is no credential path and not inside the PPM directory — and then
+ * through `readDesignFileSafe`, which re-checks the open handle. Everything else answers
+ * `refused`, never an exception, so one bad link costs one warning rather than the export.
+ */
+
+export type ReadAssetResult =
+  | { ok: true; bytes: Uint8Array }
+  | { ok: false; reason: "missing" | "refused" | "too-large" };
+
+/** `rel` is `/`-separated and relative to the design folder; `../tokens.css` is the one way out. */
+export type ReadAsset = (rel: string, maxBytes: number) => Promise<ReadAssetResult>;
+
+export const TOKENS_CSS_REL = "../tokens.css";
+
+export function createDesignAssetReader(designDir: string, designsRoot: string): ReadAsset {
+  return async (rel, maxBytes) => {
+    const tokens = rel === TOKENS_CSS_REL;
+    const root = tokens ? designsRoot : designDir;
+    if (!tokens && (rel === "" || rel.includes("\0") || rel.includes("\\") || rel.split("/").some((s) => s === ".." || s.startsWith(".")))) {
+      return { ok: false, reason: "refused" };
+    }
+    const target = tokens ? join(designsRoot, "tokens.css") : resolve(designDir, ...rel.split("/"));
+    try {
+      if (!isInsideRoot(root, target)) return { ok: false, reason: "refused" };
+      guardPreviewAsset(target, root);
+      const st = await lstatOrNull(target);
+      if (!st) return { ok: false, reason: "missing" };
+      if (st.isSymbolicLink() || !st.isFile()) return { ok: false, reason: "refused" };
+      const real = await realpath(target);
+      if (!isInsideRoot(root, real) || isCredentialPath(target) || isCredentialPath(real)) return { ok: false, reason: "refused" };
+      assertNotPpmDir(real);
+      if (st.size > maxBytes) return { ok: false, reason: "too-large" };
+      return { ok: true, bytes: await readDesignFileSafe(target, maxBytes) };
+    } catch (e) {
+      if (e instanceof SafeWalkError && e.code === "ETOOBIG") return { ok: false, reason: "too-large" };
+      const code = (e as { code?: string }).code;
+      if (code === "ENOENT" || code === "ENOTDIR") return { ok: false, reason: "missing" };
+      const status = (e as { status?: number }).status;
+      if (status === 403 || code === "ELOOP" || code === "EACCES" || code === "EPERM") return { ok: false, reason: "refused" };
+      throw e;
+    }
+  };
+}

package/src/services/design/export/design-export-entry.ts

@@ -0,0 +1,33 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { DesignError } from "../design-error.ts";
+
+/**
+ * Which page of a design `GET …/export/html?entry=` may export.
+ *
+ * Checked on the already-decoded query value, and deliberately stricter than a path join:
+ * a small character set (so `%`, `\`, `:` and NUL — the usual smuggling tools, including a
+ * second round of percent-encoding — are refused outright), no `..` and no segment starting
+ * with `.` (which rules out the design's own `.design/` working data), an `.html`/`.htm`
+ * name, and a result that still resolves inside the design folder. Pure: nothing touches
+ * the disk here; the export reads the file through the safe reader afterwards.
+ */
+
+export const EXPORT_ENTRY_RE = /^[A-Za-z0-9._/-]{1,200}\.html?$/;
+
+export interface ExportEntry {
+  /** `/`-separated, relative to the design folder. */
+  rel: string;
+  abs: string;
+}
+
+const bad = (): DesignError => new DesignError(400, "EBADENTRY", "Invalid entry: expected an .html file inside the design");
+
+export function validateExportEntry(raw: unknown, designDir: string): ExportEntry {
+  if (typeof raw !== "string" || !EXPORT_ENTRY_RE.test(raw)) throw bad();
+  const segments = raw.split("/");
+  if (segments.some((s) => s === "" || s === ".." || s.startsWith("."))) throw bad();
+  const abs = resolve(designDir, ...segments);
+  const rel = relative(designDir, abs);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw bad();
+  return { rel: rel.split(sep).join("/"), abs };
+}