dsh-conversation-recycle-bin 0.2.0 → 0.2.2

package/lib/host/api.js

@@ -17,6 +17,13 @@
  *   POST /trash/discard             remove an entry that never committed
  *   GET  /audit?limit=N             audit trail tail
  *
+ * Transport layers, in order: this route's own loopback/origin fence, then DSH's
+ * `connection` fence (`requestRejection`) when the service exists, then the
+ * `connection/request` waterfall — which is what makes the desktop app-update
+ * lock (503 + drain) cover deletions instead of killing them mid-transaction.
+ * Mutations additionally take a cross-process lock on `<dataDir>/mutation.lock`
+ * so two Hosts sharing one DSH_HOME cannot write the same manifest at once.
+ *
  * Confirmation is a two-part server-side protocol, not a Client-side courtesy:
  * `/preview` issues a single-use token bound to (session ids, includeMemory,
  * mode); `/delete` must present that token. An additional typed phrase is
@@ -25,7 +32,8 @@
  * A replayed, edited or expired plan is refused.
  */
 import { randomBytes } from 'node:crypto'
-import { readdir, stat } from 'node:fs/promises'
+import { mkdir, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
 import { DeleteError, ERROR_STATUS, asDeleteError, toWireError } from '../core/errors.js'
 import { createAuditLog } from '../core/audit.js'
 import { createTrashStore } from '../core/trash.js'
@@ -33,6 +41,7 @@ import { createMemoryService } from '../core/memory/registry.js'
 import { performSessionDelete, performPurge, performRestore, performDiscard } from '../core/cascade.js'
 import { evaluateSessionPolicy } from '../core/policy.js'
 import { createSlidingWindowLimiter } from '../core/rate-limit.js'
+import { createFileLock } from '../core/file-lock.js'
 import { createCatalogOps, createSessionLogOps } from './catalog.js'
 import { createLifecycleOps } from './lifecycle.js'
 import { createSessionGateway } from './gateway.js'
@@ -42,7 +51,9 @@ import { PLUGIN_VERSION } from '../version.js'
 export const ROUTE_PREFIX = '/conversation-recycle-bin/api'
 export const REQUIRED_HEADER = 'x-conversation-recycle-bin'
 const MAX_BODY_BYTES = 256 * 1024
-const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{6,80}$/
+// DSH's `encodeSegment` allows `.`, `_`, `-`; forked/custom ids can contain a
+// dot, so refusing one made those conversations undeletable.
+const SESSION_ID_PATTERN = /^[A-Za-z0-9._-]{6,80}$/
 
 function isLoopbackHostname(hostname) {
   const value = String(hostname ?? '').trim().toLowerCase().replace(/^\[|\]$/g, '')
@@ -69,8 +80,34 @@ function sameHostname(left, right) {
   return normalize(left) === normalize(right)
 }
 
+/** Port of a `Host`-style authority, or `''` when none is present. */
+function portOf(hostHeader) {
+  const value = String(hostHeader ?? '').trim()
+  if (value.startsWith('[')) {
+    const end = value.indexOf(']')
+    if (end === -1) return ''
+    const rest = value.slice(end + 1)
+    return rest.startsWith(':') && /^\d+$/.test(rest.slice(1)) ? rest.slice(1) : ''
+  }
+  const colon = value.lastIndexOf(':')
+  return colon > 0 && /^\d+$/.test(value.slice(colon + 1)) ? value.slice(colon + 1) : ''
+}
+
+/** The port a URL implies when it omits one. */
+function defaultPortFor(protocol) {
+  if (protocol === 'https:' || protocol === 'wss:') return '443'
+  return '80'
+}
+
 /**
  * Origin/Host verdict for one request.
+ *
+ * Hostname alone is not an origin: `http://localhost:9999` served by ANY other
+ * loopback process used to pass a Host-name comparison, so a second local web
+ * app could drive deletions. The full authority — hostname AND effective port —
+ * must match, with a missing port normalized against the Origin's own scheme
+ * (the `Host` header carries no scheme, so `https://host` and `Host: host`
+ * both mean 443).
  * @returns {{ ok: true } | { ok: false, error: DeleteError }}
  */
 export function requestOriginVerdict(headers, { requireSameOrigin, allowNonLoopback }) {
@@ -95,20 +132,27 @@ export function requestOriginVerdict(headers, { requireSameOrigin, allowNonLoopb
   if (requireSameOrigin) {
     const origin = read('origin').trim()
     if (origin !== '') {
-      let originHostname = ''
-      let trustedAppShell = false
+      let parsed = null
       try {
-        const parsed = new URL(origin)
-        originHostname = parsed.hostname.toLowerCase()
-        // The Electron shell serves the page from a private scheme and
-        // forwards the request to this same Host; no web origin can produce
-        // that scheme, so it is safe to trust it as same-origin.
-        trustedAppShell = parsed.protocol === 'dsh-app:'
+        parsed = new URL(origin)
       } catch {
-        originHostname = ''
+        parsed = null
       }
-      if (trustedAppShell !== true && (originHostname === '' || !sameHostname(originHostname, requestHostname))) {
-        return { ok: false, error: new DeleteError('E_FORBIDDEN_ORIGIN', 'The request origin does not match this Host.', { origin }) }
+      // The Electron shell serves the app from `dsh-app://app` and the Host's
+      // own fences compare against exactly this origin (verified in the shipped
+      // app: `out/lib/main.js` refuses `origin !== "dsh-app://app"`). No web
+      // origin can mint that scheme, so it is trusted as same-origin. On the
+      // real desktop route the shell's forwarder deletes the `Origin` header
+      // before the request reaches the Host, so this is defense-in-depth.
+      const trustedAppShell = parsed !== null && parsed.protocol === 'dsh-app:' && parsed.hostname === 'app'
+      if (trustedAppShell !== true) {
+        const requestPort = portOf(read('host'))
+        const originPort = parsed === null ? '' : (parsed.port === '' ? defaultPortFor(parsed.protocol) : parsed.port)
+        const hostnameMatches = parsed !== null && parsed.hostname !== '' && sameHostname(parsed.hostname, requestHostname)
+        const portMatches = originPort !== '' && originPort === (requestPort === '' ? originPort : requestPort)
+        if (!hostnameMatches || !portMatches) {
+          return { ok: false, error: new DeleteError('E_FORBIDDEN_ORIGIN', 'The request origin does not match this Host.', { origin }) }
+        }
       }
     }
   }
@@ -160,9 +204,21 @@ function readJsonBody(req) {
   return new Promise((resolve, reject) => {
     let bytes = 0
     let overflow = false
+    let settled = false
     const chunks = []
+    // The promise MUST settle on every path: an unsettled `/delete` inside
+    // `serialize()` parks every later mutation behind it until the Host is
+    // restarted. `aborted`/`close` fires when the Client disconnects mid-body
+    // (its own timeout, or the tab/app closing) and `end` may never come.
+    const finish = (error, value) => {
+      if (settled) return
+      settled = true
+      if (error !== undefined) reject(error)
+      else resolve(value)
+    }
     req.setEncoding('utf8')
     req.on('data', (chunk) => {
+      if (settled) return
       if (overflow) return
       bytes += Buffer.byteLength(chunk, 'utf8')
       if (bytes > MAX_BODY_BYTES) {
@@ -172,26 +228,38 @@ function readJsonBody(req) {
       }
       chunks.push(chunk)
     })
-    req.on('error', reject)
+    req.on('error', (error) => {
+      finish(new DeleteError('E_BAD_REQUEST', 'The request stream failed.', {}, { cause: error }))
+    })
+    req.on('aborted', () => {
+      finish(new DeleteError('E_BAD_REQUEST', 'The request was aborted before its body arrived.', {}))
+    })
+    req.on('close', () => {
+      // `close` after a complete `end` is the normal path; without it the
+      // stream was cut short.
+      if (!settled) {
+        finish(new DeleteError('E_BAD_REQUEST', 'The request was closed before its body arrived.', {}))
+      }
+    })
     req.on('end', () => {
       if (overflow) {
-        reject(new DeleteError('E_BAD_REQUEST', 'Request body exceeds the size limit.', { limit: MAX_BODY_BYTES }, { httpStatus: 413 }))
+        finish(new DeleteError('E_BAD_REQUEST', 'Request body exceeds the size limit.', { limit: MAX_BODY_BYTES }, { httpStatus: 413 }))
         return
       }
       const raw = chunks.join('').trim()
       if (raw === '') {
-        resolve({})
+        finish(undefined, {})
         return
       }
       try {
         const parsed = JSON.parse(raw)
         if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-          reject(new DeleteError('E_BAD_REQUEST', 'Request body must be a JSON object.', {}))
+          finish(new DeleteError('E_BAD_REQUEST', 'Request body must be a JSON object.', {}))
           return
         }
-        resolve(parsed)
+        finish(undefined, parsed)
       } catch (error) {
-        reject(new DeleteError('E_BAD_REQUEST', 'Request body is not valid JSON.', {}, { cause: error }))
+        finish(new DeleteError('E_BAD_REQUEST', 'Request body is not valid JSON.', {}, { cause: error }))
       }
     })
   })
@@ -215,8 +283,12 @@ function sendJson(res, status, payload) {
  * @param {object} input.paths resolution from `host/paths.js`
  * @param {() => number} [input.now]
  * @param {Pick<Console, 'error'|'warn'|'info'>} [input.logger]
+ * @param {{ acquire: () => Promise<() => Promise<void>>, lockPath?: string }} [input.mutationLock]
+ *   Cross-process lock serializing mutations. Injectable so a test can drive the
+ *   E_LOCK_BUSY path with a short wait budget; production uses 30s because a
+ *   deletion transaction legitimately takes a while and waiting beats failing.
  */
-export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = console }) {
+export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = console, mutationLock = null }) {
   const gateway = createSessionGateway({ ctx, paths, now })
   const memoryService = createMemoryService({
     adapters: createMemoryAdapters({ config, dshHome: paths.dshHome, now }),
@@ -231,6 +303,19 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     now,
   })
   const limiter = createSlidingWindowLimiter({ limit: config.maxDeletesPerMinute, windowMs: 60_000, now })
+  // Two Hosts can share one DSH_HOME (the desktop app and `dsh web`), and both
+  // write the same trash manifests, bundles and audit trail. The in-process
+  // `serialize` chain below cannot see the other one, so every mutation also
+  // takes a cross-process advisory lock on `<dataDir>/mutation.lock`. A busy
+  // lock surfaces as E_LOCK_BUSY (409) instead of a lost manifest update.
+  const mutationLockInstance = mutationLock ?? createFileLock({
+    lockPath: join(paths.dataDir, 'mutation.lock'),
+    timeoutMs: 30_000,
+    staleMs: 120_000,
+  })
+  // Which UI asked: the desktop Electron shell and `dsh web` share this code,
+  // and the audit trail used to record both as `web-ui`.
+  const auditSource = process.versions?.electron !== undefined ? 'desktop-ui' : 'web-ui'
   const ops = {
     memory: memoryService,
     sessionLog: createSessionLogOps({ gateway, paths, config, now, logger }),
@@ -260,8 +345,31 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
   let mutationChain = Promise.resolve()
   let requestCounter = 0
 
+  /**
+   * Serialize one mutation: in-process first (so two HTTP requests never
+   * interleave their transactions), then across processes (so a second Host
+   * sharing this DSH_HOME cannot write the same manifest concurrently).
+   */
   function serialize(operation) {
-    const next = mutationChain.then(operation, operation)
+    const next = mutationChain.then(async () => {
+      // The lock lives in the data dir, which a fresh install has not created
+      // yet (the trash store and audit log mkdir their own targets lazily).
+      await mkdir(paths.dataDir, { recursive: true }).catch(() => {})
+      let release
+      try {
+        release = await mutationLockInstance.acquire()
+      } catch (error) {
+        if (error?.code === 'E_LOCK_BUSY') {
+          throw new DeleteError('E_LOCK_BUSY', 'Another DSH instance is using this recycle bin; retry in a moment.', {})
+        }
+        throw error
+      }
+      try {
+        return await operation()
+      } finally {
+        await release()
+      }
+    })
     mutationChain = next.then(() => undefined, () => undefined)
     return next
   }
@@ -389,6 +497,14 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     const adapterStates = await memoryService.status()
     const confirmation = blocked.length === 0 ? issueConfirmation({ sessionIds, includeMemory, mode }) : null
 
+    // Worst-case wall time for the matching `/delete`: one lock acquisition,
+    // plus per live session a bounded drain, plus per session the memory
+    // export/restore under the plugin-private lock. The Client MUST use this
+    // instead of its own estimate, otherwise it aborts while the Host is still
+    // deleting and retries into an in-flight transaction.
+    const liveCount = sessions.filter((item) => item.live === true).length
+    const planTimeoutMs = Math.min(900_000, 15_000 + sessionIds.length * 16_000 + liveCount * config.liveDrainMs)
+
     return {
       sessions,
       blocked,
@@ -410,6 +526,7 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
         rate: limiter.status(),
         trashRetentionDays: config.trashRetentionDays,
         confirmTokenTtlMs: config.confirmTokenTtlMs,
+        planTimeoutMs,
       },
     }
   }
@@ -467,7 +584,7 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
           includeMemory,
           actor: 'local-user',
           refusals,
-          source: 'web-ui',
+          source: auditSource,
         })
         .catch(() => {})
       // Report the ACTUAL first refusal. The wire code is what the Client
@@ -504,6 +621,7 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
           config,
           now,
           actor: 'local-user',
+          source: auditSource,
           requestId: request,
         })
         results.push({
@@ -533,7 +651,7 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     if (typeof trashId !== 'string' || trashId === '') throw new DeleteError('E_BAD_REQUEST', 'A recycle-bin id is required.', {})
     const entry = await trash.read(trashId)
     if (entry === null) throw new DeleteError('E_TRASH_NOT_FOUND', 'The recycle-bin entry was not found.', { trashId })
-    const result = await performRestore({ entry, ops, trash, audit, now, actor: 'local-user', requestId: requestId() })
+    const result = await performRestore({ entry, ops, trash, audit, now, actor: 'local-user', source: auditSource, requestId: requestId() })
     gateway.invalidate()
     return result
   }
@@ -548,7 +666,7 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     // Purging a soft entry performs the missing hard stages on a still-live
     // session. The cascade's quiesce step stops that session first; if it
     // cannot be stopped within liveDrainMs, the purge fails and rolls back.
-    const result = await performPurge({ entry, ops, trash, audit, now, actor: 'local-user', requestId: requestId() })
+    const result = await performPurge({ entry, ops, trash, audit, now, actor: 'local-user', source: auditSource, requestId: requestId() })
     gateway.invalidate()
     return result
   }
@@ -565,7 +683,7 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     }
     const entry = await trash.read(trashId)
     if (entry === null) throw new DeleteError('E_TRASH_NOT_FOUND', 'The recycle-bin entry was not found.', { trashId })
