@djangocfg/widget-chat 0.1.1

package/src/core/links/scheme.ts

@@ -0,0 +1,98 @@
+/**
+ * The mention URL scheme: how a chip in a message names a thing outside it.
+ *
+ * A mention has to survive a round trip through markdown — a chip is written as
+ * a link, sent as text, parsed back, and re-drawn as a chip. That needs a URL
+ * shape both halves agree on, and a plain `https:` link cannot carry it: the
+ * host must be able to tell "open this thing I know about" from "follow this
+ * link", and only a distinct scheme says so.
+ *
+ * ## Why the scheme is configurable and the shapes are not
+ *
+ * The SCHEME is the host's — it is their product's name, and it is what their
+ * desktop shell or deep-link handler registers. The SHAPES are ours: the chat
+ * writes them and the chat parses them, so a host redefining them would break
+ * its own round trip.
+ *
+ * ```
+ * <scheme>://tool/<id>               a tool the user picked
+ * ```
+ *
+ * One shape, because only one thing here is the chat's own. A host that mentions
+ * users, documents or tickets addresses them with its own scheme and resolves
+ * them itself; this module would only be guessing at their grammar. The other
+ * shapes that used to live here were one product's nouns and left with it.
+ *
+ * Nothing here reaches a network. These are addresses the host resolves when a
+ * chip is clicked; this module only writes and reads them.
+ */
+
+/** The default scheme. Override with {@link configureMentionScheme}. */
+const DEFAULT_SCHEME = "app";
+
+let scheme = DEFAULT_SCHEME;
+
+/**
+ * Set the URL scheme mentions are written with.
+ *
+ * Call once at startup, before any message is rendered. Changing it later
+ * leaves already-written messages addressing the old scheme, which then parse
+ * as plain links — which is the honest outcome, but not one to arrive at by
+ * accident.
+ */
+export function configureMentionScheme(next: string): void {
+  scheme = next.replace(/:$/, "");
+}
+
+/** The scheme in force. Exposed so a link-hardening allowlist can name it. */
+export function mentionScheme(): string {
+  return scheme;
+}
+
+const HOST_TOOL = "tool";
+
+// --- Writers ---------------------------------------------------------------
+
+/**
+ * `<scheme>://tool/<id>`.
+ *
+ * An empty id returns the bare host, which parses but names no tool; a renderer
+ * leaves that as plain text rather than minting a chip that stands for nothing.
+ */
+export function toolURL(id: string): string {
+  return id ? `${scheme}://${HOST_TOOL}/${encodeURIComponent(id)}` : `${scheme}://${HOST_TOOL}`;
+}
+
+// --- Reader ----------------------------------------------------------------
+
+export type ParsedMention = { readonly kind: "tool"; readonly toolID: string };
+
+export type ParseResult =
+  | { readonly ok: true; readonly parsed: ParsedMention }
+  | { readonly ok: false; readonly error: "malformed" | "not-mention-url" | "missing-id" };
+
+/**
+ * Read a mention URL back into its parts.
+ *
+ * A result rather than a throw: an ordinary link in a message reaches here on
+ * every render, and "this is not one of ours" is the common case, not a fault.
+ */
+export function parse(href: string): ParseResult {
+  let url: URL;
+  try {
+    url = new URL(href);
+  } catch {
+    return { ok: false, error: "malformed" };
+  }
+  // `URL.protocol` carries the trailing colon.
+  if (url.protocol !== `${scheme}:`) return { ok: false, error: "not-mention-url" };
+
+  // `URL.pathname` opens with "/", so the first split entry is always empty.
+  const segments = url.pathname.split("/").filter((segment) => segment.length > 0);
+
+  if (url.hostname !== HOST_TOOL) return { ok: false, error: "not-mention-url" };
+
+  const [rawID] = segments;
+  if (rawID === undefined) return { ok: false, error: "missing-id" };
+  return { ok: true, parsed: { kind: "tool", toolID: decodeURIComponent(rawID) } };
+}

package/src/core/links/tool-id.ts

