Test what an attachment's name resolves to, beside folderOf

The resolution moves to sp.ts as canvasFile, with a test for a board, a
video, a shape record, an app canvas, and names that try to leave the
folder. Drop the em dashes REVIEW.md rules out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: Jing-yilin

canvas/server/agent.ts

@@ -17,7 +17,7 @@ import path from "node:path";
 import { CANVASES } from "./boards.ts";
 import { command, stop } from "./command.ts";
 import { AGENT_SKILLS, installSkills } from "./skills.ts";
-import { folderOf, sameOrigin } from "./sp.ts";
+import { canvasFile, folderOf, sameOrigin } from "./sp.ts";
 import { SAFE_NAME } from "../src/layoutEdit.ts";
 import {
   attach,
@@ -511,22 +511,21 @@ export function createAgentServer(options: {
               data: string;
               reference?: { project?: string; community?: string };
             }) => {
-              // Anything but a picture — a board, a video, a note — keeps its picture for the
-              // panel, and the agent is pointed at its file, `<slug>/<path>` in the canvases of
-              // the project it was attached from, which need not be the one it is sent from. A
-              // community project's is not on this machine, so it keeps the name `sp fetch`
-              // finds it by.
-              const [slug, ...rest] = i.name.split("/");
+              // Anything but a picture (a board, a video, a note) keeps its picture for the
+              // panel, and the agent is pointed at its file, in the canvases of the project it
+              // was attached from, which need not be the one it is sent from. A community
+              // project's is not on this machine, so it keeps the name `sp fetch` finds it by.
               const ref = i.reference;
               const from = ref?.project && projects().get(ref.project);
-              const local =
+              const file =
                 ref?.community === undefined &&
-                (ref?.project === undefined || from) &&
-                SAFE_NAME.test(slug) &&
-                rest.length > 0 &&
-                rest.every(
-                  (s) => s && !s.startsWith(".") && !s.includes("\\"),
-                );
+                (ref?.project === undefined || from)
+                  ? canvasFile(
+                      from ? path.join(from, CANVASES) : examplesDir,
+                      examplesDir,
+                      i.name,
+                    )
+                  : undefined;
               return {
                 ...i,
                 path: picture(
@@ -537,18 +536,10 @@ export function createAgentServer(options: {
                 ),
                 reference:
                   ref &&
-                  (local
-                    ? path.join(
-                        folderOf(
-                          from ? path.join(from, CANVASES) : examplesDir,
-                          examplesDir,
-                          slug,
-                        ),
-                        ...rest,
-                      )
-                    : ref.community
+                  (file ??
+                    (ref.community
                       ? `${i.name} of the community project ${ref.community}`
-                      : i.name),
+                      : i.name)),
               };
             },
           );

canvas/server/sp.test.ts

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { expect, it, vi } from "vitest";
-import { createSpServer } from "./sp.ts";
+import { canvasFile, createSpServer } from "./sp.ts";
 
 // The examples directory is listed beside the project's canvases, shadowed by a folder of the
 // project's own, refused every write, and cloned into the project.
@@ -522,3 +522,34 @@ async function serve(options: Parameters<typeof createSpServer>[0]) {
   };
   return { ask, listen, close };
 }
+
+// What a chat attachment names is a file in a canvas folder, and nothing a browser sends reaches
+// outside one.
+it("resolves an attachment's name to a file in its canvas folder", () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "sp-attach-"));
+  const own = path.join(tmp, "project");
+  const examples = path.join(tmp, "examples");
+  fs.mkdirSync(path.join(examples, "demo"), { recursive: true });
+  expect(canvasFile(own, examples, "shop/01-home.html")).toBe(
+    path.join(own, "shop", "01-home.html"),
+  );
+  expect(canvasFile(own, examples, "shop/files/clip.mp4")).toBe(
+    path.join(own, "shop", "files", "clip.mp4"),
+  );
+  expect(canvasFile(own, examples, "shop/canvas.json#shape:a1")).toBe(
+    path.join(own, "shop", "canvas.json#shape:a1"),
+  );
+  expect(canvasFile(own, examples, "demo/01-a.html")).toBe(
+    path.join(examples, "demo", "01-a.html"),
+  );
+  for (const name of [
+    "shop",
+    "../etc/passwd",
+    "shop/../../etc",
+    "shop/files/..",
+    "shop//x",
+    "shop/.env",
+    "shop/a\\..\\..\\x",
+  ])
+    expect(canvasFile(own, examples, name)).toBeUndefined();
+});

canvas/server/sp.ts

@@ -80,6 +80,20 @@ export function folderOf(
   return !isCanvas && fs.existsSync(example) ? example : own;
 }
 
+/**
+ * The file a chat attachment names as `<slug>/<path>`: a board's HTML, a file under `files/`, or
+ * `canvas.json#<shape id>`. Undefined for a name that is not one, so nothing a browser sends can
+ * point outside a canvas folder: no part may be empty, start with a dot, or hold a backslash.
+ */
+export function canvasFile(canvasesDir: string, examplesDir: string, name: string) {
+  const [slug, ...rest] = name.split("/");
+  return SAFE_NAME.test(slug) &&
+    rest.length > 0 &&
+    rest.every((s) => s && !s.startsWith(".") && !s.includes("\\"))
+    ? path.join(folderOf(canvasesDir, examplesDir, slug), ...rest)
+    : undefined;
+}
+
 /**
  * The project's own settings, beside its canvases: which cover it chose, and the name it is shown
  * by when that is not its folder's. A project made without a name is an "Untitled" folder whose

canvas/src/agents.ts

@@ -80,7 +80,7 @@ export interface AgentImage {
   /** Where the server wrote it, for an agent that takes files rather than bytes; gone once
    *  that agent has exited. */
   path: string;
-  /** The file behind it — a board's HTML, a video, a canvas.json record — when the picture is
+  /** The file behind it (a board's HTML, a video, a canvas.json record) when the picture is
    *  only the panel's drawing of it: the agent is pointed at the file, which is what it can read
    *  and change, and not handed the picture. */
   reference?: string;

canvas/src/canvasAttach.tsx

@@ -57,8 +57,8 @@ async function attach(editor: Editor, target: TLShape) {
       return dispatchAttach({ kind: "board", name, src, reference: true });
     }
     // One of the person's own, drawn for the tile and named by where the agent reads the thing
-    // itself (canvasContent.ts). A picture goes over as one; anything else — a video, a note, a
-    // drawing — is a file the agent is pointed at, as a board is.
+    // itself (canvasContent.ts). A picture goes over as one. Anything else, such as a video, a
+    // note or a drawing, is a file the agent is pointed at, as a board is.
     const slug = personsShape(editor, target);
     if (slug) {
       const { blob } = await editor.toImage([target.id], { format: "png" });