@3sln/trove 0.0.7 → 0.0.9

package/packages/core/src/encryption/rotation.js

@@ -0,0 +1,432 @@
+// Moving a collection's objects onto a new key, a slice at a time.
+//
+// Rotation is the one operation here that cannot be atomic. A collection can hold hundreds
+// of thousands of objects and every one has to be read, decrypted, re-encrypted and
+// written back — far more than fits in a request, a Worker invocation, or anyone's
+// patience. So it is a long job that runs in pieces, and the design follows from what
+// happens when a piece does not finish.
+//
+// TWO KEYS ARE LIVE THROUGHOUT. `beginRotation` mints the new key and makes it current
+// immediately, so everything uploaded from that moment is already correct and the job only
+// ever has to deal with a shrinking set. Everything not yet moved still opens with the old
+// key, because its envelope names it. Nothing is unreadable at any point, including
+// halfway through, including after a crash.
+//
+// THE CURSOR IS PERSISTED, NOT HELD. The process doing the work can vanish between slices
+// — an evicted isolate, a redeploy, a laptop closing. Progress lives in the KeyValueStore
+// with the rest of the drive's durable state, so the next slice picks up where the last
+// one stopped rather than starting again. Re-running a slice that already ran is harmless:
+// an object already on the current key is skipped, so the work is idempotent by
+// construction rather than by bookkeeping.
+//
+// IT FINISHES BY OBSERVATION. The old key is retired when a full pass finds nothing left
+// on it — not when a counter says the job is done. A count can be wrong; a pass that finds
+// nothing cannot be. That also handles the awkward case of an object uploaded onto the old
+// key by a request that was in flight when the rotation started.
+
+import { TroveError } from '../errors.js';
+import { encryptStream, decodeHeader } from './envelope.js';
+import { fromHex, fingerprint, toHex } from './keys.js';
+
+const NS = 'rotations';
+
+/** How long one slice may run before yielding, so a cron firing stays inside its budget. */
+const DEFAULT_BUDGET_MS = 15_000;
+
+/**
+ * How much sealed output to gather before sending a part.
+ *
+ * Above S3's 5 MiB floor for non-final parts, and small enough that peak memory during a
+ * rotation is a few megabytes rather than a function of the file.
+ */
+const PART_TARGET_BYTES = 8 * 1024 * 1024;
+
+/**
+ * @typedef {object} RotationState
+ * @property {string} collectionId
+ * @property {string} to        fingerprint of the key being moved onto
+ * @property {string[]} from    fingerprints being moved off
+ * @property {string|null} cursor  where the last slice stopped
+ * @property {number} moved
+ * @property {number} failed
+ * @property {number} startedAt
+ * @property {'running'|'done'} status
+ */
+
+/**
+ * The storage key a rotation writes to.
+ *
+ * Based on the key with any previous rotation suffix STRIPPED. Appending to
+ * `node.storageKey` instead compounds: a collection rotated twice held
+ * `obj_x.rotms9gq8j2.rotms9grnhf`, and a key grew by ~11 characters on every rotation for
+ * the life of the drive. S3 stops accepting a key at 1024 bytes, so a drive rotated on a
+ * schedule would eventually fail to rotate at all — years out, silently, and only for the
+ * objects with the longest names.
+ */
+export function rotatedKey(storageKey) {
+  return `${storageKey.replace(/(\.rot[0-9a-z]+)+$/, '')}.rot${Date.now().toString(36)}`;
+}
+
+export class RotationService {
+  /**
+   * @param {object} deps
+   * @param {import('../kv.js').KeyValueStore} deps.kv     where progress survives
+   * @param {import('../vfs.js').Vfs} deps.vfs
+   * @param {import('../collections/index.js').CollectionService} deps.collections
+   */
+  constructor({ kv, vfs, collections }) {
+    if (!kv || !vfs || !collections) throw TroveError.invalid('RotationService needs kv, vfs and collections');
+    this.kv = kv;
+    this.vfs = vfs;
+    this.collections = collections;
+  }
+
+  async state(collectionId) {
+    return this.kv.get(NS, collectionId);
+  }
+
+  /**
+   * Start moving a collection onto a fresh key.
+   *
+   * The new key becomes current here, before any object moves, so every upload from now on
+   * is already on it. Refuses to start a second rotation over an unfinished one — two
+   * walkers on one collection would fight over the cursor and neither would know what the
+   * other had done.
+   */
+  async begin(collectionId, principal) {
+    const running = await this.state(collectionId);
+    if (running && running.status === 'running') {
+      throw TroveError.invalid('A key rotation is already running on this collection');
+    }
+    // A finished-but-abandoned rotation can still be holding an open multipart. Starting a
+    // new one is the last moment anything knows it exists.
+    if (running?.inflight) await this.#discard(collectionId, running.inflight);
+    const { fingerprint: to, previous } = await this.collections.beginRotation(collectionId, principal);
+    const state = {
+      collectionId,
+      to,
+      // Everything currently live except the new key. Usually one, but a rotation started
+      // over an unfinished one would leave more, and dropping any of them would strand
+      // whatever is still sealed with it.
+      from: (await this.collections.keyRingFor(collectionId))
+        .map((k) => k.fingerprint)
+        .filter((fp) => fp !== to),
+      cursor: null,
+      // The object part-way through, when a slice ran out of budget inside one. See
+      // #moveSlice — this is what lets an object larger than a slice be rotated at all.
+      inflight: null,
+      moved: 0,
+      failed: 0,
+      startedAt: Date.now(),
+      status: 'running',
+      previous,
+    };
+    await this.kv.set(NS, collectionId, state);
+    return state;
+  }
+
+  /**
+   * Do a slice of the work.
+   *
+   * Bounded by time rather than by count, because objects vary from bytes to gigabytes and
+   * a count is not a budget. Returns the state, so a caller can loop until `done`.
+   */
+  async step(collectionId, { budgetMs = DEFAULT_BUDGET_MS, now = () => Date.now() } = {}) {
+    const state = await this.state(collectionId);
+    if (!state || state.status !== 'running') return state;
+
+    // One walker at a time, claimed the way a scan claims its collection.
+    //
+    // Two slices running together — a cron overlapping a manual run, or two cron firings on
+    // a slow collection — can both pick up the same object. Each writes a new object and
+    // points the item at it, and then each deletes the object IT replaced: the second
+    // delete removes the object the item is now pointing at. With the old key still in the
+    // ring nothing reports an error, and the file is simply gone.
+    //
+    // A lease rather than a flag, because the holder can die mid-slice and a lock that
+    // outlives its holder stops the rotation permanently with nobody left to notice.
+    const claim = await this.kv.acquire('rotation', collectionId, Math.max(30_000, budgetMs * 3));
+    if (!claim) return state;
+    try {
+      return await this.#slice(collectionId, state, { budgetMs, now });
+    } finally {
+      await this.kv.release('rotation', collectionId, claim).catch(() => {});
+    }
+  }
+
+  async #slice(collectionId, state, { budgetMs, now }) {
+
+    const deadline = now() + budgetMs;
+    const key = await this.collections.dataKeyFor(collectionId, state.to);
+    if (!key) throw TroveError.invalid('The key this rotation is moving onto is gone');
+    const fp = await fingerprint(key);
+
+    let cursor = state.cursor;
+    let moved = state.moved;
+    let failed = state.failed;
+    let sawStragglers = false;
+    let inflight = state.inflight || null;
+
+    // Finish what the last slice started before looking for more. An object part-way
+    // through is the one thing that MUST be dealt with first: its multipart is open and
+    // billed, and the walk would otherwise pick it up again from the beginning.
+    if (inflight) {
+      const node = await this.vfs.metadata.getById(inflight.nodeId).catch(() => null);
+      // Deleted, or already moved by something else, while we were away. Spend the upload
+      // rather than leaving it open forever.
+      if (!node || !node.encryption || node.encryption.fingerprint === state.to) {
+        await this.#discard(collectionId, inflight);
+        inflight = null;
+      } else {
+        sawStragglers = true;
+        try {
+          const r = await this.#moveSlice(node, key, fp, inflight, { deadline, now });
+          inflight = r.inflight;
+          if (r.done) moved++;
+        } catch (err) {
+          failed++;
+          await this.#discard(collectionId, inflight);
+          inflight = null;
+          console.error(`[trove] resuming ${node.name} failed:`, err?.message || err);
+        }
+        // Still not finished, or out of time: persist and let the next slice continue.
+        if (inflight || now() >= deadline) {
+          return this.#save(collectionId, { ...state, cursor, moved, failed, inflight });
+        }
+      }
+    }
+
+    for (;;) {
+      const page = await this.vfs.metadata.listItems(collectionId, { cursor, limit: 50 });
+      const items = page.items || [];
+      for (const node of items) {
+        // Only encrypted items, and only ones not already on the current key. This is what
+        // makes re-running a slice free rather than destructive.
+        if (!node.encryption || node.encryption.fingerprint === state.to) continue;
+        sawStragglers = true;
+        try {
+          const r = await this.#moveSlice(node, key, fp, null, { deadline, now });
+          if (r.done) moved++;
+          else {
+            // Bigger than the remaining budget. Its parts and its place in the envelope are
+            // recorded, and the next slice picks it up where this one stopped instead of
+            // starting the object again — which is what used to make a large object
+            // unrotatable at all rather than merely slow.
+            return this.#save(collectionId, { ...state, cursor, moved, failed, inflight: r.inflight });
+          }
+        } catch (err) {
+          // One unreadable object must not stop the rotation: the rest of the collection
+          // still needs to move, and the old key cannot be retired while anything is left
+          // on it — which is exactly the signal a failure should produce.
+          failed++;
+          console.error(`[trove] rotating ${node.name} failed:`, err?.message || err);
+        }
+        if (now() >= deadline) break;
+      }
+      cursor = page.nextCursor || null;
+      if (!cursor || now() >= deadline) break;
+    }
+
+    const finished = !cursor && !sawStragglers;
+    const next = {
+      ...state,
+      inflight: null,
+      // A finished pass starts the next one from the beginning, because items added during
+      // it may still be behind. Two clean passes in a row is what actually ends the job.
+      cursor: finished ? null : cursor,
+      moved,
+      failed,
+      status: finished && failed === 0 ? 'done' : 'running',
+      finishedAt: finished && failed === 0 ? now() : undefined,
+    };
+    await this.kv.set(NS, collectionId, next);
+
+    // Retire by observation: a pass that found nothing left on the old keys is proof, in a
+    // way that a counter never is.
+    if (next.status === 'done') {
+      for (const old of state.from) {
+        // System work: it is finishing what an admin authorized when they started the
+        // rotation, and there is no user behind a cron firing. A failure here is logged
+        // rather than swallowed — the rotation itself succeeded, but a key that should
+        // have been retired and was not is worth knowing about.
+        await this.collections.retireKey(collectionId, old, null, { system: true })
+          .catch((err) => console.error(`[trove] retiring key ${old} failed:`, err?.message || err));
+      }
+    }
+    return next;
+  }
+
+  /**
+   * Move one object onto the new key, in as many slices as it takes.
+   *
+   * A rotation slice is bounded by wall-clock time, and until now an object could only be
+   * moved whole: one larger than the budget failed its slice, restarted from the beginning
+   * on the next, and failed again — forever, with the rotation never completing and the old
+   * key never retiring. A collection containing one big video could not be rotated at all.
+   *
+   * The checkpoint is the multipart part list, which the store is already keeping for us.
+   * What has to travel with it is the ENVELOPE's position: a nonce is derived from the
+   * chunk index, so a resumed encryption must continue the same sequence under the same
+   * prefix. Starting a fresh envelope halfway would reuse nonce/key pairs from the first
+   * half — the one thing AES-GCM cannot survive — so the prefix and the next chunk index
+   * are persisted alongside the parts.
+   *
+   * @returns {Promise<{done: boolean, inflight: object|null}>}
+   */
+  async #moveSlice(node, newKey, newFingerprint, inflight, { deadline, now }) {
+    const storage = await this.vfs.storageFor(node.collectionId);
+    const chunkSize = node.encryption.chunkSize;
+    const plaintextSize = node.size;
+
+    // A store without multipart is a local one — filesystem, memory — where the whole
+    // object is already within reach. There is nothing to check point against, and nothing
+    // that needs it: the budget that makes this necessary is a network one.
+    if (!storage.capabilities?.multipart) {
+      await this.#moveWhole(node, newKey, newFingerprint, storage, chunkSize);
+      return { done: true, inflight: null };
+    }
+
+    // Written to a NEW storage key rather than over the old one. AES-GCM cannot survive a
+    // nonce being reused with a key, and rewriting in place invites exactly that on a
+    // retry; a new object also means a failure halfway leaves the original intact and
+    // readable rather than a half-written file that is neither.
+    const nextKey = inflight?.storageKey ?? rotatedKey(node.storageKey);
+    const uploadId = inflight?.uploadId ?? await storage.createMultipart(nextKey, { contentType: node.contentType });
+    const parts = inflight?.parts ? [...inflight.parts] : [];
+    let chunkIndex = inflight?.chunkIndex ?? 0;
+    let noncePrefix = inflight?.noncePrefix ? fromHex(inflight.noncePrefix) : null;
+
+    // One part per pass, so the checkpoint lands on a part boundary — which is also a chunk
+    // boundary, since a part is a whole number of sealed chunks. Sized to clear S3's 5 MiB
+    // floor for every part but the last.
+    const chunksPerPart = Math.max(1, Math.ceil(PART_TARGET_BYTES / chunkSize));
+
+    try {
+      while (chunkIndex * chunkSize < plaintextSize) {
+        const start = chunkIndex * chunkSize;
+        const end = Math.min(start + chunksPerPart * chunkSize, plaintextSize) - 1;
+        const last = end + 1 >= plaintextSize;
+
+        const read = await this.vfs.readStream(node.id, { range: { start, end } });
+        const sealed = await encryptStream(newKey, read.stream, {
+          fingerprint: newFingerprint,
+          plaintextSize,
+          chunkSize,
+          // The first pass mints the prefix and writes the header; every later one continues
+          // the same envelope, which is what `resume` means.
+          resume: noncePrefix ? { noncePrefix, index: chunkIndex } : null,
+          // `partial` says another call will continue this object. Without it a mid-object
+          // pass would be sealed as a complete envelope and every later chunk index would be
+          // wrong.
+          partial: !last,
+        });
+
+        const body = new Uint8Array(await new Response(sealed).arrayBuffer());
+        // The prefix the first pass generated, read back out of the header it wrote. It is
+        // the only place it exists, and every later pass needs it.
+        if (!noncePrefix) noncePrefix = decodeHeader(body).noncePrefix;
+
+        const partNumber = parts.length + 1;
+        const etag = await storage.putPart(nextKey, uploadId, partNumber, body);
+        parts.push({ partNumber, etag: etag?.etag ?? etag });
+        chunkIndex += Math.ceil((end + 1 - start) / chunkSize);
+
+        // Out of time, but on a boundary: hand back what has been done so the next slice
+        // continues rather than starting over.
+        if (!last && now() >= deadline) {
+          return {
+            done: false,
+            inflight: {
+              nodeId: node.id,
+              storageKey: nextKey,
+              uploadId,
+              parts,
+              chunkIndex,
+              noncePrefix: toHex(noncePrefix),
+            },
+          };
+        }
+      }
+
+      await storage.completeMultipart(nextKey, uploadId, parts);
+    } catch (err) {
+      // The parts already sent stay in the bucket, billed, with nothing left able to
+      // reclaim them — so a failure aborts rather than leaving them.
+      await storage.abortMultipart(nextKey, uploadId).catch(() => {});
+      throw err;
+    }
+
+    // The item points at the new object before the old one is removed. In the window
+    // between, both exist and the item is readable; in the reverse order there is a window
+    // where it is readable through neither.
+    const oldKey = node.storageKey;
+    await this.vfs.metadata.update(node.id, {
+      storageKey: nextKey,
+      encryption: { fingerprint: toHex(newFingerprint), chunkSize },
+    });
+    await storage.delete(oldKey).catch(() => {});
+    return { done: true, inflight: null };
+  }
+
+  /** The whole object in one put, for a store that cannot do multipart. */
+  async #moveWhole(node, newKey, newFingerprint, storage, chunkSize) {
+    const nextKey = rotatedKey(node.storageKey);
+    const read = await this.vfs.readStream(node.id);
+    const sealed = await encryptStream(newKey, read.stream, {
+      fingerprint: newFingerprint,
+      plaintextSize: read.size ?? node.size,
+      chunkSize,
+    });
+    await storage.put(nextKey, new Uint8Array(await new Response(sealed).arrayBuffer()), {
+      contentType: node.contentType,
+    });
+    const oldKey = node.storageKey;
+    await this.vfs.metadata.update(node.id, {
+      storageKey: nextKey,
+      encryption: { fingerprint: toHex(newFingerprint), chunkSize },
+    });
+    await storage.delete(oldKey).catch(() => {});
+  }
+
+  /**
+   * Abandon a half-written object.
+   *
+   * A multipart left open is billed until it is completed or aborted, and nothing else can
+   * find it: the storage contract has no way to list them, deliberately, so the only record
+   * that it exists is the one we wrote. Cancelling or restarting a rotation has to spend it.
+   */
+  async #discard(collectionId, inflight) {
+    if (!inflight?.uploadId) return;
+    try {
+      const storage = await this.vfs.storageFor(collectionId);
+      await storage.abortMultipart(inflight.storageKey, inflight.uploadId);
+    } catch (err) {
+      console.error(`[trove] abandoning a rotation upload failed:`, err?.message || err);
+    }
+  }
+
+  /** Persist progress mid-pass, so the next slice continues from here. */
+  async #save(collectionId, next) {
+    await this.kv.set(NS, collectionId, next);
+    return next;
+  }
+
+  /** Abandon a rotation. The new key stays current; what has moved stays moved. */
+  async cancel(collectionId) {
+    const state = await this.state(collectionId);
+    if (!state) return null;
+    // The half-written object goes with it. Nothing else can find that multipart — the
+    // storage contract cannot list them — so if this does not spend it, nothing will.
+    await this.#discard(collectionId, state.inflight);
+    const next = { ...state, status: 'done', cancelled: true, inflight: null };
+    await this.kv.set(NS, collectionId, next);
+    return next;
+  }
+}
+
+/** Read the fingerprint an object actually carries, for checking rather than trusting. */
+export async function fingerprintOf(bytes) {
+  return toHex(decodeHeader(bytes).fingerprint);
+}
+
+export { fromHex };

