@3sln/trove 0.0.2

package/packages/server/src/manifest.js

@@ -0,0 +1,98 @@
+// The web app manifest.
+//
+// There was already a manifest — a static file in packages/web/public, baked at build
+// time and identical in every deployment. That is fine for exactly one drive and wrong
+// for a self-hosted product: an operator running this for a team wants their name on
+// the installed icon, not "Trove". Changing it meant editing a file inside the package
+// and rebuilding, which the shipped-dist model has just made something nobody does.
+//
+// So it is generated per request from configuration, like everything else an operator
+// sets. The static file is gone rather than kept as a fallback: two documents that must
+// agree, one of which is only reachable in development, is how they stop agreeing.
+//
+// No `node:` imports — this is on the runtime-agnostic side and has to load on Workers.
+
+export const MANIFEST_PATH = '/manifest.webmanifest';
+
+const DISPLAY_MODES = ['standalone', 'fullscreen', 'minimal-ui', 'browser'];
+
+const ICON_TYPES = {
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.webp': 'image/webp',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.ico': 'image/x-icon',
+};
+
+/** Guess from the extension, since we cannot read the file — it may not even be ours. */
+function iconType(src) {
+  const dot = src.lastIndexOf('.');
+  return dot === -1 ? undefined : ICON_TYPES[src.slice(dot).toLowerCase().split('?')[0]];
+}
+
+/**
+ * Read the operator's choices out of the environment.
+ *
+ * Everything is optional and everything has a default that produces the document the
+ * static file used to contain, so a deployment that sets none of this is unchanged.
+ *
+ * @param {Record<string, string|undefined>} env
+ */
+export function manifestFromEnv(env = {}) {
+  const m = {};
+  const set = (key, value) => { if (value !== undefined && value !== '') m[key] = value; };
+
+  set('name', env.TROVE_APP_NAME);
+  set('shortName', env.TROVE_APP_SHORT_NAME);
+  set('description', env.TROVE_APP_DESCRIPTION);
+  set('themeColor', env.TROVE_APP_THEME_COLOR);
+  set('backgroundColor', env.TROVE_APP_BACKGROUND_COLOR);
+  set('display', env.TROVE_APP_DISPLAY);
+  set('startUrl', env.TROVE_APP_START_URL);
+  set('icon', env.TROVE_APP_ICON);
+  set('iconSizes', env.TROVE_APP_ICON_SIZES);
+  set('iconType', env.TROVE_APP_ICON_TYPE);
+
+  // The escape hatch. A drive that wants a maskable icon, six raster sizes and a
+  // monochrome badge is not going to be expressible in flat variables, and inventing a
+  // mini-language for it would be worse than accepting the array the spec already
+  // defines. Malformed JSON is ignored rather than fatal: a typo here should not stop a
+  // drive from booting.
+  if (env.TROVE_APP_ICONS) {
+    try {
+      const icons = JSON.parse(env.TROVE_APP_ICONS);
+      if (Array.isArray(icons) && icons.length) m.icons = icons;
+    } catch { /* keep the single-icon path */ }
+  }
+  return m;
+}
+
+/**
+ * Build the manifest document.
+ *
+ * @param {object} [m] the `manifest` block of the server config
+ * @returns {object} a W3C web app manifest
+ */
+export function webManifest(m = {}) {
+  const name = m.name || 'Trove';
+  const theme = m.themeColor || '#181a1f';
+  const src = m.icon || '/icon.svg';
+
+  const icons = m.icons || [{
+    src,
+    sizes: m.iconSizes || 'any',
+    // An SVG is resolution-independent and `any` is honest about it; a raster file at
+    // `any` is a lie the browser will believe and then scale badly, so a host pointing
+    // at a PNG is expected to say what size it is.
+    type: m.iconType || iconType(src),
+    purpose: 'any',
+  }];
+
+  return {
+    name,
+    short_name: m.shortName || name,
+    description: m.description || 'Your self-hosted drive with semantic search, media players, and plugins.',
+    start_url: m.startUrl || '/',
+    display: DISPLAY_MODES.includes(m.display) ? m.display : 'standalone',
+    background_color: m.backgroundColor || theme,
+    theme_color: theme,
+    icons: icons.map((i) => Object.fromEntries(Object.entries(i).filter(([, v]) => v !== undefined))),
+  };
+}

