@3sln/trove 0.0.11 → 0.0.13

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);

package/packages/server/src/routes.js

@@ -2,10 +2,13 @@
 // (bytes, range-aware) and direct part uploads (raw body). Downloads redirect to
 // a presigned URL when the backend supports it, otherwise stream through here.
 
+import {
+  readableCollectionIds, listFor, wholeDriveFor, assertCap, describeFor, refuseGrant,
+} from './scope.js';
 import { Router, json, parseRange } from './router.js';
 import {
   TroveError, assertSafePluginSql, concatBytes, metadataUrl, publicOrigin,
-  shouldEncrypt, estimateRotationCost,
+  estimateRotationCost, describeRateLimits, DEFAULT_RATE_LIMITS,
 } from '@3sln/trove/core';
 import { parseContribUri, CORE_DOMAIN } from '@3sln/trove/core/plugins/identity.js';
 
@@ -29,29 +32,17 @@ async function body(req) {
   }
 }
 
-// Read the body as text, aborting if it exceeds `max` bytes (checks Content-Length
-// first, then enforces while streaming in case the header lies or is absent).
-async function readCapped(req, max) {
-  const declared = Number(req.headers.get('content-length') || 0);
-  if (declared && declared > max) throw TroveError.invalid('Request body too large');
-  const reader = req.body?.getReader?.();
-  if (!reader) {
-    const text = await req.text();
-    if (text.length > max) throw TroveError.invalid('Request body too large');
-    return text;
-  }
-  const chunks = [];
-  let total = 0;
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    total += value.byteLength;
-    if (total > max) { await reader.cancel().catch(() => {}); throw TroveError.invalid('Request body too large'); }
-    chunks.push(value);
-  }
-  return new TextDecoder().decode(concatBytes(chunks));
-}
-// Read a raw binary body (e.g. an uploaded plugin package), capped like readCapped —
+/**
+ * The text of a request body, capped.
+ *
+ * Decodes what `readBytesCapped` measured, rather than counting for itself. The two were
+ * separate loops and the cap meant different things in each: this one compared
+ * `text.length` — UTF-16 code units — against a limit expressed in BYTES, so a body of
+ * multibyte characters could be up to three times the cap and pass.
+ */
+const readCapped = async (req, max) => new TextDecoder().decode(await readBytesCapped(req, max));
+
+// Read a raw binary body (e.g. an uploaded plugin package) up to `max` bytes —
 // which means enforcing WHILE streaming, not after. Checking `.byteLength` on the result
 // of `arrayBuffer()` is a check that happens once the whole body is already resident, so
 // a chunked upload with no Content-Length could park 400 MB in the heap and only then be
@@ -169,7 +160,11 @@ export function createRouter() {
     }
   });
 
