dsh-cherry-bridge 0.2.0 → 0.2.2

package/src/deviceStore.ts

@@ -11,6 +11,7 @@ import {
   writeSync,
 } from 'node:fs'
 import { dirname } from 'node:path'
+import type { DirectEndpoint } from '@cherrystudio/remote-protocol'
 
 /**
  * Crash-durable, corruption-safe archive of paired Cherry Studio desktop
@@ -75,6 +76,21 @@ export interface DeviceRecord {
    * `ports` from `port`; `port` itself stays the record-level fallback.
    */
   ports: Record<string, number>
+  /**
+   * Addresses the operator has FORGOTTEN (issue #185): never dialed and never
+   * learned again, matched CASE-INSENSITIVELY and disjoint from `hosts` — a
+   * record may not dial what it has forgotten, and `assertValidRecord` refuses
+   * the overlap rather than picking a winner at read time.
+   *
+   * OPTIONAL on purpose, and therefore not in {@link REQUIRED_KEYS}. Absence is
+   * the total default ("nothing forgotten"); no invariant depends on the key
+   * being present, unlike `security`/`ports` whose absence would make a host
+   * undialable; and an older build ignores an unknown key instead of refusing
+   * the archive. A `schemaVersion` bump would invalidate every v4 archive (and
+   * every fixture built from the v4 shape) for a list whose empty value needs
+   * no migration.
+   */
+  forgottenHosts?: string[]
   desktopIdentity: string
   grants: 'agent'[]
   /** Paired with `tokenExpiresAt`: present together or absent together. */
@@ -107,6 +123,80 @@ export type DeviceResolution = DeviceRecord | AmbiguousDevice | UnresolvedDevice
 /** The only `schemaVersion` this build reads and writes. */
 export const CURRENT_SCHEMA_VERSION = 4
 
