agentic-canvas 0.6.1 → 0.8.0

package/README.md

@@ -7,7 +7,7 @@
 
 A shared whiteboard for diagrams, drawn by people and agents.
 
-> Status: 0.6.0. The board model, the agent operations, the exports, the CLI, the
+> Status: 0.8.0. The board model, the agent operations, the exports, the CLI, the
 > MCP server, a small Worker API, and live co-editing work. The CLI, the MCP server,
 > and the SDK can join a live room. A remote client calls the Worker API. A small web UI, served by the Worker, is new in 0.4.0.
 > The package exports `agentic-canvas/ui`, a board view you can mount in your own app, new in 0.5.0.
@@ -38,7 +38,7 @@ npx agentic-canvas export demo --out demo.svg
 npx agentic-canvas export demo --format png --out demo.png
 ```
 
-Other commands: `list`, `add`, `connect`, `update`, `move`, `rm`. Run `npx agentic-canvas --help`.
+Other commands: `list`, `add`, `connect`, `update`, `move`, `rm`, `delete` (a whole board). Run `npx agentic-canvas --help`.
 `repair` is for the owner only. It needs `CANVAS_ACTOR=human:<id>`.
 Boards live in `./.agentic-canvas` (or `--dir`, or `CANVAS_DIR`). Every write
 needs an actor in `CANVAS_ACTOR`, as `<kind>:<id>`. The operator sets it. A write
@@ -52,7 +52,7 @@ CANVAS_ACTOR=agent:helper npx agentic-canvas --dir ./boards mcp
 ```
 
 The server speaks MCP on stdio. It has one tool for each CLI command: `create_board`,
-`list_boards`, `read_board`, `add_shape`, `connect`, `update_element`, `move`, `remove`, `draw_flow`, `export_svg`, and
+`delete_board`, `list_boards`, `read_board`, `add_shape`, `connect`, `update_element`, `move`, `remove`, `draw_flow`, `export_svg`, and
 `export_png`. `repair` is not a tool. Only a human operator runs it, from the CLI. The server will not start unless `CANVAS_ACTOR` is set to a valid
 `<kind>:<id>`. That actor stamps every write. No tool takes an actor, author, or kind, so a
 caller cannot choose who it writes as. An error comes back as a tool error with a code.
@@ -105,7 +105,7 @@ try {
 }
 ```
 
-There is one method per route: `me`, `listBoards`, `createBoard`, `readBoard`, `exportSvg`, `addShape`, `addConnector`,
+There is one method per route: `me`, `listBoards`, `createBoard`, `readBoard`, `deleteBoard`, `exportSvg`, `addShape`, `addConnector`,
 `drawFlow`, `update`, `move`, `remove`, `uploadImage`, `getImage`, `state`, and `checkpoint`. Each takes
 `{ signal }` last, so an `AbortSignal` can stop a call. The token sets the actor. A failed call throws
 `CanvasApiError` with the API `code` and the HTTP `status`. A call that gets no reply has code `NETWORK`
@@ -125,12 +125,66 @@ no CI secret is used:
 ```sh
 npm ci && npm run build
 WRANGLER_SEND_METRICS=false CLOUDFLARE_API_TOKEN=... npx wrangler deploy -c wrangler.demo.jsonc
