@3sln/trove 0.0.3 → 0.0.5

package/packages/server/src/routes.js

@@ -134,8 +134,22 @@ function assertPublicHost(hostname) {
 
 // Which collection a request targets. There is no folder to infer one from any more,
 // so it's named explicitly or it's the default.
-function collectionOf(src) {
-  return src?.collection || src?.collectionId || 'default';
+/**
+ * The collection a request is scoped to, from the PATH.
+ *
+ * There is no fallback. A collection-scoped route names its collection in the URL —
+ * `/api/collections/:collection/items` — so a request that does not name one cannot
+ * reach the handler at all, and the router refuses it before this is called.
+ *
+ * The fallback that used to live here (`?collection=` or else `'default'`) was the same
+ * class of bug as everything else in this file's history: a missing value silently
+ * became a specific one, so an unscoped write went somewhere real and looked fine. On a
+ * multi-user drive that somewhere was a collection plenty of people cannot even read.
+ */
+function scopedCollection(ctx) {
+  const id = ctx.params?.collection;
+  if (!id) throw TroveError.invalid('This endpoint is scoped to a collection');
+  return id;
 }
 
 export function createRouter() {
@@ -163,8 +177,13 @@ export function createRouter() {
       storage = await (await ctx.access.collection(query.collection, 'read')).storage();
     }
     return {
-      collection: query.collection || 'default',
+      collection: query.collection || null,
       storage: storage.capabilities,
+      // What kinds of backing store THIS deployment can build, with the fields each one
+      // needs. The collection form used to hardcode this list, which is how a Cloudflare
+      // Workers drive came to offer "Filesystem / NAS" — a choice its runtime cannot
+      // honour. Answered by the server now, so the form can only offer what exists.
+      storageDrivers: ctx.config.storageRegistry?.describe?.() || [],
       indexers: vfs.indexers.list(),
       partSize: vfs.uploads.partSize,
       features: {
@@ -213,13 +232,11 @@ export function createRouter() {
 
   r.get('/api/collections', ['collections'], async (ctx) => {
     const { collections, principal } = ctx;
-    if (!collectionsEnabled(ctx)) return { collections: [{ id: 'default', name: 'My Drive', capabilities: ['read', 'write', 'delete', 'admin'] }] };
     return { collections: await collections.list(principal), canCreate: collections.canCreate(principal) };
   });
 
   r.get('/api/collections/:id', ['collections'], async (ctx) => {
     const { collections, principal, params } = ctx;
-    if (!collectionsEnabled(ctx)) return { collection: { id: 'default', name: 'My Drive' } };
     const c = await collections.assert(principal, params.id, 'read');
     return { collection: collections.describe(c, principal) };
   });
@@ -259,6 +276,37 @@ export function createRouter() {
     return { collection: await ctx.collections.setGrant(ctx.params.id, await body(ctx.req), ctx.principal) };
   });
 
+  // --- API keys ---------------------------------------------------------------
+  //
+  // Managing keys requires a real admin PRINCIPAL, and a key can never be used to reach
+  // these routes — `requireHumanAdmin` refuses when the request arrived on a grant. That
+  // asymmetry is deliberate: a key that could mint keys is a key that can escalate
+  // itself, and revoking it would not revoke what it had already issued. The blast
+  // radius of a leaked key stops at the capabilities it was given.
+
+  r.get('/api/keys', ['apiKeys', 'collections'], async (ctx) => {
+    requireHumanAdmin(ctx, 'manage API keys');
+    return { keys: await ctx.apiKeys.list() };
+  });
+
+  r.post('/api/keys', ['apiKeys', 'collections'], async (ctx) => {
+    requireHumanAdmin(ctx, 'mint API keys');
+    const b = await body(ctx.req);
+    // The secret comes back exactly once, here, and is never retrievable again.
+    const { record, secret } = await ctx.apiKeys.mint({
+      name: b.name,
+      scopes: b.scopes,
+      expiresAt: b.expiresAt ?? null,
+      createdBy: ctx.principal?.id ?? null,
+    });
+    return { key: record, secret };
+  });
+
+  r.delete('/api/keys/:id', ['apiKeys', 'collections'], async (ctx) => {
+    requireHumanAdmin(ctx, 'revoke API keys');
+    return { key: await ctx.apiKeys.revoke(ctx.params.id) };
+  });
+
   // --- browse ----------------------------------------------------------------
 
   // --- items -----------------------------------------------------------------
@@ -269,9 +317,9 @@ export function createRouter() {
 
   // Every item in a collection. There is nothing to descend into — a drive is browsed
   // by search and by following links, and this is the "show me everything" fallback.
-  r.get('/api/items', ['vfs'], async (ctx) => {
+  r.get('/api/collections/:collection/items', ['vfs'], async (ctx) => {
     const { vfs, query } = ctx;
-    const collectionId = collectionOf(query);
+    const collectionId = scopedCollection(ctx);
     const collection = await ctx.access.collection(collectionId, 'read');
     const { items, nextCursor } = await collection.list({
       sort: query.sort, order: query.order,
@@ -290,12 +338,12 @@ export function createRouter() {
   });
 
   // Resolve an item: by id, by `?name=` within a collection, or by a `trove:` URI.
-  r.get('/api/items/resolve', [], async (ctx) => {
+  r.get('/api/collections/:collection/items/resolve', [], async (ctx) => {
     const ref = ctx.query.id || ctx.query.uri || ctx.query.name;
     if (!ref) throw TroveError.invalid('id, name or uri is required');
-    // A name is only unique within a collection, so the hint goes to `stat`; the
-    // capability is asserted on the collection the node turns out to be in.
-    const handle = await ctx.access.node(ref, 'read', { collectionId: collectionOf(ctx.query) });
+    // A name is only unique within a collection, which is the reason this one is scoped
+    // by path at all: resolving `notes.md` is a different question in each collection.
+    const handle = await ctx.access.node(ref, 'read', { collectionId: scopedCollection(ctx) });
     return { node: handle.node };
   });
 
@@ -396,10 +444,10 @@ export function createRouter() {
 
   // --- uploads ---------------------------------------------------------------
 
-  r.post('/api/uploads', [], async (ctx) => {
+  r.post('/api/collections/:collection/uploads', [], async (ctx) => {
     const b = await body(ctx.req);
     if (!b.name) throw TroveError.invalid('name is required');
-    const collection = await ctx.access.collection(collectionOf(b), 'write');
+    const collection = await ctx.access.collection(scopedCollection(ctx), 'write');
     return uploadDescriptor(await collection.createUpload({
       name: b.name, size: Number(b.size ?? 0), contentType: b.contentType,
       overwrite: b.overwrite === true,
@@ -442,26 +490,44 @@ export function createRouter() {
 
   // --- search & indexing -----------------------------------------------------
 
-  r.get('/api/search', ['collections', 'vfs'], async (ctx) => {
+  // Raw search: the query string is passed through as text, with NO transformer.
+  //
+  // Which means the `#tag` grammar does not apply here. `/api/capabilities` advertises a
+  // searchPrompt telling people `#tag` narrows by tag, and against this endpoint that
+  // degrades into a text search for the literal string "#tag" — no error, just quietly
+  // different results. POST /api/query is the one that runs the transformer and is what
+  // the workbench uses; this stays as the lower-level endpoint for callers that have
+  // already resolved their own query.
+  // Searching comes in two shapes, and which one you get is in the URL rather than in
+  // the presence of a parameter. The flat route searches every collection the caller can
+  // read; the scoped one searches exactly the collection it names.
+  //
+  // Two routes rather than `?collection=` because omitting a query parameter used to mean
+  // "the whole drive" — a missing value silently choosing the broadest possible scope,
+  // which is the same failure shape as the old `'default'` fallback pointing the other
+  // way. Neither is something to arrive at by accident.
+  const searchHandler = async (ctx) => {
     const { vfs, query } = ctx;
     if (!query.q) throw TroveError.invalid('q is required');
-    const collectionIds = await readableCollectionIds(ctx, query.collection);
+    const collectionIds = await readableCollectionIds(ctx, ctx.params?.collection);
     const results = await vfs.searchQuery(query.q, {
       mode: query.mode, limit: clampLimit(query.limit, 40),
       indexers: query.indexers ? query.indexers.split(',') : undefined,
       collectionIds,
     });
     return { query: query.q, results };
-  });
+  };
+  r.get('/api/search', ['collections', 'vfs'], searchHandler);
+  r.get('/api/collections/:collection/search', ['collections', 'vfs'], searchHandler);
 
   // 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
   // the results AND the `resolved` query (what was actually searched) so the client
   // can honestly show it.
-  r.post('/api/query', ['collections', 'vfs'], async (ctx) => {
+  const queryHandler = async (ctx) => {
     const b = await body(ctx.req);
     if (typeof b.q !== 'string' || !b.q.trim()) throw TroveError.invalid('q is required');
-    const collectionIds = await readableCollectionIds(ctx, b.collection);
+    const collectionIds = await readableCollectionIds(ctx, ctx.params?.collection);
     const { results, resolved } = await ctx.vfs.query(b.q, {
       mode: b.mode, limit: clampLimit(b.limit, 40), collectionIds,
       // Which views this client can draw with, so the transformer can suggest one of
@@ -470,18 +536,22 @@ export function createRouter() {
       views: Array.isArray(b.views) ? b.views : undefined,
     });
     return { query: b.q, results, resolved };
-  });
+  };
+  r.post('/api/query', ['collections', 'vfs'], queryHandler);
+  r.post('/api/collections/:collection/query', ['collections', 'vfs'], queryHandler);
 
   // Drive-wide tag/property filter (the launcher's `#tag` / `#key:op:value`).
-  r.post('/api/tags/search', ['collections', 'vfs'], async (ctx) => {
+  const tagSearchHandler = async (ctx) => {
     const b = await body(ctx.req);
     const filters = Array.isArray(b.filters) ? b.filters : [];
-    const collectionIds = await readableCollectionIds(ctx, b.collection);
+    const collectionIds = await readableCollectionIds(ctx, ctx.params?.collection);
     const items = await ctx.vfs.findByTags(filters, {
       q: b.q, collectionIds, limit: clampLimit(b.limit, 100),
     });
     return { items };
-  });
+  };
+  r.post('/api/tags/search', ['collections', 'vfs'], tagSearchHandler);
+  r.post('/api/collections/:collection/tags/search', ['collections', 'vfs'], tagSearchHandler);
 
   r.get('/api/indexers', ['vfs'], ({ vfs }) => ({ indexers: vfs.indexers.list() }));
 
@@ -590,6 +660,19 @@ export function createRouter() {
     return { ok: true };
   });
 
+  // Check the backing stores on demand, and answer with what was found rather than only
+  // leaving issues behind — an admin who just pressed "Check storage" is owed the result
+  // of the check they asked for.
+  //
+  // Origin comes from THIS request, which is the whole reason the on-demand version
+  // 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) => {
+    await requireWholeDrive(ctx, 'check the backing stores');
+    return ctx.storageCheck.run({ origin: publicOrigin(ctx.req, ctx.config) });
+  });
+
   // 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.
@@ -613,8 +696,8 @@ export function createRouter() {
   // `delete` on the collection, the same capability the delete itself needed — seeing
   // what you deleted, and undoing it, are not lesser rights than deleting.
 
-  r.get('/api/trash', [], async (ctx) => {
-    const collectionId = collectionOf(ctx.query);
+  r.get('/api/collections/:collection/trash', [], async (ctx) => {
+    const collectionId = scopedCollection(ctx);
     const collection = await ctx.access.collection(collectionId, 'delete');
     return { items: await collection.listTrash({ limit: clampLimit(ctx.query.limit, 200) }), collectionId };
   });
@@ -629,14 +712,19 @@ export function createRouter() {
 
   // Destroy for real. Separate from DELETE /api/items so that emptying the trash can
   // never be something you reach by accident from the ordinary delete path.
+  // One item, by id. The node names its own collection, so this stays flat.
   r.post('/api/trash/purge', [], async (ctx) => {
     const b = await body(ctx.req);
-    if (b.id) {
-      const node = await ctx.access.node(b.id, 'delete', { trashed: true });
-      await node.remove({ permanent: true });
-      return { purged: 1 };
-    }
-    const collection = await ctx.access.collection(collectionOf(b), 'delete');
+    if (!b.id) throw TroveError.invalid('id is required — to empty a collection\u2019s trash, use /api/collections/:collection/trash/purge');
+    const node = await ctx.access.node(b.id, 'delete', { trashed: true });
+    await node.remove({ permanent: true });
+    return { purged: 1 };
+  });
+
+  // Empty a whole collection's trash. Scoped by path, because "everything in here" is
+  // exactly the request that must never be able to mean a collection you did not name.
+  r.post('/api/collections/:collection/trash/purge', [], async (ctx) => {
+    const collection = await ctx.access.collection(scopedCollection(ctx), 'delete');
     return collection.purgeTrash({ limit: MAX_PAGE });
   });
 
@@ -748,20 +836,10 @@ export function createRouter() {
     return notifications.markRead(principal.id, b.ids);
   });
 
-  r.get('/api/push/vapid', ['notifications'], ({ notifications }) => ({ publicKey: notifications?.vapidPublicKey() || null }));
-
-  r.post('/api/push/subscribe', ['notifications'], async ({ notifications, principal, req }) => {
-    requireNotifications(notifications);
-    requirePrincipal(principal);
-    const b = await body(req);
-    return notifications.subscribePush(principal.id, b.subscription);
-  });
-  r.delete('/api/push/subscribe', ['notifications'], async ({ notifications, principal, req }) => {
-    requireNotifications(notifications);
-    requirePrincipal(principal);
-    const b = await body(req);
-    return notifications.unsubscribePush(principal.id, b.endpoint);
-  });
+  // /api/push/* is not here. Registering with a delivery channel is the channel's own
+  // business — see WebPushChannel.routes() — so the drive's route table does not carry
+  // endpoints for a transport it may not have configured, and adding email or chat does
+  // not mean editing this file.
 
   // --- plugins: domain verification proxy + per-plugin server storage --------
 
@@ -991,8 +1069,15 @@ async function assertContributorOwned(ctx, contributorId) {
  */
 async function readableCollectionIds(ctx, narrowTo) {
   if (!collectionsEnabled(ctx)) return undefined;
-  const readable = (await ctx.collections.list(ctx.principal)).map((c) => c.id);
-  return narrowTo ? readable.filter((id) => id === narrowTo) : readable;
+  // 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);
 }
 
 /**
@@ -1058,9 +1143,34 @@ async function assertTaskAccess(ctx, task, what) {
   if (task.collectionId == null) return requireWholeDrive(ctx, `${what} a drive-wide task`);
   await assertCap(ctx, task.collectionId, 'write');
 }
+/**
+ * An admin, in person.
+ *
+ * Two refusals, not one. A grant is refused outright — an API key must never be able to
+ * manage API keys, however broadly it was scoped, because a key that can mint keys can
+ * outlive its own revocation. Then the ordinary admin check on the principal.
+ */
+function requireHumanAdmin(ctx, action) {
+  if (ctx.grant) {
+    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;
+  if (!isAdmin) throw TroveError.forbidden(`You need to be an administrator to ${action}`);
+}
+
 function requirePrincipal(principal) {
   if (!principal) throw TroveError.unauthorized('Authentication required');
 }
 function requireNotifications(n) {
   if (!n) throw TroveError.unsupported('Notifications are not enabled on this server');
 }
+
+/**
+ * The request plumbing handed to routes contributed from outside this file.
+ *
+ * `body` is the capped JSON read — the cap is the reason to share it rather than let a
+ * channel call `req.json()` and accept an unbounded body — and `requirePrincipal` is
+ * the same 401 every route here throws.
+ */
+export const routeHelpers = { body, requirePrincipal };

package/packages/server/src/scope.js

@@ -15,12 +15,12 @@
  * @param {object|null} principal who is asking
  * @returns {{access: object|null, release: () => Promise<void>}}
  */
-export function leaseScope(container, principal) {
+export function leaseScope(container, principal, grant = null) {
   const held = [];
   if (!container) return { access: null, release: async () => {} };
 
   const obtain = async (name, request) => {
-    const lease = await container.lease({ [name]: { principal, ...request } });
+    const lease = await container.lease({ [name]: { principal, grant, ...request } });
     held.push(lease);
     return lease.resources[name];
   };