sliftutils 1.4.3 → 1.4.4

package/bin/filehoster.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+require("typenode");
+require("../storage/remoteFileServer").runFileHoster();

package/index.d.ts

@@ -849,6 +849,20 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabase2" {
         getColumnInfo(): Promise<BulkColumnInfo[]>;
         /** A cheap snapshot of the collection's shape (row/key counts, total bytes, columns) — no row data. */
         getReaderInfo(): Promise<BulkReaderInfo>;
+        /**
+         * Per-file breakdown of the on-disk files, read fresh from disk each call (latest sizes, including
+         * stream files still being appended). `bytes` is the actual on-disk size. Good for showing collection
+         * size/fragmentation and deciding whether to call tryMergeNow()/compact().
+         */
+        getFileInfo(): Promise<{
+            files: {
+                name: string;
+                type: "bulk" | "stream";
+                bytes: number;
+            }[];
+            count: number;
+            totalBytes: number;
+        }>;
         /** Consolidate on-disk files. Optional to call; the database also does this in the background. */
         compact(): Promise<void>;
         /**
@@ -1010,6 +1024,15 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabaseBase" {
                 byteSize: number;
             }[];
         }>;
+        getFileInfo(): Promise<{
+            files: {
+                name: string;
+                type: "bulk" | "stream";
+                bytes: number;
+            }[];
+            count: number;
+            totalBytes: number;
+        }>;
     }
 
 }
@@ -1817,6 +1840,68 @@ declare module "sliftutils/storage/fileSystemPointer" {
 
 }
 
+declare module "sliftutils/storage/remoteFileServer" {
+    export declare function generatePassword(wordCount: number): string;
+    export type RemoteFileServerOptions = {
+        root: string;
+        port?: number;
+        host?: string;
+        password?: string;
+        logAccess?: boolean;
+    };
+    export type RemoteFileServerHandle = {
+        port: number;
+        password: string;
+        url: string;
+        close: () => Promise<void>;
+    };
+    export declare function startRemoteFileServer(options: RemoteFileServerOptions): Promise<RemoteFileServerHandle>;
+    export declare function runFileHoster(): Promise<void>;
+
+}
+
+declare module "sliftutils/storage/remoteFileStorage" {
+    /// <reference types="node" />
+    /// <reference types="node" />
+    /// <reference types="node" />
+    import https from "https";
+    import type { FileStorage } from "./FileFolderAPI";
+    export type RemoteFileStorageOptions = {
+        chunkBytes?: number;
+        cacheBytes?: number;
+        latencyMs?: number;
+    };
+    type Connection = {
+        url: string;
+        password: string;
+        latencyMs: number;
+        agent: https.Agent | undefined;
+        cache: RangeCache;
+        stats: {
+            requestCount: number;
+            bytesFetched: number;
+        };
+    };
+    declare class RangeCache {
+        private chunkBytes;
+        private budget;
+        private chunks;
+        private bytes;
+        constructor(chunkBytes: number, budget: number);
+        private key;
+        private peek;
+        private store;
+        invalidate(path: string): void;
+        getRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined>;
+    }
+    export type RemoteStorageFactory = ((path: string) => Promise<FileStorage>) & {
+        stats: Connection["stats"];
+    };
+    export declare function getRemoteFileStorage(url: string, password: string, options?: RemoteFileStorageOptions): RemoteStorageFactory;
+    export {};
+
+}
+
 declare module "sliftutils/storage/storage" {
 
 

package/package.json

@@ -1,70 +1,72 @@
-{
-    "name": "sliftutils",
-    "version": "1.4.3",
-    "main": "index.js",
-    "license": "MIT",
-    "files": [
-        "**/*",
-        ".gitignore"
-    ],
-    "scripts": {
-        "type": "yarn tsc --noEmit",
-        "emit-dts": "yarn tsc --project tsconfig.declarations.json || true",
-        "generate-index-dts": "typenode ./builders/generateIndexDts.ts",
-        "update-types": "yarn emit-dts && yarn generate-index-dts",
-        "prepublishOnly": "yarn update-types",
-        "run-nodejs": "node ./build-nodejs/server.js",
-        "run-nodejs-dev": "typenode ./nodejs/server.ts --npminstall",
-        "run-web": "node ./builders/webRun.js",
-        "run-electron": "node ./node_modules/electron/cli.js ./build-electron/electronMain.js",
-        "build-nodejs": "node ./builders/nodeJSBuildRun.js",
-        "build-web": "node ./builders/webBuildRun.js",
-        "build-extension": "node ./builders/extensionBuildRun.js",
-        "build-electron": "node ./builders/electronBuildRun.js",
-        "watch-nodejs": "node ./builders/watchRun.js --port 9876 \"nodejs/*.ts\" \"nodejs/*.tsx\" \"yarn build-nodejs\"",
-        "watch-web": "node ./builders/watchRun.js --port 9877 \"web/*.ts\" \"web/*.tsx\" \"yarn build-web\"",
-        "watch-extension": "node ./builders/watchRun.js --port 9878 \"extension/*.ts\" \"extension/*.tsx\" \"yarn build-extension\"",
-        "watch-electron": "node ./builders/watchRun.js --port 9879 \"electron/*.ts\" \"electron/*.tsx\" \"yarn build-electron\"",
-        "notes": "mobx, preact, socket-function, typenode SHOULD be peerDependencies. But we want to use yarn (better dependency deduplication), so we can't use peerDependencies (as they aren't installed by default, which makes them a nightmare to use). If you want to override the versions, feel free to use overrides/resolutions.",
-        "test": "typenode ./test.ts"
-    },
-    "bin": {
-        "build-nodejs": "./builders/nodeJSBuildRun.js",
-        "buildnodejs": "./builders/nodeJSBuildRun.js",
-        "build-extension": "./builders/extensionBuildRun.js",
-        "buildextension": "./builders/extensionBuildRun.js",
-        "build-web": "./builders/webBuildRun.js",
-        "buildweb": "./builders/webBuildRun.js",
-        "build-electron": "./builders/electronBuildRun.js",
-        "buildelectron": "./builders/electronBuildRun.js",
-        "slift-watch": "./builders/watchRun.js",
-        "sliftwatch": "./builders/watchRun.js",
-        "slift-setup": "./builders/setupRun.js",
-        "sliftsetup": "./builders/setupRun.js"
-    },
-    "dependencies": {
-        "@types/chrome": "^0.0.237",
-        "@types/node-forge": "^1.3.11",
-        "@types/shell-quote": "^1.7.5",
-        "acme-client": "^5.0.0",
-        "js-sha256": "^0.11.1",
-        "mobx": "^6.13.3",
-        "preact-old-types": "^10.28.1",
-        "shell-quote": "^1.8.3",
-        "socket-function": "^1.1.42",
-        "typenode": "*",
-        "typesafecss": "*",
-        "ws": "^8.18.3",
-        "yargs": "15.4.1"
-    },
-    "resolutions": {
-        "preact": "npm:preact-old-types@*"
-    },
-    "devDependencies": {
-        "@types/yargs": "15.0.19",
-        "debugbreak": "^0.9.9",
-        "electron": "^33.2.1",
-        "open": "^8.4.0",
-        "typedev": "^0.1.1"
-    }
-}
+{
+    "name": "sliftutils",
+    "version": "1.4.4",
+    "main": "index.js",
+    "license": "MIT",
+    "files": [
+        "**/*",
+        ".gitignore"
+    ],
+    "scripts": {
+        "type": "yarn tsc --noEmit",
+        "emit-dts": "yarn tsc --project tsconfig.declarations.json || true",
+        "generate-index-dts": "typenode ./builders/generateIndexDts.ts",
+        "update-types": "yarn emit-dts && yarn generate-index-dts",
+        "prepublishOnly": "yarn update-types",
+        "run-nodejs": "node ./build-nodejs/server.js",
+        "run-nodejs-dev": "typenode ./nodejs/server.ts --npminstall",
+        "run-web": "node ./builders/webRun.js",
+        "run-electron": "node ./node_modules/electron/cli.js ./build-electron/electronMain.js",
+        "build-nodejs": "node ./builders/nodeJSBuildRun.js",
+        "build-web": "node ./builders/webBuildRun.js",
+        "build-extension": "node ./builders/extensionBuildRun.js",
+        "build-electron": "node ./builders/electronBuildRun.js",
+        "watch-nodejs": "node ./builders/watchRun.js --port 9876 \"nodejs/*.ts\" \"nodejs/*.tsx\" \"yarn build-nodejs\"",
+        "watch-web": "node ./builders/watchRun.js --port 9877 \"web/*.ts\" \"web/*.tsx\" \"yarn build-web\"",
+        "watch-extension": "node ./builders/watchRun.js --port 9878 \"extension/*.ts\" \"extension/*.tsx\" \"yarn build-extension\"",
+        "watch-electron": "node ./builders/watchRun.js --port 9879 \"electron/*.ts\" \"electron/*.tsx\" \"yarn build-electron\"",
+        "notes": "mobx, preact, socket-function, typenode SHOULD be peerDependencies. But we want to use yarn (better dependency deduplication), so we can't use peerDependencies (as they aren't installed by default, which makes them a nightmare to use). If you want to override the versions, feel free to use overrides/resolutions.",
+        "test": "typenode ./test.ts",
+        "filehoster": "node ./bin/filehoster.js"
+    },
+    "bin": {
+        "filehoster": "./bin/filehoster.js",
+        "build-nodejs": "./builders/nodeJSBuildRun.js",
+        "buildnodejs": "./builders/nodeJSBuildRun.js",
+        "build-extension": "./builders/extensionBuildRun.js",
+        "buildextension": "./builders/extensionBuildRun.js",
+        "build-web": "./builders/webBuildRun.js",
+        "buildweb": "./builders/webBuildRun.js",
+        "build-electron": "./builders/electronBuildRun.js",
+        "buildelectron": "./builders/electronBuildRun.js",
+        "slift-watch": "./builders/watchRun.js",
+        "sliftwatch": "./builders/watchRun.js",
+        "slift-setup": "./builders/setupRun.js",
+        "sliftsetup": "./builders/setupRun.js"
+    },
+    "dependencies": {
+        "@types/chrome": "^0.0.237",
+        "@types/node-forge": "^1.3.11",
+        "@types/shell-quote": "^1.7.5",
+        "acme-client": "^5.0.0",
+        "js-sha256": "^0.11.1",
+        "mobx": "^6.13.3",
+        "preact-old-types": "^10.28.1",
+        "shell-quote": "^1.8.3",
+        "socket-function": "^1.1.42",
+        "typenode": "*",
+        "typesafecss": "*",
+        "ws": "^8.18.3",
+        "yargs": "15.4.1"
+    },
+    "resolutions": {
+        "preact": "npm:preact-old-types@*"
+    },
+    "devDependencies": {
+        "@types/yargs": "15.0.19",
+        "debugbreak": "^0.9.9",
+        "electron": "^33.2.1",
+        "open": "^8.4.0",
+        "typedev": "^0.1.1"
+    }
+}

