feat(sandbox): in-RAM blob sandbox for out-of-band page transfer (#243)

Add an ephemeral, process-local blob store so the in-app agent (and the
embedded MCP) can hand a large page document and its images to an external
consumer WITHOUT routing the bytes through the model context or Docmost auth.

- SandboxStore (@Injectable singleton): Map<uuid,{buf,mime,sha256,expiresAt}>
  in RAM only. put() picks a per-blob cap by mime (image vs doc), enforces a
  total-bytes RAM guard with oldest-first eviction, and stamps a TTL; get()
  lazily expires. sha256 computed at put() doubles as the strong ETag. An
  unref'd sweep interval clears expired entries and is cleared on destroy.
- GET /api/sb/:uuid anonymous controller: serves raw bytes with Content-Type,
  Content-Length and ETag=sha256; 404 on missing/expired/non-UUID (anti-
  traversal), 304 on a matching If-None-Match. No tokens, no 401 — the
  capability is the unguessable UUID + short TTL + TLS. Auth-exempt the same
  way as /api/files/public (no JwtAuthGuard) plus an /api/sb entry in main.ts's
  workspace-resolution preHandler so a remote consumer with no workspace host
  is not rejected.
- stash_page tool in both layers (MCP resource_link + in-app {uri,size,sha256,
  images}). client.stashPage serializes the get_page_json shape, mirrors every
  INTERNAL file/image src (type-agnostic, covers drawio/excalidraw/video/file)
  into the sandbox under Docmost auth and rewrites src to the sandbox URL;
  external http(s) srcs are left untouched; dedup by src; a failed image fetch
  is counted, never aborts the doc.
- SANDBOX_PUBLIC_URL / SANDBOX_TTL_MS / SANDBOX_MAX_BYTES /
  SANDBOX_MAX_IMAGE_BYTES / SANDBOX_MAX_TOTAL_BYTES wired through the
  environment service + validation + .env.example.
- SandboxModule (@Global) provides the shared store to the controller,
  McpService and AiChatToolsService (same instance for put and get).

Tests: SandboxStore (round-trip, sha256, TTL lazy + sweep, caps, eviction),
SandboxController (200+ETag+CT+CL, 404 missing/expired/non-UUID, 304), and a
mock-HTTP stashPage test (mirror+rewrite internal, keep external, dedup, failed
image counted, returns only a link). Interoperates with the vvzvlad/habr-mcp
consumer's anonymous-GET + sha256-ETag + resource_link contract.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

@@ -131,10 +131,20 @@ export class FailedLoginLimiter {
 }
 
 // The per-session DocmostMcpConfig shape understood by @docmost/mcp: either the
-// service-account credentials variant OR the per-user getToken variant.
-export type DocmostMcpConfig =
+// service-account credentials variant OR the per-user getToken variant. The
+// optional `sandbox` sink (blob store for the stash tool) is common to both and
+// injected by McpService after the auth decision.
+export type DocmostMcpConfig = (
   | { apiUrl: string; email: string; password: string }
-  | { apiUrl: string; getToken: () => Promise<string> };
+  | { apiUrl: string; getToken: () => Promise<string> }
+) & {
+  sandbox?: {
+    put: (
+      buf: Buffer,
+      mime: string,
+    ) => { uri: string; sha256: string; size: number };
+  };
+};
 
 export interface ResolvedMcpAuth {
   config: DocmostMcpConfig;

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

@@ -116,6 +116,7 @@ function makeService(opts: {
     undefined as never, // userRepo
     undefined as never, // userSessionRepo
     moduleRef as never, // moduleRef (read by the MFA branch)
+    undefined as never, // sandboxStore (unused by the login-gate path)
   );
   // Stop the constructor's unref'd sweep timer leaking across tests.
   service.onModuleDestroy();

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

@@ -30,6 +30,7 @@ import {
   DocmostMcpConfig,
   ResolvedMcpAuth,
 } from './mcp-auth.helpers';
+import { SandboxStore } from '../sandbox/sandbox.store';
 
 // Minimal shape of the embedded MCP HTTP handler exported by @docmost/mcp/http.
 interface McpHttpHandler {
@@ -99,6 +100,8 @@ export class McpService implements OnModuleDestroy {
     private readonly userRepo: UserRepo,
     private readonly userSessionRepo: UserSessionRepo,
     private readonly moduleRef: ModuleRef,
+    // Shared singleton in-RAM blob store backing the stash tool.
+    private readonly sandboxStore: SandboxStore,
   ) {
     this.sweepTimer = setInterval(() => {
       try {
@@ -115,6 +118,23 @@ 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.
+  private buildSandboxConfig(): DocmostMcpConfig['sandbox'] {
+    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,
+        };
+      },
+    };
+  }
+
   // Service account the embedded MCP uses to talk back to this Docmost
   // instance over loopback REST + the collaboration WebSocket. Now OPTIONAL:
   // it is only a fallback when no per-user Basic/Bearer credentials are sent.
@@ -326,7 +346,10 @@ export class McpService implements OnModuleDestroy {
               // Should never happen: handle() always stashes before delegating.
               throw new UnauthorizedException('MCP authentication missing.');
             }
-            return resolved.config;
+            // Inject the blob-sandbox sink after the auth decision so stash_page
+            // can store blobs in the shared in-RAM store regardless of which
+            // credential variant resolved.
+            return { ...resolved.config, sandbox: this.buildSandboxConfig() };
           },
           {
             identify: (req: IncomingMessage) => {