@mulmobridge/chat-service 0.1.6 → 1.0.0

package/dist/atomic-write.js

@@ -1,9 +1,19 @@
 // Lightweight atomic write — write to a sibling tmp file, then rename.
 //
-// Inlined in this package (not imported from the host app) so
-// @mulmobridge/chat-service stays dependency-free beyond protocol.
-// Same contract as the host's writeFileAtomic: readers always see
-// either the old file or the new file — never a half-written one.
+// A DELIBERATE second implementation of `writeFileAtomic`, catalogued as such
+// in `docs/shared-utils.md`. The canonical one is
+// `@mulmoclaude/core/files` — but this package sits in the bridge tier, below
+// core, so importing it would be an uphill edge; and the helper needs
+// `node:fs`, which rules out the browser-safe `@mulmoclaude/common` leaf that
+// `errorMessage` / `escapeHtml` live in. @mulmobridge/chat-service therefore
+// stays dependency-free beyond protocol.
+//
+// This is a SMALLER contract, not a drifted one: no `mode`, no `uniqueTmp`.
+// Same core guarantee as the canonical — readers always see either the old
+// file or the new file, never a half-written one — but without the canonical's
+// Windows AV/Search-Indexer rename-retry loop, so a Windows-hosted bridge can
+// still surface an EPERM here. Fix bugs in the canonical first, then decide
+// whether this copy needs the same change.
 import { writeFile, rename, unlink, mkdir } from "fs/promises";
 import path from "path";
 import { randomUUID } from "crypto";

package/dist/chat-state.d.ts

@@ -22,6 +22,15 @@ export interface ChatStateStore {
     connectSession(transportId: string, externalChatId: string, chatSessionId: string, roleId?: string): Promise<TransportChatState | null>;
     generateSessionId(transportId: string, externalChatId: string): string;
 }
