shapewall 0.0.0-stage → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (304) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +651 -2
  6. package/THIRD_PARTY.md +165 -0
  7. package/bin/shapewall.js +29 -0
  8. package/dist/agent/package-lock.json +8384 -0
  9. package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
  10. package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
  11. package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
  12. package/dist/client/assets/History-CEv6b-av.js +1 -0
  13. package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
  14. package/dist/client/assets/Management-DCfhcEUY.js +1 -0
  15. package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
  16. package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
  17. package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
  18. package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
  19. package/dist/client/assets/index-ByQRKVit.css +2 -0
  20. package/dist/client/assets/index-DweQ8Qtu.js +29 -0
  21. package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-A8EnIYLR.js +1 -0
  24. package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
  25. package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
  26. package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
  27. package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
  28. package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
  29. package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
  30. package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
  31. package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
  32. package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
  33. package/dist/client/assets/ui-CLbws0rx.js +41 -0
  34. package/dist/client/build-info.json +1 -0
  35. package/dist/client/favicon.svg +7 -0
  36. package/dist/client/icons/apple-touch-icon.png +0 -0
  37. package/dist/client/icons/icon-192.png +0 -0
  38. package/dist/client/icons/icon-512.png +0 -0
  39. package/dist/client/icons/maskable-512.png +0 -0
  40. package/dist/client/index.html +25 -0
  41. package/dist/client/manifest.webmanifest +15 -0
  42. package/dist/client/sw.js +53 -0
  43. package/dist/client/theme-boot.js +27 -0
  44. package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
  45. package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
  46. package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
  47. package/dist/console/assets/console-C7uJLLOn.js +51 -0
  48. package/dist/console/assets/console-R8IBY3Am.css +2 -0
  49. package/dist/console/build-info.json +1 -0
  50. package/dist/console/console.html +21 -0
  51. package/dist/console/favicon.svg +7 -0
  52. package/dist/console/icons/apple-touch-icon.png +0 -0
  53. package/dist/console/icons/icon-192.png +0 -0
  54. package/dist/console/icons/icon-512.png +0 -0
  55. package/dist/console/icons/maskable-512.png +0 -0
  56. package/dist/console/manifest.webmanifest +15 -0
  57. package/dist/console/theme-boot.js +27 -0
  58. package/docs/agent-hardening.md +342 -0
  59. package/docs/agent-recipes.md +187 -0
  60. package/docs/agent-workflow.md +320 -0
  61. package/docs/agents.md +894 -0
  62. package/docs/architecture.md +242 -0
  63. package/docs/buzz.md +140 -0
  64. package/docs/capture-warnings.md +57 -0
  65. package/docs/config.md +489 -0
  66. package/docs/deployment.md +289 -0
  67. package/docs/design-system.md +162 -0
  68. package/docs/github.md +107 -0
  69. package/docs/hosted.md +764 -0
  70. package/docs/images/board-overview.png +0 -0
  71. package/docs/images/journeys.png +0 -0
  72. package/docs/images/live-comment.png +0 -0
  73. package/docs/images/phone-comment.png +0 -0
  74. package/docs/images/phone-overview.png +0 -0
  75. package/docs/images/variant.png +0 -0
  76. package/docs/interaction-audits.md +40 -0
  77. package/docs/journeys.md +137 -0
  78. package/docs/local-accounts.md +80 -0
  79. package/docs/notifications.md +237 -0
  80. package/docs/page-checks.md +69 -0
  81. package/docs/performance.md +174 -0
  82. package/docs/starter-agent.md +325 -0
  83. package/docs/updates.md +87 -0
  84. package/examples/audits/interaction.audit.json +17 -0
  85. package/package.json +132 -4
  86. package/src/accounts/avatar.js +121 -0
  87. package/src/accounts/local.js +464 -0
  88. package/src/agent/acp/command.js +204 -0
  89. package/src/agent/acp/detect.js +75 -0
  90. package/src/agent/acp/sandbox.js +160 -0
  91. package/src/agent/agent-health.js +75 -0
  92. package/src/agent/backends/acp.js +1297 -0
  93. package/src/agent/backends/index.js +61 -0
  94. package/src/agent/backends/openai.js +308 -0
  95. package/src/agent/composer.js +221 -0
  96. package/src/agent/config.js +338 -0
  97. package/src/agent/context.js +191 -0
  98. package/src/agent/control.js +122 -0
  99. package/src/agent/errors.js +17 -0
  100. package/src/agent/feedback-loop.js +137 -0
  101. package/src/agent/manage.js +94 -0
  102. package/src/agent/next-steps.js +51 -0
  103. package/src/agent/owner-mcp.js +38 -0
  104. package/src/agent/plain-text.js +52 -0
  105. package/src/agent/ratings-core.js +213 -0
  106. package/src/agent/ratings.js +100 -0
  107. package/src/agent/reply-text.js +67 -0
  108. package/src/agent/routes.js +1065 -0
  109. package/src/agent/run.js +326 -0
  110. package/src/agent/settings-routes.js +704 -0
  111. package/src/agent/showable.js +23 -0
  112. package/src/agent/starter/approvals.js +181 -0
  113. package/src/agent/starter/build-image.js +90 -0
  114. package/src/agent/starter/cli.js +163 -0
  115. package/src/agent/starter/disk.js +53 -0
  116. package/src/agent/starter/doctor.js +180 -0
  117. package/src/agent/starter/egress-proxy.js +351 -0
  118. package/src/agent/starter/gate.js +90 -0
  119. package/src/agent/starter/loop.js +114 -0
  120. package/src/agent/starter/model-relay.js +289 -0
  121. package/src/agent/starter/pause.js +14 -0
  122. package/src/agent/starter/probe.js +272 -0
  123. package/src/agent/starter/prompt.js +41 -0
  124. package/src/agent/starter/push-guard.js +146 -0
  125. package/src/agent/starter/rpc.js +164 -0
  126. package/src/agent/starter/runtime.js +287 -0
  127. package/src/agent/starter/sandbox-main.js +121 -0
  128. package/src/agent/starter/settings.js +290 -0
  129. package/src/agent/starter/source.js +69 -0
  130. package/src/agent/starter/supervisor.js +755 -0
  131. package/src/agent/starter/sweep.js +46 -0
  132. package/src/agent/starter/tools.js +524 -0
  133. package/src/agent/starter/watch.js +84 -0
  134. package/src/agent/starter/worktree.js +409 -0
  135. package/src/agent/text-diff.js +210 -0
  136. package/src/agent/thread-history.js +223 -0
  137. package/src/agent/threads.js +399 -0
  138. package/src/agent/tools.js +200 -0
  139. package/src/agent/turn-changes.js +424 -0
  140. package/src/agent/undo-state.js +26 -0
  141. package/src/agent/user-settings.js +308 -0
  142. package/src/auth/record.js +375 -0
  143. package/src/broken-links.js +164 -0
  144. package/src/buzz/client.js +75 -0
  145. package/src/buzz/config.js +151 -0
  146. package/src/buzz/environment.js +13 -0
  147. package/src/buzz/gateway.js +192 -0
  148. package/src/buzz/routes.js +61 -0
  149. package/src/buzz/signer-child.js +205 -0
  150. package/src/buzz/store.js +89 -0
  151. package/src/buzz/transport.js +60 -0
  152. package/src/buzz/verify.js +140 -0
  153. package/src/capture/actions.js +159 -0
  154. package/src/capture/capture.js +776 -0
  155. package/src/capture/dom-names.js +189 -0
  156. package/src/capture/element-map.js +509 -0
  157. package/src/capture/live.js +827 -0
  158. package/src/capture/media-scheme.js +317 -0
  159. package/src/capture/network-summary.js +86 -0
  160. package/src/capture/pacing.js +34 -0
  161. package/src/capture/requests.js +167 -0
  162. package/src/capture/sanitize.js +752 -0
  163. package/src/checks/accessibility.js +134 -0
  164. package/src/checks/budgets.js +58 -0
  165. package/src/checks/cli.js +55 -0
  166. package/src/checks/comparison.js +113 -0
  167. package/src/checks/environments.js +32 -0
  168. package/src/checks/flow-config.js +82 -0
  169. package/src/checks/flow-origin.js +53 -0
  170. package/src/checks/flows.js +398 -0
  171. package/src/checks/lighthouse-auth.js +145 -0
  172. package/src/checks/lighthouse-findings.js +130 -0
  173. package/src/checks/lighthouse.js +395 -0
  174. package/src/checks/robots.js +85 -0
  175. package/src/checks/routes.js +52 -0
  176. package/src/checks/run-control.js +259 -0
  177. package/src/checks/runner.js +724 -0
  178. package/src/checks/schema.js +133 -0
  179. package/src/checks/seo-analysis.js +443 -0
  180. package/src/checks/seo-probe.js +190 -0
  181. package/src/checks/seo-snapshot.js +99 -0
  182. package/src/checks/store.js +214 -0
  183. package/src/checks/transport.js +47 -0
  184. package/src/cli/args.js +319 -0
  185. package/src/cli/capture.js +79 -0
  186. package/src/cli/commands.js +92 -0
  187. package/src/cli/comments.js +84 -0
  188. package/src/cli/help.js +243 -0
  189. package/src/cli/init.js +214 -0
  190. package/src/cli/misc.js +64 -0
  191. package/src/cli/notify.js +87 -0
  192. package/src/cli/open.js +22 -0
  193. package/src/cli/serve.js +274 -0
  194. package/src/cli/variant.js +82 -0
  195. package/src/cli/watch.js +70 -0
  196. package/src/cli.js +130 -0
  197. package/src/comment-fields.js +76 -0
  198. package/src/comments-cli.js +208 -0
  199. package/src/config-reload.js +100 -0
  200. package/src/config.js +1061 -0
  201. package/src/devices-cli.js +21 -0
  202. package/src/diff.js +95 -0
  203. package/src/discover.js +284 -0
  204. package/src/doctor.js +295 -0
  205. package/src/event-log.js +268 -0
  206. package/src/events-cli.js +102 -0
  207. package/src/events.js +113 -0
  208. package/src/export.js +119 -0
  209. package/src/feedback.js +246 -0
  210. package/src/github.js +551 -0
  211. package/src/hosted/LICENSE.md +105 -0
  212. package/src/hosted/access-cli.js +78 -0
  213. package/src/hosted/admin.js +682 -0
  214. package/src/hosted/agent-approvals.js +163 -0
  215. package/src/hosted/agent-policy.js +189 -0
  216. package/src/hosted/app.js +510 -0
  217. package/src/hosted/auth-routes.js +540 -0
  218. package/src/hosted/auth.js +536 -0
  219. package/src/hosted/backup.js +483 -0
  220. package/src/hosted/board-context.js +35 -0
  221. package/src/hosted/board-routes.js +486 -0
  222. package/src/hosted/board-view.js +94 -0
  223. package/src/hosted/clean-worker.js +24 -0
  224. package/src/hosted/cleaner.js +89 -0
  225. package/src/hosted/comments.js +355 -0
  226. package/src/hosted/console-routes.js +401 -0
  227. package/src/hosted/cookies.js +18 -0
  228. package/src/hosted/crypto.js +80 -0
  229. package/src/hosted/db.js +496 -0
  230. package/src/hosted/device-routes.js +175 -0
  231. package/src/hosted/device.js +233 -0
  232. package/src/hosted/events.js +63 -0
  233. package/src/hosted/guards.js +172 -0
  234. package/src/hosted/guest-view.js +65 -0
  235. package/src/hosted/http.js +39 -0
  236. package/src/hosted/import.js +300 -0
  237. package/src/hosted/mail.js +73 -0
  238. package/src/hosted/mcp-http.js +71 -0
  239. package/src/hosted/membership.js +114 -0
  240. package/src/hosted/operator.js +478 -0
  241. package/src/hosted/ops-cli.js +345 -0
  242. package/src/hosted/pages.js +146 -0
  243. package/src/hosted/permissions.js +113 -0
  244. package/src/hosted/presence.js +372 -0
  245. package/src/hosted/projects.js +124 -0
  246. package/src/hosted/public.js +109 -0
  247. package/src/hosted/push.js +622 -0
  248. package/src/hosted/quotas.js +115 -0
  249. package/src/hosted/ratelimit.js +96 -0
  250. package/src/hosted/rebind.js +316 -0
  251. package/src/hosted/retention.js +128 -0
  252. package/src/hosted/server.js +260 -0
  253. package/src/hosted/setup-link.js +64 -0
  254. package/src/hosted/setup.js +323 -0
  255. package/src/hosted/shares.js +444 -0
  256. package/src/hosted/tailscale.js +204 -0
  257. package/src/hosted/tenancy.js +301 -0
  258. package/src/hosted/token-api.js +455 -0
  259. package/src/hosted/token-events.js +60 -0
  260. package/src/hosted/tokens.js +57 -0
  261. package/src/hosted/turnstile.js +49 -0
  262. package/src/hosted/usercontent.js +154 -0
  263. package/src/hosted/zip.js +155 -0
  264. package/src/invocation.js +58 -0
  265. package/src/journey-paths.js +282 -0
  266. package/src/journeys.js +189 -0
  267. package/src/links.js +106 -0
  268. package/src/local-projects.js +182 -0
  269. package/src/lock.js +193 -0
  270. package/src/mcp.js +417 -0
  271. package/src/mentions.js +151 -0
  272. package/src/net.js +15 -0
  273. package/src/notify/config.js +275 -0
  274. package/src/notify/index.js +301 -0
  275. package/src/notify/lease.js +73 -0
  276. package/src/notify/messages.js +212 -0
  277. package/src/notify/run.js +174 -0
  278. package/src/pixeldiff.js +49 -0
  279. package/src/png.js +143 -0
  280. package/src/reactions.js +111 -0
  281. package/src/remote/cli.js +133 -0
  282. package/src/remote/credentials.js +62 -0
  283. package/src/remote/ids.js +12 -0
  284. package/src/remote/login.js +155 -0
  285. package/src/remote/remote-mcp.js +237 -0
  286. package/src/remote/remote-watch.js +291 -0
  287. package/src/remote/remote.js +313 -0
  288. package/src/remote/share-state.js +78 -0
  289. package/src/remote/share.js +369 -0
  290. package/src/remote/terminal.js +13 -0
  291. package/src/serve-state.js +64 -0
  292. package/src/server/app.js +824 -0
  293. package/src/server/devices.js +186 -0
  294. package/src/server/local-console.js +28 -0
  295. package/src/server/local-user.js +59 -0
  296. package/src/server/pairing-routes.js +159 -0
  297. package/src/server/share-routes.js +89 -0
  298. package/src/server/tailscale.js +97 -0
  299. package/src/sitemap.js +431 -0
  300. package/src/store.js +983 -0
  301. package/src/tokens.js +11 -0
  302. package/src/update/routes.js +245 -0
  303. package/src/watch.js +403 -0
  304. package/src/which.js +58 -0
