@statewalker/file-mounts.core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{year}} Mikhail Kotelnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,317 @@
-# Temporary Holding Version
+# @statewalker/file-mounts.core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## What it is
+
+Storages mounted side by side as one `FilesApi`: a folder of the computer, the browser's private
+storage, an S3 bucket, or memory. Each storage appears at `/<key>` under a read-only root that lists
+them. The package also holds the profiles, each with an encrypted vault for its S3 keys and mounts
+(`/.settings/mounts.json` in a project is only the project's archive copy of the mounts), and a
+five-step S3 connection test that says what is wrong with a bucket instead of "failed to fetch".
+It is React-free; a view layer reads the table's `list()` and `onUpdate`.
+
+## Why it exists
+
+A files app talks to several storages at once and must keep working when one of them does not. Three
+things follow from that:
+
+- **A broken mount stays in the table.** An unusable storage (locked vault, folder access to be given
+  again, wrong keys, no answer) is mounted anyway, with a status. Every operation on it raises
+  `MountUnavailable` carrying the reason. An empty folder would look like data loss and invite
+  the person to "fix" it by saving over it.
+- **S3 is called straight from the browser.** The bucket needs a CORS rule naming the page's address,
+  and the browser reports a missing rule exactly like a dead host. The connection test tells them apart
+  and shows the rule to paste.
+- **The person's keys and storages must not sit in plain text.** Each profile's data lives in one encrypted IndexedDB record, unlocked by a password (or a passkey).
+
+## How to use
+
+```ts
+import {
+  FilesMountTable, IdbStore, Profiles, firstProfileData, localFolderMountType,
+  memoryMountType, opfsMountType, s3MountType,
+} from "@statewalker/file-mounts.core";
+
+const records = new IdbStore<unknown>("statewalker-files");
+const profiles = new Profiles({ records });
+const [first] = await profiles.load();
+const vault = first
+  ? await profiles.open(first.id) // unlocked when remembered; else vault.unlock(password, remember)
+  : await profiles.create("Personal", password, true, firstProfileData(opfsMountType().isAvailable().ok));
+
+const table = new FilesMountTable({
+  types: [
+    opfsMountType(),
+    localFolderMountType(new IdbStore("folder-handles")),
+    s3MountType({ origin: location.origin }),
+    memoryMountType(),
+  ],
+  secrets: vault,
+});
+await table.apply((await vault.read()).mounts); // creates the mounts, in parallel
+table.files; // one FilesApi: /<key>/... for every mount
+```
+
+After the person unlocks the vault, call `table.apply((await vault.read()).mounts)` again: mounts that were `locked` are
+created, mounts that are already `mounted` are kept. `apply` returns the `FileChange[]` of the mount
+roots it added, replaced or removed; nothing else announces them, so pass the list to the change hub,
+or open panels keep showing "Locked" until they are navigated again:
+
+```ts
+import { newFileChanges } from "@statewalker/file-mounts.core";
+
+const changes = newFileChanges(); // the hub panels subscribe to
+if (await vault.unlock(password, remember)) changes.emit(await table.apply((await vault.read()).mounts));
+```
+
+`table.reconnect(key)` returns only the status: after it, emit an `updated` change for `/<key>`.
+Inside a click, `table.apply(mounts, { interactive: true })` or `table.reconnect(key)` may show a
+permission prompt.
+
+`vault.lock()` does not unmount S3 storages that are already mounted: their client holds the keys
+until the next `apply` that recreates them, or a reload. Likewise, keys changed in the vault for a
+config that did not change are not picked up by `apply` (the mount is kept as is); `reconnect(key)`
+creates it again with the new keys.
+
+The main mount's project keeps archive copies of the profile. After each `vault.update(...)` that
+changes mounts or preferences, write them; *Import from this project* merges them back:
+
+```ts
+import { archiveProfile, importProfile, mergeImported } from "@statewalker/file-mounts.core";
+
+await archiveProfile(mainFiles, await vault.read()); // mainFiles: the main mount's FilesApi
+
+const archive = await importProfile(mainFiles); // show archive.problem when set
+await vault.update((d) => mergeImported(d, archive));
+```
+
+Passkeys unlock a profile beside its password (WebAuthn PRF). A `PasskeyProblem`'s `message` is what to show the person:
+
+```ts
+import { webAuthnPasskeys } from "@statewalker/file-mounts.core";
+
+const passkeys = webAuthnPasskeys({ rpName: "Files" });
+if (await passkeys.available()) await profiles.addPasskey(vault, password, passkeys);
+const unlocked = await profiles.unlockWithPasskey(passkeys, remember); // finds the profile itself
+```
+
+## What each mount type needs
+
+| Type | Needs | Notes |
+|---|---|---|
+| `local-folder` | Chromium (Chrome, Edge) | After a page reload the folder needs one click: `table.reconnect(key)` inside the handler. |
+| `opfs` | A browser with `navigator.storage.getDirectory` | Lives in the page's private storage, in the folder `mounts/<key>`. |
+| `s3` | An unlocked vault, a bucket with a CORS rule | Fields: endpoint, region, bucket, prefix, path-style, access key ID, secret access key (the last two go to the vault, as accounts `<key>/accessKeyId` and `<key>/secretAccessKey`). |
+| `memory` | nothing | Gone on reload; used by tests and demos. |
+
+A mount saved with `readOnly: true` is wrapped so writes throw; `mounted: false` keeps the settings
+without mounting.
+
+The mount key is also where a storage keeps what belongs to it: OPFS data at `mounts/<key>`, S3 keys
+in the vault under `<key>/<field>`. Changing a mount's key therefore shows an empty OPFS storage, and
+an S3 storage that says `Enter the keys for this storage in Settings → Storage.` The old data and keys
+are not deleted; they stay under the old key, unreachable until a mount uses that key again.
+
+## How S3 settings are tested and why the messages are what they are
+
+`testConnection` runs five checks in order and stops at the first failure:
+
+1. **The address answers.** A signed `ListObjectsV2` with `MaxKeys: 0` on the bucket; any HTTP answer,
+   even a refusal, counts. It is bucket-scoped because the bucket's CORS rule applies to it; a
+   service-level `ListBuckets` gets no CORS headers from AWS or R2 and would always look like CORS.
+2. **The keys are accepted.** The same call: `InvalidAccessKeyId`, `SignatureDoesNotMatch` and
+   `RequestTimeTooSkewed` fail here. `AccessDenied` and `NoSuchBucket` still mean the keys were
+   recognised; the next checks report those.
+3. **The bucket exists.** `HeadBucket`; a 403 passes, because listing says whether the bucket may be read.
+4. **Listing is allowed.** `ListObjectsV2` under the prefix.
+5. **Writing is allowed.** Puts and deletes a small object `<prefix>.<key>-write-test-<uuid>`. Skipped
+   for read-only mounts, so a read-only key is not reported as broken.
+
+Each check has a 15 s limit. The time is the point at which a person stops believing the page is
+working; a longer wait looks like a hang.
+
+A network failure is followed by an unsigned `no-cors` request to the endpoint. If that answers, the
+host is up and the browser blocked the signed call: the problem is `cors`, and the report carries the
+rule for the page's origin. If it does not answer, the problem is `unreachable`. Without this second
+request the two cases are indistinguishable in a browser.
+
+When the region is left empty, which the "Other" and R2 presets allow, the client signs with
+`us-east-1`, which is what S3-compatible servers expect by default. The AWS, MinIO / RustFS, B2 and
+Wasabi presets require a region in the form, so those are never signed with a guessed one.
+
+Messages, as the person sees them:
+
+| Situation | Message |
+|---|---|
+| Wrong keys | `Wrong access key or secret.` |
+| Clock off | `This computer's clock is off by more than 15 minutes; S3 refuses the request.` |
+| No such bucket | ``Bucket `name` not found at this endpoint.`` |
+| Not allowed to list / write | `These keys can't list this bucket.` / `These keys can't write to this bucket.` |
+| CORS rule missing | `The bucket doesn't allow this site. Add this CORS rule to the bucket:` (followed by the rule) |
+| Host dead | ``No answer from `endpoint`.`` |
+| Hang | `No answer in 15 seconds.` |
+| Vault locked | `Locked: unlock to use the S3 storages.` |
+| S3 keys not entered, or no vault created yet | `Enter the keys for this storage in Settings → Storage.` |
+| Folder access lost | ``Click Reconnect to give access to `folder` again.`` |
+| Browser without folders | `This browser can't open local folders; use Chrome or Edge.` |
+
+When an S3 mount is created, one listing runs at once, so wrong keys, a missing bucket or CORS show as
+the mount's status and not as an empty folder later.
+
+## Examples
+
+Test settings before saving them:
+
+```ts
+import { testConnection } from "@statewalker/file-mounts.core";
+
+const report = await testConnection(
+  { key: "archive", name: "Archive", type: "s3", config: { endpoint: "http://127.0.0.1:9000", bucket: "files" } },
+  { accessKeyId: "...", secretAccessKey: "..." },
+  { origin: location.origin },
+);
+if (!report.ok) console.log(report.problem?.message, report.problem?.fix?.json);
+```
+
+Read a mount that cannot be used:
+
+```ts
+import { MountUnavailable } from "@statewalker/file-mounts.core";
+
+try {
+  for await (const _ of table.files.list("/archive")) break;
+} catch (e) {
+  if (e instanceof MountUnavailable) console.log(e.problem.cause, e.problem.message);
+}
+```
+
+Store a secret and change the password:
+
+```ts
+const vault = await profiles.create("Work", "correct horse", true); // remember: silent unlock after a reload
+await vault.set("archive/accessKeyId", "AKIA...");
+await vault.changePassword("correct horse", "battery staple"); // false when the old one is wrong
+```
+
+## Internals
+
+### How the vault protects the keys
+
+Each profile has one record, `vault:<id>`, in a single `KeyValueStore` (IndexedDB). It holds a sealed
+`ProfileData` (secrets, mounts, the main storage, preferences) and the wrapped data key. A random
+AES-GCM-256 data key seals the data; a key derived from the password with PBKDF2-SHA256 wraps the data
+key. A password change re-wraps the one data key and leaves the sealed data alone. Accounts are named
+`<mount key>/<field>`. The profile id is bound into both ciphertexts as additional data, so a record
+copied under another profile does not decrypt. Kept in clear are the profile list (`profiles`: ids
+and names) and, in each vault record, the passkey credential ids and creation times and the KDF
+parameters (salt, iterations). None of these is a secret.
+
+The default is 600 000 PBKDF2 iterations: the current OWASP guidance for SHA-256, and a fraction of a
+second on a laptop. Fewer would make a stolen record cheaper to guess against; more makes every unlock
+slow on a phone. Tests pass `iterations: 1000`.
+
+*Remember* stores the **data key**, non-extractable, at `remembered:<id>`, so the next open unlocks
+silently. It is the data key and not the password-derived key because it survives a password change
+and works after any kind of unlock; and whoever can read this browser's IndexedDB could use a
+remembered password key just as well. Writes take a Web Lock per profile and each write re-reads the
+record, so two tabs changing different things keep both.
+
+A wrong password never changes anything: `unlock` and `changePassword` return `false` and the state
+stays as it was. Both check the password against the record as it is now, so after another tab changed
+the password, the new one works in this tab too, without a reload.
+
+A lost password cannot be recovered. `profiles.remove(id)` deletes the vault and its remembered key; the
+files in the storages are not touched, but the mounts and keys must be entered again. Using a removed
+profile's vault fails with `This profile was removed.`
+
+### A passkey unlocks the vault through PRF, and the password stays
+
+The authenticator returns the same 32-byte PRF secret for this site and the fixed input
+`statewalker-files vault v1`, after verifying the person. HKDF-SHA256 with a random salt per wrap turns
+that secret into the key that wraps the data key, next to the password wrap. The passkey's user handle
+is the profile id and its user name the profile's name, so one *Unlock with a passkey* finds the
+profile. The password is checked before the passkey prompt, so a wrong one leaves no orphan passkey.
+
+Support differs: Chromium with security keys and phones, Safari 18+ with Apple Passwords, Windows Hello
+only on recent builds, Firefox unclear. `available()` asks `getClientCapabilities`. An authenticator
+that registers a passkey without PRF leaves that passkey in its own list though it unlocks nothing;
+adding then fails with "This browser can't use passkeys to unlock; use the password." Removing a passkey
+from the profile does not delete it from the authenticator, which keeps offering it and gets "This
+passkey isn't linked to a profile on this browser." There is no server, so the challenge is random and
+nothing is verified beyond the PRF secret. Keep the password: a deleted passkey would otherwise lock
+the person out.
+
+### How the table keeps working when one storage does not
+
+`apply` and `reconnect` run one after another through a queue; mounts of one `apply` are created in
+parallel. `apply` validates every key first and rejects before changing anything. A create that does
+not settle in 15 s (`createTimeoutMs`) is `failed` with `No answer in 15 seconds.`; other mounts are
+unaffected, and the queue moves on. The message names 15 seconds whatever `createTimeoutMs` is set to.
+
+The one exception is a type that declares `prompts: true` (only `local-folder`), created
+interactively (`reconnect`, or `apply` with `interactive: true`): it waits on a browser permission
+prompt, which always settles when the person answers, and timing it out would fail a folder while
+they are still reading the prompt. Every other type is timed out even inside a click, because an S3
+host that never answers would otherwise hold the queue, and every later `apply` and `reconnect`,
+forever.
+
+### The main storage is the project, and keeps an archive of the profile
+
+`canBeMain(config)` is true for `opfs`, `local-folder` and `memory`, and false for `s3`. The main
+storage is the open project and must open before anything else; an S3 storage is locked until the
+vault opens, so it cannot be the one that opens first. `firstProfileData(opfs)` is what a new profile
+starts with: one "Browser storage" mount as main, or a memory mount where OPFS is missing.
+
+`archiveProfile` writes `/.settings/mounts.json` and `/.settings/preferences.json` into the project.
+Secrets never go there: the mounts file holds configs only, and the keys stay in the vault. The vault
+always wins: `importProfile` reads the copies only on an explicit import, and `mergeImported` keeps
+the profile's own mounts and preference values, adding only the mounts with unknown keys and the
+preferences it lacks. A damaged copy brings in what can be read, and `problem` says what was left
+out, for example `1 saved storage could not be read and was left out. The archived preferences are
+damaged; they were left out.`
+
+### A save over a damaged mounts.json first keeps a backup of it
+
+`mounts.json` is the project's archive copy of the mounts. `loadMountConfigs` returns the mounts in `/.settings/mounts.json`. A file that is not valid JSON or not a
+list loads as no mounts, with `problem: "The storage settings file is damaged; it is kept as is until you save."`.
+Entries that cannot be read are left out with a problem count, for example
+`2 saved storages could not be read and were left out.` Loading never rewrites the file.
+
+The next `saveMountConfigs` writes only the mounts it is given, so the entries left out would be
+gone. Before writing, it reads the file again; if it does not load cleanly (by the same rules), its
+exact text is first copied to `mounts.damaged-<timestamp>.json` in the same folder (for example
+`/.settings/mounts.damaged-2026-10-11T09-30-00-000Z.json`). Nothing removes these backups; a file there
+means a save replaced settings that could not be read, and the lost entries can be recovered from it
+by hand.
+
+### Constraints
+
+- Mount keys are validated (`validateKey`); the key is the first path segment.
+- S3 object stores have no real folders: the prefix is part of every key, and a mount sees only below it.
+- Dependencies: `@statewalker/webrun-files*` for the `FilesApi` contract and the composite, memory,
+  browser and S3 implementations; `@aws-sdk/client-s3` for signing and the checks;
+  `@statewalker/shared-baseclass` for `onUpdate`.
+
+## Running the S3 suite against a real server
+
+The unit suite needs no S3 server or Docker:
+
+```
+pnpm --filter @statewalker/file-mounts.core test
+```
+
+The integration suite starts a RustFS container (`rustfs/rustfs:1.0.0`, a free local port, root keys
+`rustfsadmin`), creates a bucket, and checks: all five checks pass, read-only skips the write, wrong
+keys, missing bucket, files land under the prefix, a copy from one storage into S3. Docker is required;
+without it the tests are skipped. Set `RUSTFS_IMAGE` to use another image.
+
+```
+pnpm --filter @statewalker/file-mounts.core test:integration
+```
+
+The container is removed when the suite ends. A restricted user (denied write) and CORS are not
+produced here: RustFS's root keys can do everything and Node does not enforce CORS. Those outcomes are
+covered by the classifier unit tests.
+
+## License
+
+MIT

package/dist/changes.d.ts

@@ -0,0 +1,16 @@
+//#region src/changes.d.ts
+/** One change to the files: what an operation or a mount change did. */
+export interface FileChange {
+  type: "added" | "updated" | "deleted";
+  path: string;
+}
+/** The one stream of changes: panels refresh from it, an indexer will follow it. */
+export interface FileChanges {
+  subscribe(listener: (changes: readonly FileChange[]) => void): () => void;
+}
+export interface FileChangesHub extends FileChanges {
+  emit(changes: readonly FileChange[]): void;
+}
+export declare function newFileChanges(): FileChangesHub;
+//#endregion
+//# sourceMappingURL=changes.d.ts.map

package/dist/changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.d.ts","names":[],"sources":["../src/changes.ts"],"mappings":";;iBACiB;EACf;EACA;;;iBAIe;EACf,UAAU,WAAW,kBAAkB;;iBAGxB,uBAAuB;EACtC,KAAK,kBAAkB;;wBAGT,kBAAkB"}

package/dist/changes.js

@@ -0,0 +1,18 @@
+//#region src/changes.ts
+function newFileChanges() {
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		emit(changes) {
+			if (!changes.length) return;
+			for (const listener of [...listeners]) listener(changes);
+		}
+	};
+}
+//#endregion
+export { newFileChanges };
+
+//# sourceMappingURL=changes.js.map

