shapewall 0.6.0 → 0.7.1

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 (127) hide show
  1. package/CHANGELOG.md +267 -0
  2. package/README.md +39 -2
  3. package/THIRD_PARTY.md +15 -0
  4. package/dist/agent/package-lock.json +594 -2
  5. package/dist/client/assets/{BoardChat-DdwBcb2N.js → BoardChat-Bv4UDOjO.js} +1 -1
  6. package/dist/client/assets/{BuzzDialog-DpUcnU6S.js → BuzzDialog-DwEAN6va.js} +1 -1
  7. package/dist/client/assets/{ChecksPanel-CngYV4yz.js → ChecksPanel-C6r_Tc9g.js} +1 -1
  8. package/dist/client/assets/{History-CD0saQA5.js → History-ajFROfWC.js} +1 -1
  9. package/dist/client/assets/{LocalSettings-MZy2baig.js → LocalSettings-BSbmmpbN.js} +1 -1
  10. package/dist/client/assets/{Management-CSvZ-SHO.js → Management-mo8uv2qG.js} +1 -1
  11. package/dist/client/assets/{QuickConnect-foLh2QUm.js → QuickConnect-DlaijESK.js} +1 -1
  12. package/dist/client/assets/{ShareDialog-DPWDftoL.js → ShareDialog-CdLdd6WQ.js} +1 -1
  13. package/dist/client/assets/{app-update-dialog-CtiXpTRD.js → app-update-dialog-BHVNR5Cp.js} +1 -1
  14. package/dist/client/assets/{circle-x-CteRBtXC.js → circle-x-D5MkDLJk.js} +1 -1
  15. package/dist/client/assets/index-B4AoX3ZW.css +2 -0
  16. package/dist/client/assets/index-CQeHY7en.js +37 -0
  17. package/dist/client/assets/{play-BjRNIGSf.js → play--xrZ7VCR.js} +1 -1
  18. package/dist/client/assets/{refresh-cw-r_tZiFfB.js → refresh-cw-B-npxKae.js} +1 -1
  19. package/dist/client/assets/{ui-zQpn-PdL.js → ui-2lMx-4bc.js} +2 -2
  20. package/dist/client/build-info.json +1 -1
  21. package/dist/client/index.html +3 -3
  22. package/dist/client/sw.js +2 -2
  23. package/dist/console/assets/LocalAccountsApp-C1sCag6a.js +1 -0
  24. package/dist/console/assets/LocalConsole-LXQmzRFT.js +2 -0
  25. package/dist/console/assets/LocalUsage-Br3Ddp7_.js +1 -0
  26. package/dist/console/assets/app-update-dialog-CVniDJKA.js +1 -0
  27. package/dist/console/assets/app-version-CTHwlY6g.js +1 -0
  28. package/dist/console/assets/console-CMNNLtFw.js +11 -0
  29. package/dist/console/assets/console-sMMn_Rwc.css +2 -0
  30. package/dist/console/assets/local-agents-DwYJ9cPb.js +6 -0
  31. package/dist/console/assets/minus-887msXez.js +1 -0
  32. package/dist/console/assets/tailnet--wXsG3uh.js +2 -0
  33. package/dist/console/assets/theme-CPfJOmcz.js +1 -0
  34. package/dist/console/assets/ui-DnyJhoQU.js +41 -0
  35. package/dist/console/assets/usage-C5CJHejQ.js +5 -0
  36. package/dist/console/assets/usage-CIPWnHaS.css +1 -0
  37. package/dist/console/assets/usage-DjmUlnXL.js +56 -0
  38. package/dist/console/build-info.json +1 -1
  39. package/dist/console/console.html +8 -2
  40. package/docs/agent-hardening.md +31 -17
  41. package/docs/agents.md +35 -0
  42. package/docs/architecture.md +10 -4
  43. package/docs/deployment.md +39 -17
  44. package/docs/design-system.md +56 -7
  45. package/docs/hosted.md +1004 -43
  46. package/docs/images/board-overview.png +0 -0
  47. package/docs/images/journeys.png +0 -0
  48. package/docs/images/live-comment.png +0 -0
  49. package/docs/images/phone-comment.png +0 -0
  50. package/docs/images/phone-overview.png +0 -0
  51. package/docs/images/variant.png +0 -0
  52. package/docs/where-to-run.md +82 -1
  53. package/package.json +6 -1
  54. package/src/agent/backends/acp.js +224 -26
  55. package/src/agent/routes.js +21 -0
  56. package/src/agent/usage-log.js +251 -0
  57. package/src/cli/args.js +24 -0
  58. package/src/cli/help.js +37 -2
  59. package/src/cli/init.js +2 -1
  60. package/src/cli/serve.js +20 -5
  61. package/src/cli.js +8 -0
  62. package/src/hosted/access-cli.js +99 -1
  63. package/src/hosted/activity-core.js +232 -0
  64. package/src/hosted/activity.js +375 -0
  65. package/src/hosted/admin.js +80 -13
  66. package/src/hosted/agent-approvals.js +2 -2
  67. package/src/hosted/agent-routes.js +3 -3
  68. package/src/hosted/agents.js +11 -4
  69. package/src/hosted/app.js +89 -7
  70. package/src/hosted/auth-routes.js +156 -15
  71. package/src/hosted/auth.js +123 -20
  72. package/src/hosted/board-routes.js +3 -3
  73. package/src/hosted/chat-frames.js +5 -15
  74. package/src/hosted/chat-permissions.js +12 -0
  75. package/src/hosted/chat-routes.js +8 -8
  76. package/src/hosted/chat-store.js +20 -3
  77. package/src/hosted/comment-files.js +5 -2
  78. package/src/hosted/console-routes.js +111 -34
  79. package/src/hosted/db.js +130 -0
  80. package/src/hosted/device-routes.js +25 -3
  81. package/src/hosted/device.js +23 -4
  82. package/src/hosted/guards.js +337 -27
  83. package/src/hosted/http.js +6 -3
  84. package/src/hosted/membership.js +13 -2
  85. package/src/hosted/operator-access.js +418 -0
  86. package/src/hosted/operator.js +106 -2
  87. package/src/hosted/ops-cli.js +238 -3
  88. package/src/hosted/pages.js +2 -0
  89. package/src/hosted/passkey-policy.js +75 -0
  90. package/src/hosted/permissions.js +14 -6
  91. package/src/hosted/presence.js +14 -2
  92. package/src/hosted/projects.js +2 -1
  93. package/src/hosted/public.js +4 -4
  94. package/src/hosted/ratelimit.js +6 -0
  95. package/src/hosted/retention.js +18 -2
  96. package/src/hosted/server.js +123 -11
  97. package/src/hosted/shares.js +2 -2
  98. package/src/hosted/step-up-settings.js +68 -0
  99. package/src/hosted/step-up.js +135 -0
  100. package/src/hosted/tailnet-identity.js +24 -0
  101. package/src/hosted/tailnet-routes.js +342 -0
  102. package/src/hosted/tailnet.js +220 -0
  103. package/src/hosted/tailscale.js +75 -9
  104. package/src/hosted/tenancy.js +48 -1
  105. package/src/hosted/token-api.js +2 -2
  106. package/src/hosted/tokens.js +9 -2
  107. package/src/hosted/usage-core.js +624 -0
  108. package/src/hosted/usage-layout.js +724 -0
  109. package/src/hosted/usage-routes.js +375 -0
  110. package/src/hosted/usage-shape.js +256 -0
  111. package/src/hosted/usage.js +641 -0
  112. package/src/remote/agent-connect.js +37 -1
  113. package/src/remote/agent-link.js +2 -0
  114. package/src/remote/login.js +33 -8
  115. package/src/remote/share.js +1 -1
  116. package/src/remote/tailnet-cli.js +547 -0
  117. package/src/server/app.js +15 -0
  118. package/src/server/pairing-routes.js +34 -5
  119. package/src/server/tailscale.js +97 -4
  120. package/src/tailnet-proof.js +766 -0
  121. package/dist/client/assets/index-Cxz1UVcV.css +0 -2
  122. package/dist/client/assets/index-uUZVBYUS.js +0 -37
  123. package/dist/console/assets/LocalAccountsApp-DIdy1KnN.js +0 -1
  124. package/dist/console/assets/LocalConsole-DfcQztF-.js +0 -1
  125. package/dist/console/assets/app-update-dialog-ttl9lF5A.js +0 -1
  126. package/dist/console/assets/console-OqAjD0kV.js +0 -55
  127. package/dist/console/assets/console-kvjrAArQ.css +0 -2
package/docs/hosted.md CHANGED
@@ -25,20 +25,23 @@ 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
- | | `SHAPEWALL_TURNSTILE_SITE_KEY` | unset | With `SHAPEWALL_TURNSTILE_SECRET`: a Cloudflare Turnstile check on open sign-up and comment share links |
41
- | | `SHAPEWALL_TURNSTILE_SECRET` | unset | Turnstile secret key. Both keys or neither (one alone is a warning and stays off) |
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) |
42
45
 
43
46
  It needs Node 22.13 or newer (it uses the built-in `node:sqlite`). Passkeys need a secure context: `https://`, or `http://localhost`
44
47
  for trying it on your own machine (`--origin http://localhost:4700`; not `127.0.0.1`, which is not a valid passkey RP ID).
@@ -58,6 +61,554 @@ that origin to the console CSP. Off by default.
58
61
  Deployment examples: [examples/hosted/shapewall-hosted.service](../examples/hosted/shapewall-hosted.service)
59
62
  (systemd, hardened) and [examples/hosted/Caddyfile](../examples/hosted/Caddyfile).
60
63
 
