agentic-canvas 0.6.1 → 0.8.0

package/dist/{chunk-66FFQMHI.js → chunk-M74ENUWR.js}

@@ -34,6 +34,22 @@ function boardKey(id) {
   }
   return id;
 }
+function isStoreId(id) {
+  try {
+    assertId(id);
+    return /^[A-Za-z0-9_-]{1,128}$/.test(id);
+  } catch {
+    return false;
+  }
+}
+function isBoardId(id) {
+  try {
+    boardKey(id);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function storeFailure(error) {
   if (error instanceof StoreConflictError) throw new CanvasError("UNAVAILABLE", "the board changed at the same time. Try again");
   if (error instanceof FileStoreError) throw new CanvasError(error.code === "LOCKED" ? "UNAVAILABLE" : "INVALID", error.message);
@@ -57,12 +73,20 @@ var CanvasService = class {
   /** The first 100 boards (the store sorts by id), with titles. A board whose stored bytes are damaged shows an empty title: it stays in the list so a person can find and repair it. */
   async list() {
     const page = await this.store.query(COLLECTION, { limit: 100 }).catch(storeFailure);
-    return page.items.map(({ id, data }) => {
-      try {
-        return { id, title: decodeStored(data, id, Board.decode).title };
-      } catch {
-        return { id, title: "" };
-      }
+    return page.items.map(({ id, data }) => summary(id, data));
+  }
+  /** The listed boards that exist, with titles, in the order given. */
+  async summaries(ids) {
+    const found = await Promise.all(ids.map(async (id) => ({ id, data: await this.store.get(COLLECTION, id).catch(storeFailure) })));
+    return found.flatMap(({ id, data }) => data ? [summary(id, data)] : []);
+  }
+  /** Delete a board and everything on it. Throws NOT_FOUND unless the board exists. The Worker erases the live room too. */
+  async delete(id) {
+    boardKey(id);
+    return this.store.transaction(async (tx) => {
+      if (!await tx.get(COLLECTION, id)) throw new CanvasError("NOT_FOUND", `no board "${id}"`);
+      await tx.delete(COLLECTION, id);
+      return { deleted: id };
     });
   }
   /** Throws NOT_FOUND unless the board exists. A live room opens only for a board that exists. */
@@ -182,6 +206,13 @@ var CanvasService = class {
     return decodeStored(doc, id, Board.decode);
   }
 };
+function summary(id, data) {
+  try {
+    return { id, title: decodeStored(data, id, Board.decode).title };
+  } catch {
+    return { id, title: "" };
+  }
+}
 function decodeStored(doc, id, decode) {
   try {
     return decode(fromBase64(String(doc.update)));
@@ -193,5 +224,7 @@ function decodeStored(doc, id, decode) {
 
 export {
   MAX_LIVE_BYTES,
+  isStoreId,
+  isBoardId,
   CanvasService
 };

package/dist/chunk-NRLF6MGR.js

@@ -0,0 +1,130 @@
+import {
+  FileStoreError
+} from "./chunk-NWQED42L.js";
+
+// src/store-file.ts
+import { randomUUID } from "crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "fs";
+import { join } from "path";
+import { createFileStore as createIdentityFileStore } from "agentic-identity/file";
+import { StoreConflictError } from "agentic-identity";
+var RETRY_FOR_MS = 1e4;
+var LOCK_STALE_MS = 3e3;
+var LOCK_WAIT_MS = 5e3;
+var HELD = /locked by another process/;
+var NOT_A_STORE_FILE = /is not an agentic-identity store file/;
+async function retried(run) {
+  const deadline = Date.now() + RETRY_FOR_MS;
+  for (; ; ) {
+    try {
+      return await run();
+    } catch (error) {
+      const clash = error instanceof StoreConflictError && !HELD.test(error.message);
+      if (!clash || Date.now() > deadline) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 5 + Math.random() * 20));
+    }
+  }
+}
+var isDoc = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var sleep = (ms) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function legacyCollections(path) {
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    const current = isDoc(data) && data.format === 1 && isDoc(data.collections);
+    const old = isDoc(data) && !current && Object.values(data).every((docs) => isDoc(docs) && Object.values(docs).every(isDoc));
+    return old ? data : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function withLock(path, fn) {
+  const lock = `${path}.lock`;
+  const mine = `${process.pid}:${randomUUID()}`;
+  for (const start = Date.now(); ; ) {
+    try {
+      writeFileSync(lock, mine, { flag: "wx", mode: 384 });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") return false;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) unlinkSync(lock);
+      } catch {
+      }
+      if (Date.now() - start > LOCK_WAIT_MS) return false;
+      sleep(10);
+    }
+  }
+  const owned = () => {
+    try {
+      return readFileSync(lock, "utf8") === mine;
+    } catch {
+      return false;
+    }
+  };
+  try {
+    fn(owned);
+  } finally {
+    if (owned()) rmSync(lock, { force: true });
+  }
+  return true;
+}
+function upgradeLegacyFile(path) {
+  if (legacyCollections(path) === void 0) return true;
+  try {
+    withLock(path, (owned) => {
+      const data = legacyCollections(path);
+      if (data === void 0) return;
+      const temp = `${path}.${process.pid}.upgrade`;
+      try {
+        const fd = openSync(temp, "w", 384);
+        try {
+          writeSync(fd, JSON.stringify({ format: 1, collections: data }));
+          fsyncSync(fd);
+        } finally {
+          closeSync(fd);
+        }
+        if (owned()) renameSync(temp, path);
+      } finally {
+        rmSync(temp, { force: true });
+      }
+    });
+  } catch {
+  }
+  return legacyCollections(path) === void 0;
+}
+function createFileStore(path, options = {}) {
+  upgradeLegacyFile(path);
+  const inner = createIdentityFileStore({ ...options, path });
+  const guard = async (run) => {
+    for (let upgraded = false; ; upgraded = true) {
+      try {
+        return await retried(run);
+      } catch (error) {
+        if (!(error instanceof Error)) throw error;
+        if (HELD.test(error.message)) throw new FileStoreError("LOCKED", "the database file is locked. If no agentic-canvas process runs, remove the .lock file next to it");
+        if (!NOT_A_STORE_FILE.test(error.message)) throw error;
+        if (legacyCollections(path) === void 0) throw new FileStoreError("DAMAGED", "the database file is not valid JSON. Repair or remove it");
+        if (upgraded || !upgradeLegacyFile(path)) throw new FileStoreError("DAMAGED", "the database file is in the older layout and could not be upgraded. Try again, and check that its folder is writable");
+      }
+    }
+  };
+  return {
+    region: inner.region,
+    get: (collection, id) => guard(() => inner.get(collection, id)),
+    query: (collection, query) => guard(() => inner.query(collection, query)),
+    put: (collection, id, doc) => guard(() => inner.put(collection, id, doc)),
+    delete: (collection, id) => guard(() => inner.delete(collection, id)),
+    transaction: (fn) => guard(() => inner.transaction(fn))
+  };
+}
+function openLocalStore(dir) {
+  mkdirSync(dir, { recursive: true });
+  return createFileStore(join(dir, STORE_FILE));
+}
+var STORE_FILE = "canvas.json";
+
+export {
+  createFileStore,
+  openLocalStore,
+  STORE_FILE
+};

package/dist/cli.js

@@ -5,13 +5,13 @@ import {
   operatorActor,
   runMcp,
   svgToPng
-} from "./chunk-VFJJGXTK.js";
+} from "./chunk-7IOW6LML.js";
 import {
   openLocalStore
-} from "./chunk-UKST5A57.js";
+} from "./chunk-NRLF6MGR.js";
 import {
   CanvasService
-} from "./chunk-66FFQMHI.js";
+} from "./chunk-M74ENUWR.js";
 import "./chunk-NWQED42L.js";
 import {
   CanvasError
@@ -36,6 +36,7 @@ Commands:
   connect <board> <from> <to> [--text <t>] Join two shapes with an arrow.
   update <board> <element> [--x --y --w --h --text --fill --stroke]  Change fields of an element. Resize with --w and --h.
   move <board> <element> --dx <n> --dy <n> Move an element or a group.
+  delete <board>                           Delete a whole board for good.
   rm <board> <element>                     Delete an element.
   flow <board> --text <t> | --file <p>     Draw a flowchart from text ("A -> B: label"). Use --file - for stdin.
   export <board> [--format svg|png] [--out <path>]  Print SVG, or write PNG to --out.
@@ -141,6 +142,10 @@ async function run(argv) {
     case "move":
       need(2, "<board> <element> --dx <n> --dy <n>");
       return print(await service.move(board, rest[0], num(v.dx) ?? Number.NaN, num(v.dy) ?? Number.NaN, actor()));
+    case "delete":
+      need(1, "<board>");
+      actor();
+      return print(await service.delete(board));
     case "rm":
       need(2, "<board> <element>");
       return print(await service.remove(board, rest[0]));

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { E as ErrorCode, a as BoardData, c as ShapeType, S as Shape, d as Endpoint, C as Connector } from './read-CeWoSAAy.js';
+import { E as ErrorCode, a as BoardData, c as ShapeType, S as Shape, d as Endpoint, C as Connector } from './read--Jd3kE13.js';
 import { PrincipalKind } from 'agentic-identity';
 import 'yjs';
 import 'zod';
@@ -81,6 +81,10 @@ interface CanvasClient {
     readBoard(id: string, options?: CallOptions): Promise<BoardData & {
         id: string;
     }>;
+    /** Delete a board for good, with its live room. Returns the id. */
+    deleteBoard(id: string, options?: CallOptions): Promise<{
+        deleted: string;
+    }>;
     /** The board as an SVG document. */
     exportSvg(id: string, options?: CallOptions): Promise<string>;
     addShape(id: string, shape: ShapeInput, options?: CallOptions): Promise<Shape>;

package/dist/client.js

@@ -58,6 +58,7 @@ function createClient(options) {
     listBoards: (o) => json("GET", "/boards", void 0, o),
     createBoard: (input = {}, o) => json("POST", "/boards", input, o),
     readBoard: (id, o) => json("GET", `/boards/${seg(id)}`, void 0, o),
+    deleteBoard: (id, o) => json("DELETE", `/boards/${seg(id)}`, void 0, o),
     exportSvg: async (id, o) => (await send("GET", `/boards/${seg(id)}/svg`, {}, o)).text(),
     addShape: (id, shape, o) => json("POST", `/boards/${seg(id)}/shapes`, shape, o),
     addConnector: (id, connector, o) => json("POST", `/boards/${seg(id)}/connectors`, connector, o),

package/dist/embed.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { CanvasClient } from './client.js';
 import { PrincipalKind } from 'agentic-identity';
-import './read-CeWoSAAy.js';
+import './read--Jd3kE13.js';
 import 'yjs';
 import 'zod';
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { B as Board, P as Principal } from './read-CeWoSAAy.js';
-export { a as BoardData, b as CanvasElement, e as CanvasError, C as Connector, f as EdgeData, d as Endpoint, E as ErrorCode, G as Group, M as MAX_ELEMENTS, g as MAX_TEXT, N as NodeData, h as SHAPE_TYPES, S as Shape, c as ShapeType, p as principalSchema, r as readBoard } from './read-CeWoSAAy.js';
-import { B as BoardAccess } from './service-Ckz-3qhK.js';
-export { C as CanvasService, D as DrawOptions, F as FlowEdge, a as FlowGraph, b as FlowNode, M as MAX_FLOW_EDGES, c as MAX_FLOW_NODES, P as Placement, d as drawFlow, l as layoutFlow, p as parseFlow } from './service-Ckz-3qhK.js';
+import { B as Board, P as Principal } from './read--Jd3kE13.js';
+export { a as BoardData, b as CanvasElement, e as CanvasError, C as Connector, f as EdgeData, d as Endpoint, E as ErrorCode, G as Group, M as MAX_ELEMENTS, g as MAX_TEXT, N as NodeData, h as SHAPE_TYPES, S as Shape, c as ShapeType, p as principalSchema, r as readBoard } from './read--Jd3kE13.js';
+import { B as BoardAccess } from './service-OiTtNadu.js';
+export { C as CanvasService, D as DrawOptions, F as FlowEdge, a as FlowGraph, b as FlowNode, M as MAX_FLOW_EDGES, c as MAX_FLOW_NODES, P as Placement, d as drawFlow, l as layoutFlow, p as parseFlow } from './service-OiTtNadu.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { FileStoreOptions, createFileStore, openLocalStore } from './store-file.js';
 export { PRINCIPAL_KINDS, PrincipalKind, isMachineMade } from 'agentic-identity';

package/dist/index.js

@@ -6,14 +6,14 @@ import {
   operatorActor,
   runMcp,
   svgToPng
-} from "./chunk-VFJJGXTK.js";
+} from "./chunk-7IOW6LML.js";
 import {
   createFileStore,
   openLocalStore
-} from "./chunk-UKST5A57.js";
+} from "./chunk-NRLF6MGR.js";
 import {
   CanvasService
-} from "./chunk-66FFQMHI.js";
+} from "./chunk-M74ENUWR.js";
 import "./chunk-NWQED42L.js";
 import {
   Board,

package/dist/live-worker.d.ts

@@ -5,10 +5,10 @@ import 'agentic-identity';
 import 'agentic-realtime';
 import 'agentic-identity/cloudflare';
 import 'hono';
-import './read-CeWoSAAy.js';
+import './read--Jd3kE13.js';
 import 'yjs';
 import 'zod';
-import './service-Ckz-3qhK.js';
+import './service-OiTtNadu.js';
 
 type Namespace = Parameters<typeof createDurableObjectRealtime>[0];
 interface LiveEnv extends WorkerEnv {

package/dist/live-worker.js

@@ -1,7 +1,7 @@
 import {
   createApp
-} from "./chunk-PH67TSYW.js";
-import "./chunk-66FFQMHI.js";
+} from "./chunk-JQCUVXXD.js";
+import "./chunk-M74ENUWR.js";
 import "./chunk-NWQED42L.js";
 import {
   CanvasError

package/dist/live.d.ts

@@ -1,6 +1,6 @@
-import { B as Board, P as Principal, a as BoardData, S as Shape, C as Connector, b as CanvasElement } from './read-CeWoSAAy.js';
+import { B as Board, P as Principal, a as BoardData, S as Shape, C as Connector, b as CanvasElement } from './read--Jd3kE13.js';
 import { Peer } from 'agentic-realtime/client';
-import { B as BoardAccess, D as DrawOptions } from './service-Ckz-3qhK.js';
+import { B as BoardAccess, D as DrawOptions } from './service-OiTtNadu.js';
 import 'yjs';
 import 'agentic-identity';
 import 'zod';
@@ -83,6 +83,9 @@ declare class LiveService implements BoardAccess {
         id: string;
         title: string;
     }[]>;
+    delete(id: string): Promise<{
+        deleted: string;
+    }>;
     read(id: string): Promise<BoardData & {
         id: string;
     }>;

package/dist/live.js

@@ -145,6 +145,13 @@ var LiveService = class {
     if (!Array.isArray(boards) || !boards.every((b) => typeof b?.id === "string" && typeof b?.title === "string")) throw new CanvasError("INVALID", "the server sent a board list this client does not know");
     return boards;
   }
+  async delete(id) {
+    const response = await call(this.options.server, this.options.token, `/boards/${encodeURIComponent(id)}`, { method: "DELETE" });
+    if (!response.ok) throw await refusal(response, "the server refused the request");
+    const { deleted } = await json(response);
+    if (deleted !== id) throw new CanvasError("INVALID", "the server sent a result this client does not know");
+    return { deleted };
+  }
   async read(id) {
     return this.use(id, async (live) => ({ id, ...readBoard(live.board) }));
   }

package/dist/{read-CeWoSAAy.d.ts → read--Jd3kE13.d.ts}

@@ -6,22 +6,16 @@ import { z } from 'zod';
  * The actor of a new write. The rule is the identity kernel's `parsePrincipal`: a known kind, and an id of 1 to 128
  * characters from A-Z, a-z, 0-9, ".", "_" and "-". The Worker, the CLI and the SDK all use it.
  */
-declare const principalSchema: z.ZodEffects<z.ZodObject<{
+declare const principalSchema: z.ZodPipe<z.ZodObject<{
     kind: z.ZodString;
     id: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    kind: string;
-    id: string;
-}, {
-    kind: string;
-    id: string;
-}>, {
+}, z.core.$strict>, z.ZodTransform<{
     kind: PrincipalKind;
     id: string;
 }, {
     kind: string;
     id: string;
-}>;
+}>>;
 type Principal = {
     kind: PrincipalKind;
     id: string;

package/dist/{service-Ckz-3qhK.d.ts → service-OiTtNadu.d.ts}

@@ -1,4 +1,4 @@
-import { c as ShapeType, B as Board, P as Principal, a as BoardData, S as Shape, C as Connector, b as CanvasElement } from './read-CeWoSAAy.js';
+import { c as ShapeType, B as Board, P as Principal, a as BoardData, S as Shape, C as Connector, b as CanvasElement } from './read--Jd3kE13.js';
 import { Store } from 'agentic-identity';
 
 declare const MAX_FLOW_NODES = 500;
@@ -68,6 +68,15 @@ declare class CanvasService {
         id: string;
         title: string;
     }[]>;
+    /** The listed boards that exist, with titles, in the order given. */
+    summaries(ids: string[]): Promise<{
+        id: string;
+        title: string;
+    }[]>;
+    /** Delete a board and everything on it. Throws NOT_FOUND unless the board exists. The Worker erases the live room too. */
+    delete(id: string): Promise<{
+        deleted: string;
+    }>;
     /** Throws NOT_FOUND unless the board exists. A live room opens only for a board that exists. */
     assertExists(id: string): Promise<void>;
     read(id: string): Promise<BoardData & {
@@ -123,6 +132,6 @@ declare class CanvasService {
     private load;
 }
 /** What the CLI and the MCP server need. `CanvasService` runs it on a store, and `LiveService` runs it in a live room. */
-type BoardAccess = Pick<CanvasService, "create" | "list" | "read" | "update" | "add" | "connect" | "move" | "remove" | "flow" | "exportSvg">;
+type BoardAccess = Pick<CanvasService, "create" | "list" | "read" | "delete" | "update" | "add" | "connect" | "move" | "remove" | "flow" | "exportSvg">;
 
 export { type BoardAccess as B, CanvasService as C, type DrawOptions as D, type FlowEdge as F, MAX_FLOW_EDGES as M, type Placement as P, type FlowGraph as a, type FlowNode as b, MAX_FLOW_NODES as c, drawFlow as d, layoutFlow as l, parseFlow as p };

package/dist/store-file.d.ts

@@ -7,19 +7,8 @@ declare class FileStoreError extends Error {
 }
 
 interface FileStoreOptions extends AdapterOptions {
-    /** How long a write waits for the lock before it fails. Defaults to 10000. */
-    lockTimeoutMs?: number;
-    /** A lock older than this is stale, if its owner is alive. Defaults to 30000. */
-    staleAfterMs?: number;
 }
-/**
- * A Store kept in one JSON file. Node only. It is an adapter of the shared Store port and passes `runStoreContract`. Many processes may share the file, for example the CLI
- * and the MCP server. Each write takes a lock file, reads the file again, applies the change, and
- * replaces the file by an atomic rename. A read sees the last renamed file, so it takes no lock.
- * Each call reads the whole file and loads the docs it needs into the shared memory adapter, which runs the
- * queries and the transaction rules. Cost grows with the file. Use it for local work, not for scale.
- * The lock needs one machine: the process check and the clock do not work across hosts.
- */
+/** A Store kept in one JSON file. Node only. It is the file adapter of agentic-identity, with a retry on a write clash. */
 declare function createFileStore(path: string, options?: FileStoreOptions): Store;
 /** The store the CLI and the MCP server share: one file in `dir`, which is made if it is missing. */
 declare function openLocalStore(dir: string): Store;

package/dist/store-file.js

@@ -2,7 +2,7 @@ import {
   STORE_FILE,
   createFileStore,
   openLocalStore
-} from "./chunk-UKST5A57.js";
+} from "./chunk-NRLF6MGR.js";
 import {
   FileStoreError
 } from "./chunk-NWQED42L.js";

package/dist/ui.css

@@ -15,9 +15,9 @@
   .shape { fill: var(--ad-color-surface-raised); stroke: var(--ad-color-border-strong); stroke-width: 1.5; }
   .shape.text { fill: transparent; stroke: none; }
   .shape.frame, .shape.image { fill: none; stroke-dasharray: 6 4; pointer-events: visiblePainted; }
-  .shape.sticky { fill: #ffe08a; stroke: #7a5b00; }
+  .shape.sticky { fill: var(--ad-color-warning-subtle); stroke: var(--ad-color-warning); }
   .label { fill: var(--ad-color-text); pointer-events: none; }
-  .sticky-label { fill: #1b1b1b; }
+  .sticky-label { fill: var(--ad-color-warning-text); }
   .edge { stroke: var(--ad-color-text-muted); stroke-width: 2; fill: none; pointer-events: none; }
   .hit { stroke: transparent; stroke-width: 14; }
   .arrowhead { fill: var(--ad-color-text-muted); }

package/dist/worker.d.ts

@@ -1,20 +1,101 @@
-import { Blobs } from 'agentic-identity';
+import { Store, PrincipalContext, Action, Grant, InviteSummary, Blobs } from 'agentic-identity';
 import { Realtime } from 'agentic-realtime';
 import { D1Like, R2Like } from 'agentic-identity/cloudflare';
 import { Hono } from 'hono';
-import { P as Principal } from './read-CeWoSAAy.js';
-import { C as CanvasService } from './service-Ckz-3qhK.js';
+import { P as Principal } from './read--Jd3kE13.js';
+import { C as CanvasService } from './service-OiTtNadu.js';
 import 'yjs';
 import 'zod';
 
+/**
+ * Who may do what on a board. A board is an identity resource of type `canvas`. The roles, the grants, the invites,
+ * and the links are those of agentic-identity: this class checks input and maps its failures to `CanvasError`.
+ * A caller who cannot read a board gets NOT_FOUND, so a board id tells a stranger nothing. A caller who can read
+ * it and lacks the role for the action gets FORBIDDEN.
+ */
+declare class CanvasAccess {
+    private readonly store;
+    private readonly sharing;
+    private readonly now;
+    constructor(store: Store, options?: {
+        now?: () => number;
+    });
+    /** A board id that the Store refuses names no board. The gate checks this for a role holder: a token of the dev list skips the gate. */
+    private known;
+    /** Make the actor the owner of a new board. */
+    register(ctx: PrincipalContext, id: string): Promise<void>;
+    /** Remove the sharing records of a board. Needs an owner. */
+    unregister(ctx: PrincipalContext, id: string): Promise<void>;
+    /** True if the board has sharing records: it was made by an identity credential. */
+    registered(id: string): Promise<boolean>;
+    /**
+     * True if the caller may do `action` on the board. A link token adds the role of its link. It writes an audit entry.
+     * An id that belongs to a resource of another type, in a Store shared with another app, is no board: it is denied.
+     */
+    allowed(ctx: PrincipalContext | null, action: Action, id: string, linkToken?: string): Promise<boolean>;
+    /** Throw NOT_FOUND for a caller who cannot read the board, and FORBIDDEN for one who can read it but not do `action`. */
+    require(ctx: PrincipalContext | null, action: Action, id: string, linkToken?: string): Promise<void>;
+    /** The ids of the boards a person or agent holds a role on, the first 100. A credential without `canvas:read` gets none. */
+    readable(ctx: PrincipalContext): Promise<string[]>;
+    grant(ctx: PrincipalContext, id: string, input: {
+        subjectKind?: unknown;
+        subjectId?: unknown;
+        role?: unknown;
+    }): Promise<{
+        ok: true;
+    }>;
+    revoke(ctx: PrincipalContext, id: string, input: {
+        subjectKind?: unknown;
+        subjectId?: unknown;
+    }): Promise<{
+        ok: true;
+    }>;
+    /** The grants and the invites on a board. An invite never shows its email. Links are not listed: a token shows once. */
+    list(ctx: PrincipalContext, id: string): Promise<{
+        grants: Grant[];
+        invites: InviteSummary[];
+    }>;
+    invite(ctx: PrincipalContext, id: string, input: {
+        role?: unknown;
+        email?: unknown;
+        handle?: unknown;
+        expiresInMs?: unknown;
+    }): Promise<{
+        id: string;
+    }>;
+    /** The email comes from a verified sign-in and the handle from the agent's own record, never from the request. */
+    accept(ctx: PrincipalContext, inviteId: string): Promise<{
+        ok: true;
+    }>;
+    /** The token shows once. Only its hash is stored. */
+    createLink(ctx: PrincipalContext, id: string, input: {
+        role?: unknown;
+        signedInOnly?: unknown;
+        expiresInMs?: unknown;
+    }): Promise<{
+        id: string;
+        token: string;
+    }>;
+    /** Revoke a link of this board. A link of another board is NOT_FOUND here, even for an owner of both. */
+    revokeLink(ctx: PrincipalContext, id: string, linkId: string): Promise<{
+        ok: true;
+    }>;
+}
+
 interface WorkerEnv {
     DB: D1Like;
     IMAGES: R2Like;
     /**
+     * Dev fallback. Set it to "1" to let `CANVAS_API_TOKENS` sign requests in. Without it, `CANVAS_API_TOKENS` is not read,
+     * and a request that sets it gets 503, so a deploy never trusts a static list by accident. Never set it in production.
+     */
+    CANVAS_UNSAFE_STATIC_TOKENS?: string;
+    /**
+     * Dev fallback, read only when `CANVAS_UNSAFE_STATIC_TOKENS` is "1". It is tried after the identity credentials.
      * JSON: `{ "<token>": { "actor": "ada", "kind": "human", "role": "viewer" } }`. A token has 32 characters or more.
      * A grant needs an actor id and a kind. A token with a missing or bad part gets 401.
      * The role is "editor" (the default) or "viewer". A viewer reads and cannot write, over HTTP or in a live room.
-     * Without this setting, every request gets 401. Every token reaches every board.
+     * Every token reaches every board, and a token cannot be revoked without a new deploy.
      */
     CANVAS_API_TOKENS?: string;
     /**
@@ -27,13 +108,22 @@ interface WorkerEnv {
     CANVAS_MAX_IMAGE_BYTES?: string;
 }
 type Role = "editor" | "viewer";
+/** The caller. `dev` is true for a token of the static list: it holds no board roles and reaches every board. */
+interface Caller {
+    actor: Principal;
+    role: Role;
+    principal: PrincipalContext;
+    dev: boolean;
+}
 type App = {
     Bindings: WorkerEnv;
     Variables: {
         service: CanvasService;
+        access: CanvasAccess;
         blobs: Blobs;
         actor: Principal;
         role: Role;
+        caller: Caller;
     };
 };
 interface AppOptions {
@@ -42,11 +132,18 @@ interface AppOptions {
 }
 /** A browser cannot set a header on a WebSocket. It offers the sub-protocols `agentic-canvas` and `agentic-canvas.bearer.<token in base64url>`. */
 declare const WS_PROTOCOL = "agentic-canvas";
-/** The principal and role for a bearer token, or null. The kind is never defaulted: a grant without a valid kind gets null. */
-declare function authenticate(request: Request, env: WorkerEnv): Promise<{
+/**
+ * The principal and role for a request, or null. A credential issued by agentic-identity (a bearer key or an access token in the
+ * store) signs in. Its scopes set the role: `canvas:write` is an editor, `canvas:read` a viewer, and none is denied.
+ * The static list signs in only with `CANVAS_UNSAFE_STATIC_TOKENS=1`. The kind is never defaulted: a principal without a valid kind gets null.
+ * Without `store` only the static list is read.
+ */
+declare function authenticate(request: Request, env: WorkerEnv, store?: Store): Promise<{
     actor: Principal;
     role: Role;
 } | null>;
+/** Like `authenticate`, with the whole principal context that board roles are checked against. */
+declare function identify(request: Request, env: WorkerEnv, store?: Store): Promise<Caller | null>;
 /** The image types we accept, found by their first bytes. The client's claim of a type is not trusted. */
 declare function sniffImage(bytes: Uint8Array): string | null;
 declare function createApp(options?: AppOptions): Hono<App>;
@@ -54,4 +151,4 @@ declare const _default: {
     fetch: (request: Request, env: WorkerEnv, ctx: unknown) => Response | Promise<Response>;
 };
 
-export { type AppOptions, type Role, WS_PROTOCOL, type WorkerEnv, authenticate, createApp, _default as default, sniffImage };
+export { type AppOptions, type Caller, type Role, WS_PROTOCOL, type WorkerEnv, authenticate, createApp, _default as default, identify, sniffImage };

package/dist/worker.js

@@ -2,10 +2,11 @@ import {
   WS_PROTOCOL,
   authenticate,
   createApp,
+  identify,
   sniffImage,
   worker_default
-} from "./chunk-PH67TSYW.js";
-import "./chunk-66FFQMHI.js";
+} from "./chunk-JQCUVXXD.js";
+import "./chunk-M74ENUWR.js";
 import "./chunk-NWQED42L.js";
 import "./chunk-ZSPZMGHG.js";
 import "./chunk-JOBTIAFJ.js";
@@ -14,5 +15,6 @@ export {
   authenticate,
   createApp,
   worker_default as default,
+  identify,
   sniffImage
 };