@3sln/trove 0.0.7 → 0.0.9

package/packages/server/src/adapters/staticAssets.js

@@ -33,6 +33,7 @@ import path from 'node:path';
 // The policy lives in its own module because index.js needs it too and has to stay
 // loadable on Workers, where `node:path` is not there to be imported.
 import { IMMUTABLE_PREFIX, cacheControlFor } from '../cachePolicy.js';
+import { SHARE_PATH } from '@3sln/trove/core/links.js';
 
 export { IMMUTABLE_PREFIX, cacheControlFor };
 
@@ -46,10 +47,16 @@ export const MIME = {
 /**
  * Should a miss here fall back to the SPA entry point?
  *
- * The client never puts a path in the URL — `navigation.js` calls pushState with no URL
- * argument, so the whole app lives at `/`. The fallback is therefore for robustness
- * (a refresh somewhere unexpected), never for deep links, which is what makes it safe
- * to refuse anything that looks like a file rather than a route.
+ * Most of the app lives at `/` — `navigation.js` pushes state with no URL — so for those
+ * views the fallback is only robustness, a refresh landing somewhere unexpected.
+ *
+ * Share links are the exception, and they break the rule this used to rest on. A share
+ * link is `/c/<collection>/i/<item>`, and an item name ends in a filename, so
+ * "anything with an extension is asking for a file" refused exactly the deep link the
+ * scheme exists to provide: the server 404'd before the app could load, and the
+ * client-side routing that would have resolved it never ran. A share path is a route
+ * whatever it ends with, so it is recognised before the extension rule rather than
+ * fighting it.
  *
  * @param {string} pathname
  */
@@ -58,7 +65,9 @@ export function shouldFallBack(pathname) {
   // Content-addressed: a miss is a stale reference to a build that no longer exists.
   // Answering it with HTML is what poisons a service worker cache.
   if (pathname.startsWith(IMMUTABLE_PREFIX)) return false;
-  // Anything with an extension is asking for a file, not a view.
+  // A route the app owns, named by the same module that produces the links.
+  if (pathname === SHARE_PATH || pathname.startsWith(`${SHARE_PATH}/`)) return true;
+  // Anything else with an extension is asking for a file, not a view.
   if (path.extname(pathname)) return false;
   return true;
 }

package/packages/server/src/engine/index.js

@@ -49,7 +49,7 @@ export function createDriveEngine(config = {}, lifecycleState = { closing: false
 export const BACKBONE = [
   'storage', 'sqlite', 'metadata', 'kv', 'tasks', 'issues', 'notifications',
   'sidecar', 'collections', 'identity', 'auth', 'search', 'vfs', 'plugins',
-  'apiKeys', 'capabilities', 'lifecycle',
+  'apiKeys', 'capabilities', 'rotation', 'lifecycle',
 ];
 
 /** The shape `beginScan` has always returned, so no caller has to change. */

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

@@ -32,6 +32,8 @@ import {
   IdentityProvider, JwtIdentityProvider, HeaderIdentityProvider, AnonymousIdentityProvider,
   cloudflareAccess,
   KeyValueStore, MemoryKV, SqliteKV,
+  KvSessionStore,
+  RotationService,
   SqliteProvider, LocalSqliteProvider,
   SidecarService, NotificationCenter, WebPushService, WebPushChannel, NotificationChannel,
   ApiKeyService, CapabilityProvider, ApiKeyCapabilityProvider,
@@ -329,6 +331,17 @@ export function coreProviders(config, lifecycleState) {
     // and the task succeeding clears the issue.
     tasks: Provider.fromLazySingleton(() => resolve(config.tasks, TaskRegistry, () => new TaskRegistry())),
 
+    // Moving a collection onto a new key, incrementally. Depends on vfs rather than the
+    // other way round, so it sits after it in the graph and the container orders itself.
+    rotation: Provider.fromLazySingleton(
+      async (deps) => {
+        const { kv, vfs, collections } = await need(deps, ['kv', 'vfs', 'collections']);
+        return new RotationService({ kv, vfs, collections });
+      },
+      null,
+      { deps: ['kv', 'vfs', 'collections'] },
+    ),
+
     issues: Provider.fromLazySingleton(
       async (deps) => {
         const { kv } = await need(deps, ['kv']);
@@ -461,11 +474,17 @@ export function coreProviders(config, lifecycleState) {
       async (deps) => {
         const r = await need(deps, [
           'storage', 'metadata', 'search', 'indexers', 'sidecar', 'collections',
-          'searchTransformer', 'issues', 'signedUrls',
+          'searchTransformer', 'issues', 'signedUrls', 'kv',
         ]);
         const vfs = new Vfs({
           ...r,
           maxUploadBytes: config.maxUploadBytes ?? null,
+          // Upload sessions in the KeyValueStore rather than this process's memory. An
+          // upload spans several requests and the session is the only thing joining them,
+          // so on a runtime that can serve those requests from different isolates an
+          // in-memory Map means "upload session not found" on a drive where nothing is
+          // wrong. See KvSessionStore.
+          uploadSessions: new KvSessionStore({ kv: r.kv }),
           // Where this server can be reached from outside, for the URLs that leave the
           // browser (an indexer hands one to an external API). Absent, those are refused
           // rather than handed out as links to nowhere.
@@ -475,7 +494,7 @@ export function coreProviders(config, lifecycleState) {
         return vfs;
       },
       null,
-      { deps: ['storage', 'metadata', 'search', 'indexers', 'sidecar', 'collections', 'searchTransformer', 'issues', 'signedUrls'] },
+      { deps: ['storage', 'metadata', 'search', 'indexers', 'sidecar', 'collections', 'searchTransformer', 'issues', 'signedUrls', 'kv'] },
     ),
 
     // Bulk plugin package blobs. Defaults to the primary storage under a prefix;

package/packages/server/src/index.js

@@ -66,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, apiKeys, capabilities,
+    sidecar, collections, identity, auth, search, vfs, plugins, apiKeys, capabilities, rotation,
   } = backbone.resources;
 
   // Aliased so the rest of this function reads as it did; the container's
@@ -232,6 +232,36 @@ export async function createServer(config = {}) {
     ? null
     : rebuildIndexIfLost(vfs, search, startReindex);
 
+  /**
+   * Advance every rotation that is part-way through, and say what moved.
+   *
+   * Extracted because there are TWO schedulers — the interval below, for a process that
+   * lives, and `runMaintenance`, for a Worker whose timers do not survive the request —
+   * and only the second one used to step rotations. On Bun and Node, which is where this
+   * is self-hosted, `POST /rotate` therefore minted the new key, reported "running", and
+   * then moved nothing, ever: `rotation.step` had no caller, and there is no route that
+   * steps one either. The old key stayed in the ring indefinitely, which is the exact
+   * failure a rotation exists to end.
+   *
+   * One function, both callers, so the next thing added to periodic work cannot land in
+   * one scheduler and not the other.
+   */
+  async function stepRotations(targets, budgetEach) {
+    const out = [];
+    for (const c of targets) {
+      const state = await rotation.state(c.id).catch(() => null);
+      if (!state || state.status !== 'running') continue;
+      // The slice claims the collection, so a firing that overlaps a manual run does
+      // nothing rather than racing it.
+      const next = await rotation.step(c.id, { budgetMs: budgetEach }).catch((e) => {
+        console.error(`[trove] rotation slice for ${c.id} failed`, e);
+        return null;
+      });
+      if (next) out.push({ collectionId: c.id, moved: next.moved, failed: next.failed, status: next.status });
+    }
+    return out;
+  }
+
   // Periodic maintenance. Both of these caches are otherwise unbounded: abandoned
   // upload sessions (a client that starts an upload and never finishes) accumulate in
   // the session store forever, and sidecar documents stay resident after their last
@@ -251,6 +281,12 @@ export async function createServer(config = {}) {
         .then(() => sidecar.sweep())
         .then(() => (trashMs > 0 ? vfs.purgeTrash({ before: Date.now() - trashMs }) : null))
         .then((r) => { if (r?.purged) console.log(`[trove] purged ${r.purged} item(s) from the trash after ${config.trashRetentionDays ?? 30} days`); })
+        // A rotation started through the API finishes on its own here. Unlike a scan this
+        // is NOT opt-in: it only touches collections someone has explicitly put into
+        // rotation, and leaving one half-moved is worse than the work of finishing it.
+        .then(() => (collections ? collections.all().catch(() => []) : []))
+        .then((targets) => stepRotations(targets, Math.max(1000, Math.floor(everyMs / 4))))
+        .then((moved) => { for (const m of moved) if (m.moved) console.log(`[trove] rotation ${m.collectionId}: ${m.moved} moved, ${m.status}`); })
         .catch((e) => console.error('maintenance sweep failed', e));
     }, everyMs);
     maintenance.unref?.();
@@ -471,6 +507,13 @@ export async function createServer(config = {}) {
       const r = await startScan(c.id, { reason: 'Scheduled', deadlineMs: each }).catch((e) => ({ error: e.message }));
       out.scans.push({ collectionId: c.id, ...r });
     }
+
+    // A rotation that has been started finishes on its own — see `stepRotations`, which
+    // the interval scheduler shares so the two cannot drift apart.
+    //
+    // Last, and out of what the scans left, because a rotation is elective and a scan is
+    // how the drive notices files that changed underneath it.
+    out.rotated = await stepRotations(targets, each);
     return out;
   }
 
@@ -482,7 +525,7 @@ export async function createServer(config = {}) {
     // inside a Durable Object want. `begin*` goes wherever `config.background` says,
     // which for a front-line Worker isolate is the object rather than itself.
     startScan, startReindex, beginScan: routeBeginScan, beginReindex: routeBeginReindex,
-    runMaintenance, checkStorage, mcp, auth, close };
+    runMaintenance, checkStorage, rotation, mcp, auth, close };
 }
 
 /**

package/packages/server/src/routes.js

@@ -5,6 +5,7 @@
 import { Router, json, parseRange } from './router.js';
 import {
   TroveError, assertSafePluginSql, concatBytes, metadataUrl, publicOrigin,
+  shouldEncrypt, estimateRotationCost,
 } from '@3sln/trove/core';
 import { parseContribUri, CORE_DOMAIN } from '@3sln/trove/core/plugins/identity.js';
 
@@ -444,10 +445,20 @@ export function createRouter() {
 
   // --- uploads ---------------------------------------------------------------
 
-  r.post('/api/collections/:collection/uploads', [], async (ctx) => {
+  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');
     const collection = await ctx.access.collection(scopedCollection(ctx), 'write');
+    // `write` is enough again, including on an encrypted collection.
+    //
+    // This used to demand `read` as well, for a good reason that has since gone away: the
+    // plan handed the client the collection's data key so it could seal locally, and that
+    // key decrypts EVERYTHING in the collection — a read capability however it arrives. So
+    // a write-only ingest credential, which the key model explicitly supports, could not
+    // upload to an encrypted collection at all.
+    //
+    // The drive seals now and the key never leaves it, so a plan carries nothing readable
+    // and there is nothing left to protect. A write-only credential works everywhere.
     return uploadDescriptor(await collection.createUpload({
       name: b.name, size: Number(b.size ?? 0), contentType: b.contentType,
       overwrite: b.overwrite === true,
@@ -673,6 +684,55 @@ export function createRouter() {
     return ctx.storageCheck.run({ origin: publicOrigin(ctx.req, ctx.config) });
   });
 
+  // --- key rotation ----------------------------------------------------------
+  //
+  // Moving a collection onto a new key is admin work in the strict sense: it rewrites every
+  // object in the collection and costs real money on a metered store. `requireHumanAdmin`
+  // refuses a request arriving on an API key — a credential that could re-key a collection
+  // could also make its contents unreadable to everyone else holding the old one.
+
+  /** What a rotation would cost, before anyone starts one. */
+  r.get('/api/collections/:collection/rotate/estimate', ['collections', 'vfs'], async (ctx) => {
+    const collectionId = scopedCollection(ctx);
+    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);
+    return estimateRotationCost(
+      { driver: record.store?.driver, endpoint: record.store?.endpoint || record.store?.s3?.endpoint },
+      { objects: stats?.items ?? 0, bytes: stats?.bytes ?? 0 },
+    );
+  });
+
+  r.get('/api/collections/:collection/rotate', ['collections', 'rotation'], async (ctx) => {
+    const collectionId = scopedCollection(ctx);
+    await ctx.access.collection(collectionId, 'admin');
+    requireHumanAdmin(ctx, 'read key rotation state');
+    // Null rather than 404: "this collection has never been rotated" is an answer, and a
+    // client polling for progress should not have to treat it as an error.
+    return { rotation: (await ctx.rotation.state(collectionId)) || null };
+  });
+
+  r.post('/api/collections/:collection/rotate', ['collections', 'rotation'], async (ctx) => {
+    const collectionId = scopedCollection(ctx);
+    await ctx.access.collection(collectionId, 'admin');
+    requireHumanAdmin(ctx, 'rotate a key');
+    // Begin only mints the key and makes it current; the objects move in slices, from the
+    // cron or from further calls. Returning immediately is the point — the walk can take
+    // hours and holding the request open for it would just time out.
+    const state = await ctx.rotation.begin(collectionId, ctx.principal);
+    return { rotation: state };
+  });
+
+  r.delete('/api/collections/:collection/rotate', ['collections', 'rotation'], async (ctx) => {
+    const collectionId = scopedCollection(ctx);
+    await ctx.access.collection(collectionId, 'admin');
+    requireHumanAdmin(ctx, 'cancel a key rotation');
+    // Stops the walk. What has already moved stays moved, and both keys stay in the ring,
+    // so nothing becomes unreadable — an abandoned rotation is untidy, not destructive.
+    return { rotation: await ctx.rotation.cancel(collectionId) };
+  });
+
   // 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.
@@ -1150,6 +1210,7 @@ async function assertTaskAccess(ctx, task, what) {
  * 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`);