package/dist/changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.js","names":[],"sources":["../src/changes.ts"],"sourcesContent":["/** One change to the files: what an operation or a mount change did. */\nexport interface FileChange {\n  type: \"added\" | \"updated\" | \"deleted\";\n  path: string;\n}\n\n/** The one stream of changes: panels refresh from it, an indexer will follow it. */\nexport interface FileChanges {\n  subscribe(listener: (changes: readonly FileChange[]) => void): () => void;\n}\n\nexport interface FileChangesHub extends FileChanges {\n  emit(changes: readonly FileChange[]): void;\n}\n\nexport function newFileChanges(): FileChangesHub {\n  const listeners = new Set<(changes: readonly FileChange[]) => void>();\n  return {\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    emit(changes) {\n      if (!changes.length) return;\n      for (const listener of [...listeners]) listener(changes);\n    },\n  };\n}\n"],"mappings":";AAeA,SAAgB,iBAAiC;CAC/C,MAAM,4BAAY,IAAI,IAA8C;CACpE,OAAO;EACL,UAAU,UAAU;GAClB,UAAU,IAAI,QAAQ;GACtB,aAAa,UAAU,OAAO,QAAQ;EACxC;EACA,KAAK,SAAS;GACZ,IAAI,CAAC,QAAQ,QAAQ;GACrB,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GAAG,SAAS,OAAO;EACzD;CACF;AACF"}

