lavish-axi 0.1.49 → 0.1.51

package/README.md

@@ -203,6 +203,12 @@ pnpm link
   Agent-initiated ends keep reopening normally, same as before.
   `lavish-axi poll`'s `ended` response and the `feedback` response for the final batch before an end both carry `next_step` guidance telling the agent to stop polling and deliver remaining updates in chat instead of reopening.
 - **Precise targets** - Text annotations include selected text plus range anchors, so agents are not limited to whole-element selectors.
+- **Image attachments** - Attach reference images (PNG, JPEG, WebP) to an annotation by pasting, drag-dropping, or using the annotation card's **Attach image** picker; each shows a thumbnail chip with upload, remove, retry, and error states.
+  Images are stored under the state dir and the queued prompt carries a server-generated absolute `path` and content-hash `id` (plus mime and dimensions) - never the raw bytes - so `lavish-axi poll` hands the agent a local file path to open.
+  Limits are `LAVISH_AXI_MAX_ATTACHMENT_BYTES` (default 10 MiB per image), `LAVISH_AXI_MAX_ATTACHMENTS_PER_PROMPT` (default 4), and `LAVISH_AXI_MAX_PROMPT_ATTACHMENT_BYTES` (default 25 MiB per annotation); if any image is missing or any annotation breaches a count or byte cap, the entire send batch is rejected, the queue is preserved, and the reason is surfaced in the composer rather than silently dropping images.
+  As a browser-side abuse guard, each chrome page allows 30 upload attempts per rolling minute, 4 uploads in flight at once, and 256 MiB of attempted image bytes over its lifetime; rejected uploads stay visible on their annotation card for retry or removal.
+  Attachments are cleaned up by `LAVISH_AXI_ATTACHMENT_TTL_MS` (default 7 days; `0`/`off` disables) but only once no pending prompt still references them; `LAVISH_AXI_MAX_ATTACHMENT_DISK_MB` (default 512 MiB; `0`/`off` disables) caps total attachment disk.
+  The cap is enforced when an image is uploaded, not just periodically: the upload first reclaims unreferenced files (oldest first, and never one added within the last hour), and if it still would not fit, that upload is refused with a storage-full error on its chip instead of discarding an image an annotation is about to send.
 - **Mermaid diagrams** - In the Lavish browser, every rendered Mermaid diagram in a `.mermaid` container becomes an embedded editable Excalidraw whiteboard.
   Click a diagram to unlock editing, and use its Fullscreen action to edit it over the whole viewport.
   Whiteboard scenes autosave locally.
@@ -217,7 +223,7 @@ pnpm link
 - **Diagnostic viewports** - `LAVISH_AXI_DIAGNOSTIC_VIEWPORTS` sets which viewport classes the layout-issue inbox tracks (`mobile`, `compact`, `desktop`; comma-separated, default all). Warnings whose class leaves the set are marked obsolete with an explicit reason instead of silently reading as fixed.
 - **Server port** - Set `LAVISH_AXI_PORT` to choose the server port; it defaults to `4387`.
 - **Network binding** - The server binds to loopback (`127.0.0.1`) by default. Set `LAVISH_AXI_HOST` to bind elsewhere; a wildcard (`0.0.0.0` or `::`) binds every interface. Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. Set `LAVISH_AXI_LINK_HOST` to control the hostname written into generated session links (defaults to the bind address, or loopback when bound to a wildcard).
