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.
- package/AGENTS.md +54 -9
- package/README.md +249 -190
- package/README.zh-CN.md +247 -201
- package/assets/home.png +0 -0
- package/assets/info.png +0 -0
- package/assets/pairing.png +0 -0
- package/assets/session.png +0 -0
- package/assets/sheet.png +0 -0
- package/cordis.patch.yml +12 -11
- package/cordis.patch.yml.example +24 -9
- package/docs/interface.md +57 -2
- package/docs/remote-access.en.md +99 -58
- package/docs/remote-access.md +99 -42
- package/dsh-push.mjs +67 -54
- package/lan-gate.mjs +88 -20
- package/lib/activity.js +168 -0
- package/lib/activity.js.map +1 -0
- package/lib/admin-routes.js +526 -0
- package/lib/admin-routes.js.map +1 -0
- package/lib/client-pairing.js +224 -0
- package/lib/client-pairing.js.map +1 -0
- package/lib/client-routes.js +674 -0
- package/lib/client-routes.js.map +1 -0
- package/lib/client.js +11498 -5990
- package/lib/config.js +346 -0
- package/lib/config.js.map +1 -0
- package/lib/fetch-route-intercept.js +418 -0
- package/lib/fetch-route-intercept.js.map +1 -0
- package/lib/fingerprint.js +365 -0
- package/lib/fingerprint.js.map +1 -0
- package/lib/http.js +69 -0
- package/lib/http.js.map +1 -0
- package/lib/index.js +675 -54
- package/lib/index.js.map +1 -1
- package/lib/intercept-shape.js +81 -0
- package/lib/intercept-shape.js.map +1 -0
- package/lib/intercept.js +3181 -0
- package/lib/intercept.js.map +1 -0
- package/lib/lan-gate-server.cjs +532 -121
- package/lib/merge-streams.js +1172 -0
- package/lib/merge-streams.js.map +1 -0
- package/lib/relay-access.js +496 -0
- package/lib/relay-access.js.map +1 -0
- package/lib/relay-client.js +1303 -0
- package/lib/relay-client.js.map +1 -0
- package/lib/relay-filter.js +282 -0
- package/lib/relay-filter.js.map +1 -0
- package/lib/relay-server.js +1813 -0
- package/lib/relay-server.js.map +1 -0
- package/lib/restart-fields.js +34 -0
- package/lib/restart-fields.js.map +1 -0
- package/lib/restart-watcher.js +106 -0
- package/lib/restart-watcher.js.map +1 -0
- package/lib/session-reference.js +157 -0
- package/lib/session-reference.js.map +1 -0
- package/lib/share-export.js +16 -1
- package/lib/share-export.js.map +1 -1
- package/lib/share-ops.js +86 -0
- package/lib/share-ops.js.map +1 -0
- package/lib/share-store.js +294 -0
- package/lib/share-store.js.map +1 -0
- package/lib/types/activity.d.ts +99 -0
- package/lib/types/activity.d.ts.map +1 -0
- package/lib/types/admin-routes.d.ts +129 -0
- package/lib/types/admin-routes.d.ts.map +1 -0
- package/lib/types/client/MobileDrawerFooter.d.ts.map +1 -1
- package/lib/types/client/MobileHome.d.ts +1 -1
- package/lib/types/client/MobileHome.d.ts.map +1 -1
- package/lib/types/client/MobileHomeChips.d.ts +1 -1
- package/lib/types/client/MobileHomeChips.d.ts.map +1 -1
- package/lib/types/client/MobileSessionHeader.d.ts +13 -2
- package/lib/types/client/MobileSessionHeader.d.ts.map +1 -1
- package/lib/types/client/MobileSessionInfo.d.ts +20 -3
- package/lib/types/client/MobileSessionInfo.d.ts.map +1 -1
- package/lib/types/client/RemoteComposerBanner.d.ts +42 -0
- package/lib/types/client/RemoteComposerBanner.d.ts.map +1 -0
- package/lib/types/client/RemoteHeaderIcon.d.ts +37 -0
- package/lib/types/client/RemoteHeaderIcon.d.ts.map +1 -0
- package/lib/types/client/RemoteShareMenu.d.ts +28 -0
- package/lib/types/client/RemoteShareMenu.d.ts.map +1 -0
- package/lib/types/client/RemoteStatusIcon.d.ts +36 -0
- package/lib/types/client/RemoteStatusIcon.d.ts.map +1 -0
- package/lib/types/client/compat/desktop.d.ts +21 -0
- package/lib/types/client/compat/desktop.d.ts.map +1 -0
- package/lib/types/client/compat/types.d.ts +57 -0
- package/lib/types/client/compat/types.d.ts.map +1 -1
- package/lib/types/client/current-session-report.d.ts +37 -0
- package/lib/types/client/current-session-report.d.ts.map +1 -0
- package/lib/types/client/effects/header-status.d.ts.map +1 -1
- package/lib/types/client/effects/keyboard-guard.d.ts.map +1 -1
- package/lib/types/client/effects/model-group-side.d.ts +13 -0
- package/lib/types/client/effects/model-group-side.d.ts.map +1 -0
- package/lib/types/client/effects/permission-sheet.d.ts +39 -0
- package/lib/types/client/effects/permission-sheet.d.ts.map +1 -0
- package/lib/types/client/effects/remote-session.d.ts +25 -0
- package/lib/types/client/effects/remote-session.d.ts.map +1 -0
- package/lib/types/client/effects/turn-fold.d.ts +9 -0
- package/lib/types/client/effects/turn-fold.d.ts.map +1 -1
- package/lib/types/client/index.d.ts.map +1 -1
- package/lib/types/client/locales.d.ts +187 -2
- package/lib/types/client/locales.d.ts.map +1 -1
- package/lib/types/client/remote-fetch.d.ts +51 -0
- package/lib/types/client/remote-fetch.d.ts.map +1 -0
- package/lib/types/client/remote-group-expansion.d.ts +41 -0
- package/lib/types/client/remote-group-expansion.d.ts.map +1 -0
- package/lib/types/client/remote-share-css.d.ts +19 -0
- package/lib/types/client/remote-share-css.d.ts.map +1 -0
- package/lib/types/client/remote-share-register.d.ts +113 -0
- package/lib/types/client/remote-share-register.d.ts.map +1 -0
- package/lib/types/client/remote-status-css.d.ts +15 -0
- package/lib/types/client/remote-status-css.d.ts.map +1 -0
- package/lib/types/client/remote-status-register.d.ts +46 -0
- package/lib/types/client/remote-status-register.d.ts.map +1 -0
- package/lib/types/client/settings/SettingsSection.d.ts +46 -0
- package/lib/types/client/settings/SettingsSection.d.ts.map +1 -0
- package/lib/types/client/settings/register-settings.d.ts +58 -0
- package/lib/types/client/settings/register-settings.d.ts.map +1 -0
- package/lib/types/client/settings/settings-css.d.ts +10 -0
- package/lib/types/client/settings/settings-css.d.ts.map +1 -0
- package/lib/types/client/share/share-preview.d.ts.map +1 -1
- package/lib/types/client/styles/composer.css.d.ts +1 -1
- package/lib/types/client/styles/composer.css.d.ts.map +1 -1
- package/lib/types/client/styles/header.css.d.ts +1 -1
- package/lib/types/client/styles/header.css.d.ts.map +1 -1
- package/lib/types/client/styles/info.css.d.ts +1 -1
- package/lib/types/client/styles/info.css.d.ts.map +1 -1
- package/lib/types/client/styles/remote-session.css.d.ts +2 -0
- package/lib/types/client/styles/remote-session.css.d.ts.map +1 -0
- package/lib/types/client-data/current-session.d.ts +41 -0
- package/lib/types/client-data/current-session.d.ts.map +1 -0
- package/lib/types/client-data/model-group-side.d.ts +44 -0
- package/lib/types/client-data/model-group-side.d.ts.map +1 -0
- package/lib/types/client-data/remote-group-expansion.d.ts +76 -0
- package/lib/types/client-data/remote-group-expansion.d.ts.map +1 -0
- package/lib/types/client-data/remote-status.d.ts +148 -0
- package/lib/types/client-data/remote-status.d.ts.map +1 -0
- package/lib/types/client-data/settings-form.d.ts +774 -0
- package/lib/types/client-data/settings-form.d.ts.map +1 -0
- package/lib/types/client-data/shares.d.ts +211 -0
- package/lib/types/client-data/shares.d.ts.map +1 -0
- package/lib/types/client-pairing.d.ts +114 -0
- package/lib/types/client-pairing.d.ts.map +1 -0
- package/lib/types/client-routes.d.ts +112 -0
- package/lib/types/client-routes.d.ts.map +1 -0
- package/lib/types/config.d.ts +200 -0
- package/lib/types/config.d.ts.map +1 -0
- package/lib/types/fetch-route-intercept.d.ts +156 -0
- package/lib/types/fetch-route-intercept.d.ts.map +1 -0
- package/lib/types/fingerprint.d.ts +166 -0
- package/lib/types/fingerprint.d.ts.map +1 -0
- package/lib/types/http.d.ts +41 -0
- package/lib/types/http.d.ts.map +1 -0
- package/lib/types/index.d.ts +56 -24
- package/lib/types/index.d.ts.map +1 -1
- package/lib/types/intercept-shape.d.ts +32 -0
- package/lib/types/intercept-shape.d.ts.map +1 -0
- package/lib/types/intercept.d.ts +442 -0
- package/lib/types/intercept.d.ts.map +1 -0
- package/lib/types/merge-streams.d.ts +398 -0
- package/lib/types/merge-streams.d.ts.map +1 -0
- package/lib/types/relay-access.d.ts +310 -0
- package/lib/types/relay-access.d.ts.map +1 -0
- package/lib/types/relay-client.d.ts +274 -0
- package/lib/types/relay-client.d.ts.map +1 -0
- package/lib/types/relay-filter.d.ts +103 -0
- package/lib/types/relay-filter.d.ts.map +1 -0
- package/lib/types/relay-server.d.ts +208 -0
- package/lib/types/relay-server.d.ts.map +1 -0
- package/lib/types/restart-fields.d.ts +22 -0
- package/lib/types/restart-fields.d.ts.map +1 -0
- package/lib/types/restart-watcher.d.ts +83 -0
- package/lib/types/restart-watcher.d.ts.map +1 -0
- package/lib/types/session-reference.d.ts +66 -0
- package/lib/types/session-reference.d.ts.map +1 -0
- package/lib/types/share-export.d.ts +14 -1
- package/lib/types/share-export.d.ts.map +1 -1
- package/lib/types/share-ops.d.ts +79 -0
- package/lib/types/share-ops.d.ts.map +1 -0
- package/lib/types/share-store.d.ts +87 -0
- package/lib/types/share-store.d.ts.map +1 -0
- package/lib/types/virtual-id.d.ts +52 -0
- package/lib/types/virtual-id.d.ts.map +1 -0
- package/lib/virtual-id.js +66 -0
- package/lib/virtual-id.js.map +1 -0
- package/llms.txt +17 -14
- package/package.json +60 -50
- package/scripts/build-client.mjs +5 -3
- package/scripts/check-host-shadow.mjs +19 -2
- package/scripts/check-settings-form.mjs +933 -0
- package/scripts/check-shares.mjs +397 -0
- package/scripts/check-upload-endpoint.mjs +59 -3
- package/scripts/sync-doc-version.mjs +8 -15
- package/scripts/verify-fingerprint-live.mjs +111 -0
- package/src/activity.ts +218 -0
- package/src/admin-routes.ts +627 -0
- package/src/client/MobileAttachButton.tsx +2 -2
- package/src/client/MobileAttachChips.tsx +3 -3
- package/src/client/MobileDrawerFooter.tsx +7 -4
- package/src/client/MobileHome.tsx +20 -16
- package/src/client/MobileHomeChips.tsx +16 -16
- package/src/client/MobileNavOverlay.tsx +2 -2
- package/src/client/MobileNavToggle.tsx +3 -3
- package/src/client/MobileSessionHeader.tsx +63 -42
- package/src/client/MobileSessionInfo.tsx +118 -17
- package/src/client/RemoteComposerBanner.tsx +76 -0
- package/src/client/RemoteHeaderIcon.tsx +103 -0
- package/src/client/RemoteShareMenu.tsx +57 -0
- package/src/client/RemoteStatusIcon.tsx +91 -0
- package/src/client/compat/desktop.ts +22 -0
- package/src/client/compat/types.ts +62 -0
- package/src/client/current-session-report.ts +164 -0
- package/src/client/effects/header-status.ts +21 -17
- package/src/client/effects/keyboard-guard.ts +65 -1
- package/src/client/effects/model-group-side.ts +132 -0
- package/src/client/effects/permission-sheet.ts +149 -0
- package/src/client/effects/remote-session.ts +68 -0
- package/src/client/effects/turn-fold.ts +52 -0
- package/src/client/index.tsx +158 -36
- package/src/client/locales.ts +396 -2
- package/src/client/remote-fetch.ts +125 -0
- package/src/client/remote-group-expansion.ts +190 -0
- package/src/client/remote-share-css.ts +54 -0
- package/src/client/remote-share-register.ts +244 -0
- package/src/client/remote-status-css.ts +64 -0
- package/src/client/remote-status-register.ts +107 -0
- package/src/client/settings/SettingsSection.tsx +1229 -0
- package/src/client/settings/register-settings.ts +116 -0
- package/src/client/settings/settings-css.ts +236 -0
- package/src/client/share/share-preview.tsx +6 -3
- package/src/client/share/share-sheet.tsx +3 -3
- package/src/client/styles/composer.css.ts +119 -26
- package/src/client/styles/header.css.ts +7 -7
- package/src/client/styles/info.css.ts +74 -0
- package/src/client/styles/remote-session.css.ts +274 -0
- package/src/client-data/current-session.ts +57 -0
- package/src/client-data/model-group-side.ts +65 -0
- package/src/client-data/remote-group-expansion.ts +145 -0
- package/src/client-data/remote-status.ts +374 -0
- package/src/client-data/settings-form.ts +1371 -0
- package/src/client-data/shares.ts +467 -0
- package/src/client-pairing.ts +244 -0
- package/src/client-routes.ts +732 -0
- package/src/config.ts +447 -0
- package/src/fetch-route-intercept.ts +510 -0
- package/src/fingerprint.ts +410 -0
- package/src/http.ts +68 -0
- package/src/index.ts +719 -62
- package/src/intercept-shape.ts +87 -0
- package/src/intercept.ts +3510 -0
- package/src/merge-streams.ts +1279 -0
- package/src/relay-access.ts +672 -0
- package/src/relay-client.ts +1514 -0
- package/src/relay-filter.ts +291 -0
- package/src/relay-server.ts +2063 -0
- package/src/restart-fields.ts +36 -0
- package/src/restart-watcher.ts +140 -0
- package/src/session-reference.ts +156 -0
- package/src/share-export.ts +26 -1
- package/src/share-ops.ts +114 -0
- package/src/share-store.ts +373 -0
- 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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"}
|