dsh-zen-remote 2.3.5 → 2.3.7

package/src/client-routes.ts

@@ -25,10 +25,13 @@
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { homedir } from 'node:os'
 import type { AdminAdmission } from './admin-routes.js'
 import { classifyClaimResponse, classifyProbe, CLAIM_PATH, normalizeServerUrl, RELAY_PING_PATH } from './client-pairing.js'
 import type { ClaimOutcome, ProbeState } from './client-pairing.js'
-import { unwrapVolatile } from './config.js'
+import { readFileConfig, resolveConfig, unwrapVolatile } from './config.js'
+import { assembleDebugReport } from './debug-report.js'
+import type { LogRingEntry } from './log-ring.js'
 import type { FetchRouteInterceptDiagnostics } from './fetch-route-intercept.js'
 import type { CurrentSessionRead, InterceptDiagnostics } from './intercept.js'
 import type { PluginRouteInterceptDiagnostics } from './plugin-route-intercept.js'
@@ -37,6 +40,7 @@ import type { BridgeStatus } from './plugin-bridge.js'
 import { RELAY_HTTP_ROUTES } from './relay-access.js'
 import { relayCredentialsDigest, RelayError } from './relay-client.js'
 import type { RelayClient, RelayHttpResult } from './relay-client.js'
+import { resolveDshVersion } from './relay-server.js'
 import { fromVirtual } from './virtual-id.js'
 
 /** Prefix all client routes live under (one webServer prefix registration). */
