dsh-zen-remote 1.1.16 → 2.0.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 (261) hide show
  1. package/AGENTS.md +54 -9
  2. package/README.md +249 -190
  3. package/README.zh-CN.md +247 -201
  4. package/assets/home.png +0 -0
  5. package/assets/info.png +0 -0
  6. package/assets/pairing.png +0 -0
  7. package/assets/session.png +0 -0
  8. package/assets/sheet.png +0 -0
  9. package/cordis.patch.yml +12 -11
  10. package/cordis.patch.yml.example +24 -9
  11. package/docs/interface.md +57 -2
  12. package/docs/remote-access.en.md +99 -58
  13. package/docs/remote-access.md +99 -42
  14. package/dsh-push.mjs +67 -54
  15. package/lan-gate.mjs +88 -20
  16. package/lib/activity.js +168 -0
  17. package/lib/activity.js.map +1 -0
  18. package/lib/admin-routes.js +526 -0
  19. package/lib/admin-routes.js.map +1 -0
  20. package/lib/client-pairing.js +224 -0
  21. package/lib/client-pairing.js.map +1 -0
  22. package/lib/client-routes.js +674 -0
  23. package/lib/client-routes.js.map +1 -0
  24. package/lib/client.js +11498 -5990
  25. package/lib/config.js +346 -0
  26. package/lib/config.js.map +1 -0
  27. package/lib/fetch-route-intercept.js +418 -0
  28. package/lib/fetch-route-intercept.js.map +1 -0
  29. package/lib/fingerprint.js +365 -0
  30. package/lib/fingerprint.js.map +1 -0
  31. package/lib/http.js +69 -0
  32. package/lib/http.js.map +1 -0
  33. package/lib/index.js +675 -54
  34. package/lib/index.js.map +1 -1
  35. package/lib/intercept-shape.js +81 -0
  36. package/lib/intercept-shape.js.map +1 -0
  37. package/lib/intercept.js +3181 -0
  38. package/lib/intercept.js.map +1 -0
  39. package/lib/lan-gate-server.cjs +532 -121
  40. package/lib/merge-streams.js +1172 -0
  41. package/lib/merge-streams.js.map +1 -0
  42. package/lib/relay-access.js +496 -0
  43. package/lib/relay-access.js.map +1 -0
  44. package/lib/relay-client.js +1303 -0
  45. package/lib/relay-client.js.map +1 -0
  46. package/lib/relay-filter.js +282 -0
  47. package/lib/relay-filter.js.map +1 -0
  48. package/lib/relay-server.js +1813 -0
  49. package/lib/relay-server.js.map +1 -0
  50. package/lib/restart-fields.js +34 -0
  51. package/lib/restart-fields.js.map +1 -0
  52. package/lib/restart-watcher.js +106 -0
  53. package/lib/restart-watcher.js.map +1 -0
  54. package/lib/session-reference.js +157 -0
  55. package/lib/session-reference.js.map +1 -0
  56. package/lib/share-export.js +16 -1
  57. package/lib/share-export.js.map +1 -1
  58. package/lib/share-ops.js +86 -0
  59. package/lib/share-ops.js.map +1 -0
  60. package/lib/share-store.js +294 -0
  61. package/lib/share-store.js.map +1 -0
  62. package/lib/types/activity.d.ts +99 -0
  63. package/lib/types/activity.d.ts.map +1 -0
  64. package/lib/types/admin-routes.d.ts +129 -0
  65. package/lib/types/admin-routes.d.ts.map +1 -0
  66. package/lib/types/client/MobileDrawerFooter.d.ts.map +1 -1
  67. package/lib/types/client/MobileHome.d.ts +1 -1
  68. package/lib/types/client/MobileHome.d.ts.map +1 -1
  69. package/lib/types/client/MobileHomeChips.d.ts +1 -1
  70. package/lib/types/client/MobileHomeChips.d.ts.map +1 -1
  71. package/lib/types/client/MobileSessionHeader.d.ts +13 -2
  72. package/lib/types/client/MobileSessionHeader.d.ts.map +1 -1
  73. package/lib/types/client/MobileSessionInfo.d.ts +20 -3
  74. package/lib/types/client/MobileSessionInfo.d.ts.map +1 -1
  75. package/lib/types/client/RemoteComposerBanner.d.ts +42 -0
  76. package/lib/types/client/RemoteComposerBanner.d.ts.map +1 -0
  77. package/lib/types/client/RemoteHeaderIcon.d.ts +37 -0
  78. package/lib/types/client/RemoteHeaderIcon.d.ts.map +1 -0
  79. package/lib/types/client/RemoteShareMenu.d.ts +28 -0
  80. package/lib/types/client/RemoteShareMenu.d.ts.map +1 -0
  81. package/lib/types/client/RemoteStatusIcon.d.ts +36 -0
  82. package/lib/types/client/RemoteStatusIcon.d.ts.map +1 -0
  83. package/lib/types/client/compat/desktop.d.ts +21 -0
  84. package/lib/types/client/compat/desktop.d.ts.map +1 -0
  85. package/lib/types/client/compat/types.d.ts +57 -0
  86. package/lib/types/client/compat/types.d.ts.map +1 -1
  87. package/lib/types/client/current-session-report.d.ts +37 -0
  88. package/lib/types/client/current-session-report.d.ts.map +1 -0
  89. package/lib/types/client/effects/header-status.d.ts.map +1 -1
  90. package/lib/types/client/effects/keyboard-guard.d.ts.map +1 -1
  91. package/lib/types/client/effects/model-group-side.d.ts +13 -0
  92. package/lib/types/client/effects/model-group-side.d.ts.map +1 -0
  93. package/lib/types/client/effects/permission-sheet.d.ts +39 -0
  94. package/lib/types/client/effects/permission-sheet.d.ts.map +1 -0
  95. package/lib/types/client/effects/remote-session.d.ts +25 -0
  96. package/lib/types/client/effects/remote-session.d.ts.map +1 -0
  97. package/lib/types/client/effects/turn-fold.d.ts +9 -0
  98. package/lib/types/client/effects/turn-fold.d.ts.map +1 -1
  99. package/lib/types/client/index.d.ts.map +1 -1
  100. package/lib/types/client/locales.d.ts +187 -2
  101. package/lib/types/client/locales.d.ts.map +1 -1
  102. package/lib/types/client/remote-fetch.d.ts +51 -0
  103. package/lib/types/client/remote-fetch.d.ts.map +1 -0
  104. package/lib/types/client/remote-group-expansion.d.ts +41 -0
  105. package/lib/types/client/remote-group-expansion.d.ts.map +1 -0
  106. package/lib/types/client/remote-share-css.d.ts +19 -0
  107. package/lib/types/client/remote-share-css.d.ts.map +1 -0
  108. package/lib/types/client/remote-share-register.d.ts +113 -0
  109. package/lib/types/client/remote-share-register.d.ts.map +1 -0
  110. package/lib/types/client/remote-status-css.d.ts +15 -0
  111. package/lib/types/client/remote-status-css.d.ts.map +1 -0
  112. package/lib/types/client/remote-status-register.d.ts +46 -0
  113. package/lib/types/client/remote-status-register.d.ts.map +1 -0
  114. package/lib/types/client/settings/SettingsSection.d.ts +46 -0
  115. package/lib/types/client/settings/SettingsSection.d.ts.map +1 -0
  116. package/lib/types/client/settings/register-settings.d.ts +58 -0
  117. package/lib/types/client/settings/register-settings.d.ts.map +1 -0
  118. package/lib/types/client/settings/settings-css.d.ts +10 -0
  119. package/lib/types/client/settings/settings-css.d.ts.map +1 -0
  120. package/lib/types/client/share/share-preview.d.ts.map +1 -1
  121. package/lib/types/client/styles/composer.css.d.ts +1 -1
  122. package/lib/types/client/styles/composer.css.d.ts.map +1 -1
  123. package/lib/types/client/styles/header.css.d.ts +1 -1
  124. package/lib/types/client/styles/header.css.d.ts.map +1 -1
  125. package/lib/types/client/styles/info.css.d.ts +1 -1
  126. package/lib/types/client/styles/info.css.d.ts.map +1 -1
  127. package/lib/types/client/styles/remote-session.css.d.ts +2 -0
  128. package/lib/types/client/styles/remote-session.css.d.ts.map +1 -0
  129. package/lib/types/client-data/current-session.d.ts +41 -0
  130. package/lib/types/client-data/current-session.d.ts.map +1 -0
  131. package/lib/types/client-data/model-group-side.d.ts +44 -0
  132. package/lib/types/client-data/model-group-side.d.ts.map +1 -0
  133. package/lib/types/client-data/remote-group-expansion.d.ts +76 -0
  134. package/lib/types/client-data/remote-group-expansion.d.ts.map +1 -0
  135. package/lib/types/client-data/remote-status.d.ts +148 -0
  136. package/lib/types/client-data/remote-status.d.ts.map +1 -0
  137. package/lib/types/client-data/settings-form.d.ts +774 -0
  138. package/lib/types/client-data/settings-form.d.ts.map +1 -0
  139. package/lib/types/client-data/shares.d.ts +211 -0
  140. package/lib/types/client-data/shares.d.ts.map +1 -0
  141. package/lib/types/client-pairing.d.ts +114 -0
  142. package/lib/types/client-pairing.d.ts.map +1 -0
  143. package/lib/types/client-routes.d.ts +112 -0
  144. package/lib/types/client-routes.d.ts.map +1 -0
  145. package/lib/types/config.d.ts +200 -0
  146. package/lib/types/config.d.ts.map +1 -0
  147. package/lib/types/fetch-route-intercept.d.ts +156 -0
  148. package/lib/types/fetch-route-intercept.d.ts.map +1 -0
  149. package/lib/types/fingerprint.d.ts +166 -0
  150. package/lib/types/fingerprint.d.ts.map +1 -0
  151. package/lib/types/http.d.ts +41 -0
  152. package/lib/types/http.d.ts.map +1 -0
  153. package/lib/types/index.d.ts +56 -24
  154. package/lib/types/index.d.ts.map +1 -1
  155. package/lib/types/intercept-shape.d.ts +32 -0
  156. package/lib/types/intercept-shape.d.ts.map +1 -0
  157. package/lib/types/intercept.d.ts +442 -0
  158. package/lib/types/intercept.d.ts.map +1 -0
  159. package/lib/types/merge-streams.d.ts +398 -0
  160. package/lib/types/merge-streams.d.ts.map +1 -0
  161. package/lib/types/relay-access.d.ts +310 -0
  162. package/lib/types/relay-access.d.ts.map +1 -0
  163. package/lib/types/relay-client.d.ts +274 -0
  164. package/lib/types/relay-client.d.ts.map +1 -0
  165. package/lib/types/relay-filter.d.ts +103 -0
  166. package/lib/types/relay-filter.d.ts.map +1 -0
  167. package/lib/types/relay-server.d.ts +208 -0
  168. package/lib/types/relay-server.d.ts.map +1 -0
  169. package/lib/types/restart-fields.d.ts +22 -0
  170. package/lib/types/restart-fields.d.ts.map +1 -0
  171. package/lib/types/restart-watcher.d.ts +83 -0
  172. package/lib/types/restart-watcher.d.ts.map +1 -0
  173. package/lib/types/session-reference.d.ts +66 -0
  174. package/lib/types/session-reference.d.ts.map +1 -0
  175. package/lib/types/share-export.d.ts +14 -1
  176. package/lib/types/share-export.d.ts.map +1 -1
  177. package/lib/types/share-ops.d.ts +79 -0
  178. package/lib/types/share-ops.d.ts.map +1 -0
  179. package/lib/types/share-store.d.ts +87 -0
  180. package/lib/types/share-store.d.ts.map +1 -0
  181. package/lib/types/virtual-id.d.ts +52 -0
  182. package/lib/types/virtual-id.d.ts.map +1 -0
  183. package/lib/virtual-id.js +66 -0
  184. package/lib/virtual-id.js.map +1 -0
  185. package/llms.txt +17 -14
  186. package/package.json +60 -50
  187. package/scripts/build-client.mjs +5 -3
  188. package/scripts/check-host-shadow.mjs +19 -2
  189. package/scripts/check-settings-form.mjs +933 -0
  190. package/scripts/check-shares.mjs +397 -0
  191. package/scripts/check-upload-endpoint.mjs +59 -3
  192. package/scripts/sync-doc-version.mjs +8 -15
  193. package/scripts/verify-fingerprint-live.mjs +111 -0
  194. package/src/activity.ts +218 -0
  195. package/src/admin-routes.ts +627 -0
  196. package/src/client/MobileAttachButton.tsx +2 -2
  197. package/src/client/MobileAttachChips.tsx +3 -3
  198. package/src/client/MobileDrawerFooter.tsx +7 -4
  199. package/src/client/MobileHome.tsx +20 -16
  200. package/src/client/MobileHomeChips.tsx +16 -16
  201. package/src/client/MobileNavOverlay.tsx +2 -2
  202. package/src/client/MobileNavToggle.tsx +3 -3
  203. package/src/client/MobileSessionHeader.tsx +63 -42
  204. package/src/client/MobileSessionInfo.tsx +118 -17
  205. package/src/client/RemoteComposerBanner.tsx +76 -0
  206. package/src/client/RemoteHeaderIcon.tsx +103 -0
  207. package/src/client/RemoteShareMenu.tsx +57 -0
  208. package/src/client/RemoteStatusIcon.tsx +91 -0
  209. package/src/client/compat/desktop.ts +22 -0
  210. package/src/client/compat/types.ts +62 -0
  211. package/src/client/current-session-report.ts +164 -0
  212. package/src/client/effects/header-status.ts +21 -17
  213. package/src/client/effects/keyboard-guard.ts +65 -1
  214. package/src/client/effects/model-group-side.ts +132 -0
  215. package/src/client/effects/permission-sheet.ts +149 -0
  216. package/src/client/effects/remote-session.ts +68 -0
  217. package/src/client/effects/turn-fold.ts +52 -0
  218. package/src/client/index.tsx +158 -36
  219. package/src/client/locales.ts +396 -2
  220. package/src/client/remote-fetch.ts +125 -0
  221. package/src/client/remote-group-expansion.ts +190 -0
  222. package/src/client/remote-share-css.ts +54 -0
  223. package/src/client/remote-share-register.ts +244 -0
  224. package/src/client/remote-status-css.ts +64 -0
  225. package/src/client/remote-status-register.ts +107 -0
  226. package/src/client/settings/SettingsSection.tsx +1229 -0
  227. package/src/client/settings/register-settings.ts +116 -0
  228. package/src/client/settings/settings-css.ts +236 -0
  229. package/src/client/share/share-preview.tsx +6 -3
  230. package/src/client/share/share-sheet.tsx +3 -3
  231. package/src/client/styles/composer.css.ts +119 -26
  232. package/src/client/styles/header.css.ts +7 -7
  233. package/src/client/styles/info.css.ts +74 -0
  234. package/src/client/styles/remote-session.css.ts +274 -0
  235. package/src/client-data/current-session.ts +57 -0
  236. package/src/client-data/model-group-side.ts +65 -0
  237. package/src/client-data/remote-group-expansion.ts +145 -0
  238. package/src/client-data/remote-status.ts +374 -0
  239. package/src/client-data/settings-form.ts +1371 -0
  240. package/src/client-data/shares.ts +467 -0
  241. package/src/client-pairing.ts +244 -0
  242. package/src/client-routes.ts +732 -0
  243. package/src/config.ts +447 -0
  244. package/src/fetch-route-intercept.ts +510 -0
  245. package/src/fingerprint.ts +410 -0
  246. package/src/http.ts +68 -0
  247. package/src/index.ts +719 -62
  248. package/src/intercept-shape.ts +87 -0
  249. package/src/intercept.ts +3510 -0
  250. package/src/merge-streams.ts +1279 -0
  251. package/src/relay-access.ts +672 -0
  252. package/src/relay-client.ts +1514 -0
  253. package/src/relay-filter.ts +291 -0
  254. package/src/relay-server.ts +2063 -0
  255. package/src/restart-fields.ts +36 -0
  256. package/src/restart-watcher.ts +140 -0
  257. package/src/session-reference.ts +156 -0
  258. package/src/share-export.ts +26 -1
  259. package/src/share-ops.ts +114 -0
  260. package/src/share-store.ts +373 -0
  261. package/src/virtual-id.ts +74 -0
