dsh-cherry-bridge 0.1.11 → 0.2.1

package/src/httpApi.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto'
-import { QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
+import { LastCandidateHostError, QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
 import type { DeviceRecord } from './deviceStore.js'
 import type { DeviceStore } from './deviceStore.js'
 import type { DeviceState, EffectiveLimits } from './connection.js'
@@ -9,6 +9,7 @@ import { CONTRACT_DIFFERENCES, buildDiagnostics, readScopeSegment } from './diag
 import type { DiagnosticsError, DiagnosticsStats, SubscriptionStat } from './diagnostics.js'
 import type { ScopeDoc, ToolScopeState } from './toolScope.js'
 import type { RefreshSummary } from './toolScopeHost.js'
+import { failureText } from './text.js'
 
 /**
  * The plugin's same-origin HTTP face (spec §3.7): device management REST plus
@@ -114,6 +115,18 @@ export interface DeviceSummary {
   enabled: boolean
   hosts: string[]
   port: number
+  /** The scheme each host is dialed with (issue #126); see `DeviceRecord`. */
+  security: Record<string, 'ws' | 'wss'>
+  /** The port each host is dialed with (issue #135); see `DeviceRecord`. */
+  ports: Record<string, number>
+  /**
+   * The addresses the operator has forgotten (issue #185): not dialed, and not
+   * re-learned until `cherry_devices` remembers them (or a PATCH puts one back
+   * into `hosts`, which clears its mark). Reported beside the address maps for
+   * the same reason they are: it is archive state an operator edits, not a
+   * credential.
+   */
+  forgottenHosts: string[]
 }
 
 /** The `device-state` SSE payload. */
@@ -432,6 +445,9 @@ function writeQuarantineRefusal(res: HttpResponseLike, route: RouteContext, erro
   try {
     route.deps.onArchiveQuarantined?.(error)
   } catch (reportError) {
+    // LOCAL observer catch (issue #161 audit): the diagnostics ring is ours, so
+    // no peer text can reach this error — the object print (with its stack) is
+    // deliberate.
     console.warn('[cherry-remote] reporting the quarantined archive failed', reportError)
   }
   writeJson(res, 503, {
@@ -538,9 +554,20 @@ interface DevicePatch {
 }
 
 /**
- * Validates a PATCH body. `hosts` is WHOLE-REPLACE by contract, and `port` is
- * shared by every host (spec §3.2) — there is no per-host port and no merge
- * semantics to get wrong.
+ * Validates a PATCH body. `hosts` is WHOLE-REPLACE by contract.
+ *
+ * The map semantics this face owes (the record's per-host maps are DERIVED,
+ * never patched directly — there is no `ports` field in this body):
+ *
+ *  - neither `hosts` nor `port` patched → the maps are unchanged;
+ *  - `hosts` replaced → a host that stays keeps ITS OWN scheme and port, a new
+ *    host gets `ws` and the record-level port;
+ *  - a CHANGED `port` (with or without `hosts`) → EVERY final host is
+ *    re-pointed to it. The face has one port field, so leaving per-host
+ *    entries would make the edit inert for every listed host that already had
+ *    one. Sending the CURRENT value is a no-op for the maps — the settings page
+ *    sends both fields on every save, and a mixed-port record must not be
+ *    flattened by a save that did not change the port.
  */
 function parsePatch(body: Record<string, unknown>): DevicePatch {
   const patch: DevicePatch = {}
@@ -573,6 +600,18 @@ function parsePatch(body: Record<string, unknown>): DevicePatch {
       if (typeof entry !== 'string') throw new PatchError('hosts entries must be strings')
       return normalizeHost(entry)
     })
+    // Checked AFTER normalization: `[::1]` and `::1` collapse to one host, and
+    // host comparison is CASE-INSENSITIVE everywhere else on this face (the
+    // learn merge, the forget/remember matching, the mark clearing), so
+    // `NAS.example` and `nas.example` are one address too. The scheme/port maps
+    // are keyed by host, so a duplicate has no single entry and silently
+    // last-wins — an ambiguous record, not an edit.
+    const seen = new Set<string>()
+    for (const host of patch.hosts) {
+      const key = host.toLowerCase()
+      if (seen.has(key)) throw new PatchError('hosts must not contain duplicates')
+      seen.add(key)
+    }
   }
 
   const port = body['port']
@@ -992,6 +1031,28 @@ async function handleRequest(req: HttpRequestLike, res: HttpResponseLike, route:
       return
     }
 
+    // The two endpoint actions (issue #204) sit UNDER the device resource
+    // because that is what they act on: they are the page's door onto #185's
+    // forget/remember, one action per request, so a "patch AND forget" body
+    // with a contradictory ordering never exists.
+    if (first === 'devices' && match.segments.length === 3 && second !== undefined) {
+      const deviceId = decodeSegment(second)
+      if (deviceId === undefined) {
+        writeError(res, 400, 'invalid-request', 'device id is not valid URL encoding')
+        return
+      }
+      const action = match.segments[2]
+      if (action !== 'forget' && action !== 'remember') {
+        writeError(res, 404, 'not-found', 'unknown route')
+        return
+      }
+      if (method !== 'POST') {
+        writeError(res, 405, 'method-not-allowed', 'POST only')
+        return
+      }
+      return await changeEndpoints(req, res, route, deviceId, action)
+    }
+
     if (first === 'pair' && match.segments.length === 1) {
       if (method !== 'POST') {
         writeError(res, 405, 'method-not-allowed', 'POST only')
@@ -1046,15 +1107,35 @@ async function handleRequest(req: HttpRequestLike, res: HttpResponseLike, route:
 }
 
 function listDevices(res: HttpResponseLike, route: RouteContext): void {
-  const devices: DeviceSummary[] = route.deps.store.list().map((device) => ({
+  writeJson(
+    res,
+    200,
+    route.deps.store.list().map((device) => deviceSummary(route, device)),
+  )
+}
+
+/**
+ * One device as the browser sees it: the public archive projection, never a
+ * credential.
+ *
+ * ONE builder, because FOUR faces answer this shape — `GET /devices`, the
+ * `PATCH`, and the two endpoint actions of issue #204 — and a hand-written copy
+ * per face is how a field ends up on one and not the others.
+ */
+function deviceSummary(route: RouteContext, device: DeviceRecord): DeviceSummary {
+  return {
     deviceId: device.deviceId,
     displayName: device.displayName,
     state: projectState(device, route.deps.connect),
     enabled: device.enabled,
     hosts: [...device.hosts],
     port: device.port,
-  }))
-  writeJson(res, 200, devices)
+    security: { ...device.security },
+    ports: { ...device.ports },
+    // An empty list is the honest "none", not an absent key: the page renders
+    // the forgotten row only when it is non-empty.
+    forgottenHosts: [...(device.forgottenHosts ?? [])],
+  }
 }
 
 /**
@@ -1255,11 +1336,13 @@ function deviceById(deps: CherryHttpDeps, deviceId: string): DeviceRecord {
   const found = deps.store.list().find((device) => device.deviceId === deviceId)
   if (found !== undefined) return found
   return {
-    schemaVersion: 2,
+    schemaVersion: 4,
     deviceId,
     displayName: '',
     hosts: [],
     port: 0,
+    security: {},
+    ports: {},
     desktopIdentity: '',
     grants: [],
     enabled: false,
@@ -1360,13 +1443,48 @@ async function patchDevice(
   const previousEnabled = existing.enabled
   const previousHosts = existing.hosts
   const previousPort = existing.port
+  const previousSecurity = existing.security
+  const previousPorts = existing.ports
+  // The per-host port map is DERIVED from the patch, never patched directly
+  // (there is no `ports` field in the body):
+  //  - no address field → unchanged;
+  //  - `hosts` replaced → a staying host keeps its own port, a new host gets the
+  //    record-level `port`;
+  //  - a CHANGED `port` (with or without `hosts`) → EVERY final host is
+  //    re-pointed; one port field on this face, so leaving per-host entries
+  //    would make the edit inert. Sending the CURRENT value is a no-op for the
+  //    map (see `parsePatch`), because the settings page sends both fields on
+  //    every save.
+  const nextPorts =
+    patch.port !== undefined && patch.port !== previousPort
+      ? portsFor(patch.hosts ?? previousHosts, {}, patch.port)
+      : patch.hosts === undefined
+        ? previousPorts
+        : portsFor(patch.hosts, previousPorts, previousPort)
+  // A host the operator puts BACK into `hosts` is dialed again, so its forget
+  // mark must go: `hosts` and `forgottenHosts` are disjoint by contract, and an
+  // explicit list is intent to dial. A PATCH that does not touch `hosts`
+  // (displayName/enabled/port) leaves every mark alone. Case-insensitive, the
+  // same comparison the learn merge uses.
+  const nextForgotten =
+    patch.hosts === undefined || existing.forgottenHosts === undefined
+      ? undefined
+      : existing.forgottenHosts.filter(
+          (host) => !patch.hosts!.some((nextHost) => nextHost.toLowerCase() === host.toLowerCase()),
+        )
   const next: DeviceRecord = {
     ...existing,
+    ...(nextForgotten === undefined ? {} : { forgottenHosts: nextForgotten }),
     ...(patch.displayName === undefined ? {} : { displayName: patch.displayName }),
     ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }),
-    // hosts is WHOLE-REPLACE: the patch wins outright, never merges.
-    ...(patch.hosts === undefined ? {} : { hosts: patch.hosts }),
+    // hosts is WHOLE-REPLACE: the patch wins outright, never merges. The
+    // scheme map is keyed by host, so replacing the host list drops the
+    // entries for hosts that are gone and defaults the new ones to `ws` —
+    // keeping the OLD schemes indexed by the NEW list would be a stale
+    // pairing of host to scheme (issue #126).
+    ...(patch.hosts === undefined ? {} : { hosts: patch.hosts, security: securityFor(patch.hosts, previousSecurity) }),
     ...(patch.port === undefined ? {} : { port: patch.port }),
+    ports: nextPorts,
   }
 
   try {
@@ -1389,7 +1507,8 @@ async function patchDevice(
   // `connect()` to rebuild from the record we just wrote.
   const addressChanged =
     (patch.hosts !== undefined && !sameHosts(patch.hosts, previousHosts)) ||
-    (patch.port !== undefined && patch.port !== previousPort)
+    (patch.port !== undefined && patch.port !== previousPort) ||
+    !sameSecurity(next.security, previousSecurity)
   const enabledChanged = patch.enabled !== undefined && patch.enabled !== previousEnabled
 
   if (addressChanged) {
@@ -1409,31 +1528,39 @@ async function patchDevice(
     try {
       track(route.deps.connect(deviceId).connect(), warnConnect(deviceId))
     } catch (error) {
+      // LOCAL: only the synchronous construction failure lands here
+      // (`connectionFor` cannot find the record, or the identity failed to
+      // load). The DIAL's rejection carries peer text and is rendered by
+      // `warnConnect` below; this arm keeps the object print and its stack
+      // (issue #161's boundary).
       console.warn(`[cherry-remote] device ${deviceId} reconnect failed`, error)
     }
   }
 
   // The response and the SSE frame always report the projection of the record
   // we just wrote: a disabled device is `disabled` regardless of what its
-  // connection last said, and an enabled one reports its live state.
-  const state = projectState(next, route.deps.connect)
+  // connection last said, and an enabled one reports its live state. ONE
+  // projection feeds both, so the frame and the body cannot disagree.
+  const summary = deviceSummary(route, next)
   if (patch.enabled !== undefined && patch.enabled !== previousEnabled) {
-    route.hub.publish('device-state', { deviceId, state })
+    route.hub.publish('device-state', { deviceId, state: summary.state })
   }
 
-  writeJson(res, 200, {
-    deviceId: next.deviceId,
-    displayName: next.displayName,
-    state,
-    enabled: next.enabled,
-    hosts: [...next.hosts],
-    port: next.port,
-  })
+  writeJson(res, 200, summary)
 }
 
 function warnConnect(deviceId: string): (error: unknown) => void {
   return (error: unknown) => {
-    console.warn(`[cherry-remote] device ${deviceId} lifecycle change failed`, error)
+    // ONE bounded STRING (issue #161). This is the arm that receives the
+    // lifecycle rejection. The common case is `AllHostsUnreachableError`, whose
+    // message embeds the last per-host error as `last: <message>` — a `ws` /
+    // channel failure, or an RPC refusal's peer message (capped at 512 by the
+    // failure schema). The terminal arms add only local wrappers (`identity
+    // mismatch`, `protocol version incompatible`, `authenticate rejected
+    // (<reason>)` — an enum). The old form handed the error OBJECT to the
+    // console. Ceiling: `[cherry-remote] device ` (23) + deviceId +
+    // ` lifecycle change failed: ` (26) + LOG_TEXT_MAX (240).
+    console.warn(`[cherry-remote] device ${deviceId} lifecycle change failed: ${failureText(error)}`)
   }
 }
 
@@ -1442,6 +1569,205 @@ function sameHosts(a: readonly string[], b: readonly string[]): boolean {
   return a.length === b.length && a.every((host, index) => host === b[index])
 }
 
+/**
+ * `POST /devices/:id/forget` and `POST /devices/:id/remember` (issue #204): the
+ * settings page's door onto #185's endpoint maintenance, which until now only
+ * the `cherry_devices` tool could open.
+ *
+ * One action per request, and the action IS the request: there is no composite
+ * "patch the record AND forget a host" body whose ordering would have to be
+ * defined. Every judgement is the store's — the last-candidate refusal, the
+ * case-insensitive matching, the disjointness of `hosts`/`forgottenHosts` — so
+ * the two doors share ONE set of STORE rules; this route only maps the verdicts
+ * onto HTTP and answers the projection the PATCH answers. (The BODY PARSERS do
+ * differ on purpose — see `parseEndpointHosts`.)
+ *
+ * EVICTION on a change, exactly like the tool's own arm and a PATCH's address
+ * maintenance, and for a DIFFERENT reason on each action — which is why both
+ * are stated here rather than waved through as "parity":
+ *
+ *  - FORGET: a pooled connection CAPTURES its record at construction, so the
+ *    socket built before this write would keep dialing the host we just forgot.
+ *    (The mark itself is honoured by the store's learn merge, so a reconnect is
+ *    about the DIAL LIST, not about suppressing the address.)
+ *  - REMEMBER: learning happens only INSIDE a handshake, against a clone of the
+ *    stored record. Without the eviction a desktop that stays connected would
+ *    not re-handshake for as long as the link holds, so the restored address
+ *    would come back only after some later flap — the button would look inert.
+ *
+ * The cost is real and inherited from the tool's arm: an eviction disposes the
+ * subscription layer and closes a healthy socket, so a write can drop an
+ * in-flight command's link. One operator click now reaches that churn; that is
+ * the price of "the archive is the truth" for a live connection.
+ */
+async function changeEndpoints(
+  req: HttpRequestLike,
+  res: HttpResponseLike,
+  route: RouteContext,
+  deviceId: string,
+  action: 'forget' | 'remember',
+): Promise<void> {
+  const existing = route.deps.store.list().find((device) => device.deviceId === deviceId)
+  if (existing === undefined) {
+    writeError(res, 404, 'not-found', `no device ${deviceId}`)
+    return
+  }
+
+  let hosts: string[]
+  try {
+    hosts = parseEndpointHosts(await readJsonBody(req))
+  } catch (error) {
+    writeError(res, 400, 'invalid-request', error instanceof Error ? error.message : String(error))
+    return
+  }
+
+  try {
+    if (action === 'forget') {
+      const { removed, marked } = route.deps.store.forgetEndpoints(deviceId, hosts)
+      if (removed.length > 0 || marked.length > 0) evict(route, deviceId)
+    } else {
+      const { restored } = route.deps.store.rememberEndpoints(deviceId, hosts)
+      if (restored.length > 0) evict(route, deviceId)
+    }
+  } catch (error) {
+    // Quarantine first, and distinctly: it is not the request's fault (the 400s
+    // below) and the browser cannot fix it — the archive is READ-ONLY until a
+    // human moves the bad file aside. A store that was ALREADY quarantined
+    // never reaches this arm: its view is empty, so the `list()` above answered
+    // 404 before any write — the same precedence PATCH and DELETE have. This is
+    // the defence for a store that begins refusing after that read, and it is
+    // what keeps a damaged archive from being reported as a bad request.
+    if (writeQuarantineRefusal(res, route, error)) return
+    // The tool's own code for the same refusal, so the page can translate it by
+    // code rather than by prose.
+    if (error instanceof LastCandidateHostError) {
+      writeError(res, 400, 'last-address', error.message)
+      return
+    }
+    writeError(res, 400, 'invalid-device', error instanceof Error ? error.message : String(error))
+    return
+  }
+
+  // The projection of the record we just wrote, never the object we read before
+  // the write: `REMOVED from a declined call` and `UNCHANGED by a no-op` are
+  // both answered from the archive's current row.
+  const fresh = route.deps.store.list().find((device) => device.deviceId === deviceId)
+  writeJson(res, 200, deviceSummary(route, fresh ?? existing))
+}
+
+/**
+ * The body of an endpoint action: `{hosts: [...]}`, non-empty, every entry
+ * normalized the same way the PATCH normalizes an address.
+ *
+ * The normalization is not cosmetic: an IPv6 literal is stored bare but a
+ * browser copy-pastes it bracketed, and the store matches by host spelling —
+ * so `[::1]` would be treated as an address the record does not dial and merely
+ * marked, leaving the real `::1` in `hosts`. The PATCH's rule is reused for the
+ * spelling (same `normalizeHost`), and deliberately NOT for its duplicate
+ * refusal: a repeated host in an action body names one host twice, which the
+ * store's own sets collapse, while the PATCH's duplicates would build an
+ * ambiguous record (`hosts`, `security` and `ports` are keyed by host).
+ */
+function parseEndpointHosts(body: Record<string, unknown>): string[] {
+  const hosts = body['hosts']
+  if (!Array.isArray(hosts) || hosts.length === 0) {
+    throw new PatchError('hosts must be a non-empty array')
+  }
+  return hosts.map((entry) => {
+    if (typeof entry !== 'string') throw new PatchError('hosts entries must be strings')
+    return normalizeHost(entry)
+  })
+}
+
+/**
+ * The scheme map for a WHOLE-REPLACE host list (issue #126): each named host
+ * keeps the scheme it was dialed with, a host the list just gained defaults to
+ * `ws`, and hosts the list dropped leave no entry behind. An edit is an
+ * address edit, not a scheme edit — re-typing the same host must not silently
+ * demote a TLS-proxied desktop to a plain dial.
+ *
+ * "The same host" is CASE-INSENSITIVE (issue #189), the same comparison the
+ * learn merge, the forget/remember actions and the mark clearing already use:
+ * `NAS.example` and `nas.example` are one address, so a PATCH that re-types
+ * the case keeps the remembered scheme instead of resetting it to `ws`.
+ * `sameHosts`/`sameSecurity` stay EXACT on purpose — they decide whether an
+ * address edit happened at all, and a new spelling IS a change to persist.
+ */
+function securityFor(
+  hosts: readonly string[],
+  previous: Record<string, 'ws' | 'wss'>,
+): Record<string, 'ws' | 'wss'> {
+  // `Object.hasOwn`, never `previous[host] ?? 'ws'`: a host named `constructor`
+  // (or `__proto__`/`toString`) would otherwise inherit a FUNCTION from
+  // Object.prototype and poison the map the store then rejects. The index is
+  // built from OWN entries only, so it is safe for the same reason.
+  const remembered = indexByHost(previous)
+  return Object.fromEntries(
+    hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? 'ws']),
+  )
+}
+
+/**
+ * A case-insensitive index over a per-host map (issue #189).
+ *
+ * FIRST spelling wins on a collision. A hand-edited archive CAN hold two
+ * spellings of one host (the store does not reject it, and this face does not
+ * touch `previous`), so callers look their exact spelling up FIRST and consult
+ * this index only as the fallback: a surviving spelling therefore keeps its
+ * OWN entry, and the collision rule only decides what a THIRD spelling
+ * inherits.
+ */
+function indexByHost<T>(previous: Record<string, T>): Map<string, T> {
+  const index = new Map<string, T>()
+  for (const [host, value] of Object.entries(previous)) {
+    const key = host.toLowerCase()
+    if (!index.has(key)) index.set(key, value)
+  }
+  return index
+}
+
+/** The exact spelling's entry, else the case-insensitive one, else nothing. */
+function exactOrRemembered<T>(
+  previous: Record<string, T>,
+  remembered: Map<string, T>,
+  host: string,
+): T | undefined {
+  return Object.hasOwn(previous, host) ? previous[host] : remembered.get(host.toLowerCase())
+}
+
+/**
+ * The port map for a host list (issue #135): each named host keeps the port it
+ * was dialed with, a host the list just gained defaults to `fallback` (the
+ * record-level port), and hosts the list dropped leave no entry behind.
+ *
+ * `previous` is empty when the caller is re-pointing EVERY host (a CHANGED
+ * `port` patch): there is no remembered entry to keep, by design — one port
+ * field on this face must move the whole list. Same `Object.hasOwn`/
+ * case-insensitive rules as `securityFor` (issue #189): a re-typed spelling
+ * keeps its own port, and an inherited function is never a remembered port.
+ */
+function portsFor(
+  hosts: readonly string[],
+  previous: Record<string, number>,
+  fallback: number,
+): Record<string, number> {
+  const remembered = indexByHost(previous)
+  return Object.fromEntries(
+    hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? fallback]),
+  )
+}
+
+/** Order-insensitive comparison for two scheme maps. */
+function sameSecurity(
+  a: Record<string, 'ws' | 'wss'>,
+  b: Record<string, 'ws' | 'wss'>,
+): boolean {
+  const keys = Object.keys(a)
+  if (keys.length !== Object.keys(b).length) return false
+  return keys.every((key) => a[key] === b[key])
+}
+
+
 /** Drops the pooled connection, closing any live socket first. */
 function evict(route: RouteContext, deviceId: string): void {
   try {
@@ -1555,6 +1881,8 @@ async function startPairing(req: HttpRequestLike, res: HttpResponseLike, route:
         try {
           route.deps.onArchiveQuarantined?.(error)
         } catch (reportError) {
+          // LOCAL observer catch (issue #161 audit): same ring as the PATCH
+          // route's, no peer text — the object print is deliberate.
           console.warn('[cherry-remote] reporting the quarantined archive failed', reportError)
         }
         // The shared instruction VERBATIM, with only the two contextual paths