@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/design/share/design-share-guest-link.ts

@@ -0,0 +1,109 @@
+import type { DesignKind } from "../../../shared/design-types.ts";
+import type { DesignVariant } from "../../../shared/design-variants.ts";
+import { projectNameForPath } from "../../project-name-for-path.ts";
+import { readDesignFileSafe } from "../design-safe-walk.ts";
+import { parseManifest, MANIFEST_FILE } from "../design-manifest.ts";
+import { manifestSystemId } from "../design-manifest-system.ts";
+import { resolveDesignVariants } from "../design-variants-resolve.ts";
+import { snapshotFilesDir } from "../design-snapshot-history.ts";
+import { resolveSnapshotScopedPath } from "../preview/design-preview-scope.ts";
+import { GUEST_VERSION_CHANGED } from "../../../shared/design-share-guest-types.ts";
+import { DesignError } from "../design-error.ts";
+import { resolveShareCode, type ResolvedShareLink } from "./design-share-resolve.ts";
+import { getShareLink } from "./design-share-links-store.ts";
+import { shareAuthEnabled } from "./design-share-link-rules.ts";
+import { INVALID_LINK_MESSAGE } from "./design-share-guest-page.ts";
+
+/**
+ * What a reviewer's code opens, as the guest routes see it: the share link resolved (see
+ * `resolveShareCode`), refused as well while its project is no longer registered in PPM,
+ * and the pinned snapshot's own manifest — title, kind, pages and app — read from the
+ * snapshot, never from the live design.
+ */
+
+export interface GuestSnapshotManifest {
+  title: string;
+  kind: DesignKind;
+  entry: string;
+  variants: DesignVariant[];
+  /** The app whose design-system files the snapshot links (`default` when none). */
+  system: string;
+}
+
+const MAX_MANIFEST_BYTES = 256 * 1024;
+/** Snapshots never change, so a manifest read once is good for as long as it is cached. */
+const MAX_CACHED_MANIFESTS = 128;
+const manifests = new Map<string, GuestSnapshotManifest>();
+
+/** The link `code` opens for a reviewer, or null for every reason it does not. */
+export async function resolveGuestLink(code: string): Promise<ResolvedShareLink | null> {
+  let resolved: ResolvedShareLink | null;
+  try {
+    resolved = await resolveShareCode(code);
+  } catch {
+    // A refused design folder (a symlink, outside the project) opens nothing either.
+    return null;
+  }
+  if (!resolved || projectNameForPath(resolved.link.projectPath) === null) return null;
+  return resolved;
+}
+
+/** Code of the refusal {@link assertGuestLinkOpen} throws; the routes answer it as a dead code. */
+export const GUEST_LINK_CLOSED = "ELINKCLOSED";
+
+/**
+ * Throws when the link `resolved` was read from no longer opens the way it did: deleted,
+ * revoked, expired, given a new code, sign-in turned off, or its project removed. With a
+ * `versionId`, also when the link now shows another snapshot than that one (a re-pin), so a
+ * comment is never pinned to a version its page was not showing. Synchronous, so it can run
+ * inside the design lock right before a reviewer's write, and again before the owner is told.
+ */
+export function assertGuestLinkOpen(resolved: ResolvedShareLink, versionId?: string): void {
+  const { link } = resolved;
+  const row = getShareLink(link.id);
+  const open = row !== null && row.revokedAt === null && (row.expiresAt === null || row.expiresAt > Date.now())
+    && row.codeVersion === link.codeVersion && row.codeHash === link.codeHash
+    && shareAuthEnabled() && projectNameForPath(row.projectPath) !== null;
+  if (!open) throw new DesignError(404, GUEST_LINK_CLOSED, INVALID_LINK_MESSAGE);
+  if (versionId !== undefined && row.snapshotId !== versionId) throw guestVersionChanged();
+}
+
+export function guestVersionChanged(): DesignError {
+  return new DesignError(409, GUEST_VERSION_CHANGED, "This design was updated. Reload the page to comment on the new version.");
+}
+
+/** True when {@link assertGuestLinkOpen} would let a write through. */
+export function guestLinkOpen(resolved: ResolvedShareLink): boolean {
+  try {
+    assertGuestLinkOpen(resolved);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readSnapshotManifestRaw(resolved: ResolvedShareLink): Promise<string | null> {
+  const { link } = resolved;
+  try {
+    const asset = await resolveSnapshotScopedPath(link, link.snapshotId, `${link.slug}/${MANIFEST_FILE}`);
+    return (await readDesignFileSafe(asset.abs, MAX_MANIFEST_BYTES)).toString("utf8");
+  } catch {
+    // Missing, refused or oversized: the snapshot reads as a design with default fields.
+    return null;
+  }
+}
+
+export async function guestSnapshotManifest(resolved: ResolvedShareLink): Promise<GuestSnapshotManifest> {
+  const { link, designDir, snapshot } = resolved;
+  const key = `${designDir}\0${snapshot.id}`;
+  const hit = manifests.get(key);
+  if (hit) return hit;
+  const { manifest } = parseManifest(await readSnapshotManifestRaw(resolved), { slug: link.slug, now: snapshot.createdAt });
+  const { variants } = await resolveDesignVariants(snapshotFilesDir(designDir, snapshot.id), manifest);
+  const value: GuestSnapshotManifest = {
+    title: manifest.title, kind: manifest.kind, entry: manifest.entry, variants, system: manifestSystemId(manifest),
+  };
+  manifests.set(key, value);
+  if (manifests.size > MAX_CACHED_MANIFESTS) manifests.delete(manifests.keys().next().value!);
+  return value;
+}

package/src/services/design/share/design-share-guest-page.ts

@@ -0,0 +1,86 @@
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * The reviewer's page shell, the one "no longer valid" page every refusal answers with, and
+ * the headers every share response carries.
+ *
+ * The shell is a separate build, `design-share-page/index.html` inside the web build. It is
+ * served only from `/s/<code>`, under its own CSP; the static route refuses its folder, so
+ * it can never be opened without that policy. The file is read once per change (mtime and
+ * size), not per request.
+ */
+
+/** Set on every `/s` response, whatever it is. */
+export const SHARE_COMMON_HEADERS: Readonly<Record<string, string>> = {
+  "Cache-Control": "no-store",
+  "Referrer-Policy": "no-referrer",
+  "X-Robots-Tag": "noindex, nofollow",
+  "X-Content-Type-Options": "nosniff",
+};
+
+/**
+ * The shell's policy: its own scripts, styles and API only, the design frame from this
+ * origin, and no service worker, manifest, plugin, form target or framing by anyone.
+ */
+export const GUEST_PAGE_CSP = [
+  "default-src 'none'",
+  "script-src 'self'",
+  "style-src 'self'",
+  "img-src 'self' data:",
+  "font-src 'self'",
+  "connect-src 'self'",
+  "frame-src 'self'",
+  "worker-src 'none'",
+  "manifest-src 'none'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'none'",
+  "object-src 'none'",
+].join("; ");
+
+/** The invalid page runs nothing; it may show inside the design frame, which is same-origin. */
+export const INVALID_PAGE_CSP = [
+  "sandbox",
+  "default-src 'none'",
+  "style-src 'unsafe-inline'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'self'",
+].join("; ");
+
+/** Same body for every reason a code does not open, so a refusal tells a guest nothing. */
+export const INVALID_PAGE_HTML = "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">"
+  + "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><meta name=\"robots\" content=\"noindex\">"
+  + "<title>Link no longer valid</title>"
+  + "<style>body{font:15px/1.5 system-ui,sans-serif;color:#555;background:#fafafa;display:grid;place-items:center;"
+  + "min-height:100vh;margin:0;padding:24px;box-sizing:border-box;text-align:center}"
+  + "@media (prefers-color-scheme:dark){body{color:#bbb;background:#161616}}h1{font-size:18px;margin:0 0 8px}</style>"
+  + "</head><body><main><h1>This link is no longer valid</h1>"
+  + "<p>Ask the person who shared it for a new link.</p></main></body></html>";
+
+/** The JSON form of the same refusal, for the API routes. */
+export const INVALID_LINK_MESSAGE = "This link is no longer valid";
+
+export const GUEST_PAGE_DIR = "design-share-page";
+const GUEST_PAGE_FILE = "index.html";
+/** The shell is a few KB; anything far larger is not the file the build writes. */
+const MAX_GUEST_PAGE_BYTES = 1024 * 1024;
+
+let cached: { path: string; mtimeMs: number; size: number; html: string } | null = null;
+
+/** The built shell under `distDir`, or null when it has not been built. */
+export async function readGuestPageHtml(distDir: string): Promise<string | null> {
+  const path = join(distDir, GUEST_PAGE_DIR, GUEST_PAGE_FILE);
+  let info;
+  try {
+    info = await stat(path);
+  } catch {
+    return null;
+  }
+  if (!info.isFile() || info.size > MAX_GUEST_PAGE_BYTES) return null;
+  if (cached && cached.path === path && cached.mtimeMs === info.mtimeMs && cached.size === info.size) return cached.html;
+  const html = await Bun.file(path).text();
+  cached = { path, mtimeMs: info.mtimeMs, size: info.size, html };
+  return html;
+}

package/src/services/design/share/design-share-link-rules.ts

@@ -0,0 +1,83 @@
+import { SHARE_LIMITS, type DesignShareErrorCode, type DesignShareLinkStatus } from "../../../shared/design-share-types.ts";
+import { configService } from "../../config.service.ts";
+import { DesignError, isDesignError } from "../design-error.ts";
+import { resolveDesignDir } from "../design-paths.ts";
+import type { ShareLinkRecord } from "./design-share-links-store.ts";
+
+/** Input checks, the status rule, and the facts both the owner list and the guest lookup need. */
+
+/** PPM sign-in. With it off, nothing is shared and no code opens a link. */
+export function shareAuthEnabled(): boolean {
+  return configService.get("auth").enabled;
+}
+
+/** The design folder, or null when the design no longer exists. */
+export async function designDirOrNull(projectPath: string, slug: string): Promise<string | null> {
+  try {
+    return await resolveDesignDir(projectPath, slug);
+  } catch (e) {
+    if (isDesignError(e) && e.status === 404) return null;
+    throw e;
+  }
+}
+
+export function shareError(status: number, code: DesignShareErrorCode, message: string): DesignError {
+  return new DesignError(status, code, message);
+}
+
+// Control characters, line breaks and the bidi overrides that could make a label read as
+// something else. Other format characters stay, or a joined emoji could not be used.
+const CONTROL_CHARS = /[\p{Cc}\p{Zl}\p{Zp}\u202A-\u202E\u2066-\u2069]/u;
+
+/** A label of at most {@link SHARE_LIMITS.maxLabelChars} printable characters, trimmed. */
+export function parseShareLabel(value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value !== "string") throw shareError(400, "bad-input", "The label must be text");
+  const label = value.trim();
+  if (CONTROL_CHARS.test(label)) throw shareError(400, "bad-input", "The label may not contain control characters");
+  if ([...label].length > SHARE_LIMITS.maxLabelChars) {
+    throw shareError(400, "bad-input", `The label may be at most ${SHARE_LIMITS.maxLabelChars} characters`);
+  }
+  return label;
+}
+
+/** Null (never expires) or an epoch-ms time after now and at most a year ahead, by server time. */
+export function parseShareExpiry(value: unknown, now: number): number | null {
+  if (value === null) return null;
+  if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+    throw shareError(400, "bad-input", "expiresAt must be null or a time in milliseconds");
+  }
+  if (value <= now) throw shareError(400, "bad-input", "The expiry must be in the future");
+  if (value > now + SHARE_LIMITS.maxExpiryMs) throw shareError(400, "bad-input", "The expiry may be at most a year ahead");
+  return value;
+}
+
+/** `true` or absent; anything else is a malformed request rather than "no". */
+export function parseFlag(value: unknown, name: string): boolean {
+  if (value === undefined) return false;
+  if (value !== true) throw shareError(400, "bad-input", `${name} must be true when given`);
+  return true;
+}
+
+export interface ShareStatusFacts {
+  now: number;
+  authEnabled: boolean;
+  /** The stored hash is the hash of the code derived from today's secret. */
+  codeCurrent: boolean;
+  /** The design and its pinned snapshot both exist. */
+  snapshotPresent: boolean;
+}
+
+/**
+ * A link's status, the most final reason first. `signin-off` comes last because it is the
+ * only one that turning sign-in back on fixes: a link reported as `signin-off` is otherwise
+ * active.
+ */
+export function shareLinkStatus(link: ShareLinkRecord, facts: ShareStatusFacts): DesignShareLinkStatus {
+  if (link.revokedAt !== null) return "revoked";
+  if (!facts.codeCurrent) return "needs-new-code";
+  if (!facts.snapshotPresent) return "design-missing";
+  if (link.expiresAt !== null && link.expiresAt <= facts.now) return "expired";
+  if (!facts.authEnabled) return "signin-off";
+  return "active";
+}

