@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/sharing/client.ts

@@ -0,0 +1,334 @@
+import { randomUUID } from "node:crypto";
+
+import { type JsonValue, parseJsonText } from "@dev.fast/json";
+import {
+  MAX_SHARE_MANIFEST_BYTES,
+  type ShareManifest,
+  shareManifestSchema,
+} from "@dev.fast/review-share-protocol";
+import {
+  StreamLimitError,
+  readBoundedStream,
+} from "@review/server/bounded-stream.js";
+import { z } from "zod";
+
+import { type ShareBundle, digestBytes } from "./export.js";
+import { validateShareBundle } from "./import.js";
+
+const uploadSchema = z.strictObject({
+  url: z.url(),
+  headers: z.record(z.string(), z.string()),
+  expiresAt: z.string(),
+});
+
+const createdSchema = z.strictObject({
+  shareId: z.uuid(),
+  upload: uploadSchema,
+});
+
+const registeredSchema = z.object({
+  registered: z.literal(true),
+  uploads: z.record(z.string(), uploadSchema),
+});
+
+const UPLOAD_CONCURRENCY = 4;
+
+// Presigned URLs and headers are larger than manifest object descriptors.
+const MAX_UPLOAD_RESPONSE_BYTES = 8 * 1024 * 1024;
+
+const linkSchema = z.strictObject({ shareId: z.uuid(), url: z.url() });
+
+const receivedSchema = z.strictObject({
+  manifest: shareManifestSchema,
+  sender: z.strictObject({ login: z.string().min(1).max(256) }),
+  sharedAt: z.number(),
+});
+
+const signedUrlSchema = z.url().refine((value) => {
+  const url = new URL(value);
+
+  return url.protocol === "https:" && !url.username && !url.password;
+});
+
+const downloadSchema = z.strictObject({ url: z.url(), expiresAt: z.string() });
+
+/** Size is checked while reading, even if Content-Length is absent or false. */
+export async function readBoundedBytes(
+  response: Response,
+  limit: number,
+): Promise<Uint8Array> {
+  if (!response.ok || !response.body)
+    throw new Error(`Download failed (${response.status}).`);
+  const declared = response.headers.get("content-length");
+
+  if (declared && Number(declared) > limit) {
+    await response.body.cancel().catch(() => {});
+    throw new Error("Download exceeds its declared limit.");
+  }
+
+  try {
+    return await readBoundedStream(response.body, limit);
+  } catch (error) {
+    if (error instanceof StreamLimitError)
+      throw new Error("Download exceeds its declared limit.");
+    throw error;
+  }
+}
+
+/** The share service rejected the account token; the stored login is stale. */
+export class ShareAuthError extends Error {
+  constructor() {
+    super("The share service rejected the stored login.");
+    this.name = "ShareAuthError";
+  }
+}
+
+export class SharePreflightError extends Error {
+  constructor(cause: unknown) {
+    super(
+      cause instanceof Error
+        ? cause.message
+        : "Repository verification failed.",
+      { cause },
+    );
+    this.name = "SharePreflightError";
+  }
+}
+
+class ShareRequestError extends Error {
+  constructor(readonly status: number) {
+    super(`Share request failed (${status}).`);
+  }
+}
+
+/** Account tokens go only to the configured API origin, never to object storage. */
+export class ShareClient {
+  private readonly origin: string;
+  constructor(
+    origin: string,
+    private readonly token?: string,
+    private readonly send: typeof fetch = fetch,
+  ) {
+    const url = new URL(origin);
+
+    if (
+      url.username ||
+      url.password ||
+      (url.protocol !== "https:" &&
+        !(url.protocol === "http:" && url.hostname === "localhost"))
+    )
+      throw new Error("Use a secure share service origin.");
+    this.origin = url.origin;
+  }
+
+  private async api(
+    route: string,
+    method = "GET",
+    body?: JsonValue,
+    capability?: string,
+    maxBytes = MAX_SHARE_MANIFEST_BYTES,
+  ): Promise<JsonValue> {
+    const headers = new Headers({ "content-type": "application/json" });
+
+    if (capability) headers.set("x-review-share-token", capability);
+    else if (this.token) headers.set("authorization", `Bearer ${this.token}`);
+
+    const init: RequestInit = {
+      method,
+      redirect: "error",
+      signal: AbortSignal.timeout(60_000),
+      headers,
+    };
+
+    if (body !== undefined) init.body = JSON.stringify(body);
+    const response = await this.send(this.origin + route, init);
+
+    if (!response.ok) {
+      await response.body?.cancel();
+
+      if (response.status === 401 && !capability) throw new ShareAuthError();
+      throw new ShareRequestError(response.status);
+    }
+
+    return parseJsonText(
+      Buffer.from(await readBoundedBytes(response, maxBytes)).toString(),
+    );
+  }
+
+  private async upload(
+    upload: z.infer<typeof uploadSchema>,
+    bytes: Uint8Array,
+  ) {
+    if (!signedUrlSchema.safeParse(upload.url).success)
+      throw new Error("Invalid object upload URL.");
+
+    const response = await this.send(upload.url, {
+      method: "PUT",
+      headers: upload.headers,
+      body: Buffer.from(bytes),
+      redirect: "error",
+      signal: AbortSignal.timeout(120_000),
+    });
+
+    // Conditional create can return 412 after a successful upload whose response
+    // was lost. Completion checks the actual stored digest before publication.
+    await response.body?.cancel();
+
+    if (!response.ok && response.status !== 412)
+      throw new Error(`Object upload failed (${response.status}).`);
+  }
+
+  async create(
+    bundle: ShareBundle,
+    requestId: string = randomUUID(),
+    beforeUpload?: () => Promise<void>,
+  ) {
+    validateShareBundle(bundle);
+    const manifestBytes = Buffer.from(JSON.stringify(bundle.manifest));
+
+    const created = createdSchema.parse(
+      await this.api("/api/shares", "POST", {
+        requestId,
+        manifest: {
+          size: manifestBytes.byteLength,
+          sha256: digestBytes(manifestBytes),
+        },
+      }),
+    );
+
+    const route = `/api/shares/${created.shareId}`;
+    await this.upload(created.upload, manifestBytes);
+
+    const { uploads } = registeredSchema.parse(
+      await this.api(
+        `${route}/manifest`,
+        "POST",
+        {},
+        undefined,
+        MAX_UPLOAD_RESPONSE_BYTES,
+      ),
+    );
+
+    try {
+      if (bundle.manifest.objects.some(({ id }) => !uploads[id]))
+        throw new Error("The share service omitted an object upload URL.");
+
+      await beforeUpload?.();
+    } catch (error) {
+      // A retry may recover an already published share after a lost response.
+      await this.recoverLink(created.shareId)
+        .catch(async (failure) => {
+          if (failure instanceof ShareRequestError && failure.status === 409)
+            await this.revoke(created.shareId);
+        })
+        .catch(() => {});
+      throw new SharePreflightError(error);
+    }
+
+    for (
+      let offset = 0;
+      offset < bundle.manifest.objects.length;
+      offset += UPLOAD_CONCURRENCY
+    ) {
+      const results = await Promise.allSettled(
+        bundle.manifest.objects
+          .slice(offset, offset + UPLOAD_CONCURRENCY)
+          .map(async (object) => {
+            await this.upload(
+              uploads[object.id]!,
+              bundle.objects.get(object.id)!,
+            );
+          }),
+      );
+
+      const failed = results.find((result) => result.status === "rejected");
+
+      if (failed) throw failed.reason;
+    }
+
+    for (
+      let batch = 0;
+      batch <= Math.ceil(bundle.manifest.objects.length / 32);
+      batch++
+    ) {
+      const result = await this.api(`${route}/complete`, "POST", {});
+
+      if (linkSchema.safeParse(result).success) return linkSchema.parse(result);
+      z.strictObject({ complete: z.literal(false) }).parse(result);
+    }
+
+    throw new Error("Share verification did not finish.");
+  }
+
+  async list(cursor?: string) {
+    const query = cursor ? `?cursor=${z.uuid().parse(cursor)}` : "";
+
+    return this.api(`/api/shares${query}`);
+  }
+
+  async recoverLink(shareId: string) {
+    return linkSchema.parse(
+      await this.api(`/api/shares/${z.uuid().parse(shareId)}/link`),
+    );
+  }
+
+  async revoke(shareId: string) {
+    return this.api(`/api/shares/${z.uuid().parse(shareId)}`, "DELETE");
+  }
+
+  async download(shareId: string, capability: string): Promise<ShareBundle> {
+    const route = `/api/shared/${z.uuid().parse(shareId)}`;
+
+    const received = receivedSchema.parse(
+      await this.api(route, "GET", undefined, capability),
+    );
+
+    const manifest: ShareManifest = received.manifest;
+    const objects = new Map<string, Uint8Array>();
+
+    const download = async (object: ShareManifest["objects"][number]) => {
+      const signed = downloadSchema.parse(
+        await this.api(
+          `${route}/objects/${object.id}`,
+          "GET",
+          undefined,
+          capability,
+        ),
+      );
+
+      if (!signedUrlSchema.safeParse(signed.url).success)
+        throw new Error("Invalid object download URL.");
+
+      const bytes = await readBoundedBytes(
+        await this.send(signed.url, {
+          redirect: "error",
+          signal: AbortSignal.timeout(120_000),
+        }),
+        object.size,
+      );
+
+      if (
+        bytes.byteLength !== object.size ||
+        digestBytes(bytes) !== object.sha256
+      )
+        throw new Error("Downloaded share object failed its integrity check.");
+      objects.set(object.id, bytes);
+    };
+
+    for (let start = 0; start < manifest.objects.length; start += 4)
+      await Promise.all(manifest.objects.slice(start, start + 4).map(download));
+
+    const bundle = {
+      manifest,
+      objects,
+      attribution: {
+        login: received.sender.login,
+        sharedAt: received.sharedAt,
+      },
+    };
+
+    // Document validation happens once at the importer boundary.
+
+    return bundle;
+  }
+}

