@3sln/trove 0.0.8 → 0.0.10

package/packages/core/src/uploads.js

@@ -14,8 +14,11 @@
 
 import { TroveError, ErrorCode } from './errors.js';
 import { newId, isValidItemName } from './util.js';
-import { cipherSize, DEFAULT_CHUNK_SIZE, isEnvelope, decodeHeader, HEADER_BYTES as ENVELOPE_HEAD } from './encryption/envelope.js';
-import { toHex } from './encryption/keys.js';
+import {
+  cipherSize, DEFAULT_CHUNK_SIZE, isEnvelope, decodeHeader, encodeHeader, encryptStream,
+  HEADER_BYTES as ENVELOPE_HEAD,
+} from './encryption/envelope.js';
+import { fromHex, toHex } from './encryption/keys.js';
 import { shouldEncrypt } from './encryption/policy.js';
 
 export const DEFAULT_PART_SIZE = 8 * 1024 * 1024; // 8 MiB
@@ -103,6 +106,40 @@ export class KvSessionStore {
   }
 }
 
+/**
+ * Whatever a caller handed us, as a stream.
+ *
+ * A part arrives as a stream over HTTP and as bytes from a test or an in-process caller;
+ * `encryptStream` takes only the former, and the sealing path has to accept both.
+ */
+function asStream(body) {
+  if (body && typeof body.getReader === 'function') return body;
+  if (body && typeof body.stream === 'function') return body.stream(); // Blob
+  const bytes = typeof body === 'string'
+    ? new TextEncoder().encode(body)
+    : (body instanceof Uint8Array ? body : new Uint8Array(body || 0));
+  return new ReadableStream({
+    start(c) {
+      if (bytes.length) c.enqueue(bytes);
+      c.close();
+    },
+  });
+}
+
+/** A stream that emits `head`, then everything `rest` produces. */
+function prependBytes(head, rest) {
+  const reader = rest.getReader();
+  return new ReadableStream({
+    start(c) { c.enqueue(head); },
+    async pull(c) {
+      const { value, done } = await reader.read();
+      if (done) c.close();
+      else c.enqueue(value);
+    },
+    cancel(reason) { return reader.cancel(reason); },
+  });
+}
+
 export class UploadManager {
   /**
    * @param {object} deps
@@ -204,6 +241,10 @@ export class UploadManager {
       storedSize,
       encrypted: encrypting,
       chunkSize: encrypting ? chunkSize : null,
+      // Fixed for the object, at negotiation, because parts are sealed INDEPENDENTLY and
+      // may arrive in any order — see `#sealPart`. Generating it per part would reuse
+      // nonces across the object, which AES-GCM does not survive.
+      noncePrefix: encrypting ? toHex(crypto.getRandomValues(new Uint8Array(8))) : null,
       keyFingerprint: encrypting ? policy.encryption.fingerprint : null,
       contentType,
       createdAt: Date.now(),
@@ -215,18 +256,35 @@ export class UploadManager {
 
     const limits = this.#limits();
 
+    // Presigned strategies hand the client a URL to the bucket, which is only safe when
+    // the client has something the bucket may hold. It seals nothing now, so for an
+    // encrypted collection a presigned PUT would put PLAINTEXT in the store — exactly what
+    // the encryption exists to prevent. Those go through us, and we seal on the way past.
+    const canPresign = caps.presignUpload && !encrypting;
+
     // Small file + presign → single PUT straight to storage (never through us).
-    if (storedSize <= SINGLE_PUT_LIMIT && caps.presignUpload) {
+    if (storedSize <= SINGLE_PUT_LIMIT && canPresign) {
       session.strategy = 'single';
       await this.sessions.put(session);
       const url = await storage.presignPut(storageKey, { contentType });
-      return { ...planSummary(session), strategy: 'single', multipart: false, presigned: true, url, limits, encryption: this.#planEncryption(session, policy) };
+      return { ...planSummary(session), strategy: 'single', multipart: false, presigned: true, url, limits, encryption: this.#planEncryption(session) };
     }
 
     // Multipart (presigned parts straight to storage, or streamed through us).
     if (caps.multipart) {
-      session.strategy = caps.presignUpload ? 'presign' : 'direct';
-      const partCount = Math.max(1, Math.ceil(storedSize / this.partSize));
+      session.strategy = canPresign ? 'presign' : 'direct';
+      // Measured in PLAINTEXT for an encrypted upload: the client sends us the file as it
+      // is, and the envelope it becomes is bigger by a tag per chunk. Sizing parts against
+      // the stored size would ask the client for bytes it does not have.
+      const wireSize = encrypting ? req.size : storedSize;
+      const partCount = Math.max(1, Math.ceil(wireSize / this.partSize));
+      // A part must hold a whole number of chunks, or the chunk a part boundary lands
+      // inside would be sealed twice under two different indices.
+      if (encrypting && this.partSize % chunkSize !== 0) {
+        throw TroveError.internal(
+          `Part size ${this.partSize} is not a multiple of the ${chunkSize}-byte chunk size`,
+        );
+      }
       // `#limits()` advertises maxParts in the very same response, and nothing enforced
       // it: a 150 GiB file planned 19,200 parts against a ceiling of 10,000, which S3
       // rejects at part 10,001 — after the client has transferred 80 GiB. On a presign
@@ -249,38 +307,31 @@ export class UploadManager {
           parts.push({ partNumber: n, url: await storage.presignPart(storageKey, session.uploadId, n) });
         }
       }
-      return { ...planSummary(session), strategy: session.strategy, multipart: true, presigned: session.strategy === 'presign', partCount, parts, limits, encryption: this.#planEncryption(session, policy) };
+      return { ...planSummary(session), strategy: session.strategy, multipart: true, presigned: session.strategy === 'presign', partCount, parts, limits, encryption: this.#planEncryption(session) };
     }
 
     // Fallback: whole-object PUT streamed through us (tiny/simple backends).
     session.strategy = 'direct-single';
     await this.sessions.put(session);
-    return { ...planSummary(session), strategy: 'direct-single', multipart: false, presigned: false, limits, encryption: this.#planEncryption(session, policy) };
+    return { ...planSummary(session), strategy: 'direct-single', multipart: false, presigned: false, limits, encryption: this.#planEncryption(session) };
   }
 
   /**
-   * What the client needs in order to encrypt before the bytes leave the browser.
+   * What a client is told about encryption: that it is happening, and nothing else.
    *
-   * The key travels, the bytes do not. That is what keeps a presigned direct-to-bucket
-   * upload possible while the bucket only ever sees ciphertext: the client seals the file
-   * locally and PUTs the envelope. Sending the key here is the explicit trade of this
-   * design — it defends the storage host, not the server, and the server had the key
-   * already in order to be able to index.
+   * This used to hand over the collection's data key so the browser could seal before the
+   * bytes left it — which is what made a presigned direct-to-bucket PUT possible while the
+   * bucket only ever held ciphertext. That trade is off. Encrypted collections now pass
+   * through the drive in BOTH directions, so the key never leaves the server and a client
+   * has nothing it could leak.
    *
-   * Null for anything not being encrypted, so a client has one thing to check.
+   * The cost is deliberate and worth naming: bytes for an encrypted collection are paid
+   * for twice, once to us and once to the store, and a presigned upload is unavailable for
+   * them. Unencrypted collections are untouched and still go straight to the bucket.
    */
-  #planEncryption(session, policy) {
+  #planEncryption(session) {
     if (!session.encrypted) return null;
-    return {
-      algorithm: 'AES-256-GCM',
-      chunkSize: session.chunkSize,
-      fingerprint: policy.encryption.fingerprint,
-      // Hex rather than raw bytes: this rides in a JSON plan.
-      key: policy.dataKeyHex,
-      // What the client should end up PUTting, so it can check its own work before
-      // spending the bytes.
-      storedSize: session.storedSize,
-    };
+    return { algorithm: 'AES-256-GCM', sealedBy: 'server' };
   }
 
 
