shapewall 0.0.0-stage → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (304) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +651 -2
  6. package/THIRD_PARTY.md +165 -0
  7. package/bin/shapewall.js +29 -0
  8. package/dist/agent/package-lock.json +8384 -0
  9. package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
  10. package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
  11. package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
  12. package/dist/client/assets/History-CEv6b-av.js +1 -0
  13. package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
  14. package/dist/client/assets/Management-DCfhcEUY.js +1 -0
  15. package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
  16. package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
  17. package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
  18. package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
  19. package/dist/client/assets/index-ByQRKVit.css +2 -0
  20. package/dist/client/assets/index-DweQ8Qtu.js +29 -0
  21. package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-A8EnIYLR.js +1 -0
  24. package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
  25. package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
  26. package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
  27. package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
  28. package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
  29. package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
  30. package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
  31. package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
  32. package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
  33. package/dist/client/assets/ui-CLbws0rx.js +41 -0
  34. package/dist/client/build-info.json +1 -0
  35. package/dist/client/favicon.svg +7 -0
  36. package/dist/client/icons/apple-touch-icon.png +0 -0
  37. package/dist/client/icons/icon-192.png +0 -0
  38. package/dist/client/icons/icon-512.png +0 -0
  39. package/dist/client/icons/maskable-512.png +0 -0
  40. package/dist/client/index.html +25 -0
  41. package/dist/client/manifest.webmanifest +15 -0
  42. package/dist/client/sw.js +53 -0
  43. package/dist/client/theme-boot.js +27 -0
  44. package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
  45. package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
  46. package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
  47. package/dist/console/assets/console-C7uJLLOn.js +51 -0
  48. package/dist/console/assets/console-R8IBY3Am.css +2 -0
  49. package/dist/console/build-info.json +1 -0
  50. package/dist/console/console.html +21 -0
  51. package/dist/console/favicon.svg +7 -0
  52. package/dist/console/icons/apple-touch-icon.png +0 -0
  53. package/dist/console/icons/icon-192.png +0 -0
  54. package/dist/console/icons/icon-512.png +0 -0
  55. package/dist/console/icons/maskable-512.png +0 -0
  56. package/dist/console/manifest.webmanifest +15 -0
  57. package/dist/console/theme-boot.js +27 -0
  58. package/docs/agent-hardening.md +342 -0
  59. package/docs/agent-recipes.md +187 -0
  60. package/docs/agent-workflow.md +320 -0
  61. package/docs/agents.md +894 -0
  62. package/docs/architecture.md +242 -0
  63. package/docs/buzz.md +140 -0
  64. package/docs/capture-warnings.md +57 -0
  65. package/docs/config.md +489 -0
  66. package/docs/deployment.md +289 -0
  67. package/docs/design-system.md +162 -0
  68. package/docs/github.md +107 -0
  69. package/docs/hosted.md +764 -0
  70. package/docs/images/board-overview.png +0 -0
  71. package/docs/images/journeys.png +0 -0
  72. package/docs/images/live-comment.png +0 -0
  73. package/docs/images/phone-comment.png +0 -0
  74. package/docs/images/phone-overview.png +0 -0
  75. package/docs/images/variant.png +0 -0
  76. package/docs/interaction-audits.md +40 -0
  77. package/docs/journeys.md +137 -0
  78. package/docs/local-accounts.md +80 -0
  79. package/docs/notifications.md +237 -0
  80. package/docs/page-checks.md +69 -0
  81. package/docs/performance.md +174 -0
  82. package/docs/starter-agent.md +325 -0
  83. package/docs/updates.md +87 -0
  84. package/examples/audits/interaction.audit.json +17 -0
  85. package/package.json +132 -4
  86. package/src/accounts/avatar.js +121 -0
  87. package/src/accounts/local.js +464 -0
  88. package/src/agent/acp/command.js +204 -0
  89. package/src/agent/acp/detect.js +75 -0
  90. package/src/agent/acp/sandbox.js +160 -0
  91. package/src/agent/agent-health.js +75 -0
  92. package/src/agent/backends/acp.js +1297 -0
  93. package/src/agent/backends/index.js +61 -0
  94. package/src/agent/backends/openai.js +308 -0
  95. package/src/agent/composer.js +221 -0
  96. package/src/agent/config.js +338 -0
  97. package/src/agent/context.js +191 -0
  98. package/src/agent/control.js +122 -0
  99. package/src/agent/errors.js +17 -0
  100. package/src/agent/feedback-loop.js +137 -0
  101. package/src/agent/manage.js +94 -0
  102. package/src/agent/next-steps.js +51 -0
  103. package/src/agent/owner-mcp.js +38 -0
  104. package/src/agent/plain-text.js +52 -0
  105. package/src/agent/ratings-core.js +213 -0
  106. package/src/agent/ratings.js +100 -0
  107. package/src/agent/reply-text.js +67 -0
  108. package/src/agent/routes.js +1065 -0
  109. package/src/agent/run.js +326 -0
  110. package/src/agent/settings-routes.js +704 -0
  111. package/src/agent/showable.js +23 -0
  112. package/src/agent/starter/approvals.js +181 -0
  113. package/src/agent/starter/build-image.js +90 -0
  114. package/src/agent/starter/cli.js +163 -0
  115. package/src/agent/starter/disk.js +53 -0
  116. package/src/agent/starter/doctor.js +180 -0
  117. package/src/agent/starter/egress-proxy.js +351 -0
  118. package/src/agent/starter/gate.js +90 -0
  119. package/src/agent/starter/loop.js +114 -0
  120. package/src/agent/starter/model-relay.js +289 -0
  121. package/src/agent/starter/pause.js +14 -0
  122. package/src/agent/starter/probe.js +272 -0
  123. package/src/agent/starter/prompt.js +41 -0
  124. package/src/agent/starter/push-guard.js +146 -0
  125. package/src/agent/starter/rpc.js +164 -0
  126. package/src/agent/starter/runtime.js +287 -0
  127. package/src/agent/starter/sandbox-main.js +121 -0
  128. package/src/agent/starter/settings.js +290 -0
  129. package/src/agent/starter/source.js +69 -0
  130. package/src/agent/starter/supervisor.js +755 -0
  131. package/src/agent/starter/sweep.js +46 -0
  132. package/src/agent/starter/tools.js +524 -0
  133. package/src/agent/starter/watch.js +84 -0
  134. package/src/agent/starter/worktree.js +409 -0
  135. package/src/agent/text-diff.js +210 -0
  136. package/src/agent/thread-history.js +223 -0
  137. package/src/agent/threads.js +399 -0
  138. package/src/agent/tools.js +200 -0
  139. package/src/agent/turn-changes.js +424 -0
  140. package/src/agent/undo-state.js +26 -0
  141. package/src/agent/user-settings.js +308 -0
  142. package/src/auth/record.js +375 -0
  143. package/src/broken-links.js +164 -0
  144. package/src/buzz/client.js +75 -0
  145. package/src/buzz/config.js +151 -0
  146. package/src/buzz/environment.js +13 -0
  147. package/src/buzz/gateway.js +192 -0
  148. package/src/buzz/routes.js +61 -0
  149. package/src/buzz/signer-child.js +205 -0
  150. package/src/buzz/store.js +89 -0
  151. package/src/buzz/transport.js +60 -0
  152. package/src/buzz/verify.js +140 -0
  153. package/src/capture/actions.js +159 -0
  154. package/src/capture/capture.js +776 -0
  155. package/src/capture/dom-names.js +189 -0
  156. package/src/capture/element-map.js +509 -0
  157. package/src/capture/live.js +827 -0
  158. package/src/capture/media-scheme.js +317 -0
  159. package/src/capture/network-summary.js +86 -0
  160. package/src/capture/pacing.js +34 -0
  161. package/src/capture/requests.js +167 -0
  162. package/src/capture/sanitize.js +752 -0
  163. package/src/checks/accessibility.js +134 -0
  164. package/src/checks/budgets.js +58 -0
  165. package/src/checks/cli.js +55 -0
  166. package/src/checks/comparison.js +113 -0
  167. package/src/checks/environments.js +32 -0
  168. package/src/checks/flow-config.js +82 -0
  169. package/src/checks/flow-origin.js +53 -0
  170. package/src/checks/flows.js +398 -0
  171. package/src/checks/lighthouse-auth.js +145 -0
  172. package/src/checks/lighthouse-findings.js +130 -0
  173. package/src/checks/lighthouse.js +395 -0
  174. package/src/checks/robots.js +85 -0
  175. package/src/checks/routes.js +52 -0
  176. package/src/checks/run-control.js +259 -0
  177. package/src/checks/runner.js +724 -0
  178. package/src/checks/schema.js +133 -0
  179. package/src/checks/seo-analysis.js +443 -0
  180. package/src/checks/seo-probe.js +190 -0
  181. package/src/checks/seo-snapshot.js +99 -0
  182. package/src/checks/store.js +214 -0
  183. package/src/checks/transport.js +47 -0
  184. package/src/cli/args.js +319 -0
  185. package/src/cli/capture.js +79 -0
  186. package/src/cli/commands.js +92 -0
  187. package/src/cli/comments.js +84 -0
  188. package/src/cli/help.js +243 -0
  189. package/src/cli/init.js +214 -0
  190. package/src/cli/misc.js +64 -0
  191. package/src/cli/notify.js +87 -0
  192. package/src/cli/open.js +22 -0
  193. package/src/cli/serve.js +274 -0
  194. package/src/cli/variant.js +82 -0
  195. package/src/cli/watch.js +70 -0
  196. package/src/cli.js +130 -0
  197. package/src/comment-fields.js +76 -0
  198. package/src/comments-cli.js +208 -0
  199. package/src/config-reload.js +100 -0
  200. package/src/config.js +1061 -0
  201. package/src/devices-cli.js +21 -0
  202. package/src/diff.js +95 -0
  203. package/src/discover.js +284 -0
  204. package/src/doctor.js +295 -0
  205. package/src/event-log.js +268 -0
  206. package/src/events-cli.js +102 -0
  207. package/src/events.js +113 -0
  208. package/src/export.js +119 -0
  209. package/src/feedback.js +246 -0
  210. package/src/github.js +551 -0
  211. package/src/hosted/LICENSE.md +105 -0
  212. package/src/hosted/access-cli.js +78 -0
  213. package/src/hosted/admin.js +682 -0
  214. package/src/hosted/agent-approvals.js +163 -0
  215. package/src/hosted/agent-policy.js +189 -0
  216. package/src/hosted/app.js +510 -0
  217. package/src/hosted/auth-routes.js +540 -0
  218. package/src/hosted/auth.js +536 -0
  219. package/src/hosted/backup.js +483 -0
  220. package/src/hosted/board-context.js +35 -0
  221. package/src/hosted/board-routes.js +486 -0
  222. package/src/hosted/board-view.js +94 -0
  223. package/src/hosted/clean-worker.js +24 -0
  224. package/src/hosted/cleaner.js +89 -0
  225. package/src/hosted/comments.js +355 -0
  226. package/src/hosted/console-routes.js +401 -0
  227. package/src/hosted/cookies.js +18 -0
  228. package/src/hosted/crypto.js +80 -0
  229. package/src/hosted/db.js +496 -0
  230. package/src/hosted/device-routes.js +175 -0
  231. package/src/hosted/device.js +233 -0
  232. package/src/hosted/events.js +63 -0
  233. package/src/hosted/guards.js +172 -0
  234. package/src/hosted/guest-view.js +65 -0
  235. package/src/hosted/http.js +39 -0
  236. package/src/hosted/import.js +300 -0
  237. package/src/hosted/mail.js +73 -0
  238. package/src/hosted/mcp-http.js +71 -0
  239. package/src/hosted/membership.js +114 -0
  240. package/src/hosted/operator.js +478 -0
  241. package/src/hosted/ops-cli.js +345 -0
  242. package/src/hosted/pages.js +146 -0
  243. package/src/hosted/permissions.js +113 -0
  244. package/src/hosted/presence.js +372 -0
  245. package/src/hosted/projects.js +124 -0
  246. package/src/hosted/public.js +109 -0
  247. package/src/hosted/push.js +622 -0
  248. package/src/hosted/quotas.js +115 -0
  249. package/src/hosted/ratelimit.js +96 -0
  250. package/src/hosted/rebind.js +316 -0
  251. package/src/hosted/retention.js +128 -0
  252. package/src/hosted/server.js +260 -0
  253. package/src/hosted/setup-link.js +64 -0
  254. package/src/hosted/setup.js +323 -0
  255. package/src/hosted/shares.js +444 -0
  256. package/src/hosted/tailscale.js +204 -0
  257. package/src/hosted/tenancy.js +301 -0
  258. package/src/hosted/token-api.js +455 -0
  259. package/src/hosted/token-events.js +60 -0
  260. package/src/hosted/tokens.js +57 -0
  261. package/src/hosted/turnstile.js +49 -0
  262. package/src/hosted/usercontent.js +154 -0
  263. package/src/hosted/zip.js +155 -0
  264. package/src/invocation.js +58 -0
  265. package/src/journey-paths.js +282 -0
  266. package/src/journeys.js +189 -0
  267. package/src/links.js +106 -0
  268. package/src/local-projects.js +182 -0
  269. package/src/lock.js +193 -0
  270. package/src/mcp.js +417 -0
  271. package/src/mentions.js +151 -0
  272. package/src/net.js +15 -0
  273. package/src/notify/config.js +275 -0
  274. package/src/notify/index.js +301 -0
  275. package/src/notify/lease.js +73 -0
  276. package/src/notify/messages.js +212 -0
  277. package/src/notify/run.js +174 -0
  278. package/src/pixeldiff.js +49 -0
  279. package/src/png.js +143 -0
  280. package/src/reactions.js +111 -0
  281. package/src/remote/cli.js +133 -0
  282. package/src/remote/credentials.js +62 -0
  283. package/src/remote/ids.js +12 -0
  284. package/src/remote/login.js +155 -0
  285. package/src/remote/remote-mcp.js +237 -0
  286. package/src/remote/remote-watch.js +291 -0
  287. package/src/remote/remote.js +313 -0
  288. package/src/remote/share-state.js +78 -0
  289. package/src/remote/share.js +369 -0
  290. package/src/remote/terminal.js +13 -0
  291. package/src/serve-state.js +64 -0
  292. package/src/server/app.js +824 -0
  293. package/src/server/devices.js +186 -0
  294. package/src/server/local-console.js +28 -0
  295. package/src/server/local-user.js +59 -0
  296. package/src/server/pairing-routes.js +159 -0
  297. package/src/server/share-routes.js +89 -0
  298. package/src/server/tailscale.js +97 -0
  299. package/src/sitemap.js +431 -0
  300. package/src/store.js +983 -0
  301. package/src/tokens.js +11 -0
  302. package/src/update/routes.js +245 -0
  303. package/src/watch.js +403 -0
  304. package/src/which.js +58 -0
