shapewall 0.8.0 → 0.9.0

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 (76) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +5 -2
  3. package/bin/shapewall.js +2 -1
  4. package/dist/agent/package-lock.json +2 -2
  5. package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
  6. package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
  7. package/dist/client/assets/{History-C_NAxaRl.js → History-FzpzGmXZ.js} +1 -1
  8. package/dist/client/assets/{LocalSettings-W5Ze9ks7.js → LocalSettings-BGFl4VKr.js} +1 -1
  9. package/dist/client/assets/{Management-CXGSi6gI.js → Management-BGdmGtby.js} +1 -1
  10. package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
  11. package/dist/client/assets/{app-update-dialog-DNL0kP9U.js → app-update-dialog-BQxVHa5e.js} +1 -1
  12. package/dist/client/assets/index-B_m65HWT.css +2 -0
  13. package/dist/client/assets/{index-DTXjDgcg.js → index-C1ZwriJU.js} +19 -19
  14. package/dist/client/build-info.json +1 -1
  15. package/dist/client/index.html +2 -2
  16. package/dist/client/sw.js +2 -2
  17. package/dist/console/assets/{LocalAccountsApp-Z0gEJ74C.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
  18. package/dist/console/assets/{LocalConsole-DzHNISE9.js → LocalConsole-Rg-MTvSJ.js} +1 -1
  19. package/dist/console/assets/{app-update-dialog-CQsUPrMX.js → app-update-dialog-CEhV7th4.js} +1 -1
  20. package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
  21. package/dist/console/assets/console-BD5_Gha1.js +11 -0
  22. package/dist/console/assets/console-PWt8SxrJ.css +2 -0
  23. package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
  24. package/dist/console/assets/{tailnet-C2QPbIIC.js → tailnet-Cqtbptzq.js} +2 -2
  25. package/dist/console/assets/{usage-BDt6IQh1.js → usage-BCIwgDP9.js} +2 -2
  26. package/dist/console/build-info.json +1 -1
  27. package/dist/console/console.html +5 -5
  28. package/docs/README.md +64 -0
  29. package/docs/agent-hardening.md +3 -3
  30. package/docs/agent-recipes.md +3 -3
  31. package/docs/agent-workflow.md +6 -4
  32. package/docs/agents.md +25 -16
  33. package/docs/architecture.md +6 -1
  34. package/docs/config.md +53 -25
  35. package/docs/deployment.md +2 -2
  36. package/docs/github.md +1 -1
  37. package/docs/hosted.md +265 -70
  38. package/docs/local-accounts.md +1 -1
  39. package/docs/performance.md +3 -2
  40. package/docs/pull-requests.md +1 -1
  41. package/docs/starter-agent.md +4 -4
  42. package/docs/where-to-run.md +1 -1
  43. package/package.json +3 -2
  44. package/src/agent/backends/acp.js +39 -9
  45. package/src/capture/capture.js +35 -5
  46. package/src/capture/destination.js +67 -0
  47. package/src/capture/load-errors.js +82 -0
  48. package/src/checks/cli.js +41 -5
  49. package/src/cli/args.js +1 -0
  50. package/src/cli/capture.js +5 -0
  51. package/src/cli/comments.js +41 -3
  52. package/src/cli/help.js +4 -1
  53. package/src/cli/init.js +8 -4
  54. package/src/cli/misc.js +3 -3
  55. package/src/cli/serve.js +34 -6
  56. package/src/comment-fields.js +5 -0
  57. package/src/comments-cli.js +26 -5
  58. package/src/config-keys.js +191 -0
  59. package/src/config-reload.js +4 -1
  60. package/src/config.js +33 -2
  61. package/src/doctor.js +188 -39
  62. package/src/hosted/auth.js +14 -8
  63. package/src/hosted/db.js +50 -0
  64. package/src/hosted/pages.js +5 -1
  65. package/src/missing-package.js +11 -0
  66. package/src/ports.js +35 -0
  67. package/src/serve-state.js +16 -0
  68. package/src/watch.js +6 -0
  69. package/dist/client/assets/BoardChat-DG08cvD0.js +0 -27
  70. package/dist/client/assets/ChecksPanel-BD7GniTp.js +0 -1
  71. package/dist/client/assets/QuickConnect-Cta4dT3n.js +0 -1
  72. package/dist/client/assets/index-CBrmVq4n.css +0 -2
  73. package/dist/console/assets/app-version-CP0o1L1_.js +0 -1
  74. package/dist/console/assets/console-DIWY1goy.css +0 -2
  75. package/dist/console/assets/console-DYqhjwPS.js +0 -11
  76. package/dist/console/assets/local-agents-D7Jd9P7A.js +0 -6
package/docs/hosted.md CHANGED
@@ -25,25 +25,32 @@ SSRF surface. You capture on your machine or in CI (it can reach `localhost` and
25
25
  shapewall hosted --data /var/lib/shapewall-hosted --origin https://app.example.com --port 4700 --trust-proxy
26
26
  ```
27
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
- | `--tailnet-sign-in` | `SHAPEWALL_HOSTED_TAILNET_SIGN_IN=1` | off | With `--tailscale`: a tailnet user is signed in as the account linked to their tailnet login, no passkey ([Tailnet sign-in](#tailnet-sign-in)). Linux only |
41
- | `--tailnet-passkeys` | `SHAPEWALL_HOSTED_TAILNET_PASSKEYS=1` | off | With `--tailnet-sign-in`: also allow passkeys ([With passkeys also allowed](#with-passkeys-also-allowed)); `hosted admin passkeys on\|off` wins over it |
42
- | `--owners-see-sign-ins` | `SHAPEWALL_HOSTED_OWNERS_SEE_SIGN_INS=1` | off | Workspace owners see their members' sign-ins, passkey events and devices in Activity. For a server with one team ([Activity](#the-activity-page)) |
43
- | | `SHAPEWALL_TURNSTILE_SITE_KEY` | unset | With `SHAPEWALL_TURNSTILE_SECRET`: a Cloudflare Turnstile check on open sign-up and comment share links |
44
- | | `SHAPEWALL_TURNSTILE_SECRET` | unset | Turnstile secret key. Both keys or neither (one alone is a warning and stays off) |
45
-
46
- It needs Node 22.13 or newer (it uses the built-in `node:sqlite`). Passkeys need a secure context: `https://`, or `http://localhost`
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` or `=uniquelocal` | off; forced on by `--tailscale` | Client IPs from `X-Forwarded-For`. `1`: a proxy on this host. `uniquelocal`: a proxy on a private network, which is what the generated Compose file sets. `--tailscale` turns it on by itself ([what that means](#tailnet-deployment-mode-1)) |
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
+ | `--tailnet-sign-in` | `SHAPEWALL_HOSTED_TAILNET_SIGN_IN=1` | off | With `--tailscale`: a tailnet user is signed in as the account linked to their tailnet login, no passkey ([Tailnet sign-in](#tailnet-sign-in)). Linux only |
41
+ | `--tailnet-passkeys` | `SHAPEWALL_HOSTED_TAILNET_PASSKEYS=1` | off | With `--tailnet-sign-in`: also allow passkeys ([With passkeys also allowed](#with-passkeys-also-allowed)); `hosted admin passkeys on\|off` wins over it |
42
+ | `--owners-see-sign-ins` | `SHAPEWALL_HOSTED_OWNERS_SEE_SIGN_INS=1` | off | Workspace owners see their members' sign-ins, passkey events and devices in Activity. For a server with one team ([Activity](#the-activity-page)) |
43
+ | `--quotas FILE` | `SHAPEWALL_HOSTED_QUOTAS` | `<data>/quotas.json` | Storage and per-workspace limits ([Operator commands and quotas](#operator-commands-and-quotas)). The flag wins over the variable, and both over the file |
44
+ | | `SHAPEWALL_TURNSTILE_SITE_KEY` | unset | With `SHAPEWALL_TURNSTILE_SECRET`: a Cloudflare Turnstile check on open sign-up and comment share links |
45
+ | | `SHAPEWALL_TURNSTILE_SECRET` | unset | Turnstile secret key. Both keys or neither (one alone is a warning and stays off) |
46
+
47
+ **The switches above read only `1`.** `SHAPEWALL_HOSTED_TRUST_PROXY` (where `uniquelocal` is the one other accepted value),
48
+ `SHAPEWALL_HOSTED_OWNERS_SEE_SIGN_INS`, `SHAPEWALL_HOSTED_TAILNET_SIGN_IN` and `SHAPEWALL_HOSTED_TAILNET_PASSKEYS` compare the
49
+ value with the string `1` and nothing else. `=true`, `=on` and `=yes` leave the feature off, and nothing warns: a server meant to
50
+ have `SHAPEWALL_HOSTED_TAILNET_SIGN_IN=true` starts as an ordinary passkey server. Read the start log: it names the sign-in
51
+ ("Sign-in: your Tailscale account ...") only when tailnet sign-in really came on.
52
+
53
+ It needs Node 22.19 or newer, like the rest of Shapewall, and uses the built-in `node:sqlite`. Passkeys need a secure context: `https://`, or `http://localhost`
47
54
  for trying it on your own machine (`--origin http://localhost:4700`; not `127.0.0.1`, which is not a valid passkey RP ID).
48
55
 
49
56
  **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
@@ -233,9 +240,13 @@ How people get in:
233
240
  "Continue as ada@example.com" and links that login. From the command line:
234
241
  `shapewall hosted claim --data DIR --login LOGIN` on the server's machine ([From your coding agent](#from-your-coding-agent)).
235
242
  Opened from the server's own machine, the tailnet address links nothing: [why](#on-the-servers-own-machine).
236
- - **Someone the server does not know** sees "Ask an admin of a workspace here to invite ada@example.com", and nothing else. The
237
- admins of every workspace see them under Members, "Arrived through the tailnet", and can invite them with a role or take them
238
- off the list (kept 30 days, at most 200).
243
+ - **Someone the server does not know** sees "Ask an admin of a workspace here to invite ada@example.com", and nothing else, on an
244
+ invite-only server, which is the default (`--signup invite`). The admins of every workspace see them under Members, "Arrived
245
+ through the tailnet", and can invite them with a role or take them off the list (kept 30 days, at most 200).
246
+ - **With `--signup open` nobody waits for an invite.** A tailnet login the server does not know gets an account on arrival and a
247
+ new workspace of its own, which it owns, exactly as open sign-up does on any other server. Only the invite stage goes: the
248
+ account is still that one login's, and it is in no workspace of yours. Keep sign-up invite-only unless everyone your tailnet
249
+ reaches should be able to make a workspace here.
239
250
  - **An invite can be for one tailnet login** (Invite people, "Tailnet login"; `POST /invites` with `tailnetLogin`). Only that
240
251
  login can use it, whoever has the link. They join the next time they open the server, with the role of the invite.
241
252
  - **One login, one account.** (With passkeys allowed, an account that has a passkey links or unlinks its login on the
@@ -245,8 +256,12 @@ How people get in:
245
256
  Good to know:
246
257
 
247
258
  - **A tailnet session is bound to the identity.** It works only on requests that arrive as that login. Its cookie is worth
248
- nothing off the tailnet, on another person's device, or through Funnel. It is marked "Signed in by tailnet" in the device list,
249
- `via: tailnet` in the account's log, and `signedInBy: tailnet` on what it does in the workspace's audit log (Activity shows a
259
+ nothing off the tailnet, on another person's device, or through Funnel. It is held to Tailscale's own id of the user as well as
260
+ to the login, so a login handed to someone else later inherits neither the account nor its sessions: a request with the right
261
+ login behind another user id is nobody ([an account is held to the tailnet user](#on-the-servers-own-machine)). The cookie is
262
+ stored under the hash of `tailnet:<token>` rather than of the token alone, so a build without tailnet sign-in finds nothing for
263
+ it. It is marked "Signed in by tailnet" in the device list and in Account activity,
264
+ `via: tailnet` on its session and in the account's log, and `signedInBy: tailnet` on what it does in the workspace's audit log (Activity shows a
250
265
  "tailnet" mark).
251
266
  - **Signing out** keeps that browser signed out until you press "Continue as ada@example.com" on the sign-in page. Arriving again
252
267
  would otherwise sign you straight back in; the page says so.
@@ -659,7 +674,7 @@ Projects belong to a workspace, never to a person. Roles:
659
674
  | member | every project | + comment, reply, react, resolve, reopen; edit and delete their own comments |
660
675
  | 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 |
661
676
  | owner | every project | + change or remove admins and owners, invite owners, delete the workspace. A workspace always keeps one owner |
662
- | API token | one project | Its scopes (below): read, comment, resolve, push. Signed as the token, marked as an agent |
677
+ | API token | one project | Its scopes (below): `read`, `reply`, `status`, `claim`, `resolve`, `push`, `import`, `agent`. Signed as the token, marked as an agent |
663
678
  | 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 |
664
679
  | 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 |
665
680
 
@@ -676,7 +691,8 @@ it (admins and owners). The secret, the scopes and the expiry do not change; wha
676
691
  revoked token is not renamed; the audit log records `token_renamed` with both names. A token that may take work is an agent with an
677
692
  icon, a state and rules of its own: see [Agents on a hosted board](#agents-on-a-hosted-board).
678
693
 
679
- **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
694
+ **Invite links** hold a 32-byte token (stored hashed), a role, an expiry (the console offers 1, 3, 7, 14 or 30 days, 7 by
695
+ default; the operator's `hosted admin invites create --days N` takes any whole number from 1 to 30), and work once. Opening
680
696
  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
681
697
  URL fragment (`/invite#<token>`), and the setup link the same way (`/signup#setup=<code>`): browsers never send a fragment, so the token
682
698
  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
@@ -810,12 +826,19 @@ An admin creates a project and an **API token** for it (Workspace page, "API tok
810
826
  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
811
827
  project and has scopes:
812
828
 
813
- | Scope | Allows |
814
- | --------- | --------------------------------------------------------- |
815
- | `read` | Pages, comments, screenshots and live HTML of the project |
816
- | `comment` | Replies and agent status |
817
- | `resolve` | Resolve and reopen |
818
- | `push` | Upload captures |
829
+ | Scope | Allows |
830
+ | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
831
+ | `read` | Pages, comments, screenshots and live HTML of the project |
832
+ | `reply` | Replies |
833
+ | `status` | An agent status on a comment |
834
+ | `claim` | Take the comments sent to an agent. A token with it is an agent ([Agents on a hosted board](#agents-on-a-hosted-board)) |
835
+ | `resolve` | Resolve and reopen |
836
+ | `push` | Upload captures |
837
+ | `import` | The one-way move of a local project, granted only by a moving device login ([Move a local project](#move-a-local-project-to-your-team)) |
838
+ | `agent` | The link of a [connected agent](#connected-agents), granted only by approving `shapewall agent connect` |
839
+
840
+ `comment` is an older name and not a scope of its own: a token asked for it is made with `reply` and `status` instead, and gains
841
+ no `claim` ([Scoped hosted agents](#scoped-hosted-agents)).
819
842
 
820
843
  The CLI takes the token from `$SHAPEWALL_TOKEN` or `--token-file FILE`, never from a flag (other users can read a process's arguments),
821
844
  and sends it only over https (plain http only to this machine).
@@ -881,8 +904,9 @@ The server treats every upload as untrusted, even from our CLI:
881
904
  the project, its other boards, its tokens and its share links stay. A later push of the same board id starts a new board: the
882
905
  captures are back, the comments are not. The audit log records who removed which board, and people who have the board open are
883
906
  told at once (`board.removed` on the event stream). API: `DELETE /api/workspaces/:ws/projects/:pid/boards/:bid`.
884
- - 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
885
- 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
907
+ - Limits: 5000 files and 1 GB per push and 500 pages per board, which are fixed; and, by default, 10 boards per project (checked
908
+ again at commit), 20 pushes per hour per token and 5 GiB per workspace (committed boards plus open pushes), which are quotas the
909
+ operator can raise or lower ([Operator commands and quotas](#operator-commands-and-quotas)). A push is open for an hour; after that it takes no more files and
886
910
  a sweep (at start and every 10 minutes) removes its staging folder, staging folders without a push, and board folders a commit left
887
911
  behind.
888
912
 
@@ -900,7 +924,8 @@ fresh redirect. Guest URLs are bound to their share link and checked again on ev
900
924
  board API, which the server validates field by field on push, including its viewport dimensions (3 MB, at most 8000 elements).
901
925
 
902
926
  For a separate cookieless domain, run `shapewall hosted --origin https://app.example.com --usercontent-origin https://example-content.net`
903
- (or set `SHAPEWALL_USERCONTENT_ORIGIN`). Point both host names at this server through your TLS proxy, preserving Host. The content origin
927
+ (or set `SHAPEWALL_USERCONTENT_ORIGIN`, for which `SHAPEWALL_HOSTED_USERCONTENT_ORIGIN` is an accepted second name). Point both
928
+ host names at this server through your TLS proxy, preserving Host. The content origin
904
929
  serves only signed `/uc/` routes, ignores cookies and never sets one; the app origin refuses `/uc/`. Its CSP permits only the app origin
905
930
  to frame documents. Use a separate registrable domain for a separate site; a second port or subdomain alone is a different origin, and
906
931
  the opaque sandbox remains the main boundary. Separate usercontent must be https when the app is https.
@@ -1118,7 +1143,7 @@ asks for is not enough when it does not ask.
1118
1143
 
1119
1144
  The same rule holds for an agent saved on the machine: it can be connected only when its command starts Claude Code. For Codex,
1120
1145
  goose and Gemini CLI, `shapewall watch --remote` stays the way to work on a hosted board. How the check was done is in
1121
- [agent-hardening.md](agent-hardening.md#connected-agents).
1146
+ [the agent hardening guide](agent-hardening.md#connected-agents).
1122
1147
 
1123
1148
  The same test decided what a fix session gets. A Claude Code session for a fix has its reading tools and its editing tools, and
1124
1149
  no shell tool: started with the shell tool, Claude Code ran commands it takes to be read-only (`ls`, `cat`) without asking anyone,
@@ -1147,7 +1172,7 @@ keeps what was set. They are explained under [Switching edits on](#switching-edi
1147
1172
  `shapewall --help` and is refused for Claude Code ([Commands](#commands-are-not-offered-for-claude-code)).
1148
1173
 
1149
1174
  - **Which program runs** is the machine's choice: an agent saved for this project on that machine, or Claude Code found on its
1150
- `PATH` with its ACP adapter, the same detection a local board uses ([agents.md](agents.md)). Codex, goose, Gemini CLI, a saved
1175
+ `PATH` with its ACP adapter, the same detection a local board uses ([chat with an agent](agents.md)). Codex, goose, Gemini CLI, a saved
1151
1176
  agent that runs one of them, a program Shapewall does not know and a model endpoint are all refused with a message. Nothing the
1152
1177
  server sends names a command, an argument, a folder or an environment variable.
1153
1178
  - **`--audience owner` trusts the server's label.** The machine cannot check who really asked: it sees only what the server says
@@ -1367,7 +1392,7 @@ gone are removed with their records, so their branch names are free again. Ctrl+
1367
1392
 
1368
1393
  If files in the person's own checkout changed while the fix ran, the thread says so: "Files in the agent's own checkout changed
1369
1394
  during this fix. Check git status on its machine." Shapewall does not sandbox the agent's own tools
1370
- ([agent-hardening.md](agent-hardening.md#connected-agents)).
1395
+ ([the agent hardening guide](agent-hardening.md#connected-agents)).
1371
1396
 
1372
1397
  ### Files that run something
1373
1398
 
@@ -1481,7 +1506,7 @@ An edit that went without asking is still a card in the thread, marked "Allowed
1481
1506
  - **No commands for Claude Code.** Its fix session has no shell tool.
1482
1507
  - **The agent never holds its token.** Its process gets a small environment with no `SHAPEWALL_*` variable.
1483
1508
 
1484
- What the machine cannot do is in [agent-hardening.md](agent-hardening.md#connected-agents): it does not sandbox the agent's own
1509
+ What the machine cannot do is in [the agent hardening guide](agent-hardening.md#connected-agents): it does not sandbox the agent's own
1485
1510
  tools, and with approvals on, a server that was broken into can forge an "allow" for an edit the agent really asked.
1486
1511
 
1487
1512
  ### When a connected agent is offline
@@ -1615,7 +1640,7 @@ Edit, Write and MultiEdit beside Read, Grep and Glob. It has no settings files,
1615
1640
  bypass. Each edit it makes asks first, and the request goes through the machine's checks and a card
1616
1641
  ([Permission cards](#permission-cards)). Chat turns on the same machine keep the read-only session.
1617
1642
 
1618
- This was shown on one machine with one adapter version ([agent-hardening.md](agent-hardening.md#connected-agents) says how). It
1643
+ This was shown on one machine with one adapter version ([the agent hardening guide](agent-hardening.md#connected-agents) says how). It
1619
1644
  is still a good idea to give a connected agent a profile of its own: a separate config folder, logged in for this purpose.
1620
1645
 
1621
1646
  ### Chat usage records and the audit log
@@ -1856,7 +1881,8 @@ member who filters by someone else gets an empty answer, not that person's rows.
1856
1881
 
1857
1882
  `/w/<workspace>/activity`. What people did, newest first, from the audit log: sign-in and sign-out, passkeys and sessions, members
1858
1883
  and invites, settings (with the value before and after), projects and pushes, share links and guests, tokens, agents (connected,
1859
- audience, approval rule, revoked), approval cards (who allowed or denied what), agent work, and exports. Filter by person, kind of
1884
+ audience, approval rule, revoked), approval cards (who allowed or denied what), agent work, comments (resolved, reopened and deleted) and
1885
+ exports. Filter by person, kind of
1860
1886
  action, agent, project, where it came through (a person, a token, a share link guest, the server) and period; search; open an
1861
1887
  entry for the address and device it came from and exactly what was recorded. "Worth a look" keeps the security-relevant changes:
1862
1888
  roles, audiences, approval rules, the agent policy, share links switched on, a project made public, tokens made, passkeys
@@ -1988,7 +2014,7 @@ Old-host passkeys show "For old.example" on the Account page.
1988
2014
  workspace.
1989
2015
  - **Audit log.** Account events (sign-up, sign-in by passkey or recovery code, failures, passkeys, recovery codes, sessions, deleted
1990
2016
  workspaces) and workspace events (members, roles, invites, projects, tokens, share links and their guests, settings, pushes,
1991
- resolved and deleted comments), with the user, token or share link and IP. Admins read the workspace log in the console.
2017
+ resolved, reopened and deleted comments), with the user, token or share link and IP. Admins read the workspace log in the console.
1992
2018
  - **Headers.** `nosniff`, `no-referrer`, COOP same-origin, `X-Robots-Tag: noindex`, HSTS on https, a strict CSP on the console and the
1993
2019
  board shell, `frame-ancestors 'none'` except for live HTML. The console has no inline script; its only inline styles are the ones
1994
2020
  Radix adds for dialogs and menus, allowed by a per-response nonce (`style-src 'self' 'nonce-...'`). It renders every value as text
@@ -2005,6 +2031,7 @@ Old-host passkeys show "For old.example" on the Account page.
2005
2031
  ```
2006
2032
  <data>/shapewall.db SQLite (WAL): accounts, workspaces, comments, tokens, audit
2007
2033
  <data>/secret.key HMAC key for signed URLs
2034
+ <data>/quotas.json the operator's quotas, when there is one (or `--quotas FILE`)
2008
2035
  <data>/setup-link the first account's setup link (0600), until it is used
2009
2036
  <data>/files/<ws>/<project>/<board>/ pushed captures, in the local layout
2010
2037
  <data>/staging/<push>/ pushes in progress (swept after an hour)
@@ -2013,29 +2040,47 @@ Old-host passkeys show "For old.example" on the Account page.
2013
2040
  Use the operator commands below for a consistent database and file copy. Copying the SQLite file alone, or copying files after an
2014
2041
  unlocked database snapshot, is not a complete backup of a board.
2015
2042
 
2016
- **Migrations** run at start (`src/hosted/db.js`, `PRAGMA user_version`); each is additive. Back up before upgrading.
2043
+ **Migrations** run at start (`src/hosted/db.js`, `PRAGMA user_version` and the `schema_migrations` ledger); each is additive
2044
+ except 18, which rebuilds `sessions` ([Migration 18 and rollback](#migration-18-and-rollback)). Back up before upgrading.
2017
2045
 
2018
2046
  - **4** (hosted QA fixes): `invites.note TEXT` (the invite's note) and `users.security_seen_at TEXT` (when the account last dismissed
2019
2047
  the recovery-code notice). Rollback: an older build ignores both columns, so the simplest rollback is to run the older build on the
2020
- same file and set `PRAGMA user_version = 3` (it then skips nothing it knows). To drop them as well (SQLite 3.35+):
2021
- `ALTER TABLE invites DROP COLUMN note; ALTER TABLE users DROP COLUMN security_seen_at; PRAGMA user_version = 3;`. Notes and the
2022
- "seen" time are lost; nothing else depends on them.
2048
+ same file and change nothing else. Setting `PRAGMA user_version` by hand does nothing here: what runs is decided by the
2049
+ `schema_migrations` ledger, and the server writes `user_version` back from it at every start. To drop the columns as well
2050
+ (SQLite 3.35+), with the server stopped: `ALTER TABLE invites DROP COLUMN note; ALTER TABLE users DROP COLUMN
2051
+ security_seen_at; DELETE FROM schema_migrations WHERE version = 4; PRAGMA user_version = 3;`. The `DELETE` is the part that
2052
+ matters: without it the ledger still says migration 4 ran, so the next upgrade does not add the columns back and the newer
2053
+ build runs against a database that no longer has them. Notes and the "seen" time are lost; nothing else depends on them.
2023
2054
  - **5** (hosted access): tables `device_logins` (pending `shapewall login` codes, hashed, results sealed), `guest_sessions` (one row
2024
2055
  per share link guest), `rebind_tokens` (move links, hashed) and `server_state` (the origin and a recorded move); columns
2025
2056
  `workspaces.public_projects`, `projects.public_id` (unique), `public_at`, `public_by`, `passkeys.rp_id` (filled with the current
2026
2057
  host name on first start) and `sessions.admin_seen_at`. Rollback: back up first. An older build ignores the new tables and columns,
2027
2058
  but its guest cookies are a different format (guests open their link again), pending device logins are lost, and public projects
2028
- stop answering (their routes do not exist there). Run the older build on the same file while keeping `user_version = 5`;
2029
- lowering it without removing migration 5 would make the next upgrade try to add its schema twice. To drop
2030
- everything as well (SQLite 3.35+): `DROP TABLE device_logins; DROP TABLE guest_sessions; DROP TABLE rebind_tokens; DROP TABLE
2031
- server_state; DROP INDEX projects_public_id; ALTER TABLE projects DROP COLUMN public_id; ALTER TABLE projects DROP COLUMN
2032
- public_at; ALTER TABLE projects DROP COLUMN public_by; ALTER TABLE workspaces DROP COLUMN public_projects; ALTER TABLE passkeys
2033
- DROP COLUMN rp_id; ALTER TABLE sessions DROP COLUMN admin_seen_at; PRAGMA user_version = 4;`. Do not roll back during an origin
2034
- move: the old build cannot serve the old address.
2059
+ stop answering (their routes do not exist there). Run the older build on the same file and leave the version alone:
2060
+ `user_version` is not what decides what runs, the `schema_migrations` ledger is, and the server writes `user_version` back from
2061
+ it at every start. To drop everything as well (SQLite 3.35+), with the server stopped: `DROP TABLE device_logins; DROP TABLE
2062
+ guest_sessions; DROP TABLE rebind_tokens; DROP TABLE server_state; DROP INDEX projects_public_id; ALTER TABLE projects DROP
2063
+ COLUMN public_id; ALTER TABLE projects DROP COLUMN public_at; ALTER TABLE projects DROP COLUMN public_by; ALTER TABLE workspaces
2064
+ DROP COLUMN public_projects; ALTER TABLE passkeys DROP COLUMN rp_id; ALTER TABLE sessions DROP COLUMN admin_seen_at; DELETE FROM
2065
+ schema_migrations WHERE version = 5; PRAGMA user_version = 4;`. Without that `DELETE` the ledger still says migration 5 ran, so
2066
+ the next upgrade does not recreate any of it and the newer build runs against missing tables and columns. Do this only on a
2067
+ database whose newest migration is 5: later migrations add to what this one made (8 adds `device_logins.purpose`), and
2068
+ re-running 5 does not bring those additions back. Do not roll back during an origin move: the old build cannot serve the old
2069
+ address.
2035
2070
  - **12** (agents, 0.4.0): tables `agents` and `agent_runs`, columns `projects.default_agent_id`, `comments.agent_id` and
2036
2071
  `agent_claims.agent_id`, and a backfill that turns every token with the `claim` scope into an agent that behaves as before. What a
2037
2072
  rollback loses is in [Migration 12 and rollback](#migration-12-and-rollback).
2038
2073
 
2074
+ **That is not every migration.** There are 17, numbered 1 to 17, and they all run at start. The ones with a rollback note are 4
2075
+ and 5 above; 7, in [Migration 7 and rollback](#migration-7-and-rollback); 8, one paragraph under
2076
+ [Move a local project to your team](#move-a-local-project-to-your-team); 12, and then one section each for 13, 14, 15, 16 and 17
2077
+ below. **Migrations 1, 2, 3, 6, 9, 10 and 11 have no rollback note anywhere:** 1 to 3 are the first schema and its early
2078
+ additions; 6 is scoped dispatch, project budgets and command approvals; 9 is profile images; 10 is `shares.include_checks`; 11 is
2079
+ comment and reply images and drawings, whose bytes live in `comment_files`. No recipe for them is written down, and this page does
2080
+ not invent one. What holds for all of them: an older build ignores additive tables and columns, the pre-upgrade backup in a fresh
2081
+ data folder is the rollback to prefer, and any hand rollback that drops a migration's schema must delete that migration's row
2082
+ from `schema_migrations` too, as the recipes below do.
2083
+
2039
2084
  **Why SQLite through `node:sqlite`.** One host, one process, small metadata (images are files), so SQLite fits. `node:sqlite` ships with
2040
2085
  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
2041
2086
  binary for every install. The cost is Node 22.13+ for the hosted server and an ExperimentalWarning on Node 22, which `shapewall hosted`
@@ -2095,11 +2140,24 @@ shapewall hosted --data ./hosted-data --tailscale --tailscale-port 8443 --funnel
2095
2140
 
2096
2141
  These commands change Tailscale Serve/Funnel configuration. Run them only when you intend to expose this server. Install Tailscale,
2097
2142
  connect the machine, enable MagicDNS and HTTPS certificates, and authorize your unprivileged user as a Tailscale operator first.
2143
+ That last step hands out real trust: the Tailscale operator can change the serve config, and with it pretend to be anyone on a
2144
+ tailnet sign-in server, so grant it only to a user you trust as you trust root there
2145
+ ([what is still trusted](#how-the-server-knows-a-request-came-through-tailscale-serve)). Rewriting the serve config under a
2146
+ running server does not stay unnoticed: the server reads it again every 30 seconds and suspends tailnet sign-in until it is the
2147
+ one entry it made.
2098
2148
  Add `--tailnet-sign-in` to sign tailnet users in by their tailnet login instead of a passkey ([Tailnet sign-in](#tailnet-sign-in)).
2099
2149
  The console and passkey origin come from this machine's `*.ts.net` hostname. Do not also pass `--origin` or a non-loopback `--host`.
2100
2150
  An occupied HTTPS port is refused, including an existing mapping to the same target. SIGINT/SIGTERM removes mappings this process
2101
2151
  added only while they still match; after a crash inspect `tailscale serve status` and remove the stale mapping explicitly.
2102
2152
 
2153
+ **`--tailscale` turns `--trust-proxy` on by itself,** because `tailscale serve` is the proxy in front of the server. Client IPs for
2154
+ rate limits, the audit log and the device list then come from `X-Forwarded-For`. With `--tailnet-sign-in` that header is believed
2155
+ only behind the checks of [Tailnet sign-in](#how-the-server-knows-a-request-came-through-tailscale-serve) (the secret path, a
2156
+ root-owned peer, tailscaled's own whois), so who someone is stays sound. With plain `--tailscale` and no `--tailnet-sign-in`
2157
+ there are no such checks: any program on this machine can open the loopback port and set `X-Forwarded-For` to what it likes, so
2158
+ the addresses in the audit log and the per-address rate limits are that program's to choose. Sign-in itself is not affected, being
2159
+ a passkey either way, but do not read an address in such a server's log as proof of where a request came from.
2160
+
2103
2161
  Funnel uses a second loopback listener and a different HTTPS port. It serves guest share pages, guest APIs, signed live HTML,
2104
2162
  static assets, legal/report routes and health only. Console, sign-in, signup, device login, invitations, member APIs and token APIs
2105
2163
  answer 404. Member session/ceremony cookies and any `Tailscale-*` header are discarded at that listener. Share links still require the secret in the link and
@@ -2119,6 +2177,15 @@ builds and starts the Compose services and reads the first setup link privately
2119
2177
  logs or monitoring. Manual equivalent: `docker compose up -d --build --wait`, then `docker compose exec shapewall cat /data/setup-link`.
2120
2178
  W6's `hosted setup-link` command can rotate an expired link; use it locally with `--data /data` in the container.
2121
2179
 
2180
+ **What is in that `.env`, besides the settings of this page.** Three variables there are read by Docker Compose itself, not by the
2181
+ server: `SHAPEWALL_SOURCE` (the build context, the checkout the image is built from), `SHAPEWALL_UID` and `SHAPEWALL_GID` (the
2182
+ user and group the container runs as, which must own the `data` and `backups` mounts; 1000 and 1000 when they are unset). The
2183
+ setup command writes all three. Changing them changes the stack, not a running server.
2184
+
2185
+ **Two settings cannot be changed in that `.env`.** The generated Compose file puts `SHAPEWALL_HOSTED_DATA: /data` and
2186
+ `SHAPEWALL_HOSTED_TRUST_PROXY: uniquelocal` in its own `environment:` block, and a Compose `environment:` entry wins over
2187
+ `env_file`. Setting either in `.env` under the generated stack has no effect; edit the Compose file if you must change them.
2188
+
2122
2189
  The image is built from a checkout using `Dockerfile.hosted`. It contains no installed capture browser: users push captures from
2123
2190
  local machines or CI. Data and backups are separate private mounts. Only Caddy publishes ports; the app trusts forwarded addresses
2124
2191
  from the private Compose network. Review network access and secrets before production. The setup command needs a checkout with the
@@ -2131,7 +2198,9 @@ Staging stays gated and noindex; the commented Caddy gate example leaves guest r
2131
2198
 
2132
2199
  ## Operator commands and quotas
2133
2200
 
2134
- Run these on the machine that holds the data, as the data owner:
2201
+ These are the server-wide commands. `admin members`, `admin invites` and `admin projects`, which do for the operator what an owner
2202
+ would do in the console, are under [On the server's own machine](#on-the-servers-own-machine). Run these on the machine that holds
2203
+ the data, as the data owner:
2135
2204
 
2136
2205
  ```sh
2137
2206
  shapewall hosted admin list --data ./hosted-data
@@ -2160,7 +2229,8 @@ but writes return `workspace_suspended`. Resume restores the previous grants. Op
2160
2229
  operator log; suspension/resume also enter the workspace audit log. The CLI is privileged filesystem access, not a web-admin role.
2161
2230
  Do not give an untrusted workspace owner shell access to it. Reports remain private to the server operator.
2162
2231
 
2163
- `--quotas FILE`, or `<data>/quotas.json`, controls storage, projects, boards per project, members, active share links per project and
2232
+ `--quotas FILE`, `SHAPEWALL_HOSTED_QUOTAS` or `<data>/quotas.json` (the flag wins over the variable, and both over the file in the
2233
+ data folder) controls storage, projects, boards per project, members, active share links per project and
2164
2234
  pushes per token per hour. Defaults: 5 GiB, 20 projects, 10 boards/project, 100 members, 20 links/project and 20 pushes/hour/token.
2165
2235
  Valid edits reload within 5 seconds; invalid edits preserve the previous limits and log a validation error. Example:
2166
2236
 
@@ -2173,14 +2243,15 @@ Valid edits reload within 5 seconds; invalid edits preserve the previous limits
2173
2243
 
2174
2244
  Lowering a quota blocks new growth; it does not delete existing data. `storageGB` is binary GiB (1024 cubed bytes). Agent claims/day
2175
2245
  limits belong to the agent policy, not this config. Rate limits are in-memory and reset on process restart: the console and board
2176
- APIs 1200 requests a minute per account (6000 for captures and other files), session requests 600/minute, device polling 60/minute,
2177
- plus the limits listed above. Run one hosted process per data folder.
2246
+ APIs 1200 requests a minute per account (6000 for captures and other files), guest requests 600 a minute per share link and IP,
2247
+ public-project requests 600 a minute per IP, device polling 60/minute, plus the limits listed above. Run one hosted process per data folder.
2178
2248
 
2179
2249
  ## Retention, backup and restore
2180
2250
 
2181
2251
  Usage records (one small row per agent turn) are kept for 400 days unless a workspace has its own `--usage-days`; see
2182
2252
  [Retention, quota and export](#retention-quota-and-export). Current captures stay. By default retention keeps the newest two historical captures per page and viewport plus every historical
2183
- capture a comment references, open or resolved. Variants are left alone. It runs at start and every 6 hours in-process when the
2253
+ capture a comment references, open or resolved, and every version a reply's drawing was made on, so that markup keeps rendering.
2254
+ Variants are left alone. It runs at start and every 6 hours in-process when the
2184
2255
  operator starts the hosted server. `--retention-hours 0` disables it; `--retention-keep N` changes the default. To preview or run it:
2185
2256
 
2186
2257
  ```sh
@@ -2196,9 +2267,15 @@ shapewall hosted restore --from ./backups --data ./restored-new-folder
2196
2267
 
2197
2268
  Backup holds a SQLite write lock only for a `VACUUM INTO` snapshot and the list of board folders; captures are copied after it is
2198
2269
  released, so reads and writes continue. A board pushed again while it is copied is copied again; boards and files deleted meanwhile
2199
- are skipped and listed under `files.skipped` in `backup.json`. The backup includes account data, passkey
2270
+ are skipped and listed under `files.skipped` in `backup.json`. Anything written after the snapshot is not in the backup: it is a
2271
+ copy of a moment, not a continuous log. A `--to` inside the data folder is refused. The backup includes account data, passkey
2200
2272
  public keys, captures, comments, audit records, signing key and default-path quota config. If the HMAC key is supplied as a systemd
2201
- credential or environment variable, give the backup command the same credential. Back up an external quota config separately.
2273
+ credential or environment variable, give the backup command the same credential: with `SHAPEWALL_HOSTED_SECRET` in the
2274
+ environment the backup writes that value into `<backup>/secret.key` in plain text, and restore copies it into the restored data
2275
+ folder, so a backup is as secret as the key. When no key is found in the environment and the data folder has no `secret.key`
2276
+ either, `backup.json` simply records `"secret": false` and nothing warns: check that field, because a restore without the key
2277
+ makes a new one on first start and the live-HTML URLs signed with the old one stop working (they last two minutes, so that is a
2278
+ blip, not an outage). Back up an external quota config separately.
2202
2279
  Backup folders are mode 0700, files 0600, and checksums cover database/capture/key files. Treat them as sensitive as the live server,
2203
2280
  encrypt offsite copies and test that you can recover them. Staging uploads and one-time setup links are excluded.
2204
2281
 
@@ -2208,6 +2285,19 @@ A monthly manual restore drill should be logged by the operator. `restore --chec
2208
2285
  checksums, row counts, board folders and health, then stops its temporary server and removes the scratch copy. Automated tests also
2209
2286
  sign in to a restored fixture with its software passkey; that does not verify real phones or hardware authenticators.
2210
2287
 
2288
+ Four things the commands above do not do for you, each enough to leave a dead instance:
2289
+
2290
+ - **Nothing stops the server.** Neither `restore` nor the drill touches a running service, and two hosted processes against one
2291
+ data folder is not supported. Stop the service yourself before you point it at restored data.
2292
+ - **Nothing sets the owner.** `restore` makes the folder 0700 and its files 0600, owned by whoever ran the command, and there is
2293
+ no `chown` step anywhere. Restored under `sudo`, the data belongs to root, the service user cannot read it and the server does
2294
+ not start. Run the restore as the user the service runs as, or change the owner afterwards yourself.
2295
+ - **The drill writes next to the backup, not inside it.** `restore --check` puts its scratch copy in the backup's **parent**
2296
+ directory (`.restore-drill-<pid>-<timestamp>`), so a backup whose parent directory is read-only fails the drill. There is no
2297
+ flag for that folder: copy the backup to a writable disk and drill the copy.
2298
+ - **`--from` pointed at a folder of backups picks the newest.** `restore --from ./backups` takes the newest
2299
+ `shapewall-backup-*` it finds there without asking. Name the exact backup folder when you mean a particular one.
2300
+
2211
2301
  Restore refuses a nonempty target. Keep the original origin (passkeys depend on it), inspect the restored copy, then change the
2212
2302
  runtime data pointer during an operator-approved maintenance window. Retain the previous release and data backup for rollback.
2213
2303
  Project/workspace deletion removes active files immediately after database deletion; backup copies age out only under the chosen
@@ -2215,10 +2305,18 @@ backup policy. Operators must replay deletion requests after restoring an older
2215
2305
 
2216
2306
  ### Migration 7 and rollback
2217
2307
 
2218
- Migration 7 adds workspace suspension/retention columns, operator log and abuse reports. A `schema_migrations` ledger records each
2219
- actually-applied migration so reserved 5/6 can land later without being skipped by a higher `user_version`. Legacy versions 1-4
2220
- are adopted into the ledger. Empty reservations are never marked applied. Back up before any upgrade and do not run a build that
2221
- uses empty migration placeholders against retained data.
2308
+ Migration 7 adds workspace suspension and retention columns, the operator log and abuse reports. It is also where the
2309
+ `schema_migrations` ledger came in: it records every migration that actually ran, so migrations written in parallel can reach a
2310
+ database in either order. `PRAGMA user_version` is the highest number in the ledger, not a count, and the server writes it back
2311
+ from the ledger at every start. Migrations 5 and 6 were reservations when this was written; both have been filled in since
2312
+ (hosted access, and scoped dispatch with command approvals), and no migration is empty today. A database from before the ledger
2313
+ has contiguous versions 1 to 4, and those are adopted into the ledger on its first start with a newer build.
2314
+
2315
+ **A database with no ledger and `user_version` above 4 is refused at start:** "Database has untracked migrations newer than
2316
+ version 4; restore its pre-upgrade backup before continuing." That is what a hand-raised `user_version` looks like, and the
2317
+ server will not guess which migrations ran. Restore the pre-upgrade backup instead.
2318
+
2319
+ Back up before any upgrade.
2222
2320
 
2223
2321
  For rollback, prefer the pre-upgrade backup in a fresh data folder and the previous immutable release. Merely running an older build
2224
2322
  on the new database ignores additive columns but also removes suspension enforcement: keep affected workspaces blocked externally
@@ -2284,7 +2382,9 @@ Migration 14 (0.6.0) adds approvals and edits from a hosted board
2284
2382
  - table `chat_permissions` (one row per permission card a connected agent asked during a fix: what it asked, as hashed, its
2285
2383
  state, who answered and when);
2286
2384
  - columns `agent_runs.approvals_asked`, `agent_runs.approvals_allowed` and `agent_runs.approvals_denied` (how many requests a
2287
- fix asked and how they ended).
2385
+ fix asked and how they ended);
2386
+ - column `agents.approval_rule_by` (who last set the agent's approval rule, so an agent whose machine says `--approvals owner`
2387
+ goes without asking only while that rule is the connecting person's own).
2288
2388
 
2289
2389
  Nothing existing is rewritten: no token gains a scope, no agent changes its audience or its approval rule, and a connected agent
2290
2390
  reads and answers only until its own machine says more. `watch --remote` and `mcp --remote` work with the same tokens. Back up
@@ -2302,7 +2402,8 @@ database also works, since it ignores the new table and columns, but:
2302
2402
 
2303
2403
  To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE chat_permissions; ALTER TABLE agent_runs DROP
2304
2404
  COLUMN approvals_asked; ALTER TABLE agent_runs DROP COLUMN approvals_allowed; ALTER TABLE agent_runs DROP COLUMN
2305
- approvals_denied; DELETE FROM schema_migrations WHERE version = 14; PRAGMA user_version = 13;`. Never reset the ledger any other
2405
+ approvals_denied; ALTER TABLE agents DROP COLUMN approval_rule_by; DELETE FROM schema_migrations WHERE version = 14; PRAGMA
2406
+ user_version = 13;`. Never reset the ledger any other
2306
2407
  way. Test a rollback on a copy first.
2307
2408
 
2308
2409
  ### Migration 15 and rollback
@@ -2396,7 +2497,9 @@ users_tailnet_login; ALTER TABLE users DROP COLUMN tailnet_login; ALTER TABLE us
2396
2497
  users DROP COLUMN tailnet_user_id; ALTER TABLE passkeys DROP COLUMN tailnet_added_from; DROP TABLE server_settings; ALTER TABLE
2397
2498
  sessions DROP COLUMN tailnet_login; ALTER TABLE invites DROP COLUMN tailnet_login; ALTER TABLE workspaces DROP COLUMN step_up;
2398
2499
  DELETE FROM schema_migrations WHERE version = 17;`, then set `PRAGMA user_version` to the highest version left in
2399
- `schema_migrations` (16 where the saved Usage layouts are there, else 15).
2500
+ `schema_migrations` (16 where the saved Usage layouts are there, else 15). Where migration 18 ran, roll it back first
2501
+ ([Migration 18 and rollback](#migration-18-and-rollback)): its check names `sessions.tailnet_login`, so the column cannot be
2502
+ dropped before.
2400
2503
 
2401
2504
  **A database from a build of this release before it was released.** While 0.7.0 was being made, the sign-in migration was
2402
2505
  numbered 16 for a while. A database such a build opened says "16 ran" in its ledger, which now means the Usage layouts. The
@@ -2409,16 +2512,108 @@ either order: a database that ran only 16 runs 17 on the next start, and one tha
2409
2512
  the highest number applied, not a count. Rolling one back does not touch the other; remove only its own row from
2410
2513
  `schema_migrations`.
2411
2514
 
2515
+ ### Migration 18 and rollback
2516
+
2517
+ Migration 18 (0.9.0) records a tailnet sign-in as one. It is the first migration that rewrites a table instead of adding to one:
2518
+
2519
+ - `sessions.via` may now be `tailnet` as well as `passkey` and `recovery`, and a check keeps `tailnet` to rows that carry a
2520
+ `tailnet_login`;
2521
+ - `sessions.tailnet_login` is never the empty string (another check): it is a login or `NULL`;
2522
+ - every existing session with a `tailnet_login` is marked `tailnet` (before, such a session was stored as `passkey` with its
2523
+ login beside it). A row whose login is `''` (no build writes one; only a hand-made row can have it) is copied with `NULL`
2524
+ instead and keeps its `via`: the server's code read `''` as "no login" while its SQL read it as a login, and now both
2525
+ read it as none. Such a row is then an ordinary session, found by the hash of its token; one stored under a tailnet hash is
2526
+ never found.
2527
+
2528
+ Why a rebuild: SQLite cannot change a `CHECK` in place, so the server makes the new `sessions` table, copies every row into it,
2529
+ drops the old one, renames the new one and makes its two indexes again (`sessions_user`, `sessions_id`), as SQLite documents.
2530
+ All of it runs in the same transaction as the ledger entry, so a failure leaves the database as it was and the server does not
2531
+ start. Nothing Shapewall makes references `sessions` (no foreign key, trigger or view), so dropping the old table touches nothing
2532
+ else. Two cases only a hand-made schema has:
2533
+
2534
+ - **A view on `sessions`** makes the migration fail with `error in view <name>: no such table: main.sessions`. The server does not
2535
+ start and the file is left as it was (still at 17). Drop the view, start the server, then make the view again.
2536
+ - **A trigger on `sessions`** is dropped with the old table, and the migration succeeds without it. Note its `CREATE TRIGGER`
2537
+ first (`SELECT sql FROM sqlite_master WHERE type = 'trigger' AND tbl_name = 'sessions';`) and make it again afterwards.
2538
+
2539
+ A session
2540
+ whose account no longer exists is not copied (it can only exist if foreign keys were switched off at some point, and it could
2541
+ never be used: signing in with it finds no account). Signed-in browsers stay signed in: the token hashes are copied as they are.
2542
+
2543
+ What it does not change: who may do what. The server never decided anything from the stored `via`. How a session came in is read
2544
+ from `tailnet_login` (the column the session's hash is bound to): a row with a login is a tailnet session whatever `via` says,
2545
+ and a row without one never is. The `verified_at` of a tailnet session stays `1970-01-01T00:00:00.000Z`, the mark for "no
2546
+ passkey was checked at sign-in", until a passkey of the account confirms it.
2547
+
2548
+ For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running the previous build on the
2549
+ upgraded database also works with no change to it: the previous build reads how a session came in from `tailnet_login` as this
2550
+ one does, and the new check allows what it writes (a tailnet session stored as `passkey` with its login). Sessions it makes are
2551
+ stored that way, and stay so after upgrading again; they still show as tailnet sessions everywhere.
2552
+
2553
+ To put the table back as it was (with the server stopped; any SQLite 3.25+ `sqlite3` shell, or Node's `node:sqlite`). Roll this
2554
+ back before rolling back migration 17, whose rollback drops `sessions.tailnet_login`:
2555
+
2556
+ ```sql
2557
+ BEGIN IMMEDIATE;
2558
+ CREATE TABLE sessions_v17 (
2559
+ token_hash TEXT PRIMARY KEY,
2560
+ user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
2561
+ created_at TEXT NOT NULL,
2562
+ last_seen_at TEXT NOT NULL,
2563
+ expires_at TEXT NOT NULL,
2564
+ verified_at TEXT NOT NULL,
2565
+ via TEXT NOT NULL DEFAULT 'passkey' CHECK (via IN ('passkey', 'recovery')),
2566
+ id TEXT,
2567
+ user_agent TEXT,
2568
+ ip TEXT,
2569
+ admin_seen_at TEXT,
2570
+ tailnet_login TEXT
2571
+ );
2572
+ INSERT INTO sessions_v17
2573
+ (token_hash, user_id, created_at, last_seen_at, expires_at, verified_at, via, id, user_agent, ip, admin_seen_at, tailnet_login)
2574
+ SELECT token_hash, user_id, created_at, last_seen_at, expires_at, verified_at,
2575
+ CASE WHEN via = 'tailnet' THEN 'passkey' ELSE via END,
2576
+ id, user_agent, ip, admin_seen_at, tailnet_login
2577
+ FROM sessions;
2578
+ DROP TABLE sessions;
2579
+ ALTER TABLE sessions_v17 RENAME TO sessions;
2580
+ CREATE INDEX sessions_user ON sessions(user_id);
2581
+ CREATE UNIQUE INDEX sessions_id ON sessions(id);
2582
+ DELETE FROM schema_migrations WHERE version = 18;
2583
+ PRAGMA user_version = 17;
2584
+ COMMIT;
2585
+ ```
2586
+
2587
+ Every session survives it, tailnet sessions as `passkey` with their login (as before 0.9.0). A login that was `''` before the upgrade stays `NULL`. `PRAGMA user_version` is the
2588
+ highest version left in `schema_migrations`: 17 unless a later migration is there too. The next upgrade runs 18 again. Never
2589
+ reset the ledger any other way. Test a rollback on a copy first: `PRAGMA integrity_check;` says `ok`, and `SELECT via,
2590
+ tailnet_login IS NOT NULL, COUNT(*) FROM sessions GROUP BY 1, 2;` shows the same sessions as before, with `tailnet` back to
2591
+ `passkey`.
2592
+
2412
2593
  ## Secrets, logs and legal review
2413
2594
 
2414
2595
  `SHAPEWALL_HOSTED_SECRET_FILE` and `RESEND_API_KEY_FILE` read private secret files. systemd `LoadCredential=shapewall-secret:...` and
2415
- `LoadCredential=resend-api-key:...` are read from `$CREDENTIALS_DIRECTORY`; explicit environment values take precedence. Setup links
2596
+ `LoadCredential=resend-api-key:...` are read from `$CREDENTIALS_DIRECTORY`. **The order is: the variable itself, then its `_FILE`,
2597
+ then the credentials directory.** A value already in `SHAPEWALL_HOSTED_SECRET` or `RESEND_API_KEY` means the file is not read at
2598
+ all, so a stale variable quietly beats the file you meant to use. The two are not treated alike when the file is missing: a
2599
+ `_FILE` you named and the server cannot read is a startup error, while a file missing from `$CREDENTIALS_DIRECTORY` is skipped in
2600
+ silence and the server carries on as if the secret were unset (it then makes its own `<data>/secret.key`, and invite emails stay
2601
+ off). Check the start log for the names it loaded; it never prints a value. Setup links
2416
2602
  are written to `<data>/setup-link` (0600) and not journaled. Caddy deletes Cookie, Authorization, Set-Cookie and signed `s` query
2417
2603
  values from access logs. Invite/setup/share fragments are never sent in HTTP requests. App errors omit request values; email logs
2418
2604
  contain status only. Do not enable debug request-body logging. Review any proxy/hosting logs outside these examples independently.
2419
2605
 
2420
- Fill `SHAPEWALL_HOSTED_TERMS_URL`, `_PRIVACY_URL`, `_AUP_URL`, `_SUBPROCESSORS_URL` and `_ABUSE_EMAIL` before inviting users. These
2421
- appear on sign-in/signup and guest pages, plus `/report`. The legal templates deliberately require an operator, contact, actual
2606
+ Fill `SHAPEWALL_HOSTED_TERMS_URL`, `_PRIVACY_URL`, `_AUP_URL`, `_SUBPROCESSORS_URL` and `_ABUSE_EMAIL` before inviting users.
2607
+ **Setting them is the only way the legal links appear:** the server shows no Terms, Privacy, Acceptable use or Subprocessors link
2608
+ for a variable that is unset -- that is the "legal links not set" state, and each variable governs its own link alone. Where they
2609
+ are set, they appear on sign-in and signup and on guest pages, plus `/report`.
2610
+
2611
+ **A bad value stops the server.** The four URLs are checked at start: each must begin `http://` or `https://` and hold no
2612
+ whitespace, quote or angle bracket, or the server throws `SHAPEWALL_HOSTED_TERMS_URL: an http(s) URL` (naming the one at fault)
2613
+ and does not start; `_ABUSE_EMAIL` must look like an email address (`SHAPEWALL_HOSTED_ABUSE_EMAIL: an email address`). A bare host name, a
2614
+ `mailto:` in a URL slot or a trailing comment is a refusal, not a warning. Unset is fine; wrong is fatal.
2615
+
2616
+ The legal templates deliberately require an operator, contact, actual
2422
2617
  hosting region, provider list and retention policy. Dan's review and any required counsel review remain release gates. No legal
2423
2618
  text, Compose stack, Tailscale mapping, timer or staging deployment is activated by adding these files.
2424
2619