+/** True iff `sessionId` is safe to persist into transport state and later
+ *  hand to session-metadata / event-log readers on the host side. Adds an
+ *  explicit `..` rejection on top of `isSafeId` — the safe-id character
+ *  class alone would accept the literal `..` and let a state file written
+ *  by `/connect` poison downstream commands (e.g. `/history` reading the
+ *  poisoned sessionId back through `readSessionJsonl`). Applied at the
+ *  `/connect` route entry AND inside `connectSession` as defense-in-depth
+ *  (issue #1896 follow-up to #1888 / #1895). */
+export declare function isSafeSessionId(sessionId: string): boolean;
 export declare function createChatStateStore(opts: {
     transportsDir: string;
     logger: Logger;

package/dist/chat-state.js

@@ -15,6 +15,23 @@ import { writeFileAtomic } from "./atomic-write.js";
 function isSafeId(id) {
     return /^[\w.-]+$/.test(id) && id.length > 0 && id.length <= 200;
 }
+/** True iff `sessionId` is safe to persist into transport state and later
+ *  hand to session-metadata / event-log readers on the host side. Adds an
+ *  explicit `..` rejection on top of `isSafeId` — the safe-id character
+ *  class alone would accept the literal `..` and let a state file written
+ *  by `/connect` poison downstream commands (e.g. `/history` reading the
+ *  poisoned sessionId back through `readSessionJsonl`). Applied at the
+ *  `/connect` route entry AND inside `connectSession` as defense-in-depth
+ *  (issue #1896 follow-up to #1888 / #1895). */
+export function isSafeSessionId(sessionId) {
+    if (typeof sessionId !== "string")
+        return false;
+    if (!isSafeId(sessionId))
+        return false;
+    if (sessionId.includes(".."))
+        return false;
+    return true;
+}
 // ── Factory ──────────────────────────────────────────────────
 export function createChatStateStore(opts) {
     const { transportsDir, logger } = opts;
@@ -58,6 +75,18 @@ export function createChatStateStore(opts) {
         return state;
     };
     const connectSession = async (transportId, externalChatId, chatSessionId, roleId) => {
+        // Defense-in-depth: even though the /connect route validates chatSessionId
+        // at entry, refuse to persist an unsafe value here too. Otherwise a caller
+        // that bypasses the route (test harness, alternate transport, direct store
+        // access) could still write a hostile sessionId into the state file — and
+        // downstream commands like /history would later read that back into
+        // path-traversing filesystem operations. Return null so the route surfaces
+        // it as 404 (same as "no state for this chat"); either way the caller
+        // can't succeed with a hostile input. Issue #1896.
+        if (!isSafeSessionId(chatSessionId)) {
+            logger.warn("chat-state", "refused to connect unsafe sessionId", { transportId, externalChatId });
+            return null;
+        }
         const existing = await getChatState(transportId, externalChatId);
         if (!existing)
             return null;

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import type { BridgeSkillSummary, Role, SessionSummary } from "./types.js";
+import type { BridgeSkillSummary, GetSessionHistoryFn, ListSessionsFn, Role } from "./types.js";
 import type { ChatStateStore, TransportChatState } from "./chat-state.js";
 export interface CommandResult {
     reply: string;
@@ -41,23 +41,8 @@ export declare function createCommandHandler(opts: {
     getRole: (roleId: string) => Role;
     resetChatState: ChatStateStore["resetChatState"];
     connectSession: ChatStateStore["connectSession"];
-    listSessions?: (opts: {
-        limit: number;
-        offset: number;
-    }) => Promise<{
-        sessions: SessionSummary[];
-        total: number;
-    }>;
-    getSessionHistory?: (sessionId: string, opts: {
-        limit: number;
-        offset: number;
-    }) => Promise<{
-        messages: Array<{
-            source: string;
-            text: string;
-        }>;
-        total: number;
-    }>;
+    listSessions?: ListSessionsFn;
+    getSessionHistory?: GetSessionHistoryFn;
     /** Lists the skills the bridge command handler should expose.
      *  Drives both the slash-command allowlist (only matching names
      *  are forwarded to the agent) and the "Skills:" section in the

package/dist/index.d.ts

@@ -16,5 +16,5 @@ export interface ChatService {
     pushToBridge: PushFn;
 }
 export declare function createChatService(deps: ChatServiceDeps): ChatService;
-export type { ChatServiceDeps, StartChatFn, OnSessionEventFn } from "./types.js";
+export type { Attachment, ChatServiceDeps, StartChatFn, StartChatParams, OnSessionEventFn } from "./types.js";
 export { writeFileAtomic } from "./atomic-write.js";

package/dist/index.js

@@ -17,7 +17,7 @@
 // standalone npm package without internal edits. See #269 / #305.
 import { Router } from "express";
 import { CHAT_SERVICE_ROUTES } from "@mulmobridge/protocol";
-import { createChatStateStore } from "./chat-state.js";
+import { createChatStateStore, isSafeSessionId } from "./chat-state.js";
 import { createCommandHandler } from "./commands.js";
 import { createRelay } from "./relay.js";
 import { createPushQueue } from "./push-queue.js";
@@ -97,6 +97,17 @@ export function createChatService(deps) {
             badRequest(res, "chatSessionId is required");
             return;
         }
+        // Reject hostile / malformed sessionIds at the entry so they can't be
+        // persisted into transport state. Without this gate a caller could POST
+        // `{"chatSessionId": "../../etc/x"}`, the value would land in the state
+        // file, and a later `/history` command would read it back and hand it to
+        // `readSessionJsonl` — whose backing reader is documented as "internal
+        // fixed paths only, no `..` traversal guard". Also defended inside
+        // `connectSession` for defense-in-depth (issue #1896 follow-up to #1895).
+        if (!isSafeSessionId(chatSessionId)) {
+            badRequest(res, "chatSessionId has an unsafe format");
+            return;
+        }
         // Resolve the target session's role BEFORE calling connectSession so the
         // persisted state's `roleId` tracks the new session's role — otherwise the
         // next relay's `startChat` would resume the new session under the previous

package/dist/types.d.ts

@@ -1,35 +1,20 @@
+import type { Attachment } from "@mulmobridge/protocol";
+export type { Attachment };
 export interface Role {
     id: string;
     name: string;
 }
+/** Structurally identical to `StructuredLogger` in `@mulmoclaude/common`, where
+ *  the rest of that family was folded (#2486). This one stays local: rule 2 only
+ *  exempts a DECLARED package dependency, and this package's sole dependency is
+ *  `@mulmobridge/protocol` — adding common would give a published
+ *  `@mulmobridge/*` package its first `@mulmoclaude/*` edge, for a type. */
 export interface Logger {
     error(prefix: string, message: string, data?: Record<string, unknown>): void;
     warn(prefix: string, message: string, data?: Record<string, unknown>): void;
     info(prefix: string, message: string, data?: Record<string, unknown>): void;
     debug(prefix: string, message: string, data?: Record<string, unknown>): void;
 }
-/** A file attached to a bridge or UI message. Generic enough for
- *  images, PDFs, documents, videos, etc. The server decides what to
- *  do with each based on mimeType — images become vision content
- *  blocks, unsupported types are ignored with a log.
- *
- *  Either `data` (inline base64 bytes) or `path` (workspace-relative
- *  path the server can read) MUST be set:
- *
- *    - Bridges over the socket transport ship raw bytes, so they
- *      populate `data` (and usually `mimeType`).
- *    - The Vue UI uploads paste/drop and sidebar-pick files to disk
- *      before sending and populates `path`; the server reads bytes
- *      from disk and infers `mimeType` from the extension.
- *
- *  Mirrors `@mulmobridge/protocol`'s `Attachment` (kept structurally
- *  duplicated here per the package-contract rules in this file). */
-export interface Attachment {
-    mimeType?: string;
-    data?: string;
-    path?: string;
-    filename?: string;
-}
 export interface StartChatParams {
     message: string;
     roleId: string;
@@ -75,6 +60,25 @@ export interface SessionSummary {
     preview: string;
     updatedAt: string;
 }
+/** List recent sessions (paged). Backs the `/sessions` bridge command. */
+export type ListSessionsFn = (opts: {
+    limit: number;
+    offset: number;
+}) => Promise<{
+    sessions: SessionSummary[];
+    total: number;
+}>;
+/** Recent messages in a session (paged, newest-first). Backs `/history`. */
+export type GetSessionHistoryFn = (sessionId: string, opts: {
+    limit: number;
+    offset: number;
+}) => Promise<{
+    messages: Array<{
+        source: string;
+        text: string;
+    }>;
+    total: number;
+}>;
 export interface ChatServiceDeps {
     /** Relay a user turn into the agent loop. */
     startChat: StartChatFn;
@@ -101,27 +105,12 @@ export interface ChatServiceDeps {
      * Omit if session listing is not available (command will reply
      * "not available").
      */
-    listSessions?: (opts: {
-        limit: number;
-        offset: number;
-    }) => Promise<{
-        sessions: SessionSummary[];
-        total: number;
-    }>;
+    listSessions?: ListSessionsFn;
     /**
      * Get recent messages from a session. Used by /history command.
      * Returns newest-first array of {source, text} pairs.
      */
-    getSessionHistory?: (sessionId: string, opts: {
-        limit: number;
-        offset: number;
-    }) => Promise<{
-        messages: Array<{
-            source: string;
-            text: string;
-        }>;
-        total: number;
-    }>;
+    getSessionHistory?: GetSessionHistoryFn;
     /**
      * Resolve the roleId a given session was started with. Used by the HTTP
      * `/connect` route so the persisted bridge state's role tracks the target

package/dist/types.js

@@ -10,7 +10,10 @@
 //     host app uses. They look like the real `Role` / `Logger` /
 //     `StartChatParams` types so the same functions plug in, but
 //     they are defined here so the package has no compile-time
-//     link back to the host.
+//     link back to the host. Importing from a declared package
+//     dependency is fine — `Attachment` comes from
+//     `@mulmobridge/protocol` (already a runtime dep) rather than
+//     being redeclared here (#2488).
 //  3. When you add a new dependency, extend `ChatServiceDeps` and
 //     thread it through the factory functions — do NOT reach out
 //     to a module import. See #269 / #305 for the rationale.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/chat-service",
-  "version": "0.1.6",
+  "version": "1.0.0",
   "description": "Server-side chat service for MulmoBridge — socket.io + REST bridge to Claude Code agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/protocol": "^0.1.4"
+    "@mulmobridge/protocol": "^1.0.0"
   },
   "peerDependencies": {
     "express": "^5.0.0",