@@ -80,6 +84,15 @@ export const CLIENT_NETWORK_HINT_ROUTE = `${CLIENT_ROUTE_PREFIX}/network-hint`
  * closed:{}}` conclusion. It carries no token and no server address. */
 export const CLIENT_REMOTE_STATUS_ROUTE = `${CLIENT_ROUTE_PREFIX}/remote-status`
 
+/** GET: the redacted diagnostic report (CU-3, SPEC 方案 C) — `_meta`,
+ * `config`, `status`, optional `gateway`, `logs` plates, assembled by
+ * {@link assembleDebugReport} and safe to paste into a GitHub issue. Mounted
+ * on BOTH roles (each answers its own report); a request that arrived
+ * through the gateway is refused BEFORE dispatch (the wizard's via wall) —
+ * diagnostics are a machine-local export, and the gateway must never be able
+ * to fetch this machine's report for its own device table either. */
+export const CLIENT_DEBUG_REPORT_ROUTE = `${CLIENT_ROUTE_PREFIX}/debug-report`
+
 /** POST `{sessionId: <虚拟 id>}`: close one remote session from THIS machine
  * (T34) — the backend forwards the ORIGINAL id through the relay's
  * `POST relay/v1/unshare`, so the server closes it with reason `'client'`. */
@@ -172,6 +185,20 @@ export interface ClientHandlerOptions {
    * a client handler WITHOUT the sink answers the same 404 (no sink, no
    * route). */
   onCurrentSession?: (read: CurrentSessionRead) => void
+  /** CU-3, the debug-report route's inputs — all optional; the route answers
+   * its 404-shaped refusal without them (an unwired composition must not
+   * pretend to have diagnostics). Wired on BOTH role mounts.
+   *
+   * The log ring's snapshot (CU-1), oldest first. */
+  getLogSnapshot?: () => readonly LogRingEntry[]
+  /** The gateway child's summary plate (HOST mount only): liveness, port,
+   * device and share counts — counts, never tokens. May be async (it probes
+   * the gateway's own status). */
+  getGatewaySummary?: () => Record<string, unknown> | Promise<Record<string, unknown>>
+  /** The profile context's display name, when the composition has one. */
+  getProfileName?: () => string | undefined
+  /** This package's own version, read at module load in src/index.ts. */
+  getPluginVersion?: () => string
 }
 
 export type ClientHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>
@@ -396,6 +423,103 @@ function remoteStatusStateOf(relay: RelayClient | undefined): 'online' | 'offlin
   }
 }
 
+/**
+ * The status route's body, computed exactly as the CLIENT_STATUS_ROUTE
+ * branch always has — extracted (CU-3) so the debug-report route can embed
+ * the same diagnostics aggregation without a second implementation. All
+ * reads are live per call: volatile row fields, the interception getters,
+ * the relay client's current state. May await one bounded probe or connect
+ * (never longer than the probe timeout).
+ */
+async function statusBodyOf(options: ClientHandlerOptions): Promise<Record<string, unknown>> {
+  const fetchImpl: FetchLike = options.fetchImpl ?? ((url, init) => fetch(url, init))
+  // The typert interception's view (T23b-1) rides on EVERY status
+  // answer, whatever the connection state — the settings surface needs
+  // it to explain a refused install even while unpaired. The interface
+  // compat verdict (T42) appears once there is something to report: a
+  // stored comparison from the relay client's last handshake, or any
+  // incompatible call the interceptor recorded. Absent otherwise —
+  // nothing to show, and the settings block presence-gates on exactly
+  // that.
+  const intercept = options.getIntercept?.()
+  const fetchRouteIntercept = options.getFetchRouteIntercept?.()
+  const serviceProbe = options.getServiceProbe?.()
+  const pluginRouteIntercept = options.getPluginRouteIntercept?.()
+  const compatRelay = options.getRelayClient?.()
+  const compat =
+    compatRelay?.compat !== undefined || (intercept?.incompatibleCalls.length ?? 0) > 0
+      ? {
+          identical: compatRelay?.compat?.identical ?? [],
+          different: compatRelay?.compat?.different ?? [],
+          unavailable: compatRelay?.compat?.unavailable ?? [],
+          incompatibleCalls: intercept?.incompatibleCalls ?? [],
+        }
+      : undefined
+  const withDiagnostics = (body: Record<string, unknown>): Record<string, unknown> => {
+    // PB-2: the per-plugin bridge verdict rides EVERY status answer —
+    // the settings surface explains a not-bridged plugin whatever the
+    // connection state (unpaired reads all-offline, the honest verdict).
+    let next: Record<string, unknown> = { ...body, pluginBridge: options.getPluginBridgeStatus?.() ?? [] }
+    if (intercept !== undefined) next = { ...next, intercept }
+    if (fetchRouteIntercept !== undefined) next = { ...next, fetchRouteIntercept }
+    if (serviceProbe !== undefined) next = { ...next, serviceProbe }
+    if (pluginRouteIntercept !== undefined) next = { ...next, pluginRouteIntercept }
+    return compat === undefined ? next : { ...next, compat }
+  }
+  // The ROW decides its own two shapes first, per request (both fields
+  // are volatile { get() } wrappers — only the row object apply()
+  // received is a live source): without both credentials nothing is
+  // paired, and a stored address that no longer normalizes must never
+  // see the token (T16-fix).
+  const row = options.getRowConfig()
+  const record = row !== null && typeof row === 'object' && !Array.isArray(row) ? row as Record<string, unknown> : {}
+  const serverUrl = stringOrEmpty(unwrapVolatile(record.serverUrl)).trim()
+  const token = stringOrEmpty(unwrapVolatile(record.deviceToken))
+  if (token === '' || serverUrl === '') {
+    return withDiagnostics({ state: 'unpaired' })
+  }
+  const normalized = normalizeServerUrl(serverUrl)
+  if (!normalized.ok) {
+    return withDiagnostics({ state: 'invalid-url' })
+  }
+  const relay = options.getRelayClient?.()
+  if (relay === undefined) {
+    // T16 shape: no relay client wired — the ping probe is the answer.
+    const state = await probe(fetchImpl, normalized.url, token)
+    return withDiagnostics({ state, serverUrl: normalized.url })
+  }
+  // The cached verdict is trusted only over the EXACT credentials the
+  // handshake earned it with: an online state whose digest no longer
+  // matches the row (address edited, re-pair) is an answer about a
+  // DIFFERENT server and falls through to a live connect instead
+  // (T23a-fix). The token never enters this body — the digest is a
+  // one-way sha256 prefix computed on both sides.
+  if (
+    relay.state === 'online' &&
+    relay.handshakeInfo !== undefined &&
+    relay.lastHandshakeDigest !== undefined &&
+    relay.lastHandshakeDigest === relayCredentialsDigest(normalized.url, token)
+  ) {
+    return withDiagnostics(deviceStatusBody(relay.state, relay.handshakeInfo, normalized.url, relay.deviceNameSyncing))
+  }
+  // Everything else — never connected, offline, connecting, revoked,
+  // stale credentials — gets ONE live connect bounded by the probe
+  // timeout; its FRESH result is the answer, never the possibly stale
+  // cached state. A failed attempt additionally carries the relay
+  // client's reconnect machinery readout (T43): when the next
+  // automatic retry fires and which code failed last — both free of
+  // credential material by contract.
+  try {
+    const info = await withProbeTimeout(relay.connect())
+    return withDiagnostics(deviceStatusBody('online', info, normalized.url, relay.deviceNameSyncing))
+  } catch (error) {
+    const body: Record<string, unknown> = { state: probeStateOfRelayError(error), serverUrl: normalized.url }
+    if (relay.nextRetryAt !== null && relay.nextRetryAt !== undefined) body.nextRetryAt = relay.nextRetryAt
+    if (relay.lastError !== undefined) body.lastError = relay.lastError
+    return withDiagnostics(body)
+  }
+}
+
 /**
  * Build the client route handler for one plugin row. The returned handler
  * owns the full response lifecycle of every request under
@@ -416,10 +540,24 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
     const route = new URL(req.url ?? '/', 'http://dsh.internal').pathname
     const method = req.method ?? 'GET'
     try {
-      // The host mount's least-exposure wall (T41a-fix2): only remote-status
-      // exists here, and it sits BEHIND the admission wall like every other
-      // route. The shape of the refusal matches the unknown-path fallthrough.
-      if (options.remoteStatusOnly === true && route !== CLIENT_REMOTE_STATUS_ROUTE) {
+      // CU-3: the debug-report route's via wall, BEFORE any dispatch (the
+      // wizard's rule): a request wearing the gateway's marker arrived from
+      // a remote device, and a forwarded request presents as same-origin
+      // (the gateway rewrites Origin/Host) — the marker is the only honest
+      // signal. The report is a machine-local export; the gateway must
+      // never be able to fetch this machine's diagnostics either.
+      if (route === CLIENT_DEBUG_REPORT_ROUTE && req.headers['x-zen-remote-via'] !== undefined) {
+        responseJson(res, 403, {
+          ok: false,
+          error: { code: 'via-gateway', message: '诊断报告只能在本机导出' },
+        })
+        return
+      }
+      // The host mount's least-exposure wall (T41a-fix2): remote-status and
+      // the debug report (CU-3, both roles answer their own) exist here,
+      // and both sit BEHIND the admission wall like every other route. The
+      // shape of the refusal matches the unknown-path fallthrough.
+      if (options.remoteStatusOnly === true && route !== CLIENT_REMOTE_STATUS_ROUTE && route !== CLIENT_DEBUG_REPORT_ROUTE) {
         responseJson(res, 404, { ok: false, error: { code: 'not-found', message: 'Unknown client route' } })
         return
       }
@@ -485,95 +623,63 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET' } })
           return
         }
-        // The typert interception's view (T23b-1) rides on EVERY status
-        // answer, whatever the connection state — the settings surface needs
-        // it to explain a refused install even while unpaired. The interface
-        // compat verdict (T42) appears once there is something to report: a
-        // stored comparison from the relay client's last handshake, or any
-        // incompatible call the interceptor recorded. Absent otherwise —
-        // nothing to show, and the settings block presence-gates on exactly
-        // that.
-        const intercept = options.getIntercept?.()
-        const fetchRouteIntercept = options.getFetchRouteIntercept?.()
-        const serviceProbe = options.getServiceProbe?.()
-        const pluginRouteIntercept = options.getPluginRouteIntercept?.()
-        const compatRelay = options.getRelayClient?.()
-        const compat =
-          compatRelay?.compat !== undefined || (intercept?.incompatibleCalls.length ?? 0) > 0
-            ? {
-                identical: compatRelay?.compat?.identical ?? [],
-                different: compatRelay?.compat?.different ?? [],
-                unavailable: compatRelay?.compat?.unavailable ?? [],
-                incompatibleCalls: intercept?.incompatibleCalls ?? [],
-              }
-            : undefined
-        const withDiagnostics = (body: Record<string, unknown>): Record<string, unknown> => {
-          // PB-2: the per-plugin bridge verdict rides EVERY status answer —
-          // the settings surface explains a not-bridged plugin whatever the
-          // connection state (unpaired reads all-offline, the honest verdict).
-          let next: Record<string, unknown> = { ...body, pluginBridge: options.getPluginBridgeStatus?.() ?? [] }
-          if (intercept !== undefined) next = { ...next, intercept }
-          if (fetchRouteIntercept !== undefined) next = { ...next, fetchRouteIntercept }
-          if (serviceProbe !== undefined) next = { ...next, serviceProbe }
-          if (pluginRouteIntercept !== undefined) next = { ...next, pluginRouteIntercept }
-          return compat === undefined ? next : { ...next, compat }
-        }
-        // The ROW decides its own two shapes first, per request (both fields
-        // are volatile { get() } wrappers — only the row object apply()
-        // received is a live source): without both credentials nothing is
-        // paired, and a stored address that no longer normalizes must never
-        // see the token (T16-fix).
-        const row = options.getRowConfig()
-        const record = row !== null && typeof row === 'object' && !Array.isArray(row) ? row as Record<string, unknown> : {}
-        const serverUrl = stringOrEmpty(unwrapVolatile(record.serverUrl)).trim()
-        const token = stringOrEmpty(unwrapVolatile(record.deviceToken))
-        if (token === '' || serverUrl === '') {
-          responseJson(res, 200, withDiagnostics({ state: 'unpaired' }))
-          return
-        }
-        const normalized = normalizeServerUrl(serverUrl)
-        if (!normalized.ok) {
-          responseJson(res, 200, withDiagnostics({ state: 'invalid-url' }))
-          return
-        }
-        const relay = options.getRelayClient?.()
-        if (relay === undefined) {
-          // T16 shape: no relay client wired — the ping probe is the answer.
-          const state = await probe(fetchImpl, normalized.url, token)
-          responseJson(res, 200, withDiagnostics({ state, serverUrl: normalized.url }))
+        responseJson(res, 200, await statusBodyOf(options))
+        return
+      }
+      if (route === CLIENT_DEBUG_REPORT_ROUTE) {
+        // Unwired composition (no log ring handed over): the same shape an
+        // unknown path gets — an old host must not pretend to have a report.
+        const logs = options.getLogSnapshot?.()
+        if (logs === undefined) {
+          responseJson(res, 404, { ok: false, error: { code: 'not-found', message: 'Unknown client route' } })
           return
         }
-        // The cached verdict is trusted only over the EXACT credentials the
-        // handshake earned it with: an online state whose digest no longer
-        // matches the row (address edited, re-pair) is an answer about a
-        // DIFFERENT server and falls through to a live connect instead
-        // (T23a-fix). The token never enters this body — the digest is a
-        // one-way sha256 prefix computed on both sides.
-        if (
-          relay.state === 'online' &&
-          relay.handshakeInfo !== undefined &&
-          relay.lastHandshakeDigest !== undefined &&
-          relay.lastHandshakeDigest === relayCredentialsDigest(normalized.url, token)
-        ) {
-          responseJson(res, 200, withDiagnostics(deviceStatusBody(relay.state, relay.handshakeInfo, normalized.url, relay.deviceNameSyncing)))
+        if (method !== 'GET') {
+          res.setHeader('Allow', 'GET')
+          responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET' } })
           return
         }
-        // Everything else — never connected, offline, connecting, revoked,
-        // stale credentials — gets ONE live connect bounded by the probe
-        // timeout; its FRESH result is the answer, never the possibly stale
-        // cached state. A failed attempt additionally carries the relay
-        // client's reconnect machinery readout (T43): when the next
-        // automatic retry fires and which code failed last — both free of
-        // credential material by contract.
-        try {
-          const info = await withProbeTimeout(relay.connect())
-          responseJson(res, 200, withDiagnostics(deviceStatusBody('online', info, normalized.url, relay.deviceNameSyncing)))
-        } catch (error) {
-          const body: Record<string, unknown> = { state: probeStateOfRelayError(error), serverUrl: normalized.url }
-          if (relay.nextRetryAt !== null && relay.nextRetryAt !== undefined) body.nextRetryAt = relay.nextRetryAt
-          if (relay.lastError !== undefined) body.lastError = relay.lastError
-          responseJson(res, 200, withDiagnostics(body))
-        }
+        // The picked config summary (CU-2's construction layer): field by
+        // NAME, never a spread — deviceToken and the other secret row fields
+        // are structurally absent; the assembler's deep redactor is the
+        // second layer behind this. serverUrl travels to the assembler raw
+        // and comes out as a shape (scheme + address class + port).
+        const row = options.getRowConfig()
+        const record = row !== null && typeof row === 'object' && !Array.isArray(row) ? row as Record<string, unknown> : {}
+        const values = resolveConfig(record, readFileConfig(), process.env).values
+        const rawMaxUpload: unknown = unwrapVolatile(record.maxUploadBytes)
+        const maxUploadBytes = typeof rawMaxUpload === 'number' && Number.isFinite(rawMaxUpload) && rawMaxUpload > 0
+          ? rawMaxUpload
+          : undefined
+        const rawProfile = options.getProfileName?.()
+        const report = assembleDebugReport({
+          meta: {
+            generatedAt: new Date().toISOString(),
+            pluginVersion: options.getPluginVersion?.() ?? 'unknown',
+            dshVersion: resolveDshVersion(),
+            platform: `${process.platform} ${process.arch}`,
+            role: String(values.role),
+            ...(rawProfile === undefined ? {} : { profileName: rawProfile }),
+          },
+          configSummary: {
+            role: values.role,
+            host: values.host,
+            port: values.port,
+            idleHours: values.idleHours,
+            maxUploadBytes,
+            autoShareNewSessions: values.autoShareNewSessions,
+            pluginBridgeConsent: values.pluginBridgeConsent,
+            pushSummary: values.pushSummary,
+            pushTurnEnd: values.pushTurnEnd,
+            pushTool: values.pushTool,
+            serverUrl: stringOrEmpty(unwrapVolatile(record.serverUrl)).trim(),
+          },
+          statusBody: await statusBodyOf(options),
+          ...(options.getGatewaySummary === undefined ? {} : { gatewaySummary: await options.getGatewaySummary() }),
+          logs,
+          home: homedir(),
+        })
+        responseJson(res, 200, report)
         return
       }
       if (route === CLIENT_RECONNECT_ROUTE) {

package/src/debug-redact.ts

@@ -0,0 +1,290 @@
+/**
+ * CU-2: the debug report's redactor (SPEC 方案 C). Pure functions — no DSH
+ * imports, no I/O — that turn free text and addresses into shapes an issue
+ * report can carry: absolute paths lose everything but their leaf, home
+ * paths fold to `~`, virtual session ids keep only the server id and the
+ * first 8 characters of the session id, long secret-shaped runs become
+ * `<token>`, and URL hostnames degrade to their address class. The report
+ * assembler (debug-report.ts) runs every string it emits through
+ * {@link redactText}; the check script pins the truth table, including the
+ * "an injected path/hostname/token can never be recovered from the output"
+ * assertion.
+ *
+ * The passes are ordered so they cannot un-do each other: URLs are lifted
+ * out first (pass 0, a sentinel in their place) and restored last in
+ * degraded form, so no text-wide pass can merge a URL's port and path into
+ * a token run; then virtual ids (a ≥32-char id would otherwise die as a
+ * token run), the home fold BEFORE the token pass (a long home path is
+ * itself a ≥32 run), the token pass, and the path passes (UNC, drive
+ * letter, Unix). Path leaves never contain whitespace, and Unix paths must
+ * start at a boundary (string start, whitespace, `(`, `~`) so relative
+ * paths and `a/b`-style words stay untouched.
+ *
+ * Deliberately ZERO relative imports: the check script imports this file
+ * straight off src/ under Node's strip-only type stripping (the same seam
+ * scripts/check-remote-drop.mjs uses for client-data/remote-drop.ts), and a
+ * `.js` specifier cannot resolve there. The address-class predicate below
+ * therefore restates the pairing normalizer's private-network ranges; the
+ * two are pinned against each other by a lib-level test in
+ * test/client-routes.test.cjs so they cannot drift apart silently.
+ */
+/** The address classes {@link serverUrlShape} reports. Deliberately coarse:
+ * enough to triage "can the two machines even see each other", never the
+ * hostname itself. */
+export type ServerUrlClass = 'loopback' | 'lan-ip' | 'public-ip' | 'domain'
+
+/** One pass's replacement result for a matched run of the token pass. */
+const TOKEN_PLACEHOLDER = '<token>'
+
+/** The private-network address ranges the pairing normalizer admits for
+ * plain http (client-pairing.ts's `isPrivateNetworkHost`), restated here
+ * because this module must import nothing (see the header). IPv4: `10/8`,
+ * `172.16/12`, `192.168/16`, `100.64/10` (CGNAT/Tailscale); IPv6: `fc00::/7`
+ * and `fe80::/10` by their first group. Loopback and `*.local` are decided
+ * by the caller, not here. */
+function isLanAddress(host: string): boolean {
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
+  if (ipv4 !== null) {
+    const a = Number(ipv4[1])
+    const b = Number(ipv4[2])
+    if (a === 10) return true
+    if (a === 172 && b >= 16 && b <= 31) return true
+    if (a === 192 && b === 168) return true
+    if (a === 100 && b >= 64 && b <= 127) return true
+    return false
+  }
+  const firstGroup = /^([0-9a-fA-F]{1,4}):/u.exec(host)
+  if (firstGroup !== null) {
+    const first = parseInt(firstGroup[1], 16)
+    return (first >= 0xfc00 && first <= 0xfdff) || (first >= 0xfe80 && first <= 0xfebf)
+  }
+  return false
+}
+
+/** Which class one hostname belongs to. Loopback first (it is also in the
+ * private ranges — order matters), then the remaining private ranges as
+ * `lan-ip`, then numeric literals as public addresses, everything else as
+ * `domain` (the "cannot tell" bucket, per SPEC). IPv6 brackets are
+ * stripped first — classification is bracket-free. */
+function classifyHost(bracketed: string): ServerUrlClass {
+  const host = bracketed.startsWith('[') && bracketed.endsWith(']') ? bracketed.slice(1, -1) : bracketed
+  if (host === 'localhost' || host === '::1' || host.startsWith('127.')) return 'loopback'
+  if (host.endsWith('.local')) return 'domain'
+  if (isLanAddress(host)) return 'lan-ip'
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(host)) return 'public-ip'
+  if (host.includes(':')) return 'public-ip'
+  return 'domain'
+}
+
+/**
+ * One server address's SHAPE: `scheme://class[:port]` — never the hostname.
+ * `http://192.168.1.10:3080` → `http://lan-ip:3080`; `https://myserver.example.com`
+ * → `https://domain`; the scheme's default port is omitted. Unset input
+ * answers `'unset'`, unparsable input `'invalid'`.
+ */
+export function serverUrlShape(url: unknown): string {
+  if (typeof url !== 'string' || url.trim() === '') return 'unset'
+  let parsed: URL
+  try {
+    parsed = new URL(url.trim())
+  } catch {
+    return 'invalid'
+  }
+  const scheme = parsed.protocol === 'https:' ? 'https' : parsed.protocol === 'http:' ? 'http' : parsed.protocol.replace(/:$/u, '')
+  const port = parsed.port
+  const defaultPort = (scheme === 'https' && port === '443') || (scheme === 'http' && port === '80')
+  return `${scheme}://${classifyHost(parsed.hostname)}${port !== '' && !defaultPort ? `:${port}` : ''}`
+}
+
+/**
+ * A bind address's shape for the config plate (`host`): the same address
+ * classes as {@link serverUrlShape}, plus `wildcard` for the all-interfaces
+ * binds (`0.0.0.0` / `::`) — the one bind fact triage actually needs. Unset
+ * input answers `'unset'`. A raw address never reaches the report.
+ */
+export function bindHostShape(host: unknown): string {
+  if (typeof host !== 'string' || host.trim() === '') return 'unset'
+  const value = host.trim()
+  if (value === '0.0.0.0' || value === '::' || value === '[::]') return 'wildcard'
+  return classifyHost(value)
+}
+
+/** The token pass: any run of ≥32 base64/base64url-ish characters (hex
+ * secrets, base64 keys, JWT segments — `-` and `_` included so a base64url
+ * signature dies whole instead of leaving a half) — long enough that real
+ * prose never trips it, short enough to catch every credential shape this
+ * plugin handles. */
+const TOKEN_RUN = /[A-Za-z0-9+/=_-]{32,}/gu
+
+/** The same run, as a CONTAINS test for one URL query value / path segment
+ * (non-global: `test` must not carry `lastIndex` between calls). */
+const HAS_TOKEN_RUN = /[A-Za-z0-9+/=_-]{32,}/u
+
+/** The same run without `/`, for one URL path segment at a time — a long
+ * path is not a secret, a long SEGMENT is. */
+const HAS_TOKEN_SEGMENT = /[A-Za-z0-9+=_-]{32,}/u
+
+/** Pass 0's URL candidates: a scheme this report can meet, then everything
+ * up to whitespace, a quote or an angle bracket. Trailing sentence
+ * punctuation is peeled back off afterwards ({@link URL_TRAILING}). */
+const URL_CANDIDATE = /(?:https?|wss?|ftp):\/\/[^\s"'<>\u0000]+/gu
+
+/** Sentence punctuation that ends a URL in prose (`see http://x/y).`) — `]`
+ * is deliberately absent: it closes a bracketed IPv6 host. */
+const URL_TRAILING = /[.,;:!?)}'"]+$/u
+
+/** The in-text stand-in for one extracted URL. NUL never survives into the
+ * text (pass 0 replaces any NUL the input carried), so a sentinel can only
+ * be one this function placed; nothing in it trips a later pass (no `zr~`,
+ * no slash, no 32-run, no drive-letter shape). */
+const URL_SENTINEL = /\u0000zr-url:(\d+)\u0000/gu
+
+/** One URL's path, redacted per segment: virtual ids truncate, and a segment
+ * that carries a secret-shaped run dies whole. Ordinary routes
+ * (`/_dsh/zen-remote/relay/v1/stream`) pass untouched. */
+function redactUrlPath(path: string): string {
+  return path
+    .replace(VIRTUAL_ID, (_match: string, serverId: string, id: string) => `zr~${serverId}~${id.replace(/^session-/, '').slice(0, 8)}`)
+    .split('/')
+    .map((segment) => (HAS_TOKEN_SEGMENT.test(segment) ? TOKEN_PLACEHOLDER : segment))
+    .join('/')
+}
+
+/** One URL's query + fragment (`?…` / `#…`), redacted per parameter: the key
+ * is kept, a value carrying a secret-shaped run becomes `<token>` (a bare
+ * parameter without `=` likewise). Virtual ids truncate first, so a
+ * `sessionId=zr~…` value stays recognisable. This is the URL's only secret
+ * pass — the URL was extracted before the text-wide token pass ran. */
+function redactUrlQuery(tail: string): string {
+  return tail.replace(/([?&#;])([^?&#;]*)/gu, (_match: string, separator: string, pair: string) => {
+    const truncated = pair.replace(VIRTUAL_ID, (_m: string, serverId: string, id: string) => `zr~${serverId}~${id.replace(/^session-/, '').slice(0, 8)}`)
+    const eq = truncated.indexOf('=')
+    if (eq === -1) return `${separator}${HAS_TOKEN_RUN.test(truncated) ? TOKEN_PLACEHOLDER : truncated}`
+    const value = truncated.slice(eq + 1)
+    return `${separator}${truncated.slice(0, eq)}=${HAS_TOKEN_RUN.test(value) ? TOKEN_PLACEHOLDER : value}`
+  })
+}
+
+/**
+ * One extracted URL in its reportable form: userinfo dropped whole to
+ * `<token>@`, host degraded to its address class, port and path KEPT (the
+ * SPEC's "端口与 path 保留"), path segments and query values carrying a
+ * secret-shaped run replaced by `<token>`.
+ *
+ * The userinfo boundary is the LAST `@` before the first `?`/`#` (RFC 3986:
+ * the authority cannot run past them), so a password holding `/`
+ * (`bob:ab/cd@host`) is still userinfo. The cost — a path that itself holds
+ * `@` loses everything before it to `<token>@` — is over-redaction, the
+ * safe direction.
+ */
+function degradeUrl(raw: string): string {
+  const schemeEnd = raw.indexOf('://')
+  const scheme = raw.slice(0, schemeEnd)
+  const rest = raw.slice(schemeEnd + 3)
+  const queryAt = rest.search(/[?#]/u)
+  const head = queryAt === -1 ? rest : rest.slice(0, queryAt)
+  const tail = queryAt === -1 ? '' : rest.slice(queryAt)
+  const at = head.lastIndexOf('@')
+  const afterUser = at === -1 ? head : head.slice(at + 1)
+  const hostPort = /^(\[[^\]]*\]|[^/:]*)(:\d+)?/u.exec(afterUser)
+  const host = hostPort?.[1] ?? ''
+  const port = hostPort?.[2] ?? ''
+  const path = afterUser.slice(hostPort?.[0].length ?? 0)
+  return `${scheme}://${at === -1 ? '' : `${TOKEN_PLACEHOLDER}@`}${classifyHost(host)}${port}${redactUrlPath(path)}${redactUrlQuery(tail)}`
+}
+
+/** The UNC pass: `\\server\share\…\leaf` → `<路径:leaf>`. Server and share
+ * are mandatory and never kept; inner segments may hold spaces
+ * (`Shared Docs`), the leaf may not — so trailing prose stays outside. */
+const UNC_PATH = /(?<![\w\\])\\\\[^\\/:*?"<>|\s]+\\[^\\/:*?"<>|\r\n]+(?:\\[^\\/:*?"<>|\r\n]+)*\\([^\\/:*?"<>|\s]+)/gu
+
+/** A bare UNC root (`\\server\share`, no leaf beyond the share): nothing in
+ * it is safe to keep. Runs after {@link UNC_PATH}. */
+const UNC_ROOT = /(?<![\w\\])\\\\[^\\/:*?"<>|\s]+\\[^\\/:*?"<>|\s]+/gu
+
+/** The virtual-id pass: `zr~<serverId>~<id>` keeps the server id and the
+ * session id's first 8 characters (the debug report needs "same server?
+ * same session?" — not the full id). */
+const VIRTUAL_ID = /zr~([^~\s]{1,80})~([^~\s]{1,80})/gu
+
+/** The Windows absolute-path pass: drive letter, colon, separator, then path
+ * segments — reduced to `<路径:leaf>`. The drive letter must not follow a
+ * word character (`https:/` is not a drive); inner segments may hold spaces
+ * (`Program Files`), the leaf may not — so `D:\x\plan.txt failed` keeps
+ * `failed` outside the placeholder. */
+const WINDOWS_PATH = /(?<!\w)([A-Za-z]:[\\/](?:[^\\/:*?"<>|\r\n]+[\\/])*)([^\\/:*?"<>|\s]+)/gu
+
+/** The Unix absolute-path pass, same reduction. The boundary lookbehind
+ * (string start, whitespace, `(`, `~`, `>`) keeps relative paths, URL path
+ * segments and `a/b` words out; `~` is excluded so a home-folded path
+ * (`~/work/x.txt`) is never re-matched. */
+const UNIX_PATH = /(?<![\w:/.\\~])(\/(?:[^/\s]+\/)*)([^/\s]+)/gu
+
+/**
+ * Redact one free-text value: home paths fold to `~` (their relative tail is
+ * kept — that is the one shape the report intentionally preserves), absolute
+ * paths reduce to `<路径:leaf>`, URL hostnames degrade to their address
+ * class, virtual session ids truncate, secret-shaped runs become
+ * `<token>`. Non-strings pass through unchanged.
+ */
+export function redactText(text: string, context: { home?: string }): string {
+  if (typeof text !== 'string' || text === '') return text
+  // 0. URLs out first, each replaced by a sentinel and restored LAST in
+  // degraded form — so no text-wide pass can merge a URL's port and path
+  // into one token run (the "ws://…:3080/_dsh/…" port loss), and the
+  // userinfo/query handling lives in one place (degradeUrl). Any NUL the
+  // input carried is neutralized first: a sentinel can only be ours.
+  const urls: string[] = []
+  let out = text.replaceAll('\u0000', '\uFFFD').replace(URL_CANDIDATE, (match: string) => {
+    const trailing = URL_TRAILING.exec(match)?.[0] ?? ''
+    urls.push(match.slice(0, match.length - trailing.length))
+    return `\u0000zr-url:${urls.length - 1}\u0000${trailing}`
+  })
+  // 1. virtual ids: a ≥32-char id would otherwise die as a token run. The
+  // id's `session-` label is stripped before the cut — the ids are all
+  // `session-<uuid>`, so the head 8 of the label would carry nothing.
+  out = out.replace(VIRTUAL_ID, (_match: string, serverId: string, id: string) => `zr~${serverId}~${id.replace(/^session-/, '').slice(0, 8)}`)
+  // 2. the home directory folds to `~` BEFORE the token pass — a long home
+  // path is itself a ≥32 run and would otherwise die whole, losing the
+  // `~/Downloads/x.bin` shape the SPEC promises (folding only removes
+  // information, so running it early is safe). Guarded: never fold the
+  // filesystem root; a separator the fold leaves behind is normalized, so a
+  // Windows home path reads `~/doc.txt` like its Unix counterpart.
+  const home = context.home
+  if (typeof home === 'string' && home.length > 1) {
+    out = out.split(home).join('~').replaceAll('~\\', '~/')
+  }
+  // 3. secret-shaped runs.
+  out = out.replace(TOKEN_RUN, () => TOKEN_PLACEHOLDER)
+  // 4. UNC paths, then bare UNC roots — before the drive-letter pass.
+  out = out.replace(UNC_PATH, (_match: string, leaf: string) => `<路径:${leaf}>`)
+  out = out.replace(UNC_ROOT, () => '<路径>')
+  // 5. Windows absolute paths → <路径:leaf>.
+  out = out.replace(WINDOWS_PATH, (_match: string, _prefix: string, leaf: string) => `<路径:${leaf}>`)
+  // 6. Unix absolute paths → <路径:leaf> (the leaf class already excludes
+  // whitespace).
+  out = out.replace(UNIX_PATH, (_match: string, _prefix: string, leaf: string) => `<路径:${leaf}>`)
+  // 7. URLs back in, degraded: userinfo → `<token>@`, host → address class,
+  // port and path kept, secret-shaped path segments / query values →
+  // `<token>`.
+  return out.replace(URL_SENTINEL, (_match: string, index: string) => degradeUrl(urls[Number(index)] ?? ''))
+}
+
+/**
+ * Deep-redact one JSON-ready value: every string (at any depth) through
+ * {@link redactText}; keys are kept as-is (plugin names, field names —
+ * public identifiers), numbers/booleans/null pass through. Returns new
+ * containers; the input is never mutated.
+ */
+export function redactValue(value: unknown, context: { home?: string }): unknown {
+  if (typeof value === 'string') return redactText(value, context)
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, context))
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = redactValue(item, context)
+    }
+    return out
+  }
+  return value
+}