-    return performDiscard({ entry, ops, trash, audit, now, actor: 'local-user', requestId: requestId() })
+    return performDiscard({ entry, ops, trash, audit, now, actor: 'local-user', source: auditSource, requestId: requestId() })
   }
 
   async function state() {
@@ -594,19 +712,31 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
   async function sessionsForUi() {
     const sessions = await gateway.list()
     await gateway.enrichTitles(sessions)
-    return sessions.map((session) => ({
-      id: session.id,
-      title: session.title,
-      cwd: session.cwd,
-      updatedAt: session.updatedAt,
-      running: session.running,
-      live: session.live,
-      blank: session.blank,
-      archived: session.archived,
-      pinned: session.pinned,
-      origin: session.origin,
-      workspace: session.workspaceId === null ? null : { id: session.workspaceId },
-    }))
+    // Every row carries its own policy verdict: "select all" used to include
+    // subagent/orphan/out-of-root conversations that `/preview` then refuses
+    // as a whole batch, leaving the user with a disabled button and no hint
+    // which row to uncheck. Soft mode is the widest verdict (hard adds only
+    // the live-session stop), so a row marked deletable here stays deletable.
+    return sessions.map((session) => {
+      const verdict = evaluateSessionPolicy({ session, workspace: session.workspace, live: session.live, mode: 'soft', config })
+      return {
+        id: session.id,
+        title: session.title,
+        cwd: session.cwd,
+        updatedAt: session.updatedAt,
+        running: session.running,
+        live: session.live,
+        blank: session.blank,
+        archived: session.archived,
+        pinned: session.pinned,
+        origin: session.origin,
+        workspace: session.workspaceId === null ? null : { id: session.workspaceId },
+        deletable: verdict.ok,
+        policy: verdict.ok
+          ? { ok: true, warnings: verdict.warnings }
+          : { ok: false, code: verdict.error.code, message: verdict.error.message },
+      }
+    })
   }
 
   function serializeEntry(entry) {
@@ -644,20 +774,43 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     return { records: result.records, malformed: result.malformed }
   }
 
-  /** One request → one response. Route matching stays here, not in `apply`. */
-  const handler = (req, res) => {
-    void (async () => {
-      const method = String(req.method ?? 'GET').toUpperCase()
-      const url = new URL(req.url ?? '/', 'http://host.invalid')
-      const path = url.pathname.startsWith(ROUTE_PREFIX) ? url.pathname.slice(ROUTE_PREFIX.length) : url.pathname
+  /**
+   * The plugin's own transport fence: loopback-only unless `allowNonLoopback`,
+   * no cross-site requests, and — when `requireSameOrigin` — an Origin whose
+   * full authority (hostname AND effective port) matches the request Host, or
+   * the desktop `dsh-app://app` shell origin.
+   *
+   * This is the FIRST gate. The `connection` fence in `handler` is
+   * authoritative when present; this one keeps the route safe in a composition
+   * without it and produces the localized error codes the Client knows.
+   */
+  function transportVerdict(req) {
+    return requestOriginVerdict(req.headers, config)
+  }
 
-      const origin = requestOriginVerdict(req.headers, config)
-      if (!origin.ok) {
-        sendJson(res, origin.error.httpStatus, toWireError(origin.error))
-        return
-      }
+  /** Read the connection service without declaring it a hard dependency. */
+  function connectionService() {
+    try {
+      const value = typeof ctx.get === 'function' ? ctx.get('connection') : ctx.connection
+      return value ?? undefined
+    } catch {
+      return undefined
+    }
+  }
 
-      try {
+  /** One request → one response. Route matching stays here, not in `apply`. */
+  const handleRequest = async (req, res) => {
+    const method = String(req.method ?? 'GET').toUpperCase()
+    const url = new URL(req.url ?? '/', 'http://host.invalid')
+    const path = url.pathname.startsWith(ROUTE_PREFIX) ? url.pathname.slice(ROUTE_PREFIX.length) : url.pathname
+
+    const origin = transportVerdict(req)
+    if (!origin.ok) {
+      sendJson(res, origin.error.httpStatus, toWireError(origin.error))
+      return
+    }
+
+    try {
         if (method === 'GET' && (path === '' || path === '/state')) {
           sendJson(res, 200, { ok: true, state: await state() })
           return
@@ -715,11 +868,55 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
           sendJson(res, 200, { ok: true, ...result })
           return
         }
-        throw new DeleteError('E_NOT_FOUND', 'Unknown endpoint.', { path: path.slice(0, 120) })
-      } catch (error) {
-        const normalized = asDeleteError(error)
-        logger.error?.(`[conversation-recycle-bin] ${method} ${path}: ${normalized.code} ${normalized.message}`)
-        sendJson(res, normalized.httpStatus, toWireError(normalized))
+      throw new DeleteError('E_NOT_FOUND', 'Unknown endpoint.', { path: path.slice(0, 120) })
+    } catch (error) {
+      const normalized = asDeleteError(error)
+      logger.error?.(`[conversation-recycle-bin] ${method} ${path}: ${normalized.code} ${normalized.message}`)
+      sendJson(res, normalized.httpStatus, toWireError(normalized))
+    }
+  }
+
+  /**
+   * Route entry point.
+   *
+   * The plugin mounts a `webServer` prefix directly, so it does NOT pass
+   * through `/api` and therefore bypasses DSH's `connection` layer by default.
+   * That layer is not cosmetic: `connection.admit()` applies the Host/Origin
+   * fence and the browser-session admission, and the desktop update task
+   * control listens on `connection/request` to refuse new requests (503) and
+   * drain in-flight ones while an app update installs. Without participating,
+   * an update or a quit could kill a Host in the middle of a deletion
+   * transaction.
+   *
+   * The service is probed, not injected: a composition without `connection`
+   * keeps working behind this route's own loopback/origin fence.
+   */
+  const handler = (req, res) => {
+    void (async () => {
+      const connection = connectionService()
+      if (connection !== undefined && typeof connection.requestRejection === 'function') {
+        let rejection
+        try {
+          rejection = connection.requestRejection(req)
+        } catch {
+          rejection = undefined
+        }
+        if (rejection === 401 || rejection === 403) {
+          const error = rejection === 401
+            ? new DeleteError('E_UNAUTHORIZED', 'This request is not authenticated with the Host.', {})
+            : new DeleteError('E_FORBIDDEN_ORIGIN', 'The Host refused this request at the connection layer.', {})
+          sendJson(res, rejection, toWireError(error))
+          return
+        }
+      }
+      const run = () => handleRequest(req, res)
+      if (typeof ctx.waterfall === 'function') {
+        // Listeners (e.g. the desktop update lock) run outermost-first and may
+        // veto by never calling `next()`; when none is registered the built-in
+        // `run` executes directly.
+        await ctx.waterfall('connection/request', req, res, run)
+      } else {
+        await run()
       }
     })().catch((error) => {
       logger.error?.('[conversation-recycle-bin] route failure:', error)