dsh-cherry-bridge 0.2.0 → 0.2.2

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'
@@ -119,6 +119,14 @@ export interface DeviceSummary {
   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. */
@@ -592,11 +600,17 @@ 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. 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.
-    if (new Set(patch.hosts).size !== patch.hosts.length) {
-      throw new PatchError('hosts must not contain duplicates')
+    // 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)
     }
   }
 
@@ -1017,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')
@@ -1071,7 +1107,23 @@ 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),
@@ -1080,8 +1132,10 @@ function listDevices(res: HttpResponseLike, route: RouteContext): void {
     port: device.port,
     security: { ...device.security },
     ports: { ...device.ports },
-  }))
-  writeJson(res, 200, devices)
+    // 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 ?? [])],
+  }
 }
 
 /**
@@ -1407,8 +1461,20 @@ async function patchDevice(
       : 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. The
@@ -1473,22 +1539,14 @@ async function patchDevice(
 
   // 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,
-    security: { ...next.security },
-    ports: { ...next.ports },
-  })
+  writeJson(res, 200, summary)
 }
 
 function warnConnect(deviceId: string): (error: unknown) => void {
@@ -1511,12 +1569,129 @@ 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[],
@@ -1524,12 +1699,42 @@ function securityFor(
 ): 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.
+  // 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, Object.hasOwn(previous, host) ? previous[host] : 'ws']),
+    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
@@ -1537,16 +1742,18 @@ function securityFor(
  *
  * `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` rule as
- * `securityFor`: an inherited function is not a remembered 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, Object.hasOwn(previous, host) ? previous[host] : fallback]),
+    hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? fallback]),
   )
 }
 

package/src/index.ts

@@ -489,6 +489,19 @@ function connectionFor(deviceId: string): DeviceConnection {
     // Spread-if-present, never `wsOptions: undefined`: the option is optional,
     // and an absent key is the honest "no override" (Node's trust store).
     ...(state.wsTls === undefined ? {} : { wsOptions: state.wsTls }),
+    // The archive write-back (issue #143). The connection has already merged the
+    // addresses into its OWN record — this instance's next reconnect dials them
+    // — so the only job here is durability. It goes through
+    // `DeviceStore.learnEndpoints`, NOT `upsert(record)`: the store's record
+    // carries the token of the PAIRING while the connection's mirrors the live
+    // one, and an `upsert` of the connection's copy would put a
+    // connection-scoped credential into the archive.
+    onAdvertisedEndpoints: (endpoints) => {
+      // `record` is THIS connection's clone: its `desktopIdentity` is the pin the
+      // answer was validated against, so a re-pair under the same deviceId cannot
+      // receive an address learned from the previous pairing.
+      state.store.learnEndpoints(deviceId, endpoints, record.desktopIdentity)
+    },
   })
   state.connectionsBuilt += 1
   connection.onState((deviceState: DeviceState) => {
@@ -651,6 +664,11 @@ function subsFor(deviceId: string): SessionSubscriptions {
   const created = new SessionSubscriptions(connection.rpc, {
     subscriptionsLimit: connection.limits.subscriptions,
     perSessionCacheBytes: state.perSessionCacheBytes,
+    // The peer's OWN un-acked window when hello advertised it (protocol 0.7.0
+    // peers do); absent falls back to the pinned constant inside the layer.
+    // A PROVIDER, not a value: the layer outlives a reconnect, and `limits` is
+    // rebuilt by every hello — a pinned number would freeze the first answer.
+    unackedBytes: () => connection.limits.unackedBytes,
   })
   state.subscriptions.set(deviceId, created)
   // INFO (spec §5 「订阅建立」): the layer is announced with the cap it was