package/packages/core/src/index.js

@@ -16,6 +16,7 @@ export { MemoryStorage } from './storage/memory.js';
 export { StorageDriverRegistry } from './storage/registry.js';
 export { portableDrivers } from './storage/drivers.js';
 export { diagnoseStorage, corsPolicy, STORAGE_ISSUE_CODES } from './storage/diagnose.js';
+export { estimateRotationCost, recognizeProvider, RATES_AS_OF } from './storage/cost.js';
 export { S3Storage } from './storage/s3.js';
 export { PrefixedStorage } from './storage/prefixed.js';
 
@@ -36,7 +37,22 @@ export { SqliteVectorStore, SqliteKeywordStore, SEARCH_DB_KEY } from './search/s
 
 export { IndexerRegistry, textIndexer, chunkText } from './indexers/registry.js';
 export { PluginService, PackageStore, StoragePackageStore, PluginInstallStore, SqlitePluginInstallStore, MemoryPluginInstallStore, parsePluginPackage, capabilityList, ALL_CAPABILITIES, IndexerRuntime, InProcessIndexerRuntime, PluginIndexers, matchFromSelector } from './plugins/index.js';
-export { UploadManager, DEFAULT_PART_SIZE } from './uploads.js';
+export { UploadManager, KvSessionStore, DEFAULT_PART_SIZE } from './uploads.js';
+// Encryption at rest: the bucket holds ciphertext, the drive holds the key. Protects
+// against the STORAGE host (a leaked bucket credential, a storage vendor who is not the
+// compute vendor) and deliberately not against the server, which must read plaintext to
+// index it. See encryption/keys.js for why nothing here is a plain hash of a passphrase.
+export {
+  encrypt, encryptStream, decrypt, decryptRange, decryptStream, encodeHeader, decodeHeader, isEnvelope,
+  cipherSize, plaintextSizeOf, cipherRangeFor,
+  HEADER_BYTES, TAG_BYTES, DEFAULT_CHUNK_SIZE,
+} from './encryption/envelope.js';
+export {
+  generateDataKey, newCollectionKey, fingerprint, fingerprintHex, toHex, fromHex,
+} from './encryption/keys.js';
+export { normalizeEncryption, shouldEncrypt, describeEncryption } from './encryption/policy.js';
+export { RotationService } from './encryption/rotation.js';
+export { describeExposure } from './encryption/exposure.js';
 export { Vfs, CONTENT_TYPES } from './vfs.js';
 export { IndexingCoordinator } from './indexing.js';
 // Work in flight (ephemeral) and standing problems (durable) — see the header of each.

