dsh-cherry-bridge 0.1.11 → 0.2.1

package/src/index.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path'
 import { DeviceStore } from './deviceStore.js'
 import { loadOrCreateIdentity } from './identity.js'
 import { DeviceConnection } from './connection.js'
-import type { DeviceState } from './connection.js'
+import type { DeviceState, WsDialOptions } from './connection.js'
 import { DEFAULT_PER_SESSION_CACHE_BYTES, DEFAULT_RATE_BUDGET_PER_SECOND } from './defaults.js'
 import { pairWithPayload } from './pairing.js'
 import { SessionSubscriptions } from './subscriptions.js'
@@ -21,6 +21,7 @@ import type {
 } from './httpApi.js'
 import type { DiagnosticsError } from './diagnostics.js'
 import { truncateErrorMessage } from './diagnostics.js'
+import { boundedJoin, failureText } from './text.js'
 
 export const name = 'cherry-remote'
 
@@ -97,11 +98,25 @@ export interface CherryBridgeConfig {
    * (not a protocol value). Omitted uses {@link DEFAULT_PER_SESSION_CACHE_BYTES}.
    */
   perSessionCacheBytes?: number
+  /**
+   * FLAT `tls.connect` options for every `wss` dial (issue #133): the operator's
+   * TLS trust for a desktop behind a private CA or a self-signed TLS front.
+   * `ws` forwards this bag straight to Node's TLS layer, so `{ ca: <pem> }` and
+   * `{ rejectUnauthorized: false }` belong at the TOP level — the `{ tls: {…} }`
+   * shape (`https`' wrapper) is not recognised by `ws` and is refused here.
+   * Applied to BOTH dial sites: the steady-state pool and pairing.
+   *
+   * NEVER persisted in the record, never logged, never reported: a `ca` is PEM
+   * CONTENT, and trust is a grant the operator makes, not a fact the desktop
+   * asserts about itself.
+   */
+  wsTls?: WsDialOptions
 }
 
 /**
- * The two config values that reach constructor arguments, with their defaults
- * applied.
+ * The plugin-config values that reach constructor arguments, resolved once: the
+ * two numeric budgets with their defaults applied, and the validated TLS trust
+ * bag (see {@link dialOptions}).
  *
  * Resolved ONCE per `apply` and threaded explicitly, rather than re-read at each
  * construction site: a config surface that can change between two constructions
@@ -110,6 +125,7 @@ export interface CherryBridgeConfig {
 export interface ResolvedBridgeConfig {
   rateBudgetPerSecond: number
   perSessionCacheBytes: number
+  wsTls: WsDialOptions | undefined
 }
 
 /**
@@ -130,11 +146,12 @@ export {
   DEFAULT_RATE_BUDGET_PER_SECOND,
 } from './defaults.js'
 
-/** Applies the documented fallbacks to the plugin config's numeric keys. */
+/** Applies the documented fallbacks and validates the plugin config's keys. */
 export function resolveBridgeConfig(config: CherryBridgeConfig = {}): ResolvedBridgeConfig {
   return {
     rateBudgetPerSecond: positive('rateBudgetPerSecond', config.rateBudgetPerSecond, DEFAULT_RATE_BUDGET_PER_SECOND),
     perSessionCacheBytes: positive('perSessionCacheBytes', config.perSessionCacheBytes, DEFAULT_PER_SESSION_CACHE_BYTES),
+    wsTls: dialOptions(config.wsTls),
   }
 }
 
@@ -164,6 +181,104 @@ function positive(key: string, value: unknown, fallback: number): number {
   return value
 }
 