@@ -0,0 +1,310 @@
1
+ /**
2
+ * Pure access control for the relay invoke and stream routes (2.0.0
3
+ * desktop-client).
4
+ *
5
+ * PER-METHOD ALLOWLIST, not a generic id scan. The first draft extracted
6
+ * whatever session ids it could find in `args.request` and checked those —
7
+ * which a hostile client defeats with a DECOY: DSH's gateway validates only
8
+ * the top-level argument names (`assertExactArguments`) and zod silently
9
+ * strips unknown fields inside `request`, so padding the arguments with an
10
+ * extra shared `sessionId` gets through the share-table check while the
11
+ * method's REAL ownership field (`agentId`, `request.parentSessionId`, …)
12
+ * goes unchecked. The fix: every invokable method is registered below with
13
+ * EXACTLY the fields that locate its session, authorization looks at those
14
+ * fields and nothing else, and any method not in the table is refused
15
+ * (`forbidden-method`) before an id is ever read. The stream route
16
+ * ({@link decideStream}) reads the SAME table: only `stream: true` entries
17
+ * may ride it, and the field rules are identical.
18
+ *
19
+ * Field verification (T22a-fix, against the 0.2.0-rc.1 wire inventory in the
20
+ * review's keys.txt and the local `typert.remote-client.js` — the spike
21
+ * proved those files byte-identical across 0.1.7/0.2.0, docs/spike-relay.md
22
+ * §2.3):
23
+ *
24
+ * - `request.address` exists only on `session/follow` and `session/page`;
25
+ * its zod schema is a union of EXACTLY two shapes —
26
+ * `{kind:'session', sessionId}` and `{kind:'subagent', parentSessionId,
27
+ * childSessionId, mode}` — and DSH's `validateAddress` re-checks that the
28
+ * child belongs to the parent, so judging a subagent call by the parent id
29
+ * is authoritative. Any other kind, or a missing id, is a refusal.
30
+ * - every other method registered before T31 carries `request.sessionId`.
31
+ *
32
+ * T31 additions, each verified against the 0.2.0 sources before registering:
33
+ *
34
+ * - `session/create` carries `request.workspaceId` — a WORKSPACE id, never
35
+ * share-checked (workspaces do not live in the share table): it must be
36
+ * present, and the relay route validates it against the server's live
37
+ * workspace list before forwarding (relay-server.ts). The new session is
38
+ * auto-shared there, which is what makes the entry safe at all.
39
+ * - `session/fork` carries `request.sessionId` (the SOURCE session); the
40
+ * forked child is auto-shared after the call succeeds.
41
+ * - `subagents/prompt` (`request.parentSessionId`) and
42
+ * `subagents/interruptByParent` (TOP-LEVEL `parentSessionId`) are judged
43
+ * by the parent: DSH re-validates the parent-child link itself
44
+ * (`authorizeLineage` on both delivery paths of prompt; the user-authority
45
+ * check inside `interrupt`), so an unshared child can no more be reached
46
+ * than an unshared parent — it is refused server-side by DSH.
47
+ * - `fileUploads/upload` and `fileReferences/list` carry a TOP-LEVEL
48
+ * `agentId`: the gateway's `agent` lookup resolves it through the agent
49
+ * registry keyed by SESSION id (dsh-agent registers wire `agentId`,
50
+ * wireTypeSymbol `SessionId`), so it IS the session id and shares its
51
+ * check. A shared `request.sessionId` padded next to it buys nothing —
52
+ * only the registered field is read.
53
+ *
54
+ * T41a additions (the panel long tail where the session id hides in another
55
+ * argument), each verified against the 0.2.0 sources before registering:
56
+ *
57
+ * - the `agentId` group grows: `goals/get|edit|pause|resume|clear`,
58
+ * `commands/list|execute`, `agentPresets/select`,
59
+ * `sessionReferenceResolver/candidates` and the whole `terminal/*` agent
60
+ * half — every one takes `agent` as its first parameter, wire `agentId`,
61
+ * source `lookup: 'agent'`, wireTypeSymbol `SessionId` (the same shape
62
+ * T31 verified for fileUploads/fileReferences).
63
+ * - `workspaceFiles/list|changes|read|readBytes|stat` carry a TOP-LEVEL
64
+ * `workspaceFileScopeId`: the host registers the `workspaceFileScope`
65
+ * lookup with wireTypeSymbol `SessionId` and resolves it by session —
66
+ * `sessions.get(sessionId).header.cwd` is only the BASE for relative
67
+ * paths (dsh-api-workspace-files lib/index.js, the lookup registration),
68
+ * not a containment: absolute paths anywhere the server process can read
69
+ * are served (see the registry note below). The field itself is
70
+ * share-checked like any session id.
71
+ * - `terminal/list` and `terminal/retain` take a plain TOP-LEVEL json
72
+ * `sessionId` (source `'json'`, not a lookup) — same check.
73
+ * - `sessionFeedback/record` carries `request.sessionId` — a plain B-type.
74
+ * - `sessionReferenceResolver/candidates` (@ mentions) answers with EVERY
75
+ * server session — title, cwd, and a ready-made `dsh-session:` mention
76
+ * — so its result travels only through the row filter that drops
77
+ * inaccessible sessions (relay-server.ts, the session/list discipline).
78
+ * - `subagents/prompt` (`request.parentSessionId` +
79
+ * `request.childSessionId`) and `subagents/interruptByParent` (TOP-LEVEL
80
+ * `parentSessionId` + `childSessionId`) now claim BOTH ids: the parent is
81
+ * share-checked directly, the child through the injected `parentOf`
82
+ * inheritance (`store.isAccessible(id, parentOf)` — a subagent session
83
+ * never enters the table, it borrows its ancestor's share). A child that
84
+ * does not descend from the claimed parent fails its own check, so the
85
+ * "shared parent + foreign child" decoy refuses here before DSH's own
86
+ * lineage validation is ever reached.
87
+ *
88
+ * PROMPT TEXT REFERENCES ARE CHECKED TOO: a prompt whose text carries a
89
+ * canonical `dsh-session:<base64url(id)>` address makes DSH inject that
90
+ * session's content (`prepareDirectMessages` → `readSurface`, with no
91
+ * access check of its own), so the relay refuses any address naming an
92
+ * inaccessible session wherever such a text can enter (relay-server.ts,
93
+ * scanning by the shared rule in session-reference.ts, T41a-fix2): the
94
+ * `session/prompt` / `subagents/prompt` content, a `session/updateQueue`
95
+ * EDIT's replacement content, and EVERY string of a `commands/execute`
96
+ * call (a command handler steers its raw input in as a user message —
97
+ * `/plan <text>` does exactly that). The client restores its virtual ids
98
+ * inside those same positions before the call travels (intercept.ts).
99
+ *
100
+ * TERMINALS ARE DELIBERATE (SPEC user story 45, explicit user request):
101
+ * remote terminals open SERVER-side, so a paired desktop client working a
102
+ * shared session gets a real PTY in the server's workspace — a shell
103
+ * running as the server user WITHOUT the agent sandbox or approval
104
+ * restrictions (RT dsh-api-terminal-controller create), the session cwd
105
+ * being only the starting directory. The authorization boundary is exactly
106
+ * the standing one — the session must be shared AND the caller must be a
107
+ * paired desktop application client (the gateway's device auth + relay
108
+ * secret), a TRUSTED DEVICE: the shared-only rule constrains session data,
109
+ * not the machine. No extra switch is added on top; closing the session's
110
+ * remote access closes its terminals with it (the stream route kills
111
+ * `terminal/follow` / `terminal/retain` with `unshared`, like every other
112
+ * session-scoped stream). The terminal ids and attachment ids inside these
113
+ * calls are CLIENT-generated (`WebTerminalId` / `TerminalAttachmentId` type
114
+ * symbols, distinct from `SessionId`) and pass through untouched.
115
+ *
116
+ * Pure functions: no I/O, no clock, the share-table lookup is injected.
117
+ */
118
+ /** Which standing filter the caller must apply to a global stream's frames
119
+ * (`src/relay-filter.ts` owns both implementations; the `$zr/events`
120
+ * forwarding subscription is filtered by relay-server.ts itself — it needs
121
+ * the per-eventId registry, not a pure frame function). */
122
+ export type StreamFilter = 'workspace' | 'control';
123
+ /** Which standing filter the caller must apply to an invoke result before it
124
+ * travels: `session-list` narrows the unscoped `session/list` items
125
+ * (relay-filter.ts), `session-reference-candidates` drops the @-mention
126
+ * candidate rows whose session is not accessible (relay-server.ts — the host
127
+ * lists EVERY server session with title, cwd and a ready-made mention, so
128
+ * unshared rows must never leave the box), and `model-catalog` empties the
129
+ * `session/modelCatalog` `failures` array (T52-fix — relay-filter.ts: the
130
+ * host's per-group error texts may carry endpoint or credential details, and
131
+ * the client discards `failures` anyway). */
132
+ export type InvokeFilter = 'session-list' | 'session-reference-candidates' | 'model-catalog';
133
+ /** One invoke decision: allow (optionally through a standing result filter),
134
+ * or the reason that goes into the 403 body. */
135
+ export type InvokeDenyReason = 'no-session' | 'not-shared' | 'forbidden-method';
136
+ export type InvokeDecision = {
137
+ allow: true;
138
+ filter?: InvokeFilter;
139
+ } | {
140
+ allow: false;
141
+ reason: InvokeDenyReason;
142
+ };
143
+ /** One stream decision: allow (global streams carry a `streamFilter`, scoped
144
+ * streams list the session ids the subscription depends on — the relay kills
145
+ * the stream and counts viewers with them, and the event subscription sets
146
+ * `events`), or the 403 reason. */
147
+ export type StreamDecision = {
148
+ allow: true;
149
+ filter?: StreamFilter;
150
+ sessionIds: string[];
151
+ events?: true;
152
+ } | {
153
+ allow: false;
154
+ reason: InvokeDenyReason;
155
+ };
156
+ /**
157
+ * Decide one relayed invoke against the per-method allowlist:
158
+ *
159
+ * 1. the method must be registered AND invoke-delivered (a `stream: true`
160
+ * entry refuses the invoke route) — anything else is `forbidden-method`;
161
+ * 2. its registered fields must all yield an owned session id — else
162
+ * `no-session`;
163
+ * 3. every claimed id must pass `isAccessible` — one unreachable id refuses
164
+ * the whole call (`not-shared`): an unshared session must not become
165
+ * readable through a shared one riding in the same arguments.
166
+ *
167
+ * A method registered with `resultFilter` allows with that marker attached;
168
+ * the caller filters the result before it travels (never the reverse — the
169
+ * filter is an OUTPUT discipline, the access check above stays input-only).
170
+ */
171
+ export declare function decideInvoke(namespace: string, method: string, args: unknown, isAccessible: (sessionId: string) => boolean): InvokeDecision;
172
+ /**
173
+ * Decide one relayed STREAM subscription against the same table:
174
+ *
175
+ * 1. the method must be registered AND stream-delivered — an invoke-only
176
+ * method riding the stream route is `forbidden-method`, exactly like a
177
+ * stream method riding the invoke route;
178
+ * 2. a global entry (`streamFilter` set) allows unconditionally — its frames
179
+ * are filtered per frame, so there is nothing to check up front;
180
+ * 3. any other entry follows the {@link decideInvoke} field rules verbatim:
181
+ * all registered fields must yield owned ids and every id must be
182
+ * accessible, and the claimed ids ride back to the caller, which kills the
183
+ * subscription when one of them stops being shared.
184
+ */
185
+ export declare function decideStream(namespace: string, method: string, args: unknown, isAccessible: (sessionId: string) => boolean): StreamDecision;
186
+ /**
187
+ * The `$events/result` answer body (T32), as the client sends it:
188
+ * `{ eventId, result }`. `result` is the Remote event OUTCOME and travels
189
+ * VERBATIM — dsh-api-gateway's `parseRemoteEventResult` is the validator
190
+ * (exactly `{clientId,eventId,outcome}` up there; kinds `next` / `result`
191
+ * with optional JSON `value` / `rejected` with `{name,message,code?,details?}`),
192
+ * and a malformed one comes back as the gateway's own 200 error envelope, so
193
+ * re-validating here would only invent a second dialect for the same refusal.
194
+ * `eventId` ownership (forwarded on a live subscription, session still
195
+ * reachable) is the ROUTE's check — it needs the handler's registry.
196
+ */
197
+ export interface EventResultBody {
198
+ eventId: string;
199
+ result: Record<string, unknown>;
200
+ }
201
+ export declare function parseEventResultBody(body: unknown): EventResultBody | undefined;
202
+ /**
203
+ * The plain-HTTP panel long tail (T41b): the session-page surfaces that do
204
+ * NOT ride the typert gateway but GET `/api/...` routes registered as exact
205
+ * Fetch routes on the host's connection service (RT
206
+ * dsh-client-ui-deliverables/lib/index.js — `ctx.connection.fetch.register`
207
+ * at ~49-58 and ~84-90; the shared handler they dispatch through is
208
+ * `createSharedFetchHandler('/api')`, dsh-client-connection/lib/index.js
209
+ * ~608-637). Each entry names the query parameter that locates the session —
210
+ * the same per-route registration discipline as RELAY_METHODS, and the same
211
+ * refusal defaults: a route not in this table answers `unknown-route`
212
+ * (404) before any id is read, and a registered route is judged ONLY along
213
+ * its declared field.
214
+ *
215
+ * Deliberately ABSENT (the known limitations of the HTTP interception, kept
216
+ * beside the registry that makes the contrast true):
217
+ *
218
+ * - `/api/session.export` (session log download) — an anchor-click download,
219
+ * not a fetch call at all, and a full ZIP of the session's server-side log
220
+ * is not a body worth re-streaming through the relay. Remote sessions have
221
+ * export DISABLED instead (T51): the sub-client's own backend refuses
222
+ * `/api/session.export` for a virtual id with 403 `remote-unsupported`
223
+ * before the local route is ever reached (fetch-route-intercept.ts), and
224
+ * the UI entry is hidden on the same html attribute
225
+ * (remote-session.css.ts) — the host route's answer for a foreign id
226
+ * never happens.
227
+ * - `/api/present.host` — takes NO parameters and reports the machine the
228
+ * SERVER process runs on; forwarding it would read server-desktop facts
229
+ * into a panel whose actions stay hidden remotely, so it is not relayed.
230
+ * - `/api/changes.open` and `/api/present.open` — POST actions that open
231
+ * files ON THE SERVER MACHINE (Finder / applications); meaningless from a
232
+ * sub-client, so the UI entries are hidden remotely (remote-session.css)
233
+ * and the routes are not registered here.
234
+ *
235
+ * The one HTTP route that USED to be absent is no longer (T51):
236
+ * `/api/session/uploadFileBinary` (attachment upload, RT
237
+ * dsh-client-file-upload) — its Blob/stream branch runs inside a Web Worker
238
+ * over XHR / Worker-scoped fetch, which neither a `window.fetch` wrapper nor
239
+ * the GET passthrough this table serves can carry. The sub-client's own
240
+ * backend instead wraps that entry in the host's `fetchRoutes` map
241
+ * (fetch-route-intercept.ts) and forwards the raw byte stream through the
242
+ * DEDICATED binary channel `POST relay/v1/upload`, whose query is decided by
243
+ * {@link decideUploadQuery} below — the same parse-once normalization, share
244
+ * table and refusal codes as everything else here.
245
+ */
246
+ export interface RelayHttpRoute {
247
+ /** The query parameter carrying the owning session id. */
248
+ sessionField: 'sessionId';
249
+ }
250
+ export declare const RELAY_HTTP_ROUTES: Readonly<Record<string, RelayHttpRoute>>;
251
+ /** One plain-HTTP decision: allow — carrying the NORMALIZED query string
252
+ * that is the only thing the caller may put on the synthetic Request URL —
253
+ * or the reason for the answer: `unknown-route` (not in
254
+ * {@link RELAY_HTTP_ROUTES}) answers 404, `no-session` (the field is missing
255
+ * or duplicated) and `bad-query` (a whitelisted coordinate repeats or is not
256
+ * a decimal non-negative integer string) answer 400, and `not-shared`
257
+ * answers 403 like every other session-scoped refusal. */
258
+ export type HttpDenyReason = 'unknown-route' | 'no-session' | 'bad-query' | 'not-shared';
259
+ export type HttpDecision = {
260
+ allow: true;
261
+ query: string;
262
+ } | {
263
+ allow: false;
264
+ reason: HttpDenyReason;
265
+ };
266
+ /**
267
+ * Decide one relayed `/api` GET against the per-route allowlist, and
268
+ * NORMALIZE the query. The two halves of this route used to disagree about
269
+ * parsing: `URLSearchParams` keeps `\t` / `\r` / `\n` inside key names
270
+ * (`session\tId` is one parameter here) while the WHATWG URL parser strips
271
+ * control characters before the request URL is built — so a query whose
272
+ * checkable `sessionId` named a shared session could DISPATCH as two
273
+ * parameters, with the serving route's own `get('sessionId')` reading the
274
+ * first one, a secret (reviewer-confirmed 200). The fix is structural: this
275
+ * function parses ONCE, takes only the whitelisted parameters — `sessionId`
276
+ * exactly once (its id must pass the share table), `seq` / `index` at most
277
+ * once each and decimal non-negative integers — and returns the rebuilt,
278
+ * fixed-order query string; the caller composes the synthetic URL from THAT
279
+ * string alone, never from raw input. Unknown parameters are dropped.
280
+ */
281
+ export declare function decideHttpRoute(route: unknown, query: unknown, isAccessible: (sessionId: string) => boolean): HttpDecision;
282
+ /**
283
+ * The binary upload channel's query (T51), decided with the SAME
284
+ * parse-once discipline as {@link decideHttpRoute}: the wire string is
285
+ * parsed exactly once here, only `sessionId` and `name` are kept, and the
286
+ * caller composes the synthetic Request URL from the RETURNED string alone.
287
+ * `URLSearchParams` keeps `\t` / `\r` / `\n` inside key names while the
288
+ * WHATWG URL parser strips control characters — the differential that was
289
+ * T41b-fix's authorization bypass on the GET routes — so the check and the
290
+ * dispatch must see one parse.
291
+ *
292
+ * `sessionId` exactly once, a non-empty string, and share-checked like any
293
+ * other session id; a repeat is `no-session` (400). `name` (the file's
294
+ * display name — the host route passes it to its own leaf-name sanitizer,
295
+ * RT dsh-client-file-upload lib/index.js `handleFileUploadHttp`) at most
296
+ * once; a repeat is `bad-query` (400) and an empty value is dropped, the
297
+ * same "absent" the host route reads when the browser sent none. Everything
298
+ * else is discarded before an id is read.
299
+ */
300
+ export type UploadQueryDecision = {
301
+ allow: true;
302
+ sessionId: string;
303
+ name: string | undefined;
304
+ query: string;
305
+ } | {
306
+ allow: false;
307
+ reason: 'no-session' | 'bad-query' | 'not-shared';
308
+ };
309
+ export declare function decideUploadQuery(query: unknown, isAccessible: (sessionId: string) => boolean): UploadQueryDecision;
310
+ //# sourceMappingURL=relay-access.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"relay-access.d.ts","sourceRoot":"","sources":["../../src/relay-access.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,274 @@
1
+ /**
2
+ * Relay client for the sub-client half (T23a): the `client`-role side of the
3
+ * 2.0.0 relay protocol. A DSH process on another machine pairs with a relay
4
+ * server's gateway (Bearer device token, T16) and reaches the server's
5
+ * shared sessions through `POST relay/v1/handshake|invoke|stream` — this
6
+ * module speaks that wire from the far end, with no dependencies beyond the
7
+ * Node 18+ standard library and the global `fetch`.
8
+ *
9
+ * Every call re-reads the credentials through the injected getters, so a
10
+ * re-pair in the settings page applies to the NEXT request without touching
11
+ * this module (the same volatile-row discipline src/client-routes.ts keeps).
12
+ * Missing credentials never touch the network: the client reports
13
+ * `unpaired` and every entry point throws immediately.
14
+ *
15
+ * Two wire details are load-bearing. `accept: application/json` — the
16
+ * gateway answers its pairing wall as a JSON 401 `{reason:'unpaired'}` only
17
+ * to requests that accept JSON; without the header a revoked token would
18
+ * draw the HTML pairing page and be unclassifiable. `redirect: 'manual'` —
19
+ * a wrong or hijacked server must not walk the pairing token through a
20
+ * redirect chain (the same rule src/client-routes.ts probes with).
21
+ *
22
+ * State moves only where the contract says so: `offline` on transport
23
+ * failure, `revoked` on the gateway's unpaired wall, `incompatible` on the
24
+ * relay-only wall or a handshake protocol mismatch, and back to `online` on
25
+ * any success envelope. Everything else — the per-call refusals
26
+ * (`not-shared` / `no-session` / `forbidden-method`), a 200 `{ok:false}`
27
+ * envelope, the gateway's own `relay-unauthorized` — is an ANSWER about the
28
+ * call, not about the link, and leaves the state alone.
29
+ *
30
+ * Since T43 the client also reconnects on its own: an `offline` client walks
31
+ * a 1s → 2s → 5s → 10s → 30s ladder (0–20% jitter per wait) until a success
32
+ * lifts it back to `online`; `unpaired`, `revoked` and `incompatible` never
33
+ * reconnect on their own — they need a user action, which arrives as
34
+ * `credentialsChanged()` (or a fresh `connect()`). The wait is observable as
35
+ * `nextRetryAt`, the last failure code as `lastError`; both carry no
36
+ * credential material.
37
+ *
38
+ * Since T42 the client also judges INTERFACE compatibility: when the wiring
39
+ * injects `computeOwnFingerprints`, every completed handshake is followed by
40
+ * a group-by-group comparison of the server's `fingerprints` map against the
41
+ * locally computed one, stored as `compat` ({@link RelayCompatVerdict}).
42
+ * Groups either side could not compute land in `unavailable` — never in
43
+ * `different` — so a partial view stays silent. The verdict is read live by
44
+ * the status route; listeners additionally hear about it through the same
45
+ * notification channel the state changes use.
46
+ */
47
+ import type { RelayCompatVerdict } from './fingerprint.js';
48
+ /**
49
+ * The clock face the reconnect machinery runs on: wall time, timers and the
50
+ * jitter source. Injectable so tests drive the whole backoff sequence
51
+ * deterministically. The default timers are `unref()`ed — a pending retry
52
+ * must never keep the host process alive on its own.
53
+ */
54
+ export interface RelayClock {
55
+ /** Epoch milliseconds. */
56
+ now(): number;
57
+ setTimeout(fn: () => void, ms: number): unknown;
58
+ clearTimeout(handle: unknown): void;
59
+ /** One random sample in [0, 1] — the jitter source. */
60
+ random(): number;
61
+ }
62
+ /**
63
+ * The default clock: real time, `unref()`ed timers, `Math.random`. Exported
64
+ * so the interceptor's own waits (the merged-stream reopen delays) run on
65
+ * the SAME clock face — one injectable seam for tests instead of two.
66
+ */
67
+ export declare const defaultClock: RelayClock;
68
+ /** The connection states the settings surface renders (and `subscribe`
69
+ * listeners react to). */
70
+ export type RelayState = 'unpaired' | 'connecting' | 'online' | 'offline' | 'revoked' | 'incompatible';
71
+ /** The handshake reply, verbatim from `POST relay/v1/handshake`. */
72
+ export interface RelayHandshake {
73
+ relayProtocol: number;
74
+ serverId: string;
75
+ serverName: string;
76
+ dshVersion: string;
77
+ fingerprints: Record<string, string>;
78
+ /**
79
+ * The SERVER's record of THIS device's name (T59) — what the pairing
80
+ * registered and renames have since made of it. `undefined` from an older
81
+ * server that does not send the field; the client then keeps whatever it
82
+ * has and pushes nothing.
83
+ */
84
+ deviceName?: string;
85
+ }
86
+ /**
87
+ * One relay failure. `code` is the mapped reason (the contract's state
88
+ * vocabulary, a server refusal like `not-shared`, or a DSH error code from
89
+ * a 200 `{ok:false}` envelope); `status` carries the HTTP status when a
90
+ * response existed. `reason` is the OPTIONAL structured detail some error
91
+ * frames carry beside the message — today only the server's `unshared`
92
+ * stream-closure frame, whose `reason` ('manual' | 'client' | 'idle', T34)
93
+ * the interceptor's closed-session display keys on. Fields are assigned in
94
+ * the constructor body rather than declared as parameter properties: Node's
95
+ * strip-only type mode rejects that syntax (the same rule as UploadError in
96
+ * index.ts).
97
+ */
98
+ export declare class RelayError extends Error {
99
+ code: string;
100
+ status?: number;
101
+ reason?: string;
102
+ constructor(code: string, message?: string, httpStatus?: number, reason?: string);
103
+ }
104
+ export interface CreateRelayClientOptions {
105
+ /** The normalized server address (no trailing slash), read live per
106
+ * request; `undefined` counts as unpaired. */
107
+ getServerUrl: () => string | undefined;
108
+ /** The pairing token, read live per request; `undefined` counts as
109
+ * unpaired. */
110
+ getToken: () => string | undefined;
111
+ /** Outbound fetch, defaulting to the global one. */
112
+ fetchImpl?: typeof fetch;
113
+ /** How long a stream may go without receiving ANY line (frames and
114
+ * `ping`s alike) before it is judged dead and aborted; default 45000. */
115
+ idleTimeoutMs?: number;
116
+ /** How long one request/response round-trip (handshake, invoke — and the
117
+ * headers of a stream open) may take; default 15000. */
118
+ requestTimeoutMs?: number;
119
+ /** Clock/timers/jitter for the reconnect backoff; defaults to the real
120
+ * ones (timers `unref()`ed). Tests inject a manual clock. */
121
+ clock?: RelayClock;
122
+ /**
123
+ * How often an ONLINE client re-runs the handshake to refresh the two
124
+ * names (T59, {@link INFO_REFRESH_MS}); `0` disables the periodic refresh
125
+ * — handshake-counting tests inject 0, the refresh test injects a cadence
126
+ * its fake clock can drive.
127
+ */
128
+ infoRefreshMs?: number;
129
+ /** This side's own interface fingerprints (T42), computed after each
130
+ * completed handshake and compared group by group against the handshake's
131
+ * map. May be sync or async; a throw counts as "nothing computed" (an
132
+ * empty map — every group lands `unavailable`). Absent: `compat` stays
133
+ * undefined and no comparison ever runs (the host role's client, tests). */
134
+ computeOwnFingerprints?: () => Promise<Record<string, string>> | Record<string, string>;
135
+ }
136
+ export interface RelayClient {
137
+ readonly state: RelayState;
138
+ /** The last completed handshake, undefined until one succeeds. */
139
+ readonly handshakeInfo: RelayHandshake | undefined;
140
+ /** Digest ({@link relayCredentialsDigest}) of the address+token the last
141
+ * completed handshake actually used, undefined until one succeeds. The
142
+ * status route compares it against the CURRENT row credentials to keep a
143
+ * cached "online" verdict from outliving the credentials it was earned
144
+ * with. */
145
+ readonly lastHandshakeDigest: string | undefined;
146
+ /** Epoch ms of the next automatic reconnect, or null while none is
147
+ * scheduled (connected, attempting, or in a state that never reconnects).
148
+ * Rendered by the settings page as "离线,将于 N 秒后重试". */
149
+ readonly nextRetryAt: number | null;
150
+ /** The error CODE of the most recent failure ('offline',
151
+ * 'relay-unauthorized', a DSH code, …) — never a message, never a token or
152
+ * URL. Cleared when a request succeeds again. */
153
+ readonly lastError: string | undefined;
154
+ /** The interface-compatibility verdict of the most recent handshake (T42):
155
+ * group names that matched, differed, or could not be compared. Undefined
156
+ * until a first handshake ran WITH `computeOwnFingerprints` wired, and
157
+ * cleared again whenever the link or the credentials move (unpaired,
158
+ * revoked, credentialsChanged) — it describes the credentials it was
159
+ * earned with, never the current ones. */
160
+ readonly compat: RelayCompatVerdict | undefined;
161
+ /** Observe state changes; a throwing listener never blocks the others.
162
+ * The CURRENT state is also broadcast when only the handshake identity
163
+ * moved (the T59 heartbeat names) — listeners re-read the getters. */
164
+ subscribe(listener: (state: RelayState) => void): () => void;
165
+ /** The row's `serverName` was just committed (T59): forward it to the
166
+ * gateway's device table when it differs from the server's record —
167
+ * immediately while online, queued for the next `online` otherwise. A
168
+ * name equal to the server's record is a no-op BY CONTRACT: that is the
169
+ * settings page's server-driven write echoing back, and pushing it would
170
+ * set the two ends overwriting each other. */
171
+ queueDeviceName(name: string): void;
172
+ /** Whether a locally-pushed rename is queued or in flight (T59-fix). The
173
+ * status route answers an EMPTY `deviceName` while this is true — an
174
+ * in-flight answer could still carry the pre-push record, and the page
175
+ * following it would bounce the fresh save back to the old name. */
176
+ readonly deviceNameSyncing: boolean;
177
+ /** Run the handshake; success resolves with it and leaves `online`. */
178
+ connect(): Promise<RelayHandshake>;
179
+ /** One immediate connection attempt from `offline`, resetting the backoff
180
+ * ladder (the settings page's 立即重连). Answers whether an attempt was
181
+ * started — the reconnect route turns a false into a 409. */
182
+ reconnect(): boolean;
183
+ /** Notify that the credentials source may have changed (the loader's
184
+ * volatile-update for the row): a pending reconnect wait is cancelled and,
185
+ * with credentials present, one immediate attempt runs with the new
186
+ * values; without them the client lands `unpaired`. */
187
+ credentialsChanged(): void;
188
+ /** Stop the automatic reconnect machinery (plugin row teardown). Explicit
189
+ * connect() calls still work, but no timer is armed again. */
190
+ stop(): void;
191
+ /** One invoke round-trip; resolves with the unwrapped `value`, throws
192
+ * RelayError otherwise. A caller abort surfaces as `RelayError('aborted')`. */
193
+ invoke(namespace: string, method: string, args: unknown, signal?: AbortSignal): Promise<unknown>;
194
+ /** Close one session's remote access on the SERVER (T34): the original
195
+ * (non-virtual) session id rides `POST relay/v1/unshare`, the server
196
+ * unshares it with reason `'client'`. Resolves on the success envelope;
197
+ * every refusal (`not-shared`, a wall, transport death) throws RelayError.
198
+ * A success proves the link and lifts a stale `offline` back to `online`,
199
+ * exactly like invoke. */
200
+ unshare(sessionId: string, signal?: AbortSignal): Promise<void>;
201
+ /** Answer one forwarded Remote event (T32): `eventId` is the ORIGINAL id
202
+ * (the interceptor swapped the virtual one back), `result` the Remote
203
+ * event OUTCOME, forwarded verbatim — the gateway validates it. The error
204
+ * mapping is invoke's: a success envelope resolves (with the value, in
205
+ * practice undefined), everything else throws RelayError. */
206
+ postEventResult(eventId: string, result: unknown, signal?: AbortSignal): Promise<unknown>;
207
+ /** Open the NDJSON stream route. `frame` lines are yielded, `ping` lines
208
+ * only refresh the idle clock, `end` finishes the iteration, an `error`
209
+ * line throws its RelayError. A caller abort ENDS the iteration normally;
210
+ * `break` aborts the underlying request. */
211
+ openStream(namespace: string, method: string, args: unknown, signal?: AbortSignal): AsyncIterable<unknown>;
212
+ /** One plain-HTTP round-trip (T41b): `route` / `query` name a registered
213
+ * `/api` GET (relay-access's RELAY_HTTP_ROUTES; `query` is the URL-encoded
214
+ * query string with the session id already restored). Resolves with the
215
+ * UPSTREAM answer — its status, content type and body text ride inside the
216
+ * success envelope, so a 404 from the underlying route is a RESOLVED
217
+ * result here, never a RelayError. */
218
+ http(route: string, query: string, signal?: AbortSignal): Promise<RelayHttpResult>;
219
+ /** One binary upload round-trip (T51): `sessionId` is the ORIGINAL
220
+ * session id, `name` the optional display filename, `body` the raw byte
221
+ * stream forwarded verbatim. The upstream answer (its status, content
222
+ * type and body text — the host route answers its business failures as
223
+ * 200-with-envelope, so those ride RESOLVED like `http`'s) comes back in
224
+ * the success envelope; every refusal or link death throws RelayError.
225
+ * The round-trip budget scales with `bytes` (the local request's declared
226
+ * `Content-Length`, when it had one) and a timeout there never moves the
227
+ * connection state — the invoke route's rules (T31-fix). */
228
+ upload(options: RelayUploadOptions, signal?: AbortSignal): Promise<RelayHttpResult>;
229
+ }
230
+ /** The inputs of one {@link RelayClient.upload} round-trip. */
231
+ export interface RelayUploadOptions {
232
+ /** The ORIGINAL (non-virtual) session id, already restored by the caller. */
233
+ sessionId: string;
234
+ /** The file's display name, when the local request carried one. */
235
+ name?: string;
236
+ /** The raw request body. `null` (a bodyless upload — the host route would
237
+ * answer its own empty-stream business failure) forwards as an empty
238
+ * stream. */
239
+ body: ReadableStream<Uint8Array> | null;
240
+ /** The local request's declared byte count, when its `Content-Length` was
241
+ * readable — sizes the round-trip budget and nothing else. */
242
+ bytes?: number;
243
+ }
244
+ /** The upstream answer one {@link RelayClient.http} round-trip carries. */
245
+ export interface RelayHttpResult {
246
+ /** The underlying `/api` route's HTTP status. */
247
+ status: number;
248
+ /** The underlying response's content type, when it sent one. */
249
+ contentType: string | undefined;
250
+ /** The underlying response body, decoded as text (both registered routes
251
+ * answer buffered JSON). */
252
+ body: string;
253
+ }
254
+ /**
255
+ * The credential digest recorded beside a completed handshake (T23a-fix):
256
+ * sha256 over `url + "\n" + token`, first 16 hex chars. Enough to detect a
257
+ * changed address or a re-pair, without keeping — or ever exposing — a
258
+ * plaintext copy of either value.
259
+ */
260
+ export declare function relayCredentialsDigest(serverUrl: string, token: string): string;
261
+ /**
262
+ * Whether the loader's `loader/volatile-update` announcement names the
263
+ * device's own field (T59-fix): the announcement rides EVERY volatile
264
+ * commit — an unrelated knob, or the settings page's own follow write — and
265
+ * only a commit that actually moved `serverName` may queue a push. The
266
+ * paths are the loader's changed-field lists (`[['serverName'], …]`).
267
+ */
268
+ export declare function volatileUpdateTouchesServerName(paths: unknown): boolean;
269
+ /**
270
+ * Build one relay client. Pure state machine + fetch plumbing; the row is
271
+ * only ever seen through the two getters.
272
+ */
273
+ export declare function createRelayClient(options: CreateRelayClientOptions): RelayClient;
274
+ //# sourceMappingURL=relay-client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"relay-client.d.ts","sourceRoot":"","sources":["../../src/relay-client.ts"],"names":[],"mappings":"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"}