@3sln/trove 0.0.3 → 0.0.5

package/packages/server/src/index.js

@@ -15,9 +15,11 @@ import {
   VectorStore, KeywordStore, IndexerRegistry,
   accessHost, TroveError,
   protectedResourceMetadata, challengeHeaders, publicOrigin,
+  diagnoseStorage, STORAGE_ISSUE_CODES,
 } from '@3sln/trove/core';
-import { createRouter } from './routes.js';
+import { createRouter, routeHelpers } from './routes.js';
 import { createDriveEngine, scanStarter, BACKBONE } from './engine/index.js';
+import { storageRegistry } from './engine/providers/core.js';
 import { createMcpHandler } from './mcp/index.js';
 import { cacheControlFor } from './cachePolicy.js';
 import { MANIFEST_PATH, webManifest, manifestFromEnv } from './manifest.js';
@@ -51,6 +53,10 @@ export async function createServer(config = {}) {
   // 200 lines of statements whose ORDER was the graph is a declaration the
   // container walks, which is also what makes `close()` stop being a hand-kept
   // list that had to agree with it.
+  // The driver registry is decided once, here, and shared: the providers build backends
+  // 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) };
   const lifecycleState = { closing: false, background: null };
   const engine = createDriveEngine(config, lifecycleState);
 
@@ -60,7 +66,7 @@ export async function createServer(config = {}) {
   const backbone = await engine.container.lease(BACKBONE);
   const {
     storage, sqlite: sqliteProvider, metadata, kv, tasks, issues, notifications,
-    sidecar, collections, identity, auth, search, vfs, plugins,
+    sidecar, collections, identity, auth, search, vfs, plugins, apiKeys, capabilities,
   } = backbone.resources;
 
   // Aliased so the rest of this function reads as it did; the container's
@@ -153,6 +159,68 @@ export async function createServer(config = {}) {
   const routeBeginReindex = lifecycleState.background.beginReindex;
   issues.handle('scan-collection', (issue) => startScan(issue.retry.collectionId, { reason: 'Retrying after a failed scan' }));
 
+  // --- 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
     // the task fixing it — a task nobody is allowed to watch is not a task worth having.
@@ -197,9 +265,9 @@ export async function createServer(config = {}) {
   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(() => []) : [{ id: 'default' }])
+      Promise.resolve(collections ? collections.list(null).catch(() => []) : [])
         .then(async (list) => {
-          for (const c of list.length ? list : [{ id: 'default' }]) {
+          for (const c of list) {
             await startScan(c.id, { reason: 'Scheduled' }).catch(() => {});
           }
         })
@@ -210,6 +278,17 @@ export async function createServer(config = {}) {
 
   const router = createRouter();
 
+  // Routes contributed by delivery channels — the endpoints a client uses to REGISTER
+  // with one, of which a VAPID key and a push subscription are the obvious example.
+  // Mounted here rather than declared in routes.js so the drive's API reflects what is
+  // actually configured: no web push, no /api/push/*. Added after the core table, so a
+  // 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);
+    }
+  }
+
   // Said at boot, because that is when someone is looking and can still fix it. The
   // alternative is discovering it from a client that can't sign in and a 401 that
   // doesn't say why.
@@ -270,9 +349,20 @@ export async function createServer(config = {}) {
     if (url.pathname.startsWith('/api/')) {
       // Authenticate every API request; a bad token is a clean 401, missing is
       // anonymous-or-401 per the provider's policy.
+      //
+      // A capability grant is resolved FIRST, and when one is found the identity step is
+      // skipped entirely. That ordering is the design: an API key answers "what may this
+      // request do" and deliberately does not answer "who is this", so there is no
+      // principal to attach and nothing downstream can mistake a key for a person.
+      //
+      // Resolving both would be worse than useless. A request bearing a weak key and a
+      // strong session would get the union of the two, which is the confused deputy
+      // reached by being accommodating — so it is one or the other, never both.
       let principal = null;
+      let grant = null;
       try {
-        principal = await identity.authenticate(req);
+        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);
@@ -284,7 +374,7 @@ export async function createServer(config = {}) {
         // locator — nothing recorded what a route used, so nothing stopped it
         // reaching for more.
         container: engine.container,
-        config, principal, auth, mcp,
+        config, principal, grant, auth, mcp,
       });
       // 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
@@ -341,15 +431,40 @@ export async function createServer(config = {}) {
    * does, so it does as much as it can and stores where it got to.
    */
   async function runMaintenance({ budgetMs = 20_000, scan = true } = {}) {
-    const out = { swept: false, purged: 0, scans: [] };
+    const out = { swept: false, purged: 0, scans: [], notified: 0, storage: 0 };
     await vfs.uploads.sweepExpired(Date.now());
     await sidecar.sweep();
+    // 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
+    // mentions piled up in the pending store and were never delivered at all: no inbox
+    // entry, no push, no error. Maintenance runs from a cron there, which is the one
+    // thing that does fire. Harmless where the timer works — concurrent drains collapse.
+    out.notified = await notifications.flush().catch((e) => {
+      console.error('[trove] mention flush failed', e);
+      return 0;
+    });
+    // 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 })
+      .then((r) => r.checked)
+      .catch((e) => {
+        console.error('[trove] storage check failed', e);
+        return 0;
+      });
     const trashMs = (config.trashRetentionDays ?? 30) * 86400_000;
     if (trashMs > 0) out.purged = (await vfs.purgeTrash({ before: Date.now() - trashMs }))?.purged || 0;
     out.swept = true;
     if (!scan) return out;
-    const list = collections ? await collections.list(null).catch(() => []) : [];
-    const targets = list.length ? list : [{ id: 'default' }];
+    // `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.
+    // No collections means nothing to scan. It used to mean "scan the one called
+    // default", which on a drive that has none is a scan of a collection that does not
+    // exist — work that fails every cron firing and reports it as a scan error.
+    const targets = collections ? await collections.all().catch(() => []) : [];
+    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) {
@@ -359,7 +474,7 @@ export async function createServer(config = {}) {
     return out;
   }
 
-  return { vfs, handle, router, sidecar, notifications, identity, kv, collections, plugins, sqlite: sqliteProvider, tasks, issues, indexRebuild,
+  return { vfs, handle, router, sidecar, notifications, identity, apiKeys, capabilities, kv, collections, plugins, sqlite: sqliteProvider, tasks, issues, indexRebuild,
     // The graph itself, so an action or query can be dispatched directly — by a
     // test, by MCP, by anything that is not an HTTP route.
     engine, engineContainer: engine.container,
@@ -367,7 +482,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, mcp, auth, close };
+    runMaintenance, checkStorage, mcp, auth, close };
 }
 
 /**
@@ -619,7 +734,17 @@ export function configFromEnv(env = (typeof process !== 'undefined' ? process.en
   config.kv = { driver: env.TROVE_KV || (config.metadata.driver === 'sqlite' ? 'sqlite' : 'memory'), path: config.metadata.path };
 
   // Collections: on by default. Admins (global) + roles that can create collections.
-  if (env.TROVE_COLLECTIONS === 'false') config.collections = false;
+  // TROVE_COLLECTIONS=false used to mean "one implicit unnamed store, no ACLs". That is
+  // precisely the fallback this drive no longer has: every collection-scoped endpoint
+  // names its collection in the path, so there is nothing for an unnamed store to answer.
+  // Refused loudly rather than ignored — a drive that quietly kept enforcing after being
+  // told not to would be a surprise in the wrong direction.
+  if (env.TROVE_COLLECTIONS === 'false') {
+    throw TroveError.invalid(
+      'TROVE_COLLECTIONS=false is no longer supported — endpoints are scoped to a named '
+      + 'collection. Remove the setting; create one collection and use it.',
+    );
+  }
   config.admins = (env.TROVE_ADMINS || '').split(',').map((s) => s.trim()).filter(Boolean);
   config.creatorRoles = (env.TROVE_COLLECTION_CREATOR_ROLES || '').split(',').map((s) => s.trim()).filter(Boolean);
   // 'default' collection grants everyone all caps unless locked down.

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

@@ -98,6 +98,33 @@ async function readText(handle) {
  * `ctx` at call time carries { vfs, collections, principal } — the same objects the HTTP
  * routes get, so the two surfaces cannot drift apart on what a given user may do.
  */
+/**
+ * An agent has to say which collection it means.
+ *
+ * There used to be a `'default'` here, which made every tool call work on a fresh drive
+ * and quietly work on the WRONG collection on a real one — an agent asked to file
+ * something would put it wherever the default happened to be, which on a multi-user drive
+ * is a collection its user may not even be able to read. Naming it is one extra call to
+ * list_collections and removes a whole class of silently-misplaced writes.
+ */
+function requireCollection(collection) {
+  if (!collection) {
+    throw TroveError.invalid('A collection is required — call list_collections to see which ones you can use');
+  }
+}
+
+/**
+ * The same, but only when the reference needs it. A file id or a `trove:` URI already
+ * names its collection; a bare NAME is only unique within one.
+ */
+function requireCollectionForName(file, collection) {
+  const ref = String(file || '');
+  const selfNaming = ref.startsWith('trove:') || /^itm_/.test(ref);
+  if (!selfNaming && !collection) {
+    throw TroveError.invalid(`"${ref}" is a name, so it needs a collection — or pass a file id or trove: URI`);
+  }
+}
+
 export function registerTroveTools(server) {
   server.instructions = INSTRUCTIONS;
 
@@ -152,12 +179,13 @@ export function registerTroveTools(server) {
     inputSchema: {
       type: 'object',
       properties: {
-        collection: { type: 'string', description: 'Which collection (default: "default").' },
+        collection: { type: 'string', description: 'Which collection to act in. Required — call list_collections first.' },
         cursor: { type: 'string', description: 'Continue from a previous call.' },
         limit: { type: 'integer', description: `Maximum items (default 25, max ${MAX_RESULTS}).` },
       },
     },
-    async run({ collection = 'default', cursor, limit }, ctx) {
+    async run({ collection, cursor, limit }, ctx) {
+      requireCollection(collection);
       // The description promises recency and `list` defaults to alphabetical, so it
       // has to be asked for. An agent answering "what did I add recently?" off the top
       // of an alphabetical list is confidently wrong in a way nothing surfaces.
@@ -184,11 +212,12 @@ export function registerTroveTools(server) {
       type: 'object',
       properties: {
         file: { type: 'string', description: 'A file id, a name, or a trove: URI.' },
-        collection: { type: 'string', description: 'Which collection to look in when given a name (default: "default").' },
+        collection: { type: 'string', description: 'Which collection to look in. Required when `file` is a name; a file id or trove: URI names its own.' },
       },
       required: ['file'],
     },
-    async run({ file, collection = 'default' }, ctx) {
+    async run({ file, collection }, ctx) {
+      requireCollectionForName(file, collection);
       const handle = await fileHandle(ctx, file, collection, 'read');
       const node = handle.node;
       if (!textLike(node.contentType)) {
@@ -216,12 +245,13 @@ export function registerTroveTools(server) {
       properties: {
         name: { type: 'string', description: 'The file name, including its extension.' },
         content: { type: 'string', description: 'The text to write.' },
-        collection: { type: 'string', description: 'Which collection (default: "default").' },
+        collection: { type: 'string', description: 'Which collection to act in. Required — call list_collections first.' },
         contentType: { type: 'string', description: 'Override the type guessed from the name.' },
       },
       required: ['name', 'content'],
     },
-    async run({ name, content, collection = 'default', contentType }, ctx) {
+    async run({ name, content, collection, contentType }, ctx) {
+      requireCollection(collection);
       if (!name?.trim()) throw TroveError.invalid('name is required');
       const into = await ctx.access.collection(collection, 'write');
       // No contentType falls through to the vfs's own guess from the name.
@@ -245,7 +275,8 @@ export function registerTroveTools(server) {
       },
       required: ['file'],
     },
-    async run({ file, collection = 'default' }, ctx) {
+    async run({ file, collection }, ctx) {
+      requireCollectionForName(file, collection);
       const handle = await fileHandle(ctx, file, collection, 'delete');
       await handle.remove();
       return toolText(`Moved "${handle.name}" to the trash. It can be restored from the drive's trash.`);
@@ -284,7 +315,8 @@ export function registerTroveTools(server) {
       },
       required: ['file'],
     },
-    async run({ file, collection = 'default' }, ctx) {
+    async run({ file, collection }, ctx) {
+      requireCollectionForName(file, collection);
       const handle = await fileHandle(ctx, file, collection, 'read');
       const node = handle.node;
       // Scoped, exactly like the HTTP route. Backlinks reach ACROSS collections by

package/packages/server/src/router.js

@@ -139,7 +139,7 @@ export class Router {
     // handler asks for an AUTHORIZED view of a node, collection or upload: the
     // grant is carried by the object it hands back, so there is no unrestricted
     // service and no raw id left over to use with one.
-    const scope = leaseScope(ctx.container, ctx.principal);
+    const scope = leaseScope(ctx.container, ctx.principal, ctx.grant);
     const access = scope.access;
     try {
       lease = ctx.container ? await ctx.container.lease(found.route.deps) : null;