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/sandbox/sandbox.controller.spec.ts

@@ -0,0 +1,124 @@
+import { SandboxController } from './sandbox.controller';
+import { SandboxEntry } from './sandbox.store';
+
+// Capturing fake of the FastifyReply surface the controller uses:
+// status()/header()/headers()/send(), all chainable.
+function makeRes() {
+  const sent: { status: number; headers: Record<string, any>; body: any } = {
+    status: 200,
+    headers: {},
+    body: undefined,
+  };
+  const res: any = {
+    status(code: number) {
+      sent.status = code;
+      return res;
+    },
+    header(key: string, value: any) {
+      sent.headers[key.toLowerCase()] = value;
+      return res;
+    },
+    headers(obj: Record<string, any>) {
+      for (const k of Object.keys(obj)) sent.headers[k.toLowerCase()] = obj[k];
+      return res;
+    },
+    send(body?: any) {
+      sent.body = body;
+      return res;
+    },
+    _sent: sent,
+  };
+  return res;
+}
+
+function makeReq(headers: Record<string, any> = {}) {
+  return { headers } as any;
+}
+
+const VALID_ID = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
+
+function entry(buf: Buffer, mime: string, sha256: string): SandboxEntry {
+  return { buf, mime, sha256, expiresAt: Date.now() + 60_000 };
+}
+
+describe('SandboxController', () => {
+  it('serves 200 with body, Content-Type, Content-Length and sha256 ETag', async () => {
+    const buf = Buffer.from('{"ok":true}', 'utf8');
+    const sha = 'a'.repeat(64);
+    const store = { get: jest.fn().mockReturnValue(entry(buf, 'application/json', sha)) };
+    const controller = new SandboxController(store as any);
+    const res = makeRes();
+
+    await controller.get(VALID_ID, makeReq(), res);
+
+    expect(store.get).toHaveBeenCalledWith(VALID_ID);
+    expect(res._sent.status).toBe(200);
+    expect(res._sent.headers['content-type']).toBe('application/json');
+    expect(res._sent.headers['content-length']).toBe(buf.length);
+    expect(res._sent.headers['etag']).toBe(`"${sha}"`);
+    expect(res._sent.body).toBe(buf);
+  });
+
+  it('returns 404 for a missing/expired blob', async () => {
+    const store = { get: jest.fn().mockReturnValue(undefined) };
+    const controller = new SandboxController(store as any);
+    const res = makeRes();
+
+    await controller.get(VALID_ID, makeReq(), res);
+
+    expect(res._sent.status).toBe(404);
+    expect(res._sent.body).toBeUndefined();
+  });
+
+  it('returns 404 for a non-UUID id WITHOUT touching the store (anti-traversal)', async () => {
+    const store = { get: jest.fn() };
+    const controller = new SandboxController(store as any);
+    const res = makeRes();
+
+    await controller.get('../../etc/passwd', makeReq(), res);
+
+    expect(store.get).not.toHaveBeenCalled();
+    expect(res._sent.status).toBe(404);
+  });
+
+  it('returns 304 (no body) when If-None-Match matches the ETag', async () => {
+    const sha = 'b'.repeat(64);
+    const store = {
+      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
+    };
+    const controller = new SandboxController(store as any);
+    const res = makeRes();
+
+    await controller.get(VALID_ID, makeReq({ 'if-none-match': `"${sha}"` }), res);
+
+    expect(res._sent.status).toBe(304);
+    expect(res._sent.body).toBeUndefined();
+    expect(res._sent.headers['etag']).toBe(`"${sha}"`);
+  });
+
+  it('accepts a bare (unquoted) sha256 in If-None-Match too', async () => {
+    const sha = 'c'.repeat(64);
+    const store = {
+      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
+    };
+    const controller = new SandboxController(store as any);
+    const res = makeRes();
+
+    await controller.get(VALID_ID, makeReq({ 'if-none-match': sha }), res);
+
+    expect(res._sent.status).toBe(304);
+  });
+
+  it('serves 200 when If-None-Match does NOT match', async () => {
+    const sha = 'd'.repeat(64);
+    const store = {
+      get: jest.fn().mockReturnValue(entry(Buffer.from('x'), 'application/json', sha)),
+    };
+    const controller = new SandboxController(store as any);
+    const res = makeRes();
+
+    await controller.get(VALID_ID, makeReq({ 'if-none-match': '"stale"' }), res);
+
+    expect(res._sent.status).toBe(200);
+  });
+});