-npx wrangler secret put CANVAS_API_TOKENS -c wrangler.demo.jsonc   # only to set or rotate tokens
+npx wrangler secret put CANVAS_API_TOKENS -c wrangler.demo.jsonc   # only to set or rotate the demo tokens
 ```
 
-`wrangler.demo.jsonc` holds the config. The tokens are a Worker secret and are not in the repo. To run your
+`wrangler.demo.jsonc` holds the config. The demo is a throwaway: it turns on the dev fallback (see "Auth") and
+signs in with a static token list. The tokens are a Worker secret and are not in the repo. To run your
 own copy, create a D1 database and an R2 bucket (both in the EU), put their names and id in a copy of that
-file, and deploy it the same way.
+file, and deploy it the same way. Remove `CANVAS_UNSAFE_STATIC_TOKENS` from your copy unless it is a throwaway.
+
+## Auth
+
+The Worker signs requests in with `agentic-identity` (`agentic-identity/http`). A bearer key (an `api_key` or
+`pat` credential) is a credential in the same Store as the boards (D1). A `session` credential works as a
+bearer key too, and as the `session` cookie for reads. A write or a socket that rides on the cookie gets 401,
+because the Worker lists no allowed origins. A credential names a principal, and the principal's scopes set the role:
+
+- Any scope that covers `canvas:write`, such as `canvas:write`, `canvas:admin`, `*:write`, or `*:admin`, is an editor.
+- Any scope that covers `canvas:read`, such as `canvas:read` or `*:read`, is a viewer. A viewer reads and cannot change a board, over HTTP or in a live room.
+- A principal with neither scope, an unknown, expired, or revoked credential, or a revoked parent in the
+  delegation chain, gets 401.
+
+Make principals and credentials in the database of this Worker with `agentic-identity` (its Worker, or
+`issueCredential` from its SDK). The two must share one D1 database and its schema (`D1_SCHEMA`). A credential
+that lives in another database gets 401 here. The author kind of every write is the kind of the principal.
+A browser sends its credential as the WebSocket sub-protocol `agentic-canvas.bearer.<token in base64url>`.
+
+**Dev fallback.** `CANVAS_API_TOKENS` is a static list of tokens, as JSON: `{ "<token>": { "actor": "ada", "kind": "human", "role": "viewer" } }`.
+It is read only when `CANVAS_UNSAFE_STATIC_TOKENS=1` is set too. Then it adds to the identity credentials: a
+token that is not a credential is looked up in the list. A static token reaches every board and cannot be
+revoked without a new deploy. It ignores revocation in the Store: a static grant named `ada` still writes as
+`ada` after the identity credential of `ada` is revoked. Use it for local work and throwaway demos only. If `CANVAS_API_TOKENS` is set
+and the switch is not, every API request gets 503 `NOT_CONFIGURED`, so a deploy never trusts the list by accident.
+
+## Sharing
+
+A board is an `agentic-identity` resource of type `canvas`. The person or agent that makes a board owns it.
+Roles, from least to most: `viewer`, `commenter`, `editor`, `owner`.
+
+| Role | May do |
+|---|---|
+| viewer, commenter | Read the board, its SVG, and join its live room to read. A board has no comments yet, so a commenter reads as a viewer. |
+| editor | Also draw: add, update, move, and remove elements. |
+| owner | Also delete the board, grant and revoke roles, list access, invite, and make or revoke share links. |
+
+A role never exceeds the scopes of the credential. An agent of an owner holds the owner's role only inside its own
+scopes: it needs `canvas:admin` to share, and `canvas:write` to draw. A caller with no role on a board gets 404, so a read or a write tells a stranger nothing. (A create with an id that is taken answers 409.) A caller with a role that is too low gets 403. `GET /boards` lists the boards you hold a role on.
+
+HTTP routes, under `/api/v1/canvas`. Each needs a bearer token, except the link read:
+
+| Route | Does |
+|---|---|
+| `GET /boards/:id/access` | Owner. The grants and the invites. An invite shows no email. |
+| `POST /boards/:id/grants` | Owner. Body `{ subjectKind: "human" or "agent", subjectId, role }`. |
+| `DELETE /boards/:id/grants?subjectKind=&subjectId=` | Owner. Revoke. The last owner cannot be removed. |
+| `POST /boards/:id/invites` | Owner. Body `{ role, email }` or `{ role, handle }`, and optional `expiresInMs`. The role is not `owner`. Returns `{ id }`. |
+| `POST /invites/accept` | Body `{ id }`. The caller must be the person (verified email) or the agent (handle) the invite names. |
+| `POST /boards/:id/links` | Owner. Body `{ role, signedInOnly?, expiresInMs? }`. Returns `{ id, token }`. The token shows once. |
+| `DELETE /boards/:id/links/:link` | Owner. Revoke a link of this board. |
+| `GET /shared/:id` and `GET /shared/:id/svg` | No bearer token needed. Send the link token in `x-link-token`. Read only. |
+
+The static dev fallback holds no board roles. Its tokens reach every board and cannot share.
 
 ## UI
 
@@ -146,12 +200,13 @@ npm ci
 npm run build                      # writes the UI to ui-dist/
 cat > .dev.vars <<'EOF2'
 CANVAS_REGION=unknown
+CANVAS_UNSAFE_STATIC_TOKENS=1
 CANVAS_API_TOKENS={"ada-token-0123456789-0123456789-0123456789":{"actor":"ada","kind":"human"}}
 EOF2
 WRANGLER_SEND_METRICS=false npx wrangler dev
 ```
 
-Open the address that wrangler prints and paste the token. A token has 32 characters or more. Its
+`CANVAS_UNSAFE_STATIC_TOKENS=1` turns on the dev fallback: see "Auth". Open the address that wrangler prints and paste the token. A static token has 32 characters or more. Its
 grant sets the name, the kind (a person or an agent), and the role. A `viewer` token reads and
 cannot change a board. The token stays in the tab's session storage.
 
@@ -239,11 +294,11 @@ at the same time keep the last write. The board list shows the first 100 boards.
 - A CLI over a local file store. Several processes can write at once.
 - An MCP server (stdio) over the same service as the CLI.
 - A Worker (`agentic-canvas/worker`) under `/api/v1/canvas`. Boards live in D1 and images in R2
-  (EU jurisdiction), through the shared `Store` and `Blobs` ports. Set `CANVAS_API_TOKENS`
-  (a JSON map of token to `{ actor, kind }`, tokens of 32 characters or more) and `CANVAS_REGION`.
-  Routes: `POST /boards`, `GET /boards/:id`, `GET /boards/:id/svg`, `POST /boards/:id/shapes`,
+  (EU jurisdiction), through the shared `Store` and `Blobs` ports. Set `CANVAS_REGION`. Callers sign in with
+  `agentic-identity` credentials (see "Auth" below). `CANVAS_API_TOKENS` is a dev fallback only.
+  Routes: `POST /boards`, `GET /boards/:id`, `DELETE /boards/:id`, `GET /boards/:id/svg`, `POST /boards/:id/shapes`,
   `/connectors`, `/flow`, `/move`, `GET /boards`, `PATCH /boards/:id/elements/:element`, `DELETE /boards/:id/elements/:element`, `POST /images`,
