@_linked/server 2.3.1 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @\_linked/server
 
+## 2.5.0
+
+### Minor Changes
+
+- [#44](https://github.com/linked-fw/server/pull/44) [`616f019`](https://github.com/linked-fw/server/commit/616f0195e0c263ccb6240d65c9c94435319649a0) Thanks [@flyon](https://github.com/flyon)! - Fix `LocalFileStore.saveFile`: preserve the key, honour `basePath`, and report where the file landed.
+
+  `saveFile` went through `getUploadTarget`, which lowercases the name and always resolves against the server's upload
+  folder. Two consequences: a key whose case matters (a Vite content hash such as `main-hwqwrAvA.css`) was corrupted, and
+  a store built with a custom `basePath` wrote to the upload folder while `getFile`, `fileExists`, `deleteFile` and
+  `statFile` all read from `basePath` — so it could never read back what it wrote.
+
+  `saveFile` now resolves the target against the store's own `basePath`, like every other method, and keeps the name's
+  case. Unsafe characters are still replaced and a missing extension is still added from `mimeType`; lowercasing stays
+  where it belongs, in `@_linked/server-utils`' upload handling, which already sanitises a browser-supplied filename
+  before any store sees it.
+
+  New `saveFileWithPath()` returns `{storedPath, publicURL}`, so a caller can hand `storedPath` straight to
+  `statFile`/`getFile`. With `preventDuplicates: false` that path equals the path given, verbatim.
+
+  Minor rather than patch because behaviour changes for existing callers in two ways:
+
+  - a name containing uppercase characters is now stored with its case intact instead of lowercased. Callers that pass an
+    already-lowercased name (which is what the HTTP upload path does) are unaffected.
+  - a store constructed with a custom `basePath` now writes into that folder instead of `./data/uploads`.
+
+  Unchanged: the default `basePath`, the suffixing default when `preventDuplicates` is unspecified, the returned URL, and
+  the two-argument `LinkedFileStorage.saveFile(path, buffer)` path.
+
+## 2.4.0
+
+### Minor Changes
+
+- [#38](https://github.com/linked-fw/server/pull/38) [`bf1e83c`](https://github.com/linked-fw/server/commit/bf1e83cdfc949baec88a645c2750479bc33f1637) Thanks [@flyon](https://github.com/flyon)! - `LocalFileStore` accepts the new `SaveFileOptions` third argument of `saveFile`
+  (still accepting a positional mime-type string) and gains `statFile()`, which
+  returns the size and a sha256 of a stored file, or `null` when it does not
+  exist, for verify-after-upload. A local file has no headers, so `cacheControl`
+  and `metadata` are accepted and ignored.
+
+  Core reports an unspecified `preventDuplicates` as `undefined` and applies no
+  default of its own, so this store keeps applying its own: a caller that says
+  nothing still gets the random file-name suffix, and only an explicit
+  `preventDuplicates: false` overwrites an existing name.
+
 ## 2.3.1
 
 ### Patch Changes

package/lib/esm/backend.js

@@ -7,8 +7,8 @@ import fs from 'fs/promises';
 export * from './shapes/quadstores/BackendAPIStoreProvider.js';
 export default class LincdServerBackendProvider extends BackendProvider {
     async setupBeforeControllers() {
-        if (!LinkedFileStorage.getDefaultDataset()) {
-            LinkedFileStorage.setDefaultDataset(new LocalFileStore(process.env.NODE_ENV + '-filestore'));
+        if (!LinkedFileStorage.getDefaultStore()) {
+            LinkedFileStorage.setDefaultStore(new LocalFileStore(process.env.NODE_ENV + '-filestore'));
         }
         let fileSystemUploadPath = path.join('data', 'filestores');
         try {

package/lib/esm/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,aAAa,CAAC;AAE7B,cAAc,gDAAgD,CAAC;AAE/D,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,eAAe;IACrE,KAAK,CAAC,sBAAsB;QAC1B,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,EAAE,CAAC;YAC3C,iBAAiB,CAAC,iBAAiB,CACjC,IAAI,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAC,CACxD,CAAC;QACJ,CAAC;QACD,IAAI,oBAAoB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,YAAY,CAAC,EAAE;gBAC5D,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,SAAS;QACP,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,aAAa,CAAC;AAE7B,cAAc,gDAAgD,CAAC;AAE/D,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,eAAe;IACrE,KAAK,CAAC,sBAAsB;QAC1B,IAAI,CAAC,iBAAiB,CAAC,eAAe,EAAE,EAAE,CAAC;YACzC,iBAAiB,CAAC,eAAe,CAC/B,IAAI,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAC,CACxD,CAAC;QACJ,CAAC;QACD,IAAI,oBAAoB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,YAAY,CAAC,EAAE;gBAC5D,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,SAAS;QACP,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;CACF"}

package/lib/esm/shapes/filestores/LocalFileStore.d.ts

@@ -1,5 +1,19 @@
-import { IFileStore } from '@_linked/core/interfaces/IFileStore';
+import { FileStat, IFileStore, SaveFileOptions } from '@_linked/core/interfaces/IFileStore';
 import { Shape } from '@_linked/core/shapes/Shape';
+/**
+ * What `saveFile` stored, and where.
+ *
+ * `storedPath` is the key as it ended up in the store: it is exactly what
+ * `getFile`, `fileExists`, `deleteFile` and `statFile` expect, so a caller that
+ * wants to verify what it just uploaded never has to guess a name back out of a
+ * URL.
+ */
+export interface SavedFileLocation {
+    /** The key the file is stored under, relative to the store's base folder. */
+    storedPath: string;
+    /** The public URL, the same string `saveFile` returns. */
+    publicURL: string;
+}
 export declare class LocalFileStore extends Shape implements IFileStore {
     private readonly basePath;
     readonly accessURL: string;
@@ -32,11 +46,65 @@ export declare class LocalFileStore extends Shape implements IFileStore {
      * @todo Take a path parameter to list files in a subdirectory
      */
     listFiles(prefix?: string): Promise<string[]>;
+    /**
+     * Work out the key a save will use, and the URL that key is served under.
+     *
+     * This used to be `getUploadTarget` from `@_linked/server-utils`, which could
+     * not be used here for two reasons:
+     *
+     * - it lowercases the name. That is HTTP-upload hygiene (browsers hand over
+     *   whatever the user's filesystem had, and `getUploadTarget` is still the
+     *   right place for it — `uploadSingleFileFromFormData` calls it before it
+     *   ever reaches a store), but it corrupts a key a program chose on purpose,
+     *   such as a Vite content hash: `main-hwqwrAvA.css`.
+     * - it always resolves against `relativeFileSystemUploadPath`, ignoring this
+     *   store's `basePath`, so a store with a custom base folder wrote where it
+     *   could not read back.
+     *
+     * Characters that are not safe in a file name are still replaced, exactly as
+     * `getUploadTarget` does it — only the case is left alone.
+     */
+    private resolveTarget;
     /**
      * Save a file to the local filesystem
-     * @param filePath The path to save the file to, relative to the base upload folder
+     * @param filePath The path to save the file to, relative to the base folder
      * @param fileContent The contents of the file as a buffer
-     * @returns A promise that resolves to the public URL of the file
+     * @param options Save options, or a string read as the old positional mimeType.
+     *   A local file has no headers to attach, so only `mimeType` (used to add a
+     *   missing extension) and `preventDuplicates` mean anything here;
+     *   `cacheControl` and `metadata` are accepted and ignored.
+     * @param preventDuplicates Only honoured when `options` is a string
+     * @returns A promise that resolves to the public URL of the file. Use
+     *   {@link saveFileWithPath} when you also need the key it was stored under.
+     */
+    saveFile(filePath: string, fileContent: Buffer, options?: SaveFileOptions | string, preventDuplicates?: boolean): Promise<string>;
+    /**
+     * Save a file and report both the key it was stored under and its URL.
+     *
+     * `saveFile` can only return one string, and `IFileStore` says that string is
+     * a URL — but a caller that wants to verify what it just wrote needs the
+     * *key*, which is what `statFile`, `getFile`, `fileExists` and `deleteFile`
+     * take. That is what `storedPath` is: hand it straight back to any of them.
+     *
+     * The key equals the `filePath` given verbatim — case included — as long as
+     * the name needs no sanitising, already has an extension, and
+     * `preventDuplicates` is `false`. With `preventDuplicates` left unspecified
+     * (this store's default, kept for upload callers) a random suffix is added,
+     * and `storedPath` is the only place that name is reported.
+     */
+    saveFileWithPath(filePath: string, fileContent: Buffer, options?: SaveFileOptions | string, preventDuplicates?: boolean): Promise<SavedFileLocation>;
+    /**
+     * Read back the metadata of a stored file, for verify-after-upload.
+     *
+     * The path is resolved exactly like saveFile/getFile/fileExists/deleteFile
+     * do, against this store's base folder, so the `storedPath` that
+     * saveFileWithPath reports can be handed straight back here.
+     *
+     * The sha256 is computed on demand from the bytes: statFile is only called
+     * during publish verification, not on every upload.
+     *
+     * @param filePath The path to the file, relative to the base upload folder
+     * @returns The size and sha256 of the file, or null if it does not exist
      */
-    saveFile(filePath: string, fileContent: Buffer, mimeType?: string): Promise<string>;
+    statFile(filePath: string): Promise<FileStat | null>;
 }

package/lib/esm/shapes/filestores/LocalFileStore.js

@@ -1,5 +1,8 @@
-import { relativeFileSystemUploadPath, getUploadTarget, } from '@_linked/server-utils/utils/Upload';
+import { relativeFileSystemUploadPath } from '@_linked/server-utils/utils/Upload';
+import { publicUploadPath } from '@_linked/server-utils/utils/ServerPaths';
+import { normalizeSaveFileOptions, } from '@_linked/core/interfaces/IFileStore';
 import { Shape } from '@_linked/core/shapes/Shape';
+import { createHash } from 'node:crypto';
 import * as fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -74,20 +77,125 @@ export class LocalFileStore extends Shape {
         }));
         return allFiles.flat();
     }
+    /**
+     * Work out the key a save will use, and the URL that key is served under.
+     *
+     * This used to be `getUploadTarget` from `@_linked/server-utils`, which could
+     * not be used here for two reasons:
+     *
+     * - it lowercases the name. That is HTTP-upload hygiene (browsers hand over
+     *   whatever the user's filesystem had, and `getUploadTarget` is still the
+     *   right place for it — `uploadSingleFileFromFormData` calls it before it
+     *   ever reaches a store), but it corrupts a key a program chose on purpose,
+     *   such as a Vite content hash: `main-hwqwrAvA.css`.
+     * - it always resolves against `relativeFileSystemUploadPath`, ignoring this
+     *   store's `basePath`, so a store with a custom base folder wrote where it
+     *   could not read back.
+     *
+     * Characters that are not safe in a file name are still replaced, exactly as
+     * `getUploadTarget` does it — only the case is left alone.
+     */
+    resolveTarget(filePath, mimeType, suffixDuplicates) {
+        // same character class as getUploadTarget: alphanumerics, dot, underscore
+        // and the path separator survive, a run of anything else becomes one dash.
+        // Case is deliberately preserved.
+        let sanitisedName = filePath.replace(/[^A-Za-z0-9\._\/]+/gi, '-');
+        if (sanitisedName.indexOf('.') === -1) {
+            //auto add an extension if none is present, based on the mimetype
+            if (!mimeType) {
+                throw new Error('This file does not have an extension and no mimetype was provided');
+            }
+            sanitisedName = sanitisedName + '.' + mimeType.split('/')[1];
+        }
+        const ext = sanitisedName.split('.').pop();
+        const withoutExt = sanitisedName.substring(0, sanitisedName.length - (ext.length + 1));
+        // 6 character random string to avoid clobbering an existing file,
+        // e.g. report.pdf -> report_312acb.pdf
+        const randomStringSuffix = suffixDuplicates
+            ? '_' + Math.random().toString(36).substring(2, 8)
+            : '';
+        const storedPath = withoutExt + randomStringSuffix + '.' + ext;
+        return {
+            storedPath,
+            publicURL: this.accessURL + publicUploadPath + '/' + storedPath,
+        };
+    }
     /**
      * Save a file to the local filesystem
-     * @param filePath The path to save the file to, relative to the base upload folder
+     * @param filePath The path to save the file to, relative to the base folder
      * @param fileContent The contents of the file as a buffer
-     * @returns A promise that resolves to the public URL of the file
+     * @param options Save options, or a string read as the old positional mimeType.
+     *   A local file has no headers to attach, so only `mimeType` (used to add a
+     *   missing extension) and `preventDuplicates` mean anything here;
+     *   `cacheControl` and `metadata` are accepted and ignored.
+     * @param preventDuplicates Only honoured when `options` is a string
+     * @returns A promise that resolves to the public URL of the file. Use
+     *   {@link saveFileWithPath} when you also need the key it was stored under.
+     */
+    async saveFile(filePath, fileContent, options, preventDuplicates) {
+        const { publicURL } = await this.saveFileWithPath(filePath, fileContent, options, preventDuplicates);
+        return publicURL;
+    }
+    /**
+     * Save a file and report both the key it was stored under and its URL.
+     *
+     * `saveFile` can only return one string, and `IFileStore` says that string is
+     * a URL — but a caller that wants to verify what it just wrote needs the
+     * *key*, which is what `statFile`, `getFile`, `fileExists` and `deleteFile`
+     * take. That is what `storedPath` is: hand it straight back to any of them.
+     *
+     * The key equals the `filePath` given verbatim — case included — as long as
+     * the name needs no sanitising, already has an extension, and
+     * `preventDuplicates` is `false`. With `preventDuplicates` left unspecified
+     * (this store's default, kept for upload callers) a random suffix is added,
+     * and `storedPath` is the only place that name is reported.
      */
-    async saveFile(filePath, fileContent, mimeType) {
-        const { publicURL, targetFilePath } = getUploadTarget(filePath, mimeType, null, '', this.accessURL);
+    async saveFileWithPath(filePath, fileContent, options, preventDuplicates) {
+        var _a;
+        const normalized = normalizeSaveFileOptions(options, preventDuplicates);
+        // Core reports an unspecified preventDuplicates as undefined, leaving the
+        // default to each store. This one has always appended a random suffix, so
+        // only an explicit `false` turns that off.
+        const suffixDuplicates = (_a = normalized.preventDuplicates) !== null && _a !== void 0 ? _a : true;
+        const target = this.resolveTarget(filePath, normalized.mimeType, suffixDuplicates);
+        // resolved against basePath, exactly like every read method does, so what
+        // is written here can be read back by the same key
+        const targetFilePath = path.join(this.basePath, target.storedPath);
         //make sure the target folder exists
         if (!fsSync.existsSync(path.dirname(targetFilePath))) {
             fsSync.mkdirSync(path.dirname(targetFilePath), { recursive: true });
         }
         await fs.writeFile(targetFilePath, fileContent);
-        return publicURL;
+        return target;
+    }
+    /**
+     * Read back the metadata of a stored file, for verify-after-upload.
+     *
+     * The path is resolved exactly like saveFile/getFile/fileExists/deleteFile
+     * do, against this store's base folder, so the `storedPath` that
+     * saveFileWithPath reports can be handed straight back here.
+     *
+     * The sha256 is computed on demand from the bytes: statFile is only called
+     * during publish verification, not on every upload.
+     *
+     * @param filePath The path to the file, relative to the base upload folder
+     * @returns The size and sha256 of the file, or null if it does not exist
+     */
+    async statFile(filePath) {
+        const fileToStat = path.join(this.basePath, filePath);
+        let stat;
+        try {
+            stat = await fs.stat(fileToStat);
+        }
+        catch (err) {
+            return null;
+        }
+        if (!stat.isFile()) {
+            return null;
+        }
+        const contents = await fs.readFile(fileToStat);
+        const sha256 = createHash('sha256').update(contents).digest('hex');
+        return { size: stat.size, sha256 };
     }
 }
 //# sourceMappingURL=LocalFileStore.js.map

package/lib/esm/shapes/filestores/LocalFileStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"LocalFileStore.js","sourceRoot":"","sources":["../../../../src/shapes/filestores/LocalFileStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LocalFileStore.js","sourceRoot":"","sources":["../../../../src/shapes/filestores/LocalFileStore.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/linked-fw/server.git"
   },
-  "version": "2.3.1",
+  "version": "2.5.0",
   "linkedPackage": true,
   "type": "module",
   "main": "lib/esm/index.js",
@@ -35,7 +35,7 @@
   ],
   "dependencies": {
     "@_linked/cli": "^1.2",
-    "@_linked/core": "^2.18.1",
+    "@_linked/core": "^2.20.0",
     "@_linked/server-utils": "^1.2.0",
     "adm-zip": "^0.5.16",
     "archiver": "^7.0.1",

package/readme.md

@@ -319,8 +319,8 @@ shape.
 
 ### LocalFileStore
 
-This is the default file store for LINCD. It is a simple file store that stores files in a local directory. Its usage
-follows the general pattern of other file stores in LINCD:
+An `IFileStore` that stores files in a local directory. Its usage follows the general pattern of other file stores in
+LINCD:
 
 - Define all storage locations when the server or application starts up
 - Access methods of the file store through the `LinkedFileStorage` class
@@ -330,15 +330,99 @@ It's important to note that this file store is not suitable for frontend usage -
 environment that has access to the [`fs` module](https://nodejs.org/api/fs.html).
 
 ```ts
-import { LinkedFileStorage } from '@_linked/core/lib/utils/LinkedFileStorage';
-import { LocalFileStore } from 'lincd-server/lib/shapes/LocalFileStore';
+import { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';
+import { LocalFileStore } from '@_linked/server/shapes/filestores/LocalFileStore';
 import path from 'path';
 
+// the second argument is the base folder on disk; it defaults to the server's
+// upload folder (`./data/uploads`, relative to the working directory)
 const pathToStore = path.join(process.cwd(), 'my-file-store');
 const store = new LocalFileStore('my-file-store', pathToStore);
 LinkedFileStorage.setDefaultStore(store);
 ```
 
+`accessURL` comes from `SITE_ROOT`, and every path you pass to `saveFile`, `getFile`, `fileExists`, `deleteFile` and
+`statFile` is relative to that base folder. Note that the URL `saveFile` returns is only meaningful when the base folder
+is the server's own upload folder — that is the only folder the server serves.
+
+Registering stores per purpose (`LinkedFileStorage.setStore`, `getStore`, `registerPurpose`) is core's concern — see
+[`@_linked/core`](https://github.com/linked-cm/core), `utils/LinkedFileStorage` and `interfaces/IFileStore`.
+
+#### Saving files
+
+`saveFile` takes core's `SaveFileOptions` as its third argument:
+
+```ts
+await store.saveFile('report.pdf', fileBuffer, {
+  mimeType: 'application/pdf',
+  preventDuplicates: true,
+});
+```
+
+A local file has no headers to attach, so only two of the options do anything here:
+
+- `mimeType` — used to add a missing file extension.
+- `preventDuplicates` — see below.
+- `cacheControl` and `metadata` are accepted (so the same call works against an S3-backed store) and ignored.
+
+The old positional form still works: a plain string third argument is read as the mime type, with `preventDuplicates`
+following it.
+
+```ts
+await store.saveFile('report.pdf', fileBuffer, 'application/pdf', true);
+```
+
+##### The key you pass is the key that is stored
+
+Characters that are unsafe in a file name are still replaced with a dash, and a missing extension is still added from
+`mimeType`, but the **case of the name is preserved**. A build asset named `main-hwqwrAvA.css` is stored under exactly
+that name. (Lowercasing belongs to HTTP upload handling, where a browser hands over whatever the user's filesystem had —
+`getUploadTarget`/`uploadSingleFileFromFormData` in `@_linked/server-utils` still do it there, before a store is ever
+called.)
+
+##### Getting the stored key back: `saveFileWithPath`
+
+`saveFile` returns a URL, but `statFile`, `getFile`, `fileExists` and `deleteFile` take a *key*. `saveFileWithPath`
+returns both, so verify-after-upload never has to guess a name back out of a URL:
+
+```ts
+const { storedPath, publicURL } = await store.saveFileWithPath(
+  'main-hwqwrAvA.css',
+  fileBuffer,
+  { mimeType: 'text/css', preventDuplicates: false }
+);
+
+const stat = await store.statFile(storedPath); // always resolves
+```
+
+With `preventDuplicates: false`, `storedPath` equals the path you passed, verbatim, as long as it needs no sanitising
+and already has an extension. With `preventDuplicates` left unspecified the random suffix is added and `storedPath` is
+the only place the resulting name is reported.
+
+##### LocalFileStore suffixes by default
+
+`preventDuplicates` left unspecified means `true` **here**. A second save of the same name does **not** overwrite the
+first: the store appends a random suffix, so `report.pdf` becomes `report_a1b2c3.pdf`. Only an explicit `false`
+overwrites.
+
+Core supplies no default of its own — an unspecified `preventDuplicates` reaches the store as `undefined` and each store
+decides. Do not assume this store's choice holds elsewhere: `S3FileStore` in `@_linked/s3` overwrites by default.
+
+#### Reading file metadata
+
+`statFile(filePath)` returns `{size, sha256}` for a stored file, or `null` when it does not exist (or is not a regular
+file). The `sha256` is a hex digest computed from the file's bytes on demand, so a caller can verify an upload it just
+made:
+
+```ts
+const stat = await store.statFile('report.pdf');
+if (stat === null) throw new Error('upload went missing');
+if (stat.sha256 !== expectedSha256) throw new Error('content mismatch');
+```
+
+`statFile` is optional on `IFileStore`, so a caller holding an `IFileStore` rather than a `LocalFileStore` must check
+that it exists before calling it.
+
 ## TODO
 
 - [ ] Add tests