package/docs/hosted.md ADDED
@@ -0,0 +1,764 @@
1
+ # Hosted Shapewall (beta, push-first)
2
+
3
+ A server for teams: people sign in with passkeys, belong to workspaces, and review boards that were captured somewhere else and
4
+ uploaded with `shapewall push`. Agents read and resolve the comments with a project token through `shapewall comments --remote`,
5
+ `shapewall watch --remote` or `shapewall mcp --remote`.
6
+
7
+ License: the server (`src/hosted`) is under the [Functional Source License 1.1, ALv2 future license](../src/hosted/LICENSE.md).
8
+ You can run it for yourself or your company; you can't offer it as a competing hosted service. Each release becomes Apache 2.0
9
+ two years later. The clients (`push` and the `--remote` commands, in `src/remote`) are Apache 2.0 like the rest of Shapewall.
10
+
11
+ **Status: beta.** Start with one
12
+ invite-only server that the team reaches over Tailscale. Each teammate signs in with their own Shapewall passkey and joins a workspace.
13
+ Walk through the [checklist before you invite the team](#before-you-invite-the-team) on your own devices and network first.
14
+
15
+ `shapewall serve` is the separate, single-owner local tool. Its Tailscale/pairing mode lets that owner use their other devices;
16
+ `shapewall hosted` supplies team accounts, roles and collaboration. A public domain or a Shapewall-operated service is not needed
17
+ for tailnet multiplayer.
18
+
19
+ What v0 does not do: capture on the server. The server never opens a browser and never fetches a URL a user gives it, so there is no
20
+ SSRF surface. You capture on your machine or in CI (it can reach `localhost` and staging, which a hosted crawler cannot) and push.
21
+
22
+ ## Run it
23
+
24
+ ```sh
25
+ shapewall hosted --data /var/lib/shapewall-hosted --origin https://app.example.com --port 4700 --trust-proxy
26
+ ```
27
+
28
+ | Flag | Env | Default | What |
29
+ | ----------------------- | ---------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------- |
30
+ | `--data DIR` | `SHAPEWALL_HOSTED_DATA` | `./shapewall-hosted-data` | Database, secret, pushed files |
31
+ | `--origin URL` | `SHAPEWALL_HOSTED_ORIGIN` | `http://HOST:PORT` | The public origin. Passkeys are bound to its host name (the RP ID). |
32
+ | `--port`/`--host` | | `4700` on `127.0.0.1` | Keep it on loopback behind a reverse proxy |
33
+ | `--signup` | `SHAPEWALL_HOSTED_SIGNUP` | `invite` | `invite`: only invite links (and the setup link). `open`: anyone |
34
+ | `--trust-proxy` | `SHAPEWALL_HOSTED_TRUST_PROXY=1` | off | Client IPs from `X-Forwarded-For` (only from a proxy on this host) |
35
+ | | `SHAPEWALL_HOSTED_SECRET` | `<data>/secret.key` | Key for signed live-HTML URLs (made on first start, mode 0600) |
36
+ | | `RESEND_API_KEY` | unset | With `SHAPEWALL_EMAIL_FROM`: invite emails through Resend |
37
+ | | `SHAPEWALL_EMAIL_FROM` | unset | Sender for invite emails, e.g. `Shapewall <invites@example.com>` |
38
+ | `--previous-origin URL` | `SHAPEWALL_HOSTED_PREVIOUS_ORIGIN` | unset | The old origin during a move ([Moving to a new origin](#moving-to-a-new-origin)) |
39
+ | `--report-email ADDR` | `SHAPEWALL_HOSTED_REPORT_EMAIL` | unset | "Report this board" on public projects opens a mail to this address |
40
+ | | `SHAPEWALL_TURNSTILE_SITE_KEY` | unset | With `SHAPEWALL_TURNSTILE_SECRET`: a Cloudflare Turnstile check on open sign-up and comment share links |
41
+ | | `SHAPEWALL_TURNSTILE_SECRET` | unset | Turnstile secret key. Both keys or neither (one alone is a warning and stays off) |
42
+
43
+ It needs Node 22.13 or newer (it uses the built-in `node:sqlite`). Passkeys need a secure context: `https://`, or `http://localhost`
44
+ for trying it on your own machine (`--origin http://localhost:4700`; not `127.0.0.1`, which is not a valid passkey RP ID).
45
+
46
+ **The first account.** On an invite-only server with no accounts, the server makes a one-time setup link (valid 24 hours) and writes it
47
+ to `<data>/setup-link` (mode 0600). The start log names only the file and the command, never the link, so journald never holds it.
48
+ Print it on the server's machine with `shapewall hosted setup-link --data <dir>` (the same link until it expires or is used; `--new`
49
+ makes a new one and voids the old one). Open it, pick a handle and your name, and create a passkey. You get a workspace you own and
50
+ ten recovery codes, shown once: save them in a password manager. Using the link deletes the file.
51
+
52
+ **Bot check.** With both Turnstile keys set, open sign-up (`--signup open`) and opening a comment share link need a passing Turnstile
53
+ check (`POST /auth/register/options` and `POST /api/shares/open` take `turnstileToken`). It fails closed: a missing, wrong or
54
+ unverifiable token (Cloudflare unreachable, 5 second timeout) is refused with 403 `turnstile_failed`. Invite and setup sign-ups and
55
+ view-only links skip it. The console loads the widget from `challenges.cloudflare.com` only then, and only a server with keys adds
56
+ that origin to the console CSP. Off by default.
57
+
58
+ Deployment examples: [examples/hosted/shapewall-hosted.service](../examples/hosted/shapewall-hosted.service)
59
+ (systemd, hardened) and [examples/hosted/Caddyfile](../examples/hosted/Caddyfile).
60
+
61
+ ## Accounts
62
+
63
+ - **Passkeys only.** No email, no passwords. Sign-up and sign-in use discoverable credentials with user verification required, so
64
+ signing in is one button (no username). Where the browser supports it, the sign-in page also offers passkeys in the handle field's
65
+ autofill (WebAuthn conditional UI), renewed before the 5-minute ceremony expires. Add more passkeys (another device, a password
66
+ manager) on the Account page; the last one cannot be removed while you have no unused recovery codes.
67
+ - **Passkey labels.** Each passkey says where it lives, from the authenticator's backup flags: "Synced" (backed up by a cloud keychain
68
+ or password manager), "This device only", or "Not synced yet" (can sync, has not), plus how it connects (built in, phone, security
69
+ key). With a single device-only passkey the page suggests adding one on another device. A sign-in from a browser and OS the account
70
+ has not used before is marked "Signed in on a new device" in Account activity.
71
+ - **Recovery codes.** Ten one-time codes (about 128 bits each), stored as SHA-256 hashes, shown once. A code plus your handle signs you
72
+ in and ends every other session of the account (a stolen device loses its session). That session is never "fresh": in its first 30
73
+ minutes it can add a passkey, and nothing sensitive. A passkey added that way signs in, but is on hold for 24 hours before it can
74
+ confirm sensitive actions, so someone with one stolen code cannot lock the owner out: the owner's own passkey still removes theirs
75
+ (which ends their sessions) and makes new codes. Making new codes voids the old ones. Lose every passkey and every code and the
76
+ account is gone, but its work is not: projects belong to workspaces, so an admin removes the old member and invites the new account.
77
+ Admins never reset someone else's credentials (that would be a takeover path).
78
+ - **Sessions.** A random 32-byte cookie (`__Host-sw_session` on https), HttpOnly, SameSite=Lax, stored as a hash, 30 days sliding and
79
+ 90 days at most. Signing in replaces the browser's previous session. The Account page lists your signed-in devices (browser and OS
80
+ from the user agent, IP, last used); sign one out, or "Sign out other devices" for all of them. Removing a passkey also ends the
81
+ other sessions. The list carries a session id, never the cookie or its hash.
82
+ - **Admin idle expiry.** For an admin or owner, workspace pages and APIs need a passkey check after 12 hours without using any of
83
+ them (403 `reauth_required`; the console shows "Confirm it's you" and loads again). The session itself stays signed in.
84
+ - **Re-auth.** Creating API tokens or share links, turning share links on, adding or removing a passkey, new recovery codes, deleting
85
+ a project or the workspace, signing out devices, changing or removing an admin or owner, making someone an admin or owner and
86
+ inviting an admin or owner, turning public projects on, making a project public and starting a move of your sign-in to a new origin
87
+ need a passkey check (not on hold) in the last 10 minutes; the console asks for it ("Confirm it's you")
88
+ when needed. In a recovery-code session, which has no passkey to confirm with, it says "Add a passkey first" and links to adding
89
+ one (or lets you use a passkey you still have, which turns the session into a passkey session).
90
+ - **Account activity.** The Account page lists your own security events, newest first: sign-ins (passkey or recovery code, with the
91
+ device and IP), passkeys added and removed, new recovery codes, devices signed out (`GET /auth/security-log?before=`). After a
92
+ recovery code was used on your account, the next passkey sign-in shows a banner until you dismiss it ("That was me",
93
+ `POST /auth/security-notice/seen`); `GET /auth/me` carries it as `securityNotice`.
94
+ - **Deleting your account.** Account page, "Delete account": a fresh passkey check and your handle typed back
95
+ (`DELETE /auth/me` with `{ confirm, revokeTokens }`; `POST /auth/delete-account/preview` shows the plan first). Workspaces where you
96
+ are the only member are deleted with it; in the others you leave (your pending invites and share links are revoked, and your API
97
+ tokens unless you untick that). It is refused while you are the only owner of a workspace that has other people in it: make one of
98
+ them an owner first. Comments keep the name they were signed with. The account's own security events are deleted; an
99
+ `account_deleted` entry without a user stays.
100
+
101
+ ## Workspaces, roles and invites
102
+
103
+ Projects belong to a workspace, never to a person. Roles:
104
+
105
+ | Who | Reaches | Can |
106
+ | -------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
107
+ | viewer | every project | See projects, boards and comments |
108
+ | member | every project | + comment, reply, react, resolve, reopen; edit and delete their own comments |
109
+ | admin | every project | + projects, API tokens, share links, invite links (up to admin), change and remove members and viewers, delete any comment, the Access overview, the audit log, rename |
110
+ | owner | every project | + change or remove admins and owners, invite owners, delete the workspace. A workspace always keeps one owner |
111
+ | API token | one project | Its scopes (below): read, comment, resolve, push. Signed as the token, marked as an agent |
112
+ | share link guest (view) | one project, no workspace | See that project's boards and comments. Nothing else: no members, no other projects, no workspace data |
113
+ | share link guest (comment) | one project, no workspace | + add comments and replies, signed `<name> (guest)`. Never resolve, reopen, edit or delete; agents skip their comments by default |
114
+
115
+ The console shows this table on **Access, Roles** and next to every role picker.
116
+
117
+ **Invite links** hold a 32-byte token (stored hashed), a role, an expiry (1, 3, 7, 14 or 30 days; 7 by default), and work once. Opening
118
+ one shows the workspace and role; a new person creates an account from it, an existing one joins with a click. The token sits in the
119
+ URL fragment (`/invite#<token>`), and the setup link the same way (`/signup#setup=<code>`): browsers never send a fragment, so the token
120
+ stays out of access logs and Referer headers. The console reads it, keeps it in session storage for the sign-in round trip, and previews
121
+ the invite with `POST /api/invites/preview`. With `RESEND_API_KEY` and `SHAPEWALL_EMAIL_FROM` set, an admin can also have the link
122
+ emailed: at most 20 an hour per workspace, 50 a day per person and 500 a day for the whole server, with a fixed subject ("You have an
123
+ invite to a Shapewall workspace") and the workspace and inviter names quoted as names they chose, so the operator's sending domain is a
124
+ poor tool for phishing. Invite emails are off on a server with `--signup open` (anyone could make an account and send them). The address
125
+ is kept on the invite for its history. Without email the console only offers copying the link. At most 100 invites are pending per
126
+ workspace; pending ones can be revoked, used and expired ones move to History with who made them and who joined.
127
+
128
+ **What someone hands out goes with them.** Removing an admin or owner, or their leaving, revokes their pending invites, share links
129
+ and API tokens in the same transaction; demoting one below admin does the same, and an owner made admin loses their pending owner
130
+ invites. Deleting an account always revokes its tokens. On top of that, an invite works only while its creator can still invite to
131
+ that role (admin, or owner for owner invites), a share link only while its creator is still an admin or owner, and an API token only
132
+ while its creator is still a member with the admin or owner role, checked again at every use. There are no service tokens: every
133
+ token has a creator. An admin removing someone may keep their tokens (`{ revokeTokens: false }`, for CI that cannot stop at once);
134
+ kept tokens are `inactive` and refused until the creator is an admin here again, so revoke them and make new ones.
135
+
136
+ **Share links** let an admin share one project's boards with someone who has no account. They are off for every workspace until an
137
+ admin turns them on (Settings, which asks for a passkey check); turning them off stops every link at once, and turning them back on
138
+ restores the ones that are not revoked or expired.
139
+
140
+ - A link reaches exactly one project. It is **view-only** or **comment** (guests give a display name, 1 to 40 characters), expires
141
+ after 1, 7, 30 or 90 days, can have a passcode (4 to 64 characters, stored with scrypt), and is revoked with a click. At most 20
142
+ active links per project. Deleting the project ends its links.
143
+ - The link is `/share#<token>`: 32 random bytes in the fragment, stored as SHA-256. The landing page previews it with
144
+ `POST /api/shares/preview`; when there is a passcode, the preview names neither the project nor the workspace until it is right.
145
+ `POST /api/shares/open` checks the passcode (5 wrong tries per 15 minutes per link and IP, 30 an hour per IP, 50 an hour per link
146
+ from anywhere). Each try counts before the passcode is checked and a right one gives its count back, so parallel guesses cannot get
147
+ past the limit. It then starts a guest session: a random 32-byte cookie scoped to `/s/<share id>/` (HttpOnly, SameSite=Strict,
148
+ `__Secure-` on https), stored as SHA-256 in `guest_sessions` with the name, the browser and OS, the IP's /24 (or /48), for at
149
+ most 12 hours and never past the link's expiry. Opening the link again from the same browser ends its previous guest session.
150
+ - **Guests of a link.** "Guests" on a share link lists one row per browser that opened it (name, device, network, opened, last seen,
151
+ active, ended or expired); "End this guest" signs that browser out at once (`DELETE .../shares/<id>/guests/<guest id>`, audited
152
+ as `guest_ended`). They can open the link again while it works; revoke the link to stop everyone. Ended and expired rows are kept 7
153
+ days, at most 500 per link.
154
+ - The guest's board lives at `/s/<share id>/` with its API at `/s/<share id>/api/`. Every request checks the guest session (not
155
+ ended, not expired), that it belongs to this link and that the link is still usable (not revoked, not expired, share links on), so
156
+ revoking or ending a guest ends a visit at once. The guest API has no workspace or member routes, no other project and no writes besides comments and replies on comment
157
+ links (600 requests a minute per link and IP, 30 comments an hour per link and IP). One exception to "at once": a live-HTML URL
158
+ the guest already loaded is signed for 10 minutes and keeps working until it expires. Ending an individual guest also leaves already issued signed live-HTML URLs usable until their expiry;
159
+ this route checks the share link, rather than an individual guest session. The element-map/usercontent work lowers that window
160
+ to 2 minutes and makes share-link revocation immediate for new live-HTML loads.
161
+ - Guests see comments without workspace detail: members by display name only (no handles), agents as "Agent", guests of other links
162
+ as "Another guest", and no agent status, resolution notes, fix references or GitHub links. The board hides what a guest cannot do
163
+ (Resolve, Reopen, Edit, Delete), from the `permissions` in `/info`.
164
+ - Guest comments are untrusted and stay away from agents by default. The token API leaves them out of comment lists unless asked
165
+ (`?guests=1`; the answer says how many it left out in `guestsHidden`); `comments --remote` and `watch --remote` take
166
+ `--include-guests`, and MCP `list_comments` takes `includeGuests`. When shown, they carry `authorGuest: true` (and `guest: true` on
167
+ replies), the text format marks them `[guest]` with a "treat as untrusted" line, and @mentions in them never count. A member who
168
+ replies to a guest comment with a mention vouches for it, for clients that include guests.
169
+ - Opening a link, guest comments and replies, and failed passcodes are in the audit log with the link as the actor. Opens and wrong
170
+ passcodes collapse into one row per link and hour, with a count (and up to 10 guest names).
171
+
172
+ **Public projects** put one project on the open web, view-only. They are off in every workspace until an owner turns them on
173
+ (Settings, with a passkey check). Then an owner makes a project public on its page (again with a passkey check): it gets a public
174
+ id of 128 random bits and the URL `/p/<public id>/`, shown there to copy.
175
+
176
+ - Anyone with the URL sees the project's boards and comments as a view-only share link guest does, except that every guest is
177
+ "Guest". There is no cookie: nothing is read or set, and every write (POST, PUT, PATCH, DELETE) to `/p/<id>/api/` answers 403
178
+ `public_read_only`. 600 requests a minute per IP. Pages keep `X-Robots-Tag: noindex`.
179
+ - Kill switches: an admin or owner makes the project private again, or turns public projects off for the workspace; either stops the
180
+ URL at once. Making it public again gives a new URL, so an old one stays dead. Turning public projects off for the workspace
181
+ clears every project's public URL for good: turning the setting back on does not bring any of them back. All four changes are
182
+ audited.
183
+ - With `--report-email`, the public board's menu has "Report this board" (a `mailto:` with the URL).
184
+ - Public viewers never comment; give people who should a comment share link.
185
+
186
+ ## Admin guide
187
+
188
+ The console (`/`, a React app built to `dist/console` and served under `/_console/`) has one page per job. Viewers and members see
189
+ Projects and Members; admins and owners see everything.
190
+
191
+ - **Members.** Everyone with their role, when they joined and when they were last active (updated at most every 5 minutes). Change a
192
+ role from the picker or remove someone from the row menu; both ask first. Admins manage members and viewers; only an owner changes
193
+ or removes an admin or an owner, and that needs a fresh passkey check, as does making someone an admin or owner. The last owner
194
+ cannot be demoted, removed or leave. Removing, or demoting below admin, revokes the person's pending invites, share links and API
195
+ tokens (the confirm dialog says so). When the person made API tokens that still work, the remove dialog lists them with "Revoke"
196
+ checked; unchecking it keeps them, inactive (`DELETE /members/:user` with `{ revokeTokens: false }`); the audit entry says whose
197
+ invites, links and tokens went.
198
+ - **Invites.** "Invite people": pick the role (up to your own: admins invite up to admin), the expiry, an optional note for whom it is
199
+ (up to 80 characters, shown in the pending list, the history and the audit log; admins only) and optionally an email address. The
200
+ link is shown once, with a copy button. Pending invites can be revoked; History shows used, revoked and expired ones. Someone who
201
+ opens an invite while signed in to an account that is already in the workspace is told so, with a link to it. The invite page keeps
202
+ the token in the tab's session storage until it is used, so a reload or a trip through sign-in does not lose it, and a link that
203
+ lost its code can be pasted back in.
204
+ - **Access.** Who reaches what. "By project" is a matrix of people, API tokens and share links against projects (on a phone, pick a
205
+ project). "By person" shows one person's role and what it gives them in each project. "Roles" is the table above. Pending invites
206
+ are counted.
207
+ - **API tokens.** Every token in the workspace with its project, scopes, creator, created, last used and expiry. A token whose creator
208
+ has left the workspace or is no longer an admin is `inactive` and flagged: it is refused at every request, so revoke it.
209
+ - **Share links.** On each project page (Manage): create, copy, see opens and last use, list and end guests, revoke. They are also
210
+ listed in Access.
211
+ - **Public.** On each project page, when the workspace allows it: make the project public (owners) or private (admins), and copy its
212
+ public URL.
213
+ - **Audit log.** Filter by who (a person, a token or a share link), by action and by time (24 hours, 7, 30 or 90 days), and search
214
+ (`q`: names, handles, projects, tokens, links, details); 50 a page, newest first, "Load older events" for more. Each entry shows the
215
+ relative and the exact time. "Export CSV" downloads up to 10,000 entries with the same filters (`GET /audit/export`; cells that
216
+ start with `=`, `+`, `-` or `@` get a leading `'` so a spreadsheet does not run them).
217
+ - **Settings.** Rename (admins), share links on or off (admins), public projects on (owners) or off (admins), export (admins), leave, and delete the workspace (the owner, with a
218
+ passkey check and the workspace name typed back). Deleting removes every project, board, file, comment, token, invite, share link and
219
+ audit entry, and writes one `workspace_deleted` entry to the account log.
220
+ - **Export.** "Download a copy" (admins, with a fresh passkey check; `POST /export`; one at a time per workspace, 409 while one runs,
221
+ and 5 an hour per person) streams a zip: `workspace.json` (the workspace,
222
+ members, projects, tokens without their secrets, share links without theirs), `audit.json`, and per board `board.json`,
223
+ `comments.json` and its files (captures, variants, versions, live HTML). Over 3.5 GB it answers 413 (no zip64 yet). `audit.json` holds
224
+ up to 100,000 entries, newest first, read and written 1,000 at a time.
225
+ - A member who opens an admin page (a link, a bookmark) sees "This page needs the admin role" instead of being sent back to Projects.
226
+ - An empty project shows a four-step checklist (project, token, push, invite) that ticks itself off. The token dialog shows the
227
+ working command once, with the token in it: `SHAPEWALL_TOKEN=... shapewall push --remote <this server>`.
228
+
229
+ Console API (cookie session; all under `/api/workspaces/:ws`): `GET /` (workspace, members, projects, `me`, features),
230
+ `PATCH /` (rename), `PATCH /settings` (`{ shareLinks }`), `DELETE /` (`{ confirm: name }`), `GET /invites` (`{ pending, history }`),
231
+ `POST /invites` (`{ role, expiresInDays, email }`), `DELETE /invites/:id`, `PATCH /members/:user` (`{ role }`),
232
+ `DELETE /members/:user` (`{ revokeTokens }`), `GET /access`, `GET /tokens`, `GET /shares`, `GET|POST /projects/:pid/shares`,
233
+ `DELETE /projects/:pid/shares/:sid`, `GET /audit?actor=user:<id>|token:<id>|share:<id>&action=&from=&to=&q=&before=&limit=`,
234
+ `GET /audit/export` (CSV, same filters), `GET /audit/filters`, `POST /export` (zip). Account: `GET /auth/sessions`,
235
+ `DELETE /auth/sessions/:id`, `POST /auth/sessions/revoke-others`, `GET /auth/security-log`, `POST /auth/security-notice/seen`,
236
+ `POST /auth/delete-account/preview`, `DELETE /auth/me`. Logins from the CLI: `POST /api/device/lookup|approve|deny` (`{ code, ... }`).
237
+
238
+ ## Projects, tokens and push
239
+
240
+ An admin creates a project and an **API token** for it (Workspace page, "API tokens"). Tokens look like `swp_` + 43 characters, are
241
+ shown once, stored as SHA-256 with a 12-character display prefix, can expire, and are revoked with a click. Each token belongs to one
242
+ project and has scopes:
243
+
244
+ | Scope | Allows |
245
+ | --------- | --------------------------------------------------------- |
246
+ | `read` | Pages, comments, screenshots and live HTML of the project |
247
+ | `comment` | Replies and agent status |
248
+ | `resolve` | Resolve and reopen |
249
+ | `push` | Upload captures |
250
+
251
+ The CLI takes the token from `$SHAPEWALL_TOKEN` or `--token-file FILE`, never from a flag (other users can read a process's arguments),
252
+ and sends it only over https (plain http only to this machine).
253
+
254
+ ```sh
255
+ shapewall capture
256
+ SHAPEWALL_TOKEN=swp_... shapewall push --remote https://app.example.com
257
+ ```
258
+
259
+ **`shapewall login`** gets a token without copying one:
260
+
261
+ ```sh
262
+ shapewall login --remote https://app.example.com
263
+ shapewall push --remote https://app.example.com # and comments, watch, mcp --remote
264
+ ```
265
+
266
+ It prints a short code (like `BCDF-GHJK`) and opens `/device` in the browser (a URL the CLI builds from `--remote`, never one the
267
+ server sends; on Windows through `rundll32 url.dll,FileProtocolHandler`, no shell). Someone with the admin role there types the code,
268
+ checks that the page shows the same code, the address the login came from and how long ago it started, picks the workspace,
269
+ project, scopes and expiry (30 or 90 days, or none), and approves with a passkey check. The machine name is shown as reported by the
270
+ terminal (unchecked), and the page warns when the login came from another address than the approver's. The CLI, polling `POST /api/v1/device/poll` every 3 seconds, receives the token once and saves it
271
+ in `$XDG_CONFIG_HOME/shapewall/credentials.json` (or `~/.config/...`): the folder 0700, the file 0600, one entry per server origin.
272
+ It never prints the token. The token is named `<machine> (shapewall login)` and listed with the others; revoke it there. A code
273
+ expires after 10 minutes, works once, and can be denied. `$SHAPEWALL_TOKEN` and `--token-file` still win over the saved login. The
274
+ CLI side is `POST /api/v1/device/start` (`{ name }`, 10 a minute per IP, at most 5 pending per IP (429), at most 500 pending in all,
275
+ the oldest dropped to make room) and `/poll` (`{ deviceCode }`: 202 while waiting, 200 with
276
+ the token, 403 denied, 410 expired); lookups are limited to 10 a minute per account. Pending logins live in SQLite
277
+ (`device_logins`), so a restart keeps them: the row holds the device code's SHA-256, never the code. An approved token is stored
278
+ sealed to a key derived from the device code (X25519 and AES-256-GCM), so only the CLI that holds the code can open it, and the row is
279
+ deleted when it is picked up. Approving is single-use: two approvals race for one row and one wins.
280
+
281
+ A refused token (revoked, expired, its creator no longer an admin, or mistyped) gets one message from every `--remote` command:
282
+ "This token was revoked, has expired or its maker is no longer an admin there (or it is wrong). Create a new one in the console:
283
+ <url>". Names and messages from the server are printed without control characters, so a project name cannot rewrite the terminal.
284
+
285
+ `push` uploads each board's latest capture, its variants and its kept versions, then commits; the board switches to the new files all at
286
+ once. Comments stay. What a push sends about the board is only what the board shows (page ids, paths, titles, groups, notes, viewports,
287
+ journeys): never `auth`, storage states, login scripts, `actions` (a `fill` can hold a password), `waitFor`, or local paths.
288
+
289
+ The server treats every upload as untrusted, even from our CLI:
290
+
291
+ - File names must be ones the local tool writes, for pages and viewports on the pushed board.
292
+ - Live HTML runs through the same sanitizer as a local capture (`sanitizeDocument`, then the CSP meta tag) and the same 5 MB cap, with
293
+ at most 4 MB of CSS per file. The sanitizer's scans run in linear time on any input.
294
+ - PNGs are decoded and re-encoded (which drops every chunk but the pixels), after a header check (at most 3840 x 8000, 16 megapixels,
295
+ 10 MB). Local viewports can be larger than 16 megapixels; those do not push.
296
+ - Cleaning runs in worker threads (2 at once, 32 waiting, 30 seconds and 512 MB each), never on the server's event loop; a token has at
297
+ most 4 uploads in flight.
298
+ - The manifest and variants are rebuilt field by field; the board definition is validated by the same code as a local config.
299
+ - Limits: 5000 files and 1 GB per push, 500 pages per board, 10 boards per project (checked again at commit), 20 pushes per hour per
300
+ token, and 5 GB per workspace (committed boards plus open pushes). A push is open for an hour; after that it takes no more files and
301
+ a sweep (at start and every 10 minutes) removes its staging folder, staging folders without a push, and board folders a commit left
302
+ behind.
303
+
304
+ ## The board
305
+
306
+ `/w/<workspace>/p/<project>/` serves the same board client as `shapewall serve`, on an API with the same shape, for members of the
307
+ workspace. Comments are signed with the account's name and handle (the server sets them; the board shows the handle beside the name).
308
+ A token's replies are signed with the token's name and marked as an agent; the API ignores any `author` it sends. Captures from the board and editing journeys are off on a
309
+ hosted board (push again instead). Compare between environments is not hosted yet.
310
+
311
+ Live HTML is served from `/uc/...` through HMAC-signed URLs that expire after 2 minutes. The board API gives each new frame load a
312
+ fresh redirect. Guest URLs are bound to their share link and checked again on every load: revoking the link stops new loads immediately
313
+ (an already loaded frame keeps its document). Responses carry a CSP `sandbox` without `allow-same-origin`, no script source, and
314
+ `Cache-Control: private, no-store`. Frames use `sandbox=""`. Pins and click targets come from the captured element map on the authenticated
315
+ board API, which the server validates field by field on push, including its viewport dimensions (3 MB, at most 8000 elements).
316
+
317
+ For a separate cookieless domain, run `shapewall hosted --origin https://app.example.com --usercontent-origin https://example-content.net`
318
+ (or set `SHAPEWALL_USERCONTENT_ORIGIN`). Point both host names at this server through your TLS proxy, preserving Host. The content origin
319
+ serves only signed `/uc/` routes, ignores cookies and never sets one; the app origin refuses `/uc/`. Its CSP permits only the app origin
320
+ to frame documents. Use a separate registrable domain for a separate site; a second port or subdomain alone is a different origin, and
321
+ the opaque sandbox remains the main boundary. Separate usercontent must be https when the app is https.
322
+
323
+ The capture's base URL (often `http://localhost:...` on the machine that captured) is never sent to a hosted board, to members or
324
+ guests: page links and "open the site" use the board's `publicUrl` when the config has one, and are hidden otherwise. Variant sources
325
+ on the capture host become paths; broken links on the site become `publicUrl` links or paths, and the capture host is taken out of
326
+ broken-link and failed-shot error messages. (Links inside the pushed live HTML are cleaned at push time, not rewritten on serve.)
327
+
328
+ The board header links back to the project's console page for members. A viewer sees a note where Comment would be. When access ends
329
+ during a visit (a share link revoked or expired, the session ended, the account removed from the workspace), the board shows a banner
330
+ at the first refused request instead of failing quietly; opening a board you cannot reach shows the console's "You don't have access to
331
+ this board" page (still a 404), with "Sign in as someone else" and "Back to your workspaces". Guests' comments are text only: an
332
+ `@agent` in one is not a mention.
333
+
334
+ ## Agents
335
+
336
+ ```sh
337
+ export SHAPEWALL_TOKEN=swp_...
338
+ shapewall comments --remote https://app.example.com --json # same JSON as local; files are URLs
339
+ shapewall comments reply 4 --body "Fixed in #12" --remote https://app.example.com
340
+ shapewall comments resolve 4 --note "Bigger button" --ref https://github.com/acme/site/pull/12 --remote https://app.example.com
341
+ shapewall watch --remote https://app.example.com --mention agent --exec "my-agent"
342
+ shapewall mcp --remote https://app.example.com
343
+ ```
344
+
345
+ - `comments --remote` has every action the local one has (list, resolve, reopen, reply, status). `files.screenshot` and
346
+ `files.liveHtml` are download URLs on the token API.
347
+ - Guest comments (from share links) are opt-in everywhere an agent touches them: listing (`--include-guests`, `?guests=1`, the MCP
348
+ `includeGuests` argument) and acting on one (get, reply, status, resolve, reopen answer 403 `guest_comment` without it). The same
349
+ goes for a guest's reply under a member's comment: an agent never receives it unless it runs with `--include-guests`.
350
+ - `watch --remote` runs until Ctrl+C (exit 0). A token that is refused, lacks a scope, or a board or project that is gone stops it with
351
+ an error and a non-zero exit; network errors and restarts are retried. It polls every 3 seconds and claims each comment with a compare-and-set on the server, so several watchers on different
352
+ machines never take the same comment. With `--exec`, the comment's screenshot and live HTML are downloaded next to its JSON under
353
+ `.shapewall/remote/<project>/<board>/agent/`, so `SHAPEWALL_SCREENSHOT` is a local path as it is locally.
354
+ - `mcp --remote` is the stdio MCP server with the same tools as local minus `recapture_pages`. Tools that write appear only when the
355
+ token has the scope. In an MCP client config:
356
+
357
+ ```json
358
+ {
359
+ "mcpServers": {
360
+ "shapewall": {
361
+ "command": "npx",
362
+ "args": ["shapewall", "mcp", "--remote", "https://app.example.com"],
363
+ "env": { "SHAPEWALL_TOKEN": "swp_..." }
364
+ }
365
+ }
366
+ }
367
+ ```
368
+
369
+ Token API (`Authorization: Bearer swp_...`; cookies are ignored there): `GET /api/v1/project`, `GET /api/v1/boards/:board/pages`,
370
+ `GET /api/v1/boards/:board/comments?status=open|resolved|all&page=&mention=&guests=1`, `GET /api/v1/boards/:board/comments/:id`,
371
+ `GET /api/v1/boards/:board/files/:kind/:file`, `POST .../comments/:id/replies`, `POST .../comments/:id/agent-status`
372
+ (`{ agentStatus, onlyFrom }`), `POST .../comments/:id/resolve` (`{ note, fixRef, agentStatus }`), `POST .../comments/:id/reopen`,
373
+ and for push `POST /api/v1/pushes`, `PUT /api/v1/pushes/:id/files/:area/:name`, `POST /api/v1/pushes/:id/commit`.
374
+
375
+ Emoji reactions are for people: members and up toggle one with `POST /api/boards/:board/comments/:id/reactions`
376
+ (`{ emoji, replyId? }`, one of a fixed set of six) from the board. Viewers and guests cannot react (guests see counts only, never who
377
+ reacted), tokens have no reactions route and the token API leaves reactions out of what agents read. Reacting does not change a
378
+ comment's `updatedAt` or notify anyone.
379
+
380
+ ## Moving to a new origin
381
+
382
+ Passkeys belong to a host name (the RP ID), so changing the server's address would lock everyone out. To move:
383
+
384
+ 1. On the server's machine: `shapewall hosted move-origin --to https://new.example --data <dir> [--days N]` (1 to 30 days, default
385
+ 30). It records the move from the current origin and prints the next steps; `--status` shows it.
386
+ 2. Point the new host name at the server and restart it with `--origin https://new.example --previous-origin https://old.example`.
387
+ Passkeys made before the move keep their old RP ID (stored per passkey since migration 5).
388
+ 3. On the old address, signed-in people see "This server is moving". "Move my sign-in" (after a passkey check) makes a one-time move
389
+ link for their own account and opens `https://new.example/rebind#<token>`, where they create a passkey for the new host name and
390
+ are signed in. The token is 32 random bytes in the URL fragment (never in a log), stored as SHA-256, works once, only for the
391
+ account that made it, for 24 hours (never past the move's end), and a newer one voids it. Made in a fresh passkey session, the
392
+ new passkey has no 24-hour hold. Admins never move anyone else's sign-in.
393
+ 4. Someone who missed it signs in on the new address with their handle and a recovery code (codes have no host name) and adds a
394
+ passkey; the normal 24-hour hold applies.
395
+ 5. Best effort: the old address serves `/.well-known/webauthn` listing the new origin (WebAuthn Related Origin Requests), and the new
396
+ sign-in page offers "Use a passkey from old.example". Browsers that support it let an old passkey sign in on the new address;
397
+ the move link is the guarantee.
398
+
399
+ During the move the old address serves only sign-in, re-auth, the move page, the move link, the related-origins file, `/api/health`
400
+ and the token API (so CI tokens keep working); other writes answer 409 `server_moved` and every other page redirects (308) to the
401
+ same path on the new address. After the move ends it redirects reads; API and auth writes answer 409 `server_moved`.
402
+ Update `--remote` to the new address before the window ends. The CLI never forwards bearer tokens across an origin redirect.
403
+ Old-host passkeys show "For old.example" on the Account page.
404
+
405
+ ## Security model
406
+
407
+ - **Tenancy.** Every tenant row (workspaces, memberships, invites, projects, boards, comments, tokens, share links, pushes, audit) has
408
+ `workspace_id`, and every query on those tables goes through `tenant(db, workspaceId)` in `src/hosted/tenancy.js`. The handle binds
409
+ `:ws` itself, refuses SQL whose WHERE does not start with `workspace_id = :ws` or that has `OR`, `UNION` or a second statement (or
410
+ an INSERT that does not write `:ws`), and refuses missing parameters (which SQLite would otherwise bind as NULL). The only lookups that start without a workspace (a token or invite by its hash, a user's
411
+ workspaces) live in that file; a test fails if any other hosted module queries tenant tables through the raw handle. A workspace or
412
+ project you cannot see answers 404, never 403. Tests cover two workspaces with the same board id across the console API, the board
413
+ API, signed URLs and tokens.
414
+ - **CSRF.** Cookie-authenticated writes need JSON and an `Origin` (or `Sec-Fetch-Site: same-origin`) equal to the configured origin,
415
+ on top of SameSite=Lax. The token API ignores cookies.
416
+ - **Rate limits** (in memory, per process): passkey ceremonies 30 a minute per IP; wrong recovery codes 5 per 15 minutes per handle and
417
+ IP, and 30 an hour per IP (right codes do not count, and nobody can use up another address's attempts); invite lookups 30 a minute
418
+ per IP; bad tokens 20 a minute per IP; 1200 requests a minute per token; 20 pushes an hour per
419
+ token; share link previews and opens 30 a minute per IP, wrong passcodes as above for recovery codes, 600 guest requests a minute
420
+ per link, 30 guest comments an hour per link and IP; 600 public-project requests a minute per IP; 20 invite emails an hour per
421
+ workspace.
422
+ - **Audit log.** Account events (sign-up, sign-in by passkey or recovery code, failures, passkeys, recovery codes, sessions, deleted
423
+ workspaces) and workspace events (members, roles, invites, projects, tokens, share links and their guests, settings, pushes,
424
+ resolved and deleted comments), with the user, token or share link and IP. Admins read the workspace log in the console.
425
+ - **Headers.** `nosniff`, `no-referrer`, COOP same-origin, `X-Robots-Tag: noindex`, HSTS on https, a strict CSP on the console and the
426
+ board shell, `frame-ancestors 'none'` except for live HTML. The console has no inline script; its only inline styles are the ones
427
+ Radix adds for dialogs and menus, allowed by a per-response nonce (`style-src 'self' 'nonce-...'`). It renders every value as text
428
+ (React, no `dangerouslySetInnerHTML`).
429
+ - **DOM clobbering.** Live HTML keeps no `name` attributes (except `<meta name>`) and no `id` that matches a document or form method or
430
+ a document property the board reads; the board calls `Document.prototype` methods on the frame's document through `.call`.
431
+ - **Agents.** `watch --remote --exec` does not pass `SHAPEWALL_TOKEN` to the command (it reads untrusted comment text) unless you add
432
+ `--pass-token`, and checks project, board and comment ids before they become file names.
433
+ - **Behind a proxy.** `shapewall hosted` warns when the origin is https, it listens on loopback and `--trust-proxy` is off (rate limits
434
+ would see every client as the proxy).
435
+
436
+ ## Data and backups
437
+
438
+ ```
439
+ <data>/shapewall.db SQLite (WAL): accounts, workspaces, comments, tokens, audit
440
+ <data>/secret.key HMAC key for signed URLs
441
+ <data>/setup-link the first account's setup link (0600), until it is used
442
+ <data>/files/<ws>/<project>/<board>/ pushed captures, in the local layout
443
+ <data>/staging/<push>/ pushes in progress (swept after an hour)
444
+ ```
445
+
446
+ Use the operator commands below for a consistent database and file copy. Copying the SQLite file alone, or copying files after an
447
+ unlocked database snapshot, is not a complete backup of a board.
448
+
449
+ **Migrations** run at start (`src/hosted/db.js`, `PRAGMA user_version`); each is additive. Back up before upgrading.
450
+
451
+ - **4** (hosted QA fixes): `invites.note TEXT` (the invite's note) and `users.security_seen_at TEXT` (when the account last dismissed
452
+ the recovery-code notice). Rollback: an older build ignores both columns, so the simplest rollback is to run the older build on the
453
+ same file and set `PRAGMA user_version = 3` (it then skips nothing it knows). To drop them as well (SQLite 3.35+):
454
+ `ALTER TABLE invites DROP COLUMN note; ALTER TABLE users DROP COLUMN security_seen_at; PRAGMA user_version = 3;`. Notes and the
455
+ "seen" time are lost; nothing else depends on them.
456
+ - **5** (hosted access): tables `device_logins` (pending `shapewall login` codes, hashed, results sealed), `guest_sessions` (one row
457
+ per share link guest), `rebind_tokens` (move links, hashed) and `server_state` (the origin and a recorded move); columns
458
+ `workspaces.public_projects`, `projects.public_id` (unique), `public_at`, `public_by`, `passkeys.rp_id` (filled with the current
459
+ host name on first start) and `sessions.admin_seen_at`. Rollback: back up first. An older build ignores the new tables and columns,
460
+ but its guest cookies are a different format (guests open their link again), pending device logins are lost, and public projects
461
+ stop answering (their routes do not exist there). Run the older build on the same file while keeping `user_version = 5`;
462
+ lowering it without removing migration 5 would make the next upgrade try to add its schema twice. To drop
463
+ everything as well (SQLite 3.35+): `DROP TABLE device_logins; DROP TABLE guest_sessions; DROP TABLE rebind_tokens; DROP TABLE
464
+ server_state; DROP INDEX projects_public_id; ALTER TABLE projects DROP COLUMN public_id; ALTER TABLE projects DROP COLUMN
465
+ public_at; ALTER TABLE projects DROP COLUMN public_by; ALTER TABLE workspaces DROP COLUMN public_projects; ALTER TABLE passkeys
466
+ DROP COLUMN rp_id; ALTER TABLE sessions DROP COLUMN admin_seen_at; PRAGMA user_version = 4;`. Do not roll back during an origin
467
+ move: the old build cannot serve the old address.
468
+
469
+ **Why SQLite through `node:sqlite`.** One host, one process, small metadata (images are files), so SQLite fits. `node:sqlite` ships with
470
+ Node, so the npm package stays free of native addons for the many people who only use the CLI; `better-sqlite3` would download or build a
471
+ binary for every install. The cost is Node 22.13+ for the hosted server and an ExperimentalWarning on Node 22, which `shapewall hosted`
472
+ hides.
473
+
474
+ ## Before you invite the team
475
+
476
+ Try these on the real server, at its real address, before the team depends on it:
477
+
478
+ 1. **Reach the same HTTPS server from two team devices.** Tailscale grants network access; Shapewall accounts and workspace roles
479
+ grant application access. Keep sign-up invite-only, and allow only the intended peers in the tailnet policy. Leave Funnel off
480
+ for a private team pilot.
481
+ 2. **Create the owner account privately.** Read the one-time setup link locally, create a passkey and save recovery codes. Invite a
482
+ second person as a member and another as a viewer; verify the member can comment and the viewer cannot. Neither can administer
483
+ members or tokens. Test sign-out and return sign-in on the real desktop and phone, including any installed home-screen app.
484
+ 3. **Move and work on a real project.** Capture locally, use `shapewall share` or `login` plus `push`, then see comments and cursor
485
+ updates between two independently signed-in browsers. Check live HTML pins, follow/unfollow, mobile background/resume, and
486
+ re-capture plus push. The local project picker is desktop-only navigation, not a phone hub or a team workspace.
487
+ 4. **Verify the agent boundary.** Use a project-scoped token on the developer machine or CI. Confirm trusted dispatch and shell
488
+ approval work, imported/guest comments stay inert, and revocation ends access. The hosted server does not run your agent or capture browser.
489
+ 5. **Check operation and recovery.** Give the server a lifecycle independent of an interactive shell or coding-agent session. The
490
+ foreground command stops when its process stops; example service/Compose files need deliberate operator setup. Probe `/api/health`
491
+ from a second device, choose monitoring and backup arrangements, and restore a backup to a separate folder before relying on it.
492
+ Do not start two hosted processes against one data directory. Record the data and immutable release to use for rollback.
493
+ 6. **Try the passkeys your team uses.** Shapewall's tests use virtual authenticators, so check iCloud, Google or password-manager
494
+ sync, hardware keys and phone autofill yourself, whichever the team will rely on. Origin migration is optional
495
+ until the address changes, but preserve the old origin and recovery codes before attempting it.
496
+
497
+ A private tailnet server needs no separate usercontent domain and no public sign-up. Live HTML still uses an opaque sandbox and
498
+ signed, short-lived URLs. Decide retention and access before sharing sensitive work; the legal templates in `examples/hosted/legal`
499
+ are drafts for you to adapt, not terms anyone has agreed to.
500
+
501
+ ## Before public hosting
502
+
503
+ These are additional operator tasks when exposing the service beyond the private team:
504
+
505
+ - Configure a separate, cookieless registrable domain with `--usercontent-origin` for live HTML.
506
+ - Configure Turnstile when sign-up is open or comment links are widely distributed; keep invite-only sign-up until then.
507
+ - Set quotas, test suspension, and provision storage for the expected workload. Agent claim budgets are already implemented separately.
508
+ - Review and adopt the draft legal text with the actual operator, contacts, regions and retention periods. Workspace export is capped at 3.5 GB.
509
+ - Set up backups, monitoring and restore drills for the public deployment. Commands and disabled timer examples are supplied, not enabled automatically.
510
+ - Record an independent security review and HTTPS real-device passkey checks for the chosen public origin and proxy.
511
+
512
+ MCP over Streamable HTTP, SSE events, quotas and the workspace kill switch are already implemented. Object storage is a later scaling
513
+ option when one disk no longer fits. Signed live HTML URLs are bearer links for up to two minutes; revoking a share stops new loads,
514
+ while ending one guest session may leave an already-issued URL valid for the remainder of that window. Rate limits are per process.
515
+
516
+ ## Tailnet deployment (mode 1)
517
+
518
+ ```sh
519
+ shapewall hosted --data ./hosted-data --tailscale --tailscale-port 8443
520
+ # Alternative invocation with optional public guest access (not a second server):
521
+ shapewall hosted --data ./hosted-data --tailscale --tailscale-port 8443 --funnel --funnel-port 443
522
+ ```
523
+
524
+ These commands change Tailscale Serve/Funnel configuration. Run them only when you intend to expose this server. Install Tailscale,
525
+ connect the machine, enable MagicDNS and HTTPS certificates, and authorize your unprivileged user as a Tailscale operator first.
526
+ The console and passkey origin come from this machine's `*.ts.net` hostname. Do not also pass `--origin` or a non-loopback `--host`.
527
+ An occupied HTTPS port is refused, including an existing mapping to the same target. SIGINT/SIGTERM removes mappings this process
528
+ added only while they still match; after a crash inspect `tailscale serve status` and remove the stale mapping explicitly.
529
+
530
+ Funnel uses a second loopback listener and a different HTTPS port. It serves guest share pages, guest APIs, signed live HTML,
531
+ static assets, legal/report routes and health only. Console, sign-in, signup, device login, invitations, member APIs and token APIs
532
+ answer 404. Member session/ceremony cookies are discarded at that listener. Share links still require the secret in the link and
533
+ any passcode configured by the workspace. Funnel makes those guest paths public. Ports are not cookie boundaries, so never add
534
+ member routes to this listener. Tailscale policy/ACL configuration remains the operator's responsibility.
535
+
536
+ ## Own domain deployment (mode 2)
537
+
538
+ ```sh
539
+ shapewall hosted --setup --domain app.example.com \
540
+ --usercontent-domain usercontent.example.net --dir ./deployment --source ./shapewall
541
+ ```
542
+
543
+ This writes Compose, Caddy and a private `.env` file; it does not start containers or modify DNS. `--dry-run` previews the plan and
544
+ checks DNS. Point the names at the server, install Docker Engine and Compose, then review `.env` and Caddyfile. `--start` explicitly
545
+ builds and starts the Compose services and reads the first setup link privately from `/data/setup-link`. Never copy that link into
546
+ logs or monitoring. Manual equivalent: `docker compose up -d --build --wait`, then `docker compose exec shapewall cat /data/setup-link`.
547
+ W6's `hosted setup-link` command can rotate an expired link; use it locally with `--data /data` in the container.
548
+
549
+ The image is built from a checkout using `Dockerfile.hosted`. It contains no installed capture browser: users push captures from
550
+ local machines or CI. Data and backups are separate private mounts. Only Caddy publishes ports; the app trusts forwarded addresses
551
+ from the private Compose network. Review network access and secrets before production. The setup command needs a checkout with the
552
+ Dockerfile, client and lockfile; a packed npm installation must pass `--source` pointing to one.
553
+
554
+ Use a separate registrable domain for live HTML, not another subdomain of the app's domain. The usercontent Caddy site forwards
555
+ only `/uc/*`, discards incoming Cookie/Authorization and strips Set-Cookie. `--usercontent-origin` /
556
+ `SHAPEWALL_USERCONTENT_ORIGIN` support is required to issue URLs for that site; the template alone does not isolate same-origin HTML.
557
+ Staging stays gated and noindex; the commented Caddy gate example leaves guest routes outside the console gate intentionally.
558
+
559
+ ## Operator commands and quotas
560
+
561
+ Run these on the machine that holds the data, as the data owner:
562
+
563
+ ```sh
564
+ shapewall hosted admin list --data ./hosted-data
565
+ shapewall hosted admin suspend ws_ID --reason "Investigating an abuse report" --data ./hosted-data
566
+ shapewall hosted admin resume ws_ID --data ./hosted-data
567
+ shapewall hosted admin export ws_ID --out ./workspace.zip --data ./hosted-data
568
+ shapewall hosted admin reports --data ./hosted-data
569
+ shapewall hosted admin reports close rp_ID --note "Reviewed" --data ./hosted-data
570
+ shapewall hosted admin log --data ./hosted-data
571
+ # Destructive, requires the workspace's exact name:
572
+ shapewall hosted admin delete ws_ID --confirm "Workspace name" --data ./hosted-data
573
+ ```
574
+
575
+ Suspension immediately refuses existing API tokens, new device approvals, invitations and guest links. Members can read and export
576
+ but writes return `workspace_suspended`. Resume restores the previous grants. Operator actions, including listing workspaces/reports and reading the log, are recorded in the
577
+ operator log; suspension/resume also enter the workspace audit log. The CLI is privileged filesystem access, not a web-admin role.
578
+ Do not give an untrusted workspace owner shell access to it. Reports remain private to the server operator.
579
+
580
+ `--quotas FILE`, or `<data>/quotas.json`, controls storage, projects, boards per project, members, active share links per project and
581
+ pushes per token per hour. Defaults: 5 GiB, 20 projects, 10 boards/project, 100 members, 20 links/project and 20 pushes/hour/token.
582
+ Valid edits reload within 5 seconds; invalid edits preserve the previous limits and log a validation error. Example:
583
+
584
+ ```json
585
+ {
586
+ "default": { "projects": 20, "storageGB": 5 },
587
+ "workspaces": { "ws_000000000000000000000000": { "storageGB": 10, "members": 25 } }
588
+ }
589
+ ```
590
+
591
+ Lowering a quota blocks new growth; it does not delete existing data. `storageGB` is binary GiB (1024 cubed bytes). Agent claims/day
592
+ limits belong to the agent policy, not this config. Rate limits are in-memory and reset on process restart: the console and board
593
+ APIs 1200 requests a minute per account (6000 for captures and other files), session requests 600/minute, device polling 60/minute,
594
+ plus the limits listed above. Run one hosted process per data folder.
595
+
596
+ ## Retention, backup and restore
597
+
598
+ Current captures stay. By default retention keeps the newest two historical captures per page and viewport plus every historical
599
+ capture a comment references, open or resolved. Variants are left alone. It runs at start and every 6 hours in-process when the
600
+ operator starts the hosted server. `--retention-hours 0` disables it; `--retention-keep N` changes the default. To preview or run it:
601
+
602
+ ```sh
603
+ shapewall hosted admin retention --run --dry-run --data ./hosted-data
604
+ shapewall hosted admin retention --run --data ./hosted-data
605
+ shapewall hosted admin retention ws_ID --keep 4 --data ./hosted-data
606
+ shapewall hosted admin retention ws_ID --keep default --data ./hosted-data
607
+ shapewall hosted backup --data ./hosted-data --to ./backups --keep-days 30
608
+ shapewall hosted restore --from ./backups --check
609
+ shapewall hosted restore --from ./backups --data ./restored-new-folder
610
+ ```
611
+
612
+ Backup holds a SQLite write lock only for a `VACUUM INTO` snapshot and the list of board folders; captures are copied after it is
613
+ released, so reads and writes continue. A board pushed again while it is copied is copied again; boards and files deleted meanwhile
614
+ are skipped and listed under `files.skipped` in `backup.json`. The backup includes account data, passkey
615
+ public keys, captures, comments, audit records, signing key and default-path quota config. If the HMAC key is supplied as a systemd
616
+ credential or environment variable, give the backup command the same credential. Back up an external quota config separately.
617
+ Backup folders are mode 0700, files 0600, and checksums cover database/capture/key files. Treat them as sensitive as the live server,
618
+ encrypt offsite copies and test that you can recover them. Staging uploads and one-time setup links are excluded.
619
+
620
+ `--keep-days 30` deletes only recognizable older backup folders in the destination; it does not schedule anything. The example
621
+ backup service/timer is disabled until the operator explicitly installs and enables it. Installation never starts a backup timer.
622
+ A monthly manual restore drill should be logged by the operator. `restore --check` creates a scratch copy beside the backup, verifies
623
+ checksums, row counts, board folders and health, then stops its temporary server and removes the scratch copy. Automated tests also
624
+ sign in to a restored fixture with its software passkey; that does not verify real phones or hardware authenticators.
625
+
626
+ Restore refuses a nonempty target. Keep the original origin (passkeys depend on it), inspect the restored copy, then change the
627
+ runtime data pointer during an operator-approved maintenance window. Retain the previous release and data backup for rollback.
628
+ Project/workspace deletion removes active files immediately after database deletion; backup copies age out only under the chosen
629
+ backup policy. Operators must replay deletion requests after restoring an older backup.
630
+
631
+ ### Migration 7 and rollback
632
+
633
+ Migration 7 adds workspace suspension/retention columns, operator log and abuse reports. A `schema_migrations` ledger records each
634
+ actually-applied migration so reserved 5/6 can land later without being skipped by a higher `user_version`. Legacy versions 1-4
635
+ are adopted into the ledger. Empty reservations are never marked applied. Back up before any upgrade and do not run a build that
636
+ uses empty migration placeholders against retained data.
637
+
638
+ For rollback, prefer the pre-upgrade backup in a fresh data folder and the previous immutable release. Merely running an older build
639
+ on the new database ignores additive columns but also removes suspension enforcement: keep affected workspaces blocked externally
640
+ until upgraded again. Do not drop the operator log or reset the ledger casually. Test rollback on a copy first.
641
+
642
+ ## Secrets, logs and legal review
643
+
644
+ `SHAPEWALL_HOSTED_SECRET_FILE` and `RESEND_API_KEY_FILE` read private secret files. systemd `LoadCredential=shapewall-secret:...` and
645
+ `LoadCredential=resend-api-key:...` are read from `$CREDENTIALS_DIRECTORY`; explicit environment values take precedence. Setup links
646
+ are written to `<data>/setup-link` (0600) and not journaled. Caddy deletes Cookie, Authorization, Set-Cookie and signed `s` query
647
+ values from access logs. Invite/setup/share fragments are never sent in HTTP requests. App errors omit request values; email logs
648
+ contain status only. Do not enable debug request-body logging. Review any proxy/hosting logs outside these examples independently.
649
+
650
+ Fill `SHAPEWALL_HOSTED_TERMS_URL`, `_PRIVACY_URL`, `_AUP_URL`, `_SUBPROCESSORS_URL` and `_ABUSE_EMAIL` before inviting users. These
651
+ appear on sign-in/signup and guest pages, plus `/report`. The legal templates deliberately require an operator, contact, actual
652
+ hosting region, provider list and retention policy. Dan's review and any required counsel review remain release gates. No legal
653
+ text, Compose stack, Tailscale mapping, timer or staging deployment is activated by adding these files.
654
+
655
+ ### Scoped hosted agents
656
+
657
+ The server never runs a model or an agent process. Capture and execution stay
658
+ on the developer's machine or CI. In a project's console, **Agent policy**
659
+ sets trusted workspace roles or handles, board overrides, `onlyMentions`,
660
+ claims per UTC day (50 by default), and open claims (3 by default). Zero stops
661
+ new claims. Policy changes require a fresh passkey. Removed members and changed
662
+ trust policy invalidate vouches immediately.
663
+
664
+ Use project tokens with `read, reply, status, claim` for runners. `reply` posts
665
+ agent replies, `status` changes their status, and `claim` takes dispatched work.
666
+ `resolve` separately allows resolving/reopening; `push` uploads captures;
667
+ `import` is reserved for the local-to-shared bridge. Old `comment` tokens map
668
+ to `reply,status`, without acquiring `claim`. Give CI only `push` when it does
669
+ not need to read the project.
670
+
671
+ A trusted member's new comment is vouched for automatically. **Send to agent**
672
+ vouches for the exact current text and anchor. Editing clears it, and both
673
+ **Send to agent** and **Approve agent run** refuse a comment that was edited
674
+ after you opened it: reload and read it again. Only admins set an agent status
675
+ from the board. Approvals and denials of an agent's commands are in the audit
676
+ log. Non-admin
677
+ requests need **Approve agent run**, with a trusted admin's fresh passkey, by
678
+ default. Guest and agent-written comments can never be dispatched, including
679
+ with `--include-guests`. Imported comments start inert and need an explicit
680
+ trusted vouch. Claim tokens see only dispatched comments, including direct-id
681
+ reads; guest replies are removed from their responses. Read tokens without
682
+ `claim` may inspect untrusted comments with the existing guest opt-in.
683
+
684
+ Claims use an atomic per-project budget and compare-and-set. Exceeding a budget
685
+ returns HTTP 429 `agent_budget`; another token cannot take over a live claim.
686
+ An operator suspension, token revocation, membership loss, changed trust or an
687
+ edited comment prevents subsequent requests. Shell approvals bind one exact
688
+ command and one claim generation, expire after two minutes and need a trusted
689
+ admin's fresh passkey. They cannot be reused on a later run of identical text.
690
+
691
+ `shapewall watch --remote` uses bearer-authenticated SSE at `/api/v1/events`,
692
+ with bounded polling fallback when a proxy does not support streams. Events
693
+ contain project/board identifiers, never comment text. Revoking a token through
694
+ the server closes its streams immediately; out-of-process database changes are
695
+ rechecked at the 15-second heartbeat. Streams are process-local and have no
696
+ replay log, so clients always refetch authoritative state.
697
+
698
+ MCP clients can use Streamable HTTP at `/mcp` with an `Authorization: Bearer`
699
+ project token, supplied from a secret store or environment. Never put it in a
700
+ URL. This stateless endpoint refuses Cookie headers and foreign Origin headers;
701
+ there is no shared MCP session or account authority. The same scoped tool set
702
+ as `shapewall mcp --remote` is available. A project selector cannot override the
703
+ token's project. Rotate/revoke tokens from the project's console.
704
+
705
+ ### Move a local project to your team
706
+
707
+ Run `shapewall share --remote https://review.example.com` from the local project, or use **Profile > Share with your team...** through the
708
+ host's private settings link. Sign in on the destination's `/device` page, choose or create a project, and explicitly select **Import local
709
+ comments once**. Only workspace admins and owners can approve this grant. It starts unchecked and is removed when the move commits.
710
+ `shapewall share --remote URL --dry-run` reports counts without contacting the server. It cannot discover remote conflicts without a request.
711
+ Use `--board ID` for one board or `--no-comments` to push only captures, variants, history and journeys.
712
+
713
+ The move pushes the same stripped definition and capture allowlist as `push`, including board-created journeys. It imports comment and
714
+ reply history with remapped ids, anchors, state, agent status, resolution notes and reaction counts. Local display names receive an
715
+ `(imported)` label. They are plain text, never an attested account or handle; imported agent statuses and replies remain inert until a
716
+ trusted teammate explicitly sends the comment to an agent. Comments whose page disappeared remain stored as orphans with the reason
717
+ `page no longer on the board`. No agent settings, chat threads, keys, notification/GitHub configuration, paired devices, browser auth,
718
+ login scripts or page actions move.
719
+
720
+ Imports use batches of at most 200 comments and 1.8 MB below the endpoint's 2 MiB wire cap. Each batch and its idempotent retry result is
721
+ committed atomically. A final commit consumes the grant after all selected boards; retrying a lost final response is safe. Already imported
722
+ comments are skipped. A changed local comment updates an untouched remote copy. If the remote copy changed or was deleted, its version is
723
+ kept and the CLI lists the local ids and exits 2. It never merges text or silently overwrites a teammate's edits. Imports from two folders
724
+ remain distinct because only an opaque hash of the real project directory, board, local id and creation time identifies the source.
725
+
726
+ Finish or stop local agent/watch runs before a CLI move. The hosted copy preserves old `working` statuses as history; they do not represent an active hosted run. The host UI refuses a move while a local owner fix is running. Do not start a new local agent run while a move is in progress.
727
+
728
+ The local folder saves a private `remote/<origin-hash>/map.json` under its output directory (0600), containing ids and content hashes,
729
+ never credentials. Corrupt, unowned, publicly readable or symlinked maps are refused. Comments freeze under their normal write lock during
730
+ the move; failures restore the preceding local choice. A successful move displays the destination URL and defaults to read-only local
731
+ comments. The host can choose **Keep commenting here** to maintain an independent local copy. Captures and journeys stay writable, and
732
+ future captures continue through `shapewall push --remote URL`. This is a one-way move, not ongoing synchronization.
733
+
734
+ Reconnect the agent explicitly with `shapewall watch --remote URL --exec '<your-agent-command>'` or `shapewall mcp --remote URL`. Local agent
735
+ settings are never copied. Keep the remaining token scoped to the work that agent needs.
736
+
737
+ Migration 8 adds `device_logins.purpose`, the `import_author_kind`, `imported_by`, `imported_at`, `import_orphan`, `imported_reactions` comment columns, and the
738
+ `import_sessions`, `import_batches`, `comment_imports` tenant tables. Rollback requires restoring the pre-upgrade backup with the previous
739
+ release; do not discard imported comments or run an older server against the upgraded database.
740
+
741
+ ## Live presence
742
+
743
+ Hosted boards show who is viewing, cursors in canvas coordinates and an avatar button to follow another viewer's camera. Move your own
744
+ canvas or press **Stop following** to leave follow mode. Phone controls keep 44-pixel targets. A share-link visitor is always shown as
745
+ **Guest** in presence, regardless of the name on their comments. Public boards show a viewer count only: no names, cursors, camera
746
+ positions or comment events. Counts represent open connections, including multiple tabs.
747
+
748
+ Presence uses Yjs awareness over the same host's WebSocket, with no shared document or persisted cursor history. The server assigns
749
+ awareness ids, names and colours. Clients can send only bounded cursor/camera coordinates, viewport mode and an open-comment id; they
750
+ cannot send arbitrary awareness updates, choose an identity or join a different room. Rooms bind workspace, project and board. Member
751
+ sockets require a live account-session cookie; share sockets require that share's live guest cookie. API tokens do not authenticate.
752
+ The handshake requires the exact application Origin and Host. Usercontent and the previous-origin listener cannot join these sockets.
753
+
754
+ The limits are 30 incoming messages/second, 1 KB/frame and 50 connections/board and 500 connections across the shared server hub, with a 60-second idle timeout and a bounded send buffer.
755
+ Clients send coordinate updates at most 20 times/second. Each incoming frame rechecks the session, membership, project, board and
756
+ share/public switches. All connections are rechecked every five seconds, and recipients of comment invalidations are checked again
757
+ before delivery. Thus a revoked silent connection may receive cursor updates for at most five seconds; its next frame is refused
758
+ immediately. Recipient authorization is cached between sweeps for cursor fan-out, avoiding a database lookup for every recipient of
759
+ every pointer movement. Comment notifications carry only ids and make the client refetch through its normal authorized API.
760
+
761
+ The primary server and a configured Funnel guest listener share one in-process room hub and event bus. The guest listener accepts
762
+ only share-cookie sockets, and cannot upgrade a console/member/public route. Shutdown removes listeners, sockets and awareness timers.
763
+ Caddy and Tailscale Serve must forward WebSocket upgrades. Actual proxies, physical phones and background-mobile behavior still need
764
+ an operator smoke test. Cursor tracking pauses over an opaque live iframe while its text-selection interaction owns the pointer.