package/render-utils/FullscreenModal.tsx

@@ -48,7 +48,11 @@ export class FullscreenModal extends preact.Component<{
                         cursor: "pointer",
                         ...this.props.outerStyle,
                     }}
-                    onClick={e => {
+                    // Close on mouse DOWN on the backdrop, not click — otherwise a drag that starts
+                    // inside the modal (e.g. selecting text) and releases out on the backdrop fires a
+                    // click on the backdrop and wrongly closes it. currentTarget === target means the
+                    // press began on the backdrop itself, not bubbled up from the modal content.
+                    onMouseDown={e => {
                         if (e.currentTarget === e.target) {
                             if (parentState) parentState.open = false;
                             this.props.onCancel?.();

package/storage/BulkDatabase2/BulkDatabase2.d.ts

@@ -84,6 +84,20 @@ export interface IBulkDatabase2<T extends {
     getColumnInfo(): Promise<BulkColumnInfo[]>;
     /** A cheap snapshot of the collection's shape (row/key counts, total bytes, columns) — no row data. */
     getReaderInfo(): Promise<BulkReaderInfo>;
+    /**
+     * Per-file breakdown of the on-disk files, read fresh from disk each call (latest sizes, including
+     * stream files still being appended). `bytes` is the actual on-disk size. Good for showing collection
+     * size/fragmentation and deciding whether to call tryMergeNow()/compact().
+     */
+    getFileInfo(): Promise<{
+        files: {
+            name: string;
+            type: "bulk" | "stream";
+            bytes: number;
+        }[];
+        count: number;
+        totalBytes: number;
+    }>;
     /** Consolidate on-disk files. Optional to call; the database also does this in the background. */
     compact(): Promise<void>;
     /**

package/storage/BulkDatabase2/BulkDatabase2.ts

@@ -69,6 +69,12 @@ export interface IBulkDatabase2<T extends { key: string }> {
     getColumnInfo(): Promise<BulkColumnInfo[]>;
     /** A cheap snapshot of the collection's shape (row/key counts, total bytes, columns) — no row data. */
     getReaderInfo(): Promise<BulkReaderInfo>;
+    /**
+     * Per-file breakdown of the on-disk files, read fresh from disk each call (latest sizes, including
+     * stream files still being appended). `bytes` is the actual on-disk size. Good for showing collection
+     * size/fragmentation and deciding whether to call tryMergeNow()/compact().
+     */
+    getFileInfo(): Promise<{ files: { name: string; type: "bulk" | "stream"; bytes: number }[]; count: number; totalBytes: number }>;
 
     /** Consolidate on-disk files. Optional to call; the database also does this in the background. */
     compact(): Promise<void>;

package/storage/BulkDatabase2/BulkDatabaseBase.d.ts

@@ -127,4 +127,13 @@ export declare class BulkDatabaseBase<T extends {
             byteSize: number;
         }[];
     }>;
+    getFileInfo(): Promise<{
+        files: {
+            name: string;
+            type: "bulk" | "stream";
+            bytes: number;
+        }[];
+        count: number;
+        totalBytes: number;
+    }>;
 }

package/storage/BulkDatabase2/BulkDatabaseBase.ts

@@ -1183,6 +1183,21 @@ export class BulkDatabaseBase<T extends { key: string }> {
             columns: reader.columns,
         };
     }
+
+    // Per-file breakdown of the collection's on-disk files, read FRESH from disk each call (so it
+    // reflects the latest sizes, including stream files still being appended). `bytes` is the actual
+    // on-disk (compressed, for bulk) size. Useful for showing collection size / fragmentation, and to
+    // decide whether to call tryMergeNow()/compact().
+    public async getFileInfo(): Promise<{ files: { name: string; type: "bulk" | "stream"; bytes: number }[]; count: number; totalBytes: number }> {
+        const { bulkFiles, streamFiles } = await this.listFiles();
+        const storage = await this.storage();
+        const sizeOf = async (name: string) => { try { return (await storage.getInfo(name))?.size ?? 0; } catch { return 0; } };
+        const files = [
+            ...await Promise.all(bulkFiles.map(async f => ({ name: f.fileName, type: "bulk" as const, bytes: await sizeOf(f.fileName) }))),
+            ...await Promise.all(streamFiles.map(async f => ({ name: f.fileName, type: "stream" as const, bytes: await sizeOf(f.fileName) }))),
+        ];
+        return { files, count: files.length, totalBytes: files.reduce((a, f) => a + f.bytes, 0) };
+    }
 }
 
 // The merged, time-resolved view over all readers. getColumn/getSingleField return the resolved value

package/storage/FileFolderAPI.tsx

@@ -7,6 +7,7 @@ import { css, isNode } from "typesafecss";
 import { IStorageRaw } from "./IStorage";
 import { runInSerial } from "socket-function/src/batching";
 import { getFileStorageIndexDB } from "./IndexedDBFileFolderAPI";
+import { getRemoteFileStorage } from "./remoteFileStorage";
 import fs from "fs";
 import path from "path";
 
@@ -78,6 +79,32 @@ export function setFileAPIKey(key: string) {
     fileAPIKey = key;
 }
 
+// ---- remote (server) storage config ----
+// Instead of a local folder, the user can point at a remoteFileServer.js instance (URL + password).
+// When configured, getFileStorageNested2 serves everything from that server. Persisted in localStorage.
+type RemoteConfig = { url: string; password: string };
+function remoteConfigKey() { return getFileAPIKey() + ":remote"; }
+function loadRemoteConfig(): RemoteConfig | undefined {
+    try {
+        const s = localStorage.getItem(remoteConfigKey());
+        if (!s) return undefined;
+        const c = JSON.parse(s);
+        if (c && typeof c.url === "string" && typeof c.password === "string") return c;
+    } catch { /* ignore */ }
+    return undefined;
+}
+function saveRemoteConfig(c: RemoteConfig) { localStorage.setItem(remoteConfigKey(), JSON.stringify(c)); }
+
+// One shared factory (and therefore one shared range cache) per remote config.
+let remoteFactory: { key: string; factory: ReturnType<typeof getRemoteFileStorage> } | undefined;
+function getRemoteFactory(remote: RemoteConfig) {
+    const key = remote.url + "\0" + remote.password;
+    if (!remoteFactory || remoteFactory.key !== key) {
+        remoteFactory = { key, factory: getRemoteFileStorage(remote.url, remote.password) };
+    }
+    return remoteFactory.factory;
+}
+
 @observer
 class DirectoryPrompter extends preact.Component {
     render() {
@@ -96,6 +123,53 @@ class DirectoryPrompter extends preact.Component {
     }
 }
 
+// "Connect to a server" option for the directory prompt: collapses to a button, expands to URL +
+// password fields. On connect it validates the credentials against the server, persists the config, and
+// reloads so getFileStorageNested2 picks up the remote storage.
+@observer
+class ServerConnectForm extends preact.Component {
+    private obs = observable({ expanded: false, url: "", password: "", error: "", connecting: false });
+    private connect = async () => {
+        const s = this.obs;
+        s.error = "";
+        s.connecting = true;
+        try {
+            const url = s.url.trim().replace(/\/+$/, "");
+            if (!url) throw new Error("Enter a server URL");
+            // A successful listing proves the URL is reachable and the password is correct.
+            await (await getRemoteFileStorage(url, s.password.trim())("")).getKeys();
+            saveRemoteConfig({ url, password: s.password.trim() });
+            window.location.reload();
+        } catch (e) {
+            s.error = "Could not connect: " + ((e as Error).message || String(e));
+            s.connecting = false;
+        }
+    };
+    render() {
+        const s = this.obs;
+        const inputCss = css.fontSize(28).pad2(24, 14).width(560).maxWidth("80vw");
+        const btnCss = css.fontSize(32).pad2(60, 30);
+        if (!s.expanded) {
+            return <button className={btnCss} onClick={() => s.expanded = true}>Connect to a server</button>;
+        }
+        return (
+            <div className={css.vbox(16).center}>
+                <input className={inputCss} placeholder="https://host:8787" value={s.url}
+                    onInput={e => s.url = (e.target as HTMLInputElement).value} />
+                <input className={inputCss} type="password" placeholder="password (six words)" value={s.password}
+                    onInput={e => s.password = (e.target as HTMLInputElement).value} />
+                {s.error ? <div className={css.fontSize(20).color("red").maxWidth("80vw")}>{s.error}</div> : null}
+                <div className={css.hbox(16)}>
+                    <button className={btnCss} disabled={s.connecting} onClick={this.connect}>
+                        {s.connecting ? "Connecting…" : "Connect"}
+                    </button>
+                    <button className={btnCss} onClick={() => { s.expanded = false; s.error = ""; }}>Back</button>
+                </div>
+            </div>
+        );
+    }
+}
+
 export class NodeJSFileHandleWrapper implements FileWrapper {
     constructor(private filePath: string) {
     }
@@ -317,6 +391,7 @@ export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Prom
                             >
                                 Pick Data Directory
                             </button>
+                            <ServerConnectForm />
                             <button
                                 className={css.fontSize(40).pad2(80, 40)}
                                 onClick={() => {
@@ -359,6 +434,7 @@ export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Prom
                 >
                     Pick Data Directory
                 </button>
+                <ServerConnectForm />
                 <button
                     className={css.fontSize(40).pad2(80, 40)}
                     onClick={() => {
@@ -388,6 +464,10 @@ export const getFileStorageNested = cache(async function getFileStorage(path: st
 export const getFileStorageNested2 = cache(async function getFileStorage(pathStr: string): Promise<FileStorage> {
     let base: DirectoryWrapper;
     pathStr = pathStr.replaceAll("\\", "/");
+    if (!isNode()) {
+        const remote = loadRemoteConfig();
+        if (remote) return getRemoteFactory(remote)(pathStr);
+    }
     if (isNode()) {
         if (path.isAbsolute(pathStr)) {
             return wrapHandle(new NodeJSDirectoryHandleWrapper(pathStr));
@@ -424,6 +504,7 @@ export const getFileStorage = lazy(async function getFileStorage(): Promise<File
 });
 export function resetStorageLocation() {
     localStorage.removeItem(getFileAPIKey());
+    try { localStorage.removeItem(remoteConfigKey()); } catch { /* ignore */ }
     window.location.reload();
 }
 

package/storage/remoteFileServer.d.ts

@@ -0,0 +1,16 @@
+export declare function generatePassword(wordCount: number): string;
+export type RemoteFileServerOptions = {
+    root: string;
+    port?: number;
+    host?: string;
+    password?: string;
+    logAccess?: boolean;
+};
+export type RemoteFileServerHandle = {
+    port: number;
+    password: string;
+    url: string;
+    close: () => Promise<void>;
+};
+export declare function startRemoteFileServer(options: RemoteFileServerOptions): Promise<RemoteFileServerHandle>;
+export declare function runFileHoster(): Promise<void>;

package/storage/remoteFileServer.ts

@@ -0,0 +1,439 @@
+import https from "https";
+import type { IncomingMessage, ServerResponse } from "http";
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import os from "os";
+import { execFileSync } from "child_process";
+import { getExternalIP } from "socket-function/src/networking";
+import { forwardPort } from "socket-function/src/forwardPort";
+
+// Remote file server for sliftutils getRemoteFileStorage / BulkDatabase2. Serves one folder on disk over
+// self-signed HTTPS, authenticated with an auto-generated 6-word password (sent as
+// `Authorization: Bearer <password>`). Run it with `yarn filehoster <folder>` (or the `filehoster` bin).
+//
+// SECURITY: the cert is self-signed, so a browser must accept it once (open the printed https URL and
+// click through), and the Node client connects with cert verification disabled. The password is what
+// authorizes access; keep it secret.
+
+// Common, memorable words (frequency-ordered subset) for passphrase generation.
+const WORDS: string[] = [
+    "that","with","which","this","from","have","they","were","their","there","when","them","said","been",
+    "would","will","what","more","then","into","some","could","time","very","than","your","other","upon",
+    "about","only","little","like","these","great","after","well","made","before","such","over","should",
+    "first","good","must","much","down","where","know","most","here","come","those","never","life","long",
+    "came","being","many","through","even","himself","back","every","shall","again","make","without","might",
+    "while","same","under","just","still","people","place","think","house","take","last","found","away",
+    "hand","went","thought","also","though","three","another","eyes","years","work","right","once","night",
+    "young","nothing","against","small","head","left","part","ever","world","each","father","give","between",
+    "face","king","things","love","because","took","always","tell","called","water","both","side","look",
+    "having","room","mind","half","heart","name","home","country","whole","however","find","among","going",
+    "thing","lord","looked","seen","mother","general","done","seemed","told","whom","days","soon","better",
+    "letter","woman","heard","asked","course","thus","moment","knew","light","enough","white","almost",
+    "until","quite","hands","words","death","large","taken","since","gave","given","best","state","brought",
+    "does","whose","door","others","power","perhaps","present","next","morning","poor","lady","four","high",
+    "year","turned","less","word","full","during","rather","want","order","near","feet","true","miss",
+    "matter","began","cannot","used","known","felt","above","round","thou","voice","till","case","nature",
+    "indeed","church","kind","certain","fire","often","stood","fact","friend","girl","five","land","says",
+    "john","myself","along","point","dear","wife","city","within","sent","times","keep","passed","form",
+    "second","body","money","believe","hundred","open","several","means","child","english","herself","sure",
+    "looking","women","already","black","alone","least","gone","held","itself","whether","hope","river",
+    "ground","either","number","chapter","england","leave","rest","town","hear","greek","friends","book",
+    "hour","short","cried","read","behind","became","making","family","earth","captain","around","dead",
+    "reason","call","become","lost","line","replied","help","coming","speak","manner","french","twenty",
+    "spirit","really","early","story","hard","close","human","public","truth","strong","master","care",
+    "towards","history","kept","later","states","dark","able","mean","return","brother","person","subject",
+    "soul","party","arms","thee","seems","common","fell","fine","feel","show","table","turn","wish","evening",
+    "free","cause","south","ready","north","across","rose","live","account","doubt","company","miles","road",
+    "bring","london","sense","horse","carried","hold","sight","fear","answer","idea","force","need","deep",
+    "further","nearly","past","army","blood","street","court","reached","view","school","sort","taking",
+    "else","chief","hours","beyond","cold","none","longer","strange","fellow","clear","service","natural",
+    "suppose","late","talk","front","stand","purpose","seem","neither","ought","west","real","except","sound",
+    "gold","forward","feeling","added","boys","self","peace","happy","living","husband","toward","spoke",
+    "fair","france","trees","effect","latter","length","change","died","green","united","fall","pretty",
+    "placed","meet","forth","office","comes","pass","written","ship","enemy","saying","tree","foot","blue",
+    "note","prince","hair","heaven","wild","play","entered","society","laid","wind","doing","paper","opened",
+    "bear","third","queen","mine","greater","various","faith","wanted","boat","stone","lived","george",
+    "window","doctor","action","books","tried","letters","makes","minutes","parts","wood","period","duty",
+    "york","instead","heavy","persons","battle","field","british","object","century","island","beauty",
+    "christ","sister","glad","below","east","opinion","save","places","months","food","sweet","trouble",
+    "system","born","desire","works","mary","chance","william","seven","single","hardly","sleep","mouth",
+    "horses","silence","ancient","broken","hall","send","rich","girls","besides","lips","henry","figure",
+    "slowly","hill","wall","future","lines","follow","german","march","filled","brown","deal","eight",
+    "covered","smile","former","week","drew","easy","paris","camp","stay","cross","seeing","result","started",
+    "caught","houses","appear","wrote","giving","simple","arrived","formed","bright","wide","uncle","piece",
+    "walked","knows","carry","middle","village","holy","merely","getting","raised","afraid","struck",
+    "charles","board","visit","royal","spring","dinner","evil","outside","wrong","summer","moved","danger",
+    "mark","fresh","plain","thirty","scene","quickly","wonder","jack","indian","walk","learned","class",
+    "secret","wait","command","easily","garden","loved","married","fight","leaving","music","usual","cases",
+    "winter","respect","value","quiet","please","stopped","write","laughed","america","chair","paid","duke",
+    "leaves","lower","colonel","perfect","james","worth","author","finally","youth","regard","glass",
+    "picture","built","modern","success","race","showed","tears","unless","mere","lives","grew","charge",
+    "beside","remain","waiting","study","hath","shot","unto","tone","iron","watch","grace","flowers","killed",
+    "allowed","news","step","proper","sitting","floor","justice","noble","goes","walls","laws","meant",
+    "bound","forms","fifty","drawn","private","fast","indians","judge","meeting","usually","sudden","gives",
+    "reach","bank","attempt","shore","stop","plan","silent","special","spot","officer","silver","passing",
+    "broke","lake","soft","journey","beneath","shown","turning","members","enter","lead","trade","names",
+    "escape","troops","bill","corner","rule","ladies","species","rock","similar","running","rate","cast",
+    "nation","post","likely","simply","orders","dress","fish","minute","birds","europe","passage","surface",
+    "snow","attack","higher","rise","grand","reply","honour","notice","speech","trying","game","writing",
+    "closed","rome","example","aunt","learn","morrow","offered","peter","equal","space","page","wished",
+    "changed","animal","social","twelve","appears","receive","valley","degree","train","steps","fixed",
+    "count","forest","matters","foreign","native","broad","moral","animals","safe","roman","break","pale",
+    "memory","warm","trust","yellow","sides","main","bird","reading","coast","pain","grave","forget","move",
+    "fortune","madame","proved","forty","lying","quick","wise","jesus","working","surely","looks","seat",
+    "divine","touch","loss","paul","heads","spent","ordered","report","caused","thomas","ones","drawing",
+    "talking","breath","meaning","month","union","pleased","powers","emperor","laugh","affairs","narrow",
+    "square","science","begin","promise","takes","conduct","serious","thank","curious","pieces","health",
+    "exactly","ways","upper","decided","nine","stream","wine","engaged","points","amount","named","song",
+    "worse","size","castle","crown","mass","liberty","stage","guard","servant","greatly","price","weeks",
+    "neck","ears","drink","crowd","thick","fallen","hills","spoken","golden","capital","sign","spite","terms",
+    "sake","council","threw","ships","portion","support","clothes","effort","fully","holding","majesty",
+    "glory","pure","facts","sword","sorry","fate","bread","prove","station","sharp","dream","vain","major",
+    "smiled","instant","spread","serve","sick","june","ideas","thrown","start","weather","gray","courage",
+    "anxious","woods","path","rising","grass","moon","gate","forced","fancy","bottom","expect","remains",
+    "shook","bishop","watched","settled","events","rain","quarter","heat","palace","glance","kingdom",
+    "papers","aside","worthy","taste","pride","july","opening","daily","leading","wounded","famous","offer",
+    "group","distant","weight","highest","vast","popular","passion","knowing","allow","sought","lies",
+    "marked","series","growing","measure","hearts","robert","obliged","western","hence","style","dropped",
+    "nations","grown","honor","edge","pray","tall","frank","poet","streets","season","pointed","mighty",
+    "temple","extent","thin","blow","freedom","entire","keeping","prevent","shut","storm","lose","college",
+    "cost","marry","spirits","worked","colour","ring","listen","fruit","waters","fashion","share","hung",
+    "proud","fingers","method","served","grow","fort","draw","dollars","quietly","yours","vessel","direct",
+    "refused","bridge","gods","inside","title","advance","priest","becomes","dick","double","seek","guess",
+    "spanish","larger","ball","finding","edward","removed","brave","tired","agreed","sacred","sons","guns",
+    "played","richard","devil","pounds","honest","false","cloth","soldier","tongue","smith","wealth","failed",
+    "height","faces","equally","legs","pocket","twice","volume","prayer","county","notes","louis","unknown",
+    "delight","rights","nice","taught","coat","dare","slight","rocks","enemies","control","forces","germany",
+    "kill","process","david","rapidly","comfort","islands","centre","salt","april","windows","noticed",
+    "truly","color","fields","date","august","desired","breast","skin","gentle","smoke","search","joined",
+    "nobody","results","needed","weak","type","stones","follows","theory","shape","waited","telling","relief",
+    "bearing","bent","mile","dressed","birth","spain","female","clearly","moving","drive","crossed","member",
+    "saved","teeth","flesh","cover","shows","farther","stands","figures","numbers","bodies","supply","motion",
+    "grey","bell","alive","seized","shadow","produce","touched","driven","talked","empire","sunday","pair",
+    "fourth","slave","regular","dozen","beat","cousin","sand","soil","rough","claim","angry","pity","walking",
+    "acts","pope","rooms","task","stock","tender","throw","reader","india","hotel","fifteen","arrival",
+    "plate","stars","willing","stories","saint","amongst","virtue","chamber","civil","yards","habit","writer",
+    "putting","origin","italy","hearing","genius","milk","busy","fool","burning","duties","brain","slow",
+    "belief","bore","mention","grant","library","inches","press","calm","total","ride","lands","labor",
+    "parties","clean","catch","treated","rode","whilst","level","efforts","minds","welcome","wisdom","supper",
+    "final","mercy","aware","lovely","empty","wants","midst","central","rank","proof","burst","term","farm",
+    "applied","loud","nearer","harry","closely","kings","explain","deck","noise","hurt","advice","absence",
+    "circle","objects","secure","plants","parents","falling","base","fellows","sorrow","flat","flower",
+    "calling","imagine","range","sold","favour","happen","showing","earl","hole","careful","dust","prison",
+    "useful","accept","firm","sing","port","seated","custom","wore","doors","lifted","edition","tale",
+    "affair","policy","roof","express","ahead","worship","partly","address","highly","victory","ocean",
+    "begun","buried","content","smiling","liked","active","quality","philip","current","divided","growth",
+    "huge","moments","article","speed","poetry","machine","join","nose","unable","ceased","gained","worn",
+    "eastern","safety","ages","vessels","hopes","corn","slaves","drop","plant","evident","local","police",
+    "october","obtain","italian","deeply","dying","wholly","dogs","playing","plenty","apart","suffer","maid",
+    "record","fairly","kindly","terror","drove","ends","sugar","capable","irish","message","chosen","flight",
+    "reasons","couple","meat","printed","blind","energy","bitter","baby","mistake","tower","ireland","trial",
+    "wear","brief","market","band","causes","clouds","goods","admit","cities","earlier","tells","stated",
+    "pressed","crime","fought","guide","hoped","list","banks","knight","fleet","pulled","tail","patient",
+    "mental","boats","kinds","stairs","star","cattle","rare","wings","disease","section","actual","bare",
+    "extreme","cruel","worst","escaped","dance","strike","views","eggs","needs","store","choice","fond",
+    "adopted","suit","singing","fail","souls","thanks","hidden","shame","faint","shop","older","joseph",
+    "knees","gently","blessed","yard","cent","grief","male","sooner","january","excited","region","praise",
+    "throne","classes","effects","demand","gain","fault","labour","variety","loose","cook","devoted","ended",
+    "changes","witness","bought","lover","visited","club","sheep","cloud","enjoy","asleep","cool","dull",
+    "painted","arose","armed","dignity","chiefly","voices","sail","event","signs","hero","schools","branch",
+    "hurried","arthur","kitchen","stick","coffee","thinks","eager","natives","flying","boston","eternal",
+    "source","fill","anger","vision","murder","viii","park","avoid","awful","raise","desert","plans","pardon",
+    "assured","wound","finger","bible","rear","details","cabin","whence","reign","weary","slavery","visible",
+    "shouted","seldom","skill","hast","throat","reality","leader","egypt","credit","smaller","severe","calls",
+    "younger","shell","sprang","anybody","handed","despair","asking","inch","mystery","manners","knife",
+    "design","sounds","wishes","stepped","towns","sixty","immense","china","favor","latin","hate","setting",
+    "excuse","chinese","behold","rushed","choose","ease","lights","paused","mission","voyage","gift","bold",
+    "meal","britain","smooth","mounted","utterly","lest","helped","picked","falls","pipe","bones","earnest",
+    "granted","swept","anxiety","teach","waves","softly","savage","hunting","defence","rapid","artist",
+    "recent","supreme","russian","created","habits","exist","guilty","pages","crew","hell","remark","request",
+    "harm","solemn","observe","trail","copy","violent","dreams","proceed","luck","steel","sell","temper",
+    "appeal","hide","fled","belong","triumph","abroad","waste","consent","writers","possess","jews","require",
+    "priests","railway","founded","pushed","host","solid","maybe","degrees","cheeks","mount","ruin","owing",
+    "fierce","reduced","mankind","text","swift","riding","silk","shade","career","wicked","afford","alas",
+    "rules","treaty","correct","spend","foolish","methods","remarks","horror","shining","enjoyed","tribes",
+    "lack","frame","gets","eagerly","russia","alike","somehow","nodded","problem","fever","sees","stern",
+    "dawn","forgive","flag","managed","fame","travel","estate","cotton","hurry","agree","feared","kiss",
+    "million","martin","mixed","risk","butter","jane","assumed","pause","benefit","unhappy","lighted",
+    "scheme","slept","plainly","forgot","delay","merry","rush","wooden","secured","poem","rolled","angel",
+    "guests","farmer","humble","glanced","shortly","rope","image","lately","africa","fired","retired","bull",
+    "steam","keen","loving","borne","readily","beloved","average","teacher","attend","flame","area","burned",
+    "thrust","negro","nurse","spare","fifth","thence","roads","refuse","tent","kissed","gates","gaze","fatal",
+    "israel","verse","scenes","confess","uttered","build","acted","hanging","reward","issue","utmost",
+    "fathers","noted","widow","related","urged","mode","failure","nervous","render","masters","tribe",
+    "colored","turns","alarm","rivers","using","eleven","rage","hers","lamp","retreat","amid","gospel",
+    "exposed","johnson","marks","tide","emotion","destroy","inner","sisters","lion","helen","tied","grounds",
+    "acid","wheel","issued","invited","gazed","senate","finds","seed","regret","clay","chain","crowded",
+    "bosom","limited","steady","chap","anne","francis","cavalry","freely","charm","faced","ideal","useless",
+    "warning","shelter","vote","xpage","cottage","beast","outer","folks","misery","anyone","expense","firmly",
+    "eating","lonely","owner","trace","coal","hastily","elder","utter","begins","chapel","nights","dared",
+    "signal","stared","track","lords","speaks","bottle","blame","claims","shoes","sigh","ghost","folk",
+    "dutch","flung","flew","cheek","staff","walter","clever","acting","hungry","poems","cutting","forever",
+    "exact","haste","dancing","trip","lincoln","pull","vice","slipped","thine","loves","permit","mill",
+    "engine","hollow","seeking","bowed","largely","charged","painful","madam","roll","leaf","prayers",
+    "element","agent","cries","songs","theatre","creek","match","ashamed","runs","aspect","canada","treat",
+    "legal","arts","corps","noon","nearest","scale","hunt","shadows","winds","landed","beings","tiny",
+    "gardens","bless","clerk","doth","derived","hang","heavens","cape","ours","brow","test","senses",
+    "opposed","error","driving","nest","headed","groups","princes","feast","admiral","poured","brings",
+    "pursued","germans","bears","lesson","journal","unusual","marched","wing","remove","studied","passes",
+    "actions","burden","colony","scott","bride","yield","crying","forming","rifle","powder","rested","shake",
+    "guest","begged","occur","altar","sorts","beaten","wave","papa","sang","depth","aloud","contact",
+    "intense","marble","poverty","detail","writes","root","metal","jean","existed","ability","purple",
+    "counsel","lane","wives","sending","heavily","leaders","queer","tales","sins","mexico","protect","clock",
+    "stuff","jones","pine","records","cave","baron","medical","pick","stayed","magic","seventy","pour",
+    "saddle","sank","dread","deny","wire","rude","holds","strain","autumn","shed","shoot","settle","basis",
+    "readers","route","beach","safely","oxford","notion","thunder","sale","saints","pound","shock","elected",
+    "signed","whereas","maiden","courts","rarely","wolf","mamma","billy","student","charity","impulse",
+    "tones","mortal","raising","wedding","belongs","chest","sharply","sounded","poets","lawyer","hugh",
+    "plays","awake","landing","debt","alice","venture","idle","uniform","contain","tobacco","boots","fears",
+    "leaned","studies","customs","prize","stir","obey","oath","badly","pursuit","resting",
+];
+
+export function generatePassword(wordCount: number): string {
+    const words: string[] = [];
+    for (let i = 0; i < wordCount; i++) words.push(WORDS[crypto.randomInt(WORDS.length)]);
+    return words.join(" ");
+}
+
+// The password is always a list of words, so we compare case-insensitively and ignore any non-letter
+// characters. That makes it forgiving of voice dictation and mobile autocorrect (spacing, capitals,
+// stray punctuation) without meaningfully weakening a 6-word passphrase.
+function normalizePassword(p: string): string {
+    return String(p || "").toLowerCase().replace(/[^a-z]/g, "");
+}
+
+// Generate (once) and cache a self-signed key + cert via openssl, outside the served folder so its
+// private key is never reachable through the API.
+function getCert(): { key: Buffer; cert: Buffer } {
+    const dir = path.join(os.homedir(), ".sliftutils-remote");
+    fs.mkdirSync(dir, { recursive: true });
+    const keyPath = path.join(dir, "key.pem");
+    const certPath = path.join(dir, "cert.pem");
+    if (!fs.existsSync(keyPath) || !fs.existsSync(certPath)) {
+        try {
+            execFileSync("openssl", [
+                "req", "-x509", "-newkey", "rsa:2048", "-nodes",
+                "-keyout", keyPath, "-out", certPath, "-days", "3650",
+                "-subj", "/CN=sliftutils-remote",
+                "-addext", "subjectAltName=DNS:localhost,IP:127.0.0.1",
+            ], { stdio: "ignore" });
+        } catch (e) {
+            throw new Error("Failed to generate a self-signed certificate with openssl (is openssl installed?): " + (e as Error).message);
+        }
+    }
+    return { key: fs.readFileSync(keyPath), cert: fs.readFileSync(certPath) };
+}
+
+function timingSafeEqualStr(a: string, b: string): boolean {
+    const ab = Buffer.from(a || "", "utf8");
+    const bb = Buffer.from(b || "", "utf8");
+    if (ab.length !== bb.length) return false;
+    return crypto.timingSafeEqual(ab, bb);
+}
+
+// Resolve a client-supplied relative path against the root, refusing anything that escapes it.
+function safeResolve(root: string, rel: string | null): string | undefined {
+    if (rel == null) rel = "";
+    if (rel.indexOf("\0") >= 0) return undefined;
+    const full = path.resolve(root, "." + path.sep + rel.replace(/\\/g, "/"));
+    if (full !== root && !full.startsWith(root + path.sep)) return undefined;
+    return full;
+}
+
+function readBody(req: IncomingMessage): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+        const chunks: Buffer[] = [];
+        req.on("data", c => chunks.push(c as Buffer));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+
+function formatBytes(n: number): string {
+    if (n < 1024) return n + "B";
+    if (n < 1024 * 1024) return (n / 1024).toFixed(1) + "KB";
+    if (n < 1024 * 1024 * 1024) return (n / 1024 / 1024).toFixed(1) + "MB";
+    return (n / 1024 / 1024 / 1024).toFixed(2) + "GB";
+}
+
+export type RemoteFileServerOptions = {
+    root: string;
+    port?: number;
+    host?: string;
+    password?: string;
+    // When true, log batched per-(client, file) access totals every 5s. The CLI turns this on; the
+    // library (tests) leaves it off.
+    logAccess?: boolean;
+};
+export type RemoteFileServerHandle = { port: number; password: string; url: string; close: () => Promise<void> };
+
+export function startRemoteFileServer(options: RemoteFileServerOptions): Promise<RemoteFileServerHandle> {
+    const root = path.resolve(options.root);
+    if (!fs.existsSync(root)) fs.mkdirSync(root, { recursive: true });
+    const port = options.port ?? 8787;
+    const host = options.host || "0.0.0.0";
+    const password = options.password || generatePassword(6);
+    const normPassword = normalizePassword(password);
+    const { key, cert } = getCert();
+
+    // Batched access log: aggregate per (ip, op, file) so hammering one file logs once per 5s with the
+    // total request count and bytes, instead of a line per request.
+    type Acc = { ip: string; op: string; path: string; count: number; bytes: number };
+    const accessLog = new Map<string, Acc>();
+    let flushTimer: ReturnType<typeof setInterval> | undefined;
+    const recordAccess = (ip: string, op: string, p: string, bytes: number) => {
+        if (!options.logAccess) return;
+        const k = ip + "|" + op + "|" + p;
+        let e = accessLog.get(k);
+        if (!e) { e = { ip, op, path: p, count: 0, bytes: 0 }; accessLog.set(k, e); }
+        e.count++;
+        e.bytes += bytes;
+    };
+    if (options.logAccess) {
+        flushTimer = setInterval(() => {
+            if (!accessLog.size) return;
+            const rows = [...accessLog.values()].sort((a, b) => b.bytes - a.bytes);
+            accessLog.clear();
+            for (const e of rows) console.log(`  [${e.op}] ${e.ip}  ${e.path}  ${e.count}x  ${formatBytes(e.bytes)}`);
+        }, 5000);
+        flushTimer.unref?.();
+    }
+    const clientIp = (req: IncomingMessage) => (req.socket.remoteAddress || "?").replace(/^::ffff:/, "");
+
+    const server = https.createServer({ key, cert }, async (req: IncomingMessage, res: ServerResponse) => {
+        const origin = (req.headers["origin"] as string) || "*";
+        const cors: Record<string, string> = {
+            "Access-Control-Allow-Origin": origin,
+            "Access-Control-Allow-Methods": "GET, PUT, POST, DELETE, OPTIONS",
+            "Access-Control-Allow-Headers": "authorization, content-type",
+            "Access-Control-Max-Age": "86400",
+            "Vary": "Origin",
+        };
+        const send = (status: number, headers: Record<string, string>, body?: Buffer | string) => {
+            res.writeHead(status, Object.assign({}, cors, headers));
+            res.end(body);
+        };
+        const sendJson = (status: number, obj: unknown) => send(status, { "Content-Type": "application/json" }, JSON.stringify(obj));
+
+        try {
+            if (req.method === "OPTIONS") return send(204, {});
+
+            const auth = (req.headers["authorization"] as string) || "";
+            const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+            if (!timingSafeEqualStr(normalizePassword(token), normPassword)) return sendJson(401, { error: "unauthorized" });
+
+            const url = new URL(req.url || "/", "https://localhost");
+            const op = url.pathname;
+            const relPath = url.searchParams.get("path") || "";
+            const full = safeResolve(root, relPath);
+            if (full === undefined) return sendJson(403, { error: "path escapes root" });
+
+            if (req.method === "GET" && op === "/list") {
+                const wantFolders = url.searchParams.get("folders") === "1";
+                let entries: fs.Dirent[];
+                try { entries = fs.readdirSync(full, { withFileTypes: true }); }
+                catch (e) { return (e as NodeJS.ErrnoException).code === "ENOENT" ? sendJson(200, []) : sendJson(500, { error: (e as Error).message }); }
+                return sendJson(200, entries.filter(d => wantFolders ? d.isDirectory() : d.isFile()).map(d => d.name));
+            }
+            if (req.method === "GET" && op === "/info") {
+                let st: fs.Stats;
+                try { st = fs.statSync(full); } catch { return sendJson(404, { error: "not found" }); }
+                return sendJson(200, { size: st.size, lastModified: st.mtimeMs });
+            }
+            if (req.method === "GET" && op === "/hasDir") {
+                let st: fs.Stats; try { st = fs.statSync(full); } catch { return sendJson(200, { exists: false }); }
+                return sendJson(200, { exists: st.isDirectory() });
+            }
+            if (req.method === "GET" && op === "/read") {
+                let st: fs.Stats;
+                try { st = fs.statSync(full); } catch { return sendJson(404, { error: "not found" }); }
+                let start = parseInt(url.searchParams.get("start") || "0", 10);
+                let end = url.searchParams.get("end") != null ? parseInt(url.searchParams.get("end") as string, 10) : st.size;
+                start = Math.min(Math.max(start, 0), st.size);
+                end = Math.min(Math.max(end, start), st.size);
+                recordAccess(clientIp(req), "read", relPath, end - start);
+                res.writeHead(200, Object.assign({}, cors, { "Content-Type": "application/octet-stream", "Content-Length": String(end - start) }));
+                if (end === start) return res.end();
+                fs.createReadStream(full, { start, end: end - 1 }).on("error", () => res.end()).pipe(res);
+                return;
+            }
+            if ((req.method === "PUT" || req.method === "POST") && (op === "/append" || op === "/set")) {
+                const body = await readBody(req);
+                fs.mkdirSync(path.dirname(full), { recursive: true });
+                if (op === "/append") fs.appendFileSync(full, body);
+                else fs.writeFileSync(full, body);
+                recordAccess(clientIp(req), "write", relPath, body.length);
+                return sendJson(200, { ok: true });
+            }
+            if (req.method === "DELETE" && op === "/remove") {
+                try { fs.unlinkSync(full); } catch (e) { if ((e as NodeJS.ErrnoException).code !== "ENOENT") return sendJson(500, { error: (e as Error).message }); }
+                return sendJson(200, { ok: true });
+            }
+            if (req.method === "DELETE" && op === "/removeDir") {
+                try { fs.rmSync(full, { recursive: true, force: true }); } catch (e) { return sendJson(500, { error: (e as Error).message }); }
+                return sendJson(200, { ok: true });
+            }
+            if (req.method === "POST" && op === "/reset") {
+                try { for (const name of fs.readdirSync(full)) fs.rmSync(path.join(full, name), { recursive: true, force: true }); }
+                catch (e) { if ((e as NodeJS.ErrnoException).code !== "ENOENT") return sendJson(500, { error: (e as Error).message }); }
+                return sendJson(200, { ok: true });
+            }
+            return sendJson(404, { error: "unknown endpoint" });
+        } catch (e) {
+            try { sendJson(500, { error: String((e as Error)?.message || e) }); } catch { /* response already sent */ }
+        }
+    });
+
+    return new Promise<RemoteFileServerHandle>((resolve, reject) => {
+        server.on("error", reject);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            const actualPort = typeof addr === "object" && addr ? addr.port : port;
+            resolve({
+                port: actualPort,
+                password,
+                url: `https://localhost:${actualPort}`,
+                close: () => new Promise<void>(r => { if (flushTimer) clearInterval(flushTimer); server.close(() => r()); }),
+            });
+        });
+    });
+}
+
+// CLI entry (invoked by bin/filehoster.js or `yarn filehoster <folder>`). Starts the server, logs the
+// password + local/public URLs + batched access, and keeps the UPnP port mapping alive.
+export async function runFileHoster(): Promise<void> {
+    const args = process.argv.slice(2);
+    const root = args.find(a => !a.startsWith("--") && !a.endsWith(".ts") && !a.endsWith(".js"));
+    if (!root) {
+        console.error("Usage: yarn filehoster <folder> [--port N]   (set a fixed password with PASSWORD=...)");
+        process.exit(1);
+    }
+    const portIdx = args.indexOf("--port");
+    const port = portIdx >= 0 ? parseInt(args[portIdx + 1], 10) : 8787;
+
+    const info = await startRemoteFileServer({ root, port, password: process.env.PASSWORD, logAccess: true });
+    let externalIP: string | undefined;
+    try { externalIP = (await getExternalIP()).trim(); } catch { /* offline / unreachable */ }
+
+    console.log("");
+    console.log("  Serving:   " + path.resolve(root));
+    console.log("  Password:  " + info.password);
+    console.log("  Local:     " + info.url);
+    if (externalIP) console.log("  Public:    https://" + externalIP + ":" + info.port + "   (once port-forwarding succeeds)");
+    console.log("");
+    console.log("  In the app, choose \"Connect to a server\" and enter the URL + password.");
+    console.log("  (Self-signed cert: open the URL once in your browser and accept it first.)");
+    console.log("");
+
+    // Keep the UPnP port mapping alive — leases expire ~hourly, so refresh well within that. No-op on
+    // Linux (forwardPort returns early there).
+    const refresh = async () => {
+        try { await forwardPort({ externalPort: info.port, internalPort: info.port }); }
+        catch (e) { console.warn("  port forwarding failed:", (e as Error).message); }
+    };
+    await refresh();
+    setInterval(refresh, 30 * 60 * 1000);
+
+    console.log("  [access] request logging on (batched every 5s)\n");
+}

package/storage/remoteFileStorage.d.ts

@@ -0,0 +1,38 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import https from "https";
+import type { FileStorage } from "./FileFolderAPI";
+export type RemoteFileStorageOptions = {
+    chunkBytes?: number;
+    cacheBytes?: number;
+    latencyMs?: number;
+};
+type Connection = {
+    url: string;
+    password: string;
+    latencyMs: number;
+    agent: https.Agent | undefined;
+    cache: RangeCache;
+    stats: {
+        requestCount: number;
+        bytesFetched: number;
+    };
+};
+declare class RangeCache {
+    private chunkBytes;
+    private budget;
+    private chunks;
+    private bytes;
+    constructor(chunkBytes: number, budget: number);
+    private key;
+    private peek;
+    private store;
+    invalidate(path: string): void;
+    getRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined>;
+}
+export type RemoteStorageFactory = ((path: string) => Promise<FileStorage>) & {
+    stats: Connection["stats"];
+};
+export declare function getRemoteFileStorage(url: string, password: string, options?: RemoteFileStorageOptions): RemoteStorageFactory;
+export {};

package/storage/remoteFileStorage.ts

@@ -0,0 +1,236 @@
+import { isNode } from "typesafecss";
+import https from "https";
+import type { FileStorage, NestedFileStorage } from "./FileFolderAPI";
+
+// Client for remoteFileServer.js: exposes a remote folder as a FileStorage (so BulkDatabase2 runs over
+// the network unchanged). One HTTP round trip per operation. A pure data-level range cache (below)
+// fetches in large aligned chunks and reuses them, because over the network latency dominates — reading
+// 1MB costs about the same as 64KB, so fewer round trips wins.
+
+const EMPTY = Buffer.alloc(0);
+
+// Over the network, fetch reads in chunks this big and cache them. Big because each request pays a
+// full round trip; over-reading a bit is far cheaper than another round trip.
+const DEFAULT_CHUNK_BYTES = 1024 * 1024;
+const DEFAULT_CACHE_BYTES = 128 * 1024 * 1024;
+
+export type RemoteFileStorageOptions = {
+    // Bytes per cached chunk (aligned). Reads coalesce/serve from these.
+    chunkBytes?: number;
+    // Max total bytes held in the range cache (LRU eviction).
+    cacheBytes?: number;
+    // Artificial per-request delay, for simulating network latency in tests.
+    latencyMs?: number;
+};
+
+type Connection = {
+    url: string;
+    password: string;
+    latencyMs: number;
+    agent: https.Agent | undefined;
+    cache: RangeCache;
+    // Observable stats (handy for tests / diagnostics).
+    stats: { requestCount: number; bytesFetched: number };
+};
+
+const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
+
+// One HTTP request. Node uses the https module (self-signed cert → verification disabled); the browser
+// uses fetch (the user accepts the self-signed cert once). Returns the raw status + body bytes.
+async function httpRequest(conn: Connection, method: string, op: string, params: Record<string, string>, body?: Buffer): Promise<{ status: number; body: Buffer }> {
+    if (conn.latencyMs > 0) await sleep(conn.latencyMs);
+    conn.stats.requestCount++;
+    const qs = new URLSearchParams(params).toString();
+    const fullUrl = conn.url.replace(/\/+$/, "") + op + (qs ? "?" + qs : "");
+    const headers: Record<string, string> = { authorization: "Bearer " + conn.password };
+    if (body) headers["content-type"] = "application/octet-stream";
+
+    if (isNode()) {
+        return await new Promise((resolve, reject) => {
+            const u = new URL(fullUrl);
+            const req = https.request({
+                hostname: u.hostname, port: u.port, path: u.pathname + u.search, method, headers, agent: conn.agent,
+            }, res => {
+                const chunks: Buffer[] = [];
+                res.on("data", d => chunks.push(d as Buffer));
+                res.on("end", () => resolve({ status: res.statusCode || 0, body: Buffer.concat(chunks) }));
+            });
+            req.on("error", reject);
+            if (body) req.write(body);
+            req.end();
+        });
+    }
+    const res = await fetch(fullUrl, { method, headers, body: body ? new Uint8Array(body) : undefined });
+    const buf = Buffer.from(await res.arrayBuffer());
+    return { status: res.status, body: buf };
+}
+
+async function readRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined> {
+    const r = await httpRequest(conn, "GET", "/read", { path, start: String(start), end: String(end) });
+    if (r.status === 404) return undefined;
+    if (r.status !== 200) throw new Error(`remote read failed (${r.status}): ${r.body.toString("utf8").slice(0, 200)}`);
+    conn.stats.bytesFetched += r.body.length;
+    return r.body;
+}
+
+// Caches the longest-known prefix of each aligned chunk per path. Safe because every file here is either
+// immutable (bulk files, written once under a unique name) or append-only (stream files): the bytes at a
+// given offset never change, only more are added. So a cached [0, n) of a chunk is always valid; a read
+// that needs MORE than we have refetches (and picks up appended bytes). It never distinguishes file
+// types — it only does range reads.
+class RangeCache {
+    private chunks = new Map<string, Buffer>(); // key: path + "
" + chunkIndex (insertion-ordered → LRU)
+    private bytes = 0;
+    constructor(private chunkBytes: number, private budget: number) { }
+
+    private key(path: string, c: number) { return path + "
" + c; }
+    private peek(path: string, c: number): Buffer | undefined {
+        const k = this.key(path, c);
+        const v = this.chunks.get(k);
+        if (v) { this.chunks.delete(k); this.chunks.set(k, v); } // bump to most-recent
+        return v;
+    }
+    private store(path: string, c: number, buf: Buffer) {
+        const k = this.key(path, c);
+        const ex = this.chunks.get(k);
+        if (ex && ex.length >= buf.length) { this.chunks.delete(k); this.chunks.set(k, ex); return; } // keep longer prefix
+        if (ex) this.bytes -= ex.length;
+        this.chunks.delete(k);
+        this.chunks.set(k, buf);
+        this.bytes += buf.length;
+        while (this.bytes > this.budget && this.chunks.size > 0) {
+            const oldest = this.chunks.keys().next().value as string;
+            this.bytes -= (this.chunks.get(oldest) as Buffer).length;
+            this.chunks.delete(oldest);
+        }
+    }
+    invalidate(path: string) {
+        const prefix = path + "
";
+        for (const k of [...this.chunks.keys()]) {
+            if (k.startsWith(prefix)) { this.bytes -= (this.chunks.get(k) as Buffer).length; this.chunks.delete(k); }
+        }
+    }
+
+    async getRange(conn: Connection, path: string, start: number, end: number): Promise<Buffer | undefined> {
+        if (end <= start) return EMPTY;
+        const CHUNK = this.chunkBytes;
+        const firstChunk = Math.floor(start / CHUNK);
+        const lastChunk = Math.floor((end - 1) / CHUNK);
+        // Find the contiguous span of chunks we don't have enough of, and fetch it in one request.
+        let fetchFrom = -1, fetchTo = -1;
+        for (let c = firstChunk; c <= lastChunk; c++) {
+            const cStart = c * CHUNK;
+            const needEnd = Math.min(end, cStart + CHUNK) - cStart;
+            const have = this.peek(path, c);
+            if (!have || have.length < needEnd) { if (fetchFrom < 0) fetchFrom = c; fetchTo = c; }
+        }
+        if (fetchFrom >= 0) {
+            const bytes = await readRange(conn, path, fetchFrom * CHUNK, (fetchTo + 1) * CHUNK);
+            if (bytes === undefined) return undefined; // file missing
+            for (let c = fetchFrom; c <= fetchTo; c++) {
+                const off = (c - fetchFrom) * CHUNK;
+                if (off >= bytes.length) break; // hit EOF — no bytes for this chunk
+                this.store(path, c, bytes.subarray(off, Math.min(off + CHUNK, bytes.length)));
+            }
+        }
+        const parts: Buffer[] = [];
+        for (let c = firstChunk; c <= lastChunk; c++) {
+            const cStart = c * CHUNK;
+            const from = Math.max(start, cStart) - cStart;
+            const to = Math.min(end, cStart + CHUNK) - cStart;
+            const chunk = this.peek(path, c);
+            if (!chunk || chunk.length < to) {
+                // File ended before the requested end — return what's available (callers read within EOF).
+                if (chunk && chunk.length > from) parts.push(chunk.subarray(from, chunk.length));
+                break;
+            }
+            parts.push(chunk.subarray(from, to));
+        }
+        return parts.length === 1 ? parts[0] : Buffer.concat(parts);
+    }
+}
+
+function makeStorage(conn: Connection, basePath: string): FileStorage {
+    const rel = (key: string) => basePath ? basePath + "/" + key : key;
+
+    const folder: NestedFileStorage = {
+        async hasKey(key: string): Promise<boolean> {
+            const r = await httpRequest(conn, "GET", "/hasDir", { path: rel(key) });
+            if (r.status !== 200) return false;
+            return !!JSON.parse(r.body.toString("utf8")).exists;
+        },
+        async getStorage(key: string): Promise<FileStorage> {
+            return makeStorage(conn, rel(key));
+        },
+        async removeStorage(key: string): Promise<void> {
+            await httpRequest(conn, "DELETE", "/removeDir", { path: rel(key) });
+            conn.cache.invalidate(rel(key));
+        },
+        async getKeys(): Promise<string[]> {
+            const r = await httpRequest(conn, "GET", "/list", { path: basePath, folders: "1" });
+            if (r.status !== 200) throw new Error(`remote list failed (${r.status})`);
+            return JSON.parse(r.body.toString("utf8"));
+        },
+    };
+
+    return {
+        async getInfo(key: string) {
+            const r = await httpRequest(conn, "GET", "/info", { path: rel(key) });
+            if (r.status === 404) return undefined;
+            if (r.status !== 200) throw new Error(`remote info failed (${r.status})`);
+            return JSON.parse(r.body.toString("utf8")) as { size: number; lastModified: number };
+        },
+        async get(key: string) {
+            const info = await this.getInfo(key);
+            if (!info) return undefined;
+            return this.getRange(key, { start: 0, end: info.size });
+        },
+        async getRange(key: string, config: { start: number; end: number }) {
+            return conn.cache.getRange(conn, rel(key), config.start, config.end);
+        },
+        async append(key: string, value: Buffer) {
+            const r = await httpRequest(conn, "PUT", "/append", { path: rel(key) }, value);
+            if (r.status !== 200) throw new Error(`remote append failed (${r.status})`);
+            // No invalidation needed: append-only files keep their prefix; a read past it refetches.
+        },
+        async set(key: string, value: Buffer) {
+            const r = await httpRequest(conn, "PUT", "/set", { path: rel(key) }, value);
+            if (r.status !== 200) throw new Error(`remote set failed (${r.status})`);
+            conn.cache.invalidate(rel(key));
+        },
+        async remove(key: string) {
+            await httpRequest(conn, "DELETE", "/remove", { path: rel(key) });
+            conn.cache.invalidate(rel(key));
+        },
+        async getKeys(includeFolders: boolean = false) {
+            const r = await httpRequest(conn, "GET", "/list", { path: basePath, folders: includeFolders ? "1" : "0" });
+            if (r.status !== 200) throw new Error(`remote list failed (${r.status})`);
+            return JSON.parse(r.body.toString("utf8"));
+        },
+        async reset() {
+            await httpRequest(conn, "POST", "/reset", { path: basePath });
+            conn.cache.invalidate(basePath);
+        },
+        folder,
+    };
+}
+
+export type RemoteStorageFactory = ((path: string) => Promise<FileStorage>) & { stats: Connection["stats"] };
+
+// Returns a StorageFactory (path -> FileStorage) backed by a remoteFileServer.js instance. Drop-in for
+// getFileStorageNested2 in BulkDatabase2. `password` is the 6-word password the server printed.
+export function getRemoteFileStorage(url: string, password: string, options: RemoteFileStorageOptions = {}): RemoteStorageFactory {
+    const conn: Connection = {
+        url,
+        password,
+        latencyMs: options.latencyMs || 0,
+        // Self-signed cert: skip verification in Node. (The browser path uses fetch, where the user has
+        // already accepted the cert.) The password is what authorizes access.
+        agent: isNode() ? new https.Agent({ rejectUnauthorized: false }) : undefined,
+        cache: new RangeCache(options.chunkBytes || DEFAULT_CHUNK_BYTES, options.cacheBytes || DEFAULT_CACHE_BYTES),
+        stats: { requestCount: 0, bytesFetched: 0 },
+    };
+    const factory = ((path: string) => Promise.resolve(makeStorage(conn, path.replace(/^\/+|\/+$/g, "")))) as RemoteStorageFactory;
+    factory.stats = conn.stats;
+    return factory;
+}