@3sln/trove 0.0.12 → 0.0.13

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

package/packages/server/src/scope.js

@@ -9,6 +9,15 @@
 // Both request surfaces need it. The HTTP router obviously; MCP just as much, because
 // an agent holding Alice's token is Alice and there must be no MCP-shaped way around
 // the ACL. Written once so the two cannot drift.
+//
+// The same goes for WHO IS ASKING and what that subject may reach. Those helpers lived in
+// routes.js, and mcp/tools.js grew its own copies — which drifted, in the direction that
+// surface makes worst: MCP filtered a named collection out of the readable list, so an
+// agent asking about a collection it may not see was told "No files matched… Try different
+// words" and burned turns rephrasing a permissions error. mcp/index.js claims "It is not a
+// second access-control system to keep in sync with the first"; it was one.
+
+import { TroveError } from '@3sln/trove/core';
 
 /**
  * @param {object|null} container the engine container, or null where there is none
@@ -41,3 +50,72 @@ export function leaseScope(container, principal, grant = null) {
     },
   };
 }
+
+/**
+ * The collections this caller may read, optionally narrowed to one they asked for.
+ *
+ * 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.
+ *
+ * Always a list. It used to answer `undefined` for "don't scope" on a drive with ACLs
+ * switched off, and there is no such drive: `collections: false` is refused by
+ * `configFromEnv` and again by the provider.
+ */
+export async function readableCollectionIds(ctx, narrowTo) {
+  // 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 listFor(ctx)).map((c) => c.id);
+}
+
+// --- who is asking ------------------------------------------------------------
+//
+// On a key request `ctx.principal` is NULL and the authority lives on `ctx.grant`, so
+// handing the principal to CollectionService asks about the anonymous caller instead of
+// about the key. That failed in both directions: on a locked drive a correctly-scoped
+// key got `list(null) === []` and 403s from search, tags, backlinks, tasks and issues,
+// while on a `defaultOpen` drive the `anyone` grant let a key scoped to one collection
+// read and write every one of them through those same routes. engine/providers/access.js
+// was the only place that had it right.
+//
+// One helper per question, so "does this surface understand API keys" has one answer
+// rather than one per call site. Never a union of the two: a request bearing a key is
+// the key's request, and falling back to whatever session is attached is how a weak
+// credential borrows a strong one.
+
+export const listFor = (ctx) =>
+  (ctx.grant ? ctx.collections.listForGrant(ctx.grant) : ctx.collections.list(ctx.principal));
+
+export const wholeDriveFor = (ctx) =>
+  (ctx.grant ? ctx.collections.grantHasWholeDrive(ctx.grant) : ctx.collections.hasWholeDrive(ctx.principal));
+
+/** Returns the collection record, so a caller that needs it does not assert twice. */
+export async function assertCap(ctx, collectionId, capability) {
+  return ctx.grant
+    ? ctx.collections.assertForGrant(ctx.grant, collectionId, capability)
+    : ctx.collections.assert(ctx.principal, collectionId, capability);
+}
+
+/** The `describe` that matches whoever asked, so the reported capabilities are theirs. */
+export const describeFor = (ctx, c) =>
+  (ctx.grant ? ctx.collections.describeForGrant(c, ctx.grant) : ctx.collections.describe(c, ctx.principal));
+
+/**
+ * Refuse a request that arrived on an API key.
+ *
+ * For the collection-ADMINISTRATION verbs, whose authority CollectionService reads from
+ * the principal alone. A key request has no principal, so those methods judge it as the
+ * anonymous caller — allowing everything on a `defaultOpen` drive and nothing on a locked
+ * one. Rather than teach create/update/remove/setGrant about grants, keys stay out: a key
+ * that can rewrite a collection's ACL can grant itself whatever it lacks, which is the
+ * self-escalation shape `requireHumanAdmin` refuses for the same reason.
+ */
+export function refuseGrant(ctx, action) {
+  if (ctx.grant) throw TroveError.forbidden(`An API key cannot ${action} — sign in instead`);
+}