package/dist/connection-test.d.ts

@@ -0,0 +1,31 @@
+import { Problem } from "./problem.js";
+import { S3Form } from "./mount-config.js";
+import { CheckId } from "./s3-problems.js";
+//#region src/connection-test.d.ts
+export interface S3Probe {
+  /** An unsigned no-cors fetch: true when the host answers at all. */
+  hostAnswers(): Promise<boolean>;
+  /** Throws an S3-like error when the check fails. */
+  check(id: CheckId): Promise<void>;
+}
+export interface ConnectionReport {
+  ok: boolean;
+  checks: {
+    id: CheckId;
+    label: string;
+    state: "ok" | "failed" | "skipped" | "not-run";
+  }[];
+  problem?: Problem;
+}
+export declare const CHECK_LABELS: Record<CheckId, string>;
+export declare const CHECK_ORDER: CheckId[];
+export declare function runConnectionTest(probe: S3Probe, form: Pick<S3Form, "endpoint" | "bucket" | "readOnly">, opts: {
+  origin: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}): Promise<ConnectionReport>;
+export type ProbeScenario = "ok" | "bad-keys" | "clock-skew" | "no-bucket" | "denied-list" | "denied-write" | "cors" | "unreachable" | "timeout";
+/** A scripted probe for stories and tests; each check waits `delayMs` so progress is visible. */
+export declare function fakeProbe(scenario: ProbeScenario, delayMs?: number): S3Probe;
+//#endregion
+//# sourceMappingURL=connection-test.d.ts.map

