@3sln/trove 0.0.7 → 0.0.9

package/packages/core/src/uploads.js

@@ -14,6 +14,12 @@
 
 import { TroveError, ErrorCode } from './errors.js';
 import { newId, isValidItemName } from './util.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
 const MIN_MULTIPART_PART = 5 * 1024 * 1024; // S3 floor (except final part)
@@ -48,6 +54,92 @@ class MemorySessionStore {
   }
 }
 
+/** The namespace upload sessions live under. */
+const SESSION_NS = 'uploads';
+
+/**
+ * Upload sessions in the KeyValueStore, so they outlive the process that made one.
+ *
+ * An upload is three or more separate requests — create, the bytes, complete — and the
+ * session is the only thing joining them. Held in a `Map`, that works exactly as long as
+ * every request happens to reach the same process: an assumption a long-lived server gets
+ * away with and a serverless one does not. On Cloudflare Workers an isolate can be
+ * discarded the moment a response resolves, and a cold drive fans a burst of requests
+ * across several isolates at once, so `create` writes to one Map and `complete` reads an
+ * empty one. The user is told their upload session does not exist while its own 24h TTL
+ * is nowhere near up — because it never expired, it was simply somewhere else.
+ *
+ * Retrying does not rescue that and must not: a missing session is `notFound`, correctly
+ * classified non-retryable, and one that genuinely expired is never coming back. The fix
+ * is for the session to live somewhere every request can see.
+ *
+ * Values are plain JSON, which is all a session ever was.
+ */
+export class KvSessionStore {
+  /** @param {{kv: import('./kv.js').KeyValueStore, ns?: string}} deps */
+  constructor({ kv, ns = SESSION_NS } = {}) {
+    if (!kv) throw TroveError.invalid('KvSessionStore needs a KeyValueStore');
+    this.kv = kv;
+    this.ns = ns;
+  }
+  async get(id) {
+    return (await this.kv.get(this.ns, id)) || null;
+  }
+  async put(session) {
+    await this.kv.set(this.ns, session.id, session);
+  }
+  async delete(id) {
+    await this.kv.delete(this.ns, id);
+  }
+  /**
+   * Which sessions have expired — WITHOUT deleting them, for the reason given on
+   * MemorySessionStore.expired: the session holds the multipart `uploadId`, and dropping
+   * the record strands the uploaded parts in the bucket with nothing left to abort them.
+   */
+  async expired(now) {
+    const rows = await this.kv.list(this.ns, '');
+    return rows
+      .map((r) => r.value)
+      .filter(Boolean)
+      .filter((s) => now - s.createdAt > SESSION_TTL_MS)
+      .map((s) => s.id);
+  }
+}
+
+/**
+ * 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
@@ -55,10 +147,14 @@ export class UploadManager {
    * @param {object} [deps.sessions] session store (defaults in-memory)
    * @param {number} [deps.partSize]
    */