@@ -0,0 +1,26 @@
+import { parse as parseMentionUrl } from "./scheme";
+
+/**
+ * `app://tool/<id>` — the link a picked tool becomes in the outbound text.
+ *
+ * Unlike a named correspondent there is no `@token` preprocess step here: the
+ * COMPOSER writes the link itself, so the id never has to be recovered from
+ * prose. This module owns only the reading half.
+ */
+
+/**
+ * Extract the tool id from a `app://tool/<id>` href, or null for any other
+ * shape. Uses the single-sourced `core/links` parser so the scheme stays in
+ * lock-step with Go.
+ *
+ * A bare `app://tool` parses but names no tool, and returns null here — the
+ * caller must treat "no id" and "not a tool link" the same way, since neither
+ * identifies anything a chip could stand for.
+ */
+export function extractToolId(href: string | undefined): string | null {
+  if (!href) return null;
+  const r = parseMentionUrl(href);
+  if (!r.ok) return null;
+  if (r.parsed.kind !== "tool") return null;
+  return r.parsed.toolID || null;
+}

package/src/core/media/allowed-src.ts

@@ -0,0 +1,138 @@
+/**
+ * The media `src` allowlist — a security boundary, mirrored from the server.
+ *
+ * SOURCE OF TRUTH: the server's own `src` allowlist and same-origin rule. This
+ * is a deliberate second implementation, not a duplicated helper: the server
+ * gates what a TOOL may emit, this side gates what a BROWSER will load, and a
+ * block can reach the DOM through a stored transcript no live server process
+ * re-validated.
+ *
+ * The stake, plainly: an unvalidated preview image is an exfil vector. A model-authored `<img src>` is an outbound GET the user never
+ * asked for, carrying the page's referrer and cookies to whoever the model
+ * names.
+ *
+ * The server also fixes the rendering contract, and it holds here too: blocks are
+ * RENDER-ONLY. Nothing in this package may interpret a block as an action.
+ *
+ * Keep in lock-step with whatever the server enforces. Divergence in either
+ * direction is a real defect — laxer here loads what the server rejected;
+ * stricter here silently blanks media that is legitimately allowed.
+ */
+
+// The app's own scheme, read from the mention-link module rather than repeated:
+// a second copy of the scheme is a second thing to change, and what it hides is
+// media that silently blanks after a host reconfigures it.
+import { mentionScheme } from "../links";
+
+/**
+ * Same-origin path prefixes a src may start with.
+ *
+ * A PARAMETER rather than a baked-in constant: the list belongs to whoever
+ * serves the transcript, and hardcoding a copy here would create a second
+ * source of truth that drifts silently the day the server adds a route.
+ */
+export type SameOriginPrefixes = readonly string[];
+
+/**
+ * Is this `src` safe to put in front of a browser?
+ *
+ * Accepts `https:`, an allowlisted same-origin absolute path, the app's own
+ * mention scheme, and `data:image/`. Everything else is rejected — including
+ * `javascript:`, non-image `data:`, plain `http:`, `file:` and `vbscript:`.
+ */
+export function isAllowedSrc(src: string, sameOriginPrefixes: SameOriginPrefixes): boolean {
+  const trimmed = src.trim();
+  if (trimmed === "") return false;
+
+  const low = trimmed.toLowerCase();
+  if (low.startsWith("https://")) return true;
+  if (low.startsWith(`${mentionScheme()}://`)) return true;
+  // `data:image/` only. A bare `data:` allows text/html, which is script.
+  if (low.startsWith("data:image/")) return true;
+  if (trimmed.startsWith("/")) return isAllowedSameOrigin(trimmed, sameOriginPrefixes);
+
+  return false;
+}
+
+/**
+ * A content address: lowercase hex sha256. Mirrored rather than parameterised
+ * because it is a property of sha256, not a route a server is free to change.
+ */
+const CONTENT_ADDRESS = /^[0-9a-f]{64}$/;
+
+/**
+ * The attachment a src IS, or nothing.
+ *
+ * The server serves hosted bytes under a content address, so the last path
+ * segment IS the id — this reads a key the src already carries rather than
+ * minting one. The ROUTE is not spelled here: it arrives as a same-origin
+ * prefix for the same reason `isAllowedSrc` takes one, since baking a server's
+ * copy in would be a second source of truth that drifts the day it moves the
+ * route.
+ *
+ * A segment that is not a full hash belongs to some other route, and claiming
+ * it as an id would name a blob that does not exist.
+ */
+export function attachmentIdOf(
+  src: string | undefined,
+  sameOriginPrefixes: SameOriginPrefixes,
+): string | undefined {
+  if (src === undefined) return undefined;
+  const path = src.split(/[?#]/, 1)[0] ?? "";
+  const prefix = sameOriginPrefixes.find((candidate) => path.startsWith(candidate));
+  if (prefix === undefined) return undefined;
+  const id = path.slice(prefix.length);
+  return CONTENT_ADDRESS.test(id) ? id : undefined;
+}
+
+/**
+ * Gate an absolute-path src.
+ *
+ * Unlike a scheme, a path can be walked out of its prefix
+ * (`/api/admin/../../etc`) or hijacked into another origin, so a plain
+ * `startsWith` is NOT sufficient. Two escapes the server calls out by name:
+ * `//evil.com/x` is protocol-relative, and `/\evil.com` is treated as such by
+ * some browsers.
+ */
+function isAllowedSameOrigin(src: string, prefixes: SameOriginPrefixes): boolean {
+  if (src.startsWith("//") || src.startsWith("/\\")) return false;
+
+  // A query or fragment may legitimately follow; the gate applies to the path.
+  const cut = src.search(/[?#]/);
+  const path = cut >= 0 ? src.slice(0, cut) : src;
+
+  // REJECT rather than normalise. A src that needs cleaning is not one we
+  // minted, and normalising first is how a traversal becomes an allowed path.
+  if (path !== cleanPath(path)) return false;
+
+  return prefixes.some((prefix) => path.startsWith(prefix));
+}
+
+/**
+ * The subset of Go's `path.Clean` this gate needs.
+ *
+ * Only used to answer "is this path already clean?", never to sanitise a path
+ * for use — a caller that cleans and then trusts the result has re-introduced
+ * exactly the bug the reject-don't-normalise rule prevents.
+ */
+export function cleanPath(path: string): string {
+  if (path === "") return ".";
+
+  const rooted = path.startsWith("/");
+  const out: string[] = [];
+
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      // At the root, `..` has nowhere to go and Go's Clean drops it.
+      if (out.length > 0 && out[out.length - 1] !== "..") out.pop();
+      else if (!rooted) out.push("..");
+      continue;
+    }
+    out.push(segment);
+  }
+
+  const joined = out.join("/");
+  if (rooted) return `/${joined}`;
+  return joined === "" ? "." : joined;
+}

package/src/core/media/block.ts

@@ -0,0 +1,254 @@
+import { attachmentIdOf, isAllowedSrc, type SameOriginPrefixes } from "./allowed-src";
+import { isMediaKind, SRC_KINDS, type MediaKind } from "./kinds";
+
+/**
+ * Reading a media block, and gating it.
+ *
+ * VALIDATION HAPPENS ONCE, HERE — not in each renderer. That split is taken
+ * from the archived chat, whose LinkBlock says outright that the payload "is
+ * validated centrally at the registry dispatch point before this renderer runs,
+ * so we can trust it here". Per-renderer checking is how one of eleven quietly
+ * ends up missing its own.
+ *
+ * A rejected URL does not throw and does not render a broken element: the field
+ * is dropped, so a block with an unsafe cover still plays its audio, and a block
+ * with an unsafe `src` renders nothing at all.
+ */
+
+export interface MediaBlock {
+  readonly kind: MediaKind;
+  readonly src?: string;
+  readonly cover?: string;
+  readonly title?: string;
+  readonly alt?: string;
+  /** Textual kinds (json/code/markdown/text/mermaid) carry content, not a src. */
+  readonly content?: string;
+  /** `code` only. */
+  readonly language?: string;
+  readonly items?: readonly MediaGalleryItem[];
+  /** `link` only — the destination and its pre-resolved unfurl. */
+  readonly url?: string;
+  readonly link?: MediaLinkPreview;
+  readonly aspectRatio?: number;
+  /** Present only when a tool produced the picture rather than found it. */
+  readonly generation?: MediaGeneration;
+  /**
+   * The server-hosted blob these bytes ARE, when the src names one.
+   *
+   * Derived from the src, never authored: the server serves hosted bytes at
+   * `/api/admin/attachments/<sha256>` and that sha256 IS the attachment id, so
+   * the block already states its own key. Absent for a picture hosted
+   * elsewhere — those bytes never reached this server and nothing here has
+   * measured them.
+   *
+   * An IDENTITY, not a copy of the facts. The turn's file parts already carry
+   * width, size and duration; duplicating them onto the block would give one
+   * fact two homes and let them disagree.
+   */
+  readonly attachmentId?: string;
+}
+
+/**
+ * How a picture came to exist: the request, and the model that answered it.
+ *
+ * `size` is a preference the provider may ignore and `quality` is an intent, so
+ * a card must present both as the request they are. `model` is the one field
+ * describing the RESULT — the router reports which model its ladder reached,
+ * which the intent alone cannot say. Absent when the router did not report one.
+ */
+export interface MediaGeneration {
+  readonly prompt: string;
+  readonly size?: string;
+  readonly quality?: string;
+  readonly model?: string;
+  /**
+   * Where these bytes also live on the open internet. Carried here because the
+   * server rewrites `src` when it hosts the bytes, so a card reading one finds
+   * an internal path. Absent when the producer hosted nothing.
+   */
+  readonly publicUrl?: string;
+}
+
+export interface MediaGalleryItem {
+  readonly src: string;
+  readonly thumbnail?: string;
+  readonly alt?: string;
+}
+
+export interface MediaLinkPreview {
+  readonly title?: string;
+  readonly description?: string;
+  readonly image?: string;
+  readonly favicon?: string;
+  readonly siteName?: string;
+}
+
+const str = (value: unknown): string | undefined =>
+  typeof value === "string" && value !== "" ? value : undefined;
+
+/**
+ * Read and GATE a media block.
+ *
+ * Returns null when the block cannot be rendered honestly — an unknown kind, a
+ * src-bearing kind whose src is rejected, or a textual kind with no content.
+ */
+/**
+ * The wire field a textual kind carries its payload in.
+ *
+ * The server does NOT send one `content` field. Each textual kind names its own
+ * — a mermaid block sends `chart`, a markdown block `markdown`, a code block
+ * `code` — while this model keeps a single `content`, because a renderer that
+ * has already switched on `kind` gains nothing from a second name for "the
+ * text". Translating at the boundary is what keeps that true.
+ *
+ * Reading only `content` is what made every one of these blocks vanish: the
+ * field was always undefined, so the check below rejected the block and no
+ * renderer ever ran. Silent, because a dropped block looks exactly like a block
+ * the agent never sent.
+ */
+const CONTENT_FIELD: Partial<Record<MediaKind, string>> = {
+  code: "code",
+  markdown: "markdown",
+  text: "text",
+  mermaid: "chart",
+};
+
+/**
+ * A textual kind's payload as a string, or undefined.
+ *
+ * `json` is the one kind whose payload is not text on the wire — the server
+ * sends the parsed VALUE. It is serialised here so the block model can keep one
+ * string field, and because a renderer showing JSON has to print it anyway.
+ */
+function readContent(row: Record<string, unknown>, kind: MediaKind): string | undefined {
+  if (kind === "json") {
+    if (row.data === undefined) return undefined;
+    try {
+      return JSON.stringify(row.data, null, 2);
+    } catch {
+      // A cycle cannot survive the wire, so this is unreachable through the
+      // server — it guards a hand-built block in a story or a test.
+      return undefined;
+    }
+  }
+
+  const field = CONTENT_FIELD[kind] ?? "content";
+  const value = row[field];
+  // Not `str()`: that treats "" as absent, and an empty code block is a
+  // legitimate thing for an agent to show.
+  if (typeof value === "string") return value;
+  // The generic name is accepted as a fallback for every kind, so a hand-built
+  // block and a story keep working against the model's own vocabulary.
+  return typeof row.content === "string" ? row.content : undefined;
+}
+
+export function readMediaBlock(
+  data: unknown,
+  prefixes: SameOriginPrefixes,
+): MediaBlock | null {
+  if (typeof data !== "object" || data === null) return null;
+  const row = data as Record<string, unknown>;
+  if (!isMediaKind(row.kind)) return null;
+
+  const kind = row.kind;
+  const safe = (value: unknown): string | undefined => {
+    const url = str(value);
+    if (url === undefined) return undefined;
+    return isAllowedSrc(url, prefixes) ? url : undefined;
+  };
+
+  const block: MediaBlock = {
+    kind,
+    src: safe(row.src),
+    // Secondary URLs are gated exactly like the primary one. They are the ones
+    // a renderer forgets, and each is an outbound request made on behalf of a
+    // model-authored block.
+    cover: safe(row.cover),
+    title: str(row.title),
+    alt: str(row.alt),
+    content: readContent(row, kind),
+    language: str(row.language),
+    items: readItems(row.items, safe),
+    url: safe(row.url),
+    link: readLink(row.link, safe),
+    aspectRatio: typeof row.aspectRatio === "number" && row.aspectRatio > 0
+      ? row.aspectRatio
+      : undefined,
+    generation: readGeneration(row.generation, safe),
+    attachmentId: attachmentIdOf(safe(row.src), prefixes),
+  };
+
+  // A src-bearing kind with no surviving src has nothing to show. Rendering an
+  // empty frame would claim media exists that the gate just refused.
+  if (SRC_KINDS.has(kind)) {
+    const hasSource =
+      block.src !== undefined ||
+      block.url !== undefined ||
+      (block.items?.length ?? 0) > 0;
+    if (!hasSource) return null;
+  } else if (kind !== "map" && block.content === undefined) {
+    return null;
+  }
+
+  return block;
+}
+
+function readItems(
+  raw: unknown,
+  safe: (value: unknown) => string | undefined,
+): readonly MediaGalleryItem[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const items: MediaGalleryItem[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const row = entry as Record<string, unknown>;
+    const src = safe(row.src);
+    // An item whose src was rejected is dropped rather than shown as a gap:
+    // the gallery stays honest about what it can actually display.
+    if (src === undefined) continue;
+    items.push({ src, thumbnail: safe(row.thumbnail), alt: str(row.alt) });
+  }
+  return items.length > 0 ? items : undefined;
+}
+
+/**
+ * A generation is its prompt. Without one there is nothing a card could show,
+ * so the field is dropped rather than kept as an empty shell a renderer would
+ * then have to decide how to draw.
+ */
+function readGeneration(
+  raw: unknown,
+  safe: (value: unknown) => string | undefined,
+): MediaGeneration | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const row = raw as Record<string, unknown>;
+  const prompt = str(row.prompt);
+  if (prompt === undefined) return undefined;
+  return {
+    prompt,
+    size: str(row.size),
+    quality: str(row.quality),
+    model: str(row.model),
+    // Gated like every other src on this block: a provenance field is written
+    // by a tool, so an unvalidated one would be an address a model chose.
+    publicUrl: safe(row.publicUrl),
+  };
+}
+
+function readLink(
+  raw: unknown,
+  safe: (value: unknown) => string | undefined,
+): MediaLinkPreview | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const row = raw as Record<string, unknown>;
+  const preview: MediaLinkPreview = {
+    title: str(row.title),
+    description: str(row.description),
+    image: safe(row.image),
+    favicon: safe(row.favicon),
+    siteName: str(row.siteName),
+  };
+  // The server's own note: a preview with no title/description/image still
+  // renders as a bare URL card, so an all-empty preview is not an error.
+  return preview;
+}

