@3sln/trove 0.0.5 → 0.0.8

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;
 }

package/packages/core/src/scan.js

@@ -23,6 +23,8 @@
 import { TroveError } from './errors.js';
 import { extname } from './util.js';
 import { PACKAGE_PREFIX } from './plugins/packageStore.js';
+import { isEnvelope, decodeHeader, HEADER_BYTES } from './encryption/envelope.js';
+import { toHex } from './encryption/keys.js';
 
 /** Objects Trove wrote itself. Anything else in the store arrived some other way. */
 const TROVE_KEY = /^obj_[0-9a-f]+$/i;
@@ -184,6 +186,26 @@ export class CollectionScanner {
     return false;
   }
 
+
+  /**
+   * Read an object's envelope header, or null if it does not have one.
+   *
+   * A fixed-size range read, so it costs one small request per adopted object and never
+   * pulls the object itself. A failure to read or parse means "not one of ours", which is
+   * the right answer for an ordinary file that happens to start with something odd.
+   */
+  async #envelopeOf(collectionId, storageKey) {
+    try {
+      const storage = await this.vfs.storageFor(collectionId);
+      const head = await storage.get(storageKey, { range: { start: 0, end: HEADER_BYTES - 1 } });
+      const bytes = new Uint8Array(await new Response(head.stream).arrayBuffer());
+      if (!isEnvelope(bytes)) return null;
+      return decodeHeader(bytes);
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Create an item for an object that arrived without us.
    *
@@ -196,13 +218,25 @@ export class CollectionScanner {
   async #adopt(collectionId, object) {
     if (TROVE_KEY.test(object.key)) return null; // orphaned blob from an interrupted upload
     const name = await this.#uniqueName(collectionId, object.key);
+    // Is this an encrypted object somebody copied in?
+    //
+    // The envelope says so, and says which key it wants, WITHOUT the key — which is the
+    // entire reason the header is readable. Without this an adopted object is recorded as
+    // plaintext, and every read of it hands back raw ciphertext with no error: the drive
+    // shows a file, and opening it gives you an unreadable blob. Sideloading is a named
+    // use case here, so it has to be the case that works.
+    const envelope = await this.#envelopeOf(collectionId, object.key);
     const node = await this.vfs.metadata.create({
       collectionId,
       name,
       storageKey: object.key,
-      size: object.size ?? 0,
+      // The size the file has, not the size the envelope occupies.
+      size: envelope ? envelope.plaintextSize : (object.size ?? 0),
       etag: object.etag ?? null,
       contentType: this.vfs.guessContentType(name),
+      encryption: envelope
+        ? { fingerprint: toHex(envelope.fingerprint), chunkSize: envelope.chunkSize }
+        : null,
       meta: { adopted: true, adoptedAt: Date.now() },
     });
     // Adopted files are indexed like any other, so they are findable immediately —

package/packages/core/src/storage/cost.js

@@ -0,0 +1,228 @@
+// What a bulk pass over a collection will cost at the storage provider.
+//
+// Re-encrypting a collection is the first operation here big enough for the answer to
+// matter: the server reads every object and writes it back, so on a metered store it is a
+// real bill, and on a large collection it can be a surprising one. Someone should be able
+// to see the number before they press the button, not on an invoice.
+//
+// Two things shape how this is written.
+//
+// THE MODEL OUTLASTS THE NUMBERS. "R2 does not charge for egress, so this costs operations
+// only" stays true long after any per-GB figure is stale. So every provider carries a
+// plain-language description of WHAT is charged, and that is what leads; the rates are
+// supporting detail, stamped with the date they were taken and linked to the source.
+//
+// WE WILL BE WRONG EVENTUALLY. Prices change, free tiers change, and a drive can be years
+// old. Nothing here is presented as authoritative: an estimate says where its figures came
+// from and when, and every answer links the provider's own pricing page. An unrecognised
+// endpoint gets an honest description of how object stores usually bill rather than a
+// fabricated number.
+
+/**
+ * When these rates were last checked. Shown with every estimate, because a figure without
+ * a date invites being trusted longer than it deserves.
+ */
+export const RATES_AS_OF = '2026-07';
+
+/**
+ * What we think we know, per provider.
+ *
+ * `egress` is the field that actually decides whether a rotation is cheap or expensive, and
+ * it is the one worth getting right: a store that does not charge for reads out is a store
+ * where this operation costs pennies regardless of size.
+ */
+const PROVIDERS = [
+  {
+    id: 'r2',
+    name: 'Cloudflare R2',
+    match: /\.r2\.cloudflarestorage\.com$/i,
+    docs: 'https://developers.cloudflare.com/r2/pricing/',
+    egress: 'none',
+    egressNote: 'R2 does not charge for data transferred out, which is the cost that would otherwise dominate this.',
+    // Class B is reads, Class A is writes.
+    readPerMillion: 0.36,
+    writePerMillion: 4.50,
+    egressPerGB: 0,
+  },
+  {
+    id: 'aws',
+    name: 'Amazon S3',
+    // Covers the regional forms (s3.eu-west-2, s3-us-west-2), the legacy global endpoint
+    // (s3.amazonaws.com), and virtual-host style (bucket.s3.region.amazonaws.com).
+    match: /(^|\.)s3([.-][a-z0-9-]+)?\.amazonaws\.com$/i,
+    docs: 'https://aws.amazon.com/s3/pricing/',
+    egress: 'metered',
+    // The nuance that changes the answer by orders of magnitude, and the one people are
+    // most often caught by.
+    egressNote:
+      'S3 charges for data transferred out to the internet. If this drive runs outside AWS '
+      + '(on Cloudflare Workers, for example) every byte read is billed at that rate; if it runs '
+      + 'in EC2 or Lambda in the same region as the bucket, transfer is normally free and this '
+      + 'costs requests only.',
+    readPerMillion: 400,
+    writePerMillion: 5000,
+    egressPerGB: 0.09,
+  },
+  {
+    id: 'b2',
+    name: 'Backblaze B2',
+    match: /(^|\.)backblazeb2\.com$/i,
+    docs: 'https://www.backblaze.com/cloud-storage/pricing',
+    egress: 'allowance',
+    egressNote:
+      'B2 includes free egress up to a multiple of what you store, and charges beyond it. A '
+      + 'one-off pass over a collection often falls inside that allowance.',
+    readPerMillion: 4,
+    writePerMillion: 0,
+    egressPerGB: 0.01,
+  },
+  {
+    id: 'wasabi',
+    name: 'Wasabi',
+    match: /(^|\.)wasabisys\.com$/i,
+    docs: 'https://wasabi.com/cloud-storage-pricing',
+    egress: 'none',
+    egressNote:
+      'Wasabi does not charge for egress or requests. Note its minimum storage duration, '
+      + 'though: rewriting an object can restart the clock on what the original was charged for.',
+    readPerMillion: 0,
+    writePerMillion: 0,
+    egressPerGB: 0,
+  },
+  {
+    id: 'spaces',
+    name: 'DigitalOcean Spaces',
+    match: /(^|\.)digitaloceanspaces\.com$/i,
+    docs: 'https://www.digitalocean.com/pricing/spaces-object-storage',
+    egress: 'allowance',
+    egressNote: 'Spaces includes a monthly transfer allowance and charges per GB beyond it.',
+    readPerMillion: 0,
+    writePerMillion: 0,
+    egressPerGB: 0.01,
+  },
+  {
+    id: 'gcs',
+    name: 'Google Cloud Storage',
+    match: /(^|\.)storage\.googleapis\.com$/i,
+    docs: 'https://cloud.google.com/storage/pricing',
+    egress: 'metered',
+    egressNote:
+      'GCS charges for data read out to the internet, and for operations. Reading from within '
+      + 'Google Cloud in the same region is normally free.',
+    readPerMillion: 400,
+    writePerMillion: 5000,
+    egressPerGB: 0.12,
+  },
+];
+
+/**
+ * Stores where this question does not arise.
+ *
+ * A directory on a disk and a NATS object store are not metered by anyone, so offering a
+ * cost estimate would be inventing a concern.
+ */
+const UNMETERED_DRIVERS = new Set(['filesystem', 'memory', 'nats']);
+
+/** Which provider an endpoint belongs to, or null if we do not recognise it. */
+export function recognizeProvider(endpoint) {
+  if (!endpoint) return null;
+  let host;
+  try {
+    host = new URL(endpoint).hostname;
+  } catch {
+    return null;
+  }
+  return PROVIDERS.find((p) => p.match.test(host)) || null;
+}
+
+const gb = (bytes) => bytes / 1024 ** 3;
+const money = (n) => Math.round(n * 100) / 100;
+
+/**
+ * What re-encrypting a collection will cost.
+ *
+ * The work is one read and one write per object, plus the bytes moving out of the bucket
+ * and back in. Ingress is free essentially everywhere, so it is named and not priced.
+ *
+ * @param {object} target
+ * @param {string} target.driver     the collection's store driver
+ * @param {string} [target.endpoint] its S3 endpoint, if it has one
+ * @param {number} objects  how many objects will be rewritten
+ * @param {number} bytes    how many bytes they hold
+ */
+export function estimateRotationCost({ driver, endpoint } = {}, { objects = 0, bytes = 0 } = {}) {
+  if (UNMETERED_DRIVERS.has(driver)) {
+    return {
+      applicable: false,
+      provider: null,
+      summary: 'This collection is on storage nobody bills you for, so a rotation costs only the time it takes.',
+      lines: [],
+      total: null,
+      docs: null,
+      asOf: RATES_AS_OF,
+    };
+  }
+
+  const p = recognizeProvider(endpoint);
+  const work = [
+    { label: 'Objects read and rewritten', value: `${objects.toLocaleString()}` },
+    { label: 'Data moved out of the bucket', value: `${gb(bytes).toFixed(2)} GB` },
+    // Named rather than priced: essentially no object store charges to receive bytes, and
+    // an estimate that lists a zero invites the reader to wonder what it is hiding.
+    { label: 'Data written back', value: `${gb(bytes).toFixed(2)} GB (ingress is not normally charged)` },
+  ];
+
+  if (!p) {
+    // Honest rather than invented. Describing how these services usually bill is more use
+    // than a number we made up for a host we have never seen.
+    return {
+      applicable: true,
+      provider: null,
+      confidence: 'unknown',
+      summary:
+        'We do not recognise this storage endpoint, so we cannot estimate a price. Object stores '
+        + 'usually charge for three things: the requests made, the data read back out, and what is '
+        + 'stored. A rotation makes one read and one write per object and moves every byte out and '
+        + 'back — so if your provider charges for egress, that is what will dominate.',
+      lines: work,
+      total: null,
+      docs: null,
+      asOf: RATES_AS_OF,
+    };
+  }
+
+  const egressCost = gb(bytes) * p.egressPerGB;
+  const readCost = (objects / 1e6) * p.readPerMillion;
+  const writeCost = (objects / 1e6) * p.writePerMillion;
+  const total = egressCost + readCost + writeCost;
+
+  const lines = [
+    ...work,
+    { label: 'Reads', value: `$${money(readCost).toFixed(2)}` },
+    { label: 'Writes', value: `$${money(writeCost).toFixed(2)}` },
+    {
+      label: 'Egress',
+      value: p.egress === 'none' ? 'not charged' : `$${money(egressCost).toFixed(2)}`,
+      note: p.egressNote,
+    },
+  ];
+
+  return {
+    applicable: true,
+    provider: p.name,
+    confidence: 'known',
+    // Leads with the model, because that is the part that stays true.
+    summary: p.egress === 'none'
+      ? `${p.name} does not charge for data transferred out, so this costs operations only.`
+      : `${p.name} charges for data read out of the bucket, so the size of this collection is what drives the price.`,
+    lines,
+    total: { amount: money(total), currency: 'USD', approximate: true },
+    docs: p.docs,
+    asOf: RATES_AS_OF,
+    // Said in the estimate itself, not left to the UI to remember.
+    caveat:
+      `These figures are what we recorded in ${RATES_AS_OF} and prices change — treat this as an `
+      + `order of magnitude, not a quote, and check ${p.name}'s own pricing page for what you will `
+      + 'actually be billed. Free tiers and committed-use discounts are not accounted for here.',
+  };
+}

package/packages/core/src/storage/drivers.js

@@ -49,9 +49,19 @@ export function portableDrivers() {
           help: 'MinIO and most self-hosted endpoints need this.',
         },
       ],
-      // S3Storage takes the config flat; the old switch passed `cfg.s3`, which meant a
-      // collection record had to nest its own settings one level deeper than every
-      // other driver for no reason a user could see.
+      // Two config shapes reach here and both have to work.
+      //
+      // Flat — `{ driver: 's3', bucket: … }` — is what `fields` above describes and what
+      // the collection form posts. Nested under `s3` is what `configFromEnv` produces and
+      // what every collection record written before this driver existed holds, because the
+      // switch this replaced read `cfg.s3` and nothing else.
+      //
+      // Normalising rather than only handling it in `create` is the point: validation runs
+      // against the normalised shape, so a nested config is no longer refused for a missing
+      // top-level `bucket` that was about to be spread in anyway. That refusal broke every
+      // environment-configured S3 deployment at startup, which is as loud as a bug gets and
+      // still took a local run to see, because no test used the env shape.
+      normalize: (cfg) => ({ ...cfg, ...(cfg.s3 || {}) }),
       create: (cfg) => new S3Storage({
         bucket: cfg.bucket,
         region: cfg.region || 'auto',
@@ -60,7 +70,6 @@ export function portableDrivers() {
         secretAccessKey: cfg.secretAccessKey,
         sessionToken: cfg.sessionToken,
         forcePathStyle: cfg.forcePathStyle === true || cfg.forcePathStyle === 'true',
-        ...(cfg.s3 || {}),
       }),
     },
     {

package/packages/core/src/storage/registry.js

@@ -56,6 +56,9 @@ export class StorageDriverRegistry {
    * @param {string} driver.label         for a form
    * @param {string} [driver.description] one line about what it is
    * @param {DriverField[]} [driver.fields]
+   * @param {(config: object) => object} [driver.normalize] accept an older or alternative
+   *   config shape, returning the one `fields` describes. Runs before validation, so the
+   *   shape checked is the shape built from.
    * @param {(config: object) => StorageBackend} driver.create
    */
   register(driver) {
@@ -82,6 +85,7 @@ export class StorageDriverRegistry {
         placeholder: f.placeholder || '',
         help: f.help || '',
       })),
+      normalize: driver.normalize || null,
       create: driver.create,
     });
     return this;
