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,180 @@
1
+ // `shapewall agent doctor`: is the starter agent ready on this machine?
2
+ //
3
+ // Checks the runtime (docker or podman, rootless or not), the image, the
4
+ // model endpoint, who may dispatch work on each board, and then, unless
5
+ // --no-egress, starts a container exactly like the agent's (same network,
6
+ // proxy, mounts, user, limits) with the probe instead of the agent
7
+ // (probe.js): not root, no capabilities, read-only root, only the worktree
8
+ // mounted, no host home or runtime socket, no host environment, no direct
9
+ // egress or outside DNS, no way to this machine's own ports, and a proxy
10
+ // that refuses hosts off the list.
11
+
12
+ import fs from 'node:fs'
13
+ import net from 'node:net'
14
+ import os from 'node:os'
15
+ import path from 'node:path'
16
+ import { readLines } from './rpc.js'
17
+ import { DEFAULT_IMAGE, PROBE_ENTRY, agentRunArgs, runNames } from './runtime.js'
18
+ import { egressAllowList, startEgress } from './supervisor.js'
19
+ import { newRunId } from './worktree.js'
20
+
21
+ export async function starterDoctor({
22
+ config,
23
+ settings,
24
+ runtime,
25
+ runtimeProblem = null,
26
+ image,
27
+ egress = true,
28
+ uid = process.getuid?.() ?? 1000,
29
+ gid = process.getgid?.() ?? 1000,
30
+ }) {
31
+ const checks = []
32
+ const add = (name, ok, detail, hint = null) => checks.push({ name, ok, detail, ...(hint ? { hint } : {}) })
33
+ if (!runtime) {
34
+ add('runtime', false, runtimeProblem || 'no container runtime')
35
+ return { ok: false, checks }
36
+ }
37
+ const version = await runtime.exec(['--version'])
38
+ let rootless = null
39
+ if (runtime.name === 'podman') {
40
+ const info = await runtime.exec(['info', '--format', '{{.Host.Security.Rootless}}'])
41
+ rootless = info.stdout.trim() === 'true'
42
+ } else {
43
+ const info = await runtime.exec(['info', '--format', '{{json .SecurityOptions}}'])
44
+ rootless = /rootless/.test(info.stdout)
45
+ }
46
+ add(
47
+ 'runtime',
48
+ version.code === 0,
49
+ `${version.stdout.trim().split('\n')[0] || runtime.name}${rootless === null ? '' : rootless ? ', rootless' : ', rootful'} (${runtime.bin})`,
50
+ runtime.name === 'docker' && rootless
51
+ ? 'rootless docker maps your uid to another one: the agent may not be able to write the worktree (the probe below checks)'
52
+ : null,
53
+ )
54
+ add('as your user', uid !== 0, uid === 0 ? 'running as root: the agent must not' : `uid ${uid}`)
55
+ const inspected = await runtime.exec(['image', 'inspect', image])
56
+ const imageOk = inspected.code === 0
57
+ add(
58
+ 'image',
59
+ imageOk,
60
+ imageOk ? image : `${image} is not built`,
61
+ imageOk ? null : `build it: shapewall agent build-image${image === DEFAULT_IMAGE ? '' : ` --image ${image}`}`,
62
+ )
63
+ add(
64
+ 'model',
65
+ !settings.problem,
66
+ settings.problem ||
67
+ `${settings.model.model} at ${settings.model.host}${settings.model.hasKey ? `, key from ${settings.model.keyVar}` : ', no key'}`,
68
+ )
69
+ for (const board of config.boards || []) {
70
+ const trusted = [...settings.trustedFor(board.id)]
71
+ add(
72
+ `trusted on ${board.id}`,
73
+ trusted.length > 0,
74
+ trusted.length ? trusted.join(', ') : 'nobody: no comment is dispatched',
75
+ trusted.length
76
+ ? 'local boards match the typed author name (not authenticated); hosted boards match account handles'
77
+ : 'set starterAgent.trusted (or starterAgent.boards.<id>.trusted) or pass --trusted',
78
+ )
79
+ }
80
+ add(
81
+ 'tests',
82
+ Boolean(settings.testCommand),
83
+ settings.testCommand ? settings.testCommand.join(' ') : 'no starterAgent.testCommand: the agent cannot run tests',
84
+ )
85
+ const allow = egressAllowList(settings)
86
+ add(
87
+ 'egress allow list',
88
+ true,
89
+ allow.map((entry) => `${entry.host}:${entry.port}`).join(', ') || 'nothing',
90
+ 'the model is called from this machine, never from the container',
91
+ )
92
+
93
+ if (egress && imageOk && uid !== 0) {
94
+ const runId = newRunId()
95
+ const names = runNames(runId)
96
+ const cleanup = []
97
+ const work = fs.mkdtempSync(path.join(os.tmpdir(), 'shapewall-probe-'))
98
+ // Something listening on this machine, on every address: the sandbox must not reach it.
99
+ const listener = net.createServer((socket) => socket.end('host\n'))
100
+ try {
101
+ await new Promise((resolve, reject) => listener.once('error', reject).listen(0, '0.0.0.0', resolve))
102
+ await startEgress({ runtime, runId, image, allow, cleanup, readyTimeoutMs: 60000 })
103
+ const allowed = settings.registry ? `${settings.registry.host}:${settings.registry.port}` : null
104
+ const args = agentRunArgs({
105
+ runtime: runtime.name,
106
+ runId,
107
+ image,
108
+ worktree: fs.realpathSync(work),
109
+ uid,
110
+ gid,
111
+ limits: settings.limits,
112
+ entry: [
113
+ ...PROBE_ENTRY,
114
+ '--host-home',
115
+ os.homedir(),
116
+ '--out',
117
+ '/work/probe.json',
118
+ ...(allowed ? ['--allowed', allowed] : []),
119
+ '--host-port',
120
+ String(listener.address().port),
121
+ ],
122
+ })
123
+ cleanup.unshift(() => runtime.exec(['rm', '-f', names.agent]))
124
+ const child = runtime.spawn(args)
125
+ child.stdin.end()
126
+ let report = null
127
+ readLines(child.stdout, (line) => (report = line))
128
+ let stderr = ''
129
+ child.stderr.on('data', (chunk) => (stderr = (stderr + chunk).slice(-2000)))
130
+ await new Promise((resolve) => {
131
+ const timer = setTimeout(() => runtime.exec(['kill', names.agent]).finally(resolve), 90000)
132
+ child.once('close', () => (clearTimeout(timer), resolve()))
133
+ child.once('error', () => (clearTimeout(timer), resolve()))
134
+ })
135
+ if (!report?.checks) add('sandbox probe', false, `the probe did not report${stderr ? `: ${stderr.trim().slice(-300)}` : ''}`)
136
+ else {
137
+ for (const [name, item] of Object.entries(report.checks)) {
138
+ // The registry may be unreachable from this network without it being the sandbox's fault.
139
+ add(
140
+ `sandbox: ${name}`,
141
+ item.ok || name === 'proxy passes allowed hosts',
142
+ item.detail,
143
+ !item.ok && name === 'proxy passes allowed hosts' ? 'the registry was not reachable through the proxy (offline?)' : null,
144
+ )
145
+ }
146
+ const owner = (() => {
147
+ try {
148
+ return fs.lstatSync(path.join(work, 'probe.json')).uid
149
+ } catch {
150
+ return null
151
+ }
152
+ })()
153
+ add(
154
+ 'sandbox: files are yours',
155
+ owner === uid,
156
+ owner === null ? 'the probe could not write the worktree' : `written as uid ${owner}`,
157
+ )
158
+ }
159
+ } catch (error) {
160
+ add('sandbox probe', false, error.message)
161
+ } finally {
162
+ listener.close()
163
+ for (const step of cleanup) await Promise.resolve(step()).catch(() => {})
164
+ fs.rmSync(work, { recursive: true, force: true })
165
+ }
166
+ } else if (egress) {
167
+ add('sandbox probe', false, 'skipped: needs the image and a non-root user')
168
+ }
169
+ return { ok: checks.every((item) => item.ok), checks }
170
+ }
171
+
172
+ export function formatStarterDoctor(report) {
173
+ const lines = ['Starter agent']
174
+ for (const item of report.checks) {
175
+ lines.push(` ${item.ok ? 'ok ' : 'FAIL'} ${item.name}: ${item.detail}`)
176
+ if (item.hint) lines.push(` ${item.hint}`)
177
+ }
178
+ lines.push(report.ok ? 'Ready.' : 'Not ready: fix the FAIL lines above (docs/starter-agent.md).')
179
+ return lines.join('\n')
180
+ }
@@ -0,0 +1,351 @@
1
+ // The starter agent's egress proxy: the only way out of the agent container.
2
+ //
3
+ // The agent container sits on an internal network with no route out and no
4
+ // outside DNS. This proxy runs in a second container on that network and on
5
+ // an ordinary one, and passes on exactly the host:port pairs it was given
6
+ // (the package registry, plus any the person added; the model is called
7
+ // from the host, not through here):
8
+ //
9
+ // - CONNECT host:port (https, and anything else tunnelled) only to an
10
+ // allowed pair;
11
+ // - plain http (absolute-form "GET http://host:port/path") only to an
12
+ // allowed pair, for local servers that speak http;
13
+ // - everything else answers 403, and each refusal is logged.
14
+ //
15
+ // Names are resolved here, then checked again by address: a name on the
16
+ // default list (the npm registry) that resolves to a private, loopback or
17
+ // link-local address is refused, so a rebinding DNS answer cannot turn it
18
+ // into a way onto the host's network. Pairs the person chose (--allow-host)
19
+ // may be private: a mirror on the LAN is the point of them.
20
+ //
21
+ // Configuration comes from the environment (no secret in it):
22
+ // SHAPEWALL_EGRESS_ALLOW "host:port,host:port!private,..." (!private: may resolve to a private address)
23
+ // SHAPEWALL_EGRESS_PORT default 3128
24
+ // Log lines are JSON on stdout: { ready }, { allow, host, port }, { deny, host, port, reason }.
25
+
26
+ import dns from 'node:dns/promises'
27
+ import http from 'node:http'
28
+ import net from 'node:net'
29
+ import { fileURLToPath } from 'node:url'
30
+
31
+ export const PROXY_PORT = 3128
32
+ const HOST_RE = /^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$/
33
+ const CONNECT_TIMEOUT_MS = 15000
34
+ const IDLE_TIMEOUT_MS = 10 * 60 * 1000
35
+
36
+ // "host:port" or "host:port!private" -> { host, port, private }. Throws for anything else.
37
+ export function parseAllowEntry(value) {
38
+ const raw = String(value || '')
39
+ .trim()
40
+ .toLowerCase()
41
+ const priv = raw.endsWith('!private')
42
+ const body = priv ? raw.slice(0, -8) : raw
43
+ const match = /^(\[[0-9a-f:.]+\]|[^:[\]]+):(\d{1,5})$/.exec(body)
44
+ if (!match) throw new Error(`egress allow entry "${value}" is not host:port`)
45
+ const host = match[1].replace(/^\[|\]$/g, '')
46
+ const port = Number(match[2])
47
+ if (!(port > 0 && port < 65536)) throw new Error(`egress allow entry "${value}" has a bad port`)
48
+ if (!net.isIP(host) && !HOST_RE.test(host)) throw new Error(`egress allow entry "${value}" has a bad host`)
49
+ return { host, port, private: priv }
50
+ }
51
+
52
+ export function parseAllowList(value) {
53
+ return String(value || '')
54
+ .split(',')
55
+ .map((item) => item.trim())
56
+ .filter(Boolean)
57
+ .map(parseAllowEntry)
58
+ }
59
+
60
+ export function formatAllowEntry(entry) {
61
+ const host = net.isIP(entry.host) === 6 ? `[${entry.host}]` : entry.host
62
+ return `${host}:${entry.port}${entry.private ? '!private' : ''}`
63
+ }
64
+
65
+ // An IPv6 address as eight 16-bit numbers (with an embedded IPv4 tail), or null.
66
+ function ipv6Words(value) {
67
+ let text = value.replace(/%.*$/, '')
68
+ const tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text)
69
+ if (tail) {
70
+ const bytes = tail[1].split('.').map(Number)
71
+ text = `${text.slice(0, -tail[1].length)}${((bytes[0] << 8) | bytes[1]).toString(16)}:${((bytes[2] << 8) | bytes[3]).toString(16)}`
72
+ }
73
+ const halves = text.split('::')
74
+ if (halves.length > 2) return null
75
+ const head = halves[0] ? halves[0].split(':') : []
76
+ const rest = halves.length === 2 && halves[1] ? halves[1].split(':') : []
77
+ const fill = halves.length === 2 ? 8 - head.length - rest.length : 0
78
+ const parts = [...head, ...Array(Math.max(0, fill)).fill('0'), ...rest]
79
+ if (parts.length !== 8 || !parts.every((part) => /^[0-9a-f]{1,4}$/.test(part))) return null
80
+ return parts.map((part) => parseInt(part, 16))
81
+ }
82
+
83
+ // The server name a TLS ClientHello asks for. Bytes may come in pieces:
84
+ // -> { need: true } (wait for more), { error }, or { sni, ech }.
85
+ export function readClientHello(buffer) {
86
+ // Handshake bytes from consecutive TLS handshake records.
87
+ let offset = 0
88
+ const chunks = []
89
+ let handshake = Buffer.alloc(0)
90
+ for (;;) {
91
+ if (buffer.length < offset + 5) return { need: true }
92
+ if (buffer[offset] !== 0x16) return { error: 'not TLS' }
93
+ if (buffer[offset + 1] !== 3) return { error: 'not TLS' }
94
+ const length = buffer.readUInt16BE(offset + 3)
95
+ if (length === 0 || length > 16384) return { error: 'bad TLS record' }
96
+ if (buffer.length < offset + 5 + length) return { need: true }
97
+ chunks.push(buffer.subarray(offset + 5, offset + 5 + length))
98
+ offset += 5 + length
99
+ handshake = Buffer.concat(chunks)
100
+ if (handshake.length >= 4) {
101
+ if (handshake[0] !== 1) return { error: 'not a ClientHello' }
102
+ const total = handshake.readUIntBE(1, 3)
103
+ if (total > 65536) return { error: 'ClientHello too big' }
104
+ if (handshake.length >= 4 + total) {
105
+ handshake = handshake.subarray(4, 4 + total)
106
+ break
107
+ }
108
+ }
109
+ }
110
+ try {
111
+ let at = 2 + 32 // version, random
112
+ at += 1 + handshake[at] // session id
113
+ at += 2 + handshake.readUInt16BE(at) // cipher suites
114
+ at += 1 + handshake[at] // compression methods
115
+ if (at === handshake.length) return { sni: null, ech: false }
116
+ const end = at + 2 + handshake.readUInt16BE(at)
117
+ if (end > handshake.length) return { error: 'bad ClientHello' }
118
+ at += 2
119
+ let sni = null
120
+ let ech = false
121
+ while (at + 4 <= end) {
122
+ const type = handshake.readUInt16BE(at)
123
+ const length = handshake.readUInt16BE(at + 2)
124
+ const data = handshake.subarray(at + 4, at + 4 + length)
125
+ if (data.length !== length) return { error: 'bad ClientHello' }
126
+ if (type === 0xfe0d) ech = true
127
+ if (type === 0) {
128
+ if (sni !== null) return { error: 'two server_name extensions' }
129
+ const listEnd = 2 + data.readUInt16BE(0)
130
+ let inner = 2
131
+ const names = []
132
+ while (inner + 3 <= listEnd) {
133
+ const nameType = data[inner]
134
+ const nameLength = data.readUInt16BE(inner + 1)
135
+ if (nameType === 0) names.push(data.subarray(inner + 3, inner + 3 + nameLength).toString('latin1'))
136
+ inner += 3 + nameLength
137
+ }
138
+ if (names.length !== 1) return { error: 'not exactly one server name' }
139
+ sni = names[0].toLowerCase()
140
+ }
141
+ at += 4 + length
142
+ }
143
+ return { sni, ech }
144
+ } catch {
145
+ return { error: 'bad ClientHello' }
146
+ }
147
+ }
148
+
149
+ const HELLO_MAX = 70000
150
+ const HELLO_TIMEOUT_MS = 10000
151
+
152
+ // Private, loopback, link-local, unique-local, CGNAT, multicast and unspecified addresses.
153
+ export function privateAddress(address) {
154
+ const value = String(address || '').toLowerCase()
155
+ if (net.isIP(value) === 4) {
156
+ const [a, b] = value.split('.').map(Number)
157
+ return (
158
+ a === 0 ||
159
+ a === 10 ||
160
+ a === 127 ||
161
+ (a === 100 && b >= 64 && b <= 127) ||
162
+ (a === 169 && b === 254) ||
163
+ (a === 172 && b >= 16 && b <= 31) ||
164
+ (a === 192 && b === 168) ||
165
+ a >= 224
166
+ )
167
+ }
168
+ if (net.isIP(value) === 6) {
169
+ const words = ipv6Words(value)
170
+ if (!words) return true
171
+ if (words.every((word) => word === 0)) return true // ::
172
+ if (words.slice(0, 7).every((word) => word === 0) && words[7] === 1) return true // ::1
173
+ const v4 = (high, low) => `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`
174
+ // IPv4-mapped (::ffff:a.b.c.d, also written ::ffff:7f00:1) and IPv4-compatible (::a.b.c.d).
175
+ if (words.slice(0, 5).every((word) => word === 0) && (words[5] === 0xffff || words[5] === 0))
176
+ return privateAddress(v4(words[6], words[7]))
177
+ // NAT64 (64:ff9b::/96 and the local-use 64:ff9b:1::/48): the IPv4 address is inside.
178
+ if (words[0] === 0x64 && words[1] === 0xff9b) return words[2] === 1 || privateAddress(v4(words[6], words[7]))
179
+ // 6to4 (2002::/16) carries an IPv4 address too; Teredo (2001:0::/32) is a tunnel: refuse.
180
+ if (words[0] === 0x2002) return privateAddress(v4(words[1], words[2]))
181
+ if (words[0] === 0x2001 && words[1] === 0) return true
182
+ const first = words[0]
183
+ return (
184
+ (first & 0xfe00) === 0xfc00 ||
185
+ (first & 0xffc0) === 0xfe80 ||
186
+ (first & 0xffc0) === 0xfec0 ||
187
+ (first & 0xff00) === 0xff00 ||
188
+ first === 0x0100
189
+ )
190
+ }
191
+ return true
192
+ }
193
+
194
+ // createEgressProxy({ allow, log, lookup }) -> http.Server (not listening yet).
195
+ // The timeouts are options for the tests only.
196
+ export function createEgressProxy({
197
+ allow,
198
+ log = (entry) => process.stdout.write(`${JSON.stringify(entry)}\n`),
199
+ lookup = dns.lookup,
200
+ connectTimeoutMs = CONNECT_TIMEOUT_MS,
201
+ idleTimeoutMs = IDLE_TIMEOUT_MS,
202
+ }) {
203
+ const entries = allow.map((entry) => ({ ...entry, host: entry.host.toLowerCase() }))
204
+ const find = (host, port) => entries.find((entry) => entry.host === String(host).toLowerCase() && entry.port === Number(port))
205
+
206
+ // The address to connect to, or a reason to refuse.
207
+ async function resolve(host, port) {
208
+ const entry = find(host, port)
209
+ if (!entry) return { reason: 'not on the allow list' }
210
+ let address = entry.host
211
+ if (!net.isIP(address)) {
212
+ try {
213
+ address = (await lookup(entry.host, { verbatim: true })).address
214
+ } catch (error) {
215
+ return { reason: `cannot resolve (${error.code || error.message})` }
216
+ }
217
+ }
218
+ if (!entry.private && privateAddress(address)) return { reason: `resolves to a private address (${address})` }
219
+ return { address, entry }
220
+ }
221
+
222
+ const deny = (host, port, reason) => log({ deny: true, host: String(host).slice(0, 255), port: Number(port) || null, reason })
223
+
224
+ const server = http.createServer(async (req, res) => {
225
+ // Plain http, absolute-form only.
226
+ let url
227
+ try {
228
+ url = new URL(req.url)
229
+ } catch {
230
+ url = null
231
+ }
232
+ if (!url || url.protocol !== 'http:') {
233
+ deny(req.headers.host || '', 0, 'not a proxy request')
234
+ res.writeHead(403, { 'Content-Type': 'text/plain' }).end('Shapewall egress proxy: only allowed hosts\n')
235
+ return
236
+ }
237
+ const port = Number(url.port || 80)
238
+ const target = await resolve(url.hostname, port)
239
+ if (!target.address) {
240
+ deny(url.hostname, port, target.reason)
241
+ res.writeHead(403, { 'Content-Type': 'text/plain' }).end(`Shapewall egress proxy: ${url.hostname}:${port} is ${target.reason}\n`)
242
+ return
243
+ }
244
+ log({ allow: true, host: url.hostname, port, method: req.method })
245
+ const headers = { ...req.headers, host: url.host }
246
+ for (const name of ['proxy-connection', 'proxy-authorization', 'connection', 'keep-alive']) delete headers[name]
247
+ const upstream = http.request(
248
+ { host: target.address, port, method: req.method, path: `${url.pathname}${url.search}`, headers, timeout: idleTimeoutMs },
249
+ (answer) => {
250
+ answer.on('error', () => res.destroy())
251
+ res.writeHead(answer.statusCode || 502, answer.headers)
252
+ answer.pipe(res)
253
+ },
254
+ )
255
+ // The timeout option only emits 'timeout'; ending the request is ours to do.
256
+ upstream.on('timeout', () => upstream.destroy(Object.assign(new Error('upstream timed out'), { code: 'ETIMEDOUT' })))
257
+ upstream.on('error', () => {
258
+ // Mid-body a 502 cannot be sent any more: cut the response instead.
259
+ if (res.headersSent) return res.destroy()
260
+ res.writeHead(502, { 'Content-Type': 'text/plain' }).end()
261
+ })
262
+ // The client went away before the answer was sent: stop the upstream request too.
263
+ res.on('close', () => {
264
+ if (!res.writableFinished) upstream.destroy()
265
+ })
266
+ req.pipe(upstream)
267
+ })
268
+
269
+ server.on('connect', async (req, client, head) => {
270
+ client.on('error', () => {})
271
+ const match = /^(\[[0-9a-fA-F:.]+\]|[^:[\]]+):(\d{1,5})$/.exec(String(req.url || ''))
272
+ const host = match ? match[1].replace(/^\[|\]$/g, '') : String(req.url || '')
273
+ const port = match ? Number(match[2]) : 0
274
+ const target = match ? await resolve(host, port) : { reason: 'not host:port' }
275
+ if (!target.address) {
276
+ deny(host, port, target.reason)
277
+ client.end('HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\n\r\nShapewall egress proxy: only allowed hosts\n')
278
+ return
279
+ }
280
+ const upstream = net.connect({ host: target.address, port, timeout: connectTimeoutMs })
281
+ let established = false
282
+ upstream.once('connect', () => {
283
+ established = true
284
+ upstream.setTimeout(idleTimeoutMs)
285
+ client.write('HTTP/1.1 200 Connection Established\r\n\r\n')
286
+ // Only TLS, and only to the name that was allowed: many hosts share an
287
+ // address (a CDN), so the address alone would let any of them through.
288
+ let buffered = head?.length ? Buffer.from(head) : Buffer.alloc(0)
289
+ const refuse = (reason) => {
290
+ deny(host, port, reason)
291
+ clearTimeout(timer)
292
+ client.destroy()
293
+ upstream.destroy()
294
+ }
295
+ const timer = setTimeout(() => refuse('no TLS ClientHello'), HELLO_TIMEOUT_MS)
296
+ const check = () => {
297
+ const hello = readClientHello(buffered)
298
+ if (hello.need) {
299
+ if (buffered.length > HELLO_MAX) refuse('ClientHello too big')
300
+ return
301
+ }
302
+ client.off('data', onData)
303
+ if (hello.error) return refuse(`${hello.error} (CONNECT carries TLS only)`)
304
+ if (hello.ech) return refuse('encrypted ClientHello (ECH)')
305
+ const expected = target.entry.host
306
+ if (hello.sni === null ? !net.isIP(expected) : hello.sni !== expected) {
307
+ return refuse(`TLS server name ${hello.sni === null ? 'missing' : `"${hello.sni.slice(0, 100)}"`} is not ${expected}`)
308
+ }
309
+ clearTimeout(timer)
310
+ log({ allow: true, host, port, method: 'CONNECT' })
311
+ upstream.write(buffered)
312
+ upstream.pipe(client)
313
+ client.pipe(upstream)
314
+ }
315
+ const onData = (chunk) => {
316
+ buffered = Buffer.concat([buffered, chunk])
317
+ check()
318
+ }
319
+ client.on('data', onData)
320
+ if (buffered.length) check()
321
+ })
322
+ // A timeout only emits 'timeout': end it as an error so the client hears of it.
323
+ upstream.on('timeout', () => upstream.destroy(Object.assign(new Error('upstream timed out'), { code: 'ETIMEDOUT' })))
324
+ upstream.on('error', (error) => {
325
+ if (client.destroyed) return
326
+ // Once the tunnel is up the client speaks TLS: no HTTP answer fits, just close.
327
+ if (established) client.destroy()
328
+ else client.end(`HTTP/1.1 502 Bad Gateway\r\n\r\n${error.code || 'upstream error'}\n`)
329
+ })
330
+ // However the upstream side closes, the client side is closed too.
331
+ upstream.on('close', () => {
332
+ if (!client.destroyed && !client.writableEnded) client.end()
333
+ })
334
+ client.on('close', () => upstream.destroy())
335
+ })
336
+ server.on('clientError', (error, socket) => socket.destroy())
337
+ return server
338
+ }
339
+
340
+ // Started as a program (in the proxy container).
341
+ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
342
+ const allow = parseAllowList(process.env.SHAPEWALL_EGRESS_ALLOW)
343
+ const port = Number(process.env.SHAPEWALL_EGRESS_PORT || PROXY_PORT)
344
+ const server = createEgressProxy({ allow })
345
+ server.listen(port, '0.0.0.0', () => {
346
+ process.stdout.write(`${JSON.stringify({ ready: true, port, allow: allow.map(formatAllowEntry) })}\n`)
347
+ })
348
+ const stop = () => server.close(() => process.exit(0))
349
+ process.on('SIGTERM', stop)
350
+ process.on('SIGINT', stop)
351
+ }
@@ -0,0 +1,90 @@
1
+ // The trigger gate: which comments the starter agent may take.
2
+ //
3
+ // Anyone who can comment can write text the agent will act on, so a comment
4
+ // is dispatched only when a trusted member stands behind it:
5
+ //
6
+ // - a share link guest's comment (authorGuest) is never dispatched, whoever
7
+ // tags it later;
8
+ // - a comment written by an agent (a hosted token, or the local "agent" /
9
+ // "shapewall" names) is not either, so agents do not feed each other;
10
+ // - a trusted member's own comment is dispatched;
11
+ // - anyone else's comment waits until a trusted member replies with @agent.
12
+ //
13
+ // Who is a member: on a hosted board, the account handle the server attests
14
+ // (authorHandle, reply.handle); display names are never enough there. On a
15
+ // local board, the author name as typed: a local board has no accounts, so
16
+ // this is only as strong as who can reach the board (docs/starter-agent.md).
17
+
18
+ import { extractMentions } from '../../mentions.js'
19
+ import { trustName } from './settings.js'
20
+
21
+ export const AGENT_HANDLE = 'agent'
22
+ const AGENT_NAMES = new Set(['agent', 'shapewall', 'shapewall agent', 'starter agent'])
23
+
24
+ // The identity behind a comment or reply: { name, attested }.
25
+ function identity(item, { hosted }) {
26
+ if (hosted) return { name: item.authorHandle || item.handle ? trustName(item.authorHandle || item.handle) : null, attested: true }
27
+ return { name: trustName(item.author), attested: false }
28
+ }
29
+
30
+ const byAgent = (item, { hosted }) => Boolean(item.authorAgent || item.agent) || (!hosted && AGENT_NAMES.has(trustName(item.author)))
31
+
32
+ // gateComment(comment, { trusted: Set, hosted }) ->
33
+ // { dispatch: true, by, via: 'author' | 'tag', attested }
34
+ // { dispatch: false, reason, final } final: never, whatever happens later
35
+ export function gateComment(comment, { trusted, hosted = false, handle = AGENT_HANDLE }) {
36
+ if (!comment || comment.status !== 'open') return { dispatch: false, reason: 'the comment is not open', final: false }
37
+ if (comment.authorGuest)
38
+ return { dispatch: false, reason: 'a share link guest wrote it (guest comments are never dispatched)', final: true }
39
+ if (byAgent(comment, { hosted })) return { dispatch: false, reason: 'an agent wrote it', final: true }
40
+ if (hosted)
41
+ return comment.dispatchable === true
42
+ ? { dispatch: true, by: 'server policy', via: 'author', attested: true }
43
+ : { dispatch: false, reason: 'the server has not dispatched this comment', final: false }
44
+ if (!trusted?.size)
45
+ return { dispatch: false, reason: 'no member may dispatch work on this board (starterAgent.trusted is empty)', final: false }
46
+ const author = identity(comment, { hosted })
47
+ if (author.name && trusted.has(author.name)) return { dispatch: true, by: author.name, via: 'author', attested: author.attested }
48
+ // A tag vouches for the text as it was then: after an edit of the comment,
49
+ // only a newer tag counts (a tag without a time does not count then).
50
+ const edited = typeof comment.editedAt === 'string' ? Date.parse(comment.editedAt) : null
51
+ let stale = false
52
+ for (const reply of comment.replies || []) {
53
+ if (reply.guest || byAgent(reply, { hosted })) continue
54
+ const who = identity(reply, { hosted })
55
+ if (!who.name || !trusted.has(who.name)) continue
56
+ if (!extractMentions(reply.body).includes(handle)) continue
57
+ const at = typeof reply.createdAt === 'string' ? Date.parse(reply.createdAt) : NaN
58
+ if (edited !== null && !(at > edited)) {
59
+ stale = true
60
+ continue
61
+ }
62
+ return { dispatch: true, by: who.name, via: 'tag', attested: who.attested }
63
+ }
64
+ return {
65
+ dispatch: false,
66
+ reason: stale
67
+ ? `the comment was edited after the @${handle} tag; a trusted member must tag it again`
68
+ : `waiting for a trusted member to reply with @${handle}`,
69
+ final: false,
70
+ }
71
+ }
72
+
73
+ // What of a comment the model may see: the comment and the replies of
74
+ // people who are not guests. Guest replies are dropped, not quoted.
75
+ export function commentForTask(item) {
76
+ return {
77
+ id: item.id,
78
+ body: item.body,
79
+ author: item.author,
80
+ status: item.status,
81
+ page: item.page || null,
82
+ variant: item.variant || null,
83
+ viewport: item.viewport || null,
84
+ element: item.element || null,
85
+ position: item.position || null,
86
+ replies: (item.replies || [])
87
+ .filter((reply) => !reply.guest)
88
+ .map((reply) => ({ author: reply.author, body: reply.body, createdAt: reply.createdAt })),
89
+ }
90
+ }