@proteinjs/db-file 1.8.4 → 1.9.0

package/src/FileStorage.ts

@@ -1,11 +1,21 @@
-import { ScopedRecord, getScopedDb, getScopedDbAsSystem } from '@proteinjs/user';
+import { Reference, getDbAsSystem } from '@proteinjs/db';
+import { ScopedRecord, UserRepo, getScopedDb, getScopedDbAsSystem } from '@proteinjs/user';
 import { File } from './tables/FileTable';
 import { tables } from './tables/tables';
 import { FileStorageService, getFileStorageService } from './services/FileStorageService';
 import { FileStorageDriver } from './FileStorageDriver';
 import { getFileReachabilityResolvers } from './FileReachabilityResolver';
+import { FileCopyRefused, getFileCopyForOthers } from './FileCopyForOthers';
+import {
+  FILE_VARIANT_KINDS,
+  FileVariant,
+  FileVariantKind,
+  FileVariantNotMade,
+  getFileVariantMaker,
+} from './FileVariantMaker';
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { Logger } from '@proteinjs/logger';
+import { ServiceRefusal } from '@proteinjs/service';
 import { DbFileStorageDriver } from './DbFileStorageDriver';
 
 /**
@@ -29,12 +39,15 @@ export interface DefaultFileStorageDriverFactory extends Loadable {
  */
 export class FileStorage implements FileStorageService {
   private static driver: FileStorageDriver;
+  /** The read path's derivations running in this process, by file and kind — see {@link deriveOnce}. */
+  private static derivations = new Map<string, Promise<string | undefined>>();
 
   public serviceMetadata = {
     auth: {
       allUsers: true,
     },
   };
+  private logger = new Logger({ name: this.constructor.name });
 
   /**
    * The `FileStorageDriver` for this process — provided by the `DefaultFileStorageDriverFactory`
@@ -77,11 +90,16 @@ export class FileStorage implements FileStorageService {
    * Retrieves the metadata of a given file — THE file-read access decision every serving path
    * derives from (`/file/:id`, signed-URL minting, the browser service).
    *
-   * Two legs: the caller's own file resolves by the SCOPED read; when that misses, the
-   * shared-content leg asks the registered {@link FileReachabilityResolver}s whether the caller
-   * can read a row that REFERENCES the file (a shared thought's media node) — content access
-   * confers file access, through the content's own grant-filtered read, never by widening file
-   * scope. No resolver vouching means the miss stands. Reads only: writes/deletes stay scoped.
+   * Three legs, cheapest first: the caller's own file resolves by the SCOPED read. When that
+   * misses, the derived leg: a VARIANT the seam made (`File.variantOf`) is readable by whoever
+   * can read its original — this same decision, asked of the original — so a variant derived
+   * after the content was placed (no content row names it) is reachable by exactly the readers
+   * of the file it was made from; one system point read decides whether the row is a variant at
+   * all. Last, the shared-content leg asks the registered {@link FileReachabilityResolver}s
+   * whether the caller can read a row that REFERENCES the file (a shared thought's media node) —
+   * content access confers file access, through the content's own grant-filtered read, never by
+   * widening file scope. No leg vouching means the miss stands. Reads only: writes/deletes stay
+   * scoped.
    * @param fileId - The `id` of the file.
    * @returns The file metadata, or `undefined` when the caller can neither own nor reach it.
    */
@@ -92,15 +110,82 @@ export class FileStorage implements FileStorageService {
       return file;
     }
 
+    const row = await getScopedDbAsSystem().get(tables.File, { id: fileId });
+    if (!row) {
+      return undefined as unknown as File;
+    }
+    if (row.variantOf?._id) {
+      // A variant's reachability is its original's — the copy for others carries no `variantOf`,
+      // so its own id stays nobody's but the owner's.
+      return (await this.getFile(row.variantOf._id)) ? row : (undefined as unknown as File);
+    }
+
     for (const resolver of getFileReachabilityResolvers()) {
       if (await resolver.canReadViaReference(fileId)) {
         // Reachability established through the caller's grant-filtered content read — the row
         // itself lives in the owner's scope, so it is served via system read.
-        return await getScopedDbAsSystem().get(tables.File, { id: fileId });
+        return row;
       }
     }
 
-    return file;
+    return undefined as unknown as File;
+  }
+
+  /**
+   * The variant of this kind of a file — the derived File the row names, or one made now, ONCE,
+   * by the registered {@link FileVariantMaker} (the read path's door, behind
+   * `GET /file/:id/variant/:kind`: a file made before the seam existed, or by a producer that did
+   * not derive it, gets its variant on the first request from a surface that draws it; every
+   * later request is served the same row without the maker). Server-only, like `getSignedUrl` —
+   * the browser asks by URL, never by service call. Access is the original's ({@link getFile});
+   * the variant is stored as the owner's own File whoever's read made it, and is served like any
+   * File afterwards — with the same non-owner copy rule.
+   * @returns The variant's File row, or `undefined` when the caller cannot read the original, no
+   *          maker is registered, the maker does not apply to this file for this kind, or the
+   *          maker could not make it of these bytes (the consumer then draws the original).
+   */
+  async getVariant(fileId: string, kind: FileVariantKind): Promise<File | undefined> {
+    const file = await this.getFile(fileId);
+    if (!file) {
+      return undefined;
+    }
+    const named = file[kind]?._id;
+    if (named) {
+      return await getScopedDbAsSystem().get(tables.File, { id: named });
+    }
+    const maker = getFileVariantMaker();
+    if (!maker || !maker.appliesTo(file, kind)) {
+      return undefined;
+    }
+    const variantId = await this.deriveOnce(file, kind);
+    return variantId ? await getScopedDbAsSystem().get(tables.File, { id: variantId }) : undefined;
+  }
+
+  /**
+   * Make and store every variant the registered maker applies to, with the original's bytes in
+   * hand (the ingest's door — one decode of bytes just stored, never a re-read). Each is named on
+   * the row; a kind the maker does not apply to is left unset (the read path may derive it later
+   * if the maker's rule changes). With no maker registered nothing is made.
+   * @returns The caller's file row with each variant made here named on it (the row as the caller
+   *          holds it, not a re-read — an unset column stays unset), and the variant Files made.
+   */
+  async deriveVariants(
+    file: File,
+    bytes: Buffer
+  ): Promise<{ file: File; variants: Partial<Record<FileVariantKind, File>> }> {
+    const maker = getFileVariantMaker();
+    const variants: Partial<Record<FileVariantKind, File>> = {};
+    const named: Partial<Pick<File, FileVariantKind>> = {};
+    if (maker) {
+      for (const kind of FILE_VARIANT_KINDS) {
+        if (!file[kind]?._id && maker.appliesTo(file, kind)) {
+          const variantId = await this.makeVariant(file, kind, bytes);
+          variants[kind] = await getScopedDbAsSystem().get(tables.File, { id: variantId });
+          named[kind] = new Reference<File>(tables.File.name, variantId);
+        }
+      }
+    }
+    return { file: { ...file, ...named }, variants };
   }
 
   /**
@@ -111,37 +196,65 @@ export class FileStorage implements FileStorageService {
    * exactly as reachable as the row that names them. The gate lives here because this is the
    * browser-facing service boundary (`FileStorageService` is `allUsers`) and the driver byte ops
    * below are deliberately unscoped. Server-side doors that make their OWN documented access
-   * decision (the avatar route, issue/ticket attachment doors) read bytes through
-   * `FileStorage.getDriver()` instead.
+   * decision (an attachment door keyed by a record's linkage, say) serve through
+   * {@link getAuthorizedFileData} — the same owner-or-copy bytes, without this gate.
+   *
+   * WHICH bytes: the owner's read serves the original; anyone else's — a read that reached the
+   * file through the shared-content leg — serves the {@link FileCopyForOthers} copy
+   * ({@link servedFileId}): the same substitution `getSignedUrl` makes, so the proxy route, the
+   * signed-URL route and every server-side reader of this door agree.
    * @param fileId - The `id` of the file.
    * @returns The file data as a single string.
-   * @throws When the file row does not exist or is not readable by the caller — the same named
-   *         miss either way, so existence is not leaked to unauthorized callers.
+   * @throws ServiceRefusal (404, `File not found`) when the file row does not exist or is not
+   *         readable by the caller, and when the caller is not the owner and no copy can be made
+   *         ({@link servedFileId}) — ONE answer for all three ({@link notFound}), so no door tells
+   *         a missing file from one this caller may not have.
    */
   async getFileData(fileId: string): Promise<string> {
     const file = await this.getFile(fileId);
     if (!file) {
-      throw new Error(`File not found: ${fileId}`);
+      throw FileStorage.notFound();
     }
 
-    return await FileStorage.getDriver().getFileData(fileId);
+    return await FileStorage.getDriver().getFileData(await this.servedFileId(file));
+  }
+
+  /**
+   * The bytes THIS caller is served for a file a server-side door has ALREADY decided the caller
+   * may read, by its own documented rule (an attachment door keyed by a record's linkage, say —
+   * a read neither the caller's scope nor a {@link FileReachabilityResolver} would open). The
+   * door vouches for access; this decides WHICH bytes, exactly as {@link getFileData} does: the
+   * original for the file's owner, the {@link FileCopyForOthers} copy for anyone else — the same
+   * copy, made once and named on the row, that every other door serves them. Server-only (not
+   * part of the browser-facing `FileStorageService`), so the rule that opens the file stays the
+   * door's.
+   * @param file - The file's row, as the door read it (its `scope` names the owner).
+   * @returns The file data as a single string.
+   * @throws ServiceRefusal (404) when the caller is not the owner and no copy can be made — the same
+   *         refusal every door gives ({@link servedFileId}).
+   */
+  async getAuthorizedFileData(file: File): Promise<string> {
+    return await FileStorage.getDriver().getFileData(await this.servedFileId(file));
   }
 
   /**
    * Mint a short-lived, read-only URL for the file's bytes (server-only; not part of the
    * browser-facing `FileStorageService`). A signed URL is a bearer capability, so minting
    * verifies the caller can read the file row (the two-legged {@link getFile} read — own scope
-   * or shared-content reachability) before signing.
+   * or shared-content reachability) before signing — and signs the bytes THAT caller is served:
+   * the original for the owner, the {@link FileCopyForOthers} copy for anyone else.
    * @param fileId - The `id` of the file.
    * @param options.ttlMs - How long the URL stays valid; the driver applies its default when omitted.
    * @returns The signed URL, or `undefined` when the driver has no external URL space
    *          (`DbFileStorageDriver`) — the caller then serves bytes through the proxy route.
-   * @throws When the file row does not exist or is not readable by the caller.
+   * @throws ServiceRefusal (404, `File not found`) when the file row does not exist or is not
+   *         readable by the caller, and when the caller is not the owner and no copy can be made —
+   *         the one answer {@link getFileData} gives ({@link notFound}).
    */
   async getSignedUrl(fileId: string, options?: { ttlMs?: number }): Promise<string | undefined> {
     const file = await this.getFile(fileId);
     if (!file) {
-      throw new Error(`File not found: ${fileId}`);
+      throw FileStorage.notFound();
     }
 
     const driver = FileStorage.getDriver();
@@ -149,7 +262,7 @@ export class FileStorage implements FileStorageService {
       return undefined;
     }
 
-    return await driver.getSignedUrl(fileId, options);
+    return await driver.getSignedUrl(await this.servedFileId(file), options);
   }
 
   /**
@@ -159,6 +272,10 @@ export class FileStorage implements FileStorageService {
    * (the same authorization a scoped row update enforces). Deliberately STRICTER than
    * {@link getFileData}: the {@link FileReachabilityResolver} leg widens READS only, so a
    * share recipient who can read the bytes still cannot write them.
+   *
+   * New bytes make every derived File stale — the copy others were served, the preview, the
+   * stage variant: each is dropped here — the row forgets it, then its row (and, through the
+   * delete watcher, its bytes) goes — and the next read that wants one makes a fresh one.
    * @param fileId - The `id` of the file.
    * @param data - The new data string to replace the existing data.
    * @throws When the file row does not exist or is not writable by the caller — the same named
@@ -172,6 +289,7 @@ export class FileStorage implements FileStorageService {
     }
 
     await FileStorage.getDriver().updateFileData(fileId, data);
+    await this.dropDerivedFiles(file);
   }
 
   /**
@@ -199,4 +317,219 @@ export class FileStorage implements FileStorageService {
     const db = getScopedDb();
     await db.delete(tables.File, { id: fileId });
   }
+
+  /**
+   * The id whose bytes this caller is served: the file's own for its owner, or for a file with
+   * no maker (or one the maker does not apply to); otherwise the {@link FileCopyForOthers} copy —
+   * the one already named on the row, or made now, once, and named for every later read.
+   *
+   * ONE REFUSAL, EVERY DOOR: when no copy can be made (the seam's {@link FileCopyRefused}), the file
+   * is served to no one but its owner, so to this caller it is not there — a
+   * `ServiceRefusal(404, 'File not found')`, thrown here so the browser service, `GET /file/:id` in
+   * both its shapes and the server-side door answer the same by construction: the service router
+   * answers 404 `{ error: 'File not found' }`, the executor logs one WARN (a refusal, never a
+   * failure), the route answers `404 File not found` — the same answer, at every door, as a row the
+   * caller cannot read ({@link notFound}). The refusal carries no reason, file id or owner: the
+   * maker's reason is the server's, logged here in one WARN, so nothing a caller reads tells a
+   * refused copy from a file that is not there.
+   */
+  private async servedFileId(file: File): Promise<string> {
+    if (this.ownedByCaller(file)) {
+      return file.id;
+    }
+    if (file.copyForOthers?._id) {
+      return file.copyForOthers._id;
+    }
+    const maker = getFileCopyForOthers();
+    if (!maker || !maker.appliesTo(file)) {
+      return file.id;
+    }
+    try {
+      return await this.makeCopyForOthers(file);
+    } catch (error) {
+      if (FileCopyRefused.is(error)) {
+        this.logger.warn({
+          message: 'No copy of a file can be made for anyone but its owner; refused as not found',
+          obj: { fileId: error.fileId, reason: error.reason },
+        });
+        throw FileStorage.notFound();
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Whether the caller is the file's owner — the row's `scope` is the owner (the scoped read
+   * {@link getFile} makes first is exactly `scope = the caller`), so a row {@link getFile} handed
+   * back whose scope is someone else's was reached through the shared-content leg. A row with no
+   * owner recorded serves as itself: there is no one to withhold it from.
+   */
+  private ownedByCaller(file: File): boolean {
+    return !file.scope || file.scope === new UserRepo().getUser().id;
+  }
+
+  /**
+   * Makes the copy (the maker's bytes, from the original's), stores it as a File in the owner's
+   * scope and names it on the original's row. Two non-owners reading at once may both get here:
+   * the row's word wins — decided in ONE transaction (the read of the row and the write of its
+   * word together, so racing writers are serialized and the loser's transaction, retried, finds
+   * the winner named) — and a copy that lost is deleted after the commit, the first is served.
+   */
+  private async makeCopyForOthers(file: File): Promise<string> {
+    const maker = getFileCopyForOthers()!;
+    const driver = FileStorage.getDriver();
+    const original = Buffer.from(await driver.getFileData(file.id), 'base64');
+    let copyBytes: Buffer;
+    try {
+      copyBytes = await maker.make(file, original);
+    } catch (cause) {
+      // The maker's contract: a throw means no copy can be made — the file is the owner's alone.
+      throw new FileCopyRefused(file.id, cause);
+    }
+    // As system, in the OWNER's scope: the copy is the owner's file (their storage, their purge).
+    const system = getDbAsSystem();
+    const copy = await system.insert(tables.File, {
+      name: file.name,
+      type: file.type,
+      size: copyBytes.length,
+      ...(file.width !== undefined && file.width !== null ? { width: file.width } : {}),
+      ...(file.height !== undefined && file.height !== null ? { height: file.height } : {}),
+      ...(file.durationMs !== undefined && file.durationMs !== null ? { durationMs: file.durationMs } : {}),
+      scope: file.scope,
+    });
+    await driver.createFile(copy, copyBytes.toString('base64'));
+
+    const named = await system.runTransaction(async () => {
+      const current = await system.get(tables.File, { id: file.id });
+      if (current?.copyForOthers?._id) {
+        return current.copyForOthers._id;
+      }
+      await system.update(tables.File, { id: file.id, copyForOthers: new Reference<File>(tables.File.name, copy.id) });
+      return copy.id;
+    });
+    if (named !== copy.id) {
+      // Outside the transaction: the row's delete takes the bytes with it (the delete watcher), a
+      // side effect that must not ride a transaction the runner may retry.
+      await system.delete(tables.File, { id: copy.id });
+    }
+    return named;
+  }
+
+  /**
+   * The read path's derivation, ONCE per file and kind at a time in this process: the readers
+   * that ask for the same absent variant while one derives (a shared document opened by many on
+   * one tick — every face asks the same URL) wait for that derivation's answer instead of each
+   * reading the original, encoding it and storing an object the row's word would then discard.
+   * Across processes the row's word in one transaction ({@link makeVariant}) still decides: this
+   * bounds the cost, that bounds the outcome. A maker that cannot make the variant of these
+   * bytes (a picture its decoder cannot read) answers `undefined` — nothing is stored, the reader
+   * draws the file itself, the next reader asks again — said in the log, never as a failed read;
+   * any other failure (the store, the database) is the reader's as it would be for any File.
+   */
+  private deriveOnce(file: File, kind: FileVariantKind): Promise<string | undefined> {
+    const key = `${file.id}:${kind}`;
+    const running = FileStorage.derivations.get(key);
+    if (running) {
+      return running;
+    }
+    const derivation = (async () => {
+      const original = Buffer.from(await FileStorage.getDriver().getFileData(file.id), 'base64');
+      try {
+        return await this.makeVariant(file, kind, original);
+      } catch (error) {
+        if (!FileVariantNotMade.is(error)) {
+          throw error;
+        }
+        new Logger({ name: 'FileStorage' }).warn({
+          message: `No ${kind} variant could be made of file ${file.id}; the file itself is served`,
+          obj: { reason: error.reason },
+        });
+        return undefined;
+      }
+    })().finally(() => FileStorage.derivations.delete(key));
+    FileStorage.derivations.set(key, derivation);
+    return derivation;
+  }
+
+  /**
+   * Makes the variant (the maker's answer from the original's bytes), stores it as a File in the
+   * OWNER's scope naming its original, and names it on the original's row. Two readers may derive
+   * the same kind at once: the row's word wins — decided in ONE transaction, exactly as the copy
+   * for others is named — and the variant that lost is deleted after the commit. The maker's own
+   * failure (it could not make the variant of these bytes) is thrown as {@link FileVariantNotMade}
+   * with the maker's reason, so the doors can tell it from a failure of the store or the database;
+   * nothing is stored on it.
+   * @returns The id of the variant the row names.
+   */
+  private async makeVariant(file: File, kind: FileVariantKind, bytes: Buffer): Promise<string> {
+    const maker = getFileVariantMaker()!;
+    const driver = FileStorage.getDriver();
+    let made: FileVariant;
+    try {
+      made = await maker.make(file, bytes, kind);
+    } catch (cause) {
+      // The maker's contract: a throw means no variant can be made of these bytes.
+      throw new FileVariantNotMade(file.id, kind, cause);
+    }
+    // As system, in the OWNER's scope: the variant is the owner's file (their storage, their purge).
+    const system = getDbAsSystem();
+    const variant = await system.insert(tables.File, {
+      name: `(${kind}) ${file.name}`,
+      type: made.type,
+      size: made.bytes.length,
+      ...(made.width !== undefined ? { width: made.width } : {}),
+      ...(made.height !== undefined ? { height: made.height } : {}),
+      variantOf: new Reference<File>(tables.File.name, file.id),
+      scope: file.scope,
+    });
+    await driver.createFile(variant, made.bytes.toString('base64'));
+
+    const named = await system.runTransaction(async () => {
+      const current = await system.get(tables.File, { id: file.id });
+      if (current?.[kind]?._id) {
+        return current[kind]!._id!;
+      }
+      await system.update(tables.File, { id: file.id, [kind]: new Reference<File>(tables.File.name, variant.id) });
+      return variant.id;
+    });
+    if (named !== variant.id) {
+      // Outside the transaction: the row's delete takes the bytes with it (the delete watcher), a
+      // side effect that must not ride a transaction the runner may retry.
+      await system.delete(tables.File, { id: variant.id });
+    }
+    return named;
+  }
+
+  /**
+   * The row forgets each derived File first (nothing serves a copy or a variant the row no longer
+   * names), then their rows go — the bytes with them, through the delete watcher: the copy for
+   * others and every variant kind, one rule.
+   */
+  private async dropDerivedFiles(file: File): Promise<void> {
+    const seats: Array<'copyForOthers' | FileVariantKind> = ['copyForOthers', ...FILE_VARIANT_KINDS];
+    const stale = seats.filter((seat) => !!file[seat]?._id);
+    if (stale.length === 0) {
+      return;
+    }
+    const system = getDbAsSystem();
+    const forgotten: Partial<File> & { id: string } = { id: file.id };
+    for (const seat of stale) {
+      forgotten[seat] = null;
+    }
+    await system.update(tables.File, forgotten);
+    for (const seat of stale) {
+      await system.delete(tables.File, { id: file[seat]!._id! });
+    }
+  }
+
+  /**
+   * THE answer a byte door gives a caller who does not get the file's bytes — a row that is not
+   * there, one this caller cannot read, or a copy that cannot be made for them: a 404 refusal in
+   * the same words every time, never the id, so the answer reveals nothing about existence (the
+   * service router sends `{ error: 'File not found' }`, the executor logs it at WARN, the routes
+   * send `404 File not found`).
+   */
+  private static notFound(): ServiceRefusal {
+    return new ServiceRefusal(404, 'File not found');
+  }
 }

package/src/FileStorageDriver.ts

@@ -1,4 +1,5 @@
 import { File } from './tables/FileTable';
+import type { FileStorageError } from './FileStorageError';
 
 /**
  * Byte store behind `FileStorage`.
@@ -7,6 +8,17 @@ import { File } from './tables/FileTable';
  * file's true bytes — for text and binary files alike. Drivers own their at-rest representation,
  * with one hard requirement: a driver that serves blobs directly to clients (`getSignedUrl`)
  * MUST store the true bytes at rest, because clients read its objects without any decode step.
+ *
+ * Error contract: a failed byte operation throws a {@link FileStorageError} — a code, a plain
+ * message and the store's HTTP status where it has one — and NEVER the store client's own error
+ * object or anything hanging off one (a request config, a request, a response, headers, a signed
+ * URL): a client's error holds the request it made, and that request holds the driver's
+ * credentials, so an application logging what it caught would write a live credential. Bytes that
+ * are not there are reported as the `not-found` code on every read and overwrite, so callers
+ * branch on one thing whichever driver is behind them (`deleteFile` alone treats missing bytes as
+ * success — see its contract). A driver whose store IS the application's database
+ * (`DbFileStorageDriver`) lets the database layer's own errors through unchanged: they are
+ * already that layer's owned errors, and a transaction runner must see them to retry.
  */
 export interface FileStorageDriver {
   createFile(file: File, fileData: string): Promise<void>;

package/src/FileStorageError.ts

@@ -0,0 +1,123 @@
+/**
+ * Why a byte operation failed — the closed set a caller branches on.
+ *
+ * - `not-found`: the stored bytes for that file id are not there.
+ * - `precondition-failed`: the store refused a conditional write (the object changed underneath it).
+ * - `forbidden`: the store refused the driver's credentials or permissions.
+ * - `unavailable`: the store could not be reached or asked to be retried later.
+ * - `unknown`: anything else.
+ */
+export type FileStorageErrorCode = 'not-found' | 'precondition-failed' | 'forbidden' | 'unavailable' | 'unknown';
+
+/**
+ * THE error a {@link FileStorageDriver} throws — the only thing that leaves a driver when a byte
+ * operation fails.
+ *
+ * It carries three plain facts and nothing else: a {@link FileStorageErrorCode}, a one-line
+ * message, and the HTTP status where the store speaks HTTP. It NEVER carries the store client's own
+ * error object, nor anything hanging off one — a request config, a request, a response, headers, a
+ * signed URL. A store client's error routinely holds the request it made, and that request holds
+ * the driver's credentials (an `Authorization` header); an application that logs the error it
+ * caught would write a live credential into its logs. The driver is the only party that talks to
+ * the store, so the driver owns what its errors carry, and no caller has to know to strip one.
+ *
+ * Callers branch on `code` — through {@link FileStorageError.is} / {@link FileStorageError.isNotFound},
+ * which read the error's shape rather than its prototype, so they hold across duplicate copies of
+ * this package in one process.
+ */
+export class FileStorageError extends Error {
+  private static readonly NAME = 'FileStorageError';
+  private static readonly CODES: FileStorageErrorCode[] = [
+    'not-found',
+    'precondition-failed',
+    'forbidden',
+    'unavailable',
+    'unknown',
+  ];
+  /** Free text that reaches a message is one line and bounded. */
+  private static readonly MAX_DETAIL_CHARS = 300;
+
+  readonly code: FileStorageErrorCode;
+  /** The store's HTTP status, where it has one. */
+  readonly status?: number;
+
+  /**
+   * @param code what went wrong, for callers to branch on
+   * @param summary the driver's own words for the failed operation (e.g. `getFileData failed for file <id>`)
+   * @param options.status the store's HTTP status, where it has one
+   * @param options.detail the store's own message text — made plain (see {@link plain}) before it is kept
+   */
+  constructor(code: FileStorageErrorCode, summary: string, options?: { status?: number; detail?: unknown }) {
+    super(FileStorageError.describe(code, summary, options));
+    this.name = FileStorageError.NAME;
+    Object.setPrototypeOf(this, FileStorageError.prototype);
+    this.code = code;
+    if (options?.status !== undefined) {
+      this.status = options.status;
+    }
+  }
+
+  /** Is this a driver's error? Read by shape, so it holds across duplicate copies of this package. */
+  static is(error: unknown): error is FileStorageError {
+    const candidate = error as { name?: unknown; code?: unknown } | null | undefined;
+    return (
+      candidate?.name === FileStorageError.NAME &&
+      FileStorageError.CODES.includes(candidate.code as FileStorageErrorCode)
+    );
+  }
+
+  /** The stored bytes for that file id are not there. */
+  static isNotFound(error: unknown): boolean {
+    return FileStorageError.is(error) && error.code === 'not-found';
+  }
+
+  /**
+   * The code an HTTP status means. Drivers whose store speaks HTTP share this table so one status
+   * never reads two ways.
+   */
+  static codeForStatus(status: number | undefined): FileStorageErrorCode {
+    if (status === 404) {
+      return 'not-found';
+    }
+    if (status === 412) {
+      return 'precondition-failed';
+    }
+    if (status === 401 || status === 403) {
+      return 'forbidden';
+    }
+    if (status === 408 || status === 429 || (status !== undefined && status >= 500 && status <= 599)) {
+      return 'unavailable';
+    }
+    return 'unknown';
+  }
+
+  private static describe(
+    code: FileStorageErrorCode,
+    summary: string,
+    options?: { status?: number; detail?: unknown }
+  ): string {
+    const status = options?.status !== undefined ? ` (HTTP ${options.status})` : '';
+    const detail = FileStorageError.plain(options?.detail);
+    return `${summary}: ${code}${status}${detail ? ` — ${detail}` : ''}`;
+  }
+
+  /**
+   * A store's message text made safe to keep: text only (an object is never read into it), one
+   * line, bounded, with every URL's query string dropped (a signed URL's signature lives there)
+   * and any bearer credential masked.
+   */
+  private static plain(detail: unknown): string {
+    if (typeof detail !== 'string') {
+      return '';
+    }
+
+    const oneLine = detail
+      .replace(/\s+/g, ' ')
+      .replace(/(https?:\/\/[^\s?#]+)[?#]\S*/gi, '$1')
+      .replace(/\b(bearer|basic)\s+\S+/gi, '$1 [masked]')
+      .trim();
+    return oneLine.length > FileStorageError.MAX_DETAIL_CHARS
+      ? `${oneLine.slice(0, FileStorageError.MAX_DETAIL_CHARS)}…`
+      : oneLine;
+  }
+}