@@ -95,9 +99,30 @@ export class StorageDriverRegistry {
     return [...this._drivers.keys()];
   }
 
-  /** What a client needs to render a form. No `create`, because that is not data. */
+  /**
+   * One registered driver, `create` included — unlike `describe()`, which deliberately
+   * strips it because it answers a client.
+   *
+   * For copying a driver into another registry, which is how a deployment narrows the set
+   * it offers: a registry has no `unregister`, so narrowing rebuilds from what survived
+   * rather than removing from what did not. Keeping removal out of this class is the point
+   * — a driver disappearing from a live registry is a store that stops being buildable
+   * while collections still reference it.
+   */
+  driver(key) {
+    return this._drivers.get(key);
+  }
+
+  /**
+   * What a client needs to render a form.
+   *
+   * Neither `create` nor `normalize`: both are behaviour, not data. JSON.stringify would
+   * drop them anyway, which is exactly why they are removed here instead — a describe()
+   * whose result is only serialisable by accident is one that leaks the next function
+   * somebody adds into every in-process consumer.
+   */
   describe() {
-    return [...this._drivers.values()].map(({ create, ...rest }) => rest);
+    return [...this._drivers.values()].map(({ create, normalize, ...rest }) => rest);
   }
 
   /**
@@ -105,6 +130,13 @@ export class StorageDriverRegistry {
    *
    * An unknown driver throws, and says what IS available. This is the arm that used to
    * return an in-memory store.
+   *
+   * `normalize` runs FIRST, so a driver that accepts more than one config shape validates
+   * the shape it will actually build from. Without it, required-field checks are performed
+   * against a config the driver was about to rewrite — which is precisely how S3 broke:
+   * `configFromEnv` nests its settings under `s3`, `create` spread that back out, and the
+   * check in between looked for a top-level `bucket` that was never going to be there and
+   * refused every environment-configured S3 deployment at startup.
    */
   build(config) {
     const key = config?.driver;
@@ -115,12 +147,13 @@ export class StorageDriverRegistry {
         `Unknown storage driver "${key}" — this deployment has: ${this.keys().join(', ') || 'none'}`,
       );
     }
+    const cfg = driver.normalize ? driver.normalize(config) : config;
     for (const f of driver.fields) {
-      if (f.required && (config[f.name] == null || config[f.name] === '')) {
+      if (f.required && (cfg[f.name] == null || cfg[f.name] === '')) {
         throw TroveError.invalid(`Storage driver "${key}" requires "${f.name}"`);
       }
     }
-    const backend = driver.create(config);
+    const backend = driver.create(cfg);
     if (!(backend instanceof StorageBackend)) {
       throw TroveError.invalid(`Storage driver "${key}" did not return a StorageBackend`);
     }