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.
- package/CHANGELOG.md +139 -0
- package/Dockerfile.agent +45 -0
- package/LICENSE +202 -0
- package/NOTICE +12 -0
- package/README.md +651 -2
- package/THIRD_PARTY.md +165 -0
- package/bin/shapewall.js +29 -0
- package/dist/agent/package-lock.json +8384 -0
- package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
- package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
- package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
- package/dist/client/assets/History-CEv6b-av.js +1 -0
- package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
- package/dist/client/assets/Management-DCfhcEUY.js +1 -0
- package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
- package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
- package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
- package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
- package/dist/client/assets/index-ByQRKVit.css +2 -0
- package/dist/client/assets/index-DweQ8Qtu.js +29 -0
- package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
- package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
- package/dist/client/assets/square-A8EnIYLR.js +1 -0
- package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
- package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
- package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
- package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
- package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
- package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
- package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
- package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
- package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
- package/dist/client/assets/ui-CLbws0rx.js +41 -0
- package/dist/client/build-info.json +1 -0
- package/dist/client/favicon.svg +7 -0
- package/dist/client/icons/apple-touch-icon.png +0 -0
- package/dist/client/icons/icon-192.png +0 -0
- package/dist/client/icons/icon-512.png +0 -0
- package/dist/client/icons/maskable-512.png +0 -0
- package/dist/client/index.html +25 -0
- package/dist/client/manifest.webmanifest +15 -0
- package/dist/client/sw.js +53 -0
- package/dist/client/theme-boot.js +27 -0
- package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
- package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
- package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
- package/dist/console/assets/console-C7uJLLOn.js +51 -0
- package/dist/console/assets/console-R8IBY3Am.css +2 -0
- package/dist/console/build-info.json +1 -0
- package/dist/console/console.html +21 -0
- package/dist/console/favicon.svg +7 -0
- package/dist/console/icons/apple-touch-icon.png +0 -0
- package/dist/console/icons/icon-192.png +0 -0
- package/dist/console/icons/icon-512.png +0 -0
- package/dist/console/icons/maskable-512.png +0 -0
- package/dist/console/manifest.webmanifest +15 -0
- package/dist/console/theme-boot.js +27 -0
- package/docs/agent-hardening.md +342 -0
- package/docs/agent-recipes.md +187 -0
- package/docs/agent-workflow.md +320 -0
- package/docs/agents.md +894 -0
- package/docs/architecture.md +242 -0
- package/docs/buzz.md +140 -0
- package/docs/capture-warnings.md +57 -0
- package/docs/config.md +489 -0
- package/docs/deployment.md +289 -0
- package/docs/design-system.md +162 -0
- package/docs/github.md +107 -0
- package/docs/hosted.md +764 -0
- package/docs/images/board-overview.png +0 -0
- package/docs/images/journeys.png +0 -0
- package/docs/images/live-comment.png +0 -0
- package/docs/images/phone-comment.png +0 -0
- package/docs/images/phone-overview.png +0 -0
- package/docs/images/variant.png +0 -0
- package/docs/interaction-audits.md +40 -0
- package/docs/journeys.md +137 -0
- package/docs/local-accounts.md +80 -0
- package/docs/notifications.md +237 -0
- package/docs/page-checks.md +69 -0
- package/docs/performance.md +174 -0
- package/docs/starter-agent.md +325 -0
- package/docs/updates.md +87 -0
- package/examples/audits/interaction.audit.json +17 -0
- package/package.json +132 -4
- package/src/accounts/avatar.js +121 -0
- package/src/accounts/local.js +464 -0
- package/src/agent/acp/command.js +204 -0
- package/src/agent/acp/detect.js +75 -0
- package/src/agent/acp/sandbox.js +160 -0
- package/src/agent/agent-health.js +75 -0
- package/src/agent/backends/acp.js +1297 -0
- package/src/agent/backends/index.js +61 -0
- package/src/agent/backends/openai.js +308 -0
- package/src/agent/composer.js +221 -0
- package/src/agent/config.js +338 -0
- package/src/agent/context.js +191 -0
- package/src/agent/control.js +122 -0
- package/src/agent/errors.js +17 -0
- package/src/agent/feedback-loop.js +137 -0
- package/src/agent/manage.js +94 -0
- package/src/agent/next-steps.js +51 -0
- package/src/agent/owner-mcp.js +38 -0
- package/src/agent/plain-text.js +52 -0
- package/src/agent/ratings-core.js +213 -0
- package/src/agent/ratings.js +100 -0
- package/src/agent/reply-text.js +67 -0
- package/src/agent/routes.js +1065 -0
- package/src/agent/run.js +326 -0
- package/src/agent/settings-routes.js +704 -0
- package/src/agent/showable.js +23 -0
- package/src/agent/starter/approvals.js +181 -0
- package/src/agent/starter/build-image.js +90 -0
- package/src/agent/starter/cli.js +163 -0
- package/src/agent/starter/disk.js +53 -0
- package/src/agent/starter/doctor.js +180 -0
- package/src/agent/starter/egress-proxy.js +351 -0
- package/src/agent/starter/gate.js +90 -0
- package/src/agent/starter/loop.js +114 -0
- package/src/agent/starter/model-relay.js +289 -0
- package/src/agent/starter/pause.js +14 -0
- package/src/agent/starter/probe.js +272 -0
- package/src/agent/starter/prompt.js +41 -0
- package/src/agent/starter/push-guard.js +146 -0
- package/src/agent/starter/rpc.js +164 -0
- package/src/agent/starter/runtime.js +287 -0
- package/src/agent/starter/sandbox-main.js +121 -0
- package/src/agent/starter/settings.js +290 -0
- package/src/agent/starter/source.js +69 -0
- package/src/agent/starter/supervisor.js +755 -0
- package/src/agent/starter/sweep.js +46 -0
- package/src/agent/starter/tools.js +524 -0
- package/src/agent/starter/watch.js +84 -0
- package/src/agent/starter/worktree.js +409 -0
- package/src/agent/text-diff.js +210 -0
- package/src/agent/thread-history.js +223 -0
- package/src/agent/threads.js +399 -0
- package/src/agent/tools.js +200 -0
- package/src/agent/turn-changes.js +424 -0
- package/src/agent/undo-state.js +26 -0
- package/src/agent/user-settings.js +308 -0
- package/src/auth/record.js +375 -0
- package/src/broken-links.js +164 -0
- package/src/buzz/client.js +75 -0
- package/src/buzz/config.js +151 -0
- package/src/buzz/environment.js +13 -0
- package/src/buzz/gateway.js +192 -0
- package/src/buzz/routes.js +61 -0
- package/src/buzz/signer-child.js +205 -0
- package/src/buzz/store.js +89 -0
- package/src/buzz/transport.js +60 -0
- package/src/buzz/verify.js +140 -0
- package/src/capture/actions.js +159 -0
- package/src/capture/capture.js +776 -0
- package/src/capture/dom-names.js +189 -0
- package/src/capture/element-map.js +509 -0
- package/src/capture/live.js +827 -0
- package/src/capture/media-scheme.js +317 -0
- package/src/capture/network-summary.js +86 -0
- package/src/capture/pacing.js +34 -0
- package/src/capture/requests.js +167 -0
- package/src/capture/sanitize.js +752 -0
- package/src/checks/accessibility.js +134 -0
- package/src/checks/budgets.js +58 -0
- package/src/checks/cli.js +55 -0
- package/src/checks/comparison.js +113 -0
- package/src/checks/environments.js +32 -0
- package/src/checks/flow-config.js +82 -0
- package/src/checks/flow-origin.js +53 -0
- package/src/checks/flows.js +398 -0
- package/src/checks/lighthouse-auth.js +145 -0
- package/src/checks/lighthouse-findings.js +130 -0
- package/src/checks/lighthouse.js +395 -0
- package/src/checks/robots.js +85 -0
- package/src/checks/routes.js +52 -0
- package/src/checks/run-control.js +259 -0
- package/src/checks/runner.js +724 -0
- package/src/checks/schema.js +133 -0
- package/src/checks/seo-analysis.js +443 -0
- package/src/checks/seo-probe.js +190 -0
- package/src/checks/seo-snapshot.js +99 -0
- package/src/checks/store.js +214 -0
- package/src/checks/transport.js +47 -0
- package/src/cli/args.js +319 -0
- package/src/cli/capture.js +79 -0
- package/src/cli/commands.js +92 -0
- package/src/cli/comments.js +84 -0
- package/src/cli/help.js +243 -0
- package/src/cli/init.js +214 -0
- package/src/cli/misc.js +64 -0
- package/src/cli/notify.js +87 -0
- package/src/cli/open.js +22 -0
- package/src/cli/serve.js +274 -0
- package/src/cli/variant.js +82 -0
- package/src/cli/watch.js +70 -0
- package/src/cli.js +130 -0
- package/src/comment-fields.js +76 -0
- package/src/comments-cli.js +208 -0
- package/src/config-reload.js +100 -0
- package/src/config.js +1061 -0
- package/src/devices-cli.js +21 -0
- package/src/diff.js +95 -0
- package/src/discover.js +284 -0
- package/src/doctor.js +295 -0
- package/src/event-log.js +268 -0
- package/src/events-cli.js +102 -0
- package/src/events.js +113 -0
- package/src/export.js +119 -0
- package/src/feedback.js +246 -0
- package/src/github.js +551 -0
- package/src/hosted/LICENSE.md +105 -0
- package/src/hosted/access-cli.js +78 -0
- package/src/hosted/admin.js +682 -0
- package/src/hosted/agent-approvals.js +163 -0
- package/src/hosted/agent-policy.js +189 -0
- package/src/hosted/app.js +510 -0
- package/src/hosted/auth-routes.js +540 -0
- package/src/hosted/auth.js +536 -0
- package/src/hosted/backup.js +483 -0
- package/src/hosted/board-context.js +35 -0
- package/src/hosted/board-routes.js +486 -0
- package/src/hosted/board-view.js +94 -0
- package/src/hosted/clean-worker.js +24 -0
- package/src/hosted/cleaner.js +89 -0
- package/src/hosted/comments.js +355 -0
- package/src/hosted/console-routes.js +401 -0
- package/src/hosted/cookies.js +18 -0
- package/src/hosted/crypto.js +80 -0
- package/src/hosted/db.js +496 -0
- package/src/hosted/device-routes.js +175 -0
- package/src/hosted/device.js +233 -0
- package/src/hosted/events.js +63 -0
- package/src/hosted/guards.js +172 -0
- package/src/hosted/guest-view.js +65 -0
- package/src/hosted/http.js +39 -0
- package/src/hosted/import.js +300 -0
- package/src/hosted/mail.js +73 -0
- package/src/hosted/mcp-http.js +71 -0
- package/src/hosted/membership.js +114 -0
- package/src/hosted/operator.js +478 -0
- package/src/hosted/ops-cli.js +345 -0
- package/src/hosted/pages.js +146 -0
- package/src/hosted/permissions.js +113 -0
- package/src/hosted/presence.js +372 -0
- package/src/hosted/projects.js +124 -0
- package/src/hosted/public.js +109 -0
- package/src/hosted/push.js +622 -0
- package/src/hosted/quotas.js +115 -0
- package/src/hosted/ratelimit.js +96 -0
- package/src/hosted/rebind.js +316 -0
- package/src/hosted/retention.js +128 -0
- package/src/hosted/server.js +260 -0
- package/src/hosted/setup-link.js +64 -0
- package/src/hosted/setup.js +323 -0
- package/src/hosted/shares.js +444 -0
- package/src/hosted/tailscale.js +204 -0
- package/src/hosted/tenancy.js +301 -0
- package/src/hosted/token-api.js +455 -0
- package/src/hosted/token-events.js +60 -0
- package/src/hosted/tokens.js +57 -0
- package/src/hosted/turnstile.js +49 -0
- package/src/hosted/usercontent.js +154 -0
- package/src/hosted/zip.js +155 -0
- package/src/invocation.js +58 -0
- package/src/journey-paths.js +282 -0
- package/src/journeys.js +189 -0
- package/src/links.js +106 -0
- package/src/local-projects.js +182 -0
- package/src/lock.js +193 -0
- package/src/mcp.js +417 -0
- package/src/mentions.js +151 -0
- package/src/net.js +15 -0
- package/src/notify/config.js +275 -0
- package/src/notify/index.js +301 -0
- package/src/notify/lease.js +73 -0
- package/src/notify/messages.js +212 -0
- package/src/notify/run.js +174 -0
- package/src/pixeldiff.js +49 -0
- package/src/png.js +143 -0
- package/src/reactions.js +111 -0
- package/src/remote/cli.js +133 -0
- package/src/remote/credentials.js +62 -0
- package/src/remote/ids.js +12 -0
- package/src/remote/login.js +155 -0
- package/src/remote/remote-mcp.js +237 -0
- package/src/remote/remote-watch.js +291 -0
- package/src/remote/remote.js +313 -0
- package/src/remote/share-state.js +78 -0
- package/src/remote/share.js +369 -0
- package/src/remote/terminal.js +13 -0
- package/src/serve-state.js +64 -0
- package/src/server/app.js +824 -0
- package/src/server/devices.js +186 -0
- package/src/server/local-console.js +28 -0
- package/src/server/local-user.js +59 -0
- package/src/server/pairing-routes.js +159 -0
- package/src/server/share-routes.js +89 -0
- package/src/server/tailscale.js +97 -0
- package/src/sitemap.js +431 -0
- package/src/store.js +983 -0
- package/src/tokens.js +11 -0
- package/src/update/routes.js +245 -0
- package/src/watch.js +403 -0
- 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.
|