+/**
+ * The most candidate hosts one record may carry (issue #143).
+ *
+ * `hosts` is a DIAL list, not a table: every reconnect walks it with one
+ * `connectTimeoutMs` per address, so its LENGTH is a time cost — a 32-host
+ * record already allows a 320 s pass, which is the number the pairing walk's
+ * aggregate budget exists for. Pairing can only ever produce 32
+ * (`pairingQrSchema`'s `.max(32)`), and learning is held to the same bound: an
+ * enrichment may not build a record that no pairing could have produced.
+ */
+export const MAX_CANDIDATE_HOSTS = 32
+
+/**
+ * Adds the candidate addresses a peer ADVERTISED that this record does not
+ * already dial, returning how many hosts were added (issue #143).
+ *
+ * The rule is ADD-ONLY, deliberately:
+ *
+ *  - a host already in `hosts` is left exactly as it is, INCLUDING its port and
+ *    its scheme. The peer's snapshot describes where it listens NOW, while a
+ *    record entry may be an operator's choice (a pinned port, a TLS proxy) that
+ *    every reconnect must keep honouring; re-pointing it would silently rewrite
+ *    the operator's address book on a schedule. "Already dials" is judged
+ *    CASE-INSENSITIVELY: a hostname is case-insensitive, the peer's schema
+ *    lowercases what it advertises, and a PATCHed record stores what the
+ *    operator typed — without this, `MyNAS.example` and `mynas.example` would
+ *    both hold a dial slot. (An IPv6 literal in a different EXPANSION is NOT
+ *    reconciled here; the PATCH path owns the archive's spelling, and it does
+ *    not canonicalize either.)
+ *  - nothing is removed HERE: a host the peer still advertises is re-learned
+ *    after an operator PATCH drops it, because the peer is the source of truth
+ *    for where it listens. The operator's answer to that is `forgetEndpoints`
+ *    (issue #185), whose mark this function honours — addition stays add-only,
+ *    and forgetting is a separate, explicit decision;
+ *  - host, port and scheme are appended TOGETHER, which is what keeps the v4
+ *    one-entry-per-host invariant true. That invariant is enforced on the READ
+ *    path by `assertValidSecurity`/`assertValidPorts`, and a semantic failure
+ *    there is NOT a quarantine (that class covers unreadable bytes): the throw
+ *    escapes `parseArchive` out of `list()`, so a split entry would break every
+ *    tool until an operator repaired the file;
+ *  - past {@link MAX_CANDIDATE_HOSTS} nothing is added, and the loop stops
+ *    rather than scanning the rest.
+ *
+ * `endpoints` must already have passed the peer's own `advertisedEndpointSchema`
+ * (which bounds the port to 1..65535, the scheme to `ws`/`wss`, and rejects a
+ * loopback destination), so every value written here is archive-valid without a
+ * second validation pass.
+ */
+export function mergeAdvertisedEndpoints(
+  record: DeviceRecord,
+  endpoints: readonly DirectEndpoint[],
+): number {
+  // One comparison rule, applied to what the record already dials AND to what
+  // this answer has added so far: a duplicate inside one answer must not take a
+  // second slot either.
+  const dialed = new Set(record.hosts.map((host) => host.toLowerCase()))
+  // A FORGOTTEN address is skipped here, not removed afterwards: the operator's
+  // decision outranks the peer's snapshot, and an answer that names it must not
+  // even spend a dial slot on it.
+  const forgotten = new Set((record.forgottenHosts ?? []).map((host) => host.toLowerCase()))
+  let added = 0
+  for (const endpoint of endpoints) {
+    const key = endpoint.host.toLowerCase()
+    if (dialed.has(key) || forgotten.has(key)) continue
+    if (record.hosts.length >= MAX_CANDIDATE_HOSTS) break
+    record.hosts.push(endpoint.host)
+    record.ports[endpoint.host] = endpoint.port
+    record.security[endpoint.host] = endpoint.security
+    dialed.add(key)
+    added += 1
+  }
+  return added
+}
+
 const FILE_MODE = 0o600
 
 /**
@@ -275,6 +365,7 @@ function assertValidRecord(disk: DeviceRecordOnDisk): DeviceRecord {
   }
   assertValidSecurity(disk.hosts, disk.security)
   assertValidPorts(disk.hosts, disk.ports)
+  assertValidForgotten(disk.hosts, disk.forgottenHosts)
 
   // accessToken / tokenExpiresAt live and die together.
   const hasToken = disk.accessToken !== undefined
@@ -363,6 +454,72 @@ function assertValidPorts(hosts: string[], ports: unknown): void {
   }
 }
 
+/**
+ * `forgottenHosts`, when present, must be a list of non-empty strings with no
+ * case-variant duplicates and no overlap with `hosts`.
+ *
+ * Each rule refuses a state whose MEANING is ambiguous: two spellings of one
+ * host make "is this address suppressed?" depend on which entry the comparison
+ * hit first, and a host that is both dialed and forgotten makes the dial list
+ * and the suppression list disagree about the same address. The message names
+ * the offending host — these are addresses an operator chose, not secrets.
+ */
+function assertValidForgotten(hosts: string[], forgotten: unknown): void {
+  if (forgotten === undefined) return
+  if (!Array.isArray(forgotten)) {
+    throw new Error('device archive entry field forgottenHosts must be an array')
+  }
+  const dialed = new Set(hosts.map((host) => host.toLowerCase()))
+  const seen = new Set<string>()
+  for (const entry of forgotten) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      throw new Error('device archive entry field forgottenHosts must list non-empty strings')
+    }
+    const key = entry.toLowerCase()
+    if (seen.has(key)) {
+      throw new Error(`device archive entry lists host "${entry}" in forgottenHosts more than once`)
+    }
+    if (dialed.has(key)) {
+      throw new Error(`device archive entry names host "${entry}" in both hosts and forgottenHosts`)
+    }
+    seen.add(key)
+  }
+}
+
+/**
+ * Repairs ONE cross-build state on the READ path: a host listed in both
+ * `hosts` and `forgottenHosts` (issue #185).
+ *
+ * A build that predates the field PRESERVES it but cannot honour it, so a
+ * downgrade followed by a still-advertising desktop appends the host to
+ * `hosts` while the mark stays. Upgrading again then yields a record that says
+ * both "dial it" and "never dial it". Refusing it would brick every device tool
+ * until an operator hand-edits a 0600 file, so the READ path keeps the DIAL
+ * list — what the running build actually did — and drops the mark, with a
+ * warning naming the device and host (addresses are not secrets).
+ *
+ * The WRITE paths stay strict: `upsert`, `forgetEndpoints` and
+ * `rememberEndpoints` never produce the overlap, and `assertValidRecord`
+ * refuses it. This runs ONLY on the read path, before that assertion.
+ */
+function reconcileForgottenMarks(disk: DeviceRecordOnDisk): DeviceRecordOnDisk {
+  const forgotten = disk.forgottenHosts
+  if (!Array.isArray(forgotten) || !Array.isArray(disk.hosts)) return disk
+  const dialed = new Set(disk.hosts.map((host) => host.toLowerCase()))
+  const kept = forgotten.filter(
+    (host) => !(typeof host === 'string' && dialed.has(host.toLowerCase())),
+  )
+  if (kept.length === forgotten.length) return disk
+  for (const host of forgotten) {
+    if (typeof host !== 'string' || !dialed.has(host.toLowerCase())) continue
+    console.warn(
+      `device archive entry ${String(disk.deviceId)} lists host "${host}" as both dialed and ` +
+        `forgotten; keeping it dialed and dropping the mark (a plugin downgrade can produce this)`,
+    )
+  }
+  return { ...disk, forgottenHosts: kept }
+}
+
 /**
  * Read path, fixed order: loose parse -> completeness gate -> version judgement
  * -> migration -> assert the required `DeviceRecord` type.
@@ -425,7 +582,9 @@ function parseRecord(raw: unknown, archiveVersion: number): DeviceRecord {
     migrated = migrate(migrated)
   }
 
-  return assertValidRecord(migrated)
+  // A cross-build repair, never a write-path policy: see
+  // `reconcileForgottenMarks` for why the read path is the forgiving one.
+  return assertValidRecord(reconcileForgottenMarks(migrated))
 }
 
 function parseArchive(parsed: unknown): ArchiveFile {
@@ -579,6 +738,31 @@ export class QuarantinedArchiveError extends Error {
   }
 }
 
+/**
+ * Refusal raised by {@link DeviceStore.forgetEndpoints} when the operation
+ * would leave a record with NO dial candidate.
+ *
+ * A record with nothing to dial is worse than the stale address the operator
+ * wanted gone: every tool would answer `offline` until a RE-PAIR or a PATCH
+ * with a non-empty `hosts` list writes a fresh one, and the archive would look
+ * healthy the whole time. The check is ATOMIC — the whole call refuses, so a
+ * name for the last host cannot remove a different host on its way to failing.
+ * Nothing is written when this is thrown.
+ */
+export class LastCandidateHostError extends Error {
+  readonly deviceId: string
+
+  constructor(deviceId: string) {
+    super(
+      `device ${deviceId}: refusing to forget the last dial candidate — the record would have ` +
+        'nothing to dial. Keep at least one address.',
+    )
+    this.name = 'LastCandidateHostError'
+    this.deviceId = deviceId
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
 /**
  * Preserves an unreadable archive as `<file>.corrupt` (best effort — a failed
  * copy must not mask the original problem) and returns the path it landed at.
@@ -772,6 +956,135 @@ export class DeviceStore {
     this.#persist(devices)
   }
 
+  /**
+   * Merges freshly learned addresses into one record and writes ONLY when that
+   * record gained a host (issue #143), returning the number added.
+   *
+   * It exists so the enrichment is an ARCHIVE operation rather than an
+   * `upsert` the assembly assembles by hand, and so a merge that adds nothing
+   * never rewrites (and fsyncs) the archive: `connection.endpoints` is asked on
+   * every connect, and a stable desktop would otherwise pay a full atomic write
+   * per reconnect. The merge runs on a CLONE and is committed as a new list,
+   * mirroring `upsert`'s discipline — the store never adopts a caller's object
+   * graph, and a write refused at {@link #persist}'s own gate cannot have
+   * half-edited the record the archive still holds.
+   *
+   * `desktopIdentity` is the pin the answering connection belongs to: the
+   * record must still name that desktop. A RE-PAIR under the same `deviceId`
+   * (the desktop regenerated its identity) would otherwise take an address
+   * learned from the previous pairing — a stale candidate whose every dial then
+   * fails the Noise pin, permanently, because learning never removes.
+   *
+   * An unknown `deviceId` is a no-op — the record may have been removed (or
+   * re-paired) between the RPC and this write.
+   */
+  learnEndpoints(deviceId: string, endpoints: readonly DirectEndpoint[], desktopIdentity: string): number {
+    const devices = this.#load()
+    const index = devices.findIndex((record) => record.deviceId === deviceId)
+    if (index < 0) return 0
+    if (devices[index]!.desktopIdentity !== desktopIdentity) return 0
+    const merged = structuredClone(devices[index]!)
+    const added = mergeAdvertisedEndpoints(merged, endpoints)
+    if (added === 0) return 0
+    const next = [...devices]
+    next[index] = merged
+    this.#persist(next)
+    return added
+  }
+
+  /**
+   * FORGETS addresses (issue #185): drops each named host from the dial list —
+   * host, scheme and port as one unit — and records it so the next
+   * advertisement cannot put it back. Returns the hosts that left the dial list
+   * (`removed`) and the marks this call added (`marked`).
+   *
+   * This is the operation learning cannot provide. `connection.endpoints` is
+   * asked on every handshake, so an address the desktop still advertises
+   * returns after any removal the operator makes by PATCH; forgetting is the
+   * explicit decision that outranks it.
+   *
+   * - Matching is CASE-INSENSITIVE (a PATCHed record keeps the operator's
+   *   spelling, the peer's schema lowercases what it advertises), and the mark
+   *   records the ARCHIVE's spelling when the host was dialed, the caller's
+   *   otherwise.
+   * - Naming an address the record does not dial is legal and still marks it:
+   *   suppression is the point, and a pre-emptive forget must survive until
+   *   the peer advertises the address.
+   * - Removing the LAST candidate throws {@link LastCandidateHostError} and
+   *   writes NOTHING — no host, no scheme, no port, no mark.
+   * - A call that changes no byte (the host was already forgotten) does not
+   *   rewrite (or fsync) the archive.
+   *
+   * The write goes through `#persist` on a CLONE with the result re-validated,
+   * so a caller-supplied junk host can never land a record the next read would
+   * refuse. An unknown `deviceId` is a no-op, like {@link learnEndpoints}.
+   */
+  forgetEndpoints(deviceId: string, hosts: readonly string[]): { removed: string[]; marked: string[] } {
+    const devices = this.#load()
+    const index = devices.findIndex((record) => record.deviceId === deviceId)
+    if (index < 0) return { removed: [], marked: [] }
+    const merged = structuredClone(devices[index]!)
+    const wanted = new Set(hosts.map((host) => host.toLowerCase()))
+    const removed = merged.hosts.filter((host) => wanted.has(host.toLowerCase()))
+    if (removed.length > 0 && removed.length === merged.hosts.length) {
+      throw new LastCandidateHostError(deviceId)
+    }
+    for (const host of removed) {
+      delete merged.security[host]
+      delete merged.ports[host]
+    }
+    merged.hosts = merged.hosts.filter((host) => !wanted.has(host.toLowerCase()))
+    const forgotten = merged.forgottenHosts ?? []
+    const known = new Set(forgotten.map((host) => host.toLowerCase()))
+    const marked: string[] = []
+    for (const host of hosts) {
+      const key = host.toLowerCase()
+      if (known.has(key)) continue
+      const spelling = removed.find((entry) => entry.toLowerCase() === key) ?? host
+      forgotten.push(spelling)
+      known.add(key)
+      marked.push(spelling)
+    }
+    if (removed.length === 0 && marked.length === 0) return { removed: [], marked: [] }
+    merged.forgottenHosts = forgotten
+    assertValidRecord(merged)
+    const next = [...devices]
+    next[index] = merged
+    this.#persist(next)
+    return { removed, marked }
+  }
+
+  /**
+   * Lifts a forget mark (issue #185), returning the marks that were removed.
+   *
+   * It does NOT dial the host again: it only lets the next handshake's
+   * advertisement add it back through the ordinary learning path, with the
+   * port and scheme the peer reports at that moment. An operator who wants the
+   * address back immediately PATCHes it into `hosts`, which clears the mark on
+   * the same write.
+   *
+   * No-op (and no write) when the device is unknown, nothing is forgotten, or
+   * none of the named hosts is marked.
+   */
+  rememberEndpoints(deviceId: string, hosts: readonly string[]): { restored: string[] } {
+    const devices = this.#load()
+    const index = devices.findIndex((record) => record.deviceId === deviceId)
+    if (index < 0) return { restored: [] }
+    const current = devices[index]!.forgottenHosts ?? []
+    if (current.length === 0) return { restored: [] }
+    const wanted = new Set(hosts.map((host) => host.toLowerCase()))
+    const restored = current.filter((host) => wanted.has(host.toLowerCase()))
+    if (restored.length === 0) return { restored: [] }
+    const merged = structuredClone(devices[index]!)
+    merged.forgottenHosts = (merged.forgottenHosts ?? []).filter(
+      (host) => !wanted.has(host.toLowerCase()),
+    )
+    const next = [...devices]
+    next[index] = merged
+    this.#persist(next)
+    return { restored }
+  }
+
   #load(): DeviceRecord[] {
     if (this.#devices !== undefined) return this.#devices
 

package/src/diagnostics.ts

@@ -199,7 +199,7 @@ export interface DiagnosticsDevice {
    * `partsMode: 'paged'`.
    *
    * Its own field, not a fifth key inside `limits`: it is a VERSION, not a
-   * count, and `limits` is documented as the four numeric caps. Present only
+   * count, and `limits` here is the four numeric caps this report CARRIES. Present only
    * when a LIVE connection reported it (the same rule as `limits`: the endpoint
    * never dials to find out). ABSENT therefore means "not advertised **or** not
    * connected" — every desktop through 2.1.7, and any device whose link is
@@ -555,10 +555,11 @@ function projectMessageSummaries(raw: unknown): { messageSummaries?: number } {
 }
 
 /**
- * Re-projects the four numeric limit keys, dropping any foreign key that a
- * caller's `limits` object might carry. A whitelist inside the whitelist: the
- * shape is rebuilt field by field rather than spread, so a future addition to
- * `EffectiveLimits` cannot arrive here unvetted.
+ * Re-projects the four numeric limit keys this report carries, dropping any
+ * foreign key that a caller's `limits` object might carry — including
+ * `EffectiveLimits`' newer `unackedBytes`, which no diagnostics consumer needs.
+ * A whitelist inside the whitelist: the shape is rebuilt field by field rather
+ * than spread, so a future addition cannot arrive here unvetted.
  */
 function projectLimits(raw: unknown): { limits?: EffectiveLimits } {
   if (raw === null || typeof raw !== 'object') return {}