-  `GET /images/:id`. An image is stored under the SHA-256 of its bytes, and the reply gives
+  `GET /images/:id`. An editor may delete a board. The Worker also erases its live room. An image is stored under the SHA-256 of its bytes, and the reply gives
   the `blob:` ref for a shape. A busy database or bucket answers 503: try again.
 - Live rooms (`agentic-canvas/live-worker`, on `agentic-realtime`). One Durable Object holds one
   board. A token may carry `"role": "viewer"`: a viewer reads and cannot write. `GET /boards/:id/ws`
@@ -304,9 +359,9 @@ old author stays on its elements. Only new writes follow the strict rule.
 
 | Name | What it is |
 |---|---|
-| `createFileStore(path, options?)`, `openLocalStore(dir)` | A store on one JSON file, or on `canvas.json` in a directory. |
-| `FileStoreError` | The error that the store throws. Its `code` is `LOCKED` or `DAMAGED`. |
-| `FileStoreOptions` (type) | `lockTimeoutMs` (default 10000) and `staleAfterMs` (default 30000), plus the adapter options. |
+| `createFileStore(path, options?)`, `openLocalStore(dir)` | A store on one JSON file, or on `canvas.json` in a directory. It is the file store of agentic-identity. |
+| `FileStoreError` | The error for a file that is not a store file, or a lock that stays held. Its `code` is `DAMAGED` or `LOCKED`. |
+| `FileStoreOptions` (type) | The adapter options. The lock options `lockTimeoutMs` and `staleAfterMs` are gone. |
 | `STORE_FILE` | The file name that `openLocalStore` uses, `canvas.json`. |
 
 ### `agentic-canvas/live`
@@ -350,10 +405,13 @@ The stylesheet is a separate export, `agentic-canvas/ui.css`. Load `agentic-desi
 
 ## Limits
 
-- Canvas takes principal kinds, regions, and the Store and Blobs ports from `agentic-identity` 0.5.
-  It does not use the sharing API yet. Its editor and viewer tokens are a separate table in
-  `CANVAS_API_TOKENS`. It has no board delete or erase. When it adopts sharing, grants are keyed
-  on kind and id, and a delete calls `deleteResource`.
+- Canvas takes principal kinds, regions, and the Store and Blobs ports from `agentic-identity` 0.6.
+- A board made before sharing has no owner. Identity credentials get 404 on it. Only the dev fallback reaches it. Make it again, or add its
+  `canvas` resource and an owner grant with `agentic-identity`.
+- An image is stored under the hash of its bytes, not under a board. Any credential with `canvas:read` can fetch an image if it knows the hash.
+- A link visitor reads the stored board, which a live room saves at its next save. It cannot load `blob:` images.
+- A revoke, or a grant of viewer or commenter, closes the live sockets of the person or agent whose role changed. An agent that acts for that person keeps its socket until it joins again.
+- A link visitor reads. A link never writes. Links are not listed: the token shows once, at creation.
 - A board holds at most 10,000 elements. A flow holds at most 500 nodes and 2,000
   edges.
 - Flow text has no chains (`A -> B -> C`). Write one edge per line.
@@ -374,13 +432,15 @@ The stylesheet is a separate export, `agentic-canvas/ui.css`. Load `agentic-desi
 - `move` writes absolute positions. Two peers that move one shape at the same time do not add up:
   the last writer wins.
 - Frames are plain shapes. They do not own the shapes inside them yet.
-- The store is one file, `canvas.json`, in the store folder. A write takes `canvas.json.lock`.
-  A lock whose owner is gone, or that is older than 30 seconds, is taken over. A lock that
-  cannot be read counts as held: the call then waits 10 seconds and fails with `UNAVAILABLE`.
-  Remove the lock by hand if no process runs.
+- The store is one file, `canvas.json`, in the store folder. It is the file store of
+  agentic-identity: a write takes `canvas.json.lock`, and a lock older than 3 seconds is taken
+  over, so a writer that is paused for longer can lose its lock and the write then fails with
+  `UNAVAILABLE`. A write that clashes with another process is run again, for up to 10 seconds.
+  Remove the lock by hand if no process runs. A file written by an older agentic-canvas is
+  upgraded in place the first time a store opens it, and an older agentic-canvas cannot read
+  the upgraded file. Stop older agentic-canvas processes before you upgrade.
 - Node 22 or newer is needed. `agentic-canvas/file-store` exports `createFileStore(path)` and
