@pi-chamber/web 1.0.4-rc.4 → 1.0.5-rc.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 (204) hide show
  1. package/README.md +1 -1
  2. package/bin/cli.js +21 -2
  3. package/bin/cli.test.js +164 -4
  4. package/bin/lib/DOCUMENTATION.md +3 -3
  5. package/bin/lib/cli-args.js +96 -13
  6. package/bin/lib/commands-connect-url-tailscale.test.js +136 -0
  7. package/bin/lib/commands-connect-url.js +146 -39
  8. package/bin/lib/commands-connect-url.test.js +126 -0
  9. package/bin/lib/commands-serve.js +45 -2
  10. package/bin/lib/commands-status.js +28 -5
  11. package/bin/lib/commands-status.test.js +107 -0
  12. package/bin/lib/commands-tunnel.js +36 -10
  13. package/dist/assets/{DiagramView--BGR3PRZ.js → DiagramView-D-OSWTbO.js} +1 -1
  14. package/dist/assets/DiffView-BKT-MIH4.js +18 -0
  15. package/dist/assets/{FileSaveConflictDialog-CcrWHRvd.js → FileSaveConflictDialog-DBkVFssC.js} +2 -2
  16. package/dist/assets/FilesView-B7GIuRlh.js +6 -0
  17. package/dist/assets/{GitHubDetailScaffold-BZhP67Va.js → GitHubDetailScaffold-C9rCZMUT.js} +2 -2
  18. package/dist/assets/{GitHubLinkPicker-CJZmDljp.js → GitHubLinkPicker-Bm09hvhJ.js} +1 -1
  19. package/dist/assets/{GitHubListPrimitives-DhF42guB.js → GitHubListPrimitives-DlhAlxI6.js} +1 -1
  20. package/dist/assets/{GitView-JK-QCK9R.js → GitView-BgqdMb0m.js} +4 -4
  21. package/dist/assets/{IssuesSurface-CAqQzrsv.js → IssuesSurface-BZXAvt49.js} +3 -3
  22. package/dist/assets/{JsonTreeView-CKTqB1CD.js → JsonTreeView-BKgCQjh_.js} +1 -1
  23. package/dist/assets/{MarkdownRendererImpl-B5kJy9Nt.js → MarkdownRendererImpl-BdcyMPw-.js} +1 -1
  24. package/dist/assets/{PatchDiff-BQnRFN30.js → PatchDiff-2MmWXcGe.js} +1 -1
  25. package/dist/assets/PierreDiffViewer-D1F2WvD0.js +135 -0
  26. package/dist/assets/PullRequestsSurface-CN2z3DFv.js +2 -0
  27. package/dist/assets/SessionSwitcherContent-CCljxAZb.js +1 -0
  28. package/dist/assets/SessionSwitcherDropdown-DtNt3qw4.js +2 -0
  29. package/dist/assets/SessionUnreadDot-B9bHMy5q.js +1 -0
  30. package/dist/assets/SettingsView-DaZVCInW.js +6 -0
  31. package/dist/assets/{SettingsWindow-CAxKgYOu.js → SettingsWindow-C-ydfopH.js} +1 -1
  32. package/dist/assets/StickyHorizontalScrollbar-BMITjK4e.js +8 -0
  33. package/dist/assets/{ToolOutputDialog-lz5exVQ4.js → ToolOutputDialog-DJUAx_Oj.js} +4 -4
  34. package/dist/assets/{ToolPartDiffPreview-nIUiNLpP.js → ToolPartDiffPreview-DFyuJM4c.js} +1 -1
  35. package/dist/assets/{VirtualizedFileDiff-IWqCJNXu.js → VirtualizedFileDiff-BS-af6rn.js} +4 -4
  36. package/dist/assets/{Virtualizer-Cp_cJWbI.js → Virtualizer-DP6HbEeC.js} +1 -1
  37. package/dist/assets/{collapsible-C7oyikVm.js → collapsible-BOcd0lzY.js} +1 -1
  38. package/dist/assets/{computeVirtualFileMetrics-CyhUKEfv.js → computeVirtualFileMetrics-BI6wORhM.js} +1 -1
  39. package/dist/assets/{contextFileOpenGuard-DkjmJ-NU.js → contextFileOpenGuard-DUMSGR4M.js} +1 -1
  40. package/dist/assets/{gitStatusPredicates-DBmUY3kA.js → gitStatusPredicates-FdKYDZe3.js} +1 -1
  41. package/dist/assets/{githubLink-BdbPMMAK.js → githubLink-B3-BaGpb.js} +5 -5
  42. package/dist/assets/index-DWSrsQWl.js +11 -0
  43. package/dist/assets/{index-CKgYIOis.js → index-Df-vmvzu.js} +1 -1
  44. package/dist/assets/index-DsQIBAWK.css +1 -0
  45. package/dist/assets/main-61_cd7S7.js +2 -0
  46. package/dist/assets/main-q43jqZ2I.js +136 -0
  47. package/dist/assets/{markdownCore-D7V46WY9.js → markdownCore-CqHYlXi_.js} +2 -2
  48. package/dist/assets/{miniChat-PanPmbEK.js → miniChat-vOuWN5pV.js} +2 -2
  49. package/dist/assets/mobile-mrXWV5ky.js +2 -0
  50. package/dist/assets/{nativeFileSave-BzhtrDoD.js → nativeFileSave-CFuugNKV.js} +1 -1
  51. package/dist/assets/pi-session-focus-preference-BEufpwC6.js +9 -0
  52. package/dist/assets/{renderDiffWithHighlighter-ByZtK9za.js → renderDiffWithHighlighter-BD9CAhZU.js} +1 -1
  53. package/dist/assets/renderElectronMiniChatApp-QQFXkY5Y.js +2 -0
  54. package/dist/assets/{renderFileWithHighlighter-CnN0Tv_8.js → renderFileWithHighlighter-KiEWMtzI.js} +1 -1
  55. package/dist/assets/renderMobileApp-DIZYvrhi.js +11 -0
  56. package/dist/assets/runtimeEndpointReset-BA2uP2rj.js +62 -0
  57. package/dist/assets/{runtimeSurface-DBiUWYK2.js → runtimeSurface-Der4qUnI.js} +1 -1
  58. package/dist/assets/useAppFontEffects-Bfw_d5eB.js +212 -0
  59. package/dist/assets/{useFilesViewSearch-BWABG6pS.js → useFilesViewSearch-Budwejnx.js} +3 -3
  60. package/dist/assets/useGitHubRemoteSearch-gUdylYy3.js +1 -0
  61. package/dist/assets/{useSwitcherItems-BSTSev5C.js → useSwitcherItems-yHSMduoo.js} +1 -1
  62. package/dist/assets/{vendor-aparajita-capacitor-secure-storage-BYohCVY0.js → vendor-aparajita-capacitor-secure-storage-BDrMx_CE.js} +1 -1
  63. package/dist/assets/{vendor-base-ui-BscvGUFt.js → vendor-base-ui-CKRUCG-f.js} +1 -1
  64. package/dist/assets/{vendor-boot-Dgb9NVFe.js → vendor-boot-EC6IyLt1.js} +13 -13
  65. package/dist/assets/{vendor-capacitor-app-BjdQVib9.js → vendor-capacitor-app-BaupizkW.js} +1 -1
  66. package/dist/assets/{vendor-capacitor-keyboard-eTtI5go3.js → vendor-capacitor-keyboard-9BVxykO7.js} +1 -1
  67. package/dist/assets/{vendor-capacitor-status-bar-9rNIGxlO.js → vendor-capacitor-status-bar-BsrUwiaA.js} +1 -1
  68. package/dist/assets/{vendor-codemirror-autocomplete-DxS3jwvE.js → vendor-codemirror-autocomplete-CGpAsPWp.js} +1 -1
  69. package/dist/assets/{vendor-codemirror-lang-angular-DdjXl9e2.js → vendor-codemirror-lang-angular-CDJoHJSY.js} +1 -1
  70. package/dist/assets/{vendor-codemirror-lang-cpp--aMr7NVt.js → vendor-codemirror-lang-cpp-BmHofQls.js} +1 -1
  71. package/dist/assets/{vendor-codemirror-lang-css-CZ_qxZY9.js → vendor-codemirror-lang-css-RM2HqXZ0.js} +1 -1
  72. package/dist/assets/{vendor-codemirror-lang-go-Ca-y2Alu.js → vendor-codemirror-lang-go-Crwca_X7.js} +1 -1
  73. package/dist/assets/{vendor-codemirror-lang-html-COZ0L5wT.js → vendor-codemirror-lang-html-CHSHUpwq.js} +1 -1
  74. package/dist/assets/{vendor-codemirror-lang-java-D3Rf3QNJ.js → vendor-codemirror-lang-java-lhQXgWu0.js} +1 -1
  75. package/dist/assets/{vendor-codemirror-lang-javascript-DwJ-IvCs.js → vendor-codemirror-lang-javascript-Dw4kFO4e.js} +1 -1
  76. package/dist/assets/{vendor-codemirror-lang-jinja-D_5lod6k.js → vendor-codemirror-lang-jinja-_pAC3UTN.js} +1 -1
  77. package/dist/assets/{vendor-codemirror-lang-json-BG8C7OpC.js → vendor-codemirror-lang-json-B-b1vAv-.js} +1 -1
  78. package/dist/assets/{vendor-codemirror-lang-less-CVEkoaTw.js → vendor-codemirror-lang-less-xIgOi1ze.js} +1 -1
  79. package/dist/assets/{vendor-codemirror-lang-liquid-U9vj0m8w.js → vendor-codemirror-lang-liquid-CP49m5dB.js} +1 -1
  80. package/dist/assets/{vendor-codemirror-lang-markdown-DqlYH9gY.js → vendor-codemirror-lang-markdown-BTht2ATe.js} +1 -1
  81. package/dist/assets/{vendor-codemirror-lang-php-BFEiEVA1.js → vendor-codemirror-lang-php-BguZDhaO.js} +1 -1
  82. package/dist/assets/{vendor-codemirror-lang-python-Cz1dQXQd.js → vendor-codemirror-lang-python-CH6_em9L.js} +1 -1
  83. package/dist/assets/{vendor-codemirror-lang-rust-C_CoD9mj.js → vendor-codemirror-lang-rust-EG_DtGyi.js} +1 -1
  84. package/dist/assets/{vendor-codemirror-lang-sass-BuR0aKh5.js → vendor-codemirror-lang-sass-BknY5Qpo.js} +1 -1
  85. package/dist/assets/{vendor-codemirror-lang-sql-DggNUjdM.js → vendor-codemirror-lang-sql-B0f-qCZo.js} +1 -1
  86. package/dist/assets/{vendor-codemirror-lang-vue-DFZHi2J3.js → vendor-codemirror-lang-vue-CyGn9snv.js} +1 -1
  87. package/dist/assets/{vendor-codemirror-lang-wast-zuTN3SHT.js → vendor-codemirror-lang-wast-CsFfSyyB.js} +1 -1
  88. package/dist/assets/{vendor-codemirror-lang-xml-CrcvhI-k.js → vendor-codemirror-lang-xml-Cdan_Jp1.js} +1 -1
  89. package/dist/assets/{vendor-codemirror-lang-yaml-DcVWsakb.js → vendor-codemirror-lang-yaml-COI5hck8.js} +1 -1
  90. package/dist/assets/{vendor-codemirror-language-data-CCLITgCF.js → vendor-codemirror-language-data-CqU7kHmg.js} +2 -2
  91. package/dist/assets/{vendor-codemirror-search-H7NOEdbX.js → vendor-codemirror-search-DUfSCF9S.js} +1 -1
  92. package/dist/assets/{vendor-lezer-cpp-C8aD2KAr.js → vendor-lezer-cpp-DMZOJzBa.js} +1 -1
  93. package/dist/assets/{vendor-lezer-css-2lbTJF-Y.js → vendor-lezer-css-DUkkbMp7.js} +1 -1
  94. package/dist/assets/{vendor-lezer-go-Bw6LFTrZ.js → vendor-lezer-go-CHIhCNY6.js} +1 -1
  95. package/dist/assets/{vendor-lezer-html-D7ym2z7S.js → vendor-lezer-html-B3h0MOrG.js} +1 -1
  96. package/dist/assets/{vendor-lezer-java-CZhK7w21.js → vendor-lezer-java-tMazV_6X.js} +1 -1
  97. package/dist/assets/{vendor-lezer-javascript-rpKeTHZp.js → vendor-lezer-javascript-ctwLWf4v.js} +1 -1
  98. package/dist/assets/{vendor-lezer-json-C7jwsd2G.js → vendor-lezer-json-BP_UAzLL.js} +1 -1
  99. package/dist/assets/{vendor-lezer-lr-DR-ylqNN.js → vendor-lezer-lr-B8TQctNw.js} +1 -1
  100. package/dist/assets/{vendor-lezer-markdown-Bir0m5nB.js → vendor-lezer-markdown-aGLZf_3h.js} +1 -1
  101. package/dist/assets/{vendor-lezer-php-y0hIEfo1.js → vendor-lezer-php-D5zCNzlt.js} +1 -1
  102. package/dist/assets/{vendor-lezer-python-D64A9lNV.js → vendor-lezer-python-EJ4Im4y2.js} +1 -1
  103. package/dist/assets/{vendor-lezer-rust-E3ZA9T2L.js → vendor-lezer-rust-DO5c7OtA.js} +1 -1
  104. package/dist/assets/{vendor-lezer-sass-C5UFI9SP.js → vendor-lezer-sass-CMi6zfXI.js} +1 -1
  105. package/dist/assets/{vendor-lezer-xml-DOy7FzCR.js → vendor-lezer-xml-0MHMeZDp.js} +1 -1
  106. package/dist/assets/{vendor-lezer-yaml-kEjaSCvZ.js → vendor-lezer-yaml-BE2EFjpA.js} +1 -1
  107. package/dist/assets/{vendor-replit-codemirror-vim-BLfh0LPy.js → vendor-replit-codemirror-vim-AnOuN8yJ.js} +1 -1
  108. package/dist/assets/{web-components-CdMfsnXE.js → web-components-CeHLxvED.js} +3 -3
  109. package/dist/index.html +4 -4
  110. package/dist/mini-chat.html +3 -3
  111. package/dist/mobile.html +3 -3
  112. package/dist/sw.js +1 -1
  113. package/package.json +1 -2
  114. package/server/index.js +69 -30
  115. package/server/lib/client-auth/DOCUMENTATION.md +15 -1
  116. package/server/lib/client-auth/pairing.js +2 -12
  117. package/server/lib/client-auth/remote-clients.js +2 -12
  118. package/server/lib/cloudflare-tunnel.js +0 -132
  119. package/server/lib/fs/DOCUMENTATION.md +8 -0
  120. package/server/lib/fs/atomic-write.js +111 -0
  121. package/server/lib/fs/atomic-write.test.js +133 -0
  122. package/server/lib/notifications/DOCUMENTATION.md +43 -32
  123. package/server/lib/notifications/pi-notification-watcher.js +8 -7
  124. package/server/lib/notifications/pi-notification-watcher.test.js +88 -2
  125. package/server/lib/pi/routes-extension-events.test.js +231 -0
  126. package/server/lib/pi/routes.js +137 -4
  127. package/server/lib/pi/routes.test.js +248 -2
  128. package/server/lib/pi/session-daemon/DOCUMENTATION.md +17 -4
  129. package/server/lib/pi/session-daemon/daemon-process.js +2 -0
  130. package/server/lib/pi/session-daemon/engines/index.js +6 -0
  131. package/server/lib/pi/session-daemon/extension-bridge-draft.test.js +1 -1
  132. package/server/lib/pi/session-daemon/extension-bridge.js +24 -0
  133. package/server/lib/pi/session-daemon/extension-message-render.js +74 -0
  134. package/server/lib/pi/session-daemon/extension-message-render.test.js +164 -0
  135. package/server/lib/pi/session-daemon/extension-tool-render.js +13 -6
  136. package/server/lib/pi/session-daemon/pending-input.js +188 -0
  137. package/server/lib/pi/session-daemon/pending-input.test.js +202 -0
  138. package/server/lib/pi/session-daemon/session-daemon-engines.test.js +828 -0
  139. package/server/lib/pi/session-daemon/session-daemon-extensions.test.js +296 -6
  140. package/server/lib/pi/session-daemon/session-daemon-turn.e2e.test.js +9 -0
  141. package/server/lib/pi/session-daemon/session-daemon.js +219 -19
  142. package/server/lib/pi/session-daemon/session-daemon.test.js +30 -2
  143. package/server/lib/pi/session-daemon/session-engine-router.js +390 -0
  144. package/server/lib/pi/session-daemon/session-engine-router.test.js +515 -0
  145. package/server/lib/pi/session-daemon/session-engines.js +467 -0
  146. package/server/lib/pi/session-daemon/session-engines.test.js +383 -0
  147. package/server/lib/pi/snippets-store.js +8 -17
  148. package/server/lib/pi/ui-settings-store.js +6 -10
  149. package/server/lib/pi/ui-settings-store.test.js +37 -1
  150. package/server/lib/relay/DOCUMENTATION.md +6 -4
  151. package/server/lib/relay/identity-store.js +116 -0
  152. package/server/lib/relay/identity-store.test.js +169 -0
  153. package/server/lib/relay/identity.js +6 -4
  154. package/server/lib/relay/server-id.js +63 -0
  155. package/server/lib/relay/server-id.test.js +132 -0
  156. package/server/lib/relay/signing-key.js +14 -11
  157. package/server/lib/security/bind-host.js +6 -2
  158. package/server/lib/security/bind-host.test.js +17 -0
  159. package/server/lib/server/core-routes.js +27 -1
  160. package/server/lib/server/lan-addresses.js +18 -6
  161. package/server/lib/server/lan-addresses.test.js +28 -0
  162. package/server/lib/server/tunnel-auth.js +47 -7
  163. package/server/lib/server/tunnel-auth.rate-limit.test.js +164 -0
  164. package/server/lib/server/tunnel-service.DOCUMENTATION.md +3 -4
  165. package/server/lib/server/tunnel-service.js +23 -20
  166. package/server/lib/server/tunnel-service.test.js +19 -2
  167. package/server/lib/stt/config-store.js +5 -15
  168. package/server/lib/tailscale/DOCUMENTATION.md +264 -0
  169. package/server/lib/tailscale/routes.js +45 -0
  170. package/server/lib/tailscale/service.js +959 -0
  171. package/server/lib/tailscale/tailscale.js +302 -0
  172. package/server/lib/tailscale/tailscale.test.js +1861 -0
  173. package/server/lib/tunnels/DOCUMENTATION.md +3 -4
  174. package/server/lib/tunnels/providers/cloudflare.js +1 -22
  175. package/server/lib/tunnels/types.js +0 -2
  176. package/server/lib/ui-auth/DOCUMENTATION.md +31 -0
  177. package/server/lib/ui-auth/ui-auth.js +80 -6
  178. package/server/lib/ui-auth/ui-auth.test.js +136 -0
  179. package/server/lib/ui-auth/ui-passkeys.js +2 -13
  180. package/server/lib/update-job-store.js +4 -6
  181. package/dist/assets/DiffView-hz90_htv.js +0 -18
  182. package/dist/assets/FilesView-DaqkPMqx.js +0 -6
  183. package/dist/assets/PierreDiffViewer-BeGpdI0x.js +0 -134
  184. package/dist/assets/PullRequestsSurface-D9beq2x9.js +0 -2
  185. package/dist/assets/SessionSwitcherContent-DElQ_cjm.js +0 -1
  186. package/dist/assets/SessionSwitcherDropdown-JaIDcDIj.js +0 -2
  187. package/dist/assets/SessionUnreadDot-Czfvjbdi.js +0 -1
  188. package/dist/assets/SettingsView-C_GC1Mx3.js +0 -6
  189. package/dist/assets/index-BnZVqcki.js +0 -11
  190. package/dist/assets/index-BnieExes.css +0 -1
  191. package/dist/assets/main-6YKi4QM2.js +0 -2
  192. package/dist/assets/main-CWdWdhdL.js +0 -136
  193. package/dist/assets/mobile-0LY-2fxw.js +0 -2
  194. package/dist/assets/pi-session-focus-preference-BC-ze1oC.js +0 -10
  195. package/dist/assets/renderElectronMiniChatApp-DETQLjFi.js +0 -2
  196. package/dist/assets/renderMobileApp-DS0FDQLg.js +0 -11
  197. package/dist/assets/runtimeEndpointReset-BqqXMwE9.js +0 -62
  198. package/dist/assets/useAppFontEffects-BisjofNZ.js +0 -212
  199. package/dist/assets/useGitHubRemoteSearch-Bsf2YeQP.js +0 -1
  200. package/dist/assets/vendor-capacitor-push-notifications-CBKq2Arn.js +0 -1
  201. package/server/lib/notifications/delivery-runtime.js +0 -314
  202. package/server/lib/notifications/delivery-runtime.test.js +0 -85
  203. package/server/lib/notifications/routes.js +0 -74
  204. package/server/lib/relay/service.js +0 -9