package/packages/server/src/mcp/auth.js

@@ -0,0 +1,40 @@
+// MCP's slice of the drive's auth discovery.
+//
+// The authorization server lives in core (identity/discovery.js) because it is a
+// property of the DEPLOYMENT, not of this endpoint: an unauthenticated call to
+// /api/items and an unauthenticated call to /mcp have the same answer, and a client
+// pointed at either should be sent to the same place. Two settings for one fact is how
+// they end up disagreeing.
+//
+// What IS specific to MCP is the resource identifier — the canonical URI naming this
+// endpoint, which an agent puts in the RFC 8707 `resource` parameter and which the
+// token's audience should match. That is about which resource, not about which
+// authorization server, so it stays here.
+
+import { publicOrigin } from '@3sln/trove/core';
+
+/** Read MCP settings out of the process environment. */
+export function mcpConfigFromEnv(env = {}) {
+  const cfg = {};
+  if (env.TROVE_MCP != null) cfg.enabled = !/^(0|off|false|no)$/i.test(String(env.TROVE_MCP));
+  if (env.TROVE_MCP_PATH) cfg.path = env.TROVE_MCP_PATH;
+  if (env.TROVE_MCP_RESOURCE) cfg.resource = String(env.TROVE_MCP_RESOURCE).replace(/\/+$/, '');
+  // Whether, not where. The drive's posture is the default — see authRequired — and this
+  // exists for the deployment that wants an open web app and a locked-down agent
+  // endpoint, or the reverse.
+  if (env.TROVE_MCP_REQUIRE_AUTH != null) cfg.requireAuth = !/^(0|off|false|no)$/i.test(String(env.TROVE_MCP_REQUIRE_AUTH));
+  return cfg;
+}
+
+/**
+ * The canonical URI of this MCP endpoint.
+ *
+ * Derived from the request when not configured, so a self-hoster doesn't have to tell
+ * the server its own address. Configured explicitly when the drive sits behind a proxy
+ * that rewrites the Host in a way the forwarded headers don't capture, where guessing
+ * would produce an identifier no token will ever match.
+ */
+export function mcpResourceUri(req, cfg = {}, serverConfig = {}) {
+  if (cfg.resource) return String(cfg.resource).replace(/\/+$/, '');
+  return `${publicOrigin(req, serverConfig)}${cfg.path || '/mcp'}`;
+}

package/packages/server/src/mcp/index.js

