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.
- package/CHANGELOG.md +57 -0
- package/README.md +5 -2
- package/bin/shapewall.js +2 -1
- package/dist/agent/package-lock.json +2 -2
- package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
- package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
- package/dist/client/assets/{History-C_NAxaRl.js → History-FzpzGmXZ.js} +1 -1
- package/dist/client/assets/{LocalSettings-W5Ze9ks7.js → LocalSettings-BGFl4VKr.js} +1 -1
- package/dist/client/assets/{Management-CXGSi6gI.js → Management-BGdmGtby.js} +1 -1
- package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
- package/dist/client/assets/{app-update-dialog-DNL0kP9U.js → app-update-dialog-BQxVHa5e.js} +1 -1
- package/dist/client/assets/index-B_m65HWT.css +2 -0
- package/dist/client/assets/{index-DTXjDgcg.js → index-C1ZwriJU.js} +19 -19
- package/dist/client/build-info.json +1 -1
- package/dist/client/index.html +2 -2
- package/dist/client/sw.js +2 -2
- package/dist/console/assets/{LocalAccountsApp-Z0gEJ74C.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
- package/dist/console/assets/{LocalConsole-DzHNISE9.js → LocalConsole-Rg-MTvSJ.js} +1 -1
- package/dist/console/assets/{app-update-dialog-CQsUPrMX.js → app-update-dialog-CEhV7th4.js} +1 -1
- package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
- package/dist/console/assets/console-BD5_Gha1.js +11 -0
- package/dist/console/assets/console-PWt8SxrJ.css +2 -0
- package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
- package/dist/console/assets/{tailnet-C2QPbIIC.js → tailnet-Cqtbptzq.js} +2 -2
- package/dist/console/assets/{usage-BDt6IQh1.js → usage-BCIwgDP9.js} +2 -2
- package/dist/console/build-info.json +1 -1
- package/dist/console/console.html +5 -5
- package/docs/README.md +64 -0
- package/docs/agent-hardening.md +3 -3
- package/docs/agent-recipes.md +3 -3
- package/docs/agent-workflow.md +6 -4
- package/docs/agents.md +25 -16
- package/docs/architecture.md +6 -1
- package/docs/config.md +53 -25
- package/docs/deployment.md +2 -2
- package/docs/github.md +1 -1
- package/docs/hosted.md +265 -70
- package/docs/local-accounts.md +1 -1
- package/docs/performance.md +3 -2
- package/docs/pull-requests.md +1 -1
- package/docs/starter-agent.md +4 -4
- package/docs/where-to-run.md +1 -1
- package/package.json +3 -2
- package/src/agent/backends/acp.js +39 -9
- package/src/capture/capture.js +35 -5
- package/src/capture/destination.js +67 -0
- package/src/capture/load-errors.js +82 -0
- package/src/checks/cli.js +41 -5
- package/src/cli/args.js +1 -0
- package/src/cli/capture.js +5 -0
- package/src/cli/comments.js +41 -3
- package/src/cli/help.js +4 -1
- package/src/cli/init.js +8 -4
- package/src/cli/misc.js +3 -3
- package/src/cli/serve.js +34 -6
- package/src/comment-fields.js +5 -0
- package/src/comments-cli.js +26 -5
- package/src/config-keys.js +191 -0
- package/src/config-reload.js +4 -1
- package/src/config.js +33 -2
- package/src/doctor.js +188 -39
- package/src/hosted/auth.js +14 -8
- package/src/hosted/db.js +50 -0
- package/src/hosted/pages.js +5 -1
- package/src/missing-package.js +11 -0
- package/src/ports.js +35 -0
- package/src/serve-state.js +16 -0
- package/src/watch.js +6 -0
- package/dist/client/assets/BoardChat-DG08cvD0.js +0 -27
- package/dist/client/assets/ChecksPanel-BD7GniTp.js +0 -1
- package/dist/client/assets/QuickConnect-Cta4dT3n.js +0 -1
- package/dist/client/assets/index-CBrmVq4n.css +0 -2
- package/dist/console/assets/app-version-CP0o1L1_.js +0 -1
- package/dist/console/assets/console-DIWY1goy.css +0 -2
- package/dist/console/assets/console-DYqhjwPS.js +0 -11
- 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
|
|
29
|
-
| ----------------------- |
|
|
30
|
-
| `--data DIR` | `SHAPEWALL_HOSTED_DATA`
|
|
31
|
-
| `--origin URL` | `SHAPEWALL_HOSTED_ORIGIN`
|
|
32
|
-
| `--port`/`--host` |
|
|
33
|
-
| `--signup` | `SHAPEWALL_HOSTED_SIGNUP`
|
|
34
|
-
| `--trust-proxy` | `SHAPEWALL_HOSTED_TRUST_PROXY=1`
|
|
35
|
-
| | `SHAPEWALL_HOSTED_SECRET`
|
|
36
|
-
| | `RESEND_API_KEY`
|
|
37
|
-
| | `SHAPEWALL_EMAIL_FROM`
|
|
38
|
-
| `--previous-origin URL` | `SHAPEWALL_HOSTED_PREVIOUS_ORIGIN`
|
|
39
|
-
| `--report-email ADDR` | `SHAPEWALL_HOSTED_REPORT_EMAIL`
|
|
40
|
-
| `--tailnet-sign-in` | `SHAPEWALL_HOSTED_TAILNET_SIGN_IN=1`
|
|
41
|
-
| `--tailnet-passkeys` | `SHAPEWALL_HOSTED_TAILNET_PASSKEYS=1`
|
|
42
|
-
| `--owners-see-sign-ins` | `SHAPEWALL_HOSTED_OWNERS_SEE_SIGN_INS=1`
|
|
43
|
-
|
|
|
44
|
-
| | `
|
|
45
|
-
|
|
46
|
-
|
|
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
|
|
237
|
-
admins of every workspace see them under Members, "Arrived
|
|
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
|
|
249
|
-
|
|
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
|
|
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
|
|
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
|
-
| `
|
|
817
|
-
| `
|
|
818
|
-
| `
|
|
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
|
|
885
|
-
|
|
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
|
|
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
|
|
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 ([
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
2021
|
-
`
|
|
2022
|
-
|
|
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
|
|
2029
|
-
|
|
2030
|
-
everything as well (SQLite 3.35+)
|
|
2031
|
-
|
|
2032
|
-
|
|
2033
|
-
DROP COLUMN
|
|
2034
|
-
|
|
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
|
-
|
|
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
|
|
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),
|
|
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
|
|
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`.
|
|
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
|
|
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
|
|
2219
|
-
|
|
2220
|
-
|
|
2221
|
-
|
|
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
|
|
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
|
|
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.
|
|
2421
|
-
|
|
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
|
|