@3sln/trove 0.0.11 → 0.0.13

package/packages/server/src/engine/providers/core.js

@@ -21,7 +21,7 @@
 // means the same thing it always did.
 
 import {
-  StorageBackend, MemoryStorage, S3Storage,
+  StorageBackend, MemoryStorage,
   StorageDriverRegistry, portableDrivers,
   MetadataStore, MemoryStore, SqliteStore,
   SearchService, EmbeddingProvider, LocalHashEmbedding, HttpEmbedding,
@@ -44,6 +44,8 @@ import {
   Vfs, TroveError,
   resolveAuthDiscovery,
   SignedUrls, resolveUrlSecret,
+  diagnoseStorage, STORAGE_ISSUE_CODES,
+  RateLimiter, MemoryRateStore, KvRateStore, DEFAULT_RATE_LIMITS,
 } from '@3sln/trove/core';
 import { Provider } from '@3sln/ngin';
 import { need } from '../lazy.js';
@@ -171,6 +173,33 @@ export function coreProviders(config, lifecycleState) {
     // reads it has to say so.
     config: Provider.fromSingleton(config),
 
+    /**
+     * What one caller may cost, per class of work.
+     *
+     * A provider so the route table can lease it like anything else, and so the store is a
+     * decision made once from configuration rather than at each call site. Null when
+     * limiting is switched off, which is the one case a caller has to handle — and it does
+     * so by not asking, since `Router.handle` only enforces for routes that named a class.
+     */
+    rateLimiter: Provider.fromLazySingleton(
+      async (deps) => {
+        // ON unless switched off, including for a library caller who built a config by
+        // hand rather than through `configFromEnv`. A limit that only exists when somebody
+        // remembers to ask for it is not a limit.
+        const rl = config.rateLimit ?? { enabled: true, store: 'memory', limits: DEFAULT_RATE_LIMITS };
+        if (!rl.enabled) return null;
+        // KV counters are shared across instances and cost a read and a write per limited
+        // request; memory counters are free and exact on ONE long-lived process. See
+        // rateLimit.js — the choice is a property of the deployment, not of the code.
+        const store = rl.store === 'kv'
+          ? new KvRateStore({ kv: (await need(deps, ['kv'])).kv })
+          : new MemoryRateStore();
+        return new RateLimiter({ store, limits: rl.limits || DEFAULT_RATE_LIMITS });
+      },
+      null,
+      { deps: ['kv'] },
+    ),
+
     // Shutdown, likewise. Long work has to be able to ask whether the server is
     // going down, and closing over a `let` made that invisible.
     lifecycle: Provider.fromSingleton({
@@ -198,12 +227,83 @@ export function coreProviders(config, lifecycleState) {
       beginReindex: (opts) => lifecycleState.background.beginReindex(opts),
     }),
 
-    // The storage self-check, late-bound for the same reason: it needs `collections` and
-    // `issues` from this container, so it is assembled in createServer and reached back
-    // into rather than built here.
-    storageCheck: Provider.fromSingleton({
-      run: (opts) => lifecycleState.storageCheck(opts),
-    }),
+    /**
+     * The 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.
+     *
+     * A PROVIDER, not a seam stamped onto `lifecycleState` after construction. The stated
+     * reason for that shape was "it needs `collections` and `issues` from this container",
+     * which is exactly what `fromLazySingleton` with deps is for — and unlike
+     * `backgroundWork`, whose comment names a real circularity (dispatching needs the
+     * engine that owns the container), there is none here.
+     */
+    storageCheck: Provider.fromLazySingleton(
+      async (deps) => {
+        const { collections, issues, config: cfg } = await need(deps, ['collections', 'issues', 'config']);
+        const KIND = 'storage';
+        return {
+          async run({ 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 = 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: cfg.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\u2019s 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: 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(KIND, `${c.id}:${code}`);
+              }
+              results.push({ collectionId: c.id, name: c.name || c.id, findings });
+            }
+            return { checked: results.length, corsChecked: !!origin, results };
+          },
+        };
+      },
+      null,
+      { deps: ['collections', 'issues', 'config'] },
+    ),
 
     storage: Provider.fromLazySingleton(
       () => resolve(config.storage ?? config.vfs?.storage, StorageBackend, (cfg) => buildStorage(cfg, config)),
@@ -525,13 +625,11 @@ export function coreProviders(config, lifecycleState) {
           indexers: r.indexerRuntime
             ? new PluginIndexers({ vfs: r.vfs, runtime: r.indexerRuntime, packages: r.packageStore })
             : null,
-          // Who may install a plugin. With no ACL layer configured there is no admin
-          // list to consult and any authenticated caller qualifies — decided from
-          // config, not from whether `collections` happens to be here, so a graph that
-          // failed to build cannot silently promote everyone.
-          isAdmin: (principal) => (config.collections === false
-            ? !!principal
-            : r.collections.isAdmin(principal)),
+          // Who may install a plugin. There is no "any authenticated caller qualifies"
+          // fallback: the arm that provided one required `collections: false`, which this
+          // provider refuses above and `configFromEnv` refuses again, so it could only ever
+          // have fired for a direct-container caller — where it handed out an open drive.
+          isAdmin: (principal) => r.collections.isAdmin(principal),
           maxPackageBytes: config.maxUploadBytes ?? undefined,
           strict: config.enforcePluginCaps === true,
         });

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' });
     }
   }
 
@@ -330,11 +279,23 @@ export async function createServer(config = {}) {
   // exist. A drive that has not configured one has no `/api/access/*` at all, rather than
   // endpoints that exist to answer "no" — which is the difference between a feature that is
   // off and a feature that is broken.
+  // Paths a contributed component declared as needing no Trove identity. Exact matches
+  // only, and that is deliberate: the check below runs BEFORE routing, so it cannot know
+  // which parameterised route would have matched. A component that wants a public route
+  // gives it a fixed path.
+  const publicPaths = new Set();
+
   const accessPolicy = config.accessEvaluation
     ? 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);
   }
 
   // Said at boot, because that is when someone is looking and can still fix it. The
@@ -345,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',
@@ -409,8 +370,14 @@ export async function createServer(config = {}) {
       let principal = null;
       let grant = null;
       try {
-        grant = await capabilities.resolve(req);
-        if (!grant) principal = await identity.authenticate(req);
+        // A public route answers to something other than this drive's identity — the
+        // external policy endpoints verify a Cloudflare-signed assertion themselves, and
+        // the keys endpoint serves a public key. Requiring a session on those is asking
+        // the caller to authenticate as a user it is not and does not have.
+        if (!publicPaths.has(url.pathname)) {
+          grant = await capabilities.resolve(req);
+          if (!grant) principal = await identity.authenticate(req);
+        }
       } catch (err) {
         const e = err instanceof TroveError ? err : TroveError.unauthorized('Authentication failed');
         return withChallenge(new Response(JSON.stringify(e.toJSON()), { status: e.status, headers: { 'content-type': 'application/json', 'x-content-type-options': 'nosniff' } }), req);
@@ -422,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
@@ -482,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
@@ -495,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);
@@ -503,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.
@@ -515,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;
   }
 
@@ -537,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 };
 }
 
 /**
@@ -588,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) {
@@ -838,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,