@3sln/trove 0.0.12 → 0.0.13

package/packages/server/src/index.js

@@ -15,7 +15,7 @@ import {
   VectorStore, KeywordStore, IndexerRegistry,
   accessHost, TroveError,
   protectedResourceMetadata, challengeHeaders, publicOrigin,
-  diagnoseStorage, STORAGE_ISSUE_CODES,
+  DEFAULT_RATE_LIMITS, RATE_CLASSES, describeRateLimits,
 } from '@3sln/trove/core';
 import { createRouter, routeHelpers } from './routes.js';
 import { createDriveEngine, scanStarter, BACKBONE } from './engine/index.js';
@@ -58,6 +58,15 @@ export async function createServer(config = {}) {
   // from it and /api/capabilities describes it, so the form a user sees and the set of
   // things the server can actually construct cannot drift apart.
   config = { ...config, storageRegistry: storageRegistry(config) };
+  // Here, not in the adapters. Three of the four called it and the Worker one did not —
+  // and a default `wrangler deploy` satisfies the condition exactly: `configFromEnv`
+  // leaves identity anonymous when TROVE_AUTH is unset and `defaultOpen` defaults true, so
+  // the drive went up world-readable and world-writable on a public URL with a clean log,
+  // while the identical config under Bun printed the warning. No adapter can forget it
+  // from here. It fires per isolate cold start rather than per process, which is noisier
+  // only for the deployments that really are open to everyone.
+  warnOnOpenAccess(config);
+  warnOnUnenforceableLimits(config);
   const lifecycleState = { closing: false, background: null };
   const engine = createDriveEngine(config, lifecycleState);
 
@@ -68,6 +77,7 @@ export async function createServer(config = {}) {
   const {
     storage, sqlite: sqliteProvider, metadata, kv, tasks, issues, notifications,
     sidecar, collections, identity, auth, search, vfs, plugins, apiKeys, capabilities, rotation,
+    storageCheck, rateLimiter,
   } = backbone.resources;
 
   // Aliased so the rest of this function reads as it did; the container's
@@ -159,68 +169,12 @@ export async function createServer(config = {}) {
   const routeBeginScan = lifecycleState.background.beginScan;
   const routeBeginReindex = lifecycleState.background.beginReindex;
   issues.handle('scan-collection', (issue) => startScan(issue.retry.collectionId, { reason: 'Retrying after a failed scan' }));
+  issues.handle('storage-check', (issue) => storageCheck.run({ origin: issue.retry?.origin || config.publicUrl || null }));
+  // The one retry that matters most: the user has been told a comment saved and it exists
+  // only in memory. The op was raised for years with no handler registered for it — and in
+  // a shape `canRetry` rejected, so the button never rendered to reveal that.
+  issues.handle('sidecar-flush', () => sidecar.retryPending());
 
-  // --- storage self-check ----------------------------------------------------
-  // The failure this exists for: a bucket with no CORS policy serves the server fine and
-  // serves the browser nothing, so the drive looks healthy and every file opens to a
-  // spinner. See core/storage/diagnose.js for why the check has to be a real preflight.
-  //
-  // `origin` is the browser origin to check the policy against, and there is no guessing
-  // it: a policy may legitimately name one origin, so checking the wrong one would invent
-  // a problem. A request supplies its own; a cron firing has only `config.publicUrl`, and
-  // without either the CORS half is skipped rather than assumed.
-  const STORAGE_ISSUE_KIND = 'storage';
-  async function checkStorage({ origin = null } = {}) {
-    // `all()`, not `list(null)`: this has no user, and asking what the anonymous principal
-    // may read means checking nothing at all on a drive that is not public.
-    const list = collections ? await collections.all().catch(() => []) : [];
-    const results = [];
-    for (const c of list) {
-      let findings;
-      try {
-        const storage = await collections.storageFor(c.id);
-        findings = await diagnoseStorage({
-          storage, origin, driver: c.store?.driver || null, fetchImpl: config.fetch,
-        });
-      } catch (err) {
-        // Failing to BUILD the store is itself the most severe version of unreachable —
-        // an unknown driver or a config missing a required field never gets far enough
-        // to be asked whether it can be read.
-        findings = [{
-          code: 'storage-unreachable',
-          severity: 'error',
-          title: 'This collection’s store could not be opened',
-          detail: err?.message || String(err),
-        }];
-      }
-      const found = new Set(findings.map((f) => f.code));
-      for (const f of findings) {
-        await issues.raise({
-          kind: STORAGE_ISSUE_KIND,
-          subject: `${c.id}:${f.code}`,
-          title: `${c.name || c.id}: ${f.title}`,
-          detail: f.detail,
-          remedy: f.remedy || null,
-          severity: f.severity,
-          collectionId: c.id,
-          // Re-running the check IS the fix verification, so Retry rechecks against the
-          // same origin the finding was made for. Checking a different one would report
-          // a pass for a policy the affected browser still cannot use.
-          retry: { op: 'storage-check', origin },
-        });
-      }
-      // Whatever is no longer true stops being listed. Without this, fixing the bucket
-      // leaves the warning up, and a problem list that outlives its problems is one
-      // people learn to scroll past.
-      for (const code of STORAGE_ISSUE_CODES) {
-        if (!found.has(code)) await issues.clear(STORAGE_ISSUE_KIND, `${c.id}:${code}`);
-      }
-      results.push({ collectionId: c.id, name: c.name || c.id, findings });
-    }
-    return { checked: results.length, corsChecked: !!origin, results };
-  }
-  issues.handle('storage-check', (issue) => checkStorage({ origin: issue.retry?.origin || config.publicUrl || null }));
-  lifecycleState.storageCheck = checkStorage;
 
   issues.handle('reindex-node', (issue) => tasks.run(
     // Carries the issue's collection, so the person who can see the file can also see
@@ -263,31 +217,24 @@ export async function createServer(config = {}) {
     return out;
   }
 
-  // Periodic maintenance. Both of these caches are otherwise unbounded: abandoned
-  // upload sessions (a client that starts an upload and never finishes) accumulate in
-  // the session store forever, and sidecar documents stay resident after their last
-  // access. Each has a sweep that had nothing calling it — this is that caller.
+  // Periodic maintenance for a runtime whose timers survive the request.
+  //
+  // The BODY is `runMaintenance`, the same function the Worker's cron calls, because this
+  // is where the two schedulers drift. `stepRotations`'s docblock already demanded it —
+  // "One function, both callers, so the next thing added to periodic work cannot land in
+  // one scheduler and not the other" — and two things had since landed in one and not the
+  // other: `checkStorage`, so a bucket whose CORS or credentials changed went unnoticed on
+  // the runtime Trove is actually self-hosted on until someone opened Activity and pressed
+  // a button, and `notifications.flush()`.
+  //
+  // `scan: false` keeps the opt-in split below. Everything else — the unbounded upload
+  // session and sidecar caches, trash retention, mention delivery, the storage preflight,
+  // and finishing a rotation someone started — happens on every firing on every runtime.
   let maintenance = null;
   if (config.startFlusher !== false && config.maintenanceIntervalMs !== 0) {
     const everyMs = config.maintenanceIntervalMs ?? 5 * 60 * 1000;
-    // Trash retention. This is the only thing in Trove that destroys data on a timer,
-    // so it is opt-outable (TROVE_TRASH_DAYS=0 keeps the trash forever) and it says what
-    // it removed. 30 days is the same grace period the drives people are used to give.
-    const trashMs = (config.trashRetentionDays ?? 30) * 86400_000;
     maintenance = setInterval(() => {
-      Promise.resolve(vfs.uploads.sweepExpired(Date.now()))
-        // NOT `sidecar.sweep?.()` — that name did not exist on SidecarService, and the
-        // optional call turned "evict idle documents" into a no-op for the process's
-        // whole lifetime. It exists now, and the `?.` is gone so a rename shows up.
-        .then(() => sidecar.sweep())
-        .then(() => (trashMs > 0 ? vfs.purgeTrash({ before: Date.now() - trashMs }) : null))
-        .then((r) => { if (r?.purged) console.log(`[trove] purged ${r.purged} item(s) from the trash after ${config.trashRetentionDays ?? 30} days`); })
-        // A rotation started through the API finishes on its own here. Unlike a scan this
-        // is NOT opt-in: it only touches collections someone has explicitly put into
-        // rotation, and leaving one half-moved is worse than the work of finishing it.
-        .then(() => (collections ? collections.all().catch(() => []) : []))
-        .then((targets) => stepRotations(targets, Math.max(1000, Math.floor(everyMs / 4))))
-        .then((moved) => { for (const m of moved) if (m.moved) console.log(`[trove] rotation ${m.collectionId}: ${m.moved} moved, ${m.status}`); })
+      runMaintenance({ scan: false, budgetMs: Math.max(4000, Math.floor(everyMs / 4)) })
         .catch((e) => console.error('maintenance sweep failed', e));
     }, everyMs);
     maintenance.unref?.();
@@ -298,16 +245,18 @@ export async function createServer(config = {}) {
   // metered API and real load on a NAS. A deployment that shares its bucket with other
   // tools wants this on; one where Trove is the only writer doesn't need it at all, and
   // can scan on demand instead.
+  //
+  // The same function again, with scanning on. It repeats the sweeps that the maintenance
+  // tick also does — all of them idempotent, and concurrent drains collapse — which is a
+  // smaller price than a third hand-written body of periodic work. What it is NOT allowed
+  // to do is pick its own collection list: this used to walk `collections.list(null)`,
+  // "what may the anonymous principal read", so on any drive that is not open to the
+  // public the scheduled scan silently scanned nothing whatsoever.
   let scanTimer = null;
   if (config.startFlusher !== false && config.scanIntervalMs) {
     scanTimer = setInterval(() => {
       if (tasks.list().some((t) => t.kind === 'scan' && t.status === 'running')) return; // still going
-      Promise.resolve(collections ? collections.list(null).catch(() => []) : [])
-        .then(async (list) => {
-          for (const c of list) {
-            await startScan(c.id, { reason: 'Scheduled' }).catch(() => {});
-          }
-        })
+      runMaintenance({ scan: true, budgetMs: Math.max(4000, Math.floor(config.scanIntervalMs / 2)) })
         .catch((e) => console.error('scheduled scan failed', e));
     }, config.scanIntervalMs);
     scanTimer.unref?.();
@@ -322,7 +271,7 @@ export async function createServer(config = {}) {
   // channel cannot shadow a built-in route by claiming its path.
   for (const channel of notifications?.channels || []) {
     for (const route of channel.routes?.(routeHelpers) || []) {
-      router.add(route.method, route.path, route.deps || [], route.handler);
+      router.add(route.method, route.path, route.deps || [], route.handler, { cost: route.cost || 'write' });
     }
   }
 
@@ -340,7 +289,12 @@ export async function createServer(config = {}) {
     ? externalEvaluation({ ...config.accessEvaluation, team: config.accessEvaluation.team || config.identity?.access?.team })
     : null;
   for (const route of accessPolicy?.routes?.(routeHelpers) || []) {
-    router.add(route.method, route.path, route.deps || [], route.handler);
+    // `evaluate` by default for a contributed public route: this is the one endpoint a
+    // stranger reaches with no credential at all, and each call is a JWKS fetch or cache
+    // read and an RSA verify. Refusing to ANSWER an unattributable caller is the right
+    // security property and does nothing about the cost of asking.
+    router.add(route.method, route.path, route.deps || [], route.handler,
+      { cost: route.cost || (route.public ? 'evaluate' : 'write') });
     if (route.public) publicPaths.add(route.path);
   }
 
@@ -352,7 +306,7 @@ export async function createServer(config = {}) {
   // MCP: the same drive, the same identity, spoken to by an agent instead of a browser.
   // Null when switched off, and then nothing below routes to it.
   const mcp = createMcpHandler({
-    vfs, collections, identity, config, auth,
+    vfs, collections, identity, config, auth, rateLimiter,
     // So an agent's tool call obtains the same authorized handles an HTTP route does.
     container: engine.container,
     version: config.version || '0.0.1',
@@ -435,7 +389,13 @@ export async function createServer(config = {}) {
         // locator — nothing recorded what a route used, so nothing stopped it
         // reaching for more.
         container: engine.container,
-        config, principal, grant, auth, mcp,
+        // `mcp` is the one exception, and it says so here rather than being engineered
+        // around: it is constructed AFTER the container, so a route that wanted it would
+        // need `backgroundWork`-style late binding for a single field. `auth` used to ride
+        // along too, and /api/capabilities — its only reader — already declares it as a
+        // dep, so it arrived twice by two mechanisms and the route table understated by
+        // one what that endpoint touches.
+        config, principal, grant, mcp, rateLimiter,
       });
       // A route can refuse on its own (a token that verified but names nobody we know,
       // a session that expired between calls). Whatever refused, the answer to "so
@@ -495,6 +455,11 @@ export async function createServer(config = {}) {
     const out = { swept: false, purged: 0, scans: [], notified: 0, storage: 0 };
     await vfs.uploads.sweepExpired(Date.now());
     await sidecar.sweep();
+    // Rate-limit buckets. One key per subject per class per window, and nothing else
+    // removes them — the window passing makes a bucket unreachable, not absent. The object
+    // guard is real (there is no limiter when limiting is off); the method is not optional,
+    // because both stores have one.
+    await rateLimiter?.store.sweep().catch(() => {});
     // Mentions are batched and drained on an interval — a timer, and a timer registered
     // during a request does not outlive it on Workers, where the adapter switches the
     // flusher off for exactly that reason. Nothing else called flush, so on that runtime
@@ -508,7 +473,7 @@ export async function createServer(config = {}) {
     // Cheap (one preflight per collection) and the only thing that will ever notice a
     // bucket policy that was fine yesterday, so it runs on every firing rather than
     // waiting for someone to open the Activity panel and press a button.
-    out.storage = await checkStorage({ origin: config.publicUrl || null })
+    out.storage = await storageCheck.run({ origin: config.publicUrl || null })
       .then((r) => r.checked)
       .catch((e) => {
         console.error('[trove] storage check failed', e);
@@ -516,8 +481,14 @@ export async function createServer(config = {}) {
       });
     const trashMs = (config.trashRetentionDays ?? 30) * 86400_000;
     if (trashMs > 0) out.purged = (await vfs.purgeTrash({ before: Date.now() - trashMs }))?.purged || 0;
+    // Said out loud, on every runtime. This is the only thing in Trove that destroys data
+    // on a timer, so it is opt-outable (TROVE_TRASH_DAYS=0 keeps the trash forever) and it
+    // reports what it removed.
+    if (out.purged) {
+      console.log(`[trove] purged ${out.purged} item(s) from the trash after ${config.trashRetentionDays ?? 30} days`);
+    }
     out.swept = true;
-    if (!scan) return out;
+
     // `all()` rather than `list(null)`. Maintenance has no user, and `list(null)` answers
     // "what may the anonymous principal read" — which on any drive that is not open to the
     // public is nothing, so the scheduled scan silently scanned no collection whatsoever.
@@ -528,17 +499,25 @@ export async function createServer(config = {}) {
     if (!targets.length) return out;
     // Share the budget across collections so one huge bucket can't starve the rest.
     const each = Math.max(1000, Math.floor(budgetMs / targets.length));
-    for (const c of targets) {
-      const r = await startScan(c.id, { reason: 'Scheduled', deadlineMs: each }).catch((e) => ({ error: e.message }));
-      out.scans.push({ collectionId: c.id, ...r });
+    if (scan) {
+      for (const c of targets) {
+        const r = await startScan(c.id, { reason: 'Scheduled', deadlineMs: each }).catch((e) => ({ error: e.message }));
+        out.scans.push({ collectionId: c.id, ...r });
+      }
     }
 
-    // A rotation that has been started finishes on its own — see `stepRotations`, which
-    // the interval scheduler shares so the two cannot drift apart.
+    // A rotation that has been started finishes on its own, and NOT gated on `scan`.
+    // Scanning is opt-in because it costs money on a bucket nobody asked us to walk; a
+    // rotation only touches collections someone explicitly put into rotation, and leaving
+    // one half-moved is worse than the work of finishing it. Tying the two together is how
+    // `POST /rotate` came to mint a key, report "running", and move nothing forever.
     //
     // Last, and out of what the scans left, because a rotation is elective and a scan is
     // how the drive notices files that changed underneath it.
     out.rotated = await stepRotations(targets, each);
+    for (const m of out.rotated) {
+      if (m.moved) console.log(`[trove] rotation ${m.collectionId}: ${m.moved} moved, ${m.status}`);
+    }
     return out;
   }
 
@@ -550,7 +529,7 @@ export async function createServer(config = {}) {
     // inside a Durable Object want. `begin*` goes wherever `config.background` says,
     // which for a front-line Worker isolate is the object rather than itself.
     startScan, startReindex, beginScan: routeBeginScan, beginReindex: routeBeginReindex,
-    runMaintenance, checkStorage, rotation, mcp, auth, close };
+    runMaintenance, checkStorage: (opts) => storageCheck.run(opts), rotation, mcp, auth, close };
 }
 
 /**
@@ -601,12 +580,42 @@ export const SAMPLE_CSP = [
   "connect-src 'self'",
 ].join('; ');
 
+/**
+ * Say so when the limits cannot actually be enforced.
+ *
+ * In-memory counters are exact on a runtime where one process serves every request, and on
+ * Workers they count PER ISOLATE — so "60 a minute" becomes 60 times however many isolates
+ * the platform decided to run, which is not a limit. `startFlusher: false` is how the
+ * Worker adapter already says "timers do not survive a request here", which is the same
+ * fact about the same absence of a long-lived process.
+ *
+ * A warning rather than a refusal, because there is a correct answer at that layer —
+ * Cloudflare's own rate limiting, configured outside the app — and refusing to boot over a
+ * limit an operator may have handled elsewhere would be worse than saying it.
+ */
+function warnOnUnenforceableLimits(config = {}) {
+  const rl = config.rateLimit;
+  if (!rl?.enabled || rl.store === 'kv') return;
+  if (config.startFlusher !== false) return; // a long-lived process; memory counters are exact
+  console.warn(
+    '[trove] Rate limits are counted IN MEMORY on a runtime with no long-lived process, so '
+    + 'they apply per isolate rather than per drive. Set TROVE_RATE_LIMIT_STORE=kv for one '
+    + 'shared budget, or configure rate limiting at the edge.',
+  );
+}
+
 /**
  * Warn (once, to the console) when a configuration is world-open — anonymous auth
  * plus the default collection granting everyone every capability. Safe on
- * localhost, dangerous when exposed. Called by the runnable adapters at startup.
+ * localhost, dangerous when exposed.
+ *
+ * Called from `createServer`, so it covers every adapter that exists and every one that
+ * will. It was called by the adapters, and the Worker adapter — the one whose default
+ * deploy is world-open on a public URL — was the one that did not call it. Not exported
+ * for the same reason: an export is a second way to reach this, and a second way is how
+ * one caller came to skip it.
  */
-export function warnOnOpenAccess(config = {}) {
+function warnOnOpenAccess(config = {}) {
   const anon = !config.identity || config.identity.driver === 'anonymous' || config.identity === 'anonymous';
   const open = config.collections !== false && config.defaultOpen !== false;
   if (anon && open) {
@@ -851,6 +860,39 @@ export function configFromEnv(env = (typeof process !== 'undefined' ? process.en
   // Per-file upload quota (bytes). Unbounded unless set.
   if (env.TROVE_MAX_UPLOAD_BYTES) config.maxUploadBytes = Number(env.TROVE_MAX_UPLOAD_BYTES);
 
+  // What one caller may cost, per class of work. On by default with the generous defaults
+  // in core/rateLimit.js — a limit nobody turns on is not a limit, and these are chosen so
+  // that using the drive normally never reaches one.
+  //
+  // TROVE_RATE_LIMIT=off        no limiting at all (a single-user drive on a laptop)
+  // TROVE_RATE_LIMIT_STORE=kv   counters in the shared store, so every instance sees one
+  //                             budget. Costs a read and a write per limited request, and
+  //                             it is what a multi-instance or Workers deployment needs —
+  //                             see describeRateLimits for why memory is not enough there.
+  // TROVE_RATE_LIMITS='{"search":{"limit":20,"windowMs":60000}}'  per-class overrides,
+  //                             merged over the defaults so naming one class keeps the rest.
+  config.rateLimit = { enabled: true, store: 'memory', limits: { ...DEFAULT_RATE_LIMITS } };
+  if (env.TROVE_RATE_LIMIT != null && /^(0|off|false|no)$/i.test(String(env.TROVE_RATE_LIMIT))) {
+    config.rateLimit.enabled = false;
+  }
+  if (env.TROVE_RATE_LIMIT_STORE) config.rateLimit.store = String(env.TROVE_RATE_LIMIT_STORE);
+  if (env.TROVE_RATE_LIMITS) {
+    // Refused loudly. A malformed limits document that fell back to the defaults would be
+    // an operator believing they had tightened something they had not.
+    let overrides;
+    try {
+      overrides = JSON.parse(env.TROVE_RATE_LIMITS);
+    } catch (err) {
+      throw TroveError.invalid(`TROVE_RATE_LIMITS is not valid JSON: ${err.message}`);
+    }
+    for (const [name, rule] of Object.entries(overrides)) {
+      if (!RATE_CLASSES.includes(name)) {
+        throw TroveError.invalid(`Unknown rate-limit class "${name}" — expected one of: ${RATE_CLASSES.join(', ')}`);
+      }
+      config.rateLimit.limits[name] = { ...config.rateLimit.limits[name], ...rule };
+    }
+  }
+
   // Deny plugin API calls with no server install record (fully closes the "any client
   // can name any pluginId" gap). Off by default for back-compat with pre-existing
   // local-only installs; flip on once clients have re-uploaded their account plugins.

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

@@ -17,19 +17,11 @@ import { TroveError, challengeHeaders, protectedResourceMetadata } from '@3sln/t
 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 { crossSiteRefusal, corsOriginFor } 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' } = {}) {
@@ -69,7 +61,7 @@ function authRequired(cfg, identity) {
  * @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 } = {}) {
+export function createMcpHandler({ vfs, collections, container, identity, config = {}, auth = {}, version, rateLimiter = null } = {}) {
   const cfg = { path: '/mcp', enabled: true, ...mcpConfigFromEnv(config.env || {}), ...(config.mcp || {}) };
   if (cfg.enabled === false) return null;
   const server = createMcpServer({ version });
@@ -106,7 +98,7 @@ export function createMcpHandler({ vfs, collections, container, identity, config
       // 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'));
+      const origin = corsOriginFor(config?.corsOrigin, req.headers.get('origin'));
       if (!origin) return new Response(null, { status: 204 });
       return new Response(null, {
         status: 204,
@@ -180,7 +172,10 @@ export function createMcpHandler({ vfs, collections, container, identity, config
     // 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 };
+    // The limiter reaches this surface too. An agent holding somebody's token can search
+    // as fast as it likes otherwise, and a search is the paid one — "exactly as privileged
+    // as the person whose token it holds" has to include how much they can spend.
+    const ctx = { vfs, collections, principal, config, access: scope.access, rateLimiter };
 
     try {
       // A batch is an array. Notifications inside it contribute nothing to the reply,

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

@@ -15,6 +15,25 @@
 import { TroveError } from '@3sln/trove/core';
 import { troveUri } from '@3sln/trove/core/links.js';
 import { toolText } from './protocol.js';
+// The one implementation of "what may this caller reach", shared with the HTTP routes.
+// This file had its own, and it FILTERED a named collection out of the readable list
+// where routes.js asserts it — so `search_files` answered "No files matched… Try
+// different words" for a collection the caller may not see, and the model burned turns
+// rephrasing what was really a 403. `ctx.access` is on the MCP ctx, so the assert path
+// was available all along.
+import { readableCollectionIds, listFor } from '../scope.js';
+import { rateSubject } from '@3sln/trove/core';
+
+/**
+ * Charge this call against the caller's budget for that class of work.
+ *
+ * The HTTP routes declare a class in the route table; a tool declares it here, at the top
+ * of the one that costs something. A search is the expensive one — on a deployment with
+ * embeddings configured it is a paid third-party call — and "an agent is exactly as
+ * privileged as the person whose token it holds" has to include how much they can spend.
+ */
+const meter = (ctx, className) =>
+  (ctx.rateLimiter ? ctx.rateLimiter.enforce(rateSubject({ principal: ctx.principal }), className) : null);
 
 // A file read has to fit in a context window and in memory. Past this the tool returns
 // the head and says so, which is far more useful than refusing or than silently
@@ -31,28 +50,6 @@ looking for something, search for it — do not try to construct a path.
 Files reference each other with trove: URIs (trove:default?name=notes.md). Search matches
 meaning as well as words, so a description of the content works as a query.`;
 
-/**
- * Whether this deployment has an ACL layer at all — from configuration, never from
- * whether `ctx.collections` happens to be there. The two agree while everything is
- * wired correctly and diverge exactly when it is not, and here the failure mode is an
- * agent quietly reading every collection in the drive.
- */
-const enforcing = (ctx) => ctx.config?.collections !== false;
-
-/**
- * Collections this principal can read, or undefined when there is no ACL layer.
- *
- * `undefined` means "do not scope the query", which is only correct when there is
- * nothing to scope BY. Search and backlinks reach across collections by design, so an
- * unscoped query hands back names, ids and `trove:` URIs from collections the caller
- * cannot read.
- */
-async function readable(ctx, narrowTo) {
-  if (!enforcing(ctx)) return undefined;
-  const ids = (await ctx.collections.list(ctx.principal)).map((c) => c.id);
-  return narrowTo ? ids.filter((id) => id === narrowTo) : ids;
-}
-
 /**
  * A file, and the operations this agent may perform on it.
  *
@@ -148,7 +145,8 @@ export function registerTroveTools(server) {
     },
     async run({ query, collection, limit }, ctx) {
       if (!query?.trim()) throw TroveError.invalid('query is required');
-      const collectionIds = await readable(ctx, collection);
+      await meter(ctx, 'search');
+      const collectionIds = await readableCollectionIds(ctx, collection);
       const { results, resolved } = await ctx.vfs.query(query, {
         limit: Math.min(Math.max(1, limit || 10), MAX_RESULTS),
         collectionIds,
@@ -292,10 +290,7 @@ export function registerTroveTools(server) {
       + 'division of the drive — the closest thing here to a folder, except they do not nest.',
     inputSchema: { type: 'object', properties: {} },
     async run(_args, ctx) {
-      if (!enforcing(ctx)) {
-        return toolText(JSON.stringify({ collections: [{ id: 'default', capabilities: ['read', 'write', 'delete'] }] }, null, 2));
-      }
-      const list = await ctx.collections.list(ctx.principal);
+      const list = await listFor(ctx);
       return toolText(JSON.stringify({ collections: list }, null, 2), { structured: { collections: list } });
     },
   });
@@ -322,7 +317,7 @@ export function registerTroveTools(server) {
       // Scoped, exactly like the HTTP route. Backlinks reach ACROSS collections by
       // design — that is what makes them useful — so an unscoped query hands back the
       // names, ids and trove: URIs of files inside collections the caller cannot read.
-      const collectionIds = await readable(ctx);
+      const collectionIds = await readableCollectionIds(ctx);
       const backlinks = await handle.backlinks({ limit: 20, collectionIds })
         // Distinguishable from "nothing links here", which in a drive with no folders is
         // a load-bearing fact an agent will reason from.
@@ -340,7 +335,7 @@ export function registerTroveTools(server) {
   // something invented for MCP — one name for a file across the whole system.
   server.resources({
     async list(params, ctx) {
-      const ids = await readable(ctx);
+      const ids = await readableCollectionIds(ctx);
       const out = [];
       for (const cid of ids || ['default']) {
         const page = await (await ctx.access.collection(cid, 'read')).list({ limit: 100 });

package/packages/server/src/router.js

@@ -7,6 +7,7 @@
 
 import { TroveError, wrapError, ErrorCode, publicOrigin } from '@3sln/trove/core';
 import { leaseScope } from './scope.js';
+import { rateSubject } from '@3sln/trove/core';
 
 // Methods that change state. A GET is safe by definition, so it isn't checked.
 const UNSAFE_METHODS = new Set(['POST', 'PUT', 'DELETE', 'PATCH']);
@@ -65,6 +66,9 @@ export class Router {
    * @param {string[]|Function} depsOrHandler  the resources this route needs, by
    *   name — or the handler, for a route that needs none.
    * @param {Function} [maybeHandler]
+   * @param {{cost?: string}} [opts] which class of work this is, for rate limiting — see
+   *   core/rateLimit.js. A route that names none is not metered, which is the right answer
+   *   for the cheap reads the shell issues constantly.
    *
    * Declaring dependencies is the point. Every handler used to receive one
    * object carrying the whole server: vfs, collections, kv, sqlite, plugins,
@@ -74,17 +78,17 @@ export class Router {
    * reading it. Named here, the answer is in the route table, and a route that
    * did not ask for `plugins` does not get `plugins`.
    */
-  add(method, pattern, depsOrHandler, maybeHandler) {
+  add(method, pattern, depsOrHandler, maybeHandler, opts = {}) {
     const handler = maybeHandler ?? depsOrHandler;
     const deps = maybeHandler ? depsOrHandler : [];
     const segs = pattern.split('/').filter(Boolean);
-    this.routes.push({ method, segs, handler, deps });
+    this.routes.push({ method, segs, handler, deps, cost: opts.cost || null });
     return this;
   }
-  get(p, d, h) { return this.add('GET', p, d, h); }
-  post(p, d, h) { return this.add('POST', p, d, h); }
-  put(p, d, h) { return this.add('PUT', p, d, h); }
-  delete(p, d, h) { return this.add('DELETE', p, d, h); }
+  get(p, d, h, o) { return this.add('GET', p, d, h, o); }
+  post(p, d, h, o) { return this.add('POST', p, d, h, o); }
+  put(p, d, h, o) { return this.add('PUT', p, d, h, o); }
+  delete(p, d, h, o) { return this.add('DELETE', p, d, h, o); }
 
   #match(method, pathname) {
     const parts = pathname.split('/').filter(Boolean);
@@ -142,6 +146,15 @@ export class Router {
     const scope = leaseScope(ctx.container, ctx.principal, ctx.grant);
     const access = scope.access;
     try {
+      // Before the handler, before the lease, and before any work: the point of a limit is
+      // that the expensive thing does not happen. `rateLimiter` is null when limiting is
+      // off, and a route that named no class is not metered at all.
+      if (found.route.cost && ctx.rateLimiter) {
+        await ctx.rateLimiter.enforce(
+          rateSubject({ grant: ctx.grant, principal: ctx.principal, req, trustProxy: ctx.config?.trustProxy }),
+          found.route.cost,
+        );
+      }
       lease = ctx.container ? await ctx.container.lease(found.route.deps) : null;
       const result = await found.route.handler({
         req, params: found.params, query, url, access, ...ctx, ...(lease?.resources || {}),
@@ -151,7 +164,13 @@ export class Router {
     } catch (raw) {
       const err = raw instanceof TroveError ? raw : wrapError(raw);
       if (err.code === ErrorCode.INTERNAL) console.error('Unhandled:', err.cause || err);
-      return cors(json(err.toJSON(), err.status), origin);
+      // A 429 without a `Retry-After` makes every client guess, and a client that guesses
+      // wrong either hammers or waits far too long. The limiter knows exactly when the
+      // window ends, so it says so — in SECONDS, rounded up, which is what RFC 9110 wants.
+      const headers = err.details?.retryAfterMs != null
+        ? { 'retry-after': String(Math.ceil(err.details.retryAfterMs / 1000)) }
+        : {};
+      return cors(json(err.toJSON(), err.status, headers), origin);
     } finally {
       await scope.release();
       await lease?.release();
@@ -162,7 +181,11 @@ export class Router {
 // Resolve the Access-Control-Allow-Origin value: null (no CORS) unless configured.
 // '*' echoes '*'; a configured origin is echoed only when the request matches it
 // (so credentials-mode requests get a specific origin, not a wildcard).
-function corsOriginFor(configured, reqOrigin) {
+//
+// Exported because the MCP endpoint needs the same answer. It kept its own copy, and two
+// parsers of one allowlist is how the API and the agent endpoint come to disagree about
+// which origins are trusted — mcp/index.js already imports `crossSiteRefusal` from here.
+export function corsOriginFor(configured, reqOrigin) {
   if (!configured) return null;
   if (configured === '*') return '*';
   const allowed = String(configured).split(',').map((s) => s.trim()).filter(Boolean);