package/packages/core/src/links.js

@@ -139,3 +139,88 @@ export function troveUrisFor(node) {
   if (node?.collectionId && node?.id) out.push(troveUri(node, 'id'));
   return out;
 }
+
+// --- shareable web links -------------------------------------------------------
+//
+// `trove:` addresses an item INSIDE the drive: it is what one document writes to link
+// another, and it means nothing to a browser. A share link is the other half — a URL you
+// can paste into a message so that someone else's browser opens the same item.
+//
+// They are deliberately the same addressing, not two competing schemes. A share link is a
+// `trove:` URI wearing an http(s) coat: same collection, same explicit `name`-or-`id`
+// selector, same refusal to infer which one you meant. So anything that can already
+// resolve a `trove:` URI can resolve a share link by parsing it back, and a rename breaks
+// both in the same visible way rather than one silently retargeting.
+//
+// The path form — /c/<collection>/i/<selector> — rather than the query form
+// `?coll=&item=`. Both put the ids in the URL and therefore in server logs and browser
+// history, so that is not the difference; the path reads as a location, survives being
+// truncated in a chat client more gracefully, and leaves the query string free for the
+// things that genuinely are parameters.
+//
+// Nothing secret ever rides in one. An encrypted collection's key is not in the link and
+// must not be: a link is pasted into chats, logged by proxies, and kept in history
+// forever. The recipient gets the item because they are allowed the collection, which is
+// the same rule as everywhere else here.
+
+/** The path a share link uses. Exported so a client router and the server agree. */
+export const SHARE_PATH = '/c';
+
+/**
+ * A URL that opens this item in a browser.
+ *
+ * @param {object} node
+ * @param {string} [origin] where the drive is served; omitted gives a root-relative link
+ * @param {'name'|'id'} [by] `name` reads better and breaks on rename; `id` is the reverse
+ */
+export function shareUrl(node, origin = '', by = 'name') {
+  if (!node?.collectionId) throw TroveError.invalid('An item needs a collection to be linked to');
+  const selector = by === 'id'
+    ? `id:${node.id}`
+    : encodeURIComponent(node.name);
+  if (!selector || (by === 'id' && !node.id)) throw TroveError.invalid('Nothing to link to');
+  const path = `${SHARE_PATH}/${encodeURIComponent(node.collectionId)}/i/${selector}`;
+  return origin ? `${String(origin).replace(/\/$/, '')}${path}` : path;
+}
+
+/**
+ * Read a share link back, from a full URL or just a path.
+ *
+ * Returns the same shape `parseTroveUri` does, so a caller resolves either without caring
+ * which it was handed. Null rather than a throw: this parses whatever was in the address
+ * bar, and a URL that is not a share link is an ordinary page, not an error.
+ */
+export function parseShareUrl(url) {
+  let path;
+  try {
+    path = url.startsWith('/') ? url : new URL(url).pathname;
+  } catch {
+    return null;
+  }
+  const m = /^\/c\/([^/]+)\/i\/(.+)$/.exec(path);
+  if (!m) return null;
+  let collection;
+  let raw;
+  try {
+    collection = decodeURIComponent(m[1]);
+    raw = decodeURIComponent(m[2]);
+  } catch {
+    return null; // a malformed escape is not a link to anything
+  }
+  if (!COLLECTION_RE.test(collection)) return null;
+  // `id:` is the explicit selector, mirroring `?id=` — a name is never guessed at just
+  // because it happens to look like an id.
+  const byId = raw.startsWith('id:');
+  const value = byId ? raw.slice(3) : raw;
+  if (!value || value.length > MAX_SELECTOR) return null;
+  return { collection, by: byId ? 'id' : 'name', value };
+}
+
+/** The `trove:` URI a share link denotes — the two are the same address. */
+export function troveUriFromShareUrl(url) {
+  const parsed = parseShareUrl(url);
+  if (!parsed) return null;
+  return parsed.by === 'id'
+    ? `${TROVE_SCHEME}${parsed.collection}?id=${encodeURIComponent(parsed.value)}`
+    : `${TROVE_SCHEME}${parsed.collection}?name=${encodeURIComponent(parsed.value)}`;
+}