package/src/core/media/index.ts

@@ -0,0 +1,22 @@
+// Media blocks: the eleven-kind vocabulary and the `src` allowlist.
+//
+// Pure TypeScript, no React — the allowlist is a SECURITY BOUNDARY and belongs
+// where it can be tested exhaustively without a renderer. It is a deliberate
+// mirror of the server's media vocabulary and allowlist, not a shared helper:
+// the server gates what a tool may emit, this gates what a browser will load,
+// and a stored transcript reaches the DOM with no live server process
+// re-checking it.
+
+export { attachmentIdOf, isAllowedSrc, cleanPath } from "./allowed-src";
+export type { SameOriginPrefixes } from "./allowed-src";
+
+export { MEDIA_KINDS, isMediaKind, TEXTUAL_KINDS, SRC_KINDS, URL_FIELDS } from "./kinds";
+export type { MediaKind } from "./kinds";
+
+export { readMediaBlock } from "./block";
+export type {
+  MediaBlock,
+  MediaGalleryItem,
+  MediaGeneration,
+  MediaLinkPreview,
+} from "./block";

package/src/core/media/kinds.ts

@@ -0,0 +1,85 @@
+/**
+ * The media block vocabulary — one event type (8), eleven kinds.
+ *
+ * SOURCE OF TRUTH: the server's `Kind` vocabulary and its supported-kinds set.
+ * Mirrored here so the discriminant lives in ONE place on this
+ * side too, instead of being re-spelled inside each renderer.
+ *
+ * This is why media is a REGISTRY rather than a widget: eleven kinds behind one
+ * event type is exactly the shape the O(1) rule exists for. A twelfth kind adds
+ * a registry entry and a renderer — never a prop on `<Chat>`.
+ */
+
+export const MEDIA_KINDS = [
+  "image",
+  "audio",
+  "video",
+  "map",
+  "json",
+  "code",
+  "markdown",
+  "text",
+  "mermaid",
+  "gallery",
+  "link",
+] as const;
+
+export type MediaKind = (typeof MEDIA_KINDS)[number];
+
+const SUPPORTED = new Set<string>(MEDIA_KINDS);
+
+/**
+ * Is this a kind this build knows how to render?
+ *
+ * An unknown kind is not an error: the server's vocabulary grows, and a
+ * transcript stored by a newer agent may reach an older client. The caller
+ * renders nothing rather than guessing — the same degrade the server applies
+ * ("an unsupported kind is rejected by Validate").
+ */
+export function isMediaKind(value: unknown): value is MediaKind {
+  return typeof value === "string" && SUPPORTED.has(value);
+}
+
+/**
+ * Kinds whose payload is TEXT, not a `src`.
+ *
+ * They are routed to the content renderer instead of a media element, which is
+ * the seam where `widgets/` and `content/` meet. Getting this list wrong grows a
+ * second markdown path — the exact duplication the registry exists to prevent.
+ */
+export const TEXTUAL_KINDS = new Set<MediaKind>([
+  "json",
+  "code",
+  "markdown",
+  "text",
+  "mermaid",
+]);
+
+/** Kinds that load a URL, and therefore MUST pass the allowlist. */
+export const SRC_KINDS = new Set<MediaKind>(["image", "audio", "video", "gallery", "link"]);
+
+/**
+ * Every URL-bearing field per kind — NOT just `src`.
+ *
+ * Checked against the server's own validation, and that is the reason to write
+ * it out: the secondary URLs are the ones a renderer forgets. The server gates
+ * `cover` on audio/video, `thumbnail` on each gallery item, and BOTH
+ * `image` and `favicon` inside a link preview — every one of them is an
+ * outbound request the browser makes on behalf of a model-authored block.
+ *
+ * A renderer that validates `src` and then drops an unvalidated `favicon` into
+ * an `<img>` has left the exfil vector open while looking careful.
+ */
+export const URL_FIELDS: Readonly<Record<MediaKind, readonly string[]>> = {
+  image: ["src"],
+  audio: ["src", "cover"],
+  video: ["src", "cover"],
+  gallery: ["items[].src", "items[].thumbnail"],
+  link: ["url", "link.image", "link.favicon"],
+  map: [],
+  json: [],
+  code: [],
+  markdown: [],
+  text: [],
+  mermaid: [],
+};