dsh-local-link 0.1.0

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/CHANGELOG.md ADDED
@@ -0,0 +1,23 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+
5
+ ## 0.1.0 — 2026-08-28
6
+
7
+ ### Added
8
+
9
+ - Local-only authenticated gateway to the stock DeepSeek Harness Web UI.
10
+ - One-use QR and copyable-link pairing with expiry and regeneration.
11
+ - Current-session transfer and live HTTP/WebSocket proxying.
12
+ - Remembered browsers with editable names, detected category/browser metadata, and revocation.
13
+ - Native sidebar and Settings integration with English and Chinese localization.
14
+ - Compatibility handling for Cordis footer coexistence and legacy device records.
15
+ - Mobile pairing page with robust browser detection, bounded connection time, and visible network/expiry errors instead of an endless spinner.
16
+ - Event-driven local diagnostics retaining only the latest 15 failures, with structured codes, burst coalescing, privacy allowlisting, Settings inspection, report copying, and clearing.
17
+ - Automated type checking, tests, package verification, CI, and npm release preparation.
18
+
19
+ ### Known limitations
20
+
21
+ - Plain HTTP on the LAN.
22
+ - Existing WebSockets are not actively closed on revoke.
23
+ - Compatibility is currently pinned to DeepSeek Harness `0.1.1-rc.2`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-local-link contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,180 @@
1
+ # dsh-local-link
2
+
3
+ [![CI](https://github.com/DoNotEatMe/dsh-local-link/actions/workflows/ci.yml/badge.svg)](https://github.com/DoNotEatMe/dsh-local-link/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/dsh-local-link.svg)](https://www.npmjs.com/package/dsh-local-link)
5
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+
7
+ Lightweight local-network access to the complete [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web interface.
8
+
9
+ Open `Local access`, scan one QR code, and continue the desktop's currently selected Harness session from a phone, tablet, or another computer on the same private network. There is no hosted relay, tunnel provider, native application, account, replacement chat UI, or second workspace picker.
10
+
11
+ > **Preview security boundary:** the `0.1.x` gateway uses plain HTTP and is intended only for a trusted private network. Do not expose its port to the internet or use it on public Wi-Fi.
12
+
13
+ ## Install
14
+
15
+ ### npm — recommended
16
+
17
+ Stop a running `dsh web` process, install the plugin into the Web profile, then start Harness again:
18
+
19
+ ```shell
20
+ dsh plugin --profile web add dsh-local-link
21
+ dsh web
22
+ ```
23
+
24
+ This command becomes installable with the first public npm release. Until then, use the source checkout below.
25
+
26
+ ### Git clone — development checkout
27
+
28
+ Requirements: Git, Node.js 22.19+ or 24+, Corepack, and a global `dsh` installation running DeepSeek Harness `0.1.1-rc.2`.
29
+
30
+ ```shell
31
+ git clone https://github.com/DoNotEatMe/dsh-local-link.git
32
+ cd dsh-local-link
33
+ corepack pnpm install --frozen-lockfile
34
+ npm run verify
35
+ dsh plugin --profile web add .
36
+ dsh web
37
+ ```
38
+
39
+ The profile points at the checkout, so rebuild after changing client code and restart `dsh web` after Host-side changes.
40
+
41
+ ## Use
42
+
43
+ ### Open Harness on another device
44
+
45
+ 1. Open the session you want on the computer.
46
+ 2. Click `Local access` at the bottom of the Harness sidebar.
47
+ 3. Scan the QR code or copy the one-time link to another device on the same network.
48
+ 4. The first browser to use the invitation opens the full Harness UI at the selected session.
49
+
50
+ The invitation is one-use, expires after five minutes by default, and is replaced immediately when `Generate another code` is selected.
51
+
52
+ <p align="center">
53
+ <img src="docs/images/local-access-qr.jpg" width="960" alt="DeepSeek Harness with the Local access QR panel, one-time link, and Paired devices shortcut">
54
+ </p>
55
+
56
+ ### Manage trusted browsers
57
+
58
+ Use `Paired devices` in the QR panel or open `Settings → Local access`. Each new browser starts as `My device`; its subtitle is detected automatically, for example `Phone · Chrome`, `Tablet · Safari`, or `Computer · Edge`.
59
+
60
+ - `Rename` changes display metadata only.
61
+ - `Revoke` invalidates the browser credential for subsequent HTTP requests and reconnects.
62
+ - A cleared cookie, private window, new browser profile, or revoked device needs a new invitation.
63
+
64
+ Browsers do not reliably distinguish laptops from desktop computers, so both are shown as `Computer`.
65
+
66
+ <p align="center">
67
+ <img src="docs/images/local-access-devices.jpg" width="960" alt="DeepSeek Harness Settings opened directly on the compact Local access paired-device list">
68
+ </p>
69
+
70
+ Expand `Diagnostics` on the same Settings page to inspect the most recent local gateway events. `Copy report` produces issue-ready JSON and `Clear` removes the local history. The report contains event codes, timestamps, severity, and a small allowlisted context only; it never includes pairing tokens, cookies, IP addresses, device or session IDs, device names, request paths, prompts, conversations, or project files.
71
+
72
+ <p align="center">
73
+ <img src="docs/images/local-access-diagnostics.jpg" width="960" alt="DeepSeek Harness Local access settings with the native-style Diagnostics panel expanded">
74
+ </p>
75
+
76
+ ## Why it stays small
77
+
78
+ - **Stock Harness UI:** the plugin opens the existing Web client and live agent stream.
79
+ - **Local only:** one private-network gateway forwards to the loopback Harness Host.
80
+ - **Two runtime dependencies:** configuration schema support and QR generation.
81
+ - **No fingerprinting:** access is a random per-browser credential, not a device identity guess.
82
+ - **Native extension points:** sidebar and Settings content use Harness slots and locale services.
83
+ - **JSON localization:** all visible plugin copy lives in matching locale dictionaries.
84
+ - **Local diagnostics:** a bounded, redacted event history helps debug installs without analytics or an external collector.
85
+
86
+ ## How it works
87
+
88
+ ```text
89
+ Desktop browser on 127.0.0.1:3080
90
+ └─ Local access → one-use invitation
91
+ │
92
+ Phone / tablet / computer on the private LAN
93
+ └─ 192.168.x.x:3088 → network + Host validation
94
+ → pairing or device-cookie validation
95
+ → HTTP / WebSocket proxy
96
+ → 127.0.0.1:3080 (the same Harness Host)
97
+ ```
98
+
99
+ The gateway does not create a second Harness session. During first connection it transfers the desktop browser's current session selection to the new browser origin; session data and ongoing conversation events still come from the same Host.
100
+
101
+ Authorization uses a 256-bit random cookie credential. Only its SHA-256 hash is stored. The editable name and detected device/browser text never grant access.
102
+
103
+ ## Configuration
104
+
105
+ The bundled profile patch installs conservative defaults:
106
+
107
+ | Option | Default | Purpose |
108
+ | --- | --- | --- |
109
+ | `listenHost` | `0.0.0.0` | Listen on local interfaces; request validation still accepts only private/loopback sources. |
110
+ | `listenPort` | `3088` | LAN gateway port. |
111
+ | `upstreamOrigin` | `http://127.0.0.1:3080` | Existing loopback Harness Web server. |
112
+ | `accessMode` | `pairing` | Require a one-use invitation and device cookie. |
113
+ | `pairingTtlSeconds` | `300` | Invitation lifetime. |
114
+ | `deviceTtlDays` | `90` | Remembered-browser lifetime. |
115
+ | `diagnosticsEnabled` | `true` | Keep the bounded local diagnostic history. |
116
+ | `diagnosticsMaxEntries` | `15` | Maximum retained events (`5`–`200`). |
117
+ | `diagnosticsFile` | next to `stateFile` | Local JSON event store; the bundled profile uses `~/.dsh/local-link/diagnostics.json`. |
118
+
119
+ `trusted-lan` disables per-device authorization and should be reserved for isolated development networks. `pairing` is the supported default because a connected Harness browser can read files, submit prompts, approve actions, and trigger commands.
120
+
121
+ The plugin never creates firewall rules. If Windows prompts for network access, allow only the **Private** network profile and never forward port `3088` on the router.
122
+
123
+ ## Troubleshooting and diagnostics
124
+
125
+ Diagnostics are a local, event-driven history of failures—not a request log. The plugin retains 15 events by default, shows the newest 12, coalesces identical five-second bursts, and records nothing for successful starts, requests, pairing, copies, renames, or revocations.
126
+
127
+ For support:
128
+
129
+ 1. Reproduce the failed action once.
130
+ 2. Open `Settings → Local access → Diagnostics`.
131
+ 3. Click `Refresh` if the panel was already open.
132
+ 4. Use the newest stable event code to identify the failed boundary.
133
+ 5. Click `Copy report`, review the JSON, and attach it to an issue if needed.
134
+
135
+ The report never includes secrets, addresses, IDs, names, URLs, paths, prompts, conversations, or project data and is never uploaded automatically. See the [event reference and first checks](docs/DIAGNOSTICS.md) for every tracked failure.
136
+
137
+ ## Localization
138
+
139
+ Harness's active language selects the plugin dictionary; the plugin has no separate language switch.
140
+
141
+ | Language | Dictionary | Status |
142
+ | --- | --- | --- |
143
+ | English | `src/locales/en.json` | Included |
144
+ | Chinese | `src/locales/zh.json` | Included |
145
+
146
+ Dictionary keys are checked for parity in tests. To add a locale, copy `en.json`, translate values without changing keys, register the locale ID in `src/client.tsx`, and run `npm test`.
147
+
148
+ ## Development
149
+
150
+ ```shell
151
+ corepack pnpm install --frozen-lockfile
152
+ npm run typecheck
153
+ npm test
154
+ npm run build
155
+ npm run verify
156
+ ```
157
+
158
+ Project documentation:
159
+
160
+ - [Architecture and compatibility boundaries](docs/ARCHITECTURE.md)
161
+ - [Local diagnostics and event codes](docs/DIAGNOSTICS.md)
162
+ - [Security model](docs/SECURITY.md)
163
+ - [Contributing](CONTRIBUTING.md)
164
+ - [Security reporting](SECURITY.md)
165
+
166
+ ## Known limitations
167
+
168
+ - LAN traffic is not encrypted in `0.1.x`.
169
+ - Revocation blocks new requests and reconnects but does not yet terminate an already-open WebSocket.
170
+ - The shortcut that opens a specific Settings section uses a small semantic compatibility bridge because Harness `0.1.1-rc.2` exposes `openSection` only to onboarding.
171
+ - Harness's footer-action container needs a compatibility layout rule when the full-width Cordis action is present.
172
+ - Compatibility is currently pinned to DeepSeek Harness `0.1.1-rc.2` and must be retested for each supported Harness release.
173
+
174
+ ## Development disclosure
175
+
176
+ The initial implementation and documentation were developed collaboratively with OpenAI Codex. Changes remain subject to maintainer review, automated tests, security review, and the same contribution requirements as human-authored changes. No runtime AI service, telemetry, or generated-code dependency is included in the package.
177
+
178
+ ## License
179
+
180
+ [MIT](LICENSE) © 2026 dsh-local-link contributors.
package/SECURITY.md ADDED
@@ -0,0 +1,7 @@
1
+ # Security policy
2
+
3
+ `dsh-local-link` controls access to an agent capable of reading files and executing commands. Please do not publish exploit details in a GitHub issue.
4
+
5
+ Until a private reporting address is configured, open a GitHub Security Advisory in the repository. Include the affected version, deployment topology, reproduction steps, and expected impact.
6
+
7
+ The current preview uses unencrypted HTTP on the local network. This is a documented limitation rather than a supported internet-facing deployment. See [docs/SECURITY.md](docs/SECURITY.md) for the complete threat model and safe-use boundary.
@@ -0,0 +1,17 @@
1
+ # Adds one Host gateway and one Web client settings page without replacing any
2
+ # stock DeepSeek Harness module.
3
+ - insert:
4
+ - id: dsh-local-link
5
+ name: dsh-local-link
6
+ inject: [webServer]
7
+ config:
8
+ listenHost: 0.0.0.0
9
+ listenPort: 3088
10
+ upstreamOrigin: http://127.0.0.1:3080
11
+ accessMode: pairing
12
+ pairingTtlSeconds: 300
13
+ deviceTtlDays: 90
14
+ diagnosticsEnabled: true
15
+ diagnosticsMaxEntries: 15
16
+ diagnosticsFile: !!js dshHomePath('local-link/diagnostics.json')
17
+ stateFile: !!js dshHomePath('local-link/devices.json')
@@ -0,0 +1,135 @@
1
+ # Architecture
2
+
3
+ ## Goals
4
+
5
+ `dsh-local-link` provides one narrow capability: open the existing DeepSeek Harness Web application from a browser on the same private network. The plugin should remain easy to audit, translate, install, and remove.
6
+
7
+ The architecture follows six constraints:
8
+
9
+ 1. Keep the stock Harness listener loopback-only.
10
+ 2. Put the network boundary in a dedicated Host-side gateway.
11
+ 3. Use Cordis lifecycle and Harness slots for all rendered UI; isolate the one settings-navigation compatibility bridge required by Harness `0.1.1-rc.2`.
12
+ 4. Make automatic QR pairing and paired-device state explicit and revocable.
13
+ 5. Keep presentation text outside implementation code.
14
+ 6. Keep support diagnostics local, bounded, structured, and free of credentials or user content.
15
+
16
+ ## Components
17
+
18
+ ### Host plugin
19
+
20
+ `src/plugin.ts` owns lifecycle integration. It starts the gateway, registers a loopback-only administration route on the existing Harness Web server, and closes both registrations with the Cordis effect.
21
+
22
+ ### LAN gateway
23
+
24
+ `src/gateway/local-gateway.ts` owns the only non-loopback listener. It performs request-boundary validation, pairing, device-cookie authorization, and HTTP/WebSocket proxying.
25
+
26
+ The gateway changes upstream `Host`, `Origin`, and fetch-site headers to the loopback Harness origin. This is safe only after the gateway has authenticated the device. It lets Harness retain its own loopback request fence rather than configuring the primary server for every LAN address.
27
+
28
+ ### Authentication state
29
+
30
+ `src/auth/pairing.ts` keeps short-lived, one-use pairing tokens in memory. They disappear on restart and are never persisted.
31
+
32
+ `src/auth/device-store.ts` persists device records atomically. A browser receives a 256-bit random credential; the file stores only its SHA-256 hash. Revocation deletes the corresponding record, which immediately invalidates future HTTP requests and WebSocket upgrades.
33
+
34
+ ### Diagnostics
35
+
36
+ `src/diagnostics.ts` persists a versioned ring of structured failure events. The default cap is 15 entries. Successful starts, requests, pairing, renames, revocations, and button clicks do not enter the ring. Context fields pass through a fixed allowlist; arbitrary objects and sensitive identifiers cannot enter the report even if a future call site tries to add them. Writes are atomic and deliberately fail soft so a diagnostics filesystem problem cannot take down local access.
37
+
38
+ The loopback administration route exposes list, clear, and a narrow allowlisted client-error endpoint only to the desktop UI. The endpoint accepts stable codes for clipboard, rename, and revoke failures; it cannot accept arbitrary messages or context. Nothing is uploaded, and the LAN gateway blocks the administration prefix. The Settings report includes timestamps, severity, stable event codes, and short operational categories—not tokens, cookies, IP addresses, device or session IDs, names, URLs, request paths, prompts, conversations, or project data.
39
+
40
+ ### Client plugin
41
+
42
+ `src/client.tsx` registers two normal Harness contributions: a compact desktop `sidebar.footer.action` that shows a QR code and copyable one-time link, and a desktop-only `settings.section` that manages paired devices and the local diagnostic report. It does not replace the root layout or mutate generated CSS-module class names.
43
+
44
+ The Harness `sidebar.footer.action` contract is a list, but `0.1.1-rc.2` renders that list as a horizontal flex row while the stock Cordis action reserves `width: 100%` with `flex: none`. Without a compatibility rule, Cordis reduces later actions to zero width. Local Link orders its entry first and changes only the footer container that semantically contains `.dsh-local-link-footer` into a vertical stack. The same scoped rule normalizes the list gap and removes the following action's private top margin so Local access, Cordis, and Settings keep one visual rhythm. The selector is anchored on the plugin-owned class and accounts for the slot renderer's `display: contents` wrapper; it never names a generated Harness class.
45
+
46
+ The connection card is fixed to the viewport and positioned from the rendered Local access action. On desktop it opens just beyond the sidebar edge and remains vertically centered. Its final QR-state height is reserved before the pairing request resolves, so loading the QR cannot move the card after its first visible frame. On narrow or short viewports it is clamped to a 12 px viewport gutter and scrolls internally instead of moving footer actions or covering them.
47
+
48
+ Harness `0.1.1-rc.2` keeps settings open state and section selection private inside its shell; the public `openSection` callback is only projected to onboarding steps. The popover's `Paired devices` shortcut therefore uses one bounded compatibility bridge: it clicks the semantic settings dialog trigger and then the nav row matching this plugin's own localized section label. The bridge uses no generated class names, mutates no DOM, and can be removed when Harness exposes a general settings-navigation service.
49
+
50
+ On an authenticated gateway page, the client contributes the trust hint required by the Harness client connection. The proxied index makes the Settings package depend on this contribution so configuration surfaces do not initialize against the unauthenticated page classification.
51
+
52
+ Plain HTTP on a private IP is not a browser secure context, while the stock Harness RPC client calls `crypto.randomUUID()` during connection startup. The rewritten index therefore installs a small RFC 4122 v4 fallback backed by `crypto.getRandomValues()` before the stock boot manifest executes. This avoids certificate installation while keeping the LAN-only setup functional.
53
+
54
+ ### Localization
55
+
56
+ JSON dictionaries under `src/locales/` are registered with Harness `LocaleRuntime`. The slot declares its locale namespace and receives the framework translation function. The application locale remains the single source of truth.
57
+
58
+ English and Chinese dictionaries intentionally contain the same key set. `tests/locales.test.ts` makes this a release invariant. Adding a language means adding one matching dictionary and registering that locale ID in `src/client.tsx`; component code remains unchanged.
59
+
60
+ ## Stable UI contract
61
+
62
+ - Opening the sidebar panel issues one invitation represented by the same QR code and copyable link.
63
+ - The client shows the server-issued expiry countdown; generating another code invalidates the previous invitation before replacing it.
64
+ - While the panel is open, its loopback-only status check closes the invitation UI as soon as the Host reports that the token was consumed.
65
+ - Pairing is automatic and opens the desktop-selected session.
66
+ - The settings surface owns device visibility, display-name editing, revocation, and the bounded local diagnostic report.
67
+ - Listener address, access mode, and retention remain configuration, not separate end-user controls; the reachable address is already part of the one-time link.
68
+
69
+ This boundary keeps connection setup in one place and persistent access management in one place without turning the plugin into a network-control dashboard.
70
+
71
+ ### Diagnostic event flow
72
+
73
+ 1. A failed user action, rejected request, or broken proxy boundary emits a stable `warn` or `error` code. Successful operations emit nothing.
74
+ 2. `DiagnosticStore` discards every context key outside `reason`, `method`, and `requestKind`, coalesces identical five-second bursts, retains at most 15 events by default, and persists atomically.
75
+ 3. The desktop-only administration route returns newest-first events. Opening Local access reads it once; only the explicit `Refresh` action reads it again.
76
+ 4. Settings renders the newest 12 events and can copy all retained events as an issue report or clear the store. No diagnostics timer, background upload, analytics SDK, or remote endpoint exists.
77
+
78
+ ## Request flows
79
+
80
+ ### Pairing
81
+
82
+ 1. The desktop sidebar action reads Harness's current session selection and requests a one-time token from the loopback administration route. Issuing it clears any older unconsumed invitation.
83
+ 2. The Host builds a LAN URL containing the token and current session in the fragment, then renders the same URL as a QR data URL. Neither value reaches the initial HTTP request.
84
+ 3. The phone opens a minimal automatic connection page. The secret remains in the URL fragment and is not sent in the initial HTTP request.
85
+ 4. The page immediately POSTs the token with a coarse device category and browser name; there is no confirmation form and no fingerprinting.
86
+ 5. The gateway consumes the token, stores a credential hash, and sets the browser cookie.
87
+ 6. The desktop's loopback-only status check observes the consumed token and closes the QR panel.
88
+ 7. Before booting Harness, the page writes the selected session into Harness's own `dsh.sessions.current` persisted-selection cell for the LAN browser origin.
89
+ 8. The browser redirects to the complete stock Harness root. Harness loads the shared server-side session list and opens the transferred current conversation, whose ordinary WebSocket stream shows live agent activity.
90
+
91
+ ### Normal request
92
+
93
+ 1. Reject requests not originating from a private or loopback address.
94
+ 2. Reject a `Host` that is not one of the machine's current private IP literals and configured port.
95
+ 3. Reject the gateway administration prefix.
96
+ 4. Validate the paired-device cookie unless `trusted-lan` was explicitly configured.
97
+ 5. Proxy to the loopback Harness listener.
98
+
99
+ ### WebSocket upgrade
100
+
101
+ The same network, Host, and credential checks run before the upgrade is passed to the upstream server. Revocation affects new connections; a future milestone will actively close already-open sockets for a revoked device.
102
+
103
+ ## Dependency policy
104
+
105
+ Runtime dependencies are intentionally limited:
106
+
107
+ - `@deepseek-ai/schemastery`: Cordis-compatible configuration schema.
108
+ - `qrcode`: QR rendering for the desktop sidebar panel.
109
+
110
+ HTTP forwarding and the two Harness event WebSocket tunnels use Node's built-in `node:http` and `node:net` modules. No general-purpose proxy package is shipped.
111
+
112
+ No service discovery, certificate generator, tunnel client, native application, analytics SDK, remote log collector, or extension runtime is included.
113
+
114
+ ## Compatibility strategy
115
+
116
+ The plugin targets DeepSeek Harness `0.1.1-rc.2`. Most integration uses declared package contracts, but three adapters are intentionally version-sensitive:
117
+
118
+ | Adapter | Why it exists | Failure behavior | Removal condition |
119
+ | --- | --- | --- | --- |
120
+ | Boot-manifest dependency adjustment | Authenticated non-loopback pages must load the Local Link trust hint before Settings initializes. | Fails closed when the expected plugin or Settings entry is absent. | Harness exposes a supported authenticated-gateway boot contract. |
121
+ | Settings navigation bridge | The shell keeps `openSection` private outside onboarding. | The shortcut does nothing; ordinary `Settings → Local access` remains available. | Harness exposes general settings navigation. |
122
+ | Footer stack rule | Cordis reserves a full-width cell inside a horizontal list container. | Without it, Local access has zero width while Cordis is mounted. | Harness stacks full-width footer actions or gives entries an explicit layout contract. |
123
+
124
+ The manifest transformation has direct tests. The two presentation adapters are verified during browser acceptance against the supported Harness build; release screenshots are also taken from that real composition with Cordis mounted.
125
+
126
+ ## Known pressure points
127
+
128
+ - **Plain HTTP:** avoids certificate onboarding but offers no confidentiality from other machines able to capture LAN traffic.
129
+ - **Socket revocation:** the credential is checked before an upgrade; an already-upgraded socket survives until it disconnects or Harness restarts.
130
+ - **Browser metadata:** category and browser are coarse display hints supplied during pairing, not trusted identity. Laptop versus desktop is intentionally reported as `Computer`.
131
+ - **Interface selection:** the first private IPv4 address is used in invitations. Multi-interface selection is not exposed yet.
132
+ - **Harness upgrades:** boot graph names, shell semantics, or client connection assumptions may change even when TypeScript package contracts still compile.
133
+ - **Process lifecycle:** Host-side updates require a Harness restart. Client artifacts may be read from disk on reload, which can temporarily create a mixed-version UI; compatibility normalization prevents old device records from rendering blank.
134
+
135
+ These are documented constraints, not hidden fallback modes. Release readiness requires the automated gate plus a real browser check of pairing, live conversation streaming, Cordis coexistence, settings navigation, rename, and revoke.
@@ -0,0 +1,100 @@
1
+ # Diagnostics
2
+
3
+ `dsh-local-link` keeps a small local history of failed connection and UI actions. It exists so an npm installation can be debugged without enabling verbose logs or reproducing the problem under a debugger. It is not telemetry and has no upload path.
4
+
5
+ ## What is recorded
6
+
7
+ An event is created only when an operation fails or a request is rejected:
8
+
9
+ - generating a one-time connection code;
10
+ - consuming an expired, replaced, reused, or malformed invitation;
11
+ - opening the gateway from an unpaired browser or an invalid network/Host boundary;
12
+ - reaching the loopback Harness HTTP server or event WebSocket;
13
+ - rewriting the authenticated Harness index;
14
+ - copying the one-time link;
15
+ - renaming or revoking a paired device;
16
+ - recovering an unreadable diagnostics file.
17
+
18
+ Successful starts, requests, pairing, link copies, renames, revocations, and ordinary UI clicks are never recorded. Diagnostics are event-driven: there is no sampling loop, heartbeat, analytics client, or remote collector.
19
+
20
+ The QR popover separately checks every two seconds whether its visible one-time invitation has been consumed. That short-lived status check runs only while the popover is open and neither reads nor writes diagnostics.
21
+
22
+ ## Retention and I/O
23
+
24
+ - Default file: `~/.dsh/local-link/diagnostics.json`.
25
+ - Default retention: the latest 15 events; configurable from 5 through 200.
26
+ - Settings view: the latest 12 events.
27
+ - Repeated identical events inside a five-second burst are stored once.
28
+ - Opening `Settings → Local access` reads the report once. `Refresh` is the only repeated UI read.
29
+ - The file is written only for a retained failure, an explicit clear, or migration away from unreadable/obsolete entries.
30
+ - Writes use an atomic temporary-file replacement and fail soft; diagnostics cannot take down pairing or proxy traffic.
31
+
32
+ Set `diagnosticsEnabled: false` to stop retaining new events. `Clear` immediately removes the retained history.
33
+
34
+ ## Privacy contract
35
+
36
+ Every event contains only:
37
+
38
+ - a random event ID;
39
+ - an ISO timestamp;
40
+ - `warn` or `error` severity;
41
+ - a stable event code;
42
+ - optional context restricted to `reason`, `method`, and `requestKind`.
43
+
44
+ Context strings are stripped of control characters and limited to 80 characters. The store rejects unknown event codes and removes obsolete or malformed entries when it loads.
45
+
46
+ Reports never contain pairing tokens, cookies, credentials, IP addresses, device or session IDs, device names, URLs, request paths, exception messages, stack traces, prompts, conversations, workspace names, or project files. Client-side reporting accepts only three fixed error codes and cannot submit arbitrary text.
47
+
48
+ ## Collect a report
49
+
50
+ 1. Reproduce the failed action once.
51
+ 2. Open `Settings → Local access → Diagnostics`.
52
+ 3. Click `Refresh` if the panel was already open during reproduction.
53
+ 4. Inspect the newest code and timestamp.
54
+ 5. Click `Copy report`.
55
+ 6. Review the JSON before attaching it to an issue.
56
+
57
+ The copied report wraps the retained events with a schema version and export timestamp:
58
+
59
+ ```json
60
+ {
61
+ "schemaVersion": 1,
62
+ "exportedAt": "2026-08-28T00:00:00.000Z",
63
+ "events": [
64
+ {
65
+ "id": "generated-event-id",
66
+ "at": "2026-08-28T00:00:00.000Z",
67
+ "level": "error",
68
+ "code": "HTTP_UPSTREAM_ERROR",
69
+ "context": { "requestKind": "root" }
70
+ }
71
+ ]
72
+ }
73
+ ```
74
+
75
+ ## Event reference
76
+
77
+ | Code | Trigger | First check |
78
+ | --- | --- | --- |
79
+ | `PAIRING_GENERATION_FAILED` | `Generate another code` could not produce an invitation or QR image. | Confirm the desktop Harness process is healthy, then retry once. |
80
+ | `PAIRING_REJECTED` | The invitation was expired, replaced, or already consumed. | Generate a new code; each invitation is one-use. |
81
+ | `PAIRING_INVALID` | The phone submitted malformed pairing data or device state could not be saved. | Generate a new code; if it repeats, inspect file permissions for `~/.dsh/local-link/`. |
82
+ | `REQUEST_REJECTED` | Source-address or `Host` validation rejected the LAN request. | Confirm both devices use the same private network and the QR URL contains the computer's current private address. |
83
+ | `AUTH_REQUIRED` | An unpaired browser opened a protected gateway page. | Pair that browser with a fresh QR/link; direct `:3088` access is intentionally rejected. |
84
+ | `HTTP_UPSTREAM_ERROR` | The gateway could not reach Harness on `127.0.0.1:3080`. | Confirm `dsh web` is running and `upstreamOrigin` matches its port. |
85
+ | `INDEX_REWRITE_ERROR` | The returned Harness index did not match the supported boot contract. | Confirm the installed Harness version is supported; currently `0.1.1-rc.2`. |
86
+ | `WS_REJECTED` | A WebSocket upgrade failed trust, authorization, or path validation. | Re-pair the browser and verify no proxy rewrites the URL. |
87
+ | `WS_UPSTREAM_ERROR` | The gateway could not open the loopback Harness event socket. | Confirm the desktop Harness process is still running and reload the paired browser. |
88
+ | `CLIPBOARD_COPY_FAILED` | The browser refused or failed to copy the one-time link. | Grant clipboard permission or select and copy the displayed link manually. |
89
+ | `DEVICE_REVOKE_FAILED` | A requested device revocation failed. | Refresh the device list and retry; inspect local state-file permissions if it repeats. |
90
+ | `DEVICE_RENAME_FAILED` | A requested device rename failed. | Refresh the device list and retry with a non-empty name. |
91
+ | `DIAGNOSTICS_STATE_RESET` | The previous diagnostics file was unreadable and was replaced safely. | Usually no action; inspect disk health or permissions if it returns. |
92
+
93
+ ## Maintainer rules
94
+
95
+ - Record failures and rejections only; do not add success or lifecycle noise.
96
+ - Add a stable code instead of persisting exception messages.
97
+ - Add context only through `SAFE_CONTEXT_KEYS` in `src/diagnostics.ts`.
98
+ - Never add request headers, URLs, filesystem paths, identifiers, user-entered text, or user content.
99
+ - A diagnostics write failure must never block pairing or proxy traffic.
100
+ - Update this reference and the privacy/retention tests whenever an event changes.
@@ -0,0 +1,64 @@
1
+ # Security model
2
+
3
+ ## Intended deployment
4
+
5
+ - Harness remains on `127.0.0.1:3080`.
6
+ - The local-access gateway listens on a private LAN interface through `0.0.0.0:3088`.
7
+ - The operating-system firewall limits the listener to private networks.
8
+ - The router does not forward the port to the internet.
9
+
10
+ ## Protected assets
11
+
12
+ A connected Harness browser may read project data, submit prompts, approve actions, and trigger commands. A gateway credential therefore grants powerful access to the current Harness instance.
13
+
14
+ ## Implemented controls
15
+
16
+ - Source-address classification for loopback, RFC1918 IPv4, link-local IPv4, IPv6 ULA, and IPv6 link-local ranges.
17
+ - IP-literal Host allowlist derived from current private interfaces.
18
+ - One-use, expiring pairing tokens.
19
+ - 256-bit device credentials.
20
+ - Hashed credentials at rest.
21
+ - `HttpOnly` and `SameSite=Strict` device cookie.
22
+ - Device expiry and explicit revocation.
23
+ - Authentication before HTTP proxying and WebSocket upgrade.
24
+ - Gateway-side block for desktop administration paths.
25
+ - Bounded local diagnostics with an explicit context allowlist and no credentials, addresses, identifiers, names, paths, or user content.
26
+ - No external relay, telemetry, analytics, or remote log collector.
27
+
28
+ ## Diagnostic data
29
+
30
+ Diagnostics are enabled by default because a local networking plugin otherwise becomes difficult to support after publication. They remain on the Harness computer in `~/.dsh/local-link/diagnostics.json` unless configured otherwise. The default ring retains only the latest 15 failures; successful operations are not recorded. The desktop Settings page is the only UI/API surface for reading, copying, and clearing them.
31
+
32
+ The report is designed to be safe to review and attach to a public bug report, but users should still inspect copied JSON before sharing it. Disabling `diagnosticsEnabled` prevents new events from being retained.
33
+
34
+ ## Known limitations of the preview
35
+
36
+ ### Plain HTTP
37
+
38
+ The initial release does not encrypt LAN traffic. Pairing credentials and Harness traffic can be observed by an attacker who can capture traffic on the local network. Use only on a trusted home network while HTTPS support is under development.
39
+
40
+ ### Existing WebSockets
41
+
42
+ Revoking a device blocks subsequent requests and reconnects, but an already-upgraded WebSocket is not actively terminated yet. Restart the Harness Web process to close every active connection immediately.
43
+
44
+ ### Version-sensitive Harness integration
45
+
46
+ Authenticated LAN boot, direct Settings navigation, and coexistence with the stock Cordis footer action currently need small compatibility adapters for Harness `0.1.1-rc.2`. They do not expand network authority, but a Harness upgrade can break presentation or fail closed. Before declaring another Harness version supported, manually retest pairing, live conversation streaming, Settings navigation, rename, revoke, and coexistence with Cordis.
47
+
48
+ ### Firewall automation
49
+
50
+ The plugin does not change Windows Firewall. This avoids surprising system-wide changes, but installation documentation must tell the operator to scope any manual rule to Private networks and the selected port.
51
+
52
+ ### Compromised paired device
53
+
54
+ Pairing establishes device possession, not user identity. Anyone controlling a paired browser profile inherits its access until the device is revoked or expires.
55
+
56
+ ## Non-goals
57
+
58
+ - Internet exposure.
59
+ - Multi-user accounts or workspace isolation.
60
+ - Authorization inside a Harness session.
61
+ - Protection against malware already executing as the desktop user.
62
+ - A replacement for TLS, VPN access control, or operating-system firewall policy.
63
+
64
+ Please report vulnerabilities privately rather than opening a public issue with exploit details.
Binary file