package/packages/core/src/metadata/memory.js

@@ -90,6 +90,8 @@ export class MemoryStore extends MetadataStore {
       size: node.size ?? 0, contentType: node.contentType ?? null,
       storageKey: node.storageKey ?? null, etag: node.etag ?? null,
       createdAt: now, updatedAt: now, meta: node.meta ?? {}, facets: rawFacetsFromNode(node),
+      // Which key opens this object; null for anything stored in the clear.
+      encryption: node.encryption ?? null,
     };
     this.#index(full);
     return clone(full);
@@ -98,7 +100,7 @@ export class MemoryStore extends MetadataStore {
   async update(id, patch) {
     const node = this.nodes.get(id);
     if (!node) throw TroveError.notFound('Item');
-    for (const k of ['size', 'contentType', 'storageKey', 'etag', 'meta']) {
+    for (const k of ['size', 'contentType', 'storageKey', 'etag', 'meta', 'encryption']) {
       if (k in patch) node[k] = patch[k];
     }
     node.updatedAt = Date.now();

package/packages/core/src/metadata/sqlite.js

@@ -46,7 +46,8 @@ export class SqliteStore extends MetadataStore {
         createdAt INTEGER NOT NULL,
         updatedAt INTEGER NOT NULL,
         meta TEXT NOT NULL DEFAULT '{}',
-        facets TEXT NOT NULL DEFAULT '{}'
+        facets TEXT NOT NULL DEFAULT '{}',
+        encryption TEXT
       );
       CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
       CREATE INDEX IF NOT EXISTS idx_nodes_updated ON nodes(updatedAt);
@@ -68,6 +69,11 @@ export class SqliteStore extends MetadataStore {
     if (!cols.some((c) => c.name === 'deletedAt')) {
       await this.db.exec('ALTER TABLE nodes ADD COLUMN deletedAt INTEGER');
     }
+    // Which key opens this object, for drives that predate encryption. NULL means stored
+    // in the clear, which is what every existing row is.
+    if (!cols.some((c) => c.name === 'encryption')) {
+      await this.db.exec('ALTER TABLE nodes ADD COLUMN encryption TEXT');
+    }
     // Recreating the index is cheap and idempotent; naming the new one differently is
     // what makes "has this run?" answerable without a migrations table.
     await this.db.exec(`
@@ -130,14 +136,16 @@ export class SqliteStore extends MetadataStore {
       size: node.size ?? 0, contentType: node.contentType ?? null,
       storageKey: node.storageKey ?? null, etag: node.etag ?? null,
       createdAt: now, updatedAt: now, meta: node.meta ?? {}, facets: rawFacetsFromNode(node),
+      encryption: node.encryption ?? null,
     };
     try {
       await this.db.run(
-        `INSERT INTO nodes (id,collectionId,name,size,contentType,storageKey,etag,createdAt,updatedAt,meta,facets)
-         VALUES (?,?,?,?,?,?,?,?,?,?,?)`,
+        `INSERT INTO nodes (id,collectionId,name,size,contentType,storageKey,etag,createdAt,updatedAt,meta,facets,encryption)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`,
         full.id, full.collectionId, full.name, full.size,
         full.contentType, full.storageKey, full.etag, full.createdAt, full.updatedAt,
         JSON.stringify(full.meta), JSON.stringify(full.facets),
+        full.encryption ? JSON.stringify(full.encryption) : null,
       );
       return full;
     } catch (err) {
@@ -150,13 +158,17 @@ export class SqliteStore extends MetadataStore {
     const node = await this.getById(id);
     if (!node) throw TroveError.notFound('Node');
     const next = { ...node };
-    for (const k of ['size', 'contentType', 'storageKey', 'etag', 'meta']) {
+    // `encryption` is here because a key rotation rewrites the object and has to record
+    // which key the new one is sealed with. Without it a rotated item still claims the old
+    // key and becomes unreadable the moment that key is retired.
+    for (const k of ['size', 'contentType', 'storageKey', 'etag', 'meta', 'encryption']) {
       if (k in patch) next[k] = patch[k];
     }
     next.updatedAt = Date.now();
     await this.db.run(
-      `UPDATE nodes SET size=?, contentType=?, storageKey=?, etag=?, meta=?, updatedAt=? WHERE id=?`,
-      next.size, next.contentType, next.storageKey, next.etag, JSON.stringify(next.meta), next.updatedAt, id,
+      `UPDATE nodes SET size=?, contentType=?, storageKey=?, etag=?, meta=?, encryption=?, updatedAt=? WHERE id=?`,
+      next.size, next.contentType, next.storageKey, next.etag, JSON.stringify(next.meta),
+      next.encryption ? JSON.stringify(next.encryption) : null, next.updatedAt, id,
     );
     return next;
   }
@@ -353,7 +365,15 @@ export class SqliteStore extends MetadataStore {
 function row(r) {
   if (!r) return null;
   const { contributions, tags } = splitContributions(r.facets ? JSON.parse(r.facets) : {});
-  const out = { ...r, meta: r.meta ? JSON.parse(r.meta) : {}, contributions, tags };
+  const out = {
+    ...r,
+    meta: r.meta ? JSON.parse(r.meta) : {},
+    // Null for everything stored in the clear, which is every row on a drive that predates
+    // encryption and every item a rule did not match.
+    encryption: r.encryption ? JSON.parse(r.encryption) : null,
+    contributions,
+    tags,
+  };
   delete out.facets; // internal column name; exposed as contributions + tags
   return out;
 }