+/** The keys {@link WsDialOptions} carries; anything else is a config mistake. */
+const WS_TLS_KEYS: ReadonlySet<string> = new Set(['rejectUnauthorized', 'ca'])
+
+/** The shape a non-object config value arrived as, for a value-free warning. */
+function shapeOf(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
+
+/**
+ * One `ca` entry: PEM CONTENT for a string, non-empty bytes for a Buffer.
+ *
+ * A string is the certificate TEXT itself, NEVER a file path: `tls.connect`
+ * would happily read whatever path it is handed, so accepting `'/etc/ssl/ca.pem'`
+ * would load bytes the operator never inspected. The header check is a SHAPE
+ * check only — whether the PEM parses beyond `-----BEGIN` is Node's business,
+ * and an unparseable body fails the handshake loudly, which is the honest
+ * verdict. Buffers keep the non-empty test with no header requirement: DER and
+ * programmatically built PEM bytes are legitimate `ca` values.
+ */
+function certificateEntry(value: unknown): boolean {
+  if (typeof value === 'string') return value.trimStart().startsWith('-----BEGIN')
+  if (Buffer.isBuffer(value)) return value.length > 0
+  return false
+}
+
+/**
+ * A configured TLS trust bag, or `undefined` when absent/unusable.
+ *
+ * ABSENT is the documented default (Node's trust store) and says nothing —
+ * exactly like {@link positive}. A key that is PRESENT but unusable is a
+ * deployment mistake that silently changes which peers are reachable, so it is
+ * warned about by name rather than swallowed — but NEVER by value: a `ca` is
+ * PEM CONTENT, and a certificate must not reach a log.
+ *
+ * FAIL CLOSED, WHOLE OBJECT. One unknown or malformed entry discards the WHOLE
+ * bag rather than forwarding the parts that happen to look right. Trust must be
+ * applied AS WRITTEN: a partially applied bag would reach some peers and not
+ * others with nothing telling the operator which half took effect, and their
+ * `ca` intention would be silently replaced by Node's default store. The
+ * fallback is "no override" — the same state as absent.
+ */
+function dialOptions(value: unknown): WsDialOptions | undefined {
+  if (value === undefined) return undefined
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    console.warn(
+      `[cherry-remote] config "wsTls" must be a plain object of flat tls.connect options ` +
+        `(got ${shapeOf(value)}); ignoring it`,
+    )
+    return undefined
+  }
+  const record = value as Record<string, unknown>
+  const unknownKeys = Object.keys(record).filter((key) => !WS_TLS_KEYS.has(key))
+  if (unknownKeys.length > 0) {
+    // The `{ tls: {…} }` wrapper is the common mistake (`https`' shape, which
+    // `ws` ignores), so naming the offending keys points straight at it.
+    console.warn(
+      `[cherry-remote] config "wsTls" carries unsupported key(s) ${unknownKeys.join(', ')}; ` +
+        'only flat rejectUnauthorized / ca are accepted — ignoring the whole object',
+    )
+    return undefined
+  }
+
+  const rejectUnauthorized = record['rejectUnauthorized']
+  if (rejectUnauthorized !== undefined && typeof rejectUnauthorized !== 'boolean') {
+    // FIELD only — a config value never enters the message.
+    console.warn(
+      '[cherry-remote] config "wsTls.rejectUnauthorized" must be a boolean; ignoring the whole object',
+    )
+    return undefined
+  }
+
+  const ca = record['ca']
+  if (ca !== undefined) {
+    const usable = Array.isArray(ca)
+      ? ca.length > 0 && ca.every((entry) => certificateEntry(entry))
+      : certificateEntry(ca)
+    if (!usable) {
+      // FIELD only — never the value: a `ca` is certificate text.
+      console.warn(
+        '[cherry-remote] config "wsTls.ca" must be PEM CONTENT (the certificate text itself, ' +
+          'not a file path) — a "-----BEGIN" string, a non-empty Buffer, or a non-empty array ' +
+          'of those; ignoring the whole object',
+      )
+      return undefined
+    }
+  }
+
+  // `{}` (or an explicit `undefined` value) is the documented default written
+  // out: no override, and no warning.
+  if (rejectUnauthorized === undefined && ca === undefined) return undefined
+  return {
+    ...(rejectUnauthorized === undefined ? {} : { rejectUnauthorized }),
+    ...(ca === undefined ? {} : { ca: ca as WsDialOptions['ca'] }),
+  }
+}
+
 /** The context slice `apply` touches beyond the HTTP face's own services. */
 export interface CherryBridgeContext extends CherryHttpContext, CherryToolsContext {
   effect?(callback: () => () => void): unknown
@@ -213,6 +328,13 @@ interface AssemblyState {
    */
   rateBudgetPerSecond: number
   perSessionCacheBytes: number
+  /**
+   * The current apply's TLS trust bag (issue #133), handed to BOTH dial sites —
+   * the pooled connection and pairing's temporary channel. Held on the state for
+   * the same reason as the two numeric values: a re-apply must move both faces
+   * onto the new config. `undefined` = Node's default trust store.
+   */
+  wsTls: WsDialOptions | undefined
   readonly connections: Map<string, DeviceConnection>
   /**
    * One subscription layer per device, sharing nothing with its siblings: the
@@ -275,6 +397,7 @@ const state: AssemblyState = {
   identityError: undefined,
   rateBudgetPerSecond: DEFAULT_RATE_BUDGET_PER_SECOND,
   perSessionCacheBytes: DEFAULT_PER_SESSION_CACHE_BYTES,
+  wsTls: undefined,
   connections: new Map(),
   subscriptions: new Map(),
   deviceStateListeners: new Set(),
@@ -363,6 +486,22 @@ function connectionFor(deviceId: string): DeviceConnection {
     identity: requireIdentity(),
     record,
     rateBudgetPerSecond: state.rateBudgetPerSecond,
+    // 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) => {
@@ -393,7 +532,18 @@ function connectionFor(deviceId: string): DeviceConnection {
     try {
       subsFor(deviceId).handleNotification(method, params)
     } catch (error) {
-      console.warn(`[cherry-remote] notification "${method}" for ${deviceId} failed`, error)
+      // ONE bounded STRING (issue #161): the old form passed the error OBJECT,
+      // so the console printed the error's name/message/stack with nothing
+      // bounding it. The layer's handler throws for no schema-valid
+      // notification today, but THIS try also calls `subsFor(deviceId)` →
+      // `connectionFor()`, which does throw today (`no device …` when the
+      // record was removed mid-race) — and a future handler throw must not hand
+      // the console an object either. Ceiling: `[cherry-remote] notification "`
+      // (30) + the notification schema's `method` cap (128) + `" for ` (6) +
+      // deviceId + ` failed: ` (9) + LOG_TEXT_MAX (240).
+      console.warn(
+        `[cherry-remote] notification "${method}" for ${deviceId} failed: ${failureText(error)}`,
+      )
     }
   })
   state.connections.set(deviceId, connection)
@@ -526,6 +676,31 @@ function subsFor(deviceId: string): SessionSubscriptions {
   return created
 }
 
+/**
+ * Bounds the link-recovery line's session-id list (issue #155).
+ *
+ * The number of ENTRIES is bounded only by the peer-advertised hello
+ * `subscriptions` — a number the peer chooses, not one this assembly can size —
+ * and a session id is the protocol's `opaqueId` (≤ 256 characters). The old
+ * `sessions.join(', ')` therefore emitted `entries × 258` characters into one
+ * info line: the protocol's own `remoteLimits.subscriptions` = 8 still allows
+ * ~2 KB, and a peer advertising more grows the line with no ceiling at all. The
+ * text is peer-controlled (the ids are echoed back from what the peer accepted
+ * as subscriptions), so it needs a LOCAL bound like every other such log.
+ *
+ * `RECOVERY_SESSIONS_MAX` = 320 is the joined ids' budget: eight normal
+ * 36-char UUIDs render as 8 × 36 + 7 × 2 = 302 characters, so the protocol's
+ * own subscription cap fits WHOLE — the bound bites only on a peer that
+ * advertises more room, or on a malformed over-long id.
+ * `RECOVERY_SESSION_ID_MAX` = 256 is that `opaqueId` cap, so a schema-valid id
+ * is never clipped; only a malformed one is. A list that stops early names the
+ * count (`(+K more)`) and rides ON TOP of the budget; entries are never dropped
+ * silently. The bound is on the LOG only — the loop still re-ensures every
+ * session.
+ */
+const RECOVERY_SESSIONS_MAX = 320
+const RECOVERY_SESSION_ID_MAX = 256
+
 /**
  * The reconnect recovery line (ruling 8): every session this device had
  * subscribed is re-ensured at its LAST cursor, so the peer replays only what
@@ -546,10 +721,16 @@ async function recoverSubscriptions(deviceId: string): Promise<void> {
   const sessions = subscriptions.activeSessions()
   // INFO (spec §5 「订阅建立与恢复」): the recovery line announces what it is
   // about to re-ensure, once per link recovery rather than once per session.
-  // Ids only — a session id is whitelisted, an event payload is not.
+  // Ids only — a session id is whitelisted, an event payload is not. The id
+  // list is bounded by {@link RECOVERY_SESSIONS_MAX} (issue #155); the
+  // `subscription(s)` count above it is the TRUE total, so a clipped list still
+  // says how many sessions are being recovered.
   if (sessions.length > 0) {
     console.info(
-      `[cherry-remote] recovering ${sessions.length} subscription(s) for ${deviceId}: ${sessions.join(', ')}`,
+      `[cherry-remote] recovering ${sessions.length} subscription(s) for ${deviceId}: ${boundedJoin(
+        sessions,
+        { max: RECOVERY_SESSIONS_MAX, itemMax: RECOVERY_SESSION_ID_MAX },
+      )}`,
     )
   }
 
@@ -566,7 +747,15 @@ async function recoverSubscriptions(deviceId: string): Promise<void> {
           (cursor === undefined ? '' : ` at seq ${cursor.seq}`),
       )
     } catch (error) {
-      console.warn(`[cherry-remote] re-subscribing session ${sessionId} of ${deviceId} failed`, error)
+      // ONE bounded STRING (issue #161). The catch is peer-triggered:
+      // `ensure` subscribes over the live link, and its failure message is the
+      // peer's JSON-RPC `error.message` verbatim (up to the 512-char failure
+      // schema cap) or a transport message. The old form handed the error
+      // OBJECT to the console, which then printed the stack plus every own
+      // property unbounded.
+      console.warn(
+        `[cherry-remote] re-subscribing session ${sessionId} of ${deviceId} failed: ${failureText(error)}`,
+      )
     }
   }
 }
@@ -603,6 +792,11 @@ function assemblyDeps(): CherryHttpDeps & CherryToolsDeps {
         payload: request.payload,
         store: state.store,
         ...(request.name === undefined ? {} : { name: request.name }),
+        // The same operator TLS trust the steady-state dial uses (issue #133):
+        // a desktop behind a private CA must be pairABLE over `wss` as well as
+        // reconnectable. Read from the assembly state, never from `request`: a
+        // caller cannot supply trust.
+        ...(state.wsTls === undefined ? {} : { wsOptions: state.wsTls }),
         onVerificationCode: request.onVerificationCode,
         // Pair bridging (ruling 10): the call site's stages reach the assembly's
         // progress fan-out, which is what the SSE route consumes.
@@ -715,6 +909,7 @@ export function apply(ctx: CherryBridgeContext, config: CherryBridgeConfig = {})
   const bridgeConfig = resolveBridgeConfig(config)
   state.rateBudgetPerSecond = bridgeConfig.rateBudgetPerSecond
   state.perSessionCacheBytes = bridgeConfig.perSessionCacheBytes
+  state.wsTls = bridgeConfig.wsTls
   state.store = new DeviceStore(join(dataDir, 'devices.json'))
 
   // A re-apply is a fresh assembly: the previous run's error summaries and