package/dist/connection-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-test.d.ts","names":[],"sources":["../src/connection-test.ts"],"mappings":";;;;iBAIiB;;EAEf,eAAe;;EAEf,MAAM,IAAI,UAAU;;iBAGL;EACf;EACA;IAAU,IAAI;IAAS;IAAe;;EACtC,UAAU;;qBAGC,cAAc,OAAO;qBAOrB,aAAa;wBAiDJ,kBACpB,OAAO,SACP,MAAM,KAAK,6CACX;EAAQ;EAAgB,SAAS;EAAa;IAC7C,QAAQ;YA+BC;;wBAqCI,UAAU,UAAU,eAAe,mBAAc"}

package/dist/connection-test.js

@@ -0,0 +1,152 @@
+import { classifyS3Error } from "./s3-problems.js";
+//#region src/connection-test.ts
+const CHECK_LABELS = {
+	endpoint: "The address answers",
+	keys: "The keys are accepted",
+	bucket: "The bucket exists",
+	list: "Listing is allowed",
+	write: "Writing is allowed"
+};
+const CHECK_ORDER = [
+	"endpoint",
+	"keys",
+	"bucket",
+	"list",
+	"write"
+];
+const CANCELLED = Symbol("cancelled");
+function isNetworkError(error) {
+	const e = error;
+	return e?.name === "NetworkError" || e?.name === "TypeError" && !!e.message?.includes("Failed to fetch");
+}
+/** Runs one check, ending it with a TimeoutError after `timeoutMs` or with CANCELLED on abort. */
+function runCheck(probe, id, timeoutMs, signal) {
+	return new Promise((resolve, reject) => {
+		const finish = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		const onAbort = () => {
+			finish();
+			reject(CANCELLED);
+		};
+		const timer = setTimeout(() => {
+			finish();
+			const timeout = /* @__PURE__ */ new Error("The check timed out");
+			timeout.name = "TimeoutError";
+			reject(timeout);
+		}, timeoutMs);
+		if (signal?.aborted) return onAbort();
+		signal?.addEventListener("abort", onAbort);
+		probe.check(id).then(() => {
+			finish();
+			resolve();
+		}, (error) => {
+			finish();
+			reject(error);
+		});
+	});
+}
+async function runConnectionTest(probe, form, opts) {
+	const checks = CHECK_ORDER.map((id) => ({
+		id,
+		label: CHECK_LABELS[id],
+		state: "not-run"
+	}));
+	for (const entry of checks) {
+		if (entry.id === "write" && form.readOnly) {
+			entry.state = "skipped";
+			continue;
+		}
+		try {
+			await runCheck(probe, entry.id, opts.timeoutMs ?? 15e3, opts.signal);
+			entry.state = "ok";
+		} catch (error) {
+			if (error === CANCELLED) return {
+				ok: false,
+				checks
+			};
+			entry.state = "failed";
+			const hostAnswers = isNetworkError(error) ? await probe.hostAnswers() : void 0;
+			return {
+				ok: false,
+				checks,
+				problem: classifyS3Error(error, {
+					check: entry.id,
+					endpoint: form.endpoint,
+					bucket: form.bucket,
+					origin: opts.origin,
+					hostAnswers
+				})
+			};
+		}
+	}
+	return {
+		ok: true,
+		checks
+	};
+}
+const FAILURES = {
+	"bad-keys": {
+		id: "keys",
+		error: () => ({
+			name: "InvalidAccessKeyId",
+			message: "The access key ID does not exist."
+		})
+	},
+	"clock-skew": {
+		id: "keys",
+		error: () => ({
+			name: "RequestTimeTooSkewed",
+			message: "The difference between the request time and the server's time is too large."
+		})
+	},
+	"no-bucket": {
+		id: "bucket",
+		error: () => ({
+			name: "NoSuchBucket",
+			message: "The specified bucket does not exist."
+		})
+	},
+	"denied-list": {
+		id: "list",
+		error: () => ({
+			name: "AccessDenied",
+			message: "Access Denied"
+		})
+	},
+	"denied-write": {
+		id: "write",
+		error: () => ({
+			name: "AccessDenied",
+			message: "Access Denied"
+		})
+	},
+	cors: {
+		id: "endpoint",
+		error: () => /* @__PURE__ */ new TypeError("Failed to fetch")
+	},
+	unreachable: {
+		id: "endpoint",
+		error: () => /* @__PURE__ */ new TypeError("Failed to fetch")
+	}
+};
+/** A scripted probe for stories and tests; each check waits `delayMs` so progress is visible. */
+function fakeProbe(scenario, delayMs = 0) {
+	const wait = () => delayMs > 0 ? new Promise((r) => setTimeout(r, delayMs)) : Promise.resolve();
+	return {
+		async hostAnswers() {
+			return scenario === "cors";
+		},
+		async check(id) {
+			await wait();
+			if (scenario === "timeout" && id === "endpoint") return new Promise(() => {});
+			const failure = FAILURES[scenario];
+			if (failure && failure.id === id) throw failure.error();
+		}
+	};
+}
+//#endregion
+export { CHECK_LABELS, CHECK_ORDER, fakeProbe, runConnectionTest };
+
+//# sourceMappingURL=connection-test.js.map

