@brftech/filex-core 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import { GlobalComponents } from 'vue';
 import { GlobalDirectives } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
+import { ShallowRef } from 'vue';
 
 declare type __VLS_Props = {
     config: ExplorerConfig;
@@ -60,6 +61,65 @@ declare type __VLS_Props_12 = {
     busy?: boolean;
 };
 
+declare type __VLS_Props_13 = {
+    config: ExplorerConfig;
+    /** Which half to open on. */
+    initialTab?: 'storages' | 'connect';
+    /** Draw a close control — the desktop app opens this as a full surface
+     *  and needs a way out; a page-embedded copy has the page's own chrome. */
+    closable?: boolean;
+};
+
+declare type __VLS_Props_14 = {
+    fields: StorageField[];
+    modelValue: Record<string, unknown>;
+    locale: LocaleCode;
+    /** Keys to mark as failing validation (missing required). */
+    invalid?: string[];
+    disabled?: boolean;
+};
+
+declare type __VLS_Props_15 = {
+    guide: ProtocolGuide;
+    locale: LocaleCode;
+};
+
+declare type __VLS_Props_16 = {
+    config: ExplorerConfig;
+    /** Storage names the caller may see, for the confinement picker. */
+    storages: string[];
+};
+
+declare type __VLS_Props_17 = {
+    config: ExplorerConfig;
+    /**
+     * Draw the key list and the paste box.
+     *
+     * ⚠ False for FTPS, which authenticates with a password or an API token and
+     * has no use for an SSH key — the panel is still MOUNTED there because it is
+     * the call that reports where the FTP endpoint listens and under what login
+     * name. Showing a key box on the FTPS page would invite somebody to register
+     * a key that protocol will never look at.
+     */
+    keysVisible?: boolean;
+};
+
+declare type __VLS_Props_18 = {
+    config: ExplorerConfig;
+    /** Storage names the caller may see, for the confinement picker. */
+    storages: string[];
+};
+
+declare type __VLS_Props_19 = {
+    config: ExplorerConfig;
+    /**
+     * Which protocol the surrounding guide is showing. It only changes the
+     * default label — a token minted here works on all of them, and pretending
+     * otherwise would have people mint one per protocol.
+     */
+    protocol?: string;
+};
+
 declare type __VLS_Props_2 = {
     open: boolean;
     locale: LocaleCode;
@@ -178,6 +238,45 @@ declare type __VLS_Props_9 = {
     narrow?: boolean;
 };
 
+/**
+ * The self-service API-token surface (`/api/tokens`).
+ *
+ * ⚠ Why this exists at all: three of the six protocols filex serves take an
+ * API token as their password — FTPS, WebDAV and `filex mount`. Until
+ * 2026-08-17 the only place to mint one was `/api/admin/ai-tokens`, which is
+ * admin-only, so a normal user opened the FTPS guide, read "use an API token
+ * as the password", and had nowhere to get one. The backend route has always
+ * been open to every account; only the UI was missing.
+ */
+/** One token row. The secret is NEVER in here — only the hash is stored. */
+export declare interface ApiToken {
+    id: number;
+    label: string;
+    scopes: string;
+    /** Per-token display identities for the audit trail; may be absent. */
+    usernames?: string | null;
+    created_at?: string;
+    last_used_at?: string | null;
+    expires_at?: string | null;
+}
+
+/** What comes back from a mint. `token` is shown exactly once. */
+export declare interface ApiTokenCreated {
+    token: string;
+    row: ApiToken;
+}
+
+export declare interface ApiTokenRequest {
+    label: string;
+    /**
+     * Comma-separated verbs. The server CAPS this against the caller's role and
+     * their own grants, so asking for more than you have is refused rather than
+     * quietly granted — never send `admin`, it is rejected outright here.
+     */
+    scopes?: string;
+    expires_in_days?: number;
+}
+
 /**
  * Set (or clear, for the default theme) the selected theme's tokens as
  * inline CSS variables on the explorer root element, resolved to the
@@ -245,6 +344,42 @@ export declare type AuthConfig = {
     csrf: string;
 };
 
+/**
+ * Every command here was RUN against the endpoint on 2026-08-16 with curl
+ * 8.5, lftp 4.9 and rclone 1.73 — including the settings each of them needs to
+ * negotiate explicit TLS, which is the half of FTPS that goes wrong quietly.
+ */
+export declare const buildFtpsGuide: GuideBuilder;
+
+export declare function buildGuide(protocol: string, ctx: GuideContext, t: Translate): ProtocolGuide | null;
+
+/**
+ * Every command here was RUN against the endpoint on 2026-08-16 with the LINUX
+ * KERNEL's own NFSv3 client — including the two options a mount fails silently
+ * without (`port=` and `mountport=`, because filex serves both on one port and
+ * runs no portmapper).
+ */
+export declare const buildNfsGuide: GuideBuilder;
+
+/**
+ * Every command here was RUN against the endpoint on 2026-08-16, not copied
+ * from a vendor page: rclone 1.73.5, aws-cli 2.11.6, restic 0.19.1, mc
+ * 2025-08-13 and s3fs 1.93 each did a full round trip, and the flags below are
+ * the ones those runs actually needed. Five of the endpoint's bugs were found
+ * that way — a guide assembled from documentation would have shipped them.
+ */
+export declare const buildS3Guide: GuideBuilder;
+
+/**
+ * Every command here was RUN against the endpoint on 2026-08-16 with OpenSSH
+ * 9.6 and rclone 1.73 — including the two settings rclone needs because filex
+ * has no shell, which are the difference between a clean run and a pile of
+ * warnings about a missing `md5sum`.
+ */
+export declare const buildSftpGuide: GuideBuilder;
+
+export declare const buildWebdavGuide: GuideBuilder;
+
 export declare interface Capabilities {
     ffmpeg?: boolean;
     ghostscript?: boolean;
@@ -261,6 +396,8 @@ export declare interface Capabilities {
     };
 }
 
+export declare function clearResume(store: ResumeStorage | null, key: string): void;
+
 export declare interface ClipboardState {
     mode: 'cut' | 'copy' | null;
     items: FileNode[];
@@ -274,6 +411,53 @@ export declare interface ClipboardState {
  */
 export declare function comboFromEvent(e: KeyboardEvent): string | null;
 
+export declare const ConnectionGuideView: DefineComponent<__VLS_Props_15, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare type ConnectionsApi = ReturnType<typeof useConnections>;
+
+/**
+ * The URL prefix the `/api/...` routes hang off.
+ *
+ * `apiBase: ''` is a legitimate value (the admin SPA is same-origin), so
+ * only `undefined`/`null` means "not given" — a falsy check would send the
+ * SPA's requests to the wrong place. Legacy embedders configure `endpoint`
+ * instead of `apiBase`; the prefix is recovered from it so they are not
+ * excluded.
+ */
+export declare function connectionsBase(config: ExplorerConfig): string;
+
+/**
+ * The origin a client program should be pointed at.
+ *
+ * The instruction pages are only worth anything if they name the real
+ * deployment, so this resolves to an absolute origin: the configured
+ * apiBase when there is one (the desktop app, embeds), otherwise the page's
+ * own origin (the admin SPA, which is served by the same binary).
+ */
+export declare function connectionsOrigin(config: ExplorerConfig): string;
+
+export declare const ConnectionsPanel: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+error: (err: {
+message: string;
+}) => any;
+close: () => any;
+changed: () => any;
+}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{
+onError?: ((err: {
+message: string;
+}) => any) | undefined;
+onClose?: (() => any) | undefined;
+onChanged?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+/** The signed-in account, from `GET /api/auth/me`. */
+export declare interface ConnectionsUser {
+    id: number;
+    email: string;
+    display_name?: string;
+    role?: string;
+}
+
 declare interface ContextAction {
     key: string;
     label: string;
@@ -312,6 +496,11 @@ export declare function decryptFile(kek: CryptoKey, data: ArrayBuffer): Promise<
 
 export declare const DEFAULT_THEME_ID = "default";
 
+/** 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 declare function defaultResumeStorage(): ResumeStorage | null;
+
 declare type Density = 'comfortable' | 'compact';
 
 /**
@@ -406,6 +595,15 @@ export declare function encryptFile(kek: CryptoKey, content: ArrayBuffer): Promi
  */
 export declare interface EndpointMap {
     manager: string;
+    /**
+     * Staged upload — the chunked, resumable, driver-agnostic path every client
+     * speaks (docs/UPLOADS.md). The per-upload routes (`PUT/GET/DELETE {id}`,
+     * `POST {id}/commit`) are derived from it by stripping `/begin`, so one
+     * override moves the whole protocol.
+     */
+    uploadBegin: string | null;
+    /** Legacy S3-presigned chunked upload. Still served by the backend for
+     *  older embedders; nothing in this package calls it. */
     uploadInit: string | null;
     uploadFinalize: string | null;
     uploadAbort: string | null;
@@ -448,6 +646,8 @@ export declare interface ExplorerConfig {
     apiBase?: string;
     /** Legacy main endpoint (Vuefinder-compat: GET/POST `?q=…`). */
     endpoint?: string;
+    /** Staged upload entry point; the `{id}` routes hang off it. */
+    uploadBegin?: string;
     uploadInit?: string;
     uploadFinalize?: string;
     uploadAbort?: string;
@@ -538,9 +738,19 @@ export declare interface ExplorerConfig {
      * embed). Defaults to `/files/viewer`.
      */
     viewerBaseUrl?: string;
-    /** Upload chunk size (bytes). Default 5 MB. */
+    /**
+     * Upload chunk size (bytes). Default 8 MB — the server's default too, so
+     * "large enough to chunk" means the same thing on both ends. The value the
+     * server returns from `begin` is binding; this is what the client asks for
+     * and the threshold above which a file goes on the staged path at all.
+     */
     chunkSize?: number;
-    /** Parallel chunks. Default 4. */
+    /**
+     * @deprecated Ignored since the move to the staged protocol. Chunks are sent
+     * sequentially because `offset` — the resume point — is the contiguous run
+     * from part 1; parallel parts would leave holes that a resumed upload has to
+     * re-send anyway.
+     */
     parallelChunks?: number;
     /** Theme. */
     theme?: ThemeMode;
@@ -1064,6 +1274,22 @@ export declare interface FileNode {
  */
 export declare function findShortcutConflict(combo: string, excludeId: string): ShortcutConflict | null;
 
+/** What an FTP client needs to be told, computed on the server. */
+declare interface FTPSFacts {
+    enabled: boolean;
+    host: string;
+    port: number;
+    /**
+     * ⚠ The passive data-port range. A firewall that blocks it makes every
+     * transfer HANG with no error on either side — the classic FTP failure, and
+     * impossible to diagnose from the client end. It belongs in the guide.
+     */
+    pasv_min: number;
+    pasv_max: number;
+    /** True when no certificate was configured and the server generated one. */
+    self_signed: boolean;
+}
+
 /**
  * Generate a stylesheet that mirrors styles/variables.css' selector
  * cascade 1:1 (light base → explicit-dark selectors → prefers-dark media
@@ -1120,9 +1346,112 @@ declare interface Grant {
     inherited?: boolean;
 }
 
+/**
+ * Protocol id → builder.
+ *
+ * S3 and SFTP land here as one entry each once their servers exist; the
+ * panel, the copy buttons, the client tabs and the i18n plumbing are
+ * already written for them. That is the whole point of the shape.
+ */
+export declare const GUIDE_BUILDERS: Record<string, GuideBuilder>;
+
+export declare interface GuideBlock {
+    kind: GuideBlockKind;
+    /** Prose for `text` / `note` / `warn`. */
+    text?: string;
+    /** Ordered instructions for `steps`. */
+    steps?: string[];
+    /** Copyable payload for `code`. */
+    code?: string;
+    /** Syntax hint / file name shown above a code block. */
+    caption?: string;
+}
+
+export declare type GuideBlockKind = 'text' | 'steps' | 'code' | 'note' | 'warn';
+
+export declare type GuideBuilder = (ctx: GuideContext, t: Translate) => ProtocolGuide;
+
+export declare interface GuideClient {
+    id: string;
+    /** Product name — never translated ("Cyberduck" is Cyberduck). */
+    name: string;
+    platform: 'windows' | 'macos' | 'linux' | 'any';
+    blocks: GuideBlock[];
+}
+
+/** Everything a guide is allowed to know about the deployment. */
+export declare interface GuideContext {
+    /** Absolute origin of the server, e.g. `https://fm.example.com`. */
+    origin: string;
+    /** The caller's own account e-mail — the username on every protocol. */
+    user: string;
+    /** Storage names the caller may see. */
+    storages: string[];
+    /** The storage the page is currently focused on, when any. */
+    storage?: string;
+    /**
+     * The S3 endpoint, as the server computes it.
+     *
+     * ⚠ NOT derived from `origin` here. With a dedicated host the endpoint is
+     * that host's root; without one it lives under `/s3`, and a client pointed
+     * at the application root reaches the web app — rclone reported
+     * "XML syntax error on line 10" against an HTML redirect page. The server
+     * returns this with every key, and the guide repeats it verbatim.
+     */
+    s3Endpoint?: string;
+    /** True when clients must be told to force path-style addressing. */
+    s3PathStyle?: boolean;
+    /** The access key id to write into the examples, when the caller has one. */
+    s3AccessKeyID?: string;
+    /** The freshly minted secret, shown only while the user is looking at it. */
+    s3Secret?: string;
+    /** The SFTP endpoint, as the server reports it. */
+    sftpHost?: string;
+    sftpPort?: number;
+    /** False when the operator has the endpoint switched off. */
+    sftpEnabled?: boolean;
+    /** The login name a client must use — the username when there is one. */
+    sftpLogin?: string;
+    /** True when the account has at least one usable key registered. */
+    sftpHasKey?: boolean;
+    /** The FTPS endpoint, as the server reports it. */
+    ftpsHost?: string;
+    ftpsPort?: number;
+    ftpsEnabled?: boolean;
+    /** The passive data-port range, which the client's firewall must allow. */
+    ftpsPasvMin?: number;
+    ftpsPasvMax?: number;
+    /** True when the server is using a self-signed certificate. */
+    ftpsSelfSigned?: boolean;
+    /** The NFS endpoint, as the server reports it. */
+    nfsHost?: string;
+    nfsPort?: number;
+    nfsEnabled?: boolean;
+    /** The freshly minted export path — the credential, shown once. */
+    nfsPath?: string;
+    /** True when the active export refuses writes. */
+    nfsReadOnly?: boolean;
+}
+
+/** One connection fact, rendered as a copyable row. */
+export declare interface GuideFact {
+    label: string;
+    value: string;
+    hint?: string;
+    /** Rendered as a hint rather than a value — filex never has the
+     *  plaintext of your password and must not pretend otherwise. */
+    placeholderOnly?: boolean;
+}
+
+/** Protocol ids that have a guide, in display order. */
+export declare function guideProtocols(): string[];
+
 /** True when the buffer starts with the 'filexe2e' magic. */
 export declare function hasMagic(buf: ArrayBuffer | Uint8Array): boolean;
 
+/** `https://fm.example.com` → `fm.example.com`; anything unparseable comes back whole. */
+export declare function hostOf(origin: string): string;
+
 declare interface InviteResponse {
     mode: 'granted' | 'user_created' | 'shared';
     user_id?: number;
@@ -1138,8 +1467,31 @@ declare interface InviteResponse {
  */
 export declare function isExternalUsable(s: ExternalServiceStatus | undefined): boolean;
 
+/** True when the deployment is not on TLS — several clients refuse that,
+ *  and Windows refuses it silently, which is worse. */
+export declare function isPlainHttp(origin: string): boolean;
+
+/** True when the staged protocol is simply not there. */
+export declare function isStagedUnsupported(err: unknown): boolean;
+
+/** Every unfinished upload this browser knows about, newest first. Surfaces
+ *  use it to say "you have an unfinished upload" instead of forgetting. */
+export declare function listResume(store: ResumeStorage | null, now?: number): ResumeRecord[];
+
+/** The record for this exact (destination, file), or null. */
+export declare function loadResume(store: ResumeStorage | null, key: string, now?: number): ResumeRecord | null;
+
 export declare type LocaleCode = 'tr' | 'en';
 
+/**
+ * Why the caller cannot manage storages, when they cannot.
+ *
+ * `none` is the honest answer for a signed-in non-admin: the surface then
+ * shows the connection guides (which every user needs) and a plain "ask
+ * your administrator" line instead of a form that would 403 on submit.
+ */
+export declare type ManageDenial = 'none' | 'anonymous' | 'unreachable';
+
 export declare interface ManagerResponse {
     adapter: string;
     storages: string[];
@@ -1158,6 +1510,71 @@ export declare function matchedInContent(matched: unknown): boolean;
 
 export declare const messages: Record<LocaleCode, Record<string, string>>;
 
+/** Where an NFS client should point, reported by the server. */
+export declare interface NFSConnection {
+    /** The FILEX_NFS kill switch. */
+    enabled: boolean;
+    host: string;
+    /**
+     * ⚠ 2049 by convention, but filex serves mount AND nfs on this one port and
+     * runs no portmapper — so a client needs `port=` and `mountport=` both set to
+     * it. A guide that omitted either produces a mount that hangs.
+     */
+    port: number;
+}
+
+/**
+ * NFS exports, as the frontend sees them.
+ *
+ * ⚠⚠ The `path` a freshly minted export returns IS the credential. NFSv3 cannot
+ * authenticate a request without Kerberos, so filex binds the identity to the
+ * export path instead: 32 bytes of entropy, shown once, stored hashed. Whoever
+ * knows it can mount as that account — which is why it belongs in a config file
+ * treated like a password, and why the UI has to say so rather than letting
+ * somebody discover it from a mount table.
+ */
+export declare interface NFSExport {
+    id: number;
+    user_id: number;
+    api_token_id?: number | null;
+    label: string;
+    /** Confinement, in the same shape the S3 keys use. */
+    storage_name?: string;
+    prefix?: string;
+    /** Refuses every write through this mount, whatever the account may do. */
+    read_only: boolean;
+    /** Comma-separated CIDR allow-list. Empty = any address the listener takes. */
+    allow_cidrs?: string;
+    created_at: string;
+    last_used_at?: string | null;
+    expires_at?: string | null;
+    disabled_at?: string | null;
+}
+
+/** What minting returns. The path appears exactly once. */
+export declare interface NFSExportCreated extends NFSConnection {
+    export: NFSExport;
+    path: string;
+}
+
+export declare const NFSExportsPanel: DefineComponent<__VLS_Props_18, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+active: (v: {
+host: string;
+port: number;
+enabled: boolean;
+path?: string;
+readOnly: boolean;
+}) => any;
+}, string, PublicProps, Readonly<__VLS_Props_18> & Readonly<{
+onActive?: ((v: {
+host: string;
+port: number;
+enabled: boolean;
+path?: string;
+readOnly: boolean;
+}) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLElement>;
+
 /** Mirrors backend `model.NodeComment` (GET /api/files/comments?node_id=…). */
 declare interface NodeComment {
     id: number;
@@ -1350,6 +1767,20 @@ monacoEl: HTMLDivElement;
 officeEl: HTMLDivElement;
 }, any>;
 
+export declare interface ProtocolGuide {
+    id: string;
+    /** Protocol name — a wire protocol is not translated either. */
+    name: string;
+    summary: string;
+    /** Server + credential, filled in from this deployment. */
+    facts: GuideFact[];
+    clients: GuideClient[];
+    notes: GuideBlock[];
+}
+
+/** Drop records older than RESUME_TTL_MS. Returns what survived. */
+export declare function pruneResume(store: ResumeStorage | null, now?: number): Store;
+
 export declare const QuickLook: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 close: () => any;
 nav: (delta: number) => any;
@@ -1401,6 +1832,106 @@ declare interface ResolveEmailResponse {
  */
 export declare function resolveEndpoints(config: ExplorerConfig): EndpointMap;
 
+/** 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 declare const RESUME_TTL_MS: number;
+
+export declare 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;
+}
+
+/** A Storage-shaped thing. Injected so tests (and any surface without
+ *  localStorage — SSR, a locked-down embed) do not have to fake globals. */
+export declare interface ResumeStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+/**
+ * The S3 access-key surface, as the frontend sees it.
+ *
+ * Mirrors `model.S3AccessKey` and the connection facts the key endpoints
+ * return alongside it. The facts travel WITH the keys on purpose: a key
+ * without an endpoint is not a usable credential, and a UI that assembled
+ * the URL itself would be a second place to get it wrong (the application
+ * URL and the S3 endpoint are different hosts whenever one is configured).
+ */
+export declare interface S3AccessKey {
+    id: number;
+    access_key_id: string;
+    user_id: number;
+    api_token_id?: number | null;
+    label: string;
+    /** Optional confinement, in the shape S3 clients already understand. */
+    bucket?: string;
+    prefix?: string;
+    created_at: string;
+    last_used_at?: string | null;
+    expires_at?: string | null;
+    /** Set = the key is switched off but still in the audit trail. */
+    disabled_at?: string | null;
+}
+
+/** Where to point a client, and how to address it. */
+export declare interface S3Connection {
+    /** Absolute endpoint URL — the S3 host's root, or `<app>/s3`. */
+    endpoint: string;
+    /** The FILEX_S3 kill switch. False = the operator turned the endpoint off. */
+    enabled: boolean;
+    /**
+     * True when there is no dedicated host, so clients must be told to force
+     * path-style addressing. A current SDK defaults to virtual-hosted and then
+     * fails at DNS with an error that names neither filex nor the cause.
+     */
+    path_style: boolean;
+}
+
+/** What a freshly minted key returns. The secret appears exactly once. */
+export declare interface S3KeyCreated extends S3Connection {
+    key: S3AccessKey;
+    secret: string;
+}
+
+/** What the caller asked for when minting. */
+export declare interface S3KeyRequest {
+    label: string;
+    /** Mint FROM an API token, inheriting its scopes, confinement and expiry. */
+    api_token_id?: number;
+    bucket?: string;
+    prefix?: string;
+    expires_at?: string;
+}
+
+export declare const S3KeysPanel: DefineComponent<__VLS_Props_16, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+active: (v: {
+accessKeyID: string;
+secret?: string;
+endpoint: string;
+pathStyle: boolean;
+}) => any;
+}, string, PublicProps, Readonly<__VLS_Props_16> & Readonly<{
+onActive?: ((v: {
+accessKeyID: string;
+secret?: string;
+endpoint: string;
+pathStyle: boolean;
+}) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLElement>;
+
 /** Matched-in values the search contract allows on a hit. */
 export declare type SearchMatched = 'name' | 'content' | 'both';
 
@@ -1555,6 +2086,64 @@ export declare interface SnippetSegment {
  */
 export declare function snippetSegments(snippet: string): SnippetSegment[];
 
+/** Where an SSH client should connect, and as whom. */
+export declare interface SSHConnection {
+    /** The FILEX_SFTP kill switch. False = the operator turned the port off. */
+    enabled: boolean;
+    host: string;
+    /**
+     * ⚠ Not 22 and not the web port. SFTP is raw TCP on a port of its own, and
+     * a guide that printed 443 would send every client at a proxy that speaks
+     * only HTTP.
+     */
+    port: number;
+    /** The login name: the account's username, or its e-mail when it has none. */
+    login: string;
+    /** The FTPS endpoint, reported by the same call. */
+    ftps?: FTPSFacts;
+}
+
+export declare const SSHKeysPanel: DefineComponent<__VLS_Props_17, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+active: (v: {
+host: string;
+port: number;
+login: string;
+enabled: boolean;
+hasKey: boolean;
+ftps?: FTPSFacts;
+}) => any;
+}, string, PublicProps, Readonly<__VLS_Props_17> & Readonly<{
+onActive?: ((v: {
+host: string;
+port: number;
+login: string;
+enabled: boolean;
+hasKey: boolean;
+ftps?: FTPSFacts;
+}) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+/**
+ * The SSH key surface, as the frontend sees it.
+ *
+ * Mirrors `model.SSHPublicKey` plus the connection facts the endpoint returns
+ * with it — the host, the port and the LOGIN NAME, which is the piece people
+ * most often get wrong when they type it themselves.
+ */
+export declare interface SSHPublicKey {
+    id: number;
+    user_id: number;
+    name: string;
+    /** SHA256 fingerprint, base64, without the `SHA256:` prefix. */
+    fingerprint: string;
+    /** The normalised wire form, `<type> <base64>`. */
+    public_key: string;
+    created_at: string;
+    last_used_at?: string | null;
+    /** Set = the key is switched off but still listed. */
+    disabled_at?: string | null;
+}
+
 export declare const StarButton: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 error: (message: string) => any;
 change: (value: boolean) => any;
@@ -1563,6 +2152,122 @@ onError?: ((message: string) => any) | undefined;
 onChange?: ((value: boolean) => any) | undefined;
 }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLButtonElement>;
 
+export declare interface StorageDriverCapabilities {
+    read?: boolean;
+    write?: boolean;
+    move?: boolean;
+    copy?: boolean;
+    delete?: boolean;
+    mkdir?: boolean;
+    presign?: boolean;
+    watch?: boolean;
+}
+
+export declare interface StorageDriverDescriptor {
+    driver: string;
+    label: string;
+    i18n_key: string;
+    fields: StorageField[];
+    capabilities: StorageDriverCapabilities;
+}
+
+/** One config key of a storage driver, as declared by the driver itself. */
+export declare interface StorageField {
+    key: string;
+    type: StorageFieldType;
+    /** English fallback label — used only when `i18n_key` is missing from
+     *  the catalogue, so a driver released after this build still renders
+     *  readable labels instead of raw keys. */
+    label: string;
+    help?: string;
+    i18n_key: string;
+    help_i18n_key?: string;
+    required: boolean;
+    /** Credential material: render masked, never log, never put in a URL. */
+    secret: boolean;
+    default?: unknown;
+    placeholder?: string;
+    options?: StorageFieldOption[];
+    min?: number;
+    max?: number;
+    monospace?: boolean;
+    multiline?: boolean;
+    advanced?: boolean;
+    /** THE field that scopes the storage inside the backend (s3 prefix,
+     *  local path, sftp/ftp/webdav root). The backend rejects an empty or
+     *  "/" value with ROOT_PATH_FORBIDDEN. */
+    root?: boolean;
+    /** Legacy spellings the driver still reads for this field. */
+    aliases?: string[];
+}
+
+export declare interface StorageFieldOption {
+    value: string;
+    /** English fallback; `i18n_key` wins when the catalogue has it. */
+    label: string;
+    i18n_key?: string;
+}
+
+export declare const StorageFields: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+"update:modelValue": (v: Record<string, unknown>) => any;
+}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{
+"onUpdate:modelValue"?: ((v: Record<string, unknown>) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+/**
+ * Connections — the shapes the storage-connection surface works with.
+ *
+ * Every one of these mirrors something the BACKEND declares, on purpose.
+ * `StorageField` / `StorageDriverDescriptor` are the wire form of
+ * `backend/internal/storage/descriptor.go`, served by
+ * `GET /api/admin/storage-drivers`: a driver states its own config keys,
+ * their types, which one is the storage root and which hold credentials,
+ * and every surface renders that one declaration.
+ *
+ * The alternative — a form per surface — is exactly what shipped broken:
+ * three of the four drivers the admin UI offered could not be created
+ * through it because the form collected keys the backend never read. A
+ * second hand-written form in the desktop app would have been a fourth
+ * copy of the same mistake.
+ */
+export declare type StorageFieldType = 'string' | 'int' | 'bool' | 'password' | 'select';
+
+/** A configured storage, as `GET /api/admin/storages` returns it. */
+export declare interface StorageRow {
+    id: number;
+    name: string;
+    driver: string;
+    enabled: boolean;
+    read_only: boolean;
+    config: Record<string, unknown>;
+    rbac_enabled?: boolean;
+    sync_mode?: string;
+    created_at?: string;
+    updated_at?: string;
+    stats?: {
+        file_count?: number;
+        total_size_bytes?: number;
+    };
+}
+
+export declare interface StorageTestResult {
+    ok: boolean;
+    error?: string;
+    object_count?: number;
+    sample_listing?: unknown[];
+}
+
+/** POST/PATCH body for a storage. */
+export declare interface StorageWrite {
+    name: string;
+    driver: string;
+    config: Record<string, unknown>;
+    read_only?: boolean;
+    enabled?: boolean;
+}
+
+declare type Store = Record<string, ResumeRecord>;
+
 /**
  * Create/update/empty the singleton `<style data-filex-theme>` element in
  * <head>. Idempotent — safe to call from every explorer instance.
@@ -1662,9 +2367,43 @@ export declare const THEMES: ThemeDef[];
 /** Map of `--fe-*` custom property → value. */
 export declare type ThemeTokenMap = Record<string, string>;
 
+export declare const TokensPanel: DefineComponent<__VLS_Props_19, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+active: (v: {
+hasToken: boolean;
+}) => any;
+}, string, PublicProps, Readonly<__VLS_Props_19> & Readonly<{
+onActive?: ((v: {
+hasToken: boolean;
+}) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLElement>;
+
 /** Turkish UI strings. */
 export declare const tr: Record<string, string>;
 
+/**
+ * connectionGuides — "how do I connect to this thing?", generated from the
+ * live deployment instead of written as prose.
+ *
+ * A published document says `https://fm.example.com/dav/` and leaves the
+ * reader to substitute three values, one of which (their own username) they
+ * usually get wrong. What ships here is the real host, the real storage
+ * name and the caller's own credential, with a copy button — which is the
+ * difference between a doc and a working paste. No surveyed product
+ * (Backblaze, R2, Storj, MinIO, Garage) does this; it is the cheapest win
+ * on the whole surface.
+ *
+ * Shape of the thing: a protocol is a `GuideBuilder` registered in
+ * `GUIDE_BUILDERS`. WebDAV is built here because WebDAV is what filex
+ * serves today; S3 and SFTP are a builder each and a registry line when
+ * their servers land — no second implementation, no second UI.
+ *
+ * The commands are not invented. They are the ones verified on 2026-08-14
+ * and written down in `docs/WEBDAV.md` and §13.5 of the write-path
+ * handover, including the three Windows registry limits that otherwise
+ * look exactly like filex bugs.
+ */
+export declare type Translate = (key: string, vars?: Record<string, string | number>) => string;
+
 /** A soft-deleted node as returned by the filex trash listing endpoint. */
 declare interface TrashEntry {
     id: number;
@@ -1683,6 +2422,13 @@ export declare interface UploadFinalizeResponse {
     url?: string;
 }
 
+/** Identity of one (destination, file) pair. */
+export declare function uploadFingerprint(path: string, file: {
+    name: string;
+    size: number;
+    lastModified?: number;
+}): string;
+
 export declare interface UploadInitResponse {
     uploadId: string;
     parts: Array<{
@@ -1697,11 +2443,22 @@ export declare interface UploadJob {
     id: string;
     file: File;
     path: string;
+    /** Server-side staged upload id, once `begin` has answered. */
     uploadId?: string;
     totalBytes: number;
+    /** Bytes filex has acknowledged (plus the chunk currently in flight). */
     uploadedBytes: number;
     percent: number;
-    status: 'pending' | 'initializing' | 'uploading' | 'finalizing' | 'done' | 'error' | 'aborted';
+    status: 'pending' | 'initializing' | 'uploading'
+    /** Every byte is in filex; the commit is being accepted. */
+    | 'committing'
+    /** Committed and listed; the ops worker is writing it to the backend. */
+    | 'transferring' | 'done' | 'error' | 'aborted';
+    /** Byte offset an interrupted session was picked up from, when it was. */
+    resumedFrom?: number;
+    /** Background transfer op, once the commit is accepted. */
+    opId?: number;
+    nodeId?: number;
     error?: string;
     cancel(): void;
 }
@@ -1714,12 +2471,62 @@ export declare interface UploadOptions {
     path: string;
     file: File;
     chunkSize?: number;
-    parallelChunks?: number;
     onProgress?: (job: UploadJob) => void;
-    onDone?: (job: UploadJob, result: UploadFinalizeResponse) => void;
+    onDone?: (job: UploadJob, result: UploadResult) => void;
     onError?: (job: UploadJob, err: Error) => void;
+    /**
+     * Wait for the backend transfer before resolving. Default false: the node is
+     * listed the moment the commit is accepted, which is the whole point of
+     * staging. `true` is for a caller that must not report success until the
+     * bytes are on the driver.
+     */
+    waitForTransfer?: boolean;
+}
+
+/** What `commit` answers, plus the fields a caller wants afterwards. */
+export declare interface UploadResult {
+    id: string;
+    op_id?: number;
+    node_id?: number;
+    path?: string;
+    transfer_state?: string;
 }
 
+export declare function useConnections(config: ExplorerConfig): {
+    drivers: ShallowRef<StorageDriverDescriptor[], StorageDriverDescriptor[]>;
+    driverNames: ComputedRef<string[]>;
+    storages: ShallowRef<StorageRow[], StorageRow[]>;
+    visible: ShallowRef<string[], string[]>;
+    me: Ref<    {
+    id: number;
+    email: string;
+    display_name?: string | undefined;
+    role?: string | undefined;
+    } | null, ConnectionsUser | {
+    id: number;
+    email: string;
+    display_name?: string | undefined;
+    role?: string | undefined;
+    } | null>;
+    loading: Ref<boolean, boolean>;
+    loaded: Ref<boolean, boolean>;
+    error: Ref<string | null, string | null>;
+    canManage: Ref<boolean | null, boolean | null>;
+    denial: Ref<ManageDenial | null, ManageDenial | null>;
+    load: () => Promise<void>;
+    createStorage: (body: StorageWrite) => Promise<StorageRow>;
+    updateStorage: (id: number, body: Partial<StorageWrite>) => Promise<StorageRow>;
+    deleteStorage: (id: number) => Promise<void>;
+    testStorage: (body: {
+        driver: string;
+        config: Record<string, unknown>;
+    }) => Promise<StorageTestResult>;
+    descriptor: (driver: string) => StorageDriverDescriptor | undefined;
+    fields: (driver: string) => StorageField[];
+    defaults: (driver: string) => Record<string, unknown>;
+    missingRequired: (driver: string, cfg: Record<string, unknown>) => StorageField[];
+};
+
 export declare function useFileApi(config: ExplorerConfig): {
     wsTicket: () => Promise<{
         ticket: string;
@@ -1876,6 +2683,74 @@ export declare function useMonacoLoader(): {
     getHighlight: typeof getHighlight;
 };
 
+export declare function useNFSExports(config: ExplorerConfig): {
+    exports: ShallowRef<NFSExport[], NFSExport[]>;
+    connection: Ref<    {
+    enabled: boolean;
+    host: string;
+    port: number;
+    } | null, NFSConnection | {
+    enabled: boolean;
+    host: string;
+    port: number;
+    } | null>;
+    loading: Ref<boolean, boolean>;
+    loaded: Ref<boolean, boolean>;
+    error: Ref<string | null, string | null>;
+    canMint: Ref<boolean | null, boolean | null>;
+    revealed: Ref<    {
+    export: {
+    id: number;
+    user_id: number;
+    api_token_id?: number | null | undefined;
+    label: string;
+    storage_name?: string | undefined;
+    prefix?: string | undefined;
+    read_only: boolean;
+    allow_cidrs?: string | undefined;
+    created_at: string;
+    last_used_at?: string | null | undefined;
+    expires_at?: string | null | undefined;
+    disabled_at?: string | null | undefined;
+    };
+    path: string;
+    enabled: boolean;
+    host: string;
+    port: number;
+    } | null, NFSExportCreated | {
+    export: {
+    id: number;
+    user_id: number;
+    api_token_id?: number | null | undefined;
+    label: string;
+    storage_name?: string | undefined;
+    prefix?: string | undefined;
+    read_only: boolean;
+    allow_cidrs?: string | undefined;
+    created_at: string;
+    last_used_at?: string | null | undefined;
+    expires_at?: string | null | undefined;
+    disabled_at?: string | null | undefined;
+    };
+    path: string;
+    enabled: boolean;
+    host: string;
+    port: number;
+    } | null>;
+    guideExport: ComputedRef<NFSExport | null>;
+    load: () => Promise<void>;
+    create: (req: {
+        label: string;
+        storage?: string;
+        prefix?: string;
+        read_only?: boolean;
+        allow_cidrs?: string;
+    }) => Promise<NFSExportCreated | null>;
+    setDisabled: (id: number, disabled: boolean) => Promise<void>;
+    remove: (id: number) => Promise<void>;
+    dismissPath: () => void;
+};
+
 export declare function useOperations(): {
     active: Ref<    {
     key: string;
@@ -2009,6 +2884,66 @@ declare interface UserSuggestion {
     role: string;
 }
 
+export declare function useS3Keys(config: ExplorerConfig): {
+    keys: ShallowRef<S3AccessKey[], S3AccessKey[]>;
+    connection: Ref<    {
+    endpoint: string;
+    enabled: boolean;
+    path_style: boolean;
+    } | null, S3Connection | {
+    endpoint: string;
+    enabled: boolean;
+    path_style: boolean;
+    } | null>;
+    loading: Ref<boolean, boolean>;
+    loaded: Ref<boolean, boolean>;
+    error: Ref<string | null, string | null>;
+    canMint: Ref<boolean | null, boolean | null>;
+    revealed: Ref<    {
+    key: {
+    id: number;
+    access_key_id: string;
+    user_id: number;
+    api_token_id?: number | null | undefined;
+    label: string;
+    bucket?: string | undefined;
+    prefix?: string | undefined;
+    created_at: string;
+    last_used_at?: string | null | undefined;
+    expires_at?: string | null | undefined;
+    disabled_at?: string | null | undefined;
+    };
+    secret: string;
+    endpoint: string;
+    enabled: boolean;
+    path_style: boolean;
+    } | null, S3KeyCreated | {
+    key: {
+    id: number;
+    access_key_id: string;
+    user_id: number;
+    api_token_id?: number | null | undefined;
+    label: string;
+    bucket?: string | undefined;
+    prefix?: string | undefined;
+    created_at: string;
+    last_used_at?: string | null | undefined;
+    expires_at?: string | null | undefined;
+    disabled_at?: string | null | undefined;
+    };
+    secret: string;
+    endpoint: string;
+    enabled: boolean;
+    path_style: boolean;
+    } | null>;
+    guideKey: ComputedRef<S3AccessKey | null>;
+    load: () => Promise<void>;
+    create: (req: S3KeyRequest) => Promise<S3KeyCreated | null>;
+    setDisabled: (id: number, disabled: boolean) => Promise<void>;
+    remove: (id: number) => Promise<void>;
+    dismissSecret: () => void;
+};
+
 export declare function useSelection(items: () => FileNode[]): {
     selected: Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>;
     anchor: Ref<string | null, string | null>;
@@ -2029,6 +2964,46 @@ export declare function useSelection(items: () => FileNode[]): {
 /** Reactive, override-aware view of the registry (registry order). */
 export declare function useShortcutList(): ComputedRef<ShortcutView[]>;
 
+export declare function useSSHKeys(config: ExplorerConfig): {
+    keys: ShallowRef<SSHPublicKey[], SSHPublicKey[]>;
+    connection: Ref<    {
+    enabled: boolean;
+    host: string;
+    port: number;
+    login: string;
+    ftps?: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    pasv_min: number;
+    pasv_max: number;
+    self_signed: boolean;
+    } | undefined;
+    } | null, SSHConnection | {
+    enabled: boolean;
+    host: string;
+    port: number;
+    login: string;
+    ftps?: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    pasv_min: number;
+    pasv_max: number;
+    self_signed: boolean;
+    } | undefined;
+    } | null>;
+    loading: Ref<boolean, boolean>;
+    loaded: Ref<boolean, boolean>;
+    error: Ref<string | null, string | null>;
+    canAdd: Ref<boolean | null, boolean | null>;
+    hasUsableKey: ComputedRef<boolean>;
+    load: () => Promise<void>;
+    add: (key: string, name?: string) => Promise<boolean>;
+    setDisabled: (id: number, disabled: boolean) => Promise<void>;
+    remove: (id: number) => Promise<void>;
+};
+
 export declare function useTabs(opts: UseTabsOptions): {
     tabs: Ref<TabState[], TabState[]>;
     activeId: Ref<string, string>;
@@ -2061,8 +3036,52 @@ export declare function useThemeState(): {
     setTheme: (id: string) => void;
 };
 
-export declare function useUploadChunked(config: ExplorerConfig, api: FileApi): {
-    uploadFile: (opts: UploadOptions) => Promise<UploadFinalizeResponse>;
+export declare function useTokens(config: ExplorerConfig): {
+    tokens: ShallowRef<ApiToken[], ApiToken[]>;
+    loading: Ref<boolean, boolean>;
+    loaded: Ref<boolean, boolean>;
+    error: Ref<string | null, string | null>;
+    canMint: Ref<boolean | null, boolean | null>;
+    revealed: Ref<    {
+    token: string;
+    row: {
+    id: number;
+    label: string;
+    scopes: string;
+    usernames?: string | null | undefined;
+    created_at?: string | undefined;
+    last_used_at?: string | null | undefined;
+    expires_at?: string | null | undefined;
+    };
+    } | null, ApiTokenCreated | {
+    token: string;
+    row: {
+    id: number;
+    label: string;
+    scopes: string;
+    usernames?: string | null | undefined;
+    created_at?: string | undefined;
+    last_used_at?: string | null | undefined;
+    expires_at?: string | null | undefined;
+    };
+    } | null>;
+    load: () => Promise<void>;
+    create: (req: ApiTokenRequest) => Promise<ApiTokenCreated | null>;
+    remove: (id: number) => Promise<void>;
+    dismiss: () => void;
+};
+
+export declare function useUploadChunked(config: ExplorerConfig, api: FileApi, storage?: ResumeStorage | null): {
+    uploadFile: (opts: UploadOptions) => Promise<UploadResult>;
+    /** True when this file is big enough (and the endpoints exist) to chunk. */
+    shouldChunk: (file: {
+        size: number;
+    }) => boolean;
+    /** The size at which chunking kicks in. */
+    threshold: () => number;
+    resumableFor: (path: string, file: File) => ResumeRecord | null;
+    listResumable: () => ResumeRecord[];
+    discardResumable: (rec: ResumeRecord) => Promise<void>;
 };
 
 /**