-  constructor({ storage, storageFor, sessions, partSize = DEFAULT_PART_SIZE, maxBytes = null }) {
+  constructor({ storage, storageFor, sessions, encryptionFor, partSize = DEFAULT_PART_SIZE, maxBytes = null }) {
     // Either a single backend, or a resolver keyed by collectionId (collections).
     this.storageFor = storageFor ?? (async () => storage);
     this.sessions = sessions ?? new MemorySessionStore();
+    // What a collection encrypts, and the key to do it with:
+    // `(collectionId) => { encryption, dataKey } | null`. Absent means nothing is
+    // encrypted, which is what every existing deployment is.
+    this.encryptionFor = encryptionFor ?? (async () => null);
     this.partSize = partSize;
     this.maxBytes = maxBytes || null; // per-file quota (null = unbounded)
   }
@@ -85,19 +181,50 @@ export class UploadManager {
   async create(req) {
     if (!isValidItemName(req.name)) throw TroveError.invalid(`Invalid file name "${req.name}"`);
     if (!(req.size >= 0)) throw TroveError.invalid('size must be a non-negative number');
-    if (this.maxBytes && req.size > this.maxBytes) {
+    const collectionId = req.collectionId || 'default';
+    const storage = await this.#storage(collectionId);
+    const caps = storage.capabilities;
+    const storageKey = newId('obj');
+    const contentType = req.contentType || 'application/octet-stream';
+
+    // Does this item get encrypted, and with what?
+    //
+    // Decided here, once, and recorded on the session — not re-derived at `complete`,
+    // because the collection's rules can change between the two and an object half-planned
+    // as one thing and finished as another is unreadable either way.
+    //
+    // Everything downstream negotiates against the STORED size, which is larger: a header
+    // plus an authentication tag per chunk. Planning multipart boundaries against the
+    // plaintext size is short by exactly that, which is the difference between a final part
+    // that exists and one that does not.
+    const policy = await this.encryptionFor(collectionId);
+    const encrypting = !!policy && shouldEncrypt(policy.encryption, { name: req.name, contentType });
+    const chunkSize = policy?.encryption?.chunkSize || DEFAULT_CHUNK_SIZE;
+    const storedSize = encrypting ? cipherSize(req.size, chunkSize) : req.size;
+
+    // The per-file limit is checked against what will be STORED, and checked here rather
+    // than against `req.size` at the top of this method.
+    //
+    // `complete` compares the size read back from the store, which for an encrypted upload
+    // is the envelope. Checking the plaintext size at negotiation and the envelope size at
+    // completion meant a file just under the limit was accepted, transferred in full, and
+    // then DELETED by the too-large branch at the end — the user paying for the whole
+    // upload and losing the file. Both ends now measure the same thing.
+    if (this.maxBytes && storedSize > this.maxBytes) {
       // Deterministic per-file limit — retrying can't help, so it's non-retryable
       // (capacity/rate quotas stay retryable via the default).
       // TOO_LARGE (413), not QUOTA: the store has plenty of room, this file is simply
       // bigger than this deployment permits. Reporting it as a capacity problem would
       // send the user looking for space to free that would not help.
-      throw TroveError.tooLarge(`File exceeds the maximum upload size of ${this.maxBytes} bytes`, { details: { maxBytes: this.maxBytes, size: req.size } });
+      throw TroveError.tooLarge(
+        encrypting && req.size <= this.maxBytes
+          // Naming the reason, because "your 10MB file exceeds the 10MB limit" is a
+          // maddening thing to be told.
+          ? `Encrypted, this file needs ${storedSize} bytes of storage, over the ${this.maxBytes}-byte limit`
+          : `File exceeds the maximum upload size of ${this.maxBytes} bytes`,
+        { details: { maxBytes: this.maxBytes, size: req.size, storedSize } },
+      );
     }
-    const collectionId = req.collectionId || 'default';
-    const storage = await this.#storage(collectionId);
-    const caps = storage.capabilities;
-    const storageKey = newId('obj');
-    const contentType = req.contentType || 'application/octet-stream';
 
     const session = {
       id: newId('up'),
@@ -108,7 +235,17 @@ export class UploadManager {
       // the session because the decision is made when the upload STARTS but has to be
       // honoured when it COMPLETES, possibly much later.
       overwrite: !!req.overwrite,
+      // The size the USER sees, which is what the item is recorded as. `storedSize` is
+      // what actually occupies the bucket.
       size: req.size,
+      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(),
       strategy: null,
@@ -119,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 (req.size <= 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 };
+      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(req.size / 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
@@ -139,7 +293,7 @@ export class UploadManager {
       if (partCount > MAX_PARTS) {
         throw TroveError.tooLarge(
           `This file needs ${partCount.toLocaleString()} parts of ${this.partSize} bytes, over the ${MAX_PARTS.toLocaleString()}-part limit`,
-          { details: { maxParts: MAX_PARTS, partCount, partSize: this.partSize, size: req.size } },
+          { details: { maxParts: MAX_PARTS, partCount, partSize: this.partSize, size: storedSize } },
         );
       }
       // Only now open the multipart. Refusing AFTER creating it left an upload open in
@@ -153,13 +307,67 @@ 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 };
+      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 };
+    return { ...planSummary(session), strategy: 'direct-single', multipart: false, presigned: false, limits, encryption: this.#planEncryption(session) };
+  }
+
+  /**
+   * What a client is told about encryption: that it is happening, and nothing else.
+   *
+   * 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.
+   *
+   * 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) {
+    if (!session.encrypted) return null;
+    return { algorithm: 'AES-256-GCM', sealedBy: 'server' };
+  }
+
+
+  /**
+   * Refuse an upload that was supposed to be encrypted and is not.
+   *
+   * Deleted rather than kept, like the over-size branch: an object that cannot be read is
+   * not worth the storage, and leaving it would also leave plaintext in a bucket the
+   * collection promises is ciphertext.
+   */
+  async #assertSealed(storage, s) {
+    let head;
+    try {
+      const got = await storage.get(s.storageKey, { range: { start: 0, end: ENVELOPE_HEAD - 1 } });
+      head = new Uint8Array(await new Response(got.stream).arrayBuffer());
+    } catch {
+      return; // a backend that cannot serve a range gets the benefit of the doubt
+    }
+    const sealed = isEnvelope(head);
+    const matches = sealed && (() => {
+      try {
+        return toHex(decodeHeader(head).fingerprint) === s.keyFingerprint;
+      } catch {
+        return false;
+      }
+    })();
+    if (sealed && matches) return;
+
+    await storage.delete(s.storageKey).catch(() => {});
+    await this.sessions.delete(s.id);
+    throw TroveError.invalid(
+      sealed
+        ? 'This upload was encrypted with the wrong key for this collection.'
+        : 'This collection encrypts its files, and this upload arrived unencrypted. The client '
+          + 'must seal the bytes using the key in the upload plan before sending them.',
+    );
   }
 
   /** Re-issue a signed URL for one part (resume after expiry). */
@@ -194,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 };
@@ -209,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);
@@ -292,15 +550,40 @@ export class UploadManager {
         { details: { maxBytes: this.maxBytes, size } },
       );
     }
+    // An upload planned as encrypted must have ARRIVED encrypted.
+    //
+    // `complete` otherwise records what the session INTENDED, so a client that ignores
+    // `plan.encryption` — which is every client that has not implemented it yet — uploads
+    // plaintext and the item is stamped with a key fingerprint anyway. The result is the
+    // worst of both: permanently unreadable, because the read path looks for an envelope
+    // that is not there, and not actually protected, because the bytes are sitting in the
+    // bucket in the clear on a collection labelled encrypted.
+    //
+    // The envelope header is readable without the key, which is exactly what makes this
+    // checkable here. One small ranged read, once, at the end of an upload.
+    if (s.encrypted) {
+      await this.#assertSealed(storage, s);
+    }
+
     await this.sessions.delete(uploadId);
     return {
       storageKey: s.storageKey,
-      size,
+      // For an encrypted object the store holds an envelope, which is larger than the
+      // file. The item records the file: that is the number a user recognises, the one
+      // search results and quotas are about, and the one a range request is against.
+      size: s.encrypted ? s.size : size,
+      storedSize: size,
       contentType: s.contentType,
       etag,
       collectionId: s.collectionId,
       name: s.name,
       overwrite: !!s.overwrite,
+      // Which key opens this object. Recorded on the item so reading it does not have to
+      // fetch the envelope header first, and so a rotation can find what it has not yet
+      // converted without opening every object in the bucket.
+      encryption: s.encrypted
+        ? { fingerprint: s.keyFingerprint, chunkSize: s.chunkSize }
+        : null,
     };
   }
 

package/packages/core/src/vfs.js

@@ -12,6 +12,8 @@
 
 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 { IndexerRegistry } from './indexers/registry.js';
 import { ParsingSearchTransformer, matchTagFilters } from './search/transformer.js';
 import { extname } from './util.js';
@@ -36,8 +38,46 @@ const CONTENT_TYPES = {
   '.mp4': 'video/mp4', '.webm': 'video/webm', '.zip': 'application/zip',
 };
 
+
+/** Drain a stream into one buffer. Only ever used for the fixed-size envelope header. */
+async function bytesOf(stream) {
+  const reader = stream.getReader();
+  const parts = [];
+  let total = 0;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    parts.push(value);
+    total += value.length;
+  }
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+
+/**
+ * Emit only the bytes between `start` and `end` of a stream.
+ *
+ * A plaintext range rarely lines up with a chunk boundary, so decryption yields whole
+ * chunks and this drops the overhang at each end — without collecting the middle, which is
+ * the entire point of streaming in the first place.
+ */
+function trimStream(stream, start, end) {
+  let seen = 0;
+  return stream.pipeThrough(new TransformStream({
+    transform(chunk, controller) {
+      const from = Math.max(0, start - seen);
+      const to = Math.min(chunk.length, end - seen);
+      if (to > from) controller.enqueue(chunk.subarray(from, to));
+      seen += chunk.length;
+      if (seen >= end) controller.terminate();
+    },
+  }));
+}
+
 export class Vfs {
-  constructor({ storage, metadata, search, indexers, sidecar, collections, searchTransformer, issues, signedUrls = null, publicUrl = '', maxIndexBytes = 2 * 1024 * 1024, maxUploadBytes = null, uploadPartSize = undefined }) {
+  constructor({ storage, metadata, search, indexers, sidecar, collections, searchTransformer, issues, signedUrls = null, publicUrl = '', maxIndexBytes = 2 * 1024 * 1024, maxUploadBytes = null, uploadPartSize = undefined, uploadSessions = undefined }) {
     if (!storage && !collections) throw TroveError.invalid('Vfs requires a storage backend or a CollectionService');
     if (!metadata) throw TroveError.invalid('Vfs requires a metadata store');
     this.storage = storage; // primary backend (default collection + capability reporting)
@@ -49,7 +89,27 @@ export class Vfs {
     this.collections = collections ?? null;
     this.indexers = indexers ?? new IndexerRegistry();
     // One UploadManager; it resolves the right backend per session's collection.
-    this.uploads = new UploadManager({ storageFor: (cid) => this.storageFor(cid), maxBytes: maxUploadBytes, partSize: uploadPartSize });
+    //
+    // `uploadSessions` is where the sessions live. It defaults to memory, which is right
+    // for a test and wrong for anything where two requests of one upload can be served by
+    // different processes — see KvSessionStore. Injected rather than built here because
+    // core does not otherwise need a KeyValueStore.
+    this.uploads = new UploadManager({
+      storageFor: (cid) => this.storageFor(cid),
+      sessions: uploadSessions,
+      // What a collection encrypts and the key for it. Only the CollectionService knows,
+      // and only it is allowed to hand the key out — see collections/index.js.
+      encryptionFor: async (cid) => {
+        if (!this.collections?.encryptionFor) return null;
+        const encryption = await this.collections.encryptionFor(cid);
+        if (!encryption?.enabled) return null;
+        const key = await this.collections.dataKeyFor(cid);
+        if (!key) return null;
+        return { encryption, dataKeyHex: toHex(key) };
+      },
+      maxBytes: maxUploadBytes,
+      partSize: uploadPartSize,
+    });
     this.maxIndexBytes = maxIndexBytes;
     // The indexing subsystem (run/backfill/purge/contributions) lives here.
     // Where a failure to index becomes a standing, retryable problem rather than a
@@ -223,17 +283,20 @@ export class Vfs {
    * — and an unconditional replace at completion silently destroys whichever landed
    * first. So an upload re-resolves the collision at the moment it commits.
    */
-  async #upsertItem({ collectionId, name, storageKey, size, contentType, etag, overwrite = true }) {
+  async #upsertItem({ collectionId, name, storageKey, size, contentType, etag, overwrite = true, encryption = null }) {
     let finalName = name;
     const existing = await this.metadata.getByName(collectionId, name);
     if (existing && overwrite) {
       const oldKey = existing.storageKey;
-      const updated = await this.metadata.update(existing.id, { storageKey, size, contentType, etag });
+      const updated = await this.metadata.update(existing.id, { storageKey, size, contentType, etag, encryption });
       if (oldKey && oldKey !== storageKey) (await this.storageFor(collectionId)).delete(oldKey).catch(() => {});
       return updated;
     }
     if (existing) finalName = await this.#uniqueName(collectionId, name);
-    return this.metadata.create({ collectionId, name: finalName, storageKey, size, contentType, etag });
+    // `encryption` names which key opens this object. Carried on the item so a read does
+    // not have to fetch the envelope header to find out, and so a rotation can tell what it
+    // has not converted without opening every object in the bucket.
+    return this.metadata.create({ collectionId, name: finalName, storageKey, size, contentType, etag, encryption });
   }
 
   /**
@@ -399,15 +462,23 @@ export class Vfs {
 
   // --- download --------------------------------------------------------------
 
-  async getDownload(id, { expiresIn, download } = {}) {
+  async getDownload(id, { expiresIn, download, ciphertext = false } = {}) {
     const node = await this.resolve(id);
     const storage = await this.storageFor(node.collectionId);
+    // An encrypted object is not redirected to by default. A redirect hands the caller raw
+    // ciphertext, and most callers of a download URL cannot do anything with it — an <img
+    // src>, a <video src>, a signed URL given to an external service. Proxying is the
+    // answer that is always correct, so it is the default; a client that holds the key and
+    // knows it can decrypt asks for `ciphertext` and gets the direct path back.
+    if (node.encryption && !ciphertext) return { mode: 'proxy', node };
     if (storage.capabilities.presignDownload) {
       const url = await storage.presignGet(node.storageKey, {
         expiresIn, responseContentType: node.contentType,
         downloadName: download ? node.name : undefined,
       });
-      return { mode: 'redirect', url, node };
+      // Named on the way out so a client that asked for ciphertext knows which key opens
+      // what it is about to receive.
+      return { mode: 'redirect', url, node, encryption: node.encryption || null };
     }
     return { mode: 'proxy', node };
   }
@@ -431,7 +502,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,
@@ -457,7 +540,75 @@ export class Vfs {
   async readStream(id, { range, signal } = {}) {
     const node = await this.resolve(id);
     if (!node.storageKey) throw TroveError.notFound('File content');
-    return (await this.storageFor(node.collectionId)).get(node.storageKey, { range, signal });
+    const storage = await this.storageFor(node.collectionId);
+    if (!node.encryption) return storage.get(node.storageKey, { range, signal });
+
+    // An encrypted object is decrypted HERE, for everything that reads through the server.
+    //
+    // The browser can decrypt for itself when it fetches — and does, which is what keeps a
+    // presigned download direct. But an <img src>, a <video src>, a signed URL handed to an
+    // external service, and the service worker's own cache fills cannot: they are bare URLs
+    // that get bytes and have nowhere to run our code. Those all arrive here, so this is
+    // where correctness has to live.
+    //
+    // The plaintext range the caller asked for is mapped onto the chunks that hold it, so a
+    // seek into a video still fetches a chunk rather than the film.
+    // The ENVELOPE is read first, and it is authoritative.
+    //
+    // The item's own record says which key sealed it and at what chunk size, and that is
+    // what makes a listing cheap — but it is a copy, and a copy can be stale: an object
+    // restored from a backup, adopted by a scan, or written by another version. Deriving
+    // the byte ranges from the record and then decrypting with the object's real geometry
+    // is how you get chunk indices computed against one layout and nonces against another,
+    // which surfaces as "the data has been altered" on data nobody altered.
+    const head = await storage.get(node.storageKey, { range: { start: 0, end: HEADER_BYTES - 1 }, signal });
+    const header = decodeHeader(await bytesOf(head.stream));
+    // The plaintext size likewise: the envelope knows, the record remembers.
+    const plaintextSize = header.plaintextSize ?? node.size;
+    const key = await this.#keyForNode(node, header);
+
+    const want = range
+      ? cipherRangeFor({ start: range.start, end: range.end }, { ...header, plaintextSize })
+      : {
+        cipherStart: 0,
+        cipherEnd: cipherSize(plaintextSize, header.chunkSize) - 1,
+        firstChunk: 0,
+        trimStart: 0,
+        trimEnd: plaintextSize,
+      };
+
+    const body = await storage.get(node.storageKey, {
+      range: { start: Math.max(want.cipherStart, HEADER_BYTES), end: want.cipherEnd }, signal,
+    });
+    const plain = await decryptStream(key, header, body.stream, want.firstChunk);
+    return {
+      stream: trimStream(plain, want.trimStart, want.trimEnd),
+      size: want.trimEnd - want.trimStart,
+      contentType: node.contentType,
+      etag: head.etag,
+      range: range ? { start: range.start, end: range.start + (want.trimEnd - want.trimStart) - 1, total: plaintextSize } : null,
+    };
+  }
+
+  /**
+   * The key that opens this object, chosen by what the ENVELOPE names.
+   *
+   * The object is the authority on which key sealed it; the item's record is a copy kept
+   * for cheap listings. Trusting the record would mean a stale one sends us to the wrong
+   * key and the failure reads as corruption.
+   */
+  async #keyForNode(node, header) {
+    const want = toHex(header.fingerprint);
+    const key = this.collections?.dataKeyFor
+      ? await this.collections.dataKeyFor(node.collectionId, want)
+      : null;
+    if (!key) {
+      throw TroveError.invalid(
+        'This item is encrypted with a key this collection no longer holds. It was probably '
+        + 'retired before a key rotation finished moving everything onto the new one.',
+      );
+    }
+    return key;
   }
 
   // --- uploads ---------------------------------------------------------------
@@ -511,7 +662,7 @@ export class Vfs {
       const node = await this.#upsertItem({
         collectionId: obj.collectionId, name: obj.name, storageKey: obj.storageKey,
         size: obj.size, contentType: obj.contentType, etag: obj.etag,
-        overwrite: obj.overwrite,
+        overwrite: obj.overwrite, encryption: obj.encryption || null,
       });
       this.indexing.indexNode(node).catch((e) => console.error('index error', e));
       return node;