package/dist/connection-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-test.js","names":[],"sources":["../src/connection-test.ts"],"sourcesContent":["import type { S3Form } from \"./mount-config.js\";\nimport type { Problem } from \"./problem.js\";\nimport { type CheckId, classifyS3Error } from \"./s3-problems.js\";\n\nexport interface S3Probe {\n  /** An unsigned no-cors fetch: true when the host answers at all. */\n  hostAnswers(): Promise<boolean>;\n  /** Throws an S3-like error when the check fails. */\n  check(id: CheckId): Promise<void>;\n}\n\nexport interface ConnectionReport {\n  ok: boolean;\n  checks: { id: CheckId; label: string; state: \"ok\" | \"failed\" | \"skipped\" | \"not-run\" }[];\n  problem?: Problem;\n}\n\nexport const CHECK_LABELS: Record<CheckId, string> = {\n  endpoint: \"The address answers\",\n  keys: \"The keys are accepted\",\n  bucket: \"The bucket exists\",\n  list: \"Listing is allowed\",\n  write: \"Writing is allowed\",\n};\nexport const CHECK_ORDER: CheckId[] = [\"endpoint\", \"keys\", \"bucket\", \"list\", \"write\"];\n\nconst CANCELLED = Symbol(\"cancelled\");\n\nfunction isNetworkError(error: unknown): boolean {\n  const e = error as { name?: string; message?: string } | null;\n  return (\n    e?.name === \"NetworkError\" ||\n    (e?.name === \"TypeError\" && !!e.message?.includes(\"Failed to fetch\"))\n  );\n}\n\n/** Runs one check, ending it with a TimeoutError after `timeoutMs` or with CANCELLED on abort. */\nfunction runCheck(\n  probe: S3Probe,\n  id: CheckId,\n  timeoutMs: number,\n  signal?: AbortSignal,\n): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    const finish = () => {\n      clearTimeout(timer);\n      signal?.removeEventListener(\"abort\", onAbort);\n    };\n    const onAbort = () => {\n      finish();\n      reject(CANCELLED);\n    };\n    const timer = setTimeout(() => {\n      finish();\n      const timeout = new Error(\"The check timed out\");\n      timeout.name = \"TimeoutError\";\n      reject(timeout);\n    }, timeoutMs);\n    if (signal?.aborted) return onAbort();\n    signal?.addEventListener(\"abort\", onAbort);\n    probe.check(id).then(\n      () => {\n        finish();\n        resolve();\n      },\n      (error) => {\n        finish();\n        reject(error);\n      },\n    );\n  });\n}\n\nexport async function runConnectionTest(\n  probe: S3Probe,\n  form: Pick<S3Form, \"endpoint\" | \"bucket\" | \"readOnly\">,\n  opts: { origin: string; signal?: AbortSignal; timeoutMs?: number },\n): Promise<ConnectionReport> {\n  const checks: ConnectionReport[\"checks\"] = CHECK_ORDER.map((id) => ({\n    id,\n    label: CHECK_LABELS[id],\n    state: \"not-run\",\n  }));\n  for (const entry of checks) {\n    if (entry.id === \"write\" && form.readOnly) {\n      entry.state = \"skipped\";\n      continue;\n    }\n    try {\n      await runCheck(probe, entry.id, opts.timeoutMs ?? 15000, opts.signal);\n      entry.state = \"ok\";\n    } catch (error) {\n      if (error === CANCELLED) return { ok: false, checks };\n      entry.state = \"failed\";\n      const hostAnswers = isNetworkError(error) ? await probe.hostAnswers() : undefined;\n      const problem = classifyS3Error(error, {\n        check: entry.id,\n        endpoint: form.endpoint,\n        bucket: form.bucket,\n        origin: opts.origin,\n        hostAnswers,\n      });\n      return { ok: false, checks, problem };\n    }\n  }\n  return { ok: true, checks };\n}\n\nexport type ProbeScenario =\n  | \"ok\"\n  | \"bad-keys\"\n  | \"clock-skew\"\n  | \"no-bucket\"\n  | \"denied-list\"\n  | \"denied-write\"\n  | \"cors\"\n  | \"unreachable\"\n  | \"timeout\";\n\nconst FAILURES: Partial<Record<ProbeScenario, { id: CheckId; error: () => unknown }>> = {\n  \"bad-keys\": {\n    id: \"keys\",\n    error: () => ({ name: \"InvalidAccessKeyId\", message: \"The access key ID does not exist.\" }),\n  },\n  \"clock-skew\": {\n    id: \"keys\",\n    error: () => ({\n      name: \"RequestTimeTooSkewed\",\n      message: \"The difference between the request time and the server's time is too large.\",\n    }),\n  },\n  \"no-bucket\": {\n    id: \"bucket\",\n    error: () => ({ name: \"NoSuchBucket\", message: \"The specified bucket does not exist.\" }),\n  },\n  \"denied-list\": { id: \"list\", error: () => ({ name: \"AccessDenied\", message: \"Access Denied\" }) },\n  \"denied-write\": {\n    id: \"write\",\n    error: () => ({ name: \"AccessDenied\", message: \"Access Denied\" }),\n  },\n  cors: { id: \"endpoint\", error: () => new TypeError(\"Failed to fetch\") },\n  unreachable: { id: \"endpoint\", error: () => new TypeError(\"Failed to fetch\") },\n};\n\n/** A scripted probe for stories and tests; each check waits `delayMs` so progress is visible. */\nexport function fakeProbe(scenario: ProbeScenario, delayMs = 0): S3Probe {\n  const wait = () =>\n    delayMs > 0 ? new Promise<void>((r) => setTimeout(r, delayMs)) : Promise.resolve();\n  return {\n    async hostAnswers() {\n      return scenario === \"cors\";\n    },\n    async check(id) {\n      await wait();\n      if (scenario === \"timeout\" && id === \"endpoint\") return new Promise<void>(() => {});\n      const failure = FAILURES[scenario];\n      if (failure && failure.id === id) throw failure.error();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { FileChange, FileChanges, FileChangesHub, newFileChanges } from "./changes.js";
+import { MountUnavailable, Problem, ProblemCause, problemOf } from "./problem.js";
+import { MountConfig, MountStatus, MountTypeId, S3Form, S3Preset, S3PresetId, S3_PRESETS, applyPreset, keyFromName, normalizeEndpoint, normalizePrefix, validateKey, validateS3Form } from "./mount-config.js";
+import { CheckId, S3ErrorLike, classifyS3Error, corsRule } from "./s3-problems.js";
+import { CHECK_LABELS, CHECK_ORDER, ConnectionReport, ProbeScenario, S3Probe, fakeProbe, runConnectionTest } from "./connection-test.js";
+import { IdbStore, KeyValueStore, MemoryStore } from "./key-value-store.js";
+import { MountContext, MountField, MountType, NeedsUserGesture } from "./mount-type.js";
+import { localFolderMountType } from "./local-folder-mount-type.js";
+import { ProfileData, SecretStore, SecretVault, SecretsLocked, VaultState } from "./secret-vault.js";
+import { canBeMain, firstProfileData } from "./main-storage.js";
+import { memoryMountType } from "./memory-mount-type.js";
+import { MOUNTS_FILE, loadMountConfigs, saveMountConfigs } from "./mount-settings-file.js";
+import { FilesMountTable, MountTable } from "./mount-table.js";
+import { opfsMountType } from "./opfs-mount-type.js";
+import { MemoryAuthenticator, PASSKEY_MESSAGES, PasskeyAuthenticator, PasskeyProblem, memoryAuthenticator, webAuthnPasskeys } from "./passkeys.js";
+import { ProfileInfo, Profiles, validateProfileName } from "./profiles.js";
+import { PROJECT_SYSTEM_DIR, ProjectArchive, archiveProfile, importProfile, mergeImported } from "./project-archive.js";
+import { S3Keys, S3Settings, newS3Probe, s3MountType, s3Settings, testConnection } from "./s3.js";
+import { unavailableFiles } from "./unavailable-files.js";
+export { CHECK_LABELS, CHECK_ORDER, CheckId, ConnectionReport, FileChange, FileChanges, FileChangesHub, FilesMountTable, IdbStore, KeyValueStore, MOUNTS_FILE, MemoryAuthenticator, MemoryStore, MountConfig, MountContext, MountField, MountStatus, MountTable, MountType, MountTypeId, MountUnavailable, NeedsUserGesture, PASSKEY_MESSAGES, PROJECT_SYSTEM_DIR, PasskeyAuthenticator, PasskeyProblem, ProbeScenario, Problem, ProblemCause, ProfileData, ProfileInfo, Profiles, ProjectArchive, S3ErrorLike, S3Form, S3Keys, S3Preset, S3PresetId, S3Probe, S3Settings, S3_PRESETS, SecretStore, SecretVault, SecretsLocked, VaultState, applyPreset, archiveProfile, canBeMain, classifyS3Error, corsRule, fakeProbe, firstProfileData, importProfile, keyFromName, loadMountConfigs, localFolderMountType, memoryAuthenticator, memoryMountType, mergeImported, newFileChanges, newS3Probe, normalizeEndpoint, normalizePrefix, opfsMountType, problemOf, runConnectionTest, s3MountType, s3Settings, saveMountConfigs, testConnection, unavailableFiles, validateKey, validateProfileName, validateS3Form, webAuthnPasskeys };