-  `openLocalStore(dir)`. A writer that is paused for more than 30 seconds can lose its lock
-  and then still write.
+  `openLocalStore(dir)`.
 - A room remembers its authors for good, so a client can stamp an element with the name of anyone who
   once sent an update in that room. A save corrects the stored board and not the room: after a save that
   reports `fixed`, join again. A client that adds a root Yjs type of its own blocks later saves of that room.

package/dist/{chunk-VFJJGXTK.js → chunk-7IOW6LML.js}

@@ -8,7 +8,7 @@ import {
 
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.6.1" : readPackageVersion();
+var VERSION = true ? "0.8.0" : readPackageVersion();
 
 // src/brand.ts
 var BRAND = {
@@ -104,6 +104,11 @@ function createMcpServer(service, actor) {
     { description: "Read a board as data: nodes, edges, groups, text, and who made what.", inputSchema: { board }, annotations: read },
     tool(async (a) => json(await service.read(a.board)))
   );
+  server.registerTool(
+    "delete_board",
+    { description: "Delete a whole board for good. It cannot be undone.", inputSchema: { board }, annotations: { destructiveHint: true } },
+    tool(async (a) => json(await service.delete(a.board)))
+  );
   server.registerTool(
     "add_shape",
     {

package/dist/{chunk-PH67TSYW.js → chunk-JQCUVXXD.js}

@@ -1,13 +1,15 @@
 import {
   CanvasService,
-  MAX_LIVE_BYTES
-} from "./chunk-66FFQMHI.js";
+  MAX_LIVE_BYTES,
+  isBoardId,
+  isStoreId
+} from "./chunk-M74ENUWR.js";
 import {
   CanvasError
 } from "./chunk-ZSPZMGHG.js";
 
 // src/worker.ts
-import { hasScope, parsePrincipal, parseRegion } from "agentic-identity";
+import { createStoreAuth, hasScope as hasScope2, parsePrincipal, parseRegion } from "agentic-identity";
 import { createD1Store, createR2Blobs, D1_SCHEMA } from "agentic-identity/cloudflare";
 import { acceptWebSocketProtocol, principalFromWebSocketRequest } from "agentic-identity/http";
 
@@ -1788,6 +1790,150 @@ var Hono3 = class extends Hono {
   }
 };
 
+// src/access.ts
+import { createSharing, EraseRefusedError, hasScope, ROLES, SUBJECT_KINDS } from "agentic-identity";
+var RESOURCE_TYPE = "canvas";
+var SHARE_ROLES = ROLES.filter((r) => r !== "owner");
+var BAD_INPUT = /^(give an email or a handle|invalid handle|invalid email|invalid subject( kind "[^"]*")?|the last owner cannot be removed|expiresInMs must be .*|expiresAt must be .*|invalid role .*)$/;
+function refuse(error) {
+  if (error instanceof EraseRefusedError) throw new CanvasError("INVALID", error.message);
+  if (error instanceof Error && error.message === "forbidden") throw new CanvasError("FORBIDDEN", "you may not do this on this board");
+  if (error instanceof Error && BAD_INPUT.test(error.message)) throw new CanvasError("INVALID", error.message);
+  throw error;
+}
+var oneOf = (value, list, name) => {
+  if (typeof value !== "string" || !list.includes(value)) throw new CanvasError("INVALID", `${name} must be one of: ${list.join(", ")}`);
+  return value;
+};
+var storeId = (value, name) => {
+  if (typeof value !== "string" || !isStoreId(value)) throw new CanvasError("INVALID", `${name} must be 1 to 128 of A-Z, a-z, 0-9, _ and -, and not like __x__`);
+  return value;
+};
+var word = (value, name) => {
+  if (typeof value !== "string" || value === "") throw new CanvasError("INVALID", `${name} must be a non-empty string`);
+  return value;
+};
+var lifetime = (value, name) => {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new CanvasError("INVALID", `${name} must be a whole number of milliseconds above 0`);
+  return value;
+};
+var CanvasAccess = class {
+  constructor(store, options = {}) {
+    this.store = store;
+    this.sharing = createSharing(store, options);
+    this.now = options.now ?? Date.now;
+  }
+  store;
+  sharing;
+  now;
+  /** 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. */
+  known(id) {
+    if (!isBoardId(id)) throw new CanvasError("NOT_FOUND", `no board "${id}"`);
+  }
+  /** Make the actor the owner of a new board. */
+  async register(ctx, id) {
+    await this.sharing.createResource(ctx, { id, type: RESOURCE_TYPE }).catch((error) => {
+      if (error instanceof Error && error.message === "resource exists") throw new CanvasError("DUPLICATE_ID", `board "${id}" already exists`);
+      if (error instanceof Error && error.message === "resource id has old audit entries") throw new CanvasError("UNAVAILABLE", "this board id was used a moment ago. Try again, or use another id");
+      return refuse(error);
+    });
+  }
+  /** Remove the sharing records of a board. Needs an owner. */
+  async unregister(ctx, id) {
+    await this.sharing.deleteResource(ctx, id).catch(refuse);
+  }
+  /** True if the board has sharing records: it was made by an identity credential. */
+  async registered(id) {
+    if (!isBoardId(id)) return false;
+    return (await this.store.get("resources", id))?.type === RESOURCE_TYPE;
+  }
+  /**
+   * 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.
+   */
+  async allowed(ctx, action, id, linkToken) {
+    if (!await this.registered(id)) return false;
+    return (await this.sharing.can(ctx, action, id, linkToken === void 0 ? {} : { linkToken })).allowed;
+  }
+  /** Throw NOT_FOUND for a caller who cannot read the board, and FORBIDDEN for one who can read it but not do `action`. */
+  async require(ctx, action, id, linkToken) {
+    if (await this.allowed(ctx, action, id, linkToken)) return;
+    if (action === "read" || !await this.allowed(ctx, "read", id, linkToken)) throw new CanvasError("NOT_FOUND", `no board "${id}"`);
+    throw new CanvasError("FORBIDDEN", `this needs the ${action === "admin" ? "owner" : "editor"} role on the board`);
+  }
+  /** The ids of the boards a person or agent holds a role on, the first 100. A credential without `canvas:read` gets none. */
+  async readable(ctx) {
+    const root = ctx.chain[0];
+    if (!root || !SUBJECT_KINDS.includes(root.kind) || !hasScope(ctx.scopes, `${RESOURCE_TYPE}:read`)) return [];
+    const ids = [];
+    let cursor;
+    for (let pages = 0; pages < 10 && ids.length < 100; pages++) {
+      const page = await this.store.query("grants", { where: { subjectKind: root.kind, subjectId: root.id }, limit: 100, ...cursor === void 0 ? {} : { cursor } });
+      for (const { data } of page.items) {
+        if (ids.length >= 100 || typeof data.resourceId !== "string" || !ROLES.includes(data.role)) continue;
+        if (await this.registered(data.resourceId)) ids.push(data.resourceId);
+      }
+      if ((cursor = page.nextCursor) === void 0) break;
+    }
+    return ids;
+  }
+  async grant(ctx, id, input) {
+    this.known(id);
+    const subject = { kind: oneOf(input.subjectKind, SUBJECT_KINDS, "subjectKind"), id: storeId(input.subjectId, "subjectId") };
+    await this.sharing.grant(ctx, id, subject, oneOf(input.role, ROLES, "role")).catch(refuse);
+    return { ok: true };
+  }
+  async revoke(ctx, id, input) {
+    this.known(id);
+    const subject = { kind: oneOf(input.subjectKind, SUBJECT_KINDS, "subjectKind"), id: storeId(input.subjectId, "subjectId") };
+    await this.sharing.revokeGrant(ctx, id, subject).catch(refuse);
+    return { ok: true };
+  }
+  /** The grants and the invites on a board. An invite never shows its email. Links are not listed: a token shows once. */
+  async list(ctx, id) {
+    this.known(id);
+    const [grants, invites] = await Promise.all([this.sharing.listGrants(ctx, id, { limit: 200 }), this.sharing.listInvites(ctx, id, { limit: 200 })]).catch(refuse);
+    return { grants: grants.grants, invites: invites.invites };
+  }
+  async invite(ctx, id, input) {
+    this.known(id);
+    const role = oneOf(input.role, SHARE_ROLES, "role");
+    const expiresInMs = lifetime(input.expiresInMs, "expiresInMs");
+    const who = input.email !== void 0 ? { email: word(input.email, "email") } : input.handle !== void 0 ? { handle: word(input.handle, "handle") } : {};
+    if (input.email !== void 0 && input.handle !== void 0) throw new CanvasError("INVALID", "give an email or a handle, not both");
+    return this.sharing.createInvite(ctx, id, { role, ...who, ...expiresInMs === void 0 ? {} : { expiresInMs } }).catch(refuse);
+  }
+  /** The email comes from a verified sign-in and the handle from the agent's own record, never from the request. */
+  async accept(ctx, inviteId) {
+    if (!isStoreId(inviteId)) throw new CanvasError("FORBIDDEN", "you may not do this on this board");
+    const user = await this.store.get("users", ctx.principalId);
+    const agent = await this.store.get("principals", ctx.principalId);
+    const identity = {
+      ...user?.emailVerified === true && typeof user.email === "string" ? { email: user.email } : {},
+      ...typeof agent?.handle === "string" ? { handle: agent.handle } : {}
+    };
+    await this.sharing.acceptInvite(ctx, word(inviteId, "id"), identity).catch(refuse);
+    return { ok: true };
+  }
+  /** The token shows once. Only its hash is stored. */
+  async createLink(ctx, id, input) {
+    this.known(id);
+    const role = oneOf(input.role, SHARE_ROLES, "role");
+    const expiresInMs = lifetime(input.expiresInMs, "expiresInMs");
+    if (input.signedInOnly !== void 0 && typeof input.signedInOnly !== "boolean") throw new CanvasError("INVALID", "signedInOnly must be true or false");
+    return this.sharing.createLink(ctx, id, { role, signedInOnly: input.signedInOnly === true, ...expiresInMs === void 0 ? {} : { expiresAt: this.now() + expiresInMs } }).catch(refuse);
+  }
+  /** Revoke a link of this board. A link of another board is NOT_FOUND here, even for an owner of both. */
+  async revokeLink(ctx, id, linkId) {
+    this.known(id);
+    const link = isStoreId(linkId) ? await this.store.get("links", linkId) : null;
+    if (!link || link.resourceId !== id) throw new CanvasError("NOT_FOUND", "no such link on this board");
+    await this.sharing.revokeLink(ctx, linkId).catch(refuse);
+    return { ok: true };
+  }
+};
+
 // src/room-sync.ts
 import * as Y from "yjs";
 var SEEDER = { kind: "agent", id: "canvas-room" };
@@ -1902,6 +2048,9 @@ function remember(id, mark) {
   if (saved.size > 500) saved.clear();
   saved.set(id, mark);
 }
+function forget(id) {
+  saved.delete(id);
+}
 async function pull(live, service, id, force = false) {
   const { updates, compactions } = await live.meta(id);
   const mark = `${updates}:${compactions}`;
@@ -1979,11 +2128,52 @@ function tokenAuth(env) {
     }
   };
 }
-async function authenticate(request, env) {
-  const found = await principalFromWebSocketRequest(request, tokenAuth(env), { protocol: WS_PROTOCOL });
+var staticTokensOn = (env) => env.CANVAS_UNSAFE_STATIC_TOKENS === "1";
+function workerAuth(env, store) {
+  const auths = [];
+  if (store) auths.push(createStoreAuth(store));
+  const devAuth = staticTokensOn(env) ? tokenAuth(env) : void 0;
+  if (devAuth) auths.push(devAuth);
+  let dev = false;
+  let failure;
+  const auth = {
+    async authenticate(request) {
+      for (const auth2 of auths) {
+        let found;
+        try {
+          found = await auth2.authenticate(request);
+        } catch (error) {
+          failure = error;
+          return null;
+        }
+        if (!found) continue;
+        dev = auth2 === devAuth;
+        let step;
+        try {
+          step = parsePrincipal({ kind: found.kind, id: found.principalId });
+        } catch {
+          return null;
+        }
+        if (step.kind === SEEDER.kind && step.id === SEEDER.id) return null;
+        return found;
+      }
+      return null;
+    }
+  };
+  return { auth, failure: () => failure, dev: () => dev };
+}
+async function authenticate(request, env, store) {
+  const found = await identify(request, env, store);
+  return found && { actor: found.actor, role: found.role };
+}
+async function identify(request, env, store) {
+  const { auth, failure, dev } = workerAuth(env, store);
+  const found = await principalFromWebSocketRequest(request, auth, { protocol: WS_PROTOCOL, scope: "canvas:read" });
+  if (failure() !== void 0) throw failure();
   if (found instanceof Response) return null;
-  return { actor: { kind: found.kind, id: found.principalId }, role: hasScope(found.scopes, "canvas:write") ? "editor" : "viewer" };
+  return { actor: { kind: found.kind, id: found.principalId }, role: hasScope2(found.scopes, "canvas:write") ? "editor" : "viewer", principal: found, dev: dev() };
 }
+var svgResponse = (svg) => new Response(svg, { headers: { "content-type": "image/svg+xml", "x-content-type-options": "nosniff", "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; img-src data:" } });
 function sniffImage(bytes) {
   const at = (offset, ...sig) => sig.every((b, i) => bytes[offset + i] === b);
   if (at(0, 137, 80, 78, 71, 13, 10, 26, 10)) return "image/png";
@@ -2052,8 +2242,7 @@ var loggable = (error) => error instanceof Error ? LOGGABLE.exec(error.message)?
 function createApp(options = {}) {
   const app2 = new Hono3();
   app2.get("/health", (c) => c.json({ ok: true }));
-  const api = new Hono3();
-  api.use("*", async (c, next) => {
+  const open = async (c) => {
     let region;
     try {
       region = parseRegion(c.env.CANVAS_REGION ?? "");
@@ -2061,14 +2250,36 @@ function createApp(options = {}) {
       return fail("NOT_CONFIGURED", 'set CANVAS_REGION to "eu", "us", or "unknown"', 503);
     }
     if (!c.env.DB || !c.env.IMAGES) return fail("NOT_CONFIGURED", "bind DB (D1) and IMAGES (R2)", 503);
-    const who = await authenticate(c.req.raw, c.env);
+    if (c.env.CANVAS_API_TOKENS && !staticTokensOn(c.env)) return fail("NOT_CONFIGURED", "CANVAS_API_TOKENS is a dev fallback. Set CANVAS_UNSAFE_STATIC_TOKENS=1 to use it, or remove it and issue agentic-identity credentials", 503);
+    await ready(c.env.DB);
+    return createD1Store(c.env.DB, { region });
+  };
+  const shared = new Hono3();
+  const visit = async (c, route) => {
+    const store = await open(c);
+    if (store instanceof Response) return store;
+    const who = await identify(c.req.raw, c.env, store);
+    if (!who && c.req.header("authorization")) return fail("UNAUTHORIZED", "send a valid bearer token", 401);
+    const id = c.req.param("id");
+    await new CanvasAccess(store).require(who?.principal ?? null, "read", id, c.req.header("x-link-token") ?? "");
+    return route(new CanvasService(store));
+  };
+  shared.get("/:id", (c) => visit(c, async (service) => c.json(await service.read(c.req.param("id")))));
+  shared.get("/:id/svg", (c) => visit(c, async (service) => svgResponse(await service.exportSvg(c.req.param("id")))));
+  app2.route("/api/v1/canvas/shared", shared);
+  const api = new Hono3();
+  api.use("*", async (c, next) => {
+    const store = await open(c);
+    if (store instanceof Response) return store;
+    const who = await identify(c.req.raw, c.env, store);
     if (!who) return fail("UNAUTHORIZED", "send a valid bearer token", 401);
-    if (who.role === "viewer" && c.req.method !== "GET") return fail("FORBIDDEN", "this token is a viewer; it cannot change a board", 403);
+    if (who.role === "viewer" && c.req.method !== "GET" && !(c.req.method === "POST" && c.req.path === "/api/v1/canvas/invites/accept")) return fail("FORBIDDEN", "this token is a viewer; it cannot change a board", 403);
     c.set("actor", who.actor);
     c.set("role", who.role);
-    await ready(c.env.DB);
-    c.set("service", new CanvasService(createD1Store(c.env.DB, { region })));
-    c.set("blobs", createR2Blobs(c.env.IMAGES, { region, urlBase: new URL(c.req.url).origin, urlSecret: `${crypto.randomUUID()}${crypto.randomUUID()}` }));
+    c.set("caller", who);
+    c.set("service", new CanvasService(store));
+    c.set("access", new CanvasAccess(store));
+    c.set("blobs", createR2Blobs(c.env.IMAGES, { region: parseRegion(c.env.CANVAS_REGION ?? ""), urlBase: new URL(c.req.url).origin, urlSecret: `${crypto.randomUUID()}${crypto.randomUUID()}` }));
     await next();
   });
   api.get("/me", (c) => c.json({ actor: c.var.actor.id, kind: c.var.actor.kind, role: c.var.role }));
@@ -2086,16 +2297,39 @@ function createApp(options = {}) {
     }
   };
   const sync = async (c, next) => {
-    if (!/\/(ws|checkpoint)$/.test(new URL(c.req.url).pathname)) await saveRoom(c, false);
+    if (!/\/(ws|checkpoint)$/.test(new URL(c.req.url).pathname)) {
+      await saveRoom(c, false).catch((error) => {
+        if (!(c.req.method === "DELETE" && error instanceof CanvasError && error.code === "NOT_FOUND")) throw error;
+      });
+    }
     await next();
   };
+  const ADMIN = /* @__PURE__ */ new Set(["access", "grants", "invites", "links"]);
+  const WRITE = /* @__PURE__ */ new Set(["shapes", "connectors", "flow", "move", "elements", "checkpoint"]);
+  const needs = (method, path) => {
+    let decoded;
+    try {
+      decoded = decodeURI(path);
+    } catch {
+      return "admin";
+    }
+    const part = decoded.split("/boards/")[1].split("/");
+    if (part.length === 1) return method === "DELETE" ? "admin" : method === "GET" ? "read" : "write";
+    if (ADMIN.has(part[1])) return "admin";
+    return WRITE.has(part[1]) || method !== "GET" ? "write" : "read";
+  };
+  api.use("/boards/:id/*", async (c, next) => {
+    if (!c.var.caller.dev) await c.var.access.require(c.var.caller.principal, needs(c.req.method, new URL(c.req.url).pathname), c.req.param("id"));
+    await next();
+  });
   api.use("/boards/:id/*", sync);
   api.get("/boards/:id/ws", async (c) => {
     if (!options.live) return fail("NOT_FOUND", "this server hosts no live rooms", 404);
     if (c.req.header("upgrade") !== "websocket") return fail("UPGRADE_REQUIRED", "open this route as a WebSocket", 426);
     const id = c.req.param("id");
     await saveRoom(c, true);
-    const { actor, role } = c.var;
+    const { actor, caller } = c.var;
+    const role = caller.dev ? c.var.role : await c.var.access.allowed(caller.principal, "write", id) ? "editor" : "viewer";
     const opened = await options.live(c.env).connect(id, c.req.raw, { principal: { id: actor.id, kind: actor.kind }, role, name: actor.id });
     return acceptWebSocketProtocol(c.req.raw, opened, WS_PROTOCOL);
   });
@@ -2108,15 +2342,64 @@ function createApp(options = {}) {
     if (!update) throw new CanvasError("INVALID", `the update must be at most ${MAX_LIVE_BYTES} bytes`);
     return c.json(await handSave(options.live(c.env), c.var.service, id, update, c.var.actor));
   });
-  api.get("/boards", async (c) => c.json({ boards: await c.var.service.list() }));
+  api.get("/boards", async (c) => c.json({ boards: c.var.caller.dev ? await c.var.service.list() : await c.var.service.summaries(await c.var.access.readable(c.var.caller.principal)) }));
   api.post("/boards", async (c) => {
     const b = await jsonBody(c);
     const id = b.id === void 0 ? void 0 : text(b.id, "id");
     const title = b.title === void 0 ? void 0 : text(b.title, "title");
-    return c.json(await c.var.service.create(c.var.actor, { id, title }), 201);
+    if (c.var.caller.dev && id !== void 0 && await c.var.access.registered(id)) throw new CanvasError("DUPLICATE_ID", `board "${id}" already exists`);
+    const created = await c.var.service.create(c.var.actor, { id, title });
+    if (!c.var.caller.dev) {
+      await c.var.access.register(c.var.caller.principal, created.id).catch(async (error) => {
+        await c.var.service.delete(created.id).catch((failed) => console.error(JSON.stringify({ level: "error", op: "undo-create", message: loggable(failed) })));
+        throw error;
+      });
+    }
+    return c.json(created, 201);
   });
   api.get("/boards/:id", async (c) => c.json(await c.var.service.read(c.req.param("id"))));
-  api.get("/boards/:id/svg", async (c) => new Response(await c.var.service.exportSvg(c.req.param("id")), { headers: { "content-type": "image/svg+xml", "x-content-type-options": "nosniff", "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; img-src data:" } }));
+  api.delete("/boards/:id", async (c) => {
+    const id = c.req.param("id");
+    const { dev, principal } = c.var.caller;
+    if (dev && await c.var.access.registered(id)) throw new CanvasError("FORBIDDEN", "this board has owners: only an owner deletes it");
+    const present = await c.var.service.assertExists(id).then(() => true, (error) => {
+      if (error instanceof CanvasError && error.code === "NOT_FOUND" && !dev) return false;
+      throw error;
+    });
+    const live = options.live?.(c.env);
+    if (live) await live.erase(id);
+    const deleted = present ? await c.var.service.delete(id) : { deleted: id };
+    if (!dev) await c.var.access.unregister(principal, id);
+    if (live) {
+      await live.erase(id);
+      forget(id);
+    }
+    console.log(JSON.stringify({ level: "info", op: "delete-board", actorKind: c.var.actor.kind }));
+    return c.json(deleted);
+  });
+  api.get("/boards/:id/svg", async (c) => svgResponse(await c.var.service.exportSvg(c.req.param("id"))));
+  api.get("/boards/:id/access", async (c) => c.json(await c.var.access.list(c.var.caller.principal, c.req.param("id"))));
+  api.post("/boards/:id/grants", async (c) => {
+    const id = c.req.param("id");
+    const input = await jsonBody(c);
+    const done = await c.var.access.grant(c.var.caller.principal, id, input);
+    if (options.live && (input.role === "viewer" || input.role === "commenter") && typeof input.subjectId === "string") {
+      await options.live(c.env).revoke(id, input.subjectId).catch((error) => console.error(JSON.stringify({ level: "error", op: "revoke-room", message: loggable(error) })));
+    }
+    return c.json(done);
+  });
+  api.delete("/boards/:id/grants", async (c) => {
+    const id = c.req.param("id");
+    const subjectKind = c.req.query("subjectKind");
+    const subjectId = c.req.query("subjectId");
+    const done = await c.var.access.revoke(c.var.caller.principal, id, { subjectKind, subjectId });
+    if (options.live && subjectId) await options.live(c.env).revoke(id, subjectId).catch((error) => console.error(JSON.stringify({ level: "error", op: "revoke-room", message: loggable(error) })));
+    return c.json(done);
+  });
+  api.post("/boards/:id/invites", async (c) => c.json(await c.var.access.invite(c.var.caller.principal, c.req.param("id"), await jsonBody(c)), 201));
+  api.post("/boards/:id/links", async (c) => c.json(await c.var.access.createLink(c.var.caller.principal, c.req.param("id"), await jsonBody(c)), 201));
+  api.delete("/boards/:id/links/:link", async (c) => c.json(await c.var.access.revokeLink(c.var.caller.principal, c.req.param("id"), c.req.param("link"))));
+  api.post("/invites/accept", async (c) => c.json(await c.var.access.accept(c.var.caller.principal, text((await jsonBody(c)).id, "id"))));
   api.post("/boards/:id/shapes", async (c) => c.json(await c.var.service.add(c.req.param("id"), await jsonBody(c), c.var.actor), 201));
   api.post("/boards/:id/connectors", async (c) => c.json(await c.var.service.connect(c.req.param("id"), await jsonBody(c), c.var.actor), 201));
   api.post("/boards/:id/flow", async (c) => c.json(await c.var.service.flow(c.req.param("id"), text((await jsonBody(c)).text, "text"), c.var.actor)));
@@ -2176,6 +2459,7 @@ var worker_default = { fetch: (request, env, ctx) => app.fetch(request, env, ctx
 export {
   WS_PROTOCOL,
   authenticate,
+  identify,
   sniffImage,
   createApp,
   worker_default