@3sln/trove 0.0.5 → 0.0.8

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

@@ -0,0 +1,101 @@
+// What encryption does not protect you from, said plainly and per collection.
+//
+// Encryption here defends the BUCKET. Anything that indexes a file sees it in the clear,
+// because indexing is by definition reading the contents — the server decrypts before
+// handing bytes to an indexer, and that is the whole reason full search still works on an
+// encrypted collection. So a badge saying "encrypted" is true and, on its own, misleading.
+//
+// The disclosure that matters is therefore not about encryption at all. It is: which things
+// read your files, which of them are third-party code, and where that code is allowed to
+// send what it reads. A built-in indexer runs in this drive and talks to nobody. A plugin
+// indexer might be pointed at an external API, and the manifest already says which one.
+//
+// Read off the manifest rather than written as prose. A sentence in a settings page drifts
+// from what a plugin is actually permitted the moment either changes; a list derived from
+// the declaration it is enforced against cannot. If it says a plugin may reach one host,
+// that is because the plugin may reach exactly that host.
+
+/**
+ * @typedef {object} IndexerExposure
+ * @property {string} id
+ * @property {string} name
+ * @property {'built-in'|'plugin'} source
+ * @property {string|null} pluginId
+ * @property {string[]} endpoints  where this one may send what it reads; empty means nowhere
+ */
+
+/**
+ * Who reads the files in this collection, and where it can send them.
+ *
+ * @param {object} deps
+ * @param {Array<{id: string, displayName?: string}>} deps.indexers  what will run
+ * @param {Array<object>} [deps.plugins]  installed plugin records, with manifests
+ * @param {(manifest: object) => string[]} [deps.endpointsOf]  how to read declared egress
+ * @param {object|null} [deps.encryption]  the collection's encryption config
+ */
+export function describeExposure({ indexers = [], plugins = [], endpointsOf = null, encryption = null } = {}) {
+  // Defaulting this to `() => []` would have every plugin report "reaches nowhere" whenever
+  // a caller forgot to wire it — an affirmative safety claim made with no evidence, which
+  // is the same mistake as calling an unresolved plugin built-in. No reader means unknown.
+  const readEndpoints = typeof endpointsOf === 'function' ? endpointsOf : null;
+  // A plugin indexer's id is a contribution URI — `trove+contrib:<domain>/<name>/<what>` —
+  // so the plugin it belongs to is derivable from the id rather than tracked separately.
+  const byId = new Map();
+  for (const p of plugins) {
+    const id = p.id || p.manifest?.name;
+    if (id) byId.set(id, p);
+  }
+
+  const rows = indexers.map((i) => {
+    // Whether something is a plugin is decided by its ID, not by whether we managed to find
+    // its install record. An indexer whose plugin we cannot resolve is still third-party
+    // code, and calling it built-in would be the most dangerous mislabel available here.
+    const contributed = String(i.id || '').startsWith('trove+contrib:');
+    const owner = contributed ? pluginOf(i.id, byId) : null;
+    return {
+      id: i.id,
+      name: i.displayName || i.id,
+      source: contributed ? 'plugin' : 'built-in',
+      pluginId: owner ? (owner.id || owner.manifest?.name || null) : null,
+      // `[]` is an affirmative claim that this reaches nowhere. Without a manifest we
+      // cannot make it, so an unresolved plugin gets `null` — unknown — and is counted
+      // among the things that might send data out rather than among the things that cannot.
+      endpoints: owner && readEndpoints ? [...new Set(readEndpoints(owner.manifest) || [])] : (contributed ? null : []),
+    };
+  });
+
+  const reachOut = rows.filter((r) => r.endpoints === null || r.endpoints.length);
+  const unknown = rows.filter((r) => r.endpoints === null);
+  return {
+    encrypted: !!encryption?.enabled,
+    // Said explicitly, because "encrypted" without a scope is the thing people
+    // over-read. This is what the encryption is and is not.
+    protects: encryption?.enabled
+      ? 'Files are encrypted before they reach the storage provider, so the bucket holds ciphertext. '
+        + 'It is not end-to-end: this drive holds the key, and anything that indexes a file reads it in the clear.'
+      : null,
+    indexers: rows,
+    // The single fact someone should be able to see without reading a list.
+    anyEgress: reachOut.length > 0,
+    egressSummary: reachOut.length
+      ? `${reachOut.length} of ${rows.length} indexers may send file contents outside this drive.`
+        + (unknown.length
+          ? ` ${unknown.length} could not be checked, because the plugin that provides it is not installed here.`
+          : '')
+      : rows.length
+        ? 'No indexer on this collection may send file contents anywhere.'
+        : 'Nothing indexes this collection.',
+  };
+}
+
+/** Which installed plugin an indexer id belongs to, if any. */
+function pluginOf(indexerId, byId) {
+  const id = String(indexerId || '');
+  if (!id.startsWith('trove+contrib:')) return null;
+  // `trove+contrib:<domain>/<name>/<contribution>` — the plugin is domain/name.
+  const path = id.slice('trove+contrib:'.length);
+  const parts = path.split('/');
+  if (parts.length < 2) return null;
+  const owner = `${parts[0]}/${parts[1]}`;
+  return byId.get(owner) || byId.get(parts[1]) || null;
+}

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