-  r.get('/api/capabilities', ['auth', 'collections', 'notifications', 'sidecar', 'vfs'], async (ctx) => {
+  // No `collections` in the leases: the handler reaches collections through
+  // `ctx.access.collection`, which comes from `leaseScope` rather than from the route
+  // table. A declaration that overstates what an endpoint touches is the same problem as
+  // one that understates it — the table exists to answer that question.
+  r.get('/api/capabilities', ['auth', 'notifications', 'sidecar', 'vfs'], async (ctx) => {
     const { vfs, config, sidecar, notifications, principal, query, auth, mcp } = ctx;
     // Storage is per-collection, so report the backend for the requested collection
     // (else the client picks the wrong upload strategy on a non-default collection).
@@ -200,6 +195,15 @@ export function createRouter() {
       // grammar, so it owns the prompt — a client that hardcodes "# filter by tag"
       // tells people the wrong thing the moment a different transformer is configured.
       searchPrompt: vfs.searchTransformer?.describe?.() || null,
+      // What this deployment will actually enforce, and at what SCOPE. `scope: 'isolate'`
+      // is the admission that in-memory counters on a runtime with no long-lived process
+      // apply per isolate — reported rather than assumed, so a deployment that cannot
+      // enforce a limit says so instead of appearing to. See core/rateLimit.js.
+      rateLimits: describeRateLimits({
+        enabled: true, store: 'memory', limits: DEFAULT_RATE_LIMITS,
+        ...(ctx.config.rateLimit || {}),
+        perProcess: ctx.config.startFlusher !== false,
+      }),
 
       // Where a refused client is sent, and where an agent connects. Both are DEPLOYMENT
       // facts — env, or a field the library caller passed — so they are reported here
@@ -232,35 +236,35 @@ export function createRouter() {
   // --- collections -----------------------------------------------------------
 
   r.get('/api/collections', ['collections'], async (ctx) => {
-    const { collections, principal } = ctx;
-    return { collections: await collections.list(principal), canCreate: collections.canCreate(principal) };
+    // `listFor`, not `list(principal)`: a key request has no principal, and the drive it
+    // can see is the one its scopes name. `canCreate` stays a principal question — making
+    // a collection is not a capability any scope can hold, so a key never can.
+    return { collections: await listFor(ctx), canCreate: ctx.collections.canCreate(ctx.principal) };
   });
 
   r.get('/api/collections/:id', ['collections'], async (ctx) => {
-    const { collections, principal, params } = ctx;
-    const c = await collections.assert(principal, params.id, 'read');
-    return { collection: collections.describe(c, principal) };
+    return { collection: describeFor(ctx, await assertCap(ctx, ctx.params.id, 'read')) };
   });
 
   r.post('/api/collections', ['collections'], async (ctx) => {
-    requireCollections(ctx);
+    refuseGrant(ctx, 'create collections');
     return { collection: await ctx.collections.create(await body(ctx.req), ctx.principal) };
   });
 
   r.post('/api/collections/:id', ['collections'], async (ctx) => {
-    requireCollections(ctx);
+    refuseGrant(ctx, 'change a collection');
     return { collection: await ctx.collections.update(ctx.params.id, await body(ctx.req), ctx.principal) };
   });
 
   r.delete('/api/collections/:id', ['collections', 'vfs'], async (ctx) => {
-    requireCollections(ctx);
+    refuseGrant(ctx, 'delete a collection');
     const { collections, vfs, principal, params } = ctx;
     // A collection record is the only thing that knows where its items' BYTES live, so
     // deleting it while items still reference it stranded every one of them: `storageFor`
     // throws "Collection not found", and since reindex walks the whole metadata store,
     // every rebuild — including the one at boot — failed on them forever, raising a
     // retryable issue whose Retry re-ran the same failure. Refuse, and say what to do.
-    const n = await vfs.metadata.countItems?.(params.id);
+    const n = await vfs.metadata.countItems(params.id);
     if (n) {
       throw TroveError.conflict(
         `“${params.id}” still holds ${n.toLocaleString()} item${n === 1 ? '' : 's'}. `
@@ -281,7 +285,7 @@ export function createRouter() {
    * listing would carry it. Asking for it is an explicitly admin-gated act.
    */
   r.get('/api/collections/:id/grants', ['collections'], async (ctx) => {
-    requireCollections(ctx);
+    refuseGrant(ctx, 'read a collection\u2019s access list');
     const c = await ctx.collections.assert(ctx.principal, ctx.params.id, 'admin');
     // Drive administrators come from the DEPLOYMENT (TROVE_ADMINS), not from this ACL, and
     // returning them alongside rather than inside `grants` is the honest shape: they hold
@@ -294,7 +298,7 @@ export function createRouter() {
   });
 
   r.post('/api/collections/:id/grants', ['collections'], async (ctx) => {
-    requireCollections(ctx);
+    refuseGrant(ctx, 'change who can reach a collection');
     return { collection: await ctx.collections.setGrant(ctx.params.id, await body(ctx.req), ctx.principal) };
   });
 
@@ -351,7 +355,7 @@ export function createRouter() {
     // `stats` describes the COLLECTION; `items` is one page of it. Without this the
     // client can only report the page it happens to be holding, which on a drive with
     // more items than fit in a page is simply a wrong number on screen.
-    const stats = await vfs.metadata.collectionStats?.(collectionId).catch(() => null) ?? null;
+    const stats = await vfs.metadata.collectionStats(collectionId).catch(() => null) ?? null;
     // Space left on the backing store, when it can say. Null for object stores, which
     // have no such number — and a UI that showed a made-up gauge for S3 would be worse
     // than one that shows nothing.
@@ -397,6 +401,10 @@ export function createRouter() {
   });
 
   // --- download (presign redirect or range-aware proxy) ----------------------
+  //
+  // `cost: 'download'`, and generously: a media player range-requests one file many
+  // times, which is one file's worth of bandwidth rather than many. The limit is there
+  // to bound a loop, not to bound watching a video.
 
   r.get('/api/items/download', [], async (ctx) => {
     const { query, req } = ctx;
@@ -415,9 +423,9 @@ export function createRouter() {
 
     // Ranged requests must proxy (we can't add Range to a bare redirect safely
     // for all clients), so only redirect for full-file GETs.
-    if (!range) {
-      const d = await node.download({ download: attach });
-      if (d.mode === 'redirect') return Response.redirect(d.url, 302);
+    if (!range && await node.canRedirect()) {
+      const { url } = await node.mintUrl({ op: 'download', download: attach });
+      return Response.redirect(url, 302);
     }
 
     const { stream, size, contentType, etag, range: served } = await node.read({ range });
@@ -435,7 +443,7 @@ export function createRouter() {
       return new Response(stream, { status: 206, headers });
     }
     return new Response(stream, { status: 200, headers });
-  });
+  }, { cost: 'download' });
 
   // Mint URLs that carry their own authorization, for the things that cannot send a
   // header. Batched on purpose: a gallery draws hundreds of tiles, and per-object
@@ -466,6 +474,10 @@ export function createRouter() {
 
   // --- uploads ---------------------------------------------------------------
 
+  // Metered at NEGOTIATION rather than per part: one session is one file, which is the
+  // unit `maxUploadBytes` is also about, and metering parts would punish a large file for
+  // being large rather than a caller for being greedy. Encrypted collections proxy BOTH
+  // directions since the drive seals, so this is the more expensive it has ever been.
   r.post('/api/collections/:collection/uploads', ['collections', 'vfs'], async (ctx) => {
     const b = await body(ctx.req);
     if (!b.name) throw TroveError.invalid('name is required');
@@ -484,7 +496,7 @@ export function createRouter() {
       name: b.name, size: Number(b.size ?? 0), contentType: b.contentType,
       overwrite: b.overwrite === true,
     }));
-  });
+  }, { cost: 'upload' });
 
   // An upload spans several requests keyed only by an unguessable id, so each one
   // re-obtains the handle — which re-asserts `write` on the session's collection. A
@@ -549,8 +561,11 @@ export function createRouter() {
     });
     return { query: query.q, results };
   };
-  r.get('/api/search', ['collections', 'vfs'], searchHandler);
-  r.get('/api/collections/:collection/search', ['collections', 'vfs'], searchHandler);
+  // `cost: 'search'` — on a deployment with TROVE_EMBEDDINGS_URL set, every one of these
+  // is a paid call to a third party. It is the one place an attacker spends the operator's
+  // money rather than their own CPU. See core/rateLimit.js.
+  r.get('/api/search', ['collections', 'vfs'], searchHandler, { cost: 'search' });
+  r.get('/api/collections/:collection/search', ['collections', 'vfs'], searchHandler, { cost: 'search' });
 
   // Unified query: a raw user string is run through the search transformer (default
   // parses `#tag` syntax; a plugged-in one may use an LLM), then dispatched. Returns
@@ -569,7 +584,7 @@ export function createRouter() {
     });
     return { query: b.q, results, resolved };
   };
-  r.post('/api/query', ['collections', 'vfs'], queryHandler);
+  r.post('/api/query', ['collections', 'vfs'], queryHandler, { cost: 'search' });
   r.post('/api/collections/:collection/query', ['collections', 'vfs'], queryHandler);
 
   // Drive-wide tag/property filter (the launcher's `#tag` / `#key:op:value`).
@@ -582,8 +597,8 @@ export function createRouter() {
     });
     return { items };
   };
-  r.post('/api/tags/search', ['collections', 'vfs'], tagSearchHandler);
-  r.post('/api/collections/:collection/tags/search', ['collections', 'vfs'], tagSearchHandler);
+  r.post('/api/tags/search', ['collections', 'vfs'], tagSearchHandler, { cost: 'search' });
+  r.post('/api/collections/:collection/tags/search', ['collections', 'vfs'], tagSearchHandler, { cost: 'search' });
 
   r.get('/api/indexers', ['vfs'], ({ vfs }) => ({ indexers: vfs.indexers.list() }));
 
@@ -700,7 +715,7 @@ export function createRouter() {
   // exists alongside the scheduled one: a bucket policy may legitimately name a single
   // origin, and the origin that matters is the one browsers are actually using to reach
   // the drive. A cron firing can only fall back to a configured TROVE_PUBLIC_URL.
-  r.post('/api/diagnostics/storage', ['collections', 'issues', 'storageCheck'], async (ctx) => {
+  r.post('/api/diagnostics/storage', ['collections', 'storageCheck'], async (ctx) => {
     await requireWholeDrive(ctx, 'check the backing stores');
     return ctx.storageCheck.run({ origin: publicOrigin(ctx.req, ctx.config) });
   });
@@ -718,7 +733,7 @@ export function createRouter() {
     await ctx.access.collection(collectionId, 'admin');
     requireHumanAdmin(ctx, 'estimate a key rotation');
     const record = await ctx.collections.get(collectionId);
-    const stats = await ctx.vfs.metadata.collectionStats?.(collectionId).catch(() => null);
+    const stats = await ctx.vfs.metadata.collectionStats(collectionId).catch(() => null);
     return estimateRotationCost(
       { driver: record.store?.driver, endpoint: record.store?.endpoint || record.store?.s3?.endpoint },
       { objects: stats?.items ?? 0, bytes: stats?.bytes ?? 0 },
@@ -743,7 +758,7 @@ export function createRouter() {
     // hours and holding the request open for it would just time out.
     const state = await ctx.rotation.begin(collectionId, ctx.principal);
     return { rotation: state };
-  });
+  }, { cost: 'job' });
 
   r.delete('/api/collections/:collection/rotate', ['collections', 'rotation'], async (ctx) => {
     const collectionId = scopedCollection(ctx);
@@ -757,9 +772,10 @@ export function createRouter() {
   // Rebuild the search index on demand. Admin-only: it re-reads every object in the
   // drive, so it is a real load, and it is drive-wide rather than scoped to anything
   // the caller owns. Returns the task, which is how the caller watches it.
+  // `cost: 'job'` — admin-gated is not rate-limited, and an admin key that leaks is
+  // otherwise a way to make the drive scan and re-index forever.
   r.post('/api/reindex', ['backgroundWork', 'collections', 'tasks'], async (ctx) => {
     await requireWholeDrive(ctx, 'rebuild the search index');
-    if (!ctx.backgroundWork) throw TroveError.unsupported('Reindexing is not available on this deployment');
     // Two concurrent full rebuilds would double the work to reach the same place, so
     // `beginReindex` claims the drive first and says whether it got it. The claim is
     // shared state rather than this process's task list — the other rebuild may be in
@@ -770,7 +786,7 @@ export function createRouter() {
       return { task: local || null, alreadyRunning: true };
     }
     return { task };
-  });
+  }, { cost: 'job' });
 
   // --- trash -----------------------------------------------------------------
   // Deleting moves an item here rather than destroying it. Everything below needs
@@ -814,7 +830,6 @@ export function createRouter() {
   // collection, because a scan can create items in it.
   r.post('/api/collections/:id/scan', ['backgroundWork', 'tasks'], async (ctx) => {
     await ctx.access.collection(ctx.params.id, 'write');
-    if (!ctx.backgroundWork) throw TroveError.unsupported('Scanning is not available on this deployment');
     const { task, alreadyRunning } = await ctx.backgroundWork.beginScan(ctx.params.id, { reason: 'Started manually' });
     if (alreadyRunning) {
       const local = (await ctx.tasks.list())
@@ -822,7 +837,7 @@ export function createRouter() {
       return { task: local || null, alreadyRunning: true };
     }
     return { task };
-  });
+  }, { cost: 'job' });
 
   // --- identity --------------------------------------------------------------
 
@@ -836,7 +851,7 @@ export function createRouter() {
     // which UI the client offers — the routes enforce regardless — but a `collections`
     // that went missing would tell every visitor they were an administrator, which is
     // a worse lie than an error.
-    admin: collectionsEnabled(ctx) ? ctx.collections.isAdmin(ctx.principal) : !!ctx.principal,
+    admin: ctx.collections.isAdmin(ctx.principal),
   }));
 
   // --- conversations, tags, sidecar (per file) -------------------------------
@@ -957,7 +972,7 @@ export function createRouter() {
     const bytes = await readBytesCapped(req, plugins.maxPackageBytes || 32 * 1024 * 1024);
     const grants = query.grants ? String(query.grants).split(',').map((s) => s.trim()).filter(Boolean) : undefined;
     return { install: await plugins.install({ principal, bytes, grants }) };
-  });
+  }, { cost: 'install' });
 
   // List this account's server-installed plugins (for cross-device sync).
   r.get('/api/plugins/installed', ['plugins'], async ({ plugins, principal }) => {
@@ -1140,69 +1155,15 @@ async function assertContributorOwned(ctx, contributorId) {
   await ctx.plugins.assertCapability(ctx.principal, parsed.pluginId, 'indexer');
 }
 
-/**
- * The collections this caller may read, optionally narrowed to one they asked for.
- * `undefined` when collections are disabled, which means "don't scope" downstream.
- *
- * Every drive-wide query needs this, and it has to be applied INSIDE the query rather
- * than by filtering results: a LIMIT spent on rows the caller can't see would report
- * "no matches" while matches they can see sit just past the cut.
- */
-async function readableCollectionIds(ctx, narrowTo) {
-  if (!collectionsEnabled(ctx)) return undefined;
-  // A NAMED collection is asserted, not filtered. Filtering an unreadable id out of the
-  // list answers "no results" for a collection the caller may not see — indistinguishable
-  // from one that is simply empty, so a permissions problem reads as an indexing problem.
-  // `access.collection` throws the 403 that says what actually happened.
-  if (narrowTo) {
-    await ctx.access.collection(narrowTo, 'read');
-    return [narrowTo];
-  }
-  return (await ctx.collections.list(ctx.principal)).map((c) => c.id);
-}
-
-/**
- * Whether this deployment has an ACL layer at all.
- *
- * Read from configuration, not from whether `ctx.collections` is truthy. The two
- * agree when everything is wired correctly, and diverge exactly when it is not —
- * and a security check that stands down because a service is missing is one that
- * stops enforcing at the worst possible moment. Configuration says whether to
- * enforce; the service does the enforcing, and if it is absent this throws.
- */
-const collectionsEnabled = (ctx) => ctx.config?.collections !== false;
-
-/**
- * Managing collections is only meaningful where there is an ACL layer to manage.
- *
- * From config, not from `ctx.collections` being null — the two agree today only
- * because the provider derives one from the other, and a build failure would make
- * "Collections are not enabled" a lie about a drive that has them.
- */
-function requireCollections(ctx) {
-  if (!collectionsEnabled(ctx)) throw TroveError.unsupported('Collections are not enabled');
-}
-
-async function assertCap(ctx, collectionId, capability) {
-  if (!collectionsEnabled(ctx)) return; // no ACL layer configured
-  await ctx.collections.assert(ctx.principal, collectionId, capability);
-}
-
 /**
  * Gate an operation that acts on the whole drive rather than on anything the caller
  * owns — rebuilding the index, cancelling someone else's task. See
  * CollectionService.hasWholeDrive for why this isn't plain `isAdmin`.
  */
 async function requireWholeDrive(ctx, what) {
-  const allowed = collectionsEnabled(ctx)
-    ? await ctx.collections.hasWholeDrive(ctx.principal)
-    : !!ctx.principal;
-  if (!allowed) throw TroveError.forbidden(`You do not have permission to ${what}`);
+  if (!(await wholeDriveFor(ctx))) throw TroveError.forbidden(`You do not have permission to ${what}`);
 }
-const canWholeDrive = (ctx) =>
-  (collectionsEnabled(ctx)
-    ? ctx.collections.hasWholeDrive(ctx.principal)
-    : Promise.resolve(!!ctx.principal));
+const canWholeDrive = (ctx) => wholeDriveFor(ctx);
 
 /**
  * Who may act on an issue: whoever may act on the thing it is about.
@@ -1237,7 +1198,7 @@ function requireHumanAdmin(ctx, action) {
     throw TroveError.forbidden(`An API key cannot ${action} — sign in as an administrator`);
   }
   requirePrincipal(ctx.principal);
-  const isAdmin = collectionsEnabled(ctx) ? ctx.collections.isAdmin(ctx.principal) : !!ctx.principal;
+  const isAdmin = ctx.collections.isAdmin(ctx.principal);
   if (!isAdmin) throw TroveError.forbidden(`You need to be an administrator to ${action}`);
 }