-- **Allowed hosts** - To defend against DNS rebinding, the server rejects (`403`) any request whose `Host` header is missing or not one it answers to: the loopback names (`127.0.0.1`, `::1`, `localhost`) plus the configured bind and link host. If you reach the server under another name - a wildcard bind accessed by LAN IP, a reverse-proxy hostname, or an extra interface - list those names in `LAVISH_AXI_ALLOWED_HOSTS` (whitespace-separated) to allow them. Behind a reverse proxy, the forwarded `X-Forwarded-Host` is validated against the same list, so add your public hostname there and have the proxy send it. Set `LAVISH_AXI_ALLOWED_HOSTS` to `*` to disable the check entirely (only when the server sits behind your own authentication or proxy).
+- **Allowed hosts** - To defend against DNS rebinding, the server rejects (`403`) any request whose `Host` header is missing or not one it answers to: the loopback names (`127.0.0.1`, `::1`, `localhost`) plus the configured bind and link host. If you reach the server under another name - a wildcard bind accessed by LAN IP, a reverse-proxy hostname, or an extra interface - list those names in `LAVISH_AXI_ALLOWED_HOSTS` (whitespace-separated) to allow them. Behind a reverse proxy, the forwarded `X-Forwarded-Host` is validated against the same list, so add your public hostname there and have the proxy send it together with `X-Forwarded-Proto`. Set `LAVISH_AXI_ALLOWED_HOSTS` to `*` to disable the check entirely (only when the server sits behind your own authentication or proxy).
 - **Browser opening** - Set `LAVISH_AXI_NO_OPEN=1`, equivalent to `--no-open`, to create or resume a session without launching a browser window.
 
 ## CLI Reference

package/dist/chrome-client.js

@@ -11,6 +11,59 @@ const warningSelectionStorageKey = "lavish-axi:warning-selection:" + key;
 const internalQueueKeyField = "_lavishQueueKey";
 const initialChat = Array.isArray(sessionData.initialChat) ? sessionData.initialChat : [];
 const MODE_TOGGLE_HOTKEY_KEY = String(sessionData.modeToggleHotkeyKey || "").toLowerCase();
+const attachmentMaxBytes = Number(sessionData.attachmentMaxBytes) || 0;
+
+// The chrome is the only path from the sandboxed (opaque-origin) artifact iframe to
+// the loopback server, so it is the sole place a same-origin confused-deputy can be
+// mediated: the frame's postMessage source check proves a message came from the
+// artifact frame but NOT that a user gesture (paste/drop/pick) drove it, so hostile
+// artifact script could otherwise drive unbounded uploads. Bound both the rate and
+// the cumulative bytes per chrome session here; the server keeps a bounded disk
+// quota as the durable backstop.
+const UPLOAD_RATE_WINDOW_MS = 60_000;
+const UPLOAD_RATE_MAX = 30;
+const UPLOAD_SESSION_BYTE_QUOTA = 256 * 1024 * 1024; // 256 MiB per chrome session
+// The rate and cumulative-byte guards bound uploads over time, but not how many run
+// AT ONCE: each accepted message starts fetch() immediately, so a hostile artifact
+// could post ~30 large bodies in one tick and hold hundreds of MiB of structured
+// clones + server body buffers concurrently before the cumulative quota trips (D8).
+// Cap the number in flight; the over-cap ones are refused with a retry hint (like the
+// rate guard) and a freed slot admits the next.
+const UPLOAD_MAX_IN_FLIGHT = 4;
+const uploadTimestamps = [];
+let uploadedBytesTotal = 0;
+let uploadsInFlight = 0;
+
+function formatByteLimit(bytes) {
+  if (bytes >= 1024 * 1024) return Math.round(bytes / (1024 * 1024)) + " MB";
+  if (bytes >= 1024) return Math.round(bytes / 1024) + " KB";
+  return bytes + " bytes";
+}
+
+// Turn the server's atomic-reject detail (C4) into one human line naming the cap
+// that was hit, so the user knows what to fix. Nothing was delivered - the queue is
+// preserved - so the wording is about correcting, not about a partial send.
+function describeAttachmentRejection(rejected, caps) {
+  const reasons = new Set(rejected.map((ref) => ref && ref.reason));
+  const parts = [];
+  if (reasons.has("prompt-bytes-exceeded") && caps && caps.maxPromptBytes) {
+    parts.push("images exceed the " + formatByteLimit(caps.maxPromptBytes) + " per-annotation limit");
+  }
+  if (reasons.has("too-many") && caps && caps.maxPerPrompt) {
+    parts.push("more than " + caps.maxPerPrompt + " images on one annotation");
+  }
+  if (reasons.has("too-many-in-request")) {
+    parts.push("too many images queued at once");
+  }
+  if (reasons.has("malformed")) {
+    parts.push("an image attachment was malformed");
+  }
+  if (reasons.has("not-found")) {
+    parts.push("an image is no longer available");
+  }
+  const detail = parts.length ? parts.join("; ") : "some attachments could not be delivered";
+  return "Not sent — " + detail + ". Remove or fix the image, then send again.";
+}
 
 function isModeToggleHotkeyEvent(event) {
   if (event.shiftKey || event.altKey) return false;
@@ -164,10 +217,49 @@ function saveJsonState(storageKey, value) {
   }
 }
 
