@brftech/filex-core 0.19.0 → 0.20.1

package/src/lib/realtime.ts

@@ -3,7 +3,7 @@
 // webcomponent embedded in host apps — gets live folder updates + presence.
 //
 // Auth: the browser's native WebSocket can't set an Authorization header and,
-// when embedded, connects cross-origin to fm.brf.sh. So instead of a header we
+// when embedded, connects cross-origin to fm.example.com. So instead of a header we
 // fetch a short-lived, single-use TICKET through the host's normal API (which
 // injects the real token server-side) and open `wss://…/api/ws?ticket=<t>`.
 // The durable token never reaches the browser.

package/src/lib/uploadResume.ts

@@ -0,0 +1,157 @@
+/**
+ * uploadResume — where a browser upload writes down that it is not finished.
+ *
+ * A staged upload survives a dropped connection because the SERVER holds the
+ * bytes and can be asked for its offset. What the browser has to survive is
+ * itself: a reloaded tab, a closed laptop, a crashed renderer. None of those
+ * reach the server, and without a note on disk the next visit has no idea an
+ * upload id ever existed — so the same 4 GB starts again at zero, which is the
+ * exact complaint this work exists to answer.
+ *
+ * The note is deliberately small and deliberately a hint:
+ *
+ *   - it stores the upload id, not the bytes. localStorage cannot hold a File,
+ *     and the browser will not hand a File back without a fresh user gesture.
+ *     Recovery is therefore "pick the same file again and it continues", not
+ *     "it silently continues" — the honest shape, and the one the platform
+ *     allows.
+ *   - `offset` here is never used as a resume point. It is shown to the user
+ *     ("resuming at 62%") and used to decide a session is worth asking about;
+ *     the byte to continue from always comes from GET /api/files/upload/{id}.
+ *
+ * The fingerprint pins a record to one file: name, size and lastModified. A
+ * different file with the same name must not inherit the session, because
+ * appending its tail to the previous head is the one way a resumable upload
+ * corrupts data.
+ *
+ * This lives in `packages/core` because it is not browser-chrome: the web
+ * explorer, the desktop app's explorer and the work.example.com / fishapp embeds all
+ * mount the same component, and an upload that resumes in one of them and not
+ * the others would be two products again.
+ */
+
+const STORE_KEY = 'filex:uploads:v1';
+
+/** How long an unfinished record is worth keeping. The server sweeps its own
+ *  staging after FILEX_UPLOAD_STAGING_TTL (24 h by default); a note that
+ *  outlives the bytes it describes only produces a confusing "resuming…" that
+ *  immediately restarts. */
+export const RESUME_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface ResumeRecord {
+  /** Server-side staged upload id. */
+  uploadId: string;
+  /** Destination directory, qualified (`adapter://sub/dir`). */
+  path: string;
+  name: string;
+  size: number;
+  /** File.lastModified — part of the identity, not metadata. */
+  lastModified: number;
+  chunkSize: number;
+  /** Last offset the server acknowledged. Display + triage only. */
+  offset: number;
+  updatedAt: number;
+}
+
+/** Identity of one (destination, file) pair. */
+export function uploadFingerprint(
+  path: string,
+  file: { name: string; size: number; lastModified?: number },
+): string {
+  return [path, file.name, file.size, file.lastModified ?? 0].join('\u0000');
+}
+
+type Store = Record<string, ResumeRecord>;
+
+/** A Storage-shaped thing. Injected so tests (and any surface without
+ *  localStorage — SSR, a locked-down embed) do not have to fake globals. */
+export interface ResumeStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/** The default backing store, or null where the platform has none. Reading
+ *  localStorage throws in a partitioned/blocked context, so the probe is a real
+ *  try, not a typeof check. */
+export function defaultResumeStorage(): ResumeStorage | null {
+  try {
+    if (typeof localStorage === 'undefined') return null;
+    localStorage.getItem(STORE_KEY);
+    return localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function read(store: ResumeStorage | null): Store {
+  if (!store) return {};
+  try {
+    const raw = store.getItem(STORE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as Store;
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    // Corrupt payload: an upload that starts over is a far smaller problem
+    // than one that throws on every page load.
+    return {};
+  }
+}
+
+function write(store: ResumeStorage | null, data: Store): void {
+  if (!store) return;
+  try {
+    store.setItem(STORE_KEY, JSON.stringify(data));
+  } catch {
+    /* quota / private mode — resume degrades, uploads still work */
+  }
+}
+
+/** Drop records older than RESUME_TTL_MS. Returns what survived. */
+export function pruneResume(store: ResumeStorage | null, now = Date.now()): Store {
+  const data = read(store);
+  let changed = false;
+  for (const [key, rec] of Object.entries(data)) {
+    if (!rec?.uploadId || now - (rec.updatedAt ?? 0) > RESUME_TTL_MS) {
+      delete data[key];
+      changed = true;
+    }
+  }
+  if (changed) write(store, data);
+  return data;
+}
+
+/** The record for this exact (destination, file), or null. */
+export function loadResume(
+  store: ResumeStorage | null,
+  key: string,
+  now = Date.now(),
+): ResumeRecord | null {
+  const rec = pruneResume(store, now)[key];
+  return rec ?? null;
+}
+
+export function saveResume(
+  store: ResumeStorage | null,
+  key: string,
+  rec: Omit<ResumeRecord, 'updatedAt'>,
+  now = Date.now(),
+): void {
+  const data = read(store);
+  data[key] = { ...rec, updatedAt: now };
+  write(store, data);
+}
+
+export function clearResume(store: ResumeStorage | null, key: string): void {
+  const data = read(store);
+  if (key in data) {
+    delete data[key];
+    write(store, data);
+  }
+}
+
+/** Every unfinished upload this browser knows about, newest first. Surfaces
+ *  use it to say "you have an unfinished upload" instead of forgetting. */
+export function listResume(store: ResumeStorage | null, now = Date.now()): ResumeRecord[] {
+  return Object.values(pruneResume(store, now)).sort((a, b) => b.updatedAt - a.updatedAt);
+}

package/src/locales/en.ts

@@ -59,6 +59,9 @@ export const en: Record<string, string> = {
   'upload.failed': 'Could not upload “{name}”',
   'upload.aborted': 'Aborted',
   'upload.cancel': 'Cancel',
+  'upload.resuming': 'Resuming “{name}” from {percent}%',
+  'upload.committing': 'Finishing',
+  'upload.transferring': 'Moving to storage',
 
   'empty.folder': 'This folder is empty',
   'empty.search': 'No results',
@@ -407,4 +410,414 @@ export const en: Record<string, string> = {
   'e2e.decrypt_failed': 'Could not decrypt the file (password changed or file corrupted).',
   'e2e.download.failed': 'Could not download the encrypted file.',
   /* /wiring:e2 */
+
+  /* ── connections: storage config + "how to connect" ──────────────
+     `storages.*` keys are the ones the BACKEND's driver descriptors
+     name (each driver package declares one next to its Init). They are
+     kept identical to web/src/locales/*.json on purpose: the same
+     descriptor is rendered on both surfaces, so a field that reads
+     "Base path" in the admin panel and something else in the desktop
+     app would be the same drift this whole mechanism exists to stop. */
+  'conn.title': 'Storage connections',
+  'conn.subtitle': 'Connect {host} to a backend, or connect your computer to {host}.',
+  'conn.close': 'Close',
+  'conn.tab.storages': 'Storages',
+  'conn.tab.connect': 'How to connect',
+  'conn.loading': 'Loading…',
+  'conn.visibleOnly': 'you can browse this one',
+  'conn.denied.title': 'Only an administrator can add storages here',
+  'conn.denied.none': 'Your account may browse files but not change what this server is connected to. Ask an administrator of this server to add or edit a storage.',
+  'conn.denied.anonymous': 'You are not signed in on this server.',
+  'conn.denied.unreachable': 'The server did not answer: {error}',
+  'conn.denied.guideHint': 'You do not need administrator rights to connect your own computer to the storages you can already see.',
+  'conn.denied.guideCta': 'Show me how to connect',
+  'conn.list.count': '{n} storage(s)',
+  'conn.list.add': 'Add a storage',
+  'conn.list.empty': 'No storage is configured yet. Add one and the files show up in the explorer.',
+  'conn.list.edit': 'Edit',
+  'conn.list.remove': 'Remove',
+  'conn.list.confirm': 'Really remove?',
+  'conn.list.readOnly': 'read-only',
+  'conn.list.disabled': 'disabled',
+  'conn.form.newTitle': 'New storage',
+  'conn.form.editTitle': 'Edit “{name}”',
+  'conn.form.name': 'Display name',
+  'conn.form.namePlaceholder': 'photos',
+  'conn.form.nameHelp': 'What this storage is called everywhere: in the explorer, in paths (name://folder) and in WebDAV URLs.',
+  'conn.form.driver': 'Type',
+  'conn.form.driverLocked': 'A storage\'s type cannot change after it is created — the paths already point at it.',
+  'conn.form.readOnly': 'Read-only (nothing may be written to this storage)',
+  'conn.form.enabled': 'Enabled',
+  'conn.form.test': 'Test connection',
+  'conn.form.testing': 'Testing…',
+  'conn.form.testOk': 'Connected. {count} item(s) at the root.',
+  'conn.form.testFail': 'Could not connect: {error}',
+  'conn.form.save': 'Save',
+  'conn.form.saving': 'Saving…',
+  'conn.form.cancel': 'Cancel',
+  'conn.form.nameRequired': 'Give the storage a name.',
+  'conn.form.fillRequired': 'Fill in the fields marked with *.',
+  'conn.form.required': 'Required',
+  'conn.form.advanced': 'Advanced settings',
+  'conn.form.noFields': 'This server did not describe any settings for this driver.',
+  'conn.form.reveal': 'Show',
+  'conn.form.hide': 'Hide',
+  'conn.guide.protocol': 'Protocol',
+  'conn.guide.storage': 'Storage',
+  'conn.guide.allStorages': 'All storages',
+  'conn.guide.copy': 'Copy',
+  'conn.guide.copied': 'Copied',
+  'conn.guide.goodToKnow': 'Good to know',
+  'conn.guide.userPlaceholder': 'your-email@example.com',
+  'conn.guide.secretPlaceholder': 'your-password-or-token',
+  'conn.guide.fact.url': 'Address',
+  'conn.guide.fact.urlRootHint': 'Every storage you can see appears as a folder under this address.',
+  'conn.guide.fact.urlStorageHint': 'Mounts “{storage}” directly. Drop the last segment to see every storage.',
+  'conn.guide.fact.user': 'Username',
+  'conn.guide.fact.password': 'Password',
+  'conn.guide.webdav.summary': 'WebDAV mounts filex as a drive: Windows Explorer, macOS Finder, Linux, rclone and Cyberduck all speak it, and every change is mirrored back into filex.',
+  'conn.guide.webdav.userHint': 'Your filex account e-mail — not a display name.',
+  'conn.guide.webdav.passwordHint': 'Your account password, or an API token (Settings → API tokens). An account with two-factor authentication MUST use a token: Basic auth has no second-factor slot.',
+  'conn.guide.webdav.win.s1': 'Open File Explorer, right-click This PC and choose “Map network drive…”.',
+  'conn.guide.webdav.win.s2': 'Pick a drive letter and enter {url} as the folder.',
+  'conn.guide.webdav.win.s3': 'Tick “Connect using different credentials” and sign in with the username and password above.',
+  'conn.guide.webdav.win.cmdCaption': 'Command Prompt (same thing, without the wizard)',
+  'conn.guide.webdav.win.limits': 'Windows has three built-in limits that look exactly like filex bugs: transfers stop at ~47.7 MB, folders with about a thousand files refuse to open (“Disk is not formatted”), and the WebClient service must be restarted after changing either.',
+  'conn.guide.webdav.win.regCaption': 'Run as administrator, then reconnect the drive',
+  'conn.guide.webdav.win.https': 'HTTPS is mandatory. Windows sends Basic credentials over TLS only, and over plain http:// it silently refuses with no useful message. Do not set BasicAuthLevel to 2 — use TLS.',
+  'conn.guide.webdav.win.persist': 'The mapped drive does not survive a sign-out: since Windows 7 Basic credentials cannot be stored in Credential Manager, and /persistent:yes does not change that. Re-run the command from a logon script if you need it back automatically.',
+  'conn.guide.webdav.win.service': 'If nothing mounts at all, make sure the WebClient service is running: sc config WebClient start= auto && net start WebClient.',
+  'conn.guide.webdav.mac.s1': 'In Finder choose Go → Connect to Server… (⌘K).',
+  'conn.guide.webdav.mac.s2': 'Enter {url} and connect.',
+  'conn.guide.webdav.mac.s3': 'Authenticate with the username and password above.',
+  'conn.guide.webdav.mac.note': 'The drive appears under Locations; each storage is a top-level folder.',
+  'conn.guide.webdav.linux.mountCaption': 'davfs2, or the desktop file manager (GNOME Files, Dolphin)',
+  'conn.guide.webdav.linux.gvfsComment': 'or paste this address into GNOME Files / Dolphin',
+  'conn.guide.webdav.linux.locks': 'davfs2 needs locking turned off. filex keeps WebDAV locks in process memory, so they do not survive a restart and are not shared between replicas — davfs2 assumes otherwise and hangs.',
+  'conn.guide.webdav.rclone.obscureCaption': 'rclone stores an obscured password — run this first and paste the output below',
+  'conn.guide.webdav.rclone.passPlaceholder': '<output of rclone obscure>',
+  'conn.guide.webdav.rclone.useCaption': 'Using it',
+  'conn.guide.webdav.duck.s1': 'New Bookmark → WebDAV (HTTPS).',
+  'conn.guide.webdav.duck.s2': 'Server {host}, port 443.',
+  'conn.guide.webdav.duck.s3': 'Path {path}.',
+  'conn.guide.webdav.duck.s4': 'Username {user}, password as above.',
+  'conn.guide.webdav.note.delete': 'A WebDAV delete is permanent. The web UI moves files to the filex trash; a client delete removes the object from the backing storage directly.',
+  'conn.guide.webdav.note.locks': 'Locks live in server memory: they do not survive a restart and are not shared between replicas. They exist to satisfy Windows and Office, not to arbitrate concurrent edits.',
+  'conn.guide.webdav.note.permissions': 'You see exactly what you see in the web UI. The root lists only the storages you may open, and a path outside your grants answers 404 rather than 403, so the tree never leaks what exists.',
+  'conn.guide.webdav.note.http': 'This server is reachable over plain http://. Windows will refuse to send your credentials at all, and every other client sends your password in the clear. Put filex behind TLS before mounting it.',
+  // ── S3 endpoint: keys and the guide ──────────────────────────────
+  'conn.s3keys.title': 'S3 access keys',
+  'conn.s3keys.lead': 'An access key lets any S3 client — rclone, restic, the AWS CLI, mc, s3fs, Cyberduck — connect to filex. It carries your own permissions and nothing more.',
+  'conn.s3keys.disabled': 'The S3 endpoint is switched off on this server (FILEX_S3). A key minted here will not connect until an operator turns it back on.',
+  'conn.s3keys.cannotMint': 'You are not signed in with an account that can mint access keys. The instructions below still apply — ask for a key and paste it in.',
+  'conn.s3keys.label': 'What is it for? (laptop backup, CI, …)',
+  'conn.s3keys.defaultLabel': 'access key',
+  'conn.s3keys.everyBucket': 'Every bucket I can see',
+  'conn.s3keys.prefix': 'Folder inside the bucket (optional)',
+  'conn.s3keys.mint': 'Create key',
+  'conn.s3keys.inheritNote': 'A key can only ever narrow what you already have: your grants, your tenant, your role. Confining it to one bucket or folder is the difference between a laptop backup and a credential that can read everything.',
+  'conn.s3keys.once': 'Copy the secret now — this is the only time it is shown.',
+  'conn.s3keys.accessKeyID': 'Access key ID',
+  'conn.s3keys.secret': 'Secret key',
+  'conn.s3keys.dismiss': 'I have copied it',
+  'conn.s3keys.col.label': 'Label',
+  'conn.s3keys.col.key': 'Access key ID',
+  'conn.s3keys.col.scope': 'Limited to',
+  'conn.s3keys.col.lastUsed': 'Last used',
+  'conn.s3keys.scopeAll': 'everything you can see',
+  'conn.s3keys.noLabel': '(no label)',
+  'conn.s3keys.neverUsed': 'never',
+  'conn.s3keys.enable': 'Enable',
+  'conn.s3keys.disable': 'Disable',
+  'conn.s3keys.revoke': 'Revoke',
+  'conn.s3keys.confirm': 'Sure?',
+  'conn.s3keys.empty': 'No access keys yet.',
+  'conn.guide.s3.summary': 'The S3 endpoint makes filex the destination for anything that speaks S3 — backups, sync tools, SDKs — using the storages you already have.',
+  'conn.guide.s3.keyPlaceholder': 'create a key above',
+  'conn.guide.s3.secretPlaceholder': 'shown once, when you create the key',
+  'conn.guide.s3.fact.endpoint': 'Endpoint',
+  'conn.guide.s3.fact.endpointHint': 'Point the client here, not at the web address of filex.',
+  'conn.guide.s3.fact.bucket': 'Bucket',
+  'conn.guide.s3.fact.bucketHint': 'A bucket is a filex storage. Buckets are created by an administrator, not by the client.',
+  'conn.guide.s3.fact.key': 'Access key ID',
+  'conn.guide.s3.fact.keyHint': 'The public half. It travels in every request.',
+  'conn.guide.s3.fact.secret': 'Secret key',
+  'conn.guide.s3.fact.secretHint': 'Shown once, when the key is created. filex cannot show it again — create a new key if it is lost.',
+  'conn.guide.s3.fact.region': 'Region',
+  'conn.guide.s3.fact.regionHint': 'filex has no regions; any value works and is echoed back. Clients still insist on one.',
+  'conn.guide.s3.fact.addressing': 'Addressing',
+  'conn.guide.s3.fact.pathStyle': 'path-style (required)',
+  'conn.guide.s3.fact.pathStyleHint': 'There is no dedicated S3 host on this install, so bucket.host does not resolve.',
+  'conn.guide.s3.fact.virtualHosted': 'virtual-hosted or path-style',
+  'conn.guide.s3.fact.virtualHostedHint': 'This install has its own S3 host, so both styles work.',
+  'conn.guide.s3.rclone.useCaption': 'Use it',
+  'conn.guide.s3.rclone.mtime': 'filex carries the file modification time (x-amz-meta-mtime), so rclone sync settles after the first run instead of re-uploading everything.',
+  'conn.guide.s3.aws.configureCaption': 'Configure once',
+  'conn.guide.s3.aws.useCaption': 'Use it',
+  'conn.guide.s3.aws.pathStyle': 'Add path addressing to your AWS config, or every command fails at DNS.',
+  'conn.guide.s3.restic.envCaption': 'Environment',
+  'conn.guide.s3.restic.useCaption': 'Back up, verify, prune',
+  'conn.guide.s3.restic.verified': 'Verified against this endpoint: restic check --read-data reads every pack byte for byte and reports no errors.',
+  'conn.guide.s3.mc.aliasCaption': 'Add the alias',
+  'conn.guide.s3.mc.useCaption': 'Use it',
+  'conn.guide.s3.s3fs.credsCaption': 'Credentials file',
+  'conn.guide.s3.s3fs.mountCaption': 'Mount it',
+  'conn.guide.s3.s3fs.note': 'Editing a file over s3fs rewrites the whole object, and a delete goes to the filex trash. Good for a shared folder, not for a database.',
+  'conn.guide.s3.duck.s1': 'New bookmark → Amazon S3.',
+  'conn.guide.s3.duck.s2': 'Server: {host}.',
+  'conn.guide.s3.duck.s3': 'Access key ID: {key}, secret as above.',
+  'conn.guide.s3.duck.s4': 'Open the bookmark; the buckets are your filex storages.',
+  'conn.guide.s3.duck.pathStyle': 'In Preferences → S3, turn OFF "Use virtual host style" — this install has no wildcard S3 host.',
+  'conn.guide.s3.sdk.note': 'Any SigV4 client works the same way: endpoint, key, secret, and path addressing when this install has no S3 host of its own.',
+  'conn.guide.s3.note.buckets': 'A bucket is a filex storage. A client can create folders and objects inside one, but not the bucket itself — that needs a driver and a path, which an S3 request cannot express.',
+  'conn.guide.s3.note.permissions': 'The key sees exactly what you see. A bucket you may not open answers "no such bucket" rather than "forbidden", so the endpoint never reveals what exists.',
+  'conn.guide.s3.note.trash': 'A delete goes to the filex trash, the same as everywhere else, and is recoverable until the retention policy sweeps it.',
+  'conn.guide.s3.note.mtime': 'Uploads carry their modification time, and the checksums clients send (Content-MD5, x-amz-checksum-*) are verified — a corrupted upload is refused rather than stored.',
+  'conn.guide.s3.note.pathStyle': 'This install has no dedicated S3 host, so clients must be told to use path-style addressing. Without it a current SDK fails at DNS with an error that names neither filex nor the cause.',
+  'conn.guide.s3.note.http': 'This endpoint is plain http://. Signatures still protect the request, but the objects travel in the clear. Put filex behind TLS before pointing a backup at it.',
+  // ── SFTP endpoint: keys and the guide ────────────────────────────
+  'conn.sshkeys.title': 'SSH keys',
+  'conn.sshkeys.lead': 'Register a public key and every SSH client — sftp, scp, WinSCP, FileZilla, rclone, sshfs — can connect without sending your password.',
+  'conn.sshkeys.disabled': 'The SFTP endpoint is switched off on this server (FILEX_SFTP). A key registered here will not connect until an operator turns it back on.',
+  'conn.sshkeys.cannotAdd': 'You are not signed in with an account that can register keys.',
+  'conn.sshkeys.paste': 'Paste the contents of ~/.ssh/id_ed25519.pub',
+  'conn.sshkeys.name': 'Name (optional — the key comment is used otherwise)',
+  'conn.sshkeys.add': 'Add key',
+  'conn.sshkeys.noCopyId': 'ssh-copy-id cannot work here: it appends to ~/.ssh/authorized_keys over a shell, and filex has none. This box is the way in.',
+  'conn.sshkeys.col.name': 'Name',
+  'conn.sshkeys.col.fingerprint': 'Fingerprint',
+  'conn.sshkeys.col.added': 'Added',
+  'conn.sshkeys.col.lastUsed': 'Last used',
+  'conn.sshkeys.noName': '(no name)',
+  'conn.sshkeys.neverUsed': 'never',
+  'conn.sshkeys.enable': 'Enable',
+  'conn.sshkeys.disable': 'Disable',
+  'conn.sshkeys.remove': 'Remove',
+  'conn.sshkeys.confirm': 'Sure?',
+  'conn.sshkeys.empty': 'No keys yet. Without one, clients sign in with your account password.',
+  'conn.guide.sftp.summary': 'SFTP makes filex reachable by anything that already speaks SSH — a backup job, a scanner, WinSCP, rclone, or a mounted folder.',
+  'conn.guide.sftp.fact.host': 'Host',
+  'conn.guide.sftp.fact.hostHint': 'The same machine as the web app, on a port of its own.',
+  'conn.guide.sftp.fact.port': 'Port',
+  'conn.guide.sftp.fact.portHint': 'Not 22 and not 443: SFTP is raw TCP and cannot go through the web proxy.',
+  'conn.guide.sftp.fact.userHint': 'Your short login name. An @ in a login has to be quoted in most client config files, which is what this avoids.',
+  'conn.guide.sftp.fact.auth': 'Sign in with',
+  'conn.guide.sftp.fact.authKey': 'your registered SSH key (or your password)',
+  'conn.guide.sftp.fact.authPassword': 'your account password — or register a key above',
+  'conn.guide.sftp.fact.authHint': 'An API token works as a password too, and is revocable on its own. An account with two-factor sign-in must use a key or a token.',
+  'conn.guide.sftp.fact.path': 'Path',
+  'conn.guide.sftp.fact.pathHint': 'The first folder is a storage; the root lists the ones you may open.',
+  'conn.guide.sftp.openssh.connectCaption': 'Connect, put, get',
+  'conn.guide.sftp.openssh.noShell': 'There is no shell here — only the SFTP subsystem. `ssh host command` is refused on purpose, and scp works because OpenSSH 9 speaks SFTP for it.',
+  'conn.guide.sftp.key.tab': 'Set up a key',
+  'conn.guide.sftp.key.s1': 'Generate a key pair on the machine that will connect (skip if you already have one).',
+  'conn.guide.sftp.key.s2': 'Copy the PUBLIC half — the .pub file, never the other one.',
+  'conn.guide.sftp.key.s3': 'Paste it into the box above and connect; no password is sent from then on.',
+  'conn.guide.sftp.key.genCaption': 'On your own machine',
+  'conn.guide.sftp.key.noCopyId': 'ssh-copy-id will NOT work against filex: it needs a shell to append to ~/.ssh/authorized_keys, and there is none. Paste the key above instead.',
+  'conn.guide.sftp.winscp.s1': 'New site → File protocol: SFTP.',
+  'conn.guide.sftp.winscp.s2': 'Host name: {host}, port: {port}.',
+  'conn.guide.sftp.winscp.s3': 'User name: {user}. For a key: Advanced → SSH → Authentication → private key file.',
+  'conn.guide.sftp.winscp.s4': 'WinSCP needs a .ppk private key — use its own tool (Tools → PuTTYgen) to convert an OpenSSH key once.',
+  'conn.guide.sftp.filezilla.s1': 'File → Site Manager → New site, Protocol: SFTP.',
+  'conn.guide.sftp.filezilla.s2': 'Host: {host}, port: {port}.',
+  'conn.guide.sftp.filezilla.s3': 'User: {user}. Logon type: Normal for a password, or Key file for a key.',
+  'conn.guide.sftp.rclone.useCaption': 'Use it',
+  'conn.guide.sftp.sshfs.mountCaption': 'Mount and unmount',
+  'conn.guide.sftp.sshfs.note': 'A mounted folder rewrites the whole file on every save. Good for documents, not for a database or a video you are editing in place.',
+  'conn.guide.sftp.note.storages': 'The root is not a home directory: it lists the storages you may open, and the first path segment names one.',
+  'conn.guide.sftp.note.permissions': 'The permission bits your client draws come from your access level here, so a file shown as read-only really is one for you.',
+  'conn.guide.sftp.note.trash': 'A delete goes to the filex trash, the same as everywhere else, and is recoverable until the retention policy sweeps it.',
+  'conn.guide.sftp.note.totp': 'If your account has two-factor sign-in, the password will not work here — SSH has no way to ask for the code. Register a key, or use an API token as the password.',
+  'conn.guide.sftp.note.disabled': 'The SFTP endpoint is switched off on this server. These instructions will work once an operator enables it.',
+  // ── FTPS ─────────────────────────────────────────────────────────
+  'conn.guide.ftps.summary': 'FTPS is here for the equipment that only ever learned FTP — scan-to-folder printers, EDI counterparties, older lab and industrial software. Always over TLS.',
+  'conn.guide.ftps.fact.host': 'Host',
+  'conn.guide.ftps.fact.hostHint': 'The same machine as the web app, on a port of its own.',
+  'conn.guide.ftps.fact.port': 'Port',
+  'conn.guide.ftps.fact.portHint': 'The control channel. Data moves on a separate port from the passive range below.',
+  'conn.guide.ftps.fact.mode': 'Encryption',
+  'conn.guide.ftps.fact.modeValue': 'FTPS — explicit TLS (AUTH TLS), required',
+  'conn.guide.ftps.fact.modeHint': 'Plain FTP is refused before the password is read. Choose "Require explicit FTP over TLS", never "plain FTP" and never "implicit".',
+  'conn.guide.ftps.fact.userHint': 'Your short login name, or your e-mail. An API token works as the password too and can be revoked on its own.',
+  'conn.guide.ftps.fact.passwordHint': 'Your account password, or an API token. An account with two-factor sign-in must use a token — FTP has no way to ask for the code.',
+  'conn.guide.ftps.fact.pasv': 'Passive ports',
+  'conn.guide.ftps.fact.pasvHint': 'Data connections land here. If your firewall blocks this range the transfer HANGS with no error on either side — that is the classic FTP failure.',
+  'conn.guide.ftps.filezilla.s1': 'File → Site Manager → New site, Protocol: FTP.',
+  'conn.guide.ftps.filezilla.s2': 'Host: {host}, port: {port}.',
+  'conn.guide.ftps.filezilla.s3': 'Encryption: "Require explicit FTP over TLS". Logon type: Normal, user: {user}.',
+  'conn.guide.ftps.filezilla.s4': 'Transfer settings → Passive. Active mode is refused by this server.',
+  'conn.guide.ftps.winscp.s1': 'New site → File protocol: FTP, Encryption: TLS/SSL Explicit encryption.',
+  'conn.guide.ftps.winscp.s2': 'Host name: {host}, port: {port}.',
+  'conn.guide.ftps.winscp.s3': 'User name: {user}, password as above.',
+  'conn.guide.ftps.curl.caption': 'Upload and download',
+  'conn.guide.ftps.curl.sslReqd': '--ssl-reqd is not optional: it makes curl REQUIRE TLS instead of falling back to plaintext. This server refuses plaintext anyway, but the habit protects you against the servers that do not.',
+  'conn.guide.ftps.lftp.caption': 'Connect',
+  'conn.guide.ftps.lftp.protectData': 'ssl-protect-data encrypts the FILE as well as the login. Without it lftp logs in over TLS and then sends your file in the clear — which is the FTPS misconfiguration people actually ship.',
+  'conn.guide.ftps.rclone.useCaption': 'Use it',
+  'conn.guide.ftps.printer.tab': 'Scanner / printer',
+  'conn.guide.ftps.printer.s1': 'In the device\'s scan-to-FTP settings: server {host}, port {port}.',
+  'conn.guide.ftps.printer.s2': 'User: {user}, password as above. Create an API token for the device rather than using your own password — it can be revoked without changing anything else.',
+  'conn.guide.ftps.printer.s3': 'Path: {path} — or a folder inside it that you created first. The device cannot create a storage.',
+  'conn.guide.ftps.printer.s4': 'Turn ON "SSL/TLS" or "FTPS explicit", and PASSIVE mode.',
+  'conn.guide.ftps.printer.noTLS': 'Plenty of scan-to-FTP firmware cannot do TLS at all. This server will not talk to such a device, and that is deliberate — the alternative is your documents and your password crossing the office network in the clear.',
+  'conn.guide.ftps.note.tls': 'TLS is mandatory and there is no switch to turn it off. Plain FTP sends your password in the clear and your file after it.',
+  'conn.guide.ftps.note.passive': 'Passive mode only. Active mode has the server dial back to the client, which does not survive NAT and is blocked by most firewalls.',
+  'conn.guide.ftps.note.storages': 'The root is not a home directory: it lists the storages you may open, and the first path segment names one.',
+  'conn.guide.ftps.note.trash': 'A delete goes to the filex trash, the same as everywhere else, and is recoverable until the retention policy sweeps it.',
+  'conn.guide.ftps.note.prefer': 'If the client can speak SFTP, prefer it: one connection, one port, no passive-mode surprises.',
+  'conn.guide.ftps.note.selfSigned': 'This server is using a self-signed certificate. It encrypts the channel but proves nothing about who is on the other end — most clients will ask you to accept it once. Supply a real certificate for anything that matters.',
+  'conn.guide.ftps.note.disabled': 'The FTPS endpoint is switched off on this server. These instructions will work once an operator enables it.',
+  // ── NFS ──────────────────────────────────────────────────────────
+  'conn.nfs.title': 'NFS exports',
+  'conn.nfs.lead': 'An export lets a machine on your network mount filex as a drive — a media player, a build server, a backup box.',
+  'conn.nfs.pathIsSecret': '⚠ The export path IS the password. NFS cannot ask a client who it is without Kerberos, so filex puts 32 random bytes in the path instead: whoever knows it can mount as you. Treat the mount line like a credential — /etc/fstab is world-readable on most systems.',
+  'conn.nfs.disabled': 'The NFS endpoint is switched off on this server (FILEX_NFS). An export created here will not mount until an operator turns it back on.',
+  'conn.nfs.cannotMint': 'You are not signed in with an account that can create exports.',
+  'conn.nfs.label': 'What is it for? (media player, backup box, …)',
+  'conn.nfs.defaultLabel': 'nfs export',
+  'conn.nfs.everyStorage': 'Every storage I can see',
+  'conn.nfs.prefix': 'Folder inside the storage (optional)',
+  'conn.nfs.allowCidrs': 'Allowed addresses, e.g. 192.168.1.0/24 (optional)',
+  'conn.nfs.readOnly': 'Read-only',
+  'conn.nfs.readOnlyHint': 'Read-only is the safer default for a machine: it refuses every write through this mount whatever your own permissions are. An address list narrows it further — outside it, the mount is refused.',
+  'conn.nfs.mint': 'Create export',
+  'conn.nfs.once': 'Copy this now — the path is shown only once and cannot be recovered.',
+  'conn.nfs.dismiss': 'I have copied it',
+  'conn.nfs.col.label': 'Label',
+  'conn.nfs.col.scope': 'Limited to',
+  'conn.nfs.col.mode': 'Mode',
+  'conn.nfs.col.lastUsed': 'Last mounted',
+  'conn.nfs.scopeAll': 'everything you can see',
+  'conn.nfs.modeRead': 'read-only',
+  'conn.nfs.modeWrite': 'read/write',
+  'conn.nfs.noLabel': '(no label)',
+  'conn.nfs.neverUsed': 'never',
+  'conn.nfs.enable': 'Enable',
+  'conn.nfs.disable': 'Disable',
+  'conn.nfs.revoke': 'Revoke',
+  'conn.nfs.confirm': 'Sure?',
+  'conn.nfs.empty': 'No exports yet.',
+  'conn.guide.nfs.summary': 'NFS mounts filex as a drive on a machine in your own network — the NAS protocol, for the devices that expect one.',
+  'conn.guide.nfs.pathPlaceholder': 'create an export above',
+  'conn.guide.nfs.fact.host': 'Host',
+  'conn.guide.nfs.fact.hostHint': 'The same machine as the web app, on a port of its own.',
+  'conn.guide.nfs.fact.port': 'Port',
+  'conn.guide.nfs.fact.portHint': 'Both port= and mountport= must be set to this; filex serves the mount and NFS services on one port.',
+  'conn.guide.nfs.fact.export': 'Export path',
+  'conn.guide.nfs.fact.exportHint': 'This is the credential. It is shown once, when you create the export, and is stored hashed — filex cannot show it again.',
+  'conn.guide.nfs.fact.options': 'Mount options',
+  'conn.guide.nfs.fact.optionsHint': 'nolock because filex does not run the NFS lock manager; nfsvers=3 because that is what this server speaks.',
+  'conn.guide.nfs.linux.mountCaption': 'Mount it',
+  'conn.guide.nfs.linux.fstabSecret': 'An /etc/fstab line containing this path is a password in a world-readable file. Use a credentials-protected automount, or keep the mount in a root-only unit, if that matters where you are.',
+  'conn.guide.nfs.mac.mountCaption': 'Mount it',
+  'conn.guide.nfs.mac.resvport': 'macOS needs resvport: its client insists on a privileged source port and refuses the mount without it.',
+  'conn.guide.nfs.win.s1': 'Turn on "Services for NFS" → "Client for NFS" in Windows Features (Pro and Enterprise only; Home does not have it).',
+  'conn.guide.nfs.win.s2': 'Open a Command Prompt as administrator.',
+  'conn.guide.nfs.win.s3': 'Map the export to a drive letter with the command below.',
+  'conn.guide.nfs.win.cmdCaption': 'Map it to Z:',
+  'conn.guide.nfs.win.port': 'Windows has no way to say which port the mount service is on, so it can only reach an NFS server on the standard port 2049. If this server is on another port, use SFTP or the filex desktop app instead.',
+  'conn.guide.nfs.nas.tab': 'NAS / media player',
+  'conn.guide.nfs.nas.s1': 'In the device\'s NFS settings: server {host}, port {port} (set both the NFS and the mount port if it asks for them separately).',
+  'conn.guide.nfs.nas.s2': 'Remote path: the export path above, exactly as shown.',
+  'conn.guide.nfs.nas.s3': 'NFS version 3, no locking. Create the export read-only unless the device genuinely needs to write.',
+  'conn.guide.nfs.note.unencrypted': 'NFSv3 is not encrypted. Anyone who can read the traffic sees your files, and anyone who learns the path can mount them. Use it on a home or office network, or over a VPN — never across the internet.',
+  'conn.guide.nfs.note.pathIsSecret': 'The export path is the whole credential. Revoke it from the list above if it leaks; there is nothing else to change.',
+  'conn.guide.nfs.note.noPortmapper': 'There is no portmapper on port 111, so a client that is not told the port cannot find the server. That is why every command here carries port= and mountport=.',
+  'conn.guide.nfs.note.uid': 'The user and group ids your client sends are ignored: the mount already knows whose it is. The permissions you see come from your access in filex.',
+  'conn.guide.nfs.note.trash': 'A delete goes to the filex trash, the same as everywhere else, and is recoverable until the retention policy sweeps it.',
+  'conn.guide.nfs.note.revoke': 'Revoking takes effect on the next request, not instantly: NFS has no session to end, so a client with the mount open sees its next operation fail.',
+  'conn.guide.nfs.note.disabled': 'The NFS endpoint is switched off on this server. These instructions will work once an operator enables it.',
+  'conn.tokens.title': 'API tokens',
+  'conn.tokens.lead': 'FTPS, WebDAV and filex mount all sign in with a token instead of your account password. Mint one here — it can be revoked on its own, and an account with two-factor sign-in cannot use its password on these at all.',
+  'conn.tokens.mint': 'Create token',
+  'conn.tokens.once': 'Copy it now — this is the only time it is shown. Only a hash is stored, so it cannot be shown again.',
+  'conn.tokens.dismiss': 'I have copied it',
+  'conn.tokens.cannotMint': 'This session cannot create tokens. Sign in with your own account to make one.',
+  'conn.tokens.empty': 'No tokens yet.',
+  'conn.tokens.neverUsed': 'never',
+  'conn.tokens.revoke': 'Revoke',
+  'conn.tokens.confirm': 'Sure?',
+  'conn.tokens.col.label': 'Name',
+  'conn.tokens.col.scopes': 'Can do',
+  'conn.tokens.col.used': 'Last used',
+  'conn.tokens.revokeHint': 'Revoking stops a connection that is already open, not just the next sign-in: an SFTP or FTPS session is cut and a mount stops working within about half a minute.',
+  'conn.guide.mount.summary': 'filex mount attaches a remote filex server to a folder on this machine, over the same HTTPS the browser uses. It is the only one of these that works from anywhere — no LAN, no extra server, no third-party client.',
+  'conn.guide.mount.fact.url': 'Server URL',
+  'conn.guide.mount.fact.urlHint': 'The same address you use in the browser. Nothing else has to be reachable.',
+  'conn.guide.mount.fact.token': 'API token',
+  'conn.guide.mount.fact.tokenPlaceholder': 'create one under Tokens',
+  'conn.guide.mount.fact.tokenHint': 'A token, not your password — it can be revoked on its own, and an account with 2FA cannot use its password here at all.',
+  'conn.guide.mount.fact.remote': 'What to mount',
+  'conn.guide.mount.fact.remoteHint': 'Leave --remote off to see every storage as a folder, or name one storage — or a folder inside it — to mount just that.',
+  'conn.guide.mount.linux.mountCaption': 'Mount it',
+  'conn.guide.mount.linux.umountCaption': 'Unmount it',
+  'conn.guide.mount.linux.umountWarn': 'Unmount with fusermount, not by killing the process. A mount whose process died without detaching leaves a folder where every ls hangs until somebody runs fusermount by hand.',
+  'conn.guide.mount.linux.systemdCaption': 'Mount it at login (systemd user unit)',
+  'conn.guide.mount.win.winfsp': 'Windows needs WinFsp installed once — it is free and open source: https://winfsp.dev. Nothing else, and no administrator rights after that.',
+  'conn.guide.mount.win.mountCaption': 'Mount it as a drive',
+  'conn.guide.mount.win.freeLetter': 'Pick a drive letter that is FREE. The letter is created by the mount, not attached to something that already exists, and pointing it at one that is in use fails with a message that does not say so.',
+  'conn.guide.mount.win.stop': 'Stop it with Ctrl-C in that window. The drive disappears and nothing is left behind on this machine.',
+  'conn.guide.mount.mac.unsupported': 'filex mount does not work on macOS. It needs macFUSE, whose licence does not allow a program like filex to install it for you, and whose Go binding needs a C compiler filex deliberately does not require. The command refuses here rather than appearing to work and doing nothing.',
+  'conn.guide.mount.mac.alternatives': 'On macOS, use the filex desktop app with folder sync (keeps the files on disk), or SFTP with a client that mounts drives.',
+  'conn.guide.mount.note.notASync': 'This is not a sync. Nothing is copied to this machine except a small read cache, so a mount opens one file out of a hundred thousand without downloading the rest. If you want the files when you are offline, use folder sync instead.',
+  'conn.guide.mount.note.reachable': 'It reaches the server through whatever proxy or tunnel the browser goes through, because underneath it is the same API. Your permissions, your storages and — on a multi-tenant server — your tenant come with it.',
+  'conn.guide.mount.note.wholeFileWrites': 'A file you write through the mount is uploaded when the program closes it, not while it is being written. Editing a very large file in place is slower here than a local disk; copying it in and out is not.',
+  'conn.guide.mount.note.trash': 'A delete goes to the filex trash, the same as everywhere else, and is recoverable until the retention policy sweeps it.',
+  'conn.guide.mount.note.revoke': 'Revoke the token to stop a mount. It stops serving within half a minute, even if the mount is still attached.',
+  'storages.driver.ftp': 'FTP / FTPS',
+  'storages.driver.local': 'Local filesystem',
+  'storages.driver.s3': 'S3 / Hetzner / MinIO',
+  'storages.driver.sftp': 'SFTP',
+  'storages.driver.smb': 'SMB / CIFS (NAS)',
+  'storages.driver.webdav': 'WebDAV',
+  'storages.fieldHelp.smbShare': 'The share name alone, without the server: `media`, not `\\\\nas\\media`.',
+  'storages.fieldHelp.smbDomain': 'Only for a Windows domain account. Leave empty for a NAS.',
+  'storages.fieldHelp.smbRoot': 'Sub-folder inside the share. Leave empty for the whole share.',
+  'storages.fields.share': 'Share',
+  'storages.fields.domain': 'Domain / workgroup',
+  'storages.fields.dialTimeout': 'Connect timeout (seconds)',
+  'storages.fieldHelp.disablePresign': 'Turn on when the store rejects SDK-signed URLs (Ceph RGW / some Hetzner setups answer SignatureDoesNotMatch); uploads then stream through the backend.',
+  'storages.fieldHelp.endpoint': 'Leave empty for AWS S3. Any S3-compatible store needs its endpoint.',
+  'storages.fieldHelp.hostKey': 'A single public key in authorized_keys / known_hosts line form.',
+  'storages.fieldHelp.insecureSkipHostKey': 'Accepts any host key. Only for throwaway hosts.',
+  'storages.fieldHelp.keyPath': 'Path to a key file on the server, read when the storage starts. Used when the PEM field is empty.',
+  'storages.fieldHelp.knownHosts': 'OpenSSH known_hosts path for strict host-key checking. Default is trust-on-first-use in ~/.filex/known_hosts.',
+  'storages.fieldHelp.passive': 'Off switches to active mode, which needs the server to dial back into this host.',
+  'storages.fieldHelp.path': 'Directory on the server. It is created if missing; filex never mounts /.',
+  'storages.fieldHelp.pathStyle': 'On for every non-AWS store. It is turned on automatically when an endpoint is set and this was never touched.',
+  'storages.fieldHelp.prefix': 'Sub-folder inside the bucket. Required: filex never takes ownership of the bucket root.',
+  'storages.fieldHelp.region': 'Defaults to "auto" when left empty.',
+  'storages.fieldHelp.root': 'Sub-folder on the backend. Required: filex never mounts the account root.',
+  'storages.fieldHelp.sftpAuth': 'Either a password or a private key is required.',
+  'storages.fieldHelp.tls': 'Plain FTP sends credentials in the clear — turn this on whenever the server supports it.',
+  'storages.fields.accessKey': 'Access key',
+  'storages.fields.basePath': 'Base path',
+  'storages.fields.bucket': 'Bucket',
+  'storages.fields.disablePresign': 'Disable presigned URLs',
+  'storages.fields.endpoint': 'Endpoint',
+  'storages.fields.host': 'Host',
+  'storages.fields.hostKey': 'Pinned host key',
+  'storages.fields.insecureSkipHostKey': 'Skip host-key verification (insecure)',
+  'storages.fields.keyPath': 'Private key file',
+  'storages.fields.knownHosts': 'known_hosts file',
+  'storages.fields.name': 'Display name',
+  'storages.fields.namePlaceholder': 'Personal photos',
+  'storages.fields.passive': 'Passive mode (PASV)',
+  'storages.fields.password': 'Password',
+  'storages.fields.path': 'Filesystem path',
+  'storages.fields.pathStyle': 'Use path-style URLs (Hetzner, MinIO)',
+  'storages.fields.port': 'Port',
+  'storages.fields.prefix': 'Prefix',
+  'storages.fields.privateKey': 'Private key (PEM)',
+  'storages.fields.rbac': 'Per-item access control (RBAC)',
+  'storages.fields.rbacHint': 'When on, non-admins see only files/folders explicitly granted to them via the permissions panel. When off, the storage is open to all users (capability by role).',
+  'storages.fields.readOnly': 'Read-only mount',
+  'storages.fields.region': 'Region',
+  'storages.fields.root': 'Base path',
+  'storages.fields.secretKey': 'Secret key',
+  'storages.fields.tls': 'FTPS (explicit AUTH TLS)',
+  'storages.fields.url': 'Base URL',
+  'storages.fields.user': 'User',
+
 };