@@ -0,0 +1,88 @@
+// The key a collection's objects are encrypted with, and the fingerprint that names it.
+//
+// The threat model is the STORAGE HOST, and only that: the bucket holds ciphertext, so a
+// leaked bucket credential, a public-bucket misconfiguration, or a storage vendor who is
+// not the compute vendor learns sizes and timestamps and no content. The server holds the
+// key — it has to, in order to hand it to a client and to decrypt for an indexer — so this
+// is explicitly not end-to-end and does not pretend to be.
+//
+// Which is why the key is GENERATED rather than derived from something a user types.
+// A passphrase would buy nothing here: the server knows the key either way, so there is no
+// protection to gain from the user holding it, and every cost still applies — a slow KDF
+// on every unlock, a prompt in front of every collection, a key that can be forgotten and
+// then cannot be reset by anyone, and a re-encryption of everything whenever someone
+// changes their password. A random 256-bit key has none of that and is stronger than any
+// passphrase a person would choose.
+//
+// Access to the key is therefore an ACCESS-CONTROL question, not a knowledge one: whoever
+// may read the collection may have the key, because they may already read its contents.
+//
+// If this ever becomes end-to-end, the change is confined to where the key comes from and
+// who is allowed it. The envelope, the fingerprint, and every stored object are unchanged.
+
+import { TroveError } from '../errors.js';
+
+const enc = new TextEncoder();
+
+export const KEY_BYTES = 32; // AES-256
+export const FINGERPRINT_BYTES = 16;
+
+/** A new collection key. Random, because there is nothing to derive it from. */
+export function generateDataKey() {
+  return crypto.getRandomValues(new Uint8Array(KEY_BYTES));
+}
+
+/**
+ * The public name of a key.
+ *
+ * Stamped into every object and recorded on the collection, so an object can be matched to
+ * a key by whoever holds it — which is what makes a sideloaded object identifiable and
+ * what lets a key rotation tell what it has already converted.
+ *
+ * Derived through HKDF rather than being a plain hash of the key. With a random 256-bit key
+ * there is nothing to guess, so this is no longer load-bearing against an offline attack;
+ * it stays because a fingerprint should be a value derived FOR this purpose, and a bare
+ * `SHA-256(key)` is a value that might mean something somewhere else. The label makes it
+ * unambiguously this and nothing else.
+ *
+ * @param {Uint8Array} dataKey
+ * @returns {Promise<Uint8Array>} 16 bytes — far past collision risk for "which key is this"
+ */
+export async function fingerprint(dataKey) {
+  if (!(dataKey instanceof Uint8Array) || dataKey.length !== KEY_BYTES) {
+    throw TroveError.invalid('A data key must be 32 bytes');
+  }
+  const base = await crypto.subtle.importKey('raw', dataKey, 'HKDF', false, ['deriveBits']);
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: enc.encode('trove-key-id') },
+    base,
+    FINGERPRINT_BYTES * 8,
+  );
+  return new Uint8Array(bits);
+}
+
+/** Bytes as lowercase hex — how a key and a fingerprint are written down. */
+export function toHex(b) {
+  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+export function fromHex(hex) {
+  if (typeof hex !== 'string' || !hex.length || hex.length % 2 || /[^0-9a-f]/i.test(hex)) {
+    throw TroveError.invalid('Not hex');
+  }
+  return new Uint8Array(hex.match(/../g).map((h) => parseInt(h, 16)));
+}
+
+/** Kept as the name the rest of the code already uses for a fingerprint in hex. */
+export const fingerprintHex = toHex;
+
+/**
+ * A fresh key and what the collection records about it.
+ *
+ * The key is returned separately from the config because they go to different places: the
+ * config is what any reader may see, and the key is what the server keeps.
+ */
+export async function newCollectionKey() {
+  const dataKey = generateDataKey();
+  return { dataKey, config: { fingerprint: toHex(await fingerprint(dataKey)) } };
+}

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

@@ -0,0 +1,112 @@
+// Which items in a collection get encrypted, and what the collection tells a client
+// about its key.
+//
+// Encryption is per collection and selective within it, because "encrypt everything" is
+// not always what someone wants and the cost is not free: an encrypted object cannot be
+// served straight from the bucket to something that does not hold the key, and the storage
+// host can no longer deduplicate it. So a collection says which extensions and which media
+// types are sensitive, and the rest is stored as it always was.
+//
+// The rules are matched at UPLOAD time and the answer is recorded in the object itself —
+// the envelope header — rather than re-derived later. Rules change; an object that was
+// encrypted must stay readable as an encrypted object regardless of what the collection
+// says today, and one that was not must not suddenly be interpreted as one.
+
+import { TroveError } from '../errors.js';
+
+/**
+ * What a collection stores about its encryption.
+ *
+ * The fingerprint is safe to show anyone who may see the collection: it names the key
+ * without being it. The key itself is never part of this — it reaches a client through a
+ * transfer plan, which is authorized per operation.
+ *
+ * @typedef {object} EncryptionConfig
+ * @property {boolean} enabled
+ * @property {string} fingerprint hex — which key this collection's objects are sealed with
+ * @property {{extensions: string[], mimeTypes: string[], all: boolean}} rules
+ */
+
+const normList = (v) => (Array.isArray(v) ? v : [])
+  .map((s) => String(s || '').trim().toLowerCase())
+  .filter(Boolean);
+
+/** An extension without its dot, so ".PDF", "PDF" and "pdf" are one rule. */
+const normExt = (e) => e.replace(/^\./, '');
+
+/**
+ * Validate and normalise what a caller asked for, against the key the server holds.
+ *
+ * The fingerprint is a separate argument rather than a field of `input` because the two
+ * come from different places and only one of them is the caller's to decide: rules are
+ * asked for, the key is minted. A collection recorded as encrypted with no fingerprint is
+ * one whose objects could never be matched to a key, so it is refused rather than repaired.
+ *
+ * @param {object|null} input   what the caller asked for: `{ enabled, rules }`
+ * @param {string} [fingerprint] hex, from the collection's key
+ */
+export function normalizeEncryption(input, fingerprint) {
+  if (!input || input.enabled === false) return null;
+  const fp = fingerprint ?? input.fingerprint;
+  if (!fp) throw TroveError.invalid('An encrypted collection needs a key fingerprint');
+  if (!/^[0-9a-f]{32}$/.test(String(fp))) {
+    throw TroveError.invalid('Not a key fingerprint');
+  }
+  const r = input.rules || {};
+  const out = {
+    enabled: true,
+    fingerprint: String(fp),
+    rules: {
+      all: !!r.all,
+      extensions: [...new Set(normList(r.extensions).map(normExt))],
+      mimeTypes: [...new Set(normList(r.mimeTypes))],
+    },
+  };
+  if (!out.rules.all && !out.rules.extensions.length && !out.rules.mimeTypes.length) {
+    // Enabling encryption and matching nothing is almost certainly a mistake, and a silent
+    // one: every upload would be stored in the clear on a collection labelled encrypted.
+    throw TroveError.invalid(
+      'This collection is set to encrypt, but no file would match. Choose "all files", or name some extensions or media types.',
+    );
+  }
+  return out;
+}
+
+/**
+ * Should this item be encrypted?
+ *
+ * A media type match is by full type or by its leading part, so `image` covers
+ * `image/png` without listing every format — which is how someone actually thinks about
+ * "encrypt my photos".
+ */
+export function shouldEncrypt(encryption, { name = '', contentType = '' } = {}) {
+  if (!encryption?.enabled) return false;
+  const { rules } = encryption;
+  if (rules.all) return true;
+
+  const ext = normExt((String(name).match(/\.[^./\\]+$/) || [''])[0].toLowerCase());
+  if (ext && rules.extensions.includes(ext)) return true;
+
+  const type = String(contentType || '').toLowerCase().split(';')[0].trim();
+  if (!type) return false;
+  if (rules.mimeTypes.includes(type)) return true;
+  const [top] = type.split('/');
+  return !!top && rules.mimeTypes.includes(top);
+}
+
+/**
+ * What a client is told about a collection's encryption.
+ *
+ * Enough to know that objects here are sealed and which key seals them; never the key.
+ * There is no "locked" state and nothing to prompt for — a client that may read the
+ * collection is handed the key with the transfer plan, because being allowed to read the
+ * contents and being allowed to decrypt them are the same permission.
+ */
+export function describeEncryption(encryption) {
+  if (!encryption?.enabled) return null;
+  return {
+    enabled: true,
+    fingerprint: encryption.fingerprint,
+    rules: { ...encryption.rules },
+  };
+}

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

@@ -0,0 +1,313 @@
+// 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
+ */
+
+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');
+    }
+    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,
+      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;
+
+    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 {
+          await this.#move(node, key, fp);
+          moved++;
+        } 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,
+      // 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;
+  }
+
+  /**
+   * Read one object under whichever key it names, and write it back under the new one.
+   *
+   * 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.
+   */
+  async #move(node, newKey, newFingerprint) {
+    const storage = await this.vfs.storageFor(node.collectionId);
+    const chunkSize = node.encryption.chunkSize;
+    // 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 = `${node.storageKey}.rot${Date.now().toString(36)}`;
+
+    const read = await this.vfs.readStream(node.id);
+    const sealed = await encryptStream(newKey, read.stream, {
+      fingerprint: newFingerprint,
+      plaintextSize: read.size ?? node.size,
+      chunkSize,
+    });
+
+    // Streamed into multipart parts rather than collected.
+    //
+    // Buffering meant holding the file twice — once decrypted and once sealed — so a
+    // rotation was capped at whatever fits in an isolate. On Workers that is 128 MB for
+    // everything, which put the ceiling somewhere around a 50 MB file and made rotation
+    // simply unavailable for the collections most likely to want it. Peak memory is now one
+    // part, whatever the object weighs.
+    //
+    // A backend that cannot do multipart is a local one — filesystem, memory — where the
+    // whole object is already in reach and a single put is both simpler and fine.
+    if (storage.capabilities?.multipart) {
+      await this.#putStreamed(storage, nextKey, sealed, node.contentType);
+    } else {
+      await storage.put(nextKey, new Uint8Array(await new Response(sealed).arrayBuffer()), {
+        contentType: node.contentType,
+      });
+    }
+
+    // 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(() => {});
+  }
+
+  /**
+   * Upload a stream as a multipart object, holding one part at a time.
+   *
+   * Parts are accumulated to a target size because S3 requires every part except the last
+   * to clear a 5 MiB floor — an envelope chunk is far smaller than that, so one chunk per
+   * part would be rejected.
+   *
+   * A failure aborts the multipart. Without that the parts already sent stay in the bucket,
+   * billed, with nothing left able to reclaim them.
+   */
+  async #putStreamed(storage, key, stream, contentType) {
+    const uploadId = await storage.createMultipart(key, { contentType });
+    try {
+      const reader = stream.getReader();
+      const parts = [];
+      let held = [];
+      let size = 0;
+      let n = 1;
+      const flush = async () => {
+        const part = new Uint8Array(size);
+        let at = 0;
+        for (const p of held) { part.set(p, at); at += p.length; }
+        held = [];
+        size = 0;
+        const etag = await storage.putPart(key, uploadId, n, part);
+        parts.push({ partNumber: n, etag: etag?.etag ?? etag });
+        n++;
+      };
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        held.push(value);
+        size += value.length;
+        if (size >= PART_TARGET_BYTES) await flush();
+      }
+      // The final part may be under the floor, and only the final part may be.
+      if (size || parts.length === 0) await flush();
+      await storage.completeMultipart(key, uploadId, parts);
+    } catch (err) {
+      await storage.abortMultipart(key, uploadId).catch(() => {});
+      throw err;
+    }
+  }
+
+  /** 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;
+    const next = { ...state, status: 'done', cancelled: true };
+    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.