+// A queued prompt is authored by the untrusted artifact iframe, so its attachment
+// refs are validated at the single boundary every prompt crosses before it is
+// persisted or rendered. Anything that is not a well-formed `{id}` object is
+// dropped: the queue is written to sessionStorage BEFORE it renders, so one bad
+// entry would throw out of render(), stay on disk, and throw again on every
+// reload - wedging the tab permanently instead of failing once. The card's own
+// flow only ever produces `{id, name}`, so a malformed entry is fabricated and
+// there is no user image to preserve. The server re-validates independently.
+// Each surviving ref is PROJECTED onto a fresh primitives-only object rather than
+// kept by reference: postMessage delivers a structured clone, which faithfully
+// preserves BigInt values and cycles that `JSON.stringify` then refuses. Passing
+// the artifact's own object through would carry that junk into sessionStorage and
+// the POST body, where the throw makes the queue unsendable - the same wedge as a
+// poisoned entry, just one step later.
+function sanitizeAttachmentRefs(value) {
+  if (!Array.isArray(value)) return [];
+  const refs = [];
+  for (const ref of value) {
+    if (!ref || typeof ref !== "object" || Array.isArray(ref)) continue;
+    if (typeof ref.id !== "string" || !ref.id) continue;
+    const projected = { id: ref.id };
+    if (typeof ref.name === "string" && ref.name) projected.name = ref.name;
+    refs.push(projected);
+  }
+  return refs;
+}
+
+function sanitizeQueuedPrompt(prompt) {
+  if (!prompt || typeof prompt !== "object") return null;
+  if (!("attachments" in prompt)) return prompt;
+  const clean = { ...prompt };
+  const refs = sanitizeAttachmentRefs(clean.attachments);
+  if (refs.length) clean.attachments = refs;
+  else delete clean.attachments;
+  return clean;
+}
+
 function loadQueuedPrompts() {
   try {
     const parsed = JSON.parse(sessionStorage.getItem(queueStorageKey) || "[]");
-    return Array.isArray(parsed) ? parsed.filter((prompt) => prompt && typeof prompt === "object") : [];
+    // Also sanitize on restore: a tab poisoned before this guard existed still has
+    // the bad prompt on disk and would otherwise stay wedged after an upgrade.
+    return Array.isArray(parsed) ? parsed.map(sanitizeQueuedPrompt).filter(Boolean) : [];
   } catch {
     return [];
   }
@@ -190,8 +282,10 @@ function render() {
     .map(
       (prompt, index) =>
         '<div class="pill-wrap"><div class="pill"><span class="pill-preview">' +
-        escapeHtml(prompt.prompt) +
-        '</span><button class="pill-close" type="button" aria-label="Remove queued prompt" data-index="' +
+        escapeHtml(prompt.prompt || (attachmentCount(prompt) ? "Image annotation" : "")) +
+        "</span>" +
+        pillAttachmentsHtml(prompt) +
+        '<button class="pill-close" type="button" aria-label="Remove queued prompt" data-index="' +
         index +
         '"><svg width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden="true" focusable="false"><path d="M1 1L9 9M9 1L1 9" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button></div><div class="pill-tooltip">' +
         (prompt.selector
@@ -219,12 +313,65 @@ function updateSendState() {
   if (warningsQueueButton) updateWarningSelectionState();
 }
 
-function showSendHint() {
+function attachmentCount(prompt) {
+  return Array.isArray(prompt.attachments) ? prompt.attachments.length : 0;
+}
+
+// How many thumbnails the compact pill shows before the rest collapse into a badge.
+const PILL_THUMBNAIL_LIMIT = 4;
+
+// Thumbnails for a queued prompt's images, served straight from the same-origin
+// attachment endpoint (the ids are already server-vetted at upload time). The pill
+// has room for only a few, but the per-prompt cap is configurable
+// (LAVISH_AXI_MAX_ATTACHMENTS_PER_PROMPT), so a prompt can legitimately carry more
+// than fit: the remainder collapses into a +N badge rather than being dropped from
+// the preview, which would make the queue look like it lost the extra images (W-A).
+function pillAttachmentsHtml(prompt) {
+  const count = attachmentCount(prompt);
+  if (!count) return "";
+  const hidden = count - PILL_THUMBNAIL_LIMIT;
+  return (
+    '<span class="pill-attachments">' +
+    prompt.attachments
+      .slice(0, PILL_THUMBNAIL_LIMIT)
+      .map((attachment) => {
+        const alt = escapeHtml(attachment.name || "image");
+        return (
+          '<img class="pill-attachment" src="/api/' +
+          encodeURIComponent(key) +
+          "/attachments/" +
+          encodeURIComponent(attachment.id) +
+          '" alt="' +
+          alt +
+          '" title="' +
+          alt +
+          '">'
+        );
+      })
+      .join("") +
+    (hidden > 0
+      ? '<span class="pill-attachment-more" title="' +
+        hidden +
+        " more image" +
+        (hidden === 1 ? "" : "s") +
+        '">+' +
+        hidden +
+        "</span>"
+      : "") +
+    "</span>"
+  );
+}
+
+const DEFAULT_SEND_HINT = "Write a message or annotate an element first.";
+
+function showSendHint(message = DEFAULT_SEND_HINT, holdMs = 2600) {
+  sendHint.textContent = message;
   sendHint.hidden = false;
   clearTimeout(sendHintTimer);
   sendHintTimer = setTimeout(() => {
     sendHint.hidden = true;
-  }, 2600);
+    sendHint.textContent = DEFAULT_SEND_HINT;
+  }, holdMs);
   chatInput.focus();
 }
 
@@ -354,8 +501,9 @@ function promptQueueKey(prompt) {
   return prompt && typeof prompt[internalQueueKeyField] === "string" ? prompt[internalQueueKeyField].trim() : "";
 }
 
-function enqueuePrompt(prompt) {
-  if (!prompt || typeof prompt !== "object") return;
+function enqueuePrompt(rawPrompt) {
+  const prompt = sanitizeQueuedPrompt(rawPrompt);
+  if (!prompt) return;
 
   const queueKey = promptQueueKey(prompt);
   if (queueKey) {
@@ -457,6 +605,15 @@ async function submitQueuedOnce() {
       endAfterSubmit = false;
       return false;
     }
+    // C4: the server persisted nothing (atomic reject) - the queue below is left
+    // intact because the splice only runs on success. Surface exactly what failed
+    // so the user can fix the offending attachment(s) rather than losing them.
+    if (response.status === 400) {
+      const detail = await response.json().catch(() => ({}));
+      if (Array.isArray(detail.rejected) && detail.rejected.length) {
+        showSendHint(describeAttachmentRejection(detail.rejected, detail.caps), 6000);
+      }
+    }
     throw new Error("failed to submit queued prompts");
   }
   for (const prompt of prompts) {
@@ -1293,7 +1450,8 @@ function showWhiteboardOverlay(index) {
   postToFrame({ type: "lavish:suspendWhiteboard", diagramIndex: index });
   // A fresh document per open: the frame boots, posts ready, and receives its
   // init - no stale editor state can leak between opens.
-  whiteboardFrame.src = "/whiteboard-frame?diagramIndex=" + encodeURIComponent(String(index));
+  whiteboardFrame.src =
+    "/whiteboard-frame?diagramIndex=" + encodeURIComponent(String(index)) + "&key=" + encodeURIComponent(key);
 }
 
 function finishWhiteboardClose(index) {
@@ -1573,10 +1731,30 @@ function handleAuthenticatedWhiteboardMessage(index, message, mode) {
   if (message.type === "lavish-whiteboard:flushComplete") finishWhiteboardFlush(index, message, mode);
 }
 
+// Inline whiteboard frames are created by the SDK inside the artifact document,
+// so a genuine one is always a direct child of the *current* artifact window.
+// Descent - not the channel token - is what proves the sender is ours: the
+// frame page is framable by any origin, so a token is not a secret an attacker
+// cannot obtain. Without this, any window that could postMessage to this chrome
+// (a page that framed it, or one holding a window.open handle) could open a
+// channel and queue a fabricated prompt. Mirrors the artifact-message handler's
+// `event.source !== frame.contentWindow` guard.
+function isArtifactChildWindow(source) {
+  if (!source) return false;
+  try {
+    // Reading `parent` on a cross-origin WindowProxy is permitted; the frame's
+    // sandbox makes everything else about it opaque.
+    return source.parent === frame.contentWindow;
+  } catch {
+    return false;
+  }
+}
+
 function handleInlineWhiteboardMessage(event, message) {
   if (ended) return;
+  if (!isArtifactChildWindow(event.source)) return;
   const index = validWhiteboardIndex(message.diagramIndex);
-  if (index === null || !event.source) return;
+  if (index === null) return;
   if (message.type === "lavish-whiteboard:ready") {
     if (inlineWhiteboardChannels.has(index)) return;
     const channelId = String(message.channelToken || "");
@@ -1736,11 +1914,139 @@ window.addEventListener("message", (event) => {
       messageToken,
     ).catch(() => {});
   }
+  if (msg.type === "lavish:uploadAttachment") uploadAttachment(msg);
+  // There is deliberately no attachment-delete message. See removeAttachment's
+  // removal note below: the iframe cannot be trusted to decide a delete, and the
+  // chrome cannot see every live reference, so reclamation is the sweeper's job.
   if (msg.type === "lavish:sendQueuedPrompts") sendQueued();
   if (msg.type === "lavish:endSession") endSession();
   if (msg.type === "lavish:toggleAnnotationMode") toggleAnnotationMode();
 });
 
+// The sandboxed artifact iframe can't reach the loopback server (opaque origin),
+// so it hands captured image bytes here and the chrome performs the same-origin
+// upload, then reports the server-vetted id back to the card.
+async function uploadAttachment(message) {
+  const localId = String(message.localId || "");
+  if (!localId) return;
+  // Echoed verbatim on every result so the artifact can tell a reply to ITS upload
+  // from one still in flight for a previous document (E1). The chrome never
+  // interprets it; it only round-trips it.
+  const nonce = message.nonce;
+  const bytes = message.bytes;
+  let size;
+  if (ArrayBuffer.isView(bytes)) {
+    size = bytes.byteLength;
+  } else {
+    try {
+      const byteLengthGetter = Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, "byteLength")?.get;
+      size = byteLengthGetter ? byteLengthGetter.call(bytes) : NaN;
+    } catch {
+      size = NaN;
+    }
+  }
+  if (!Number.isFinite(size) || size < 0) {
+    postToFrame({
+      type: "lavish:attachmentResult",
+      nonce,
+      localId,
+      ok: false,
+      error: "invalid upload payload",
+    });
+    return;
+  }
+  // Reject over-cap images before they hit the network: an over-cap upload aborts
+  // mid-stream, and the browser can hang or reset instead of surfacing the 413, so
+  // the chip would never leave "uploading". Catching it here guarantees the card
+  // reaches its error+retry state. The server still enforces the cap authoritatively.
+  if (attachmentMaxBytes > 0 && size > attachmentMaxBytes) {
+    postToFrame({
+      type: "lavish:attachmentResult",
+      nonce,
+      localId,
+      ok: false,
+      error: "Image is larger than the " + formatByteLimit(attachmentMaxBytes) + " limit",
+    });
+    return;
+  }
+  // Confused-deputy guard: rate + cumulative-byte ceiling before touching the network.
+  const now = Date.now();
+  while (uploadTimestamps.length && now - uploadTimestamps[0] > UPLOAD_RATE_WINDOW_MS) uploadTimestamps.shift();
+  if (uploadTimestamps.length >= UPLOAD_RATE_MAX) {
+    postToFrame({
+      type: "lavish:attachmentResult",
+      nonce,
+      localId,
+      ok: false,
+      error: "Too many uploads. Wait a moment and retry.",
+    });
+    return;
+  }
+  if (uploadedBytesTotal + size > UPLOAD_SESSION_BYTE_QUOTA) {
+    postToFrame({
+      type: "lavish:attachmentResult",
+      nonce,
+      localId,
+      ok: false,
+      error: "Upload limit reached for this session (" + formatByteLimit(UPLOAD_SESSION_BYTE_QUOTA) + ").",
+    });
+    return;
+  }
+  // In-flight ceiling: refuse rather than pile another large body onto the network
+  // while the bound is full. The card keeps its retry affordance, and a settled
+  // upload (below) frees a slot for the next.
+  if (uploadsInFlight >= UPLOAD_MAX_IN_FLIGHT) {
+    postToFrame({
+      type: "lavish:attachmentResult",
+      nonce,
+      localId,
+      ok: false,
+      error: "Too many uploads in flight. Wait a moment and retry.",
+    });
+    return;
+  }
+  uploadTimestamps.push(now);
+  uploadedBytesTotal += size;
+  uploadsInFlight += 1;
+  try {
+    const response = await fetch("/api/" + key + "/attachments", {
+      method: "POST",
+      headers: { "content-type": String(message.mime || "application/octet-stream") },
+      body: bytes,
+    });
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) throw new Error(data.error || "Upload failed");
+    postToFrame({
+      type: "lavish:attachmentResult",
+      nonce,
+      localId,
+      ok: true,
+      id: (data.attachment && data.attachment.id) || "",
+    });
+  } catch (error) {
+    postToFrame({
+      type: "lavish:attachmentResult",
+      nonce,
+      localId,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  } finally {
+    uploadsInFlight -= 1;
+  }
+}
+
+// There is intentionally no eager attachment delete here. Removing a chip used to
+// ask the chrome to DELETE the stored file once no queued prompt referenced it,
+// but that check is not authoritative: attachments are content-addressed, so two
+// tabs (or two cards) can hold the SAME id, and a chip that is ready but not yet
+// queued in another tab is invisible from here. The delete was also driven by the
+// untrusted iframe, making the chrome a confused deputy - a malicious artifact
+// could destroy bytes a live card still needed, which then failed as `not-found`
+// on send. Unreferenced files are reclaimed by the server's reference-aware TTL
+// sweeper and the disk-cap backstop, which see every session's pending prompts
+// at once. Deleting late is cheap; deleting bytes someone still needs is not.
+
 loadFrame();
 
 function toggleAnnotationMode() {

package/dist/chrome.css

@@ -1058,6 +1058,36 @@ body.lavish {
   white-space: nowrap;
   text-overflow: ellipsis;
 }
+.pill-attachments {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 0 auto;
+}
+.pill-attachment {
+  width: 22px;
+  height: 22px;
+  border-radius: 5px;
+  object-fit: cover;
+  background: var(--border);
+  border: 1px solid var(--border-strong);
+}
+.pill-attachment-more {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 22px;
+  height: 22px;
+  padding: 0 4px;
+  border-radius: 5px;
+  background: var(--border);
+  border: 1px solid var(--border-strong);
+  color: var(--fg-muted);
+  font-size: 10px;
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
 .pill-close {
   display: flex;
   align-items: center;