package/src/sharing/export.ts

@@ -0,0 +1,195 @@
+import { createHash } from "node:crypto";
+
+import {
+  MAX_SHARE_BYTES,
+  MAX_SHARE_MANIFEST_BYTES,
+  MAX_SHARE_OBJECT_BYTES,
+  SHARE_FORMAT,
+  type ShareManifest,
+  shareManifestSchema,
+} from "@dev.fast/review-share-protocol";
+import { sourceAnchors } from "@review/lens-selection.js";
+import { markdownNodes, parseMarkdown } from "@review/markdown.js";
+import { lensSelections } from "@review/review-api/diff-lenses.js";
+import { ReviewInputError } from "@review/review-api/document.js";
+import {
+  anchorPins,
+  checkReferences,
+  documentSchema,
+  elements,
+  hasCodeReferences,
+  resourceReference,
+  resourceReferences,
+  sourceReferences,
+} from "@review/review-api/document.js";
+import type { LocalReviewData } from "@review/review-api/local-data.js";
+import type { ReviewStore, Snapshot } from "@review/review-api/store.js";
+import { z } from "zod";
+
+export interface ShareBundle {
+  manifest: ShareManifest;
+  objects: Map<string, Uint8Array>;
+  attribution?: { login: string; sharedAt: number };
+}
+
+export type ShareExportStore = Pick<ReviewStore, "read" | "resource">;
+
+export type ShareExportData = Pick<
+  LocalReviewData,
+  "map" | "validateResource" | "validateSource"
+>;
+
+export function digestBytes(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function validateShareSources(
+  snapshot: Pick<Snapshot, "pins" | "document" | "lenses">,
+) {
+  if (!snapshot.pins && hasCodeReferences(snapshot))
+    throw new ReviewInputError(
+      "Reviews with code references need source pins before sharing.",
+      409,
+    );
+}
+
+/** Freeze one stored version before any asynchronous source reads. */
+export async function exportShare(input: {
+  store: ShareExportStore;
+  data: ShareExportData;
+  reviewId: string;
+  version?: number;
+  repository?: ShareManifest["repository"];
+}): Promise<ShareBundle> {
+  // A share is the finished document: what edit last touched it stays home.
+  const {
+    target,
+    kind: _kind,
+    staleSources: _staleSources,
+    sourceUnavailable: _sourceUnavailable,
+    lastEdit: _lastEdit,
+    ...snapshot
+  } = structuredClone(input.store.read(input.reviewId, input.version));
+
+  if (target?.kind === "worktree")
+    throw new ReviewInputError("Pin this review to commits before sharing it.");
+
+  documentSchema.parse(snapshot.document);
+  checkReferences(snapshot.document);
+  const objects = new Map<string, Uint8Array>();
+  let totalBytes = 0;
+
+  const add = (bytes: Uint8Array) => {
+    if (bytes.byteLength > MAX_SHARE_OBJECT_BYTES)
+      throw new ReviewInputError("A shared object exceeds the upload limit.");
+    const id = digestBytes(bytes);
+
+    if (!objects.has(id)) {
+      totalBytes += bytes.byteLength;
+
+      if (totalBytes > MAX_SHARE_BYTES)
+        throw new ReviewInputError("Review exceeds the sharing limit.");
+      objects.set(id, Uint8Array.from(bytes));
+    }
+
+    return id;
+  };
+
+  const json = <Value>(value: Value) => add(Buffer.from(JSON.stringify(value)));
+  const resources: ShareManifest["resources"] = [];
+  const maps: Record<string, Awaited<ReturnType<LocalReviewData["map"]>>> = {};
+
+  // Lens ranges travel with the snapshot and must resolve at its pins too.
+  const sources = [
+    ...sourceReferences(snapshot.document),
+    ...lensSelections(snapshot.lenses ?? []).flatMap((selection) =>
+      sourceAnchors(selection.source).map((source) => ({
+        ...selection,
+        source,
+        peek: false,
+      })),
+    ),
+  ];
+
+  const pins = snapshot.pins;
+
+  validateShareSources(snapshot);
+
+  if (Boolean(pins) !== Boolean(input.repository))
+    throw new ReviewInputError("Shared source pins require a repository.", 409);
+
+  for (const block of elements(snapshot.document)) {
+    if (block.type !== "markdown") continue;
+
+    for (const node of markdownNodes(parseMarkdown(block.markdown)))
+      if (node.type === "image")
+        throw new ReviewInputError(
+          "Convert Markdown images to managed image blocks before sharing.",
+        );
+  }
+
+  for (const block of resourceReferences(snapshot.document)) {
+    await input.data.validateResource(pins, block);
+
+    const reference = resourceReference(block);
+
+    if (
+      !reference ||
+      resources.some((resource) => resource.id === reference.id)
+    )
+      continue;
+    const { id } = reference;
+    const resource = input.store.resource(id);
+    resources.push({
+      id,
+      kind: z.enum(["image", "trace", "map"]).parse(resource.kind),
+      mimeType: z
+        .enum(["image/png", "application/json"])
+        .parse(resource.mimeType),
+      object: add(resource.data),
+    });
+
+    if (block.type === "software_map") {
+      const map = await input.data.map(pins, id);
+      Object.defineProperty(maps, id, { value: map, enumerable: true });
+
+      for (const element of map.elements)
+        for (const range of element.sourceRanges ?? [])
+          sources.push({
+            id: `${id}:${element.id}`,
+            source: { ...range, side: map.side },
+          });
+    }
+  }
+
+  for (const reference of sources)
+    await input.data.validateSource(
+      anchorPins(reference.source, pins),
+      reference.source,
+      { peek: reference.peek ?? false },
+    );
+
+  const snapshotId = json(snapshot);
+  const presentationId = json({ maps });
+
+  const manifest = shareManifestSchema.parse({
+    format: SHARE_FORMAT,
+    reviewId: snapshot.reviewId,
+    version: snapshot.version,
+    title: snapshot.title,
+    snapshot: snapshotId,
+    presentation: presentationId,
+    objects: [...objects].map(([id, bytes]) => ({
+      id,
+      sha256: id,
+      size: bytes.byteLength,
+    })),
+    resources,
+    repository: input.repository,
+  });
+
+  if (Buffer.byteLength(JSON.stringify(manifest)) > MAX_SHARE_MANIFEST_BYTES)
+    throw new ReviewInputError("The share manifest exceeds the upload limit.");
+
+  return { manifest, objects };
+}