64
+ ## Signing in
65
+
66
+ Four ways to reach Shapewall, side by side. Pick by who has to reach the board.
67
+
68
+ | How you reach it | Command | How people sign in | Who can reach it |
69
+ | ----------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------ |
70
+ | Local board, on your machine | `shapewall serve` | Nothing: it is your board | This machine |
71
+ | Over an SSH tunnel | `ssh -L 4700:127.0.0.1:4700 server` | A local board: nothing, as if you sat at that machine. A hosted server: a passkey each | Whoever can SSH to the machine |
72
+ | Your tailnet, tailnet sign-in | `shapewall hosted --tailscale --tailnet-sign-in` | Your Tailscale account, from every tailnet device of yours. No passkey, no password. An admin invites | People on your tailnet |
73
+ | Your own domain | `shapewall hosted --origin https://app.example.com` | A passkey each | Anyone you invite |
74
+
75
+ A tailnet server can also run with passkeys instead of tailnet sign-in (`shapewall hosted --tailscale`: a passkey each), or
76
+ with both (`--tailnet-sign-in --tailnet-passkeys`). Everything after the sign-in is the same on every hosted server: accounts,
77
+ workspaces, roles, invites, the audit log.
78
+
79
+ ### Over SSH
80
+
81
+ For people who do not use Tailscale: an SSH tunnel carries one port of the server's machine to your own.
82
+
83
+ ```sh
84
+ # On the server (once): a hosted server for the address your browser will use. No TLS, no proxy, loopback only.
85
+ shapewall hosted --data ./hosted-data --port 4700 --origin http://shapewall.localhost:4700
86
+
87
+ # On your machine, each time:
88
+ ssh -L 4700:127.0.0.1:4700 you@server
89
+ # then open http://shapewall.localhost:4700
90
+ ```
91
+
92
+ - **Give the tunnel a host name of its own: `shapewall.localhost`.** Browsers send every name that ends in `.localhost` to
93
+ your own machine and treat it as a secure context, so passkeys work without a certificate, and the name keeps the server's
94
+ cookies and passkeys to itself. Tested in Chromium (sign-up and sign-in with a passkey; the passkey belongs to
95
+ `shapewall.localhost`, the session cookie is sent to that name only).
96
+ - **Plain `http://localhost:4700` works too** (`--origin http://localhost:4700`), for a browser or a tool that does not
97
+ resolve `.localhost` names. Know what it means: **cookies are not kept apart by port.** At plain `localhost` the session
98
+ cookie is also sent to any other web server on your machine's `localhost` (a dev server on another port), and that server
99
+ could use it against Shapewall while you have the tunnel open. With `shapewall.localhost` it is not. Not `127.0.0.1`: not a
100
+ valid passkey host.
101
+ - **Accounts are passkey accounts** for that origin. The origin is part of the passkey: keep the same host name and the same
102
+ port on both ends. Everyone who tunnels in uses the same address and has their own account, role and passkey.
103
+ - **Everyone arrives from 127.0.0.1.** The server sees the SSH daemon's end of the tunnel, so all tunnelled people share one
104
+ address: the rate limits that count per address (sign-in attempts, recovery codes, invite lookups) are shared between
105
+ them, and the audit log and the device list show `127.0.0.1` for everyone. Who did what is still each person's account.
106
+ - **The first account** is made with the setup link, as on any server: `shapewall hosted setup-link --data ./hosted-data` on
107
+ the server prints `http://shapewall.localhost:4700/signup#setup=...`; open it through the tunnel.
108
+ - **The server listens on 127.0.0.1 only.** Nothing is open to the network; SSH is the way in, and whoever has an SSH login on
109
+ the machine can reach the port. Sign-in still decides who is who.
110
+ - **Share links** made there point at the tunnel's address too, so they work only for people with a tunnel. For links
111
+ anyone can open, use a tailnet with `--funnel` or your own domain.
112
+ - **A local board over a tunnel** (`shapewall serve --port 4600` on the remote machine, `ssh -L 4600:127.0.0.1:4600 ...`):
113
+ the board sees a connection from its own machine, so you are treated as the person sitting at it. There is no sign-in and no
114
+ pairing; comments, chat with the agent and approvals work as they do locally, and settings still need the private owner
115
+ link the terminal printed. That is right for your own machine over your own SSH login. It also means that every OS user on
116
+ that machine, and anyone you forward the port to, is that same person: do not tunnel a local board for other people; run
117
+ the hosted server for them.
118
+
119
+ Tested in the suite with the real command and a real browser at `http://shapewall.localhost:<port>` and at
120
+ `http://localhost:<port>` (sign-up, sign-out, sign-in with a passkey, and which of the two sends its session cookie to
121
+ another server on localhost; `test/e2e/hosted-ssh.e2e.test.js`). The tunnel itself is SSH's.
122
+
123
+ ### When Shapewall asks for the passkey again
124
+
125
+ This section is about servers where passkeys are the sign-in. On a tailnet sign-in server without passkeys (the default
126
+ there) the fixed core below asks for a typed name instead, and nothing else asks: [Tailnet sign-in](#tailnet-sign-in).
127
+
128
+ Once you are signed in, your role decides what you may do, and that is all: approving an agent or a machine, agent settings,
129
+ tokens, share links, exports, an agent's edit and push cards, members and roles, deleting a project. No second prompt.
130
+
131
+ Two things ask for the passkey again ("Confirm it's you"):
132
+
133
+ **1. A small fixed core, always, on every server** (a passkey check in the last 10 minutes). These guard the account itself or
134
+ cannot be undone for everyone:
135
+
136
+ - adding or removing a passkey (`POST /auth/passkeys/options`, `POST /auth/passkeys/verify`, `DELETE /auth/passkeys/:id`);
137
+ - new recovery codes (`POST /auth/recovery-codes`);
138
+ - linking or unlinking a tailnet login (`POST` and `DELETE /auth/tailnet/link`; ticking the box at sign-up is the one way to
139
+ link without it);
140
+ - deleting your account (`DELETE /auth/me`);
141
+ - deleting a workspace (`DELETE /api/workspaces/:ws`);
142
+ - owners: making someone an owner, changing or removing an owner, inviting an owner (`PATCH` and `DELETE
143
+ /api/workspaces/:ws/members/:user`, `POST /api/workspaces/:ws/invites` with role `owner`);
144
+ - moving your sign-in to the server's new address (`POST /auth/rebind/start`);
145
+ - making the setting below weaker (`PATCH /api/workspaces/:ws/step-up`).
146
+
147
+ The list is one table in the code (`FIXED_CORE` in `src/hosted/step-up.js`), enforced in one place before any route runs.
148
+ "Sign out other devices" is not in it, but it is not free either: it needs a session that passed a passkey check at some
149
+ point (any passkey sign-in has), so a session someone merely holds cannot sign you out everywhere.
150
+
151
+ **2. What a workspace's owner switches on.** Settings, "Ask for a passkey again". Everything is off by default. One switch per
152
+ group:
153
+
154
+ | Group | Asks before |
155
+ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
156
+ | Agent edits and pushes | Allow on an agent's edit or command, Push this fix, approving an agent run or a shell command |
157
+ | Agents and machines | approving a machine or an agent (`shapewall login`, `agent connect`), who may use an agent, its approval rule, the project agent policy |
158
+ | Tokens and share links | new API tokens, new share links, turning share links or public projects on, making a project public |
159
+ | Members and roles | inviting an admin, making someone an admin, changing or removing an admin |
160
+ | Exports and deletes | exporting the workspace, deleting a project or a board |
161
+
162
+ With them: how long one check counts (5, 15, 30 or 60 minutes; 15 by default), and the admin idle rule (admin pages ask once more
163
+ after 12 hours without opening one). Only an owner changes these. Switching something on needs nothing more; switching it off or
164
+ choosing a longer time is part of the fixed core. Every change is in the audit log with the value before and after
165
+ (`step_up_changed`), and Activity's "Worth a look" filter marks it.
166
+
167
+ The server decides, route by route: it answers 403 `reauth_required` with a message that says which rule asked (and `stepUp` in the
168
+ error: `always`, the group's id, `adminIdle` or `restricted`), and only then does the console show the prompt. The console never
169
+ asks on its own.
170
+
171
+ A session that started with a recovery code, or with a passkey that was added with one in the last 24 hours, keeps the strict
172
+ rules whatever the workspace chose: everything in the groups above, and signing out other devices, needs a passkey check it cannot
173
+ give yet ([Accounts](#accounts)).
174
+
175
+ The audit log is unchanged: every action above is recorded as before, whether or not a passkey was asked for.
176
+
177
+ The settings as an API, one setting per request (owners): `PATCH /api/workspaces/:ws/step-up` with `{ "group": "tokens", "on":
178
+ true }`, `{ "windowMinutes": 30 }`, `{ "adminIdle": true }` or `{ "cliApproval": true }`. `GET /api/workspaces/:ws` carries them as
179
+ `workspace.settings.stepUp`.
180
+
181
+ ### Tailnet sign-in
182
+
183
+ ```sh
184
+ shapewall hosted --data ./hosted-data --tailscale --tailnet-sign-in # or SHAPEWALL_HOSTED_TAILNET_SIGN_IN=1
185
+ ```
186
+
187
+ On your tailnet, your Tailscale account is the sign-in: one identity, your different machines, and they all reach the server
188
+ with no second credential. `tailscale serve` adds the identity of the person behind each request (`Tailscale-User-Login`,
189
+ `Tailscale-User-Name`), and the server signs that person in as the account linked to their login.
190
+
191
+ **No passkeys, by default.** On a server started with `--tailnet-sign-in` no passkey is asked for or offered: the sign-in page
192
+ shows "Continue as ada@example.com" (or the invited and not-invited states) and nothing else, the Account page has no passkeys
193
+ and no recovery codes, and every passkey route answers 403 `passkeys_off`. What that means, plainly:
194
+
195
+ - **The tailnet is the trust boundary.** Anything running as you on one of your tailnet devices can act as you on this
196
+ server: a script, a coding agent, a browser extension. Tailscale says which device a request came from and whose device it
197
+ is, not that you are at the keyboard. Lock your devices, and keep the tailnet to people and machines you trust.
198
+ - **The few things Shapewall always asks about ask you to type a name.** Deleting a workspace or your account, making,
199
+ changing or removing an owner (leaving as one too), inviting an owner: the console asks you to type the workspace's name
200
+ (your handle for the account), and the server refuses the request until it carries that name (403 `confirm_required`;
201
+ the header `X-Shapewall-Confirm`). On the command line the same things need `--yes`, and the command names what it
202
+ confirms. This is deliberateness, not proof: the identity is already proven, and a program acting as you can type too.
203
+ The header is no secret and no token: the request is refused from another site exactly as every other write is (the same
204
+ origin and JSON are required, and no other origin is allowed to send the header). When you are in more than one workspace
205
+ with the same name, the name would not say which, so the prompt asks for the workspace's id instead and shows it.
206
+ - **Nothing else asks.** A workspace's "Ask for a passkey again" switches have nothing to ask for; Settings shows
207
+ "Confirming changes" in their place.
208
+ - **Passkeys are an opt-in hardening.** Start the server with `--tailnet-passkeys` (or
209
+ `SHAPEWALL_HOSTED_TAILNET_PASSKEYS=1`), or switch them on a running server: `shapewall hosted admin passkeys on --data DIR`
210
+ (`off`, `status`; kept in the database, and it wins over the flag). Then anyone may add a passkey on the Account page, an
211
+ account that has one confirms the fixed core with it, and everything under
212
+ [With passkeys also allowed](#with-passkeys-also-allowed) applies. Switched off again, passkeys are kept and not used, and the switch does three things and says them: every session that a
213
+ passkey or a recovery code started is ended (deleted, so switching on later does not bring one back); a passkey that was
214
+ still on hold stays on hold, stays removable with "Not you? Remove it", and starts its 24 hours again when passkeys come
215
+ back; and each workspace that asks for a passkey somewhere ("Ask for a passkey again", the command line switch) gets an
216
+ audit entry and a line in Settings, "Switched on here, and not asked while this server has passkeys off": its settings are
217
+ kept and asked again when passkeys are. An account with no tailnet login cannot sign in until they are on again (the
218
+ command says how many). In this mode a tailnet session ends the account's other sessions with no further question.
219
+
220
+ **Each tailnet login is its own account, and an admin still decides who is in a workspace.** Being on the tailnet alone gives
221
+ nothing. Why:
222
+
223
+ - **Who did what.** Comments, approvals, the audit log and usage name a person. One shared identity for "the tailnet" would make
224
+ all of that anonymous.
225
+ - **Roles.** A viewer, a member, an admin and an owner are different things; agents have audiences. None of it works without
226
+ accounts.
227
+ - **A tailnet is wider than a team.** It holds family devices, a contractor's laptop, a build machine, nodes shared in from
228
+ someone else's tailnet. They can reach the server; that should not put them in your workspace.
229
+
230
+ How people get in:
231
+
232
+ - **The first owner** claims the server with the setup link, as on any server. Opened through the tailnet, the page offers
233
+ "Continue as ada@example.com" and links that login. From the command line:
234
+ `shapewall hosted claim --data DIR --login LOGIN` on the server's machine ([From your coding agent](#from-your-coding-agent)).
235
+ 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).
239
+ - **An invite can be for one tailnet login** (Invite people, "Tailnet login"; `POST /invites` with `tailnetLogin`). Only that
240
+ login can use it, whoever has the link. They join the next time they open the server, with the role of the invite.
241
+ - **One login, one account.** (With passkeys allowed, an account that has a passkey links or unlinks its login on the
242
+ Account page; without them there is nothing to link or unlink.)
243
+ - **Tagged devices and nodes shared in without a user** carry no login. They are never signed in.
244
+
245
+ Good to know:
246
+
247
+ - **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
250
+ "tailnet" mark).
251
+ - **Signing out** keeps that browser signed out until you press "Continue as ada@example.com" on the sign-in page. Arriving again
252
+ would otherwise sign you straight back in; the page says so.
253
+ - **Share links, public boards and `--funnel`** work as on any server. The public listener never reads an identity.
254
+
255
+ ### With passkeys also allowed
256
+
257
+ Only on a tailnet server where the operator switched passkeys on (`--tailnet-passkeys`, or `hosted admin passkeys on`). An
258
+ account may then add a passkey; one that has a passkey confirms the fixed core with it (a passkey check in the last 10
259
+ minutes) and no longer by typing a name, and a workspace's "Ask for a passkey again" switches work.
260
+
261
+ - **The fixed core without a passkey.** An account that only its tailnet signs in has no passkey to confirm with. For the few
262
+ things that always need one it is told to add a passkey first (403 `passkey_required`). Adding the first passkey needs no
263
+ passkey check (there is nothing stronger to check it against). What it does need, and what follows:
264
+ - **A browser and a named device.** The request must come from the Account page in a browser (not from the command line's
265
+ tailnet session, not from another site), and you confirm a step that names the device: "Add a passkey from Chrome on
266
+ Linux?". A program on your device can imitate both; they keep the command line and other sites out, and they put the
267
+ device's name on the passkey.
268
+ - **The passkey is on hold for 24 hours.** It signs in at once, and it cannot confirm the fixed core until the day is over,
269
+ exactly like a passkey added after a recovery code. It cannot add a second passkey or make recovery codes either.
270
+ - **Every page says so, on every device.** While it is on hold, each page of your account shows "A passkey was added from
271
+ Chrome on Linux" with the time, and **"Not you? Remove it"**. Any tailnet session of your account removes it with that
272
+ button: no passkey check (the only passkey there is to check with is the one in question), and it goes though it is your
273
+ only passkey and you have no recovery codes. The sessions that passkey signed in end, every other passkey still on hold
274
+ starts its 24 hours again, and the account is as it was before. Adding it is in the account's log and "Worth a look" in
275
+ Activity ("First passkey added in a tailnet session"); so is the removal.
276
+ - **After the 24 hours** it is an ordinary passkey: removing it needs a passkey check. If you find a passkey that is not
277
+ yours then, or cannot reach the server from a tailnet device, the server's operator removes it:
278
+ `shapewall hosted admin passkeys list|remove` ([Operator commands](#operator-commands-and-quotas)).
279
+
280
+ A tailnet identity is per device, so whatever runs as you on one of your devices could add a passkey of its own; the hold,
281
+ the notice and the removal are what stand between that and your account. So add your passkey before you need it, and look
282
+ at the notice when you did not. We chose this over "ask the proxy again": a second request through the proxy proves nothing
283
+ the first did not.
284
+
285
+ - **Ending your other sessions** ("Sign out other devices") needs a session that passed a passkey check at some point, or an
286
+ account with no passkey at all. A tailnet session of an account that has a passkey confirms with it once.
287
+ - **Signing up with a passkey while you arrive through the tailnet does not link your login.** The sign-up page has a box,
288
+ "Also sign me in from this tailnet login", off by default. Ticked, the link is in the account's log (`tailnet_linked`).
289
+ - **`shapewall login` and `agent connect`** are approved in the browser by a tailnet-signed-in admin with no passkey, or with no
290
+ browser at all ([From your coding agent](#from-your-coding-agent)), unless the workspace switched on "Approve command line
291
+ logins in the browser": then the server takes an approval only from a session with a passkey check in the last 10 minutes,
292
+ whatever the client is and whatever it sends. The same switch keeps a session that only a tailnet identity stands behind
293
+ from making an API token and from inviting or making an admin (an admin could do the first two); it covers those three
294
+ things and nothing else that session's role allows.
295
+ - **People from another tailnet who accepted a share of this machine** do carry a login (Tailscale sets the headers for them).
296
+ They are visitors like anyone else: listed for the admins, in nothing until invited.
297
+
298
+ ### How the server knows a request came through tailscale serve
299
+
300
+ The identity headers are only as good as the path they came by. `tailscale serve` removes any `Tailscale-User-*` header a client
301
+ sent and sets its own, for traffic from tailnet users only: none for tagged devices, none for Funnel
302
+ ([Tailscale: identity headers](https://tailscale.com/kb/1312/serve#identity-headers)). But the server listens on `127.0.0.1`, and
303
+ other things can open that port and write the same headers:
304
+
305
+ - any program on the machine, directly;
306
+ - any program on the machine, through tailscaled: it asks for the server's own tailnet address
307
+ (`https://board.example.ts.net/`), and serve answers its own machine like any other device, with the machine owner's login;
308
+ - a tailnet device, when tailscaled runs in userspace-networking mode: its netstack forwards a raw TCP connection to the
309
+ machine's tailnet address, on a port serve does not handle, to `127.0.0.1:<same port>`, and tailscaled itself dials it;
310
+ - a local user through tailscaled's own dialler (`tailscale nc`, before Tailscale 1.98), or through tailscaled's SOCKS5 or
311
+ outbound HTTP proxy.
312
+
313
+ The last three arrive from a socket that tailscaled owns. So no single check is proof, and an identity is believed only when
314
+ **all** of these hold:
315
+
316
+ 1. **The secret.** At each start the server makes a random secret and points its serve entry at
317
+ `http://127.0.0.1:<port>/_ts/<secret>`. Serve puts the path of its target in front of every request it proxies; a raw
318
+ forward, a dial or a proxy passes the client's own path. A request without the secret is never asked who it is. This stops a
319
+ tailnet device, and anything else that cannot read this machine's serve config. **It does not stop a local user:** any local
320
+ user can read the serve config (`tailscale serve status` works for a user who is not the Tailscale operator; checked), secret
321
+ included. The secret is in no log line, error or response; a wrong one gets a plain 404.
322
+ 2. **The peer.** The connection's other end must be a socket owned by root, the user tailscaled runs as. On Linux the kernel
323
+ lists every TCP socket with its owner in `/proc/net/tcp`, and the server looks the peer up for each connection. This stops
324
+ a local program that connects to the port itself, though it has the secret: its socket is its own. It does not stop a local
325
+ program that asks tailscaled for the serve address (check 4 does). There is no setting to name another user.
326
+ 3. **tailscaled vouches.** For each request the server asks tailscaled who owns the address in `X-Forwarded-For` (which serve
327
+ sets to the tailnet address the request came from): `tailscale whois`. It must be a user's device, not tagged, with a key
328
+ that has not expired, of the same login as the header, and the answer must name the user by Tailscale's id. Kept for a minute per connection and address. Not proof alone (the address is a header too), required
329
+ in addition.
330
+ 4. **Not this machine.** A request whose source is the server's own machine is never taken by its tailnet identity. Any
331
+ program there, under any user, can ask tailscaled for the serve address; serve then sets the machine owner's login, adds the
332
+ secret and dials the server from a root socket, and whois agrees. Nothing in such a request says which local user or
333
+ program made it. So the server refuses when the address in `X-Forwarded-For` is one of this node's own tailnet addresses
334
+ (IPv4 or IPv6, from `tailscale status --json`, read again every 30 seconds), or when whois says the address belongs to this
335
+ node (compared by the node's stable id, not by a name). The machine's network interfaces are read on every request as
336
+ well, so an address tailscaled was given a moment ago counts at once. If the server cannot tell which node it is, nobody
337
+ is believed.
338
+ What this means for the owner: [On the server's own machine](#on-the-servers-own-machine).
339
+ 5. **The headers are clean.** Exactly one `Tailscale-User-Login`, no `Tailscale-Funnel-Request`, a value that is plain ASCII or
340
+ RFC 2047 encoded UTF-8 (what Tailscale sends for non-ASCII names) and reads as `user@domain`. Twice, empty, another
341
+ character set, a broken escape: nobody.
342
+ 6. **The request is from this origin.** The proxy adds the identity to every request a device makes, also one that a page on
343
+ another site made the browser send. So the identity alone only answers `GET /auth/me` with `Sec-Fetch-Site: same-origin`
344
+ and the `POST /auth/tailnet/*` routes (same-origin and JSON, as for every write). Everything else needs the session cookie
345
+ as before. `GET /auth/me` never makes a session: for a linked login it answers `"tailnet":{"state":"linked"}`, and the
346
+ console and the command line then sign in with `POST /auth/tailnet/sign-in` (rate limited per login). An account keeps at
347
+ most 20 tailnet sessions per login; signing in again past that ends the oldest.
348
+
349
+ **The feature refuses to turn on, and the server does not start,** when the peer check would not mean what it must. While the
350
+ server runs the same is checked every 30 seconds, and nobody is signed in by tailnet identity until it is right again (tailnet
351
+ sessions stop counting and their open live streams are cut; passkey sessions go on; the log says why):
352
+
353
+ - not Linux (macOS and Windows have no such table), `/proc/net/tcp` unreadable, or a test connection from the server itself not
354
+ recognised;
355
+ - tailscaled in **userspace-networking mode** (`tailscale status --json` says `TUN: false`, or it was started with
356
+ `--tun=userspace-networking`);
357
+ - **Tailscale older than 1.98**;
358
+ - tailscaled running a **SOCKS5 or outbound HTTP proxy** (`--socks5-server`, `--outbound-http-proxy-listen`, read from its
359
+ command line in `/proc`);
360
+ - no tailscaled of root found, more than one, or its command line not readable. Which process is tailscaled: where systemd
361
+ runs it, the main process of `tailscaled.service` (`systemctl show -p MainPID`) and no other, whatever else on the machine
362
+ is called `tailscaled`; without systemd, a process named `tailscaled` (where `/proc/<pid>/exe` can be read, the program
363
+ file itself must be). In both cases only a process that is root in all four of its ids (the `Uid:` line of
364
+ `/proc/<pid>/status`): a setuid-root program that an ordinary user started under that name is ignored, cannot be mistaken
365
+ for the daemon, and cannot switch the feature off;
366
+ - tailscaled started with `TS_DEBUG_NETSTACK_LOOPBACK_PORT` or `TS_DEBUG_NETSTACK_SUBNETS` in its environment (debugging
367
+ switches that make tailscaled forward tailnet connections to loopback), when the server can read that environment;
368
+ - the server cannot tell which node it is (`tailscale status --json` without `Self.ID` or without its tailnet addresses);
369
+ - the server in a **container or a user namespace**, where "root" may not be the machine's root (a `/.dockerenv` or
370
+ `/run/.containerenv` file, a container cgroup, `container` or `KUBERNETES_SERVICE_HOST` in the environment, or a uid map
371
+ that is not the machine's own);
372
+ - the serve config not the one entry the server added: a raw TCP forward to its port (under any spelling of loopback), another
373
+ serve entry to it, Funnel on its port, or its own entry gone or changed.
374
+
375
+ Run with passkeys in those cases (`--tailscale` without `--tailnet-sign-in`).
376
+
377
+ **What is still trusted.** Root on the server's machine, and whoever may change tailscaled's serve config there (the Tailscale
378
+ operator). Either can pretend to be anyone. Nothing else on the machine is trusted, and nothing on the tailnet. tailscaled's
379
+ environment is part of that root configuration: `/proc/<pid>/environ` of a root process is readable only by root, so a server
380
+ that runs as an ordinary user (as it should) cannot see the two debugging switches above and trusts root not to have set them.
381
+
382
+ ### On the server's own machine
383
+
384
+ The server's own machine is never signed in by its tailnet identity, in the browser or from the command line: a request from
385
+ there proves only that something on the machine made it. What to use there instead:
386
+
387
+ - **Hosted server: two ways.**
388
+ 1. **Another tailnet device of yours.** Your phone or laptop opens the server and is you. The sign-in page on the server's
389
+ machine says so: "This is the server's own machine: the server never takes a tailnet identity from here".
390
+ 2. **The operator's commands on the machine, with the data folder.** Being able to read and write the data folder is the
391
+ proof, as for `hosted claim`. They cover what an owner needs there:
392
+
393
+ ```sh
394
+ shapewall hosted claim --data ./hosted-data --login ada@example.com # the first account
395
+ shapewall hosted admin members list --data ./hosted-data
396
+ shapewall hosted admin members add --login ben@example.com --role admin --data ./hosted-data
397
+ shapewall hosted admin members remove --handle ben --data ./hosted-data
398
+ shapewall hosted admin members relink --handle ben [--login ben@new.example] --data ./hosted-data
399
+ shapewall hosted admin members unlink --handle ben --data ./hosted-data
400
+ shapewall hosted admin invites list|create --login cyd@example.com|revoke ID --data ./hosted-data
401
+ shapewall hosted admin projects list --data ./hosted-data
402
+ shapewall hosted admin passkeys status|on|off --data ./hosted-data
403
+ shapewall hosted admin passkeys list|remove ID --login ada@example.com --data ./hosted-data
404
+ ```
405
+
406
+ `members add` puts an existing account in at once (or changes its role); a tailnet login with no account yet gets an
407
+ invite that only that login can take. `members remove` also revokes the invites, share links and API tokens that person made. With
408
+ several workspaces add `--workspace ID`. Every one of these is in the operator log and in the workspace's audit log as
409
+ "Server operator".
410
+
411
+ `shapewall login` and `shapewall agent connect` on the server's machine fall back to the code (approve it in a browser on
412
+ another device); `shapewall join` and `shapewall admin` say to run them on another tailnet device. Where passkeys are
413
+ allowed, a passkey session works from the machine as from anywhere.
414
+
415
+ - **Local board** (`shapewall serve --tailscale`). On the machine itself open `http://localhost:<port>`: the board's own
416
+ machine is the owner there by the settings token, as without Tailscale. The tailnet address opened from the machine itself
417
+ asks to pair, and the pairing page says why. On a local board a peer check that fails its self test at start keeps
418
+ identity off until the board is started again; the 30 second watch never switches it back on.
419
+
420
+ One consequence to know: an owner who works only on the server's machine and has no second tailnet device cannot open the
421
+ console of a tailnet sign-in server from there. The operator's commands above are for that; for the console itself, use a
422
+ second device, or run the server with passkeys and reach it [over SSH](#over-ssh) instead.
423
+
424
+ **An identity is per device, not per person.** Tailscale says which device a request came from and whose device it is. It
425
+ cannot say that the person is at the keyboard. Anything running as you on a tailnet device of yours (a script, a coding agent,
426
+ a browser extension, malware) can act as you here, as far as a tailnet session goes. That is why the fixed core asks for a
427
+ passkey, why a first passkey is on hold for a day, and why a workspace can require a passkey for approving machines and for making
428
+ tokens ("Approve command line logins in the browser": with it on, a session that only a tailnet identity stands behind can
429
+ neither approve a command line login nor make an API token on a project's page; alone, the first would be no barrier, since
430
+ a token is what a command line works with). If that is not acceptable for your team, use passkeys.
431
+
432
+ **An account is held to the tailnet user, not to the login's spelling.** A login is a name (`ada@example.com`), and a name can
433
+ be given to someone else later, or a node shared in from another tailnet can carry one that reads the same. So when a login is
434
+ linked the server keeps Tailscale's own id of the user (from `tailscale whois`, `UserProfile.ID`), and every later request must
435
+ carry the same id: a request with the right login and another id is nobody ("This tailnet login belongs to someone else here"),
436
+ and so is a whois answer with no user id at all. If that happens to your own account (Tailscale gave you a new user id:
437
+ the tailnet moved to another identity provider, or you were removed and added again), the page shows the command for
438
+ whoever runs the server: `shapewall hosted admin members relink --login you@example.com --data DIR` forgets the stored id,
439
+ so the next arrival as that login is taken as the account's person. `members relink --handle HANDLE --login NEW` links the
440
+ account to another login, and `members unlink --handle HANDLE` takes the login off. The operator decides because nobody
441
+ in the product can tell a new id for the same person from the same name given to someone else; each is in the operator log
442
+ and in the account's own log. A link made by `hosted claim --login` knows only the name: it takes the id of
443
+ the first proven request that arrives as that login, so open the server from your own device soon after claiming. A device
444
+ whose key has expired is nobody.
445
+
446
+ **"Root on this machine" is what the peer check proves, and no more.** It shows that the connection was opened by a process of
447
+ this machine's root. That this process is tailscaled's serve proxy follows from the other checks (the secret, the refusal
448
+ list below it, the serve config). And Tailscale's identity is the device's: **several OS users of one tailnet device all count
449
+ as that device's owner**. A family computer signed in to Tailscale as Ada signs every one of its users in as Ada. Tailscale's
450
+ serve documentation does not spell this out; it follows from how the identity headers are made (from the connection's source
451
+ device).
452
+
453
+ ### What was and was not checked against real Tailscale
454
+
455
+ Checked on a real machine (Tailscale 1.104.2, Linux), read-only:
456
+
457
+ - `tailscaled` runs as root, and its command line is readable in `/proc` by an ordinary user;
458
+ - `tailscale status --json` has `TUN` (true there) and `Version` ("1.104.2-...");
459
+ - `tailscale serve status --json` has the shape the server reads for an HTTPS entry (`TCP`, `Web`, `Handlers`, `Proxy`), and
460
+ **a user who is not the operator can read it** (run as `nobody`): the secret is not secret from local users;
461
+ - `tailscale whois --json <address>` answers `Node` and `UserProfile.LoginName` for this machine's own tailnet address, and
462
+ "peer not found" for an address that is nobody's;
463
+ - `tailscale status --json` has `Self.ID` and `Self.TailscaleIPs` (IPv4 and IPv6), and whois on one of those addresses
464
+ answers `Node.StableID` equal to `Self.ID`;
465
+ - one capture of real requests through an existing serve entry, made from the machine itself: the request arrived from a
466
+ root-owned socket, with the entry's path in front, the identity headers set to the machine owner's login, and exactly one
467
+ `X-Forwarded-For` holding one of the machine's own tailnet addresses. That is the request check 4 refuses;
468
+ - the `/proc/net/tcp` lookup names the right owner for a real loopback connection (a test in the suite, on Linux).
469
+
470
+ **Run against a real tailscaled** (Tailscale 1.102.5, Linux, kernel mode, other serve entries on the machine, and a second
471
+ tailnet device), with a build of this release from before the last review round:
472
+
473
+ - the serve entry with the `/_ts/<secret>` target was accepted, and requests arrived with the secret path in front;
474
+ - a visitor from the other device was recognised by login, over IPv4 and IPv6, with the real whois;
475
+ - forged `Tailscale-User-Login`, `Tailscale_User_Login` and `X-Forwarded-For` headers sent by that visitor were ignored;
476
+ - a guessed secret path got 404, and the server's local port was not reachable from the tailnet;
477
+ - the server's own machine got "This is the server's own machine" by the server's name, by its own IPv4 and by its IPv6;
478
+ - a direct loopback request with a forged header was nobody, without the secret and with the real one;
479
+ - `hosted claim --login`, then from the other device `admin projects create` and `list`, `admin members list`, `admin agents
480
+ list` and `login --project` with no code; `admin` from the server's own machine was refused with its message;
481
+ - stopping the server removed its serve entry, and Tailscale 1.94 was refused at start with its message.
482
+
483
+ That run was made before four things in this release existed, so they are covered by the suite's stand-in only: holding an
484
+ account to Tailscale's id of the user (`UserProfile.ID` in whois), finding tailscaled by its systemd unit, reading the
485
+ machine's network interfaces on every request, and the server without passkeys (typed confirmation, the operator's
486
+ commands).
487
+
488
+ Read in Tailscale's source (`ipn/ipnlocal/serve.go`, `wgengine/netstack`, `cmd/tailscaled`), not run: that the userspace
489
+ netstack forwards raw TCP to loopback; the proxy flags; the debug switches.
490
+
491
+ **Not checked against a live serve:**
492
+
493
+ - **a tagged device** (how `tailscale whois --json` marks it on your version; the code reads `Node.Tags`), and a device
494
+ shared in from another tailnet;
495
+ - **the suspension within 30 seconds** when the serve config changes under a running server (a raw TCP forward, Funnel, the
496
+ entry changed), and that sign-in comes back when it is put right;
497
+ - **a sign-in in a real browser** through the tailnet (the browser tests send the headers themselves);
498
+ - and, smaller: whether the server can read `/proc/<pid>/environ` of tailscaled anywhere it is meant to run (as an ordinary
499
+ user it cannot), and the time `tailscale whois` takes per new connection under load.
500
+
501
+ [Checking it on your own tailnet](#checking-it-on-your-own-tailnet) below goes through all of it, these three included.
502
+
503
+ ### Checking it on your own tailnet
504
+
505
+ The tests run without a tailnet, against a stand-in for `tailscale serve`. Before you rely on tailnet sign-in, check it on
506
+ yours. You need the server's machine, a second tailnet device of your own, and if you can a tagged device and a device of
507
+ another person. Nothing here changes any setting except starting the server.
508
+
509
+ 1. **Start it and read what it says.** `shapewall hosted --data ./hosted-data --tailscale --tailnet-sign-in`. It either prints
510
+ the private address or refuses and says why ([the list](#how-the-server-knows-a-request-came-through-tailscale-serve)).
511
+ A refusal is the feature working: run with passkeys there.
512
+ 2. **The serve entry.** `tailscale serve status --json` on the server's machine shows one HTTPS entry whose `Proxy` is
513
+ `http://127.0.0.1:<port>/_ts/<a long secret>`, no `TCP` forward to that port and no Funnel.
514
+ 3. **Claim, from the server's machine:** `shapewall hosted claim --data ./hosted-data --login <your tailnet login>`. It prints
515
+ the owner account and the login it linked.
516
+ 4. **From your second device, open the address.** You are signed in as that account with no passkey. Account, "Devices"
517
+ shows a session marked tailnet. This is the one check that needs a real request from another device; the suite cannot
518
+ make it.
519
+ 5. **From the server's own machine, open the same address.** You must not be signed in: the page says "This is the server's
520
+ own machine". `curl -s https://<name>.ts.net/auth/me -H 'Sec-Fetch-Site: same-origin'` there answers
521
+ `"tailnet":{"state":"self"}`. If it signs you in, stop and report it.
522
+ 6. **Forge it.** On the server's machine: `curl -s http://127.0.0.1:<port>/auth/me -H 'Tailscale-User-Login: <your login>'
523
+ -H 'Sec-Fetch-Site: same-origin'` must answer `"user":null` and never `"state":"linked"` (a `GET` makes no session anywhere; `linked` would mean the forged login was believed), and so must the same request with the `/_ts/<secret>` path
524
+ from the serve config in front and `-H 'X-Forwarded-For: <your second device's tailnet address>'`. The server log has
525
+ "ignored identity headers" with the check that failed (the connection did not come from tailscaled).
526
+ 7. **A tagged device, and another person's device,** if you have them: the first sees "Your tailnet did not say who you
527
+ are", the second "Ask an admin of a workspace here to invite ..." and appears under Members, "Arrived through the
528
+ tailnet". Neither is in anything.
529
+ 8. **The first passkey, if you allowed passkeys** (`shapewall hosted admin passkeys on`; without it the Account page has no
530
+ passkeys and step 8 does not apply). On the second device add a passkey on the Account page: it asks you to confirm the device by name,
531
+ then every page shows "A passkey was added from ...". Press "Not you? Remove it" from a third device or the same one: it
532
+ is gone, with no passkey prompt. `shapewall hosted admin passkeys list --login <your login> --data ./hosted-data` on the
533
+ server shows the same.
534
+ 9. **Break it and watch it stop.** `tailscale serve --tcp=<port> tcp://127.0.0.1:<port>` on the server's machine (a raw
535
+ forward to the server's port); within 30 seconds the log says tailnet sign-in is suspended and the second device is
536
+ signed out. Remove the forward (`tailscale serve --tcp=<port> off`): sign-in comes back. Do this only on a machine whose
537
+ serve config is yours to change.
538
+ 10. **Which tailscaled.** `systemctl show -p MainPID --value tailscaled.service` is the process the server checks; its
539
+ `Uid:` line in `/proc/<pid>/status` is `0 0 0 0`. Without systemd the server goes by the process name.
540
+
541
+ What to send us if a step fails: the Tailscale version, the step, and the "ignored identity headers" line. Not the serve
542
+ config: it holds the secret.
543
+
544
+ ### From your coding agent
545
+
546
+ On a server with tailnet sign-in, an agent or a terminal on a tailnet machine is already known to the server as that machine's
547
+ tailnet user. Nothing below needs a browser unless it says so. Each command asks the server who it is (through `tailscale
548
+ serve`, by the same rule as the browser), gets a session that works only with that identity, uses the console's own API with it
549
+ (the same role checks, the same audit entries, marked as a tailnet session from "Shapewall CLI"), and signs out when it ends.
550
+ No admin token is stored anywhere.
551
+
552
+ **1. An owner sets up a server and a first project.** On the machine that runs the server:
553
+
554
+ ```sh
555
+ shapewall hosted --data ./hosted-data --tailscale --tailnet-sign-in & # needs Tailscale, MagicDNS and HTTPS certificates
556
+ shapewall hosted claim --data ./hosted-data --login ada@example.com --workspace-name "Team" # no browser
557
+ ```
558
+
559
+ Then on another tailnet device of the owner's (the server's own machine is never signed in by its tailnet identity:
560
+ [why](#on-the-servers-own-machine)):
561
+
562
+ ```sh
563
+ shapewall admin projects create "My site" --remote https://board.example.ts.net
564
+ shapewall login --remote https://board.example.ts.net # no code, no browser: a token for the project
565
+ shapewall push --remote https://board.example.ts.net
566
+ shapewall admin invites create --login ben@example.com --role admin --remote https://board.example.ts.net
567
+ ```
568
+
569
+ `hosted claim` reads the one-time setup link from the data folder: being able to read that folder is the proof, as it is for
570
+ `hosted setup-link`. It does not ask the tailnet who you are, because on the server's own machine the tailnet cannot say.
571
+ `--login` names the owner's tailnet login and is required; it must read as a login (`ada@example.com`), it is taken on your
572
+ word, and the command prints what it linked: the server's address, the owner account and its handle, the tailnet login, the
573
+ workspace. A server is claimed once: with an account already there, or the setup link used or replaced, the command refuses.
574
+ The audit log records the account and the link as made by "hosted claim on the server". From another tailnet device, with the
575
+ setup link in hand, `shapewall hosted claim --setup-link URL` asks the server who is asking instead, and `--login` there only
576
+ refuses anyone else. No passkey is made and none is needed: the Tailscale account is the sign-in. The few things Shapewall
577
+ always asks about need `--yes` on the command line (`shapewall admin invites create --role owner --yes`), which names what
578
+ it confirms. Where the operator allowed passkeys, an account that has one confirms those in the browser instead.
579
+
580
+ **2. A member joins and connects their machine.** On their own tailnet machine, after an admin invited their login:
581
+
582
+ ```sh
583
+ shapewall join --remote https://board.example.ts.net # takes the invite made for your login
584
+ shapewall agent connect --remote https://board.example.ts.net --project my-site --name "Builder"
585
+ ```
586
+
587
+ `join` reports the workspace, your role and its projects. With an invite link instead: `shapewall join --remote URL --invite
588
+ LINK`. The role is always the invite's; there is no way to choose one, and no way into a workspace that did not invite you.
589
+ `agent connect` (and `shapewall login`) is approved by your own tailnet identity when your role may make tokens (admin or owner),
590
+ with the scopes the browser's approval page gives; the audit entry says "approved by tailnet identity" with the machine's name.
591
+ A member or viewer gets the usual code, for an admin to approve in the browser. **Needs a browser:** nothing, for an admin.
592
+
593
+ The rules of those commands:
594
+
595
+ - **Which project.** `--project <slug>` (and `--workspace <name>` when you are in several). With one project it is picked.
596
+ Otherwise the command lists the projects with the exact flags to add and exits with an error. It never prompts.
597
+ - **An agent's look and audience** come from flags: `--name`, `--icon`, `--tint`, `--used-by owner|trusted` (default `owner`:
598
+ only you). Named members are picked in the console.
599
+ - **A workspace can require the browser and a passkey:** Settings, "Approve command line logins in the browser" (owners). The
600
+ server then refuses an approval from any session that only a tailnet identity stands behind (no passkey check in the last 10
601
+ minutes): `login` and `agent connect` show the code, and whoever approves it confirms with a passkey. Such a session can
602
+ then not make an API token or invite or make an admin either (`shapewall admin invites create --role admin` says so). This is decided by the
603
+ server from the session; nothing the command line or a browser sends changes it. A workspace that asks for a passkey for
604
+ "Agents and machines" gets the code too.
605
+ - **When it does not apply** (the server has no tailnet sign-in, the request did not come through the tailnet, a tagged device, a
606
+ login with no account): `login` and `agent connect` use the code and the browser, unchanged. `join` says that an account
607
+ needs a passkey, which is made in the browser, and gives the link. `admin` says it would need an admin token, which does not
608
+ exist yet, and points at the console.
609
+ - **The admin commands** are these and no more: `admin projects list|create NAME`, `admin invites create --login LOGIN | --link
610
+ [--role ROLE] [--days N]`, `admin members list`, `admin agents list` (`--json` for scripts).
611
+
61
612
  ## Accounts
62
613
 
63
614
  - **Passkeys only.** No email, no passwords. Sign-up and sign-in use discoverable credentials with user verification required, so
@@ -70,7 +621,7 @@ Deployment examples: [examples/hosted/shapewall-hosted.service](../examples/host
70
621
  has not used before is marked "Signed in on a new device" in Account activity.
71
622
  - **Recovery codes.** Ten one-time codes (about 128 bits each), stored as SHA-256 hashes, shown once. A code plus your handle signs you
72
623
  in and ends every other session of the account (a stolen device loses its session). That session is never "fresh": in its first 30
73
- minutes it can add a passkey, and nothing sensitive. A passkey added that way signs in, but is on hold for 24 hours before it can
624
+ minutes it can add a passkey, and nothing that ever asked for a passkey check. A passkey added that way signs in, but is on hold for 24 hours before it can
74
625
  confirm sensitive actions, so someone with one stolen code cannot lock the owner out: the owner's own passkey still removes theirs
75
626
  (which ends their sessions) and makes new codes. Making new codes voids the old ones. Lose every passkey and every code and the
76
627
  account is gone, but its work is not: projects belong to workspaces, so an admin removes the old member and invites the new account.
@@ -79,19 +630,19 @@ Deployment examples: [examples/hosted/shapewall-hosted.service](../examples/host
79
630
  90 days at most. Signing in replaces the browser's previous session. The Account page lists your signed-in devices (browser and OS
80
631
  from the user agent, IP, last used); sign one out, or "Sign out other devices" for all of them. Removing a passkey also ends the
81
632
  other sessions. The list carries a session id, never the cookie or its hash.
82
- - **Admin idle expiry.** For an admin or owner, workspace pages and APIs need a passkey check after 12 hours without using any of
83
- them (403 `reauth_required`; the console shows "Confirm it's you" and loads again). The session itself stays signed in.
84
- - **Re-auth.** Creating API tokens or share links, turning share links on, adding or removing a passkey, new recovery codes, deleting
85
- a project or the workspace, signing out devices, changing or removing an admin or owner, making someone an admin or owner and
86
- inviting an admin or owner, turning public projects on, making a project public and starting a move of your sign-in to a new origin
87
- need a passkey check (not on hold) in the last 10 minutes; the console asks for it ("Confirm it's you")
88
- when needed. In a recovery-code session, which has no passkey to confirm with, it says "Add a passkey first" and links to adding
89
- one (or lets you use a passkey you still have, which turns the session into a passkey session).
633
+ - **Asking for the passkey again.** By default a signed-in session with the right role is enough. A small fixed core always asks
634
+ (passkeys, recovery codes, deleting the account or a workspace, owners, moving the server), and a workspace's owner can switch
635
+ more on: [When Shapewall asks for the passkey again](#when-shapewall-asks-for-the-passkey-again). In a recovery-code session,
636
+ which has no passkey to confirm with, the prompt says "Add a passkey first" and links to adding one (or lets you use a passkey
637
+ you still have, which turns the session into a passkey session). Such a session, and one started by a passkey that is still on
638
+ hold, is asked for everything the workspace settings cover, whatever they are set to.
639
+ - **Tailnet sign-in.** On a server run with `--tailscale --tailnet-sign-in`, an account can be linked to a tailnet login and is
640
+ then signed in without a passkey: [Tailnet sign-in](#tailnet-sign-in).
90
641
  - **Account activity.** The Account page lists your own security events, newest first: sign-ins (passkey or recovery code, with the
91
642
  device and IP), passkeys added and removed, new recovery codes, devices signed out (`GET /auth/security-log?before=`). After a
92
643
  recovery code was used on your account, the next passkey sign-in shows a banner until you dismiss it ("That was me",
93
644
  `POST /auth/security-notice/seen`); `GET /auth/me` carries it as `securityNotice`.
94
- - **Deleting your account.** Account page, "Delete account": a fresh passkey check and your handle typed back
645
+ - **Deleting your account.** Account page, "Delete account": a fresh passkey check (always) and your handle typed back
95
646
  (`DELETE /auth/me` with `{ confirm, revokeTokens }`; `POST /auth/delete-account/preview` shows the plan first). Workspaces where you
96
647
  are the only member are deleted with it; in the others you leave (your pending invites and share links are revoked, and your API
97
648
  tokens unless you untick that). It is refused while you are the only owner of a workspace that has other people in it: make one of
@@ -114,6 +665,10 @@ Projects belong to a workspace, never to a person. Roles:
114
665
 
115
666
  The console shows this table on **Access, Roles** and next to every role picker.
116
667
 
668
+ From 0.7.0: a member also reads their own agent usage (and that of agents they connected), and everyone reads their own
669
+ activity. Admins and owners read the workspace's usage, everyone's activity and the access review
670
+ ([Usage and activity](#usage-and-activity)).
671
+
117
672
  **Renaming a token.** An agent that watches a hosted board signs its comments and replies with its token's name (for a terminal
118
673
  login, "laptop (shapewall login)"). **Rename** on the token lists (the project page and **API tokens**) gives it a human name:
119
674
  `PATCH /api/workspaces/:ws/projects/:pid/tokens/:tid` with `{ "name": "..." }`, 1 to 60 characters, for the same people who may revoke
@@ -141,7 +696,7 @@ token has a creator. An admin removing someone may keep their tokens (`{ revokeT
141
696
  kept tokens are `inactive` and refused until the creator is an admin here again, so revoke them and make new ones.
142
697
 
143
698
  **Share links** let an admin share one project's boards with someone who has no account. They are off for every workspace until an
144
- admin turns them on (Settings, which asks for a passkey check); turning them off stops every link at once, and turning them back on
699
+ admin turns them on (Settings); turning them off stops every link at once, and turning them back on
145
700
  restores the ones that are not revoked or expired.
146
701
 
147
702
  - A link reaches exactly one project. It is **view-only** or **comment** (guests give a display name, 1 to 40 characters), expires
@@ -177,7 +732,7 @@ restores the ones that are not revoked or expired.
177
732
  passcodes collapse into one row per link and hour, with a count (and up to 10 guest names).
178
733
 
179
734
  **Public projects** put one project on the open web, view-only. They are off in every workspace until an owner turns them on
180
- (Settings, with a passkey check). Then an owner makes a project public on its page (again with a passkey check): it gets a public
735
+ (Settings). Then an owner makes a project public on its page: it gets a public
181
736
  id of 128 random bits and the URL `/p/<public id>/`, shown there to copy.
182
737
 
183
738
  - Anyone with the URL sees the project's boards and comments as a view-only share link guest does, except that every guest is
@@ -197,7 +752,8 @@ Projects and Members; admins and owners see everything.
197
752
 
198
753
  - **Members.** Everyone with their role, when they joined and when they were last active (updated at most every 5 minutes). Change a
199
754
  role from the picker or remove someone from the row menu; both ask first. Admins manage members and viewers; only an owner changes
200
- or removes an admin or an owner, and that needs a fresh passkey check, as does making someone an admin or owner. The last owner
755
+ or removes an admin or an owner. Anything that makes, changes or removes an owner always asks for the passkey; the same for
756
+ an admin when the workspace asks for it (Settings, "Members and roles"). The last owner
201
757
  cannot be demoted, removed or leave. Removing, or demoting below admin, revokes the person's pending invites, share links and API
202
758
  tokens (the confirm dialog says so). When the person made API tokens that still work, the remove dialog lists them with "Revoke"
203
759
  checked; unchecking it keeps them, inactive (`DELETE /members/:user` with `{ revokeTokens: false }`); the audit entry says whose
@@ -221,10 +777,14 @@ Projects and Members; admins and owners see everything.
221
777
  (`q`: names, handles, projects, tokens, links, details); 50 a page, newest first, "Load older events" for more. Each entry shows the
222
778
  relative and the exact time. "Export CSV" downloads up to 10,000 entries with the same filters (`GET /audit/export`; cells that
223
779
  start with `=`, `+`, `-` or `@` get a leading `'` so a spreadsheet does not run them).
780
+ - **Usage.** Every agent turn with the numbers each agent reported: tiles against the period before, charts, a grid of every turn,
781
+ saved views and exports ([Usage and activity](#usage-and-activity)).
782
+ - **Activity.** What people did, read from the audit log: sign-ins, settings with before and after, agents, approvals, tokens and
783
+ exports; a page per person and per agent; and the access review.
224
784
  - **Settings.** Rename (admins), share links on or off (admins), public projects on (owners) or off (admins), export (admins), leave, and delete the workspace (the owner, with a
225
785
  passkey check and the workspace name typed back). Deleting removes every project, board, file, comment, token, invite, share link and
226
786
  audit entry, and writes one `workspace_deleted` entry to the account log.
227
- - **Export.** "Download a copy" (admins, with a fresh passkey check; `POST /export`; one at a time per workspace, 409 while one runs,
787
+ - **Export.** "Download a copy" (admins; `POST /export`; one at a time per workspace, 409 while one runs,
228
788
  and 5 an hour per person) streams a zip: `workspace.json` (the workspace,
229
789
  members, projects, tokens without their secrets, share links without theirs), `audit.json`, and per board `board.json`,
230
790
  `comments.json` and its files (captures, variants, versions, live HTML), and `chats.json` when the board has chat with a
@@ -275,7 +835,9 @@ shapewall push --remote https://app.example.com # and comments, watch, mcp --
275
835
  It prints a short code (like `BCDF-GHJK`) and opens `/device` in the browser (a URL the CLI builds from `--remote`, never one the
276
836
  server sends; on Windows through `rundll32 url.dll,FileProtocolHandler`, no shell). Someone with the admin role there types the code,
277
837
  checks that the page shows the same code, the address the login came from and how long ago it started, picks the workspace,
278
- project, scopes and expiry (30 or 90 days, or none), and approves with a passkey check. The machine name is shown as reported by the
838
+ project, scopes and expiry (30 or 90 days, or none), and approves (with a passkey check when the workspace asks for one
839
+ before "Agents and machines"). On a server with tailnet sign-in the command needs no code at all:
840
+ [From your coding agent](#from-your-coding-agent). The machine name is shown as reported by the
279
841
  terminal (unchecked), and the page warns when the login came from another address than the approver's. The CLI, polling `POST /api/v1/device/poll` every 3 seconds, receives the token once and saves it
280
842
  in `$XDG_CONFIG_HOME/shapewall/credentials.json` (or `~/.config/...`): the folder 0700, the file 0600, one entry per server origin.
281
843
  It never prints the token. The token is named `<machine> (shapewall login)` and listed with the others; revoke it there. A code
@@ -314,7 +876,7 @@ The server treats every upload as untrusted, even from our CLI:
314
876
  never to share link guests or public viewers. After a restart every agent reads offline, with the last time it was seen, until
315
877
  its next call.
316
878
  - **Removing a board.** A board pushed by mistake, or one you retired, comes off the server on the project page: "Remove board"
317
- on its row in the Boards list, for the same people who may delete the project (admins and owners, with a fresh passkey check).
879
+ on its row in the Boards list, for the same people who may delete the project (admins and owners).
318
880
  It deletes that board's captures, page history, variants, checks, comments, replies and comment images, and frees their storage;
319
881
  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
320
882
  captures are back, the comments are not. The audit log records who removed which board, and people who have the board open are
@@ -450,13 +1012,13 @@ comment, with a state and rules about who may use it. Nothing changes on the mac
450
1012
  does not take work from never reaches its token, however trusted they are by the agent policy. An audience governs new work: a
451
1013
  comment the agent already holds stays its own until it finishes, even if the audience is narrowed meanwhile, and sending a comment
452
1014
  again while an agent works on it changes nothing. On the board, an agent you may not use is listed, greyed, with the reason ("Only
453
- Ada can send work to Builder. Ask them, or an admin, to share it."). Changing an audience asks for a fresh passkey check.
1015
+ Ada can send work to Builder. Ask them, or an admin, to share it.").
454
1016
  **Tokens that already had the `claim` scope before 0.4.0 keep the behaviour they had**: everyone the agent policy trusts. The
455
1017
  console marks them "kept from before 0.4.0".
456
1018
 
457
1019
  - **Approvals.** Each agent has an approval rule and two roles: who may answer its approvals, and who may change the rule (admins and
458
1020
  owners, or owners only; only an owner changes those two). The rule in effect is **Ask every time** unless the agent's own machine
459
- says otherwise: what an agent asks to do waits for a person with that role and a fresh passkey check. **Allow without asking** is
1021
+ says otherwise: what an agent asks to do waits for a person with that role (and their passkey again when the workspace asks for it). **Allow without asking** is
460
1022
  listed as not available until the agent's own machine names what may go without asking (`shapewall agent connect --approvals
461
1023
  owner --auto edits`, on that machine). It is never the default and is never possible on the server's say alone. A
462
1024
  [connected agent](#connected-agents) reads and answers only until its machine switches edits on
@@ -515,7 +1077,8 @@ shapewall agent connect --remote https://wall.example.com
515
1077
  1. **The first run asks for an approval.** The command prints a short code and the address of the server's `/device` page. An admin
516
1078
  or owner of the workspace opens it, types the code, and sees "Connect an agent": the machine's name, the address it asked from,
517
1079
  and which agent it says it runs. They give the agent a name and an icon, choose the project, and choose who may use it. **Only
518
- me** is the default. Approving asks for a fresh passkey check.
1080
+ me** is the default. (On a server with tailnet sign-in, run on a tailnet machine by an admin, there is no code and no
1081
+ browser: [From your coding agent](#from-your-coding-agent).)
519
1082
  2. **The machine gets the agent's own token.** It is saved on that machine and never printed. The next run of the same command needs
520
1083
  no approval.
521
1084
  3. **The agent comes online.** It shows in the board's Agents panel and on the project's Agents page for as long as the command
@@ -721,7 +1284,13 @@ shapewall agent connect --remote https://wall.example.com --approvals none
721
1284
  from that branch, whatever the checkout holds. `--base head` goes back to the default.
722
1285
  - **`--git-remote NAME`** is where a finished fix is pushed (`origin` by default). `--git-remote none`: never pushed.
723
1286
 
724
- `agent connect` prints what is in effect when it starts. The console's Agents page and the board's Agents panel say which mode an
1287
+ `agent connect` prints what is in effect when it starts, and it says the same to the server with the code: the approval page
1288
+ shows what that machine asked for (read and answer only, or edits on a branch and who may allow them, "without asking" if it
1289
+ asked for `--auto edits`, the base branch, and that it never runs a command), marked "Reported by the terminal". The machine
1290
+ enforces its own rules; the server decides nothing by that report. Before it goes online, `agent connect` also opens a session
1291
+ with the agent (no prompt is sent) and prints which adapter version answered ([tested versions](agents.md#claude-code)).
1292
+
1293
+ The console's Agents page and the board's Agents panel say which mode an
725
1294
  agent is in: "Reads and answers", "Edits on a branch, each allowed by the person who connected it" (or "an admin", or "an
726
1295
  owner"), or "Edits on a branch, allowed without asking".
727
1296
 
@@ -852,7 +1421,8 @@ passes is shown in the comment's chat thread as a card:
852
1421
  - **A card is answered once.** Stop cancels the cards that wait.
853
1422
  - **Everyone with the thread open sees the state change live**: waiting, allowed and by whom, denied, expired, cancelled. The strip
854
1423
  above the board lists the cards that wait for you, and opens the comment's chat, where the diff is.
855
- - **Allow needs a passkey check in the last 10 minutes.** The browser asks for it. Deny does not: it only ever stops something.
1424
+ - **Allow asks for a passkey again only when the workspace says so** (Settings, "Agent edits and pushes"; off by default). The
1425
+ browser asks when the server does. Deny never does: it only ever stops something.
856
1426
 
857
1427
  **Who may answer.** Someone with the agent's answer role (admin by default), who is also in the agent's audience and trusted by
858
1428
  the project's agent policy. When the agent's machine says `--approvals owner`: only the person who connected it. Everyone else
@@ -880,8 +1450,8 @@ without asking**.
880
1450
  branch, and the commit is still kept only when it is exactly what was allowed.
881
1451
  - **Nothing reaches a remote without a person having seen the diff.** A fix with an edit that went without asking is committed
882
1452
  on its branch on the machine and held there. It is not pushed and no pull request is opened. The thread shows one
883
- **Push this fix** card with the whole changed-files diff. Someone who may answer the agent's cards allows it, with a fresh
884
- passkey, under the same rules as any card (the hash, once, the machine's own recheck); it waits 10 minutes. Denied or not
1453
+ **Push this fix** card with the whole changed-files diff. Someone who may answer the agent's cards allows it,
1454
+ under the same rules as any card (the hash, once, the machine's own recheck); it waits 10 minutes. Denied or not
885
1455
  answered, the fix stays on the machine and the result offers **Push this fix** again, as often as needed. A fix too large to
886
1456
  show in full cannot be pushed from the board at all.
887
1457
  - **If the machine connects again without it**, the stored rule is set back to "ask" at once, and that is in the audit log.
@@ -1053,7 +1623,7 @@ is still a good idea to give a connected agent a profile of its own: a separate
1053
1623
  Every chat turn writes one usage record: who asked, which agent, the board and thread (or comment), when it started and ended, and
1054
1624
  how it ended (answered, stopped, failed, interrupted). The model, the effort and the token counts are kept only when the agent
1055
1625
  reports them, and a cost only when the agent itself reports one: nothing is estimated, and "not reported" is not zero. A record
1056
- never holds a message or an answer. There is no page for them yet.
1626
+ never holds a message or an answer. They are shown on the Usage page: see [Usage and activity](#usage-and-activity).
1057
1627
 
1058
1628
  A fix is one usage record of kind "fix": its steps, how it ended (fix ready, answered, stopped, failed, interrupted), and how many
1059
1629
  requests it asked and how many were allowed and denied.
@@ -1100,6 +1670,270 @@ Fix with an agent is `POST .../threads/comment-<n>/messages` with `{ fix: true }
1100
1670
  thread's, `dispatchHash` for the text you saw). A card is answered with `POST .../threads/:thread/permissions/:id`
1101
1671
  (`{ optionId: "allow" | "deny", hash }`), and `GET agent/boards/:board/permissions` lists the cards that wait for you.
1102
1672
 
1673
+ ## Usage and activity
1674
+
1675
+ Two pages of the Workspace Console (Shapewall 0.7.0) answer two different questions. **Usage** is about agents: every turn an
1676
+ agent ran, with the numbers it reported. **Activity** is about people: who signed in, who changed what, who answered which
1677
+ approval. Activity is read from the audit log, which stays the security record; the two pages link to each other and are never
1678
+ merged.
1679
+
1680
+ To look before you install: the live demo has both pages, with about sixty days of made-up numbers
1681
+ ([Usage](https://shapewall.com/demo/console.html#/w/ws_4c756d000000000000000001/usage),
1682
+ [Activity](https://shapewall.com/demo/console.html#/w/ws_4c756d000000000000000001/activity)). There the queries run in your browser over
1683
+ a fictional history; everything on this page describes a real server.
1684
+
1685
+ ### What a usage record holds
1686
+
1687
+ One row per agent turn: a chat answer, a comment an agent answered, a fix, or the push of a fix. It is written when the turn
1688
+ starts and completed when it ends.
1689
+
1690
+ | Recorded | Where it comes from |
1691
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------- |
1692
+ | When it started and ended, how long | The server's own clock, from the question to the end of the turn |
1693
+ | Who asked | The signed-in person (nobody, when an agent took a queued comment by itself) |
1694
+ | Which agent, on which machine | The agent and the machine label it connected with; and who connected it |
1695
+ | Project, board, thread or comment | Ids. A private chat's id is shown only to the person who started it |
1696
+ | Kind | Chat, comment answer, fix or push |
1697
+ | Outcome | Answered, fix ready, needs a person, stopped, failed, interrupted, and a few "let go" states |
1698
+ | Model and effort | As the agent reported them |
1699
+ | Input, output and cached tokens | As the agent reported them |
1700
+ | Context used, of how much | As the agent reported it |
1701
+ | Cost | Only when the agent or its endpoint reported a cost |
1702
+ | Steps, and tool calls counted by type | The number of steps and a count per tool type ("read: 12, edit: 3"). Never a label or an argument |
1703
+ | Approvals | How many it asked, how many were allowed, how many without asking, how many denied, and by whom |
1704
+ | The agent's own time | How long the agent says it worked, when it says |
1705
+
1706
+ **Never recorded:** the question, the answer, file contents, file names from a step, a diff or a command. Those are in the thread,
1707
+ which has its own access rule (members and up; a private chat only its starter). A usage row links to the comment or board for
1708
+ people who may read it there.
1709
+
1710
+ **Nothing is estimated.** Shapewall has no table of model prices. Subscription CLIs often report tokens and no cost, and some
1711
+ agents report nothing. Wherever a number was not reported the pages say "Not reported" (a dash in a table, a hatched area in a
1712
+ chart), never zero, and each total says how many of its turns reported the number ("723 of 1,795 turns reported").
1713
+
1714
+ ### The Usage page
1715
+
1716
+ `/w/<workspace>/usage`. Everything on it follows one filter, shown in one row above it:
1717
+
1718
+ - **Period:** today, the last 7, 30 or 90 days, this week, this month, last month, or a custom range of up to 400 days. Days,
1719
+ weeks and months are in your browser's time zone (the server stores UTC), across any number of clock changes, north or south.
1720
+ Weeks start on Monday.
1721
+ - **Agent, project, person, kind, model, outcome:** several values each. "No model reported" and "nobody" are values too.
1722
+ - **Ranges** of tokens and of duration, and a **search over ids** (a turn, an agent, a project, a board, a comment number).
1723
+
1724
+ The filters live in the page's address, so a link is a view and Back undoes a filter.
1725
+
1726
+ **Overview** is a dashboard of widgets, which each person arranges for themselves ([Arranging the
1727
+ dashboard](#arranging-the-dashboard)). Unless you change it, it shows, for that filter:
1728
+
1729
+ - **Tiles:** turns, tokens, agent time, reported cost, fixes that ended ready, and the share that failed or was stopped, each with
1730
+ its change against the period to compare with, which the tile names: the same number of days just before (whole local days,
1731
+ whatever the clocks did); this week or this month so far against last week or last month up to the same day; last month against
1732
+ the month before.
1733
+ - **Usage over time:** stacked bars per day, week or month, split by agent, project, person, kind, model or outcome, measuring
1734
+ turns, tokens (total, input, output, cached), time or reported cost. Drag the bar under the chart to zoom, then "Use ... for the
1735
+ page" to keep that range.
1736
+ - **A breakdown:** ranked bars with each group's share.
1737
+ - **How turns ended** as a share per day, **approvals** (allowed by a person, allowed without asking, denied), and **turn
1738
+ duration** (the median and the 95th percentile; the 90th and 99th are an option).
1739
+ - **Top lists:** the busiest agents, the threads that used the most tokens, the slowest turns, the agents with the most denied
1740
+ approvals (five entries each; three or ten are an option).
1741
+ - **Budgets today** (admins and owners): each project's daily chat turns and fixes from its agent policy, with today's use, last
1742
+ week's daily average, and a forecast for the end of the day once a third of the day has passed and there are at least five
1743
+ turns to go by. The day is UTC, as the policy counts it. There are no per-agent budgets yet.
1744
+
1745
+ Hovering (or tapping) a chart shows exact values. Pressing a bar, a row of the breakdown or a legend entry filters the whole page
1746
+ to it. Every chart has a table of the same numbers, "copy as CSV" and "copy as an image". The colours are one palette, checked for
1747
+ colour-blind readers in light and dark, and never the only sign: legends carry names, outcomes carry icons.
1748
+
1749
+ **Turns** is every turn of the filter in a grid: sorted, filtered and paged by the server (a hundred rows at a time as you
1750
+ scroll, by a cursor, so the last page costs what the first does). Choose columns, drag a header to move its column and drag its right edge to resize it (each header's menu does both from the
1751
+ keyboard: move left or right, wider, narrower), pin columns to the left, sort by time, duration, tokens or cost, group by any
1752
+ dimension with subtotals, and switch to denser rows. With groups on, **Compare** adds two columns to the group rows: the group's
1753
+ turns in the period before, and the change. While you page through a sorted table it holds still: a turn that finishes meanwhile
1754
+ keeps the place it had when the first page was read, and turns that started later wait for the next look. Arrow keys move
1755
+ through the rows and Enter opens one. A turn opens in a drawer with everything in the table above, a link to its comment or board, and for
1756
+ admins a link to the activity around it. On a phone the grid is a list of cards and the drawer is a sheet.
1757
+
1758
+ **Saved views** are yours alone: a name for the page's address (filters, columns, sort) and, for a view saved from the overview,
1759
+ the dashboard as you have it: its layout and every widget's options (measure, split, bucket and the rest). Untick **Include this
1760
+ layout** to save the filters alone. "Copy a link to this view" shares the address; whoever opens it sees what they themselves may
1761
+ see, so a link or a view never widens access. Opening a view that carries a layout only ever shows that layout; your own stays as
1762
+ it is. For one of your own views a small chip says which view you are looking at, with "Back to my layout". For a view somebody
1763
+ shared by link, a note says whose layout it is, with "Use this layout" (which makes it yours) and "Back to my layout". Links and
1764
+ views made before the dashboard could be arranged, which name a chart's measure, split or bucket in the address (`metric=`, `by=`,
1765
+ `bucket=`, `bd=`), still set the first chart over time and the first breakdown.
1766
+
1767
+ **Print** prints the overview as a report (the period and filters at the top), the widgets one after another in reading order,
1768
+ each as tall as it needs, whatever sizes they have on screen. **Export** downloads the turns of the filter as CSV
1769
+ or JSON: streamed, newest first, at most 50,000 rows, with an audit entry (`usage_exported`: who, the format, how many rows, the
1770
+ period). There are no scheduled or emailed exports.
1771
+
1772
+ ### Arranging the dashboard
1773
+
1774
+ **Edit layout** (in the page's header; **Done** or Escape leaves it) turns the overview into a grid you arrange. Every tile,
1775
+ chart and list is a widget on 12 columns:
1776
+
1777
+ - **Move** a widget by dragging the bar it wears while you edit. What was in its way moves down; nothing overlaps and no gap is
1778
+ left above a widget.
1779
+ - **Resize** it from its bottom right corner, inside what its kind allows: a tile is 2, 3 or 4 columns wide and always 2 rows
1780
+ tall; the chart over time is 4 to 12 columns by 4 to 10 rows; a breakdown 3 to 12 by 3 to 10; the other charts 4 to 12 by 4
1781
+ to 8; a top list 3 to 6 by 3 to 9; the budgets 4 to 12 by 3 to 10. A row is 56 px, so no chart can be made too small to read.
1782
+ - **Hide** a widget with its ×, and bring it back from **Add widget**, which lists everything that is hidden.
1783
+ - **Duplicate** a chart from its bar (up to four of one kind): two charts over time can sit side by side, one measuring turns by
1784
+ agent and one cost by model. Each copy keeps its own options.
1785
+ - **Undo** takes back the last change (a run of arrow keys on one widget counts as one). **Reset to default** forgets your
1786
+ layout: you see the workspace's default if it has one, else the built-in layout.
1787
+
1788
+ Outside "Edit layout" nothing can be dragged, and until you change something the page is the layout it always was. While you
1789
+ edit, a widget's bar is its heading (its own title row steps aside), and at the default sizes nothing is cut off, editing or not.
1790
+
1791
+ **Heights that follow the content.** A top list, a breakdown and the budgets are as tall as what they hold: a list set to ten
1792
+ rows grows and one set to three shrinks, and the budgets hold a row per project (from six projects on, the list scrolls inside
1793
+ its card). That stops for a widget once you size it by hand: its height is then the one you gave it.
1794
+
1795
+ **With nothing to show yet.** A workspace where no agent has taken a turn in the period shows one plain "No agent turns" state.
1796
+ Someone who has arranged the dashboard, or whose workspace has a default layout, keeps the dashboard instead (a member who has
1797
+ not asked an agent anything yet, for one): each widget says there is nothing yet, and "Edit layout" works as ever.
1798
+
1799
+ **From the keyboard:** while editing, every widget takes the focus (Tab). The arrow keys move it: a column left or right, and
1800
+ up or down past the widget above or below. Shift with an arrow key resizes it by a column or a row. Each change is spoken by a
1801
+ live region ("Turn duration moved to row 3, column 7; 6 wide, 2 tall"), and so is the reason when nothing can change. Tab goes
1802
+ on to the widget's own buttons (options, duplicate, hide). With "reduce motion" set, widgets do not glide to their places.
1803
+
1804
+ **Each widget has options,** behind the "..." button on it (while editing, on its bar). They are saved with that widget, so two
1805
+ copies of a chart differ:
1806
+
1807
+ | Widget | Options |
1808
+ | --------------- | -------------------------------------------------------------------------------------------------------------------- |
1809
+ | Usage over time | measure, split, bucket (or automatic), stacked bars, grouped bars or lines, legend on or off, zoom brush on or off |
1810
+ | Breakdown | what to break down by, measure (its own, or the same as the first chart over time), 5, 8, 12 or 20 rows, show shares |
1811
+ | How turns ended | share of turns, or number of turns |
1812
+ | Approvals | stacked, or side by side |
1813
+ | Turn duration | which of the median, 90th, 95th and 99th percentile to draw; a logarithmic axis (off unless you turn it on) |
1814
+ | Top lists | 3, 5 or 10 rows |
1815
+ | Tiles | the trend line, and the line that compares with the period before |
1816
+ | Any chart | chart or table, as what it opens with |
1817
+
1818
+ The switches in a chart's header (measure, split, bucket, chart or table) are the same options: pressing one saves it for that
1819
+ chart. A narrow chart keeps only its title and its options button. The outcomes, approvals and duration charts, and the tiles'
1820
+ trend lines, use the bucket of the first chart over time.
1821
+
1822
+ **Narrower screens** show the same layout on fewer columns, worked out the same way every time: 6 columns below about 840 px
1823
+ of dashboard (tiles three to a row, charts one to a row, lists in pairs) and one column on a phone, in reading order, with the
1824
+ tiles in pairs as before. There you move a widget with the up and down buttons on its bar (or the arrow keys; on 6 columns a
1825
+ drag works too), and nothing is resized. One layout is stored, the 12-column one; a move made on a phone is a move in that
1826
+ layout. On a tablet held sideways the grid is the 12-column one, and a finger on a widget's bar drags it (a finger anywhere else
1827
+ scrolls the page).
1828
+
1829
+ **Saving.** Every change is saved for you, in this workspace, a moment after you make it, with a note that offers Undo. If a
1830
+ save fails the change stays on the page and the page says so, with "Try again"; it is lost only if you leave before it is
1831
+ saved. Your layout is yours: nobody else sees or changes it, on any role.
1832
+
1833
+ **A default for everyone.** An owner can press **Reset > Set as default for everyone**: people who have not arranged the
1834
+ dashboard, and everyone who joins later, start from that layout (their own changes are still their own). "Remove the workspace
1835
+ default" goes back to the built-in layout. Both leave an audit entry (`usage_layout_default_set` with the number of widgets,
1836
+ `usage_layout_default_removed`). The budgets are drawn for admins and owners only, whatever layout says so.
1837
+
1838
+ **What is stored** is JSON, at most 16,000 characters and 40 widgets, checked on the way in and again on the way out
1839
+ (`src/hosted/usage-layout.js`): a widget of a kind this build does not know, a size or a place out of range, a repeated id or a
1840
+ second copy of a tile is dropped, an option that is not one of the listed values falls back to its default, and something that
1841
+ is not a layout at all is refused (400; 413 when too large). Nothing a stored layout says is drawn as it is.
1842
+
1843
+ ### Who sees usage
1844
+
1845
+ | Role | Sees |
1846
+ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
1847
+ | Owner, admin | Every turn in the workspace |
1848
+ | Member | The turns they asked for, and every turn of an agent they connected (it ran on their machine), whoever asked |
1849
+ | Viewer | Nothing (the page says so) |
1850
+ | Share link guests, project tokens, signed-out browsers | Nothing: the usage routes take a signed-in session only |
1851
+
1852
+ The server decides this for every request, including exports, a turn opened by its id, and the lists the filter pickers offer. A
1853
+ member who filters by someone else gets an empty answer, not that person's rows. Another workspace's ids open nothing.
1854
+
1855
+ ### The Activity page
1856
+
1857
+ `/w/<workspace>/activity`. What people did, newest first, from the audit log: sign-in and sign-out, passkeys and sessions, members
1858
+ 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
1860
+ action, agent, project, where it came through (a person, a token, a share link guest, the server) and period; search; open an
1861
+ entry for the address and device it came from and exactly what was recorded. "Worth a look" keeps the security-relevant changes:
1862
+ roles, audiences, approval rules, the agent policy, share links switched on, a project made public, tokens made, passkeys
1863
+ removed, and exports.
1864
+
1865
+ - **Owners and admins** read everyone's activity. **Anyone else** in the workspace reads their own, whatever they filter by.
1866
+ - **What someone did in this workspace** (with the address it came from) is the workspace's record, as before.
1867
+ - **Sign-ins, passkey and recovery-code events and the list of signed-in devices are account events.** They belong to the person
1868
+ and cover every workspace that person is in, so by default nobody else sees them: each person sees their own, on their own
1869
+ activity and their own page, and an owner or admin sees none of them for anyone else, in the list, on a person's page or in an
1870
+ export.
1871
+ - **On a server with one team** the operator can switch that on: `shapewall hosted --owners-see-sign-ins` (or
1872
+ `SHAPEWALL_HOSTED_OWNERS_SEE_SIGN_INS=1`). Then a workspace's **owners** (not admins) also see those events and devices for the
1873
+ people who are members of their workspace now, from the day each joined, and the page says so. Do not switch it on where
1874
+ separate teams share a server: a person's sign-in is not tied to one workspace, so an owner would see sign-ins a member made
1875
+ for another team. An entry holds a device label ("Chrome on macOS") and the address the server saw; the device list holds a
1876
+ label and when it was last seen, never an address.
1877
+ - **A person's page** (`/activity/<user id>`; admins, or the person themselves): role and when it changed, what they can reach,
1878
+ the tokens and agents they made, how much they commented, their agent usage and their activity; and, for the person themselves
1879
+ (or an owner where the operator said so), the devices they are signed in on.
1880
+ - **A page is at most 200 entries** however many are asked for; older ones load as you scroll. **A text search always has a
1881
+ start:** without a period it looks at the last 90 days and says so. Searches and filters by agent or project are limited to 60
1882
+ a minute per person.
1883
+ - **Saved views** work here for everyone who has the page, viewers too.
1884
+ - **An agent's page** (`/activity/<agent id>`; admins): what it is, who connected it, who may send it work, its approval rule,
1885
+ its usage and the activity about it.
1886
+ - **Access review** (admins and owners): every person, agent, API token, share link, public project and open invite in one place,
1887
+ with what it reaches, who made it and when it was last used. Anything unused for 90 days is marked. "Export CSV" downloads it
1888
+ (audited as `access_exported`); each list links to the page where access is cut.
1889
+ - **Export CSV** on the log downloads up to 10,000 entries of the filter (audited as `audit_exported`). The older Audit log page
1890
+ and its export are unchanged, and that export now leaves the same audit entry.
1891
+
1892
+ New audit entries in 0.7.0: `signed_out`, `usage_exported`, `audit_exported`, `access_exported`, `usage_retention_changed`,
1893
+ `usage_layout_default_set`, `usage_layout_default_removed`, and
1894
+ `agent_policy_changed` now says which settings changed, from what to what.
1895
+
1896
+ **What the log does and does not prove.** The application has no route that edits or deletes an audit entry; entries are ordered
1897
+ by one increasing id and leave only when the workspace is deleted. That is a record for people who trust the server. It is not
1898
+ tamper-evident: someone with the database file can change it, and there is no hash chain yet. Keep backups if you need to compare.
1899
+
1900
+ ### Retention, quota and export
1901
+
1902
+ - **Retention.** Usage records are kept for 400 days by default, and a finished record older than that is removed by the
1903
+ retention job (at start and every 6 hours). A turn still running is never removed. The operator sets it per workspace:
1904
+ `shapewall hosted admin retention ws_ID --usage-days 90` (or `default`). Audit entries are not pruned.
1905
+ - **Quota.** Each usage record counts 400 bytes toward the workspace's storage quota.
1906
+ - **Workspace export.** "Download a copy" now includes `usage.json`: every usage record of the workspace, newest first, read a
1907
+ page at a time (the 50,000 cap is for downloads from the Usage page only).
1908
+ - **A deleted account** takes its saved views with it, in every workspace.
1909
+
1910
+ ### The usage and activity API
1911
+
1912
+ For the console (session cookie; every route answers 404 for a workspace you are not in). All of them are one function each in
1913
+ `src/hosted/usage.js` and `src/hosted/activity.js`, so a later admin tool calls the same code.
1914
+
1915
+ `GET /api/workspaces/:ws/usage/summary`, `/usage/series?bucket=day|week|month&groupBy=<dimension>|none&metric=`,
1916
+ `/usage/breakdown?groupBy=`, `/usage/latency?bucket=`, `/usage/top`, `/usage/budgets`, `/usage/options`,
1917
+ `/usage/rows?sort=started|duration|tokens|input|output|cached|cost|steps&dir=asc|desc&cursor=&limit=`, `/usage/rows/:id`,
1918
+ `/usage/export?format=csv|json`. Each takes the filter: `from`, `to` (ISO instants), `tz` (an IANA zone), `agent`, `project`,
1919
+ `person`, `kind`, `outcome` (a comma list or the parameter repeated), `model` (the parameter repeated, once per name, never
1920
+ split: a model's name may hold commas, brackets and spaces), `~` for the empty value, `tokensMin`, `tokensMax`, `durationMin`,
1921
+ `durationMax` (milliseconds), `q`, and `prevFrom` with `prevTo` (the period to compare with; without them, the same span on the
1922
+ wall clock just before). `/usage/breakdown` takes `previous=1` for the same split over that period.
1923
+
1924
+ `GET /api/workspaces/:ws/activity?person=&agent=&project=&group=&action=&source=&sensitive=1&from=&to=&q=&before=&limit=`,
1925
+ `/activity/filters`, `/activity/export`, `/people/:user`, `/agents/:agent/profile`, `/access-review`, `/access-review/export`.
1926
+ `GET|POST /views` and `DELETE /views/:id` keep a person's saved views (`POST` takes `layout` to keep a dashboard layout with a
1927
+ view of the Usage page). `GET /views/:id/layout` answers a view's name and layout to anyone in the workspace who has the Usage
1928
+ page and the view's link (404 for a view that carries none).
1929
+
1930
+ The dashboard's layout: `GET /usage/layout` answers `{ layout, default, canSetDefault }` (the caller's own layout or null, the
1931
+ workspace's default or null), `PUT /usage/layout` with `{ layout }` saves the caller's own, `DELETE /usage/layout` resets it,
1932
+ and `PUT` or `DELETE /usage/layout/default` sets or removes the workspace's default (owners; audited). There is no address for
1933
+ another person's layout. `/usage/top` takes `limit` (1 to 10, default 5); `/usage/latency` answers `p50`, `p90`, `p95` and
1934
+ `p99`. Members and up, like the rest of Usage; in `src/hosted/usage.js` these are `createLayouts` (one function per operation)
1935
+ and `createViews`.
1936
+
1103
1937
  ## Moving to a new origin
1104
1938
 
1105
1939
  Passkeys belong to a host name (the RP ID), so changing the server's address would lock everyone out. To move:
@@ -1136,6 +1970,16 @@ Old-host passkeys show "For old.example" on the Account page.
1136
1970
  API, signed URLs and tokens.
1137
1971
  - **CSRF.** Cookie-authenticated writes need JSON and an `Origin` (or `Sec-Fetch-Site: same-origin`) equal to the configured origin,
1138
1972
  on top of SameSite=Lax. The token API ignores cookies.
1973
+ - **Tailnet identity** (only with `--tailnet-sign-in`). The `Tailscale-User-*` headers are believed only on a request that
1974
+ carries the secret path of the serve entry this server made, on a connection whose other end is owned by root, for an address
1975
+ tailscaled's own whois gives to that login, with exactly one clean login header and no Funnel mark, and never for a request
1976
+ from the server's own machine (any program there can ask tailscaled for the serve address). On direct loopback requests, raw
1977
+ TCP forwards, Funnel traffic and with the flag off they are ignored. The secret is taken off the request before the
1978
+ application sees it and is in no response; a test crawls the hosted server and the local board for it. The server refuses to start with the flag
1979
+ (and suspends it while running) under userspace networking, Tailscale before 1.98, tailscaled's own proxies, in a container,
1980
+ or when the serve config is not its one entry. Root and the Tailscale operator on the machine are trusted; nothing else on
1981
+ the machine or the tailnet is. An identity is per device, not per person
1982
+ ([how](#how-the-server-knows-a-request-came-through-tailscale-serve)).
1139
1983
  - **Rate limits** (in memory, per process): passkey ceremonies 30 a minute per IP; wrong recovery codes 5 per 15 minutes per handle and
1140
1984
  IP, and 30 an hour per IP (right codes do not count, and nobody can use up another address's attempts); invite lookups 30 a minute
1141
1985
  per IP; bad tokens 20 a minute per IP; 1200 requests a minute per token; 20 pushes an hour per
@@ -1251,13 +2095,14 @@ shapewall hosted --data ./hosted-data --tailscale --tailscale-port 8443 --funnel
1251
2095
 
1252
2096
  These commands change Tailscale Serve/Funnel configuration. Run them only when you intend to expose this server. Install Tailscale,
1253
2097
  connect the machine, enable MagicDNS and HTTPS certificates, and authorize your unprivileged user as a Tailscale operator first.
2098
+ Add `--tailnet-sign-in` to sign tailnet users in by their tailnet login instead of a passkey ([Tailnet sign-in](#tailnet-sign-in)).
1254
2099
  The console and passkey origin come from this machine's `*.ts.net` hostname. Do not also pass `--origin` or a non-loopback `--host`.
1255
2100
  An occupied HTTPS port is refused, including an existing mapping to the same target. SIGINT/SIGTERM removes mappings this process
1256
2101
  added only while they still match; after a crash inspect `tailscale serve status` and remove the stale mapping explicitly.
1257
2102
 
1258
2103
  Funnel uses a second loopback listener and a different HTTPS port. It serves guest share pages, guest APIs, signed live HTML,
1259
2104
  static assets, legal/report routes and health only. Console, sign-in, signup, device login, invitations, member APIs and token APIs
1260
- answer 404. Member session/ceremony cookies are discarded at that listener. Share links still require the secret in the link and
2105
+ 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
1261
2106
  any passcode configured by the workspace. Funnel makes those guest paths public. Ports are not cookie boundaries, so never add
1262
2107
  member routes to this listener. Tailscale policy/ACL configuration remains the operator's responsibility.
1263
2108
 
@@ -1296,10 +2141,20 @@ shapewall hosted admin export ws_ID --out ./workspace.zip --data ./hosted-data
1296
2141
  shapewall hosted admin reports --data ./hosted-data
1297
2142
  shapewall hosted admin reports close rp_ID --note "Reviewed" --data ./hosted-data
1298
2143
  shapewall hosted admin log --data ./hosted-data
2144
+ # An account's passkeys (by handle, or by the tailnet login it is linked to):
2145
+ shapewall hosted admin passkeys list --login ada@example.com --data ./hosted-data
2146
+ shapewall hosted admin passkeys remove PASSKEY_ID --handle ada --data ./hosted-data
1299
2147
  # Destructive, requires the workspace's exact name:
1300
2148
  shapewall hosted admin delete ws_ID --confirm "Workspace name" --data ./hosted-data
1301
2149
  ```
1302
2150
 
2151
+ `passkeys remove` is for the case nobody in the product can solve: an account whose only passkey is not its owner's, or is
2152
+ lost with no recovery codes, most of all on a server with tailnet sign-in after a first passkey's 24 hours have passed. Being
2153
+ able to read and write the data folder is the proof, as for every operator command. It removes any passkey, also the last
2154
+ one, and ends the account's passkey sessions (tailnet sessions go on); an account with a tailnet login then signs in through
2155
+ the tailnet and can add a passkey again, and one without signs in with a recovery code if it has one. It is in the operator
2156
+ log and in the account's own security log ("removed by the server's operator").
2157
+
1303
2158
  Suspension immediately refuses existing API tokens, new device approvals, invitations and guest links. Members can read and export
1304
2159
  but writes return `workspace_suspended`. Resume restores the previous grants. Operator actions, including listing workspaces/reports and reading the log, are recorded in the
1305
2160
  operator log; suspension/resume also enter the workspace audit log. The CLI is privileged filesystem access, not a web-admin role.
@@ -1323,7 +2178,8 @@ plus the limits listed above. Run one hosted process per data folder.
1323
2178
 
1324
2179
  ## Retention, backup and restore
1325
2180
 
1326
- Current captures stay. By default retention keeps the newest two historical captures per page and viewport plus every historical
2181
+ Usage records (one small row per agent turn) are kept for 400 days unless a workspace has its own `--usage-days`; see
2182
+ [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
1327
2183
  capture a comment references, open or resolved. Variants are left alone. It runs at start and every 6 hours in-process when the
1328
2184
  operator starts the hosted server. `--retention-hours 0` disables it; `--retention-keep N` changes the default. To preview or run it:
1329
2185
 
@@ -1332,6 +2188,7 @@ shapewall hosted admin retention --run --dry-run --data ./hosted-data
1332
2188
  shapewall hosted admin retention --run --data ./hosted-data
1333
2189
  shapewall hosted admin retention ws_ID --keep 4 --data ./hosted-data
1334
2190
  shapewall hosted admin retention ws_ID --keep default --data ./hosted-data
2191
+ shapewall hosted admin retention ws_ID --usage-days 90 --data ./hosted-data
1335
2192
  shapewall hosted backup --data ./hosted-data --to ./backups --keep-days 30
1336
2193
  shapewall hosted restore --from ./backups --check
1337
2194
  shapewall hosted restore --from ./backups --data ./restored-new-folder
@@ -1448,6 +2305,110 @@ COLUMN approvals_asked; ALTER TABLE agent_runs DROP COLUMN approvals_allowed; AL
1448
2305
  approvals_denied; DELETE FROM schema_migrations WHERE version = 14; PRAGMA user_version = 13;`. Never reset the ledger any other
1449
2306
  way. Test a rollback on a copy first.
1450
2307
 
2308
+ ### Migration 15 and rollback
2309
+
2310
+ Migration 15 (0.7.0) adds what the Usage and Activity pages need ([Usage and activity](#usage-and-activity)). It is additive
2311
+ and runs once:
2312
+
2313
+ - columns on `agent_runs`: `agent_owner` (who connected the agent; filled in for existing rows), `duration_ms` (filled in for
2314
+ finished rows from their start and end), `agent_ms`, `tools`, `approvals_auto`, `approvals_by`, `window_used`, `window_size`;
2315
+ - indexes `agent_runs_owner` and `agent_runs_thread`;
2316
+ - table `saved_views` (a person's named filters on the Usage and Activity pages);
2317
+ - column `workspaces.retention_usage_days` (how long a workspace keeps usage records; empty means the default, 400 days);
2318
+ - indexes on the audit log for the Activity filters: `audit_workspace_at`, `audit_workspace_user`, `audit_account_user`.
2319
+
2320
+ Nothing existing is rewritten beyond the two fill-ins above, and no role gains a permission it did not have, except that members
2321
+ may now read their own usage and everyone their own activity. Back up before upgrading. From 0.7.0 the retention job removes
2322
+ finished usage records older than 400 days; set `--usage-days` for a workspace first if you want to keep them longer.
2323
+
2324
+ For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running 0.6.0 on the upgraded
2325
+ database also works, since it ignores the new columns, table and indexes, but:
2326
+
2327
+ - **There are no Usage and Activity pages,** and turns recorded by 0.6.0 lack the new fields (they show as "not reported" after
2328
+ upgrading again, and their duration is not filled in).
2329
+ - **Usage records are not pruned** and do not count toward the quota while 0.6.0 runs.
2330
+ - **Saved views stay** in their table, unused.
2331
+
2332
+ To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE saved_views; DROP INDEX agent_runs_owner; DROP
2333
+ INDEX agent_runs_thread; DROP INDEX audit_workspace_at; DROP INDEX audit_workspace_user; DROP INDEX audit_account_user; ALTER
2334
+ TABLE agent_runs DROP COLUMN agent_owner; ALTER TABLE agent_runs DROP COLUMN duration_ms; ALTER TABLE agent_runs DROP COLUMN
2335
+ agent_ms; ALTER TABLE agent_runs DROP COLUMN tools; ALTER TABLE agent_runs DROP COLUMN approvals_auto; ALTER TABLE agent_runs
2336
+ DROP COLUMN approvals_by; ALTER TABLE agent_runs DROP COLUMN window_used; ALTER TABLE agent_runs DROP COLUMN window_size; ALTER
2337
+ TABLE workspaces DROP COLUMN retention_usage_days; DELETE FROM schema_migrations WHERE version = 15; PRAGMA user_version = 14;`.
2338
+ Never reset the ledger any other way. Test a rollback on a copy first.
2339
+
2340
+ ### Migration 16 and rollback
2341
+
2342
+ Migration 16 (0.7.0) adds one table and changes nothing else:
2343
+
2344
+ - table `usage_layouts`: the layouts of the Usage dashboard ([Arranging the dashboard](#arranging-the-dashboard)). One row per
2345
+ layout: a person's own (`kind` `person`, `subject` their user id), the workspace's default (`default`, empty subject), and the
2346
+ layout a saved view carries (`view`, the view's id). `layout` is the checked JSON; `updated_by` and `updated_at` say who saved
2347
+ it and when. Rows go with their workspace, with a member who leaves or is removed, with a deleted account, and with a deleted
2348
+ view.
2349
+
2350
+ It is additive, and it does not touch `saved_views` or any other table of migration 15. Back up before upgrading.
2351
+
2352
+ For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous build. Running a build without migration 16
2353
+ on the upgraded database also works, since it ignores the table, but:
2354
+
2355
+ - **Everyone sees the built-in dashboard,** fixed as it was. Layouts, the workspace's default and the layouts of saved views
2356
+ stay in the table, unused, and are back when you upgrade again.
2357
+ - **Saved views keep working** as names for an address. A link that names a view (`view=`) opens the filters and ignores the
2358
+ rest.
2359
+ - **A member removed or an account deleted meanwhile** leaves their rows behind. They are harmless (a layout holds no usage
2360
+ data, only which widgets go where), and `DELETE FROM usage_layouts WHERE kind = 'person' AND subject NOT IN (SELECT user_id
2361
+ FROM memberships WHERE workspace_id = usage_layouts.workspace_id);` clears them.
2362
+
2363
+ To remove the schema as well, with the server stopped: `DROP TABLE usage_layouts; DELETE FROM schema_migrations WHERE version =
2364
+ 16;`, then set `PRAGMA user_version` to the highest version left in `schema_migrations` (17 where migration 17 is there, else
2365
+ 15). Never reset the ledger any other way. Test a rollback on a copy first.
2366
+
2367
+ ### Migration 17 and rollback
2368
+
2369
+ Migration 17 (0.7.0) adds what the passkey settings and tailnet sign-in need ([Signing in](#signing-in)). It is additive and
2370
+ runs once:
2371
+
2372
+ - column `workspaces.step_up` (the "Ask for a passkey again" settings as JSON; `{}` is all off);
2373
+ - columns `users.tailnet_login`, `users.tailnet_linked_at` and `users.tailnet_user_id` (Tailscale's id of the linked user), with
2374
+ the unique index `users_tailnet_login`;
2375
+ - column `passkeys.tailnet_added_from` (the device a first passkey was added from in a tailnet session);
2376
+ - table `server_settings` (what the operator switched for the whole server: passkeys on a tailnet sign-in server);
2377
+ - column `sessions.tailnet_login` (set on a session that came in by tailnet identity);
2378
+ - column `invites.tailnet_login` (an invite for one login);
2379
+ - table `tailnet_visitors` (logins that arrived and are in no workspace).
2380
+
2381
+ **What changes on upgrade, with no setting touched:** the passkey prompts before workspace actions are gone. A signed-in session
2382
+ with the right role is enough. If you want them back, an owner switches the groups on in Settings, per workspace.
2383
+
2384
+ For rollback, prefer the pre-upgrade backup in a fresh data folder with the previous release. Running the previous build on the
2385
+ upgraded database also works, but:
2386
+
2387
+ - **The old passkey rules are back for everyone,** whatever the workspaces chose.
2388
+ - **Delete tailnet sessions** (`DELETE FROM sessions WHERE tailnet_login IS NOT NULL;`). An older build cannot use them in any
2389
+ case: they are stored under the hash of `tailnet:<token>`, and an older build looks a cookie up by the hash of the token
2390
+ alone, so it finds nothing. Deleting them is tidiness, and the documented step.
2391
+ - **Accounts made by tailnet sign-in have no passkey** and no recovery codes, so they cannot sign in to an older build.
2392
+ - **Invites made for a tailnet login** work for anyone who has their link on an older build. Revoke the pending ones first.
2393
+
2394
+ To remove the schema as well (SQLite 3.35+), with the server stopped: `DROP TABLE tailnet_visitors; DROP INDEX
2395
+ users_tailnet_login; ALTER TABLE users DROP COLUMN tailnet_login; ALTER TABLE users DROP COLUMN tailnet_linked_at; ALTER TABLE
2396
+ users DROP COLUMN tailnet_user_id; ALTER TABLE passkeys DROP COLUMN tailnet_added_from; DROP TABLE server_settings; ALTER TABLE
2397
+ sessions DROP COLUMN tailnet_login; ALTER TABLE invites DROP COLUMN tailnet_login; ALTER TABLE workspaces DROP COLUMN step_up;
2398
+ 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).
2400
+
2401
+ **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
+ numbered 16 for a while. A database such a build opened says "16 ran" in its ledger, which now means the Usage layouts. The
2403
+ server recognises it (the sign-in tables are there, `usage_layouts` is not, 17 is not marked), adds what that early build
2404
+ did not have yet, and corrects the ledger to "17 ran, 16 did not", so both end applied once. Nothing to do by hand.
2405
+
2406
+ **Migrations 16 and 17.** Number 16 is the Usage layouts (table `usage_layouts`) and 17 is sign-in; they were made separately
2407
+ and do not depend on each other. The server keeps a ledger of what ran (`schema_migrations`), so they can reach a database in
2408
+ either order: a database that ran only 16 runs 17 on the next start, and one that ran only 17 runs 16. `PRAGMA user_version` is
2409
+ the highest number applied, not a count. Rolling one back does not touch the other; remove only its own row from
2410
+ `schema_migrations`.
2411
+
1451
2412
  ## Secrets, logs and legal review
1452
2413
 
1453
2414
  `SHAPEWALL_HOSTED_SECRET_FILE` and `RESEND_API_KEY_FILE` read private secret files. systemd `LoadCredential=shapewall-secret:...` and
@@ -1467,7 +2428,7 @@ The server never runs a model or an agent process. Capture and execution stay
1467
2428
  on the developer's machine or CI. In a project's console, **Agent policy**
1468
2429
  sets trusted workspace roles or handles, board overrides, `onlyMentions`,
1469
2430
  claims per UTC day (50 by default), and open claims (3 by default). Zero stops
1470
- new claims. Policy changes require a fresh passkey. Removed members and changed
2431
+ new claims. Removed members and changed
1471
2432
  trust policy invalidate vouches immediately.
1472
2433
 
1473
2434
  Use project tokens with `read, reply, status, claim` for runners. `reply` posts
@@ -1485,7 +2446,7 @@ vouches for the exact current text and anchor. Editing clears it, and both
1485
2446
  after you opened it: reload and read it again. Only admins set an agent status
1486
2447
  from the board. Approvals and denials of an agent's commands are in the audit
1487
2448
  log. Non-admin
1488
- requests need **Approve agent run**, with a trusted admin's fresh passkey, by
2449
+ requests need **Approve agent run** by a trusted admin, by
1489
2450
  default. Guest and agent-written comments can never be dispatched, including
1490
2451
  with `--include-guests`. Imported comments start inert and need an explicit
1491
2452
  trusted vouch. Claim tokens see only dispatched comments, including direct-id
@@ -1508,7 +2469,7 @@ returns HTTP 429 `agent_budget`; another token cannot take over a live claim.
1508
2469
  An operator suspension, token revocation, membership loss, changed trust or an
1509
2470
  edited comment prevents subsequent requests. Shell approvals bind one exact
1510
2471
  command and one claim generation, expire after two minutes and need a trusted
1511
- admin's fresh passkey. They cannot be reused on a later run of identical text.
2472
+ admin (and their passkey again when the workspace asks for it). They cannot be reused on a later run of identical text.
1512
2473
 
1513
2474
  `shapewall watch --remote` uses bearer-authenticated SSE at `/api/v1/events`,
1514
2475
  with bounded polling fallback when a proxy does not support streams. Events