@@ -0,0 +1,213 @@
+// The MCP endpoint: one URL, JSON-RPC over HTTP, guarded by the drive's own identity.
+//
+// This is the "Streamable HTTP" transport. Trove implements the half of it that matters
+// for a server with no server-initiated messages: POST carries a request and gets a
+// single JSON response back. The GET-for-SSE half exists in the spec so a server can
+// push notifications, and Trove has none to push — so it says 405 rather than holding a
+// stream open that will never carry anything. A client that needs streaming falls back
+// to plain POST, which is what it would end up using anyway.
+//
+// Authentication reuses the drive's IdentityProvider verbatim, and its authorization
+// server comes from the drive's config rather than from anything MCP-specific. That is
+// the point of the exercise: an agent presents the same JWT the browser does, from the
+// same place, subject to the same verification and the same collection permissions. It
+// is not a second access-control system to keep in sync with the first.
+
+import { TroveError, challengeHeaders, protectedResourceMetadata } from '@3sln/trove/core';
+import { McpServer, rpcError, JSONRPC_ERRORS } from './protocol.js';
+import { registerTroveTools } from './tools.js';
+import { mcpConfigFromEnv, mcpResourceUri } from './auth.js';
+import { crossSiteRefusal } from '../router.js';
+import { leaseScope } from '../scope.js';
+
+const MAX_BODY_BYTES = 1024 * 1024;
+
+/** The CORS origin to echo, or null for "no cross-origin access" — same rule as the API. */
+function allowedOrigin(configured, reqOrigin) {
+  if (!configured) return null;
+  if (configured === '*') return '*';
+  const allowed = String(configured).split(',').map((s) => s.trim()).filter(Boolean);
+  return reqOrigin && allowed.includes(reqOrigin) ? reqOrigin : null;
+}
+
+export { McpServer, mcpConfigFromEnv, mcpResourceUri };
+
+export function createMcpServer({ name = 'trove', version = '0.0.1' } = {}) {
+  return registerTroveTools(new McpServer({ name, version }));
+}
+
+function jsonResponse(body, status = 200, headers = {}) {
+  return new Response(body == null ? null : JSON.stringify(body), {
+    status,
+    headers: {
+      ...(body == null ? {} : { 'content-type': 'application/json' }),
+      'x-content-type-options': 'nosniff',
+      ...headers,
+    },
+  });
+}
+
+/**
+ * Does this deployment require a token for MCP?
+ *
+ * Default: follow the drive. A drive running open (the zero-config case, one shared
+ * anonymous user) exposes MCP the same way, because demanding a token from an agent for
+ * a drive that demands none from a browser protects nothing. A drive with a real
+ * identity provider requires one. An operator can force either.
+ */
+function authRequired(cfg, identity) {
+  if (cfg.requireAuth != null) return !!cfg.requireAuth;
+  return !identity?.constructor?.name?.startsWith('Anonymous');
+}
+
+/**
+ * Build the MCP request handler.
+ *
+ * Returns null when MCP is switched off, so the caller can skip the routes entirely
+ * rather than serving an endpoint that 404s in a way indistinguishable from a typo.
+ *
+ * @param {object} deps
+ * @param {object} deps.auth the drive's resolved auth discovery (see resolveAuthDiscovery)
+ */
+export function createMcpHandler({ vfs, collections, container, identity, config = {}, auth = {}, version } = {}) {
+  const cfg = { path: '/mcp', enabled: true, ...mcpConfigFromEnv(config.env || {}), ...(config.mcp || {}) };
+  if (cfg.enabled === false) return null;
+  const server = createMcpServer({ version });
+  const path = cfg.path || '/mcp';
+
+  /** The 401 an agent uses to discover where to sign in. */
+  const unauthorized = (req, description) => jsonResponse(
+    // A JSON-RPC error body as well as the header, because a client that reads the body
+    // before the status still gets told what happened.
+    rpcError(null, JSONRPC_ERRORS.INVALID_REQUEST, description || 'Authentication required'),
+    401,
+    challengeHeaders(mcpResourceUri(req, cfg, config), auth, { description }),
+  );
+
+  async function handle(req, url) {
+    // --- discovery: RFC 9728 for THIS endpoint --------------------------------
+    // The drive's own document is served by the caller at the bare well-known path;
+    // this is the /mcp-suffixed one, which names the MCP endpoint as the resource.
+    // Always unauthenticated — a document whose whole job is to say how to authenticate
+    // cannot itself require a token.
+    if (url.pathname === `/.well-known/oauth-protected-resource${path}`) {
+      return jsonResponse(protectedResourceMetadata(mcpResourceUri(req, cfg, config), auth), 200, {
+        'cache-control': 'public, max-age=3600',
+        'access-control-allow-origin': '*',
+      });
+    }
+
+    if (url.pathname !== path) return null;
+
+    if (req.method === 'OPTIONS') {
+      // Echoing the request's own Origin approves EVERY site. On the zero-config
+      // deployment MCP needs no token, so that let any page the user happened to be
+      // visiting call write_file and delete_file on their drive — the reply is
+      // unreadable to the attacker, but the deletions still happen. Agents are not
+      // browsers and do not need CORS at all, so this follows the same
+      // TROVE_CORS_ORIGIN allowlist the JSON API does, and stays off by default.
+      const origin = allowedOrigin(config?.corsOrigin, req.headers.get('origin'));
+      if (!origin) return new Response(null, { status: 204 });
+      return new Response(null, {
+        status: 204,
+        headers: {
+          'access-control-allow-origin': origin,
+          ...(origin === '*' ? {} : { vary: 'Origin' }),
+          'access-control-allow-methods': 'POST, GET, DELETE, OPTIONS',
+          'access-control-allow-headers': 'content-type, authorization, mcp-protocol-version, mcp-session-id',
+          'access-control-expose-headers': 'www-authenticate, mcp-session-id',
+        },
+      });
+    }
+
+    // No server-initiated messages, so no stream to open. Said plainly.
+    if (req.method === 'GET') {
+      return jsonResponse({ error: 'This server sends no unsolicited messages; POST JSON-RPC requests instead.' }, 405,
+        { allow: 'POST, OPTIONS' });
+    }
+    // Sessions are not used — every request stands alone — so there is nothing to end.
+    if (req.method === 'DELETE') return new Response(null, { status: 204 });
+    if (req.method !== 'POST') return jsonResponse({ error: 'Method not allowed' }, 405, { allow: 'POST, OPTIONS' });
+
+    // The OPTIONS allowlist above only governs requests a browser preflights. A
+    // cross-site POST with `content-type: text/plain` is a CORS simple request — no
+    // preflight, so nothing consulted that allowlist, and `delete_file` ran. Agents are
+    // not browsers and send none of these headers, so this costs them nothing.
+    const refused = crossSiteRefusal(req, config);
+    if (refused) return refused;
+
+    // --- identity -------------------------------------------------------------
+    let principal = null;
+    const needsAuth = authRequired(cfg, identity);
+    try {
+      principal = await identity.authenticate(req);
+    } catch (err) {
+      // A bad token is a 401 WITH the challenge, not a bare rejection — an agent whose
+      // token expired needs to be told where to get another one, which is the same
+      // answer as for an agent that never had one.
+      const e = err instanceof TroveError ? err : null;
+      if (e && e.code === 'transient') {
+        return jsonResponse(rpcError(null, JSONRPC_ERRORS.INTERNAL, e.message), 503);
+      }
+      return unauthorized(req, err?.message || 'The token was not accepted.');
+    }
+    if (needsAuth && (!principal || principal.anonymous)) {
+      return unauthorized(req, 'This drive requires a bearer token.');
+    }
+
+    // --- the message ----------------------------------------------------------
+    const declared = Number(req.headers.get('content-length') || 0);
+    if (declared > MAX_BODY_BYTES) {
+      return jsonResponse(rpcError(null, JSONRPC_ERRORS.INVALID_REQUEST, 'Request too large'), 413);
+    }
+    let text;
+    try {
+      text = await req.text();
+    } catch {
+      return jsonResponse(rpcError(null, JSONRPC_ERRORS.PARSE, 'Could not read the request body'), 400);
+    }
+    if (text.length > MAX_BODY_BYTES) {
+      return jsonResponse(rpcError(null, JSONRPC_ERRORS.INVALID_REQUEST, 'Request too large'), 413);
+    }
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      return jsonResponse(rpcError(null, JSONRPC_ERRORS.PARSE, 'Body is not valid JSON'), 400);
+    }
+
+    // The same authorization the browser gets, from the same place: a tool asks for a
+    // node or collection HANDLE and operates through it, so there is no MCP-shaped path
+    // around the collection ACL and no unrestricted `vfs` sitting in a tool body.
+    const scope = leaseScope(container, principal);
+    const ctx = { vfs, collections, principal, config, access: scope.access };
+
+    try {
+      // A batch is an array. Notifications inside it contribute nothing to the reply,
+      // and a batch of only notifications gets 202 with no body at all.
+      if (Array.isArray(msg)) {
+        if (!msg.length) return jsonResponse(rpcError(null, JSONRPC_ERRORS.INVALID_REQUEST, 'Empty batch'), 400);
+        const replies = (await Promise.all(msg.map((m) => server.dispatch(m, ctx)))).filter(Boolean);
+        return replies.length ? jsonResponse(replies) : new Response(null, { status: 202 });
+      }
+
+      const reply = await server.dispatch(msg, ctx);
+      // A notification gets 202 and NO body. Returning a JSON-RPC envelope here is the
+      // classic way to make a conformant client decide the server is broken.
+      if (!reply) return new Response(null, { status: 202 });
+      return jsonResponse(reply);
+    } finally {
+      await scope.release();
+    }
+  }
+
+  return {
+    handle,
+    server,
+    path,
+    config: cfg,
+    /** What to paste into an agent, for a given request's public origin. */
+    endpoint: (req) => mcpResourceUri(req, cfg, config),
+    requiresAuth: () => authRequired(cfg, identity),
+  };
+}