@@ -0,0 +1,260 @@
1
+ // `shapewall hosted`: starts the hosted server. Data lives in one folder:
2
+ // <data>/shapewall.db SQLite (WAL): accounts, workspaces, comments, tokens, audit
3
+ // <data>/secret.key key for signed capture URLs (0600, made on first start)
4
+ // <data>/files/<ws>/<project>/<board>/ pushed captures (the local layout)
5
+ // <data>/staging/<push>/ pushes in progress
6
+ // <data>/quotas.json the operator's quotas (optional, src/hosted/quotas.js)
7
+ // Back up with `shapewall hosted backup` (src/hosted/backup.js), which takes a
8
+ // consistent copy while the server runs.
9
+
10
+ import fs from 'node:fs'
11
+ import path from 'node:path'
12
+ import http from 'node:http'
13
+ import { randomBytes } from 'node:crypto'
14
+ import { MIN_NODE, nodeSupportsSqlite, openDatabase, quietSqliteWarning } from './db.js'
15
+ import { writeSetupLink } from './setup-link.js'
16
+
17
+ export function readSecret(dataDir, env = process.env) {
18
+ if (env.SHAPEWALL_HOSTED_SECRET) return env.SHAPEWALL_HOSTED_SECRET
19
+ const file = path.join(dataDir, 'secret.key')
20
+ try {
21
+ return fs.readFileSync(file, 'utf8').trim()
22
+ } catch (error) {
23
+ if (error.code !== 'ENOENT') throw error
24
+ }
25
+ const secret = randomBytes(32).toString('base64url')
26
+ fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 })
27
+ fs.writeFileSync(file, `${secret}\n`, { mode: 0o600, flag: 'wx' })
28
+ return secret
29
+ }
30
+
31
+ // Secrets from files instead of the environment: systemd credentials
32
+ // (LoadCredential=shapewall-secret:..., resend-api-key:...; read from
33
+ // $CREDENTIALS_DIRECTORY) or NAME_FILE variables (Docker secrets). A value
34
+ // already in the environment wins. Returns the names it loaded (never values).
35
+ export const CREDENTIALS = [
36
+ ['SHAPEWALL_HOSTED_SECRET', 'shapewall-secret'],
37
+ ['RESEND_API_KEY', 'resend-api-key'],
38
+ ]
39
+ export function loadCredentials(env = process.env) {
40
+ const loaded = []
41
+ for (const [name, credential] of CREDENTIALS) {
42
+ if (env[name]) continue
43
+ const file = env[`${name}_FILE`] || (env.CREDENTIALS_DIRECTORY ? path.join(env.CREDENTIALS_DIRECTORY, credential) : null)
44
+ if (!file) continue
45
+ let value
46
+ try {
47
+ value = fs.readFileSync(file, 'utf8').trim()
48
+ } catch (error) {
49
+ if (error.code === 'ENOENT' && !env[`${name}_FILE`]) continue
50
+ throw new Error(`${name}: cannot read ${file} (${error.code || error.message})`, { cause: error })
51
+ }
52
+ if (value) {
53
+ env[name] = value
54
+ loaded.push(name)
55
+ }
56
+ }
57
+ return loaded
58
+ }
59
+
60
+ // An https origin served from loopback means a reverse proxy in front; without
61
+ // --trust-proxy every client looks like 127.0.0.1 and shares one rate limit.
62
+ export function proxyWarning({ origin, host, trustProxy }) {
63
+ const loopback = ['127.0.0.1', '::1', 'localhost'].includes(String(host).replace(/^\[|\]$/g, ''))
64
+ if (trustProxy || !loopback || !String(origin).startsWith('https:')) return null
65
+ return 'Warning: the origin is https but the server listens on loopback without --trust-proxy, so rate limits see every client as the proxy. Add --trust-proxy when a reverse proxy on this host forwards to it.'
66
+ }
67
+
68
+ function listen(handler, port, host) {
69
+ const server = http.createServer(handler)
70
+ return new Promise((resolve, reject) => {
71
+ server.once('error', reject)
72
+ server.listen(port, host, () => {
73
+ server.off('error', reject)
74
+ resolve(server)
75
+ })
76
+ })
77
+ }
78
+
79
+ export async function startHosted({
80
+ dataDir,
81
+ port = 4700,
82
+ host = '127.0.0.1',
83
+ origin = null,
84
+ signup = 'invite',
85
+ usercontentOrigin = null,
86
+ trustProxy = false,
87
+ previousOrigin = null,
88
+ reportEmail = null,
89
+ // Mode 1 (src/hosted/tailscale.js): { httpsPort, funnel: { httpsPort, localPort } | null, run }
90
+ tailscale = null,
91
+ quotasFile = null,
92
+ retentionHours = undefined,
93
+ retentionKeep = undefined,
94
+ env = process.env,
95
+ out = console.log,
96
+ exitOnStop = true,
97
+ }) {
98
+ if (!nodeSupportsSqlite())
99
+ throw new Error(`shapewall hosted needs Node ${MIN_NODE.join('.')} or newer (for node:sqlite); this is ${process.versions.node}`)
100
+ if (!['invite', 'open'].includes(signup)) throw new Error('--signup must be invite or open')
101
+ quietSqliteWarning()
102
+ const dir = path.resolve(dataDir)
103
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
104
+ const loaded = loadCredentials(env)
105
+ if (loaded.length) out(`Secrets from credential files: ${loaded.join(', ')}`)
106
+ const { legalSettings } = await import('./operator.js')
107
+ const legal = legalSettings(env)
108
+ const { createQuotas } = await import('./quotas.js')
109
+ const quotaPath = quotasFile
110
+ ? path.resolve(quotasFile)
111
+ : fs.existsSync(path.join(dir, 'quotas.json'))
112
+ ? path.join(dir, 'quotas.json')
113
+ : null
114
+ const quotas = createQuotas({ file: quotaPath, log: (line) => out(line) })
115
+ if (quotaPath) out(`Quotas from ${quotaPath}`)
116
+ if (tailscale && host !== '127.0.0.1')
117
+ throw new Error('--tailscale listens on 127.0.0.1 only (tailscale serve forwards to it); drop --host')
118
+ if (tailscale && origin) throw new Error('--tailscale sets the origin itself (https://<machine>.<tailnet>.ts.net); drop --origin')
119
+ const db = await openDatabase(path.join(dir, 'shapewall.db'))
120
+ const cleanup = []
121
+ const stopAll = async () => {
122
+ for (const step of cleanup.reverse()) await step()
123
+ cleanup.length = 0
124
+ }
125
+ try {
126
+ const { createHostedApp } = await import('./app.js')
127
+ const { createMailer } = await import('./mail.js')
128
+ const { turnstileFromEnv } = await import('./turnstile.js')
129
+ const { createRateLimiter } = await import('./ratelimit.js')
130
+ const { startRetention } = await import('./retention.js')
131
+ // Invite emails through Resend when RESEND_API_KEY and SHAPEWALL_EMAIL_FROM
132
+ // are set; otherwise admins copy the link.
133
+ const mailer = createMailer({ env, log: (line) => out(line) })
134
+ const turnstile = turnstileFromEnv(env, { log: (line) => out(line) })
135
+ if (Boolean(env.SHAPEWALL_TURNSTILE_SITE_KEY) !== Boolean(env.SHAPEWALL_TURNSTILE_SECRET))
136
+ out('Warning: Turnstile needs both SHAPEWALL_TURNSTILE_SITE_KEY and SHAPEWALL_TURNSTILE_SECRET; it stays off.')
137
+ const secret = readSecret(dir, env)
138
+ const rateLimiter = createRateLimiter()
139
+
140
+ // Mode 1: listen on loopback first (port 0 picks one), then point
141
+ // tailscale serve at it; the origin is only known after that.
142
+ const holder = { app: null, share: null }
143
+ const server = await listen((req, res) => (holder.app ? holder.app(req, res) : res.writeHead(503).end()), port, host)
144
+ cleanup.push(() => new Promise((resolve) => server.close(() => resolve())))
145
+ const localPort = server.address().port
146
+ let publicOrigin = origin || `http://${host.includes(':') ? `[${host}]` : host}:${localPort}`
147
+ let shareOrigin = null
148
+ let shareServer = null
149
+ if (tailscale) {
150
+ const ts = await import('./tailscale.js')
151
+ let funnel = null
152
+ if (tailscale.funnel) {
153
+ shareServer = await listen((req, res) => (holder.share ? holder.share(req, res) : res.writeHead(503).end()), 0, '127.0.0.1')
154
+ cleanup.push(() => new Promise((resolve) => shareServer.close(() => resolve())))
155
+ funnel = { httpsPort: tailscale.funnel.httpsPort, localPort: shareServer.address().port }
156
+ }
157
+ const served = await ts.startTailscale({
158
+ localPort,
159
+ httpsPort: tailscale.httpsPort ?? 443,
160
+ funnel,
161
+ ...(tailscale.run ? { run: tailscale.run } : {}),
162
+ })
163
+ cleanup.push(async () => {
164
+ const ok = await served.stop()
165
+ out(
166
+ ok
167
+ ? 'Removed the tailscale serve config this server added.'
168
+ : 'Could not remove the tailscale serve config; check tailscale serve status.',
169
+ )
170
+ })
171
+ publicOrigin = served.origin
172
+ shareOrigin = served.shareOrigin
173
+ trustProxy = true
174
+ out(`On your tailnet: ${publicOrigin} (tailscale serve, not public)`)
175
+ if (shareOrigin) out(`Share links are public through Tailscale Funnel: ${shareOrigin} (share pages only; the console is not there)`)
176
+ }
177
+
178
+ const warning = proxyWarning({ origin: publicOrigin, host, trustProxy })
179
+ if (warning) out(warning)
180
+ const common = {
181
+ db,
182
+ dataDir: dir,
183
+ signup,
184
+ trustProxy,
185
+ secret,
186
+ rateLimiter,
187
+ quotas,
188
+ legal,
189
+ usercontentOrigin,
190
+ turnstile,
191
+ reportEmail,
192
+ log: (line) => out(line),
193
+ }
194
+ const app = createHostedApp({ ...common, origin: publicOrigin, shareOrigin, previousOrigin, mailer: mailer.configured ? mailer : null })
195
+ app.locals.presence.attach(server)
196
+ holder.app = app
197
+ cleanup.push(() => app.locals.close())
198
+ if (shareServer) {
199
+ const { shareOnly } = await import('./tailscale.js')
200
+ const shareApp = createHostedApp({
201
+ ...common,
202
+ origin: shareOrigin,
203
+ shareOrigin,
204
+ guestOnly: true,
205
+ sweepEveryMs: 0,
206
+ eventBus: app.locals.events,
207
+ presenceHub: app.locals.presence.hub,
208
+ })
209
+ shareApp.locals.presence.attach(shareServer)
210
+ holder.share = shareOnly(shareApp)
211
+ cleanup.push(() => shareApp.locals.close())
212
+ }
213
+ const stopRetention = startRetention({
214
+ db,
215
+ dataDir: dir,
216
+ hours: retentionHours,
217
+ keepDefault: retentionKeep,
218
+ log: (line) => out(line),
219
+ })
220
+ cleanup.push(() => stopRetention())
221
+
222
+ out(`Shapewall hosted is listening on ${host}:${localPort} for ${publicOrigin} (sign-up: ${signup})`)
223
+ out(
224
+ !mailer.configured
225
+ ? 'Invite emails: off (set RESEND_API_KEY and SHAPEWALL_EMAIL_FROM to send them)'
226
+ : signup === 'open'
227
+ ? 'Invite emails: off (not with --signup open)'
228
+ : 'Invite emails: on (Resend)',
229
+ )
230
+ if (!legal.terms || !legal.privacy)
231
+ out('Legal links: not set (SHAPEWALL_HOSTED_TERMS_URL, SHAPEWALL_HOSTED_PRIVACY_URL); set them before inviting people.')
232
+ const setup = app.locals.setupLink()
233
+ if (setup) {
234
+ writeSetupLink(dir, setup)
235
+ out(`No accounts yet. The one-time setup link is in ${path.join(dir, 'setup-link')} (0600); read it privately on this machine.`)
236
+ }
237
+ let stopping = null
238
+ const stop = () => {
239
+ stopping ||= (async () => {
240
+ const force = setTimeout(() => exitOnStop && process.exit(0), 8000)
241
+ force.unref()
242
+ server.closeAllConnections?.()
243
+ shareServer?.closeAllConnections?.()
244
+ await stopAll()
245
+ process.off('SIGINT', stop)
246
+ process.off('SIGTERM', stop)
247
+ db.close()
248
+ if (exitOnStop) process.exit(0)
249
+ })()
250
+ return stopping
251
+ }
252
+ process.once('SIGINT', stop)
253
+ process.once('SIGTERM', stop)
254
+ return { server, shareServer, app, db, origin: publicOrigin, shareOrigin, stop }
255
+ } catch (error) {
256
+ await stopAll().catch(() => {})
257
+ db.close()
258
+ throw error
259
+ }
260
+ }
@@ -0,0 +1,64 @@
1
+ // The setup link: the one-time link that creates the first account on an
2
+ // invite-only server. It is a secret (whoever opens it first owns the
3
+ // server), so it never goes to the start log, which journald keeps: the
4
+ // server writes it to <data>/setup-link (mode 0600, only the operator reads
5
+ // it) and the log says where it is. `shapewall hosted setup-link` prints it
6
+ // in the operator's own terminal (or makes a new one). Using it removes the
7
+ // file.
8
+
9
+ import fs from 'node:fs'
10
+ import path from 'node:path'
11
+ import { randomToken, sha256 } from './crypto.js'
12
+ import { accounts } from './tenancy.js'
13
+
14
+ export const SETUP_FILE = 'setup-link'
15
+ export const SETUP_TTL_MS = 86_400_000
16
+
17
+ export const setupFile = (dataDir) => path.join(dataDir, SETUP_FILE)
18
+
19
+ // A new code (unused older ones stop working); returns the URL.
20
+ export function mintSetupLink(db, origin, now = new Date()) {
21
+ const q = accounts(db)
22
+ const code = randomToken(24)
23
+ q.run('DELETE FROM setup_codes WHERE used_at IS NULL')
24
+ q.run('INSERT INTO setup_codes (code_hash, created_at, expires_at) VALUES (:hash, :at, :expires)', {
25
+ hash: sha256(code),
26
+ at: now.toISOString(),
27
+ expires: new Date(now.getTime() + SETUP_TTL_MS).toISOString(),
28
+ })
29
+ return `${origin}/signup#setup=${code}`
30
+ }
31
+
32
+ // Whether a setup URL's code still works (unused, not expired).
33
+ export function setupLinkUsable(db, url, now = new Date()) {
34
+ let code = ''
35
+ try {
36
+ code = new URLSearchParams(new URL(url).hash.slice(1)).get('setup') || ''
37
+ } catch {
38
+ return false
39
+ }
40
+ if (!code) return false
41
+ const row = accounts(db).get('SELECT used_at, expires_at FROM setup_codes WHERE code_hash = :hash', { hash: sha256(code) })
42
+ return Boolean(row && !row.used_at && row.expires_at > now.toISOString())
43
+ }
44
+
45
+ // Written so that only the owner of the data folder can read it, even when
46
+ // the file existed before with looser permissions.
47
+ export function writeSetupLink(dataDir, url) {
48
+ const file = setupFile(dataDir)
49
+ fs.rmSync(file, { force: true })
50
+ fs.writeFileSync(file, `${url}\n`, { mode: 0o600, flag: 'wx' })
51
+ return file
52
+ }
53
+
54
+ export function readSetupLink(dataDir) {
55
+ try {
56
+ return fs.readFileSync(setupFile(dataDir), 'utf8').trim() || null
57
+ } catch {
58
+ return null
59
+ }
60
+ }
61
+
62
+ export const removeSetupLink = (dataDir) => fs.rmSync(setupFile(dataDir), { force: true })
63
+
64
+ export const userCount = (db) => accounts(db).get('SELECT COUNT(*) AS n FROM users').n
@@ -0,0 +1,323 @@
1
+ // Mode 2: `shapewall hosted --setup --domain app.example.com`. Writes a
2
+ // Docker Compose project for one VPS (the server plus Caddy for TLS) into a
3
+ // folder, checks DNS, and with --start brings it up and prints the one-time
4
+ // setup link.
5
+ //
6
+ // <dir>/compose.yml the server (no published port) and Caddy (80, 443)
7
+ // <dir>/Caddyfile the app site, and the usercontent site when
8
+ // --usercontent-domain is given (live HTML only: no
9
+ // cookies, no auth)
10
+ // <dir>/.env origin, sign-up, email and legal settings (0600)
11
+ // <dir>/data/ the server's data folder (back it up: hosted backup)
12
+ //
13
+ // The image is built from a Shapewall checkout (Dockerfile.hosted) until the
14
+ // package is on npm; --source points at it (default: this installation).
15
+ // examples/hosted/compose.yml and examples/hosted/Caddyfile.compose are these
16
+ // same templates for app.example.com (test/hosted-ops.test.js keeps them in
17
+ // step).
18
+
19
+ import fs from 'node:fs'
20
+ import os from 'node:os'
21
+ import path from 'node:path'
22
+ import dns from 'node:dns/promises'
23
+ import { fileURLToPath } from 'node:url'
24
+ import { runCommand } from './tailscale.js'
25
+
26
+ export class SetupError extends Error {}
27
+
28
+ const HERE = path.dirname(fileURLToPath(import.meta.url))
29
+ export const PACKAGE_ROOT = path.resolve(HERE, '..', '..')
30
+ const DOMAIN_RE = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/
31
+
32
+ export function cleanDomain(value, flag) {
33
+ const domain = String(value || '')
34
+ .trim()
35
+ .toLowerCase()
36
+ .replace(/\.$/, '')
37
+ if (!DOMAIN_RE.test(domain)) throw new SetupError(`${flag}: a host name such as app.example.com (no https://, no path)`)
38
+ return domain
39
+ }
40
+
41
+ // The registrable part, roughly (the last two labels). Enough to warn that a
42
+ // usercontent domain under the app's own domain shares its cookies.
43
+ const siteOf = (domain) => domain.split('.').slice(-2).join('.')
44
+
45
+ export function renderCompose() {
46
+ return `# Hosted Shapewall with Docker Compose: the server and Caddy (TLS) on one
47
+ # machine. Written by \`shapewall hosted --setup\` (docs/hosted.md, "Own
48
+ # domain"); settings live in .env next to this file.
49
+ #
50
+ # docker compose up -d --build
51
+ # docker compose exec shapewall cat /data/setup-link # read privately, never in logs
52
+ # docker compose exec shapewall node bin/shapewall.js hosted backup --data /data --to /backups --keep-days 30
53
+ #
54
+ # The server's port is never published: only Caddy reaches it, on the
55
+ # compose network, which is why it trusts X-Forwarded-For from private
56
+ # addresses (SHAPEWALL_HOSTED_TRUST_PROXY=uniquelocal).
57
+
58
+ services:
59
+ shapewall:
60
+ build:
61
+ context: \${SHAPEWALL_SOURCE:-.}
62
+ dockerfile: Dockerfile.hosted
63
+ image: shapewall-hosted:local
64
+ init: true
65
+ restart: unless-stopped
66
+ user: '\${SHAPEWALL_UID:-1000}:\${SHAPEWALL_GID:-1000}'
67
+ env_file: .env
68
+ environment:
69
+ SHAPEWALL_HOSTED_DATA: /data
70
+ SHAPEWALL_HOSTED_TRUST_PROXY: uniquelocal
71
+ command: ['hosted', '--host', '0.0.0.0', '--port', '4700']
72
+ volumes:
73
+ - ./data:/data
74
+ - ./backups:/backups
75
+ read_only: true
76
+ tmpfs:
77
+ - /tmp
78
+ cap_drop:
79
+ - ALL
80
+ security_opt:
81
+ - no-new-privileges:true
82
+ mem_limit: 2g
83
+ pids_limit: 256
84
+
85
+ caddy:
86
+ image: caddy:2
87
+ restart: unless-stopped
88
+ depends_on:
89
+ - shapewall
90
+ ports:
91
+ - '80:80'
92
+ - '443:443'
93
+ - '443:443/udp'
94
+ volumes:
95
+ - ./Caddyfile:/etc/caddy/Caddyfile:ro
96
+ - ./caddy/data:/data
97
+ - ./caddy/config:/config
98
+ `
99
+ }
100
+
101
+ const LOG_FILTER = ` log {
102
+ output stdout
103
+ # Never log cookies, tokens or the signature of a live-HTML URL.
104
+ # Invite, setup and share tokens travel in the URL fragment, which
105
+ # browsers never send.
106
+ format filter {
107
+ wrap json
108
+ fields {
109
+ request>headers>Cookie delete
110
+ request>headers>Authorization delete
111
+ request>uri query {
112
+ delete s
113
+ }
114
+ resp_headers>Set-Cookie delete
115
+ }
116
+ }
117
+ }`
118
+
119
+ export function renderCaddyfile({ domain, usercontentDomain = null, email = null, upstream = 'shapewall:4700' }) {
120
+ const global = email ? `{\n\temail ${email}\n}\n\n` : ''
121
+ const app = `${domain} {
122
+ encode zstd gzip
123
+
124
+ # Pushes upload one file per request; the largest is a 10 MB PNG.
125
+ request_body {
126
+ max_size 12MB
127
+ }
128
+
129
+ reverse_proxy ${upstream}
130
+
131
+ # The server sets its own security headers (CSP per route, nosniff,
132
+ # no-referrer, HSTS, noindex, Cache-Control). Do not override them here.
133
+ header -Server
134
+
135
+ # A staging copy: keep it private (uncomment, make a hash with
136
+ # caddy hash-password). Share links and /uc/ stay outside the gate.
137
+ # @gated not path /s/* /share /api/shares/* /uc/* /report /api/health
138
+ # basic_auth @gated {
139
+ # reviewer <hash>
140
+ # }
141
+
142
+ ${LOG_FILTER}
143
+ }
144
+ `
145
+ const usercontent = usercontentDomain
146
+ ? `
147
+ # Live HTML on its own registrable domain: no cookies in, none out, no
148
+ # auth, nothing but /uc/ (signed, expiring URLs the board hands out).
149
+ ${usercontentDomain} {
150
+ request_header -Cookie
151
+ request_header -Authorization
152
+ @uc path /uc/*
153
+ handle @uc {
154
+ reverse_proxy ${upstream} {
155
+ header_down -Set-Cookie
156
+ }
157
+ }
158
+ handle {
159
+ respond "Not found" 404
160
+ }
161
+ header -Server
162
+
163
+ ${LOG_FILTER}
164
+ }
165
+ `
166
+ : ''
167
+ return `# Caddy for hosted Shapewall: TLS, then the server. Written by
168
+ # \`shapewall hosted --setup\` (docs/hosted.md, "Own domain").
169
+
170
+ ${global}${app}${usercontent}`
171
+ }
172
+
173
+ export function renderEnv({ domain, usercontentDomain = null, uid = 1000, gid = 1000, source }) {
174
+ return `# Hosted Shapewall settings (docs/hosted.md). This file holds secrets once
175
+ # you fill them in: keep it 0600 and out of git.
176
+ SHAPEWALL_HOSTED_ORIGIN=https://${domain}
177
+ SHAPEWALL_HOSTED_SIGNUP=invite
178
+ ${usercontentDomain ? `SHAPEWALL_USERCONTENT_ORIGIN=https://${usercontentDomain}\n` : ''}SHAPEWALL_SOURCE=${source}
179
+ SHAPEWALL_UID=${uid}
180
+ SHAPEWALL_GID=${gid}
181
+
182
+ # Invite emails through Resend (optional): both or neither.
183
+ RESEND_API_KEY=
184
+ SHAPEWALL_EMAIL_FROM=
185
+
186
+ # Shown on sign-up and share pages and on /report (fill in before inviting
187
+ # anyone; examples/hosted/legal/ has templates).
188
+ SHAPEWALL_HOSTED_TERMS_URL=
189
+ SHAPEWALL_HOSTED_PRIVACY_URL=
190
+ SHAPEWALL_HOSTED_AUP_URL=
191
+ SHAPEWALL_HOSTED_SUBPROCESSORS_URL=
192
+ SHAPEWALL_HOSTED_ABUSE_EMAIL=
193
+ `
194
+ }
195
+
196
+ function localAddresses() {
197
+ const out = new Set()
198
+ for (const list of Object.values(os.networkInterfaces())) for (const item of list || []) if (!item.internal) out.add(item.address)
199
+ return out
200
+ }
201
+
202
+ // Where each name points, and whether that is this machine. Behind NAT or a
203
+ // floating IP the public address is not on an interface: a warning, not an
204
+ // error.
205
+ export async function checkDns(names, { resolve = dns, addresses = localAddresses() } = {}) {
206
+ const results = []
207
+ for (const name of names) {
208
+ const found = []
209
+ for (const kind of ['resolve4', 'resolve6']) {
210
+ try {
211
+ found.push(...(await resolve[kind](name)))
212
+ } catch {
213
+ /* no record of this kind */
214
+ }
215
+ }
216
+ const here = found.filter((address) => addresses.has(address))
217
+ results.push({
218
+ name,
219
+ addresses: found,
220
+ ok: found.length > 0,
221
+ here: here.length > 0,
222
+ message: !found.length
223
+ ? `${name} has no A or AAAA record yet. Point it at this server; Caddy cannot get a certificate until it resolves.`
224
+ : here.length
225
+ ? `${name} points at this machine (${here.join(', ')}).`
226
+ : `${name} points at ${found.join(', ')}, which is not an address on this machine (fine behind NAT or a floating IP; otherwise fix the record).`,
227
+ })
228
+ }
229
+ return results
230
+ }
231
+
232
+ export function sourceProblem(source) {
233
+ for (const file of ['Dockerfile.hosted', 'package.json', 'package-lock.json', 'client', 'src/hosted']) {
234
+ if (!fs.existsSync(path.join(source, file)))
235
+ return `${source} is not a Shapewall checkout (no ${file}). Clone https://github.com/danbaruch/shapewall and pass --source <that folder>.`
236
+ }
237
+ return null
238
+ }
239
+
240
+ // Plans (and unless dryRun, writes) the folder. Returns { dir, files, dns,
241
+ // warnings, next }.
242
+ export async function setupHosted({
243
+ domain: rawDomain,
244
+ usercontentDomain: rawUsercontent = null,
245
+ email = null,
246
+ dir: rawDir = 'shapewall-hosted',
247
+ source = PACKAGE_ROOT,
248
+ dryRun = false,
249
+ force = false,
250
+ resolve = dns,
251
+ addresses = undefined,
252
+ uid = typeof process.getuid === 'function' ? process.getuid() : 1000,
253
+ gid = typeof process.getgid === 'function' ? process.getgid() : 1000,
254
+ }) {
255
+ if (!rawDomain) throw new SetupError('--setup needs --domain app.example.com (the name people will open)')
256
+ const domain = cleanDomain(rawDomain, '--domain')
257
+ const usercontentDomain = rawUsercontent ? cleanDomain(rawUsercontent, '--usercontent-domain') : null
258
+ if (email !== null && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(email)))
259
+ throw new SetupError('--email: an email address (for the TLS certificate)')
260
+ const warnings = []
261
+ if (usercontentDomain === domain) throw new SetupError('--usercontent-domain must differ from --domain')
262
+ if (usercontentDomain && siteOf(usercontentDomain) === siteOf(domain))
263
+ warnings.push(
264
+ `${usercontentDomain} shares a registrable domain with ${domain}: cookies set for ${siteOf(domain)} would reach live HTML. Use a separate domain (for example ${siteOf(domain).replace(/\..*$/, '')}content.com).`,
265
+ )
266
+ const dir = path.resolve(rawDir)
267
+ const sourceDir = path.resolve(source)
268
+ const problem = sourceProblem(sourceDir)
269
+ if (problem) warnings.push(problem)
270
+ // Running as root: the container still runs as an unprivileged user.
271
+ const runAs = uid === 0 ? { uid: 1000, gid: 1000 } : { uid, gid }
272
+ const files = {
273
+ 'compose.yml': renderCompose(),
274
+ Caddyfile: renderCaddyfile({ domain, usercontentDomain, email }),
275
+ '.env': renderEnv({ domain, usercontentDomain, source: sourceDir, ...runAs }),
276
+ }
277
+ const existing = Object.keys(files).filter((name) => fs.existsSync(path.join(dir, name)))
278
+ if (existing.length && !force && !dryRun)
279
+ throw new SetupError(`${dir} already has ${existing.join(', ')}. Pass --force to overwrite (the data folder is never touched).`)
280
+ const dnsResults = await checkDns([domain, ...(usercontentDomain ? [usercontentDomain] : [])], {
281
+ resolve,
282
+ ...(addresses ? { addresses } : {}),
283
+ })
284
+ if (!dryRun) {
285
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
286
+ for (const [name, text] of Object.entries(files))
287
+ fs.writeFileSync(path.join(dir, name), text, { mode: name === '.env' ? 0o600 : 0o644 })
288
+ fs.chmodSync(path.join(dir, '.env'), 0o600)
289
+ for (const sub of ['data', 'backups']) {
290
+ const folder = path.join(dir, sub)
291
+ fs.mkdirSync(folder, { recursive: true, mode: 0o700 })
292
+ if (uid === 0) fs.chownSync(folder, runAs.uid, runAs.gid)
293
+ }
294
+ }
295
+ const next = [
296
+ `cd ${dir}`,
297
+ 'Fill in .env (legal page links, abuse email; Resend for invite emails, optional)',
298
+ 'docker compose up -d --build',
299
+ 'docker compose exec shapewall cat /data/setup-link (read privately)',
300
+ ]
301
+ return { dir, domain, usercontentDomain, files, existing, dns: dnsResults, warnings, next, dryRun }
302
+ }
303
+
304
+ // --start is explicit: no containers or services start during file generation.
305
+ // Setup URLs stay out of Compose/journald logs; read the private file directly.
306
+ export async function startCompose({ dir, run = runCommand, out = () => {} }) {
307
+ const compose = await run('docker', ['compose', 'version'])
308
+ if (compose.missing || compose.code !== 0)
309
+ throw new SetupError(
310
+ 'Docker Compose is not available (docker compose version failed). Install Docker Engine with the compose plugin first.',
311
+ )
312
+ out('Building and starting (docker compose up -d --build)...')
313
+ const up = await run('docker', ['compose', '--project-directory', dir, 'up', '-d', '--build', '--wait'], { timeoutMs: 30 * 60_000 })
314
+ if (up.code !== 0)
315
+ throw new SetupError('docker compose up failed; inspect its status locally (output can contain sensitive configuration).')
316
+ const link = await run('docker', ['compose', '--project-directory', dir, 'exec', '-T', 'shapewall', 'cat', '/data/setup-link'])
317
+ const setupLink = String(link.stdout || '').trim()
318
+ if (link.code === 0 && /^https:\/\/[^\s]+\/signup#setup=[A-Za-z0-9_-]+$/.test(setupLink)) return { setupLink }
319
+ return {
320
+ setupLink: null,
321
+ note: 'The server is healthy. Read its setup link privately: docker compose exec shapewall cat /data/setup-link. Existing accounts do not need it.',
322
+ }
323
+ }