@@ -351,7 +402,8 @@ export class UploadManager {
       // deliberately doesn't apply — so this is the only place a client can be stopped
       // from writing an unbounded object through us.
       const capped = capStream(body, this.maxBytes);
-      const info = await storage.put(s.storageKey, capped, { contentType: s.contentType, ...opts });
+      const toStore = s.encrypted ? await this.#sealPart(s, 1, capped, true) : capped;
+      const info = await storage.put(s.storageKey, toStore, { contentType: s.contentType, ...opts });
       s.parts[1] = { etag: info.etag || 'single' };
       await this.sessions.put(s);
       return { partNumber: 1, etag: s.parts[1].etag };
@@ -366,13 +418,62 @@ export class UploadManager {
     if (!Number.isInteger(partNumber) || partNumber < 1 || (s.partCount && partNumber > s.partCount)) {
       throw TroveError.invalid(`Part ${partNumber} is outside this upload's ${s.partCount} part(s)`);
     }
-    // A part is exactly `partSize` bytes, except the last, which is smaller.
-    const res = await storage.putPart(s.storageKey, s.uploadId, partNumber, capStream(body, s.partSize), opts);
+    // A part is exactly `partSize` bytes, except the last, which is smaller. Capped on the
+    // way IN — that is the plaintext the client sends; what we write is bigger by a tag per
+    // chunk.
+    const capped = capStream(body, s.partSize);
+    const toStore = s.encrypted
+      ? await this.#sealPart(s, partNumber, capped, partNumber === (s.partCount ?? 1))
+      : capped;
+    const res = await storage.putPart(s.storageKey, s.uploadId, partNumber, toStore, opts);
     s.parts[partNumber] = { etag: res.etag };
     await this.sessions.put(s);
     return res;
   }
 
+  /**
+   * Seal one part on its way to the store.
+   *
+   * Parts are sealed INDEPENDENTLY, which is what lets a client keep sending them
+   * concurrently now that it no longer seals them itself. That is safe only because a
+   * part's position in the envelope is a function of its NUMBER: part n carries plaintext
+   * bytes [(n-1)·partSize, n·partSize), so it begins at chunk (n-1)·partSize/chunkSize, and
+   * the nonce prefix was fixed for the whole object at negotiation. Nothing depends on the
+   * order parts arrive in, and no two chunks can ever be sealed under the same nonce.
+   *
+   * The header goes on the front of part 1 and nowhere else — it is the first 44 bytes of
+   * the object. Every part but the last is `partial`, which is what makes `encryptStream`
+   * refuse to finish an envelope early and insist on stopping at a chunk boundary.
+   */
+  async #sealPart(s, partNumber, body, isLast) {
+    const chunksPerPart = s.partSize / s.chunkSize;
+    const startChunk = (partNumber - 1) * chunksPerPart;
+    const key = await this.#dataKeyFor(s);
+    const sealed = await encryptStream(key, asStream(body), {
+      fingerprint: fromHex(s.keyFingerprint),
+      plaintextSize: s.size,
+      chunkSize: s.chunkSize,
+      resume: { noncePrefix: fromHex(s.noncePrefix), index: startChunk },
+      partial: !isLast,
+    });
+    if (partNumber !== 1) return sealed;
+    const header = encodeHeader({
+      chunkSize: s.chunkSize,
+      plaintextSize: s.size,
+      noncePrefix: fromHex(s.noncePrefix),
+      fingerprint: fromHex(s.keyFingerprint),
+    });
+    return prependBytes(header, sealed);
+  }
+
+  /** The collection's key, for sealing. Never leaves this process. */
+  async #dataKeyFor(s) {
+    const policy = await this.encryptionFor(s.collectionId);
+    const key = policy?.dataKeyHex ? fromHex(policy.dataKeyHex) : null;
+    if (!key) throw TroveError.internal('This collection is encrypted but its key is unavailable');
+    return key;
+  }
+
   /** Which parts are still outstanding (resume support). */
   async status(uploadId) {
     const s = await this.#session(uploadId);

package/packages/core/src/vfs.js

@@ -12,8 +12,12 @@
 
 import { TroveError, isOutOfSpace } from './errors.js';
 import { UploadManager } from './uploads.js';
-import { toHex } from './encryption/keys.js';
-import { decryptStream, decodeHeader, cipherRangeFor, cipherSize, HEADER_BYTES } from './encryption/envelope.js';
+import { fromHex, toHex } from './encryption/keys.js';
+import {
+  encrypt, decryptStream, decodeHeader, cipherRangeFor, cipherSize, HEADER_BYTES,
+  DEFAULT_CHUNK_SIZE,
+} from './encryption/envelope.js';
+import { shouldEncrypt } from './encryption/policy.js';
 import { IndexerRegistry } from './indexers/registry.js';
 import { ParsingSearchTransformer, matchTagFilters } from './search/transformer.js';
 import { extname } from './util.js';
@@ -56,6 +60,24 @@ async function bytesOf(stream) {
   return out;
 }
 
+/**
+ * Whatever `writeFile` was handed, as bytes.
+ *
+ * Sealing needs the plaintext size before it can write the envelope header, and this path
+ * is the convenience write for things already resident, so buffering costs nothing that was
+ * not already paid.
+ */
+async function bytesOfBody(body) {
+  if (body == null) return new Uint8Array(0);
+  if (typeof body === 'string') return new TextEncoder().encode(body);
+  if (body instanceof Uint8Array) return body;
+  if (ArrayBuffer.isView(body)) return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+  if (body instanceof ArrayBuffer) return new Uint8Array(body);
+  if (typeof body.arrayBuffer === 'function') return new Uint8Array(await body.arrayBuffer());
+  if (typeof body.getReader === 'function') return bytesOf(body);
+  return new Uint8Array(body);
+}
+
 /**
  * Emit only the bytes between `start` and `end` of a stream.
  *
@@ -132,6 +154,32 @@ export class Vfs {
     if (this.collections) await this.collections.init();
   }
 
+  /**
+   * What this collection wants sealed, and the key for it — or null.
+   *
+   * The same question `UploadManager` asks through its injected `encryptionFor`, including
+   * `shouldEncrypt`, so a collection with per-item rules answers identically whichever way
+   * the bytes arrive.
+   */
+  async #sealingFor(collectionId, name, contentType) {
+    if (!this.collections?.encryptionFor) return null;
+    // A collection record that is not there cannot ask for anything. `writeFile` defaults
+    // to 'default', which on a zero-config drive is a storage backend rather than a
+    // collection anyone created, and asking about it throws rather than answering "no".
+    let encryption;
+    try {
+      encryption = await this.collections.encryptionFor(collectionId);
+    } catch (err) {
+      if (err?.code === 'not_found') return null;
+      throw err;
+    }
+    if (!encryption?.enabled) return null;
+    if (!shouldEncrypt(encryption, { name, contentType })) return null;
+    const key = await this.collections.dataKeyFor(collectionId);
+    if (!key) throw TroveError.internal('This collection is encrypted but its key is unavailable');
+    return { key, fingerprint: fromHex(encryption.fingerprint), chunkSize: encryption.chunkSize || DEFAULT_CHUNK_SIZE };
+  }
+
   /** Resolve the storage backend for a collection. */
   async storageFor(collectionId = 'default') {
     if (this.collections) return this.collections.storageFor(collectionId);
@@ -256,9 +304,31 @@ export class Vfs {
     const storageKey = `obj_${cryptoId()}`;
     const ct = contentType || this.guessContentType(name);
     const storage = await this.storageFor(collectionId);
+    // Sealed here too, if the collection says so.
+    //
+    // This path wrote straight to the bucket and recorded the item with no `encryption`,
+    // never asking — so a server-side write put a READABLE file in a collection someone had
+    // set up to be encrypted, and stamped it as unencrypted so the read path served it back
+    // happily and nothing ever said otherwise. Once the drive started sealing uploads, this
+    // was the only remaining way to get plaintext into an encrypted bucket.
+    const sealing = await this.#sealingFor(collectionId, name, ct);
+    let toStore = body;
+    let encryption = null;
+    let plaintextSize = null;
+    if (sealing) {
+      // Buffered, unlike the upload path, which streams. This is the convenience write for
+      // things already resident — a sidecar, a test fixture, an in-process import — and the
+      // envelope needs the plaintext size before it can write its header.
+      const plain = await bytesOfBody(body);
+      plaintextSize = plain.length;
+      toStore = await encrypt(sealing.key, plain, {
+        fingerprint: sealing.fingerprint, chunkSize: sealing.chunkSize,
+      });
+      encryption = { fingerprint: toHex(sealing.fingerprint), chunkSize: sealing.chunkSize };
+    }
     let info;
     try {
-      info = await storage.put(storageKey, body, { contentType: ct, signal });
+      info = await storage.put(storageKey, toStore, { contentType: ct, signal });
     } catch (err) {
       // A write that failed for lack of room is a standing condition, not one bad
       // request: the next upload will fail the same way. Record it so it is visible
@@ -266,7 +336,11 @@ export class Vfs {
       if (isOutOfSpace(err)) await this.storageUsage(collectionId).catch(() => {});
       throw err;
     }
-    const node = await this.#upsertItem({ collectionId, name, storageKey, size: info.size, contentType: ct, etag: info.etag });
+    // The size the user sees is the FILE's, not the envelope's.
+    const node = await this.#upsertItem({
+      collectionId, name, storageKey, size: plaintextSize ?? info.size, contentType: ct,
+      etag: info.etag, encryption,
+    });
     // Small server-side writes index synchronously (search is ready on return);
     // large client uploads (completeUpload) index in the background instead.
     await this.indexing.indexNode(node).catch((e) => console.error('index error', e));
@@ -502,7 +576,19 @@ export class Vfs {
     const node = await this.resolve(id);
     if (!node.storageKey) throw TroveError.notFound('File content');
     const storage = await this.storageFor(node.collectionId);
-    if (storage.capabilities.presignDownload) {
+    // An ENCRYPTED object is never presigned to the store — the same rule `getDownload`
+    // already follows, and the one place it was missing. A bucket URL serves CIPHERTEXT,
+    // and everything a minted URL exists for (an <img src>, a <video src>, cache.add(), a
+    // URL handed to an external service) fetches bytes with nowhere to run decryption. So
+    // every thumbnail and preview in an encrypted collection on a presigning store pointed
+    // at ciphertext and rendered nothing.
+    //
+    // Worse than proxying would have been: a bucket URL is a DIFFERENT ORIGIN, so the
+    // service worker never saw it either — the one place that could have decrypted was
+    // routed around. Sending these through our own address is what lets the worker read
+    // straight from the store and decrypt (platform/directRead.js), and lets the server
+    // decrypt for anything without a worker.
+    if (storage.capabilities.presignDownload && !node.encryption) {
       const seconds = clampAge(op, expiresIn);
       const url = await storage.presignGet(node.storageKey, {
         expiresIn: seconds, responseContentType: node.contentType,

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

@@ -33,6 +33,7 @@ import {
   cloudflareAccess,
   KeyValueStore, MemoryKV, SqliteKV,
   KvSessionStore,
+  RotationService,
   SqliteProvider, LocalSqliteProvider,
   SidecarService, NotificationCenter, WebPushService, WebPushChannel, NotificationChannel,
   ApiKeyService, CapabilityProvider, ApiKeyCapabilityProvider,
@@ -330,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']);

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,7 +5,7 @@
 import { Router, json, parseRange } from './router.js';
 import {
   TroveError, assertSafePluginSql, concatBytes, metadataUrl, publicOrigin,
-  shouldEncrypt,
+  shouldEncrypt, estimateRotationCost,
 } from '@3sln/trove/core';
 import { parseContribUri, CORE_DOMAIN } from '@3sln/trove/core/plugins/identity.js';
 
@@ -449,16 +449,16 @@ export function createRouter() {
     const b = await body(ctx.req);
     if (!b.name) throw TroveError.invalid('name is required');
     const collection = await ctx.access.collection(scopedCollection(ctx), 'write');
-    // An upload onto an encrypted collection is handed the collection's key, so the client
-    // can seal the bytes before they reach the bucket. That key decrypts EVERYTHING in the
-    // collection, which makes it a read capability however it arrives — and `write` does
-    // not imply `read` here (only `admin` expands). Without this, a write-only API key,
-    // which the key model explicitly supports, could ask for a plan for a one-byte file and
-    // receive the means to decrypt the whole collection.
+    // `write` is enough again, including on an encrypted collection.
     //
-    // Refused rather than quietly narrowed to a plaintext upload: silently storing in the
-    // clear on a collection someone set up to be encrypted is the worse failure.
-    await assertReadIfKeyed(ctx, b);
+    // 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,
@@ -684,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.
@@ -1162,22 +1211,6 @@ async function assertTaskAccess(ctx, task, what) {
  * outlive its own revocation. Then the ordinary admin check on the principal.
  */
 
-/**
- * An upload plan that will carry the collection key needs `read`, not merely `write`.
- *
- * Checked before the session is created, so a refusal costs nothing and leaves no orphan.
- */
-async function assertReadIfKeyed(ctx, body) {
-  if (!ctx.collections?.encryptionFor) return;
-  const collectionId = scopedCollection(ctx);
-  const encryption = await ctx.collections.encryptionFor(collectionId);
-  if (!encryption?.enabled) return;
-  const contentType = body.contentType || ctx.vfs?.guessContentType?.(body.name) || '';
-  if (!shouldEncrypt(encryption, { name: body.name, contentType })) return;
-  // Throws if the caller does not hold read on this collection.
-  await ctx.access.collection(collectionId, 'read');
-}
-
 function requireHumanAdmin(ctx, action) {
   if (ctx.grant) {
     throw TroveError.forbidden(`An API key cannot ${action} — sign in as an administrator`);