package/packages/server/src/mcp/protocol.js

@@ -0,0 +1,181 @@
+// The MCP wire protocol: JSON-RPC 2.0 over a single HTTP endpoint.
+//
+// Deliberately small. Trove is an MCP *server* exposing a handful of tools, not a
+// framework, and the surface an agent actually exercises is `initialize`, `tools/list`,
+// `tools/call`, and the resource pair. Everything else is answered honestly with
+// "method not found" rather than half-implemented.
+//
+// Two shapes matter and are easy to get wrong:
+//
+//   - A NOTIFICATION (no `id`) gets no response body at all — 202 with nothing. Sending
+//     a JSON-RPC result for `notifications/initialized` makes conformant clients treat
+//     the connection as broken.
+//   - A tool that FAILS is not a JSON-RPC error. It returns a normal result carrying
+//     `isError: true`, because the model is supposed to see what went wrong and try
+//     something else. JSON-RPC errors are reserved for the protocol itself being wrong —
+//     an unknown method, malformed params — which the model cannot do anything about.
+
+// The newest final revision at the time of writing. Older clients get their own version
+// echoed back when we can speak it, which is how MCP negotiation works: the server picks
+// from what the client asked for rather than forcing an upgrade.
+export const LATEST_PROTOCOL = '2025-11-25';
+export const SUPPORTED_PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+
+export const JSONRPC_ERRORS = {
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603,
+};
+
+export function rpcResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+export function rpcError(id, code, message, data) {
+  return { jsonrpc: '2.0', id: id ?? null, error: { code, message, ...(data ? { data } : {}) } };
+}
+
+/** A tool result the model can read. `isError` is how a failure reaches the model. */
+export function toolText(text, { isError = false, structured } = {}) {
+  return {
+    content: [{ type: 'text', text: String(text) }],
+    ...(structured ? { structuredContent: structured } : {}),
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+export class McpServer {
+  /**
+   * @param {object} opts
+   * @param {string} opts.name
+   * @param {string} opts.version
+   * @param {string} [opts.instructions] shown to the model once, describing the server
+   */
+  constructor({ name, version, instructions } = {}) {
+    this.name = name || 'mcp';
+    this.version = version || '0.0.0';
+    this.instructions = instructions || '';
+    this.tools = new Map();
+    this.resourceProviders = null;
+  }
+
+  /**
+   * @param {object} tool
+   * @param {string} tool.name
+   * @param {string} tool.description written for a MODEL to read, not a person
+   * @param {object} tool.inputSchema JSON Schema for the arguments
+   * @param {(args: object, ctx: object) => Promise<any>} tool.run
+   * @param {boolean} [tool.readOnly] declared as a hint, and enforced by the caller
+   */
+  tool(tool) {
+    this.tools.set(tool.name, tool);
+    return this;
+  }
+
+  /** @param {{list: Function, read: Function}} providers */
+  resources(providers) {
+    this.resourceProviders = providers;
+    return this;
+  }
+
+  /**
+   * Handle one JSON-RPC message. Returns null for notifications — the caller must send
+   * no body at all, not `null` serialized.
+   */
+  async dispatch(msg, ctx = {}) {
+    if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+      return rpcError(msg?.id, JSONRPC_ERRORS.INVALID_REQUEST, 'Not a JSON-RPC 2.0 request');
+    }
+    const isNotification = msg.id === undefined || msg.id === null;
+    const params = msg.params || {};
+
+    try {
+      switch (msg.method) {
+        case 'initialize':
+          return rpcResult(msg.id, this.#initialize(params));
+
+        // The client telling us it is ready. Nothing to say back.
+        case 'notifications/initialized':
+        case 'notifications/cancelled':
+          return null;
+
+        case 'ping':
+          return rpcResult(msg.id, {});
+
+        case 'tools/list':
+          return rpcResult(msg.id, {
+            tools: [...this.tools.values()]
+              .filter((t) => !t.available || t.available(ctx))
+              .map((t) => ({
+                name: t.name,
+                title: t.title || undefined,
+                description: t.description,
+                inputSchema: t.inputSchema,
+                ...(t.readOnly ? { annotations: { readOnlyHint: true } } : {}),
+              })),
+          });
+
+        case 'tools/call':
+          return rpcResult(msg.id, await this.#call(params, ctx));
+
+        case 'resources/list':
+          if (!this.resourceProviders) break;
+          return rpcResult(msg.id, await this.resourceProviders.list(params, ctx));
+
+        case 'resources/read':
+          if (!this.resourceProviders) break;
+          return rpcResult(msg.id, await this.resourceProviders.read(params, ctx));
+
+        // Declared as unsupported in `initialize`, so a conformant client won't ask.
+        // Answered anyway, because one that does should get an empty list rather than
+        // an error it treats as the connection failing.
+        case 'prompts/list':
+          return rpcResult(msg.id, { prompts: [] });
+        case 'resources/templates/list':
+          return rpcResult(msg.id, { resourceTemplates: [] });
+
+        default:
+          break;
+      }
+      if (isNotification) return null; // an unknown notification is not worth an error
+      return rpcError(msg.id, JSONRPC_ERRORS.METHOD_NOT_FOUND, `Unknown method: ${msg.method}`);
+    } catch (err) {
+      if (isNotification) return null;
+      // Something in the dispatch itself broke — not the tool, which handles its own
+      // failures below.
+      return rpcError(msg.id, JSONRPC_ERRORS.INTERNAL, err?.message || 'Internal error');
+    }
+  }
+
+  #initialize(params) {
+    const asked = params.protocolVersion;
+    return {
+      protocolVersion: SUPPORTED_PROTOCOLS.includes(asked) ? asked : LATEST_PROTOCOL,
+      capabilities: {
+        tools: { listChanged: false },
+        ...(this.resourceProviders ? { resources: { subscribe: false, listChanged: false } } : {}),
+      },
+      serverInfo: { name: this.name, version: this.version },
+      ...(this.instructions ? { instructions: this.instructions } : {}),
+    };
+  }
+
+  async #call(params, ctx) {
+    const tool = this.tools.get(params.name);
+    // An unknown tool IS a tool-level failure, not a protocol one: models hallucinate
+    // tool names, and the useful response is one the model can read and correct from.
+    if (!tool) return toolText(`No such tool: ${params.name}`, { isError: true });
+    if (tool.available && !tool.available(ctx)) {
+      return toolText(`The tool "${params.name}" is not available to you.`, { isError: true });
+    }
+    try {
+      const out = await tool.run(params.arguments || {}, ctx);
+      return out?.content ? out : toolText(typeof out === 'string' ? out : JSON.stringify(out, null, 2));
+    } catch (err) {
+      // Permission denied, file missing, drive full — all of it goes to the model as
+      // readable text so it can adjust, rather than to the transport as a fault.
+      return toolText(err?.message || 'The tool failed', { isError: true });
+    }
+  }
+}