@@ -0,0 +1,264 @@
1
+ # Tailscale Module Documentation
2
+
3
+ ## Purpose
4
+
5
+ Tailscale remote access for PiChamber: `tailscale serve` publishes the local
6
+ server at `https://<machine>.<tailnet>.ts.net[:port]`, reachable only by
7
+ devices in the user's tailnet (private). `tailscale funnel` is identical but
8
+ reachable from the public internet (public). Funnel only allows the HTTPS
9
+ ports 443, 8443 and 10000. The URL is the machine's MagicDNS name and does
10
+ not change when the mapping is removed and re-added.
11
+
12
+ Off by default. Enabled only via the settings API (`PUT
13
+ /api/pichamber/tailscale/config`) or CLI flags (`pichamber pair --tailscale`,
14
+ `pichamber serve --tailscale`). Never auto-enabled when Tailscale is
15
+ detected.
16
+
17
+ Ephemeral Cloudflare quick tunnels were removed; this module is unaffected.
18
+
19
+ ## Entrypoints and structure
20
+
21
+ - `tailscale.js`: pure helpers — config validation/normalization, the auth
22
+ gate, executable resolution, `status --json` parsing (trailing-dot DNSName,
23
+ `BackendState`, `CertDomains`), `serve status --json` conflict detection,
24
+ approval-URL extraction, permission-denied detection. No I/O.
25
+ - `service.js`: `createTailscaleService` — persisted config, lifecycle
26
+ (apply on start, remove on stop, reconcile on change), crash-safe mapping
27
+ record, probe-before-advertise, approval wait, and the status model. All
28
+ process execution goes through the injected `runner` (argument arrays, no
29
+ shell, bounded timeouts); tests inject a fake.
30
+ - `routes.js`: `registerTailscaleRoutes` — thin authenticated HTTP API
31
+ following the `/api/pichamber/tunnel/*` conventions.
32
+ - `tailscale.test.js`: unit tests with an injected fake runner.
33
+
34
+ ## Lifecycle ("while PiChamber runs")
35
+
36
+ 1. `startWebUiServer` loads the persisted config, then reconciles the mapping
37
+ **after** HTTP listen to `http://127.0.0.1:<boundPort>` — always loopback,
38
+ even when the server also binds LAN. Reconcile runs in the background so
39
+ an approval wait never blocks server-ready (status shows
40
+ starting/needs-approval meanwhile); rejections are caught and logged.
41
+ Apply failure logs a warning and never stops startup; the status model
42
+ carries the error and `POST /api/pichamber/tailscale/retry` (or any
43
+ config change) reconciles again.
44
+ 2. Runtime config changes and retry respond after at most a short grace
45
+ (`CONFIG_RESPONSE_GRACE_MS`, 3s) with the current (possibly
46
+ transitional) status while reconcile continues in the background:
47
+ abort the in-flight apply (generation bump kills it), remove the old
48
+ mapping, apply the new one (bounded timeouts). A superseded apply that
49
+ still created a mapping is verified and removed, so no mapping is left
50
+ unowned. The enabled path reports `starting` synchronously before its
51
+ first await (approval output flips it to `needs-approval`), so the
52
+ early response is already transitional. Background failures are caught
53
+ and logged, never unhandled. Clients (the Remote Access UI hook,
54
+ `pichamber pair --tailscale`) poll `GET /status` until a terminal
55
+ state. Reconciles are serialized: each reconcile starts only after the
56
+ previous one settles, in call order. A reconcile superseded while queued
57
+ is skipped, and a superseded in-flight reconcile never removes a mapping
58
+ after the newer one starts — the generation is re-checked after the
59
+ serve-status query inside verified removal, and again before every
60
+ host-info/state write. A throwing reconcile never wedges the chain: the
61
+ next queued reconcile still runs while the caller still sees the
62
+ rejection.
63
+ 3. Graceful shutdown (`controller.stop`, covering CLI serve stop, SIGINT,
64
+ SIGTERM, and the Electron in-process server stop path) removes the mapping
65
+ PiChamber created (`serve/funnel --https=<p> off`, as appropriate) — but
66
+ only after verifying ownership against live serve status. On a status
67
+ query failure nothing is removed and the record is kept, so the next
68
+ start's stale cleanup retries with verification. Electron awaits this
69
+ stop with a bounded quit timeout (8s) before exiting, so shutdown uses
70
+ tighter bounds than reconcile — 3s status query + 4s removal — to finish
71
+ inside it; keep both sides in sync. A failed removal also
72
+ keeps the record and logs a warning (the next start's stale cleanup
73
+ retries with verification), and never blocks shutdown.
74
+
75
+ ## Crash safety and conflict rules
76
+
77
+ - The mapping PiChamber created is recorded in `tailscale-mapping.json`
78
+ (`{ httpsPort, mode, localPort }`) in the PiChamber data dir. On the next
79
+ start, a stale record for a different port/mode is removed (when it is
80
+ ours) before the new mapping is applied; a disabled config removes a stale
81
+ own mapping and reports `off`; a `blocked` (auth-gate) config removes a
82
+ stale own mapping first and then reports `blocked` (tailscaled persists
83
+ serve config, so the mapping would otherwise stay reachable without
84
+ auth). A failed status query keeps the record and reports `error` with
85
+ code `status_query_failed` (retry available) instead of acting blind. A
86
+ failed removal of a verified own mapping also keeps the record and
87
+ reports `error` with code `remove_failed` (the mapping may still be
88
+ live), so a later reconcile or retry can remove it first — reconcile
89
+ never applies a new mapping over one it failed to remove.
90
+ - NEVER remove or overwrite a mapping PiChamber did not create. Before
91
+ applying, `tailscale serve status --json` (`funnel status --json` for
92
+ public) is inspected — `Web` entries keyed by `<host>:<port>` with handler
93
+ targets. A mapping is OURS only when every handler target points at our
94
+ own `http://127.0.0.1:<boundPort>`. A mapping on the configured port is
95
+ also OURS when the mapping record (same port+mode) names the local port
96
+ the live targets point at — a crash-restart on a new bound port leaves the
97
+ old record behind while the port/mode are unchanged. Such a mapping is
98
+ repointed to the new bound port instead of reporting conflict. Anything
99
+ else on the target port reports state `conflict` with code `conflict` and a message suggesting the
100
+ other ports (8443/10000). Disabled and blocked reconciles still query host
101
+ prerequisites (`tailscale status --json` only — no serve/funnel commands)
102
+ after the mapping-removal check, so `installed`/`running`/`loggedIn` stay
103
+ accurate while `state` is `off`/`blocked`; the retry route re-checks them
104
+ the same way.
105
+
106
+ ## Security gate (core-enforced)
107
+
108
+ Tailscale proxies requests to loopback, which bypasses the
109
+ "refuse a network-exposed bind without a UI password" rule. Enabling
110
+ Tailscale (either mode) therefore requires UI auth (a UI password):
111
+
112
+ - Enforced in `setConfig` (rejects with code `auth_required`), in
113
+ `persistTailscaleConfigForStartup` (same gate, so the CLI cannot persist
114
+ an enabled config without satisfying it either), in server startup
115
+ reconcile (config enabled but gate unsatisfied → existing own mapping
116
+ removed with ownership verification, then state `blocked`, code
117
+ `auth_required`, mapping not applied), and in `pichamber serve
118
+ --tailscale` (fast deterministic CLI failure).
119
+ - `private` mode honors the same `PICHAMBER_ALLOW_UNAUTHENTICATED_LAN`
120
+ escape hatch as a LAN bind (`true`/`1`, case-insensitive). `public` mode
121
+ has NO escape hatch.
122
+
123
+ With no UI password, the Tailscale status/config routes are reachable
124
+ unauthenticated on loopback/LAN — the same as every other route in that
125
+ mode (no per-route auth exists without a password); enabling/disabling is
126
+ fail-safe because the auth gate above rejects enabling.
127
+
128
+ Funnel traffic is classified as `local` request scope by tunnel-auth
129
+ `classifyRequestScope` (it arrives from the loopback socket with a
130
+ forwarded Host). `local` scope is transport classification only and must
131
+ never relax authentication.
132
+
133
+ ## Trust-proxy / rate-limit / cookie / passkey findings
134
+
135
+ The server runs with `app.set('trust proxy', true)` (intentional: reverse
136
+ proxies and tunnels terminate TLS and set `X-Forwarded-*`).
137
+
138
+ - **Rate limiting (`getClientIp`)**: login limiters (UI password/passkey in
139
+ `ui-auth.js`, `/connect` in `tunnel-auth.js`) use a DUAL bucket. The
140
+ per-client bucket is still keyed by `X-Forwarded-For` first (UX behind
141
+ legit proxies: each tailnet device keeps its own budget), but EVERY
142
+ attempt is ALSO counted against a socket-address bucket keyed by
143
+ `req.socket.remoteAddress` (never `req.ip`, which Express rewrites from
144
+ XFF under `trust proxy`). The socket bucket allows 5x the per-client
145
+ limit in the same window — headroom for one forwarder multiplexing many
146
+ clients — and an attempt is refused if EITHER bucket is exhausted.
147
+ A successful login clears only the requester's per-client bucket, never
148
+ the shared socket bucket (which decays via window/lockout expiry only);
149
+ otherwise any legitimate login would wipe an attacker's accumulated
150
+ guesses and defeat the socket bound. Accepted trade-off: because
151
+ Serve/Funnel share the loopback socket, an attacker exhausting the
152
+ socket bucket over Funnel locks out every Tailscale/loopback login for
153
+ the lockout window (15 min) — bounded guessing is preferred over
154
+ unlimited guessing; the per-client bucket keeps separate tailnet
155
+ devices' normal budgets.
156
+ Threat direction: Tailscale Serve/Funnel forwards from 127.0.0.1 and
157
+ passes attacker-supplied XFF through, so XFF alone is attacker-controlled
158
+ and must never be the only key. Rotating XFF from one socket now hits the
159
+ socket lockout (50 login / 100 connect attempts per 5 minutes), and
160
+ distinct sockets stay independent.
161
+ - **Pairing redeem limiter**: keyed by the socket address (deliberately NOT
162
+ `req.ip`), so all Tailscale traffic shares the `127.0.0.1` bucket: 10
163
+ attempts per 5 minutes per `pairingId`. Pairing-ID scoping keeps this a
164
+ per-link budget, so one attacker's guesses never consume another link's
165
+ budget. Kept as-is; documented here.
166
+ - **Secure cookies (`isSecureRequest`)**: trusts `X-Forwarded-Proto`. Tailscale
167
+ terminates TLS and forwards `https`, so session cookies stay `Secure` over
168
+ the ts.net URL. If the header were absent, cookies would be issued without
169
+ the Secure flag but still over the encrypted tailnet transport — no
170
+ downgrade to plaintext.
171
+ - **Passkeys (`getCurrentRpId`)**: the relying-party ID derives from the
172
+ request host, so passkeys registered over the ts.net hostname are scoped to
173
+ that hostname and do not collide with LAN-host passkeys. No change needed.
174
+ - **Origin checks**: tunneled requests carry the ts.net origin via
175
+ `Host`/`X-Forwarded-Host`; no ts.net-specific origin bypass was added.
176
+
177
+ Nothing above required a code change: the gates already treat Tailscale as an
178
+ untrusted network transport, and the `auth_required` gate closes the
179
+ loopback-proxies-bypass-auth hole.
180
+
181
+ ## Status model (shared with the UI wrapper in `packages/ui/src/lib/tailscale.ts`)
182
+
183
+ `{ installed, running /* BackendState Running */, loggedIn, magicDnsName,
184
+ httpsCertsAvailable /* from CertDomains when present, else null */,
185
+ config: { enabled, mode, httpsPort }, state, url, approvalUrl, errorCode,
186
+ errorMessage, authGate: { privateAllowed, publicAllowed } }`
187
+
188
+ `authGate` is computed with `checkTailscaleAuthGate` for each mode: private
189
+ may stay allowed via `PICHAMBER_ALLOW_UNAUTHENTICATED_LAN`, public never is.
190
+ The UI disables each mode individually from these flags before the user
191
+ clicks, instead of waiting for the 403 from `setConfig`.
192
+
193
+ `installed`/`running`/`loggedIn`/`magicDnsName`/`httpsCertsAvailable` are
194
+ refreshed from `status --json` on every reconcile — including disabled
195
+ (`off`) and blocked reconciles, which never set prerequisite error codes
196
+ (`not_installed`/`not_running`/`not_logged_in`) for this — so the UI renders
197
+ Not installed / Not signed in accurately instead of a blanket Off, and
198
+ `POST /api/pichamber/tailscale/retry` re-checks them.
199
+
200
+ States: `off` | `unavailable` (not installed/running/logged in) | `blocked`
201
+ (auth gate) | `starting` (applied, URL not yet verified) |
202
+ `needs-approval` (+ `approvalUrl`) | `active` (+ `url`) | `conflict` |
203
+ `error`. `url` is set ONLY after a credential-free probe of `<url>/health`
204
+ reports this server's `serverId` — the stable relay signing-key identity
205
+ (`deriveServerId` of the `relaySigningKey` public JWK in the host-local
206
+ `<dataDir>/relay-identity.json`, the same id reported on `/health`,
207
+ `/api/version`, and relay pairing candidates, so clients verify a learned
208
+ address BEFORE sending a bearer token). `settings.json` is portable (copied
209
+ between hosts) and must never hold host identity. The probe compares against
210
+ the injected `getServerId` (a null/throwing id fails the probe, so the URL
211
+ stays `starting` and is never advertised). First-time
212
+ Funnel DNS can take minutes: `starting` keeps re-probing with backoff for up
213
+ to ~10 minutes.
214
+
215
+ Error codes: `auth_required` | `not_installed` | `not_running` |
216
+ `not_logged_in` | `permission_denied` (`sudo tailscale set --operator=$USER`)
217
+ | `needs_approval` | `conflict` | `apply_failed` | `remove_failed`
218
+ (the own mapping may still be live; the record is kept for retry) |
219
+ `status_query_failed`
220
+ (retry available; nothing was changed) | `probe_failed` | `invalid_config` |
221
+ `timeout` | `unknown`.
222
+
223
+ ## Approval flow
224
+
225
+ When HTTPS certs or Funnel are not enabled for the tailnet, serve/funnel
226
+ prints `https://login.tailscale.com/f/serve?node=...` (or `/f/funnel?...`)
227
+ and may block. The service streams stdout/stderr, extracts the first approval
228
+ URL, reports `needs-approval` while it keeps waiting (bounded 5 minutes,
229
+ cancellable on config change/shutdown), then proceeds. A timeout or exit with
230
+ the URL still pending stays `needs-approval` so the operator can approve and
231
+ hit retry.
232
+
233
+ ## Platform notes
234
+
235
+ - Executable: the well-known install location when it exists — macOS
236
+ `/Applications/Tailscale.app/Contents/MacOS/Tailscale`, Windows
237
+ `%ProgramFiles%\Tailscale\tailscale.exe` — otherwise `tailscale` /
238
+ `tailscale.exe` on PATH. The install location wins because GUI installs
239
+ often add no CLI to PATH and Electron launched from Finder has a minimal
240
+ PATH.
241
+ - Linux non-root without operator rights fails with access/permission style
242
+ errors → code `permission_denied` with the operator fix hint.
243
+ - Tailscale is not installed in CI/dev here; runtime validation against real
244
+ Tailscale is out of scope. The service is fully covered by fake-runner unit
245
+ tests instead.
246
+
247
+ ## Pairing integration
248
+
249
+ When `active`, the service exposes `{ type: 'tailscale', url, mode,
250
+ priority: 20 }` via `getPairingCandidate()`. Server routes append it to
251
+ Pairing v2 payloads and `GET /api/client-auth/connection/candidates` after
252
+ LAN candidates (priority 10) and before the relay candidate (priority 30).
253
+ `tailscale` is a distinct candidate type: old parsers drop unknown types
254
+ (verified in `connectionPayload.ts` and Electron `main.mjs`), so old clients
255
+ ignore it and use the rest; new desktop/mobile clients redeem over its `url`
256
+ like any direct URL. There is no per-transport "connected via" label surface
257
+ today, so no label change was needed.
258
+
259
+ ## Verification
260
+
261
+ ```sh
262
+ bun run test -- server/lib/tailscale/tailscale.test.js
263
+ node --check packages/web/server/lib/tailscale/service.js
264
+ ```
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Authenticated Tailscale HTTP API (thin entrypoint — domain logic lives in
3
+ * `service.js`). Route conventions follow `/api/pichamber/tunnel/*`.
4
+ *
5
+ * - GET /api/pichamber/tailscale/status → status model (shared with the UI)
6
+ * - PUT /api/pichamber/tailscale/config → `{ enabled?, mode?, httpsPort? }`
7
+ * - POST /api/pichamber/tailscale/retry → re-run reconciliation
8
+ */
9
+
10
+ export const registerTailscaleRoutes = (app, { express, tailscaleService, uiAuthController }) => {
11
+ if (!tailscaleService) return;
12
+ const requireAuth = (req, res, next) => uiAuthController.requireAuth(req, res, next);
13
+
14
+ app.get('/api/pichamber/tailscale/status', requireAuth, async (_req, res) => {
15
+ try {
16
+ res.json(tailscaleService.getStatus());
17
+ } catch (error) {
18
+ res.status(500).json({ error: error?.message || 'Failed to get Tailscale status' });
19
+ }
20
+ });
21
+
22
+ app.put('/api/pichamber/tailscale/config', express.json({ limit: '16kb' }), requireAuth, async (req, res) => {
23
+ try {
24
+ const body = req.body && typeof req.body === 'object' ? req.body : {};
25
+ const patch = {};
26
+ if (Object.hasOwn(body, 'enabled')) patch.enabled = body.enabled;
27
+ if (Object.hasOwn(body, 'mode')) patch.mode = body.mode;
28
+ if (Object.hasOwn(body, 'httpsPort')) patch.httpsPort = body.httpsPort;
29
+ const result = await tailscaleService.setConfig(patch);
30
+ res.json(result);
31
+ } catch (error) {
32
+ const code = error?.code || 'unknown';
33
+ const statusCode = code === 'invalid_config' ? 422 : code === 'auth_required' ? 403 : 500;
34
+ res.status(statusCode).json({ error: error?.message || 'Failed to update Tailscale config', code });
35
+ }
36
+ });
37
+
38
+ app.post('/api/pichamber/tailscale/retry', requireAuth, async (_req, res) => {
39
+ try {
40
+ res.json(await tailscaleService.retry());
41
+ } catch (error) {
42
+ res.status(500).json({ error: error?.message || 'Tailscale retry failed' });
43
+ }
44
+ });
45
+ };