package/src/services/design/share/design-share-links-store.ts

@@ -0,0 +1,157 @@
+import { getDb } from "../../db.service.ts";
+import { SHARE_LIMITS } from "../../../shared/design-share-types.ts";
+
+/** Rows of `design_share_links`. No column holds a code: only `code_hash`. */
+
+export interface ShareLinkRecord {
+  id: string;
+  codeHash: string;
+  codeVersion: number;
+  projectPath: string;
+  projectKey: string;
+  slug: string;
+  snapshotId: string;
+  label: string;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number | null;
+  revokedAt: number | null;
+}
+
+interface ShareLinkRow {
+  id: string;
+  code_hash: string;
+  code_version: number;
+  project_path: string;
+  project_key: string;
+  slug: string;
+  snapshot_id: string;
+  label: string;
+  created_at: number;
+  updated_at: number;
+  expires_at: number | null;
+  revoked_at: number | null;
+}
+
+function toRecord(r: ShareLinkRow): ShareLinkRecord {
+  return {
+    id: r.id,
+    codeHash: r.code_hash,
+    codeVersion: r.code_version,
+    projectPath: r.project_path,
+    projectKey: r.project_key,
+    slug: r.slug,
+    snapshotId: r.snapshot_id,
+    label: r.label,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+    expiresAt: r.expires_at,
+    revokedAt: r.revoked_at,
+  };
+}
+
+const COLUMNS = "id, code_hash, code_version, project_path, project_key, slug, snapshot_id, label, created_at, updated_at, expires_at, revoked_at";
+
+/**
+ * Insert a link unless its design already has {@link SHARE_LIMITS.maxLinksPerDesign}.
+ * Count and insert run in one transaction, so two creates cannot both take the last slot.
+ */
+export function insertShareLink(record: ShareLinkRecord): boolean {
+  const db = getDb();
+  return db.transaction(() => {
+    const { n } = db.query("SELECT COUNT(*) AS n FROM design_share_links WHERE project_key = ? AND slug = ?")
+      .get(record.projectKey, record.slug) as { n: number };
+    if (n >= SHARE_LIMITS.maxLinksPerDesign) return false;
+    db.query(`INSERT INTO design_share_links (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+      record.id, record.codeHash, record.codeVersion, record.projectPath, record.projectKey, record.slug,
+      record.snapshotId, record.label, record.createdAt, record.updatedAt, record.expiresAt, record.revokedAt,
+    );
+    return true;
+  }).immediate();
+}
+
+export function getShareLink(id: string): ShareLinkRecord | null {
+  const row = getDb().query(`SELECT ${COLUMNS} FROM design_share_links WHERE id = ?`).get(id) as ShareLinkRow | null;
+  return row ? toRecord(row) : null;
+}
+
+export function getShareLinkByCodeHash(codeHash: string): ShareLinkRecord | null {
+  const row = getDb().query(`SELECT ${COLUMNS} FROM design_share_links WHERE code_hash = ?`).get(codeHash) as ShareLinkRow | null;
+  return row ? toRecord(row) : null;
+}
+
+/** One design's links, oldest first. */
+export function listShareLinksForDesign(projectKey: string, slug: string): ShareLinkRecord[] {
+  const rows = getDb().query(`SELECT ${COLUMNS} FROM design_share_links WHERE project_key = ? AND slug = ? ORDER BY created_at, id`)
+    .all(projectKey, slug) as ShareLinkRow[];
+  return rows.map(toRecord);
+}
+
+/** What one owner request changes on a link. Absent fields are left as the row has them. */
+export interface ShareLinkChange {
+  updatedAt: number;
+  label?: string;
+  expiresAt?: number | null;
+  revoke?: boolean;
+  /** Issue the next code: the hash of the code for a given version. */
+  newCodeHash?: (version: number) => string;
+  snapshotId?: string;
+}
+
+export type ShareLinkChangeResult =
+  | { record: ShareLinkRecord; previous: ShareLinkRecord }
+  | "missing"
+  | "revoked";
+
+/**
+ * Apply `change` to the row as it is now, in one transaction, writing only the columns the
+ * change names. The caller may have awaited a snapshot since it last read the row, and a
+ * revoke, new code or expiry committed meanwhile must survive: a new code counts up from the
+ * stored version, `revoked_at` once set is never cleared, and a re-pin or new code on a row
+ * revoked meanwhile is refused instead of applied.
+ */
+export function applyShareLinkChange(id: string, change: ShareLinkChange): ShareLinkChangeResult {
+  const db = getDb();
+  return db.transaction((): ShareLinkChangeResult => {
+    const previous = getShareLink(id);
+    if (!previous) return "missing";
+    if ((change.newCodeHash || change.snapshotId !== undefined) && previous.revokedAt !== null) return "revoked";
+    const sets = ["updated_at = ?"];
+    const values: (string | number | null)[] = [change.updatedAt];
+    const set = (column: string, value: string | number | null) => { sets.push(`${column} = ?`); values.push(value); };
+    if (change.label !== undefined) set("label", change.label);
+    if (change.expiresAt !== undefined) set("expires_at", change.expiresAt);
+    if (change.snapshotId !== undefined) set("snapshot_id", change.snapshotId);
+    if (change.newCodeHash) {
+      const version = previous.codeVersion + 1;
+      set("code_version", version);
+      set("code_hash", change.newCodeHash(version));
+    }
+    if (change.revoke) {
+      sets.push("revoked_at = COALESCE(revoked_at, ?)");
+      values.push(change.updatedAt);
+    }
+    db.query(`UPDATE design_share_links SET ${sets.join(", ")} WHERE id = ?`).run(...values, id);
+    return { record: getShareLink(id)!, previous };
+  }).immediate();
+}
+
+export function deleteShareLinkRow(id: string): boolean {
+  return getDb().query("DELETE FROM design_share_links WHERE id = ?").run(id).changes > 0;
+}
+
+/** Remove every link of a design; returns how many went. */
+export function deleteShareLinksForDesign(projectKey: string, slug: string): number {
+  return getDb().query("DELETE FROM design_share_links WHERE project_key = ? AND slug = ?").run(projectKey, slug).changes;
+}
+
+/**
+ * Snapshots a design's links pin, which pruning must keep. Expired links count too, because
+ * the owner may extend them; revoked ones do not, because revoking is final.
+ */
+export function pinnedSnapshotIds(projectKey: string, slug: string): Set<string> {
+  const rows = getDb().query(
+    "SELECT DISTINCT snapshot_id FROM design_share_links WHERE project_key = ? AND slug = ? AND revoked_at IS NULL",
+  ).all(projectKey, slug) as { snapshot_id: string }[];
+  return new Set(rows.map((r) => r.snapshot_id));
+}

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

@@ -0,0 +1,174 @@
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+import { isSnapshotId, type DesignSnapshotInfo } from "../../../shared/design-types.ts";
+import {
+  SHARE_LIMITS, SHARE_PATH_PREFIX, type DesignShareChangedFiles, type DesignShareLink, type UpdateDesignShareResult,
+} from "../../../shared/design-share-types.ts";
+import { projectKey } from "../../project-name-for-path.ts";
+import { isValidDesignSlug } from "../design-slug.ts";
+import { withRecoveredDesign } from "../design-restore-journal.ts";
+import { readSnapshotInfo } from "../design-snapshot-history.ts";
+import { snapshotDesign } from "../design-snapshots.service.ts";
+import { deriveCode, hashCode } from "./design-share-code.ts";
+import {
+  applyShareLinkChange, deleteShareLinkRow, getShareLink, insertShareLink, listShareLinksForDesign,
+  type ShareLinkRecord,
+} from "./design-share-links-store.ts";
+import {
+  designDirOrNull, parseFlag, parseShareExpiry, parseShareLabel, shareAuthEnabled, shareError, shareLinkStatus,
+} from "./design-share-link-rules.ts";
+import { diffSnapshotFiles, diffSnapshotWithLive } from "./design-share-changed-files.ts";
+
+/**
+ * The owner's share links and the one lookup a guest request goes through.
+ *
+ * While PPM sign-in is off nothing can be shared: a public address would then expose all of
+ * PPM, not one design. New links, re-pins and new codes are refused, and no code resolves.
+ * The rows are kept, so the links open again once sign-in is back on.
+ */
+
+function requireSignIn(): void {
+  if (!shareAuthEnabled()) throw shareError(409, "signin-off", "Turn on PPM sign-in before sharing");
+}
+
+function newRecord(projectPath: string, slug: string, snapshotId: string, label: string, expiresAt: number | null): ShareLinkRecord {
+  const id = randomBytes(6).toString("hex");
+  const now = Date.now();
+  return {
+    id, codeHash: hashCode(deriveCode(id, 1)), codeVersion: 1,
+    projectPath: resolve(projectPath), projectKey: projectKey(projectPath), slug, snapshotId,
+    label, createdAt: now, updatedAt: now, expiresAt, revokedAt: null,
+  };
+}
+
+/** The owner's view of a row. The code is re-derived; only a hash was ever stored. */
+function toLink(record: ShareLinkRecord, snapshot: DesignSnapshotInfo | null): DesignShareLink {
+  const code = deriveCode(record.id, record.codeVersion);
+  const codeCurrent = hashCode(code) === record.codeHash;
+  const status = shareLinkStatus(record, {
+    now: Date.now(), authEnabled: shareAuthEnabled(), codeCurrent, snapshotPresent: snapshot !== null,
+  });
+  const issuable = codeCurrent && status !== "revoked";
+  return {
+    id: record.id, label: record.label, snapshotId: record.snapshotId,
+    snapshotCreatedAt: snapshot?.createdAt ?? null,
+    createdAt: record.createdAt, updatedAt: record.updatedAt,
+    expiresAt: record.expiresAt, revokedAt: record.revokedAt,
+    status, path: issuable ? `${SHARE_PATH_PREFIX}${code}` : null,
+  };
+}
+
+async function linkView(record: ShareLinkRecord): Promise<DesignShareLink> {
+  const dir = await designDirOrNull(record.projectPath, record.slug);
+  return toLink(record, dir ? await readSnapshotInfo(dir, record.snapshotId) : null);
+}
+
+/** The pin a manual snapshot taken now gives: a new snapshot, or the newest when nothing changed. */
+async function snapshotNow(projectPath: string, slug: string): Promise<string> {
+  const taken = await snapshotDesign(projectPath, slug, "manual");
+  if ("id" in taken) return taken.id;
+  if (taken.skipped === "unchanged") return taken.sameAs;
+  if (taken.skipped === "missing") throw shareError(404, "not-found", `Design not found: ${slug}`);
+  throw shareError(409, "too-large", "The design is too large to snapshot, so it cannot be shared");
+}
+
+const limitReached = () => shareError(
+  409, "limit", `This design already has ${SHARE_LIMITS.maxLinksPerDesign} share links; delete one first`,
+);
+
+function insertOrRefuse(record: ShareLinkRecord): void {
+  if (!insertShareLink(record)) throw limitReached();
+}
+
+export async function createShareLink(projectPath: string, slug: string, input: Record<string, unknown>): Promise<DesignShareLink> {
+  requireSignIn();
+  const label = parseShareLabel(input.label);
+  if (!("expiresAt" in input)) throw shareError(400, "bad-input", "expiresAt is required (null for never)");
+  const expiresAt = parseShareExpiry(input.expiresAt, Date.now());
+  const version = input.version;
+  // Checked again by the insert; this only spares a snapshot that could not be used.
+  if (listShareLinksForDesign(projectKey(projectPath), slug).length >= SHARE_LIMITS.maxLinksPerDesign) throw limitReached();
+  if (version === "current") {
+    const record = newRecord(projectPath, slug, await snapshotNow(projectPath, slug), label, expiresAt);
+    insertOrRefuse(record);
+    return linkView(record);
+  }
+  if (!isSnapshotId(version)) throw shareError(400, "bad-input", 'version must be "current" or a snapshot id');
+  // Under the design lock, so the snapshot cannot be pruned between the check and the insert.
+  return withRecoveredDesign(projectPath, slug, async (dir) => {
+    const info = await readSnapshotInfo(dir, version);
+    if (!info) throw shareError(404, "not-found", `Snapshot not found: ${version}`);
+    const record = newRecord(projectPath, slug, version, label, expiresAt);
+    insertOrRefuse(record);
+    return toLink(record, info);
+  });
+}
+
+export async function listShareLinks(projectPath: string, slug: string): Promise<DesignShareLink[]> {
+  if (!isValidDesignSlug(slug)) throw shareError(400, "bad-input", "Invalid design slug");
+  const records = listShareLinksForDesign(projectKey(projectPath), slug);
+  const dir = records.length ? await designDirOrNull(projectPath, slug) : null;
+  return Promise.all(records.map(async (r) => toLink(r, dir ? await readSnapshotInfo(dir, r.snapshotId) : null)));
+}
+
+/** A link of this design, or a 404 (a link of another design is not this route's to touch). */
+function ownLink(projectPath: string, slug: string, id: string): ShareLinkRecord {
+  const record = getShareLink(id);
+  if (!record || record.projectKey !== projectKey(projectPath) || record.slug !== slug) {
+    throw shareError(404, "not-found", "Share link not found");
+  }
+  return record;
+}
+
+export async function updateShareLink(
+  projectPath: string, slug: string, id: string, input: Record<string, unknown>,
+): Promise<UpdateDesignShareResult> {
+  const record = ownLink(projectPath, slug, id);
+  const now = Date.now();
+  const revoke = parseFlag(input.revoke, "revoke");
+  const repin = parseFlag(input.repin, "repin");
+  const newCode = parseFlag(input.newCode, "newCode");
+  const label = "label" in input ? parseShareLabel(input.label) : undefined;
+  const expiresAt = "expiresAt" in input ? parseShareExpiry(input.expiresAt, now) : undefined;
+  if (!revoke && !repin && !newCode && label === undefined && expiresAt === undefined) {
+    throw shareError(400, "bad-input", "Nothing to change");
+  }
+  if ((repin || newCode) && (revoke || record.revokedAt !== null)) {
+    throw shareError(409, "revoked", "A revoked link cannot be re-pinned or given a new code");
+  }
+  if (repin || newCode) requireSignIn();
+
+  // Only what this request names is written, against the row as it is after the snapshot:
+  // a revoke or new code from another tab committed while it ran is kept, never undone.
+  const snapshotId = repin ? await snapshotNow(projectPath, slug) : undefined;
+  const applied = applyShareLinkChange(id, {
+    updatedAt: Date.now(), label, expiresAt, revoke, snapshotId,
+    newCodeHash: newCode ? (version) => hashCode(deriveCode(id, version)) : undefined,
+  });
+  if (applied === "missing") throw shareError(404, "not-found", "Share link not found");
+  if (applied === "revoked") throw shareError(409, "revoked", "This link was revoked, so it cannot be re-pinned or given a new code");
+  const link = await linkView(applied.record);
+  if (!repin) return { link };
+  const dir = await designDirOrNull(projectPath, slug);
+  const changedFiles = dir ? await diffSnapshotFiles(dir, applied.previous.snapshotId, applied.record.snapshotId) : null;
+  return { link, changedFiles };
+}
+
+/**
+ * What "Update to latest" would change for reviewers of this link: its pinned snapshot
+ * against the live design files, read the way the re-pin's snapshot would be. Null when the
+ * pinned snapshot is gone. Read under the design lock, so neither a prune nor a restore can
+ * move files while they are compared.
+ */
+export async function previewShareRepin(projectPath: string, slug: string, id: string): Promise<DesignShareChangedFiles | null> {
+  const record = ownLink(projectPath, slug, id);
+  if (record.revokedAt !== null) throw shareError(409, "revoked", "A revoked link cannot be re-pinned");
+  return withRecoveredDesign(projectPath, slug, (dir) => diffSnapshotWithLive(dir, record.snapshotId));
+}
+
+export function deleteShareLink(projectPath: string, slug: string, id: string): void {
+  ownLink(projectPath, slug, id);
+  if (!deleteShareLinkRow(id)) throw shareError(404, "not-found", "Share link not found");
+}
+
+export { resolveShareCode, type ResolvedShareLink } from "./design-share-resolve.ts";