package/dist/index.js

@@ -0,0 +1,20 @@
+import { newFileChanges } from "./changes.js";
+import { classifyS3Error, corsRule } from "./s3-problems.js";
+import { CHECK_LABELS, CHECK_ORDER, fakeProbe, runConnectionTest } from "./connection-test.js";
+import { IdbStore, MemoryStore } from "./key-value-store.js";
+import { NeedsUserGesture } from "./mount-type.js";
+import { MountUnavailable, problemOf } from "./problem.js";
+import { localFolderMountType } from "./local-folder-mount-type.js";
+import { canBeMain, firstProfileData } from "./main-storage.js";
+import { memoryMountType } from "./memory-mount-type.js";
+import { S3_PRESETS, applyPreset, keyFromName, normalizeEndpoint, normalizePrefix, validateKey, validateS3Form } from "./mount-config.js";
+import { MOUNTS_FILE, loadMountConfigs, saveMountConfigs } from "./mount-settings-file.js";
+import { SecretVault, SecretsLocked } from "./secret-vault.js";
+import { unavailableFiles } from "./unavailable-files.js";
+import { FilesMountTable } from "./mount-table.js";
+import { opfsMountType } from "./opfs-mount-type.js";
+import { PASSKEY_MESSAGES, PasskeyProblem, memoryAuthenticator, webAuthnPasskeys } from "./passkeys.js";
+import { Profiles, validateProfileName } from "./profiles.js";
+import { PROJECT_SYSTEM_DIR, archiveProfile, importProfile, mergeImported } from "./project-archive.js";
+import { newS3Probe, s3MountType, s3Settings, testConnection } from "./s3.js";
+export { CHECK_LABELS, CHECK_ORDER, FilesMountTable, IdbStore, MOUNTS_FILE, MemoryStore, MountUnavailable, NeedsUserGesture, PASSKEY_MESSAGES, PROJECT_SYSTEM_DIR, PasskeyProblem, Profiles, S3_PRESETS, SecretVault, SecretsLocked, applyPreset, archiveProfile, canBeMain, classifyS3Error, corsRule, fakeProbe, firstProfileData, importProfile, keyFromName, loadMountConfigs, localFolderMountType, memoryAuthenticator, memoryMountType, mergeImported, newFileChanges, newS3Probe, normalizeEndpoint, normalizePrefix, opfsMountType, problemOf, runConnectionTest, s3MountType, s3Settings, saveMountConfigs, testConnection, unavailableFiles, validateKey, validateProfileName, validateS3Form, webAuthnPasskeys };