fix(sandbox): address PR #250 review — SSRF guard, eviction safety, cleanup (#243)

Security:
- stash_page: reject path-traversal / percent-encoded srcs before the authed
  loopback fetch (resolveInternalFilePath), closing an SSRF/exfiltration hole
  where a crafted node.attrs.src could read an arbitrary internal GET endpoint
  into the anonymous sandbox.

Stability:
- stash_page: revert + recount mirrors FIFO-evicted by a later put in the same
  stash (no dangling sandbox refs, honest images.mirrored/failed); free image
  blobs if the final document put throws.
- Reject/clamp non-positive SANDBOX_TTL_MS to the 1h default (warn once).
- Log mirror failures unconditionally (console.warn, no blob bodies).

Cleanup / architecture:
- Remove dead expiresAt from SandboxPutResult.
- Centralize the /api/sb route in SANDBOX_ROUTE_SEGMENT/SANDBOX_API_PATH and
  move URL composition into SandboxStore.putAndLink; drop the duplicated sink
  closures and the now-unused EnvironmentService injection from McpService and
  AiChatToolsService.
- Un-export isInternalFileUrl; document the process-local (instance-bound)
  sandbox limitation in the tool description and .env.example.

Docs/tests:
- README/README.ru: 38 -> 39 tools + stash_page entry.
- Add traversal/normalize/recursion unit tests, stash self-eviction +
  doc-put-throw + empty/octet-stream mock tests, controller If-None-Match
  (wildcard/weak/list) + Cache-Control tests, and SANDBOX_TTL_MS validation
  tests. Regenerate packages/mcp/build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/server/src/integrations/mcp/mcp-auth.helpers.ts

@@ -143,6 +143,11 @@ export type DocmostMcpConfig = (
       buf: Buffer,
       mime: string,
     ) => { uri: string; sha256: string; size: number };
+    // Optional live/evict probes the package uses to keep stash_page's mirror
+    // counts honest under the store's FIFO eviction (mirror of the package's
+    // sink type); older bindings omit them.
+    has?: (uri: string) => boolean;
+    evict?: (uri: string) => void;
   };
 };
 

apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts

@@ -109,7 +109,6 @@ function makeService(opts: {
   };
 
   const service = new McpService(
-    undefined as never, // environmentService
     undefined as never, // workspaceRepo
     undefined as never, // authService
     undefined as never, // tokenService

apps/server/src/integrations/mcp/mcp.service.ts

@@ -8,7 +8,6 @@ import { ModuleRef } from '@nestjs/core';
 import { pathToFileURL } from 'node:url';
 import { IncomingMessage } from 'node:http';
 import { FastifyReply, FastifyRequest } from 'fastify';
-import { EnvironmentService } from '../environment/environment.service';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 import { UserRepo } from '@docmost/db/repos/user/user.repo';
 import { UserSessionRepo } from '@docmost/db/repos/session/user-session.repo';
@@ -93,7 +92,6 @@ export class McpService implements OnModuleDestroy {
   private readonly sweepTimer: NodeJS.Timeout;
 
   constructor(
-    private readonly environmentService: EnvironmentService,
     private readonly workspaceRepo: WorkspaceRepo,
     private readonly authService: AuthService,
     private readonly tokenService: TokenService,
@@ -118,20 +116,17 @@ export class McpService implements OnModuleDestroy {
     clearInterval(this.sweepTimer);
   }
 
-  // Bind the stash tool to the shared in-RAM SandboxStore and compose the
-  // anonymous public URL (the MCP package owns neither env nor the store).
-  // put() returns the read URL + sha256/size; sha256 is also the blob ETag.
+  // Bind the stash tool to the shared in-RAM SandboxStore. The store owns the
+  // anonymous-URL composition (putAndLink) and the live/evict probes the MCP
+  // package needs to keep its mirror counts honest under FIFO eviction; the
+  // package owns neither env nor the store. The sink speaks `uri`s, so the
+  // probes map a uri back to its id (the last path segment).
   private buildSandboxConfig(): DocmostMcpConfig['sandbox'] {
+    const idOf = (uri: string) => uri.substring(uri.lastIndexOf('/') + 1);
     return {
-      put: (buf: Buffer, mime: string) => {
-        const stored = this.sandboxStore.put(buf, mime);
-        const base = this.environmentService.getSandboxPublicUrl();
-        return {
-          uri: `${base}/api/sb/${stored.id}`,
-          sha256: stored.sha256,
-          size: stored.size,
-        };
-      },
+      put: (buf, mime) => this.sandboxStore.putAndLink(buf, mime),
+      has: (uri) => this.sandboxStore.has(idOf(uri)),
+      evict: (uri) => this.sandboxStore.remove(idOf(uri)),
     };
   }