@brftech/filex-core 0.30.0 → 0.31.0

package/dist/index.d.ts

@@ -61,9 +61,40 @@ declare type __VLS_Props_12 = {
     locale: LocaleCode;
     /** True while the parent is creating the folder + uploading the marker. */
     busy?: boolean;
+    /** Short id of this installation's E2E escrow key, when one is configured.
+     *  Shown BEFORE the folder is created: escrow means the operator can open
+     *  it without the password, and that is not a detail to discover later. */
+    escrowKid?: string | null;
 };
 
 declare type __VLS_Props_13 = {
+    open: boolean;
+    locale: LocaleCode;
+    /** The key itself. Shown, copied, downloaded — never emitted or stored. */
+    recoveryKey: string;
+    /** Folder name, for the downloaded file and the dialog copy. */
+    folderName?: string;
+    /** Set when this installation holds an escrow key for the folder too. */
+    escrowKid?: string | null;
+    /** 'created' = a new folder; 'upgraded' = an existing folder gained recovery. */
+    variant?: 'created' | 'upgraded';
+};
+
+declare type __VLS_Props_14 = {
+    open: boolean;
+    locale: LocaleCode;
+    /** The folder has a user recovery key slot (v2 markers created since 0.31). */
+    hasRecovery: boolean;
+    /** The folder has an escrow slot AND this installation has escrow enabled. */
+    hasEscrow: boolean;
+    /** Short id of the escrow key the folder was sealed to. */
+    escrowKid?: string | null;
+    busy?: boolean;
+    /** Set by the parent after a failed attempt. */
+    error?: string | null;
+};
+
+declare type __VLS_Props_15 = {
     config: ExplorerConfig;
     /** Which half to open on. */
     initialTab?: 'storages' | 'connect';
@@ -72,7 +103,7 @@ declare type __VLS_Props_13 = {
     closable?: boolean;
 };
 
-declare type __VLS_Props_14 = {
+declare type __VLS_Props_16 = {
     fields: StorageField[];
     modelValue: Record<string, unknown>;
     locale: LocaleCode;
@@ -81,18 +112,18 @@ declare type __VLS_Props_14 = {
     disabled?: boolean;
 };
 
-declare type __VLS_Props_15 = {
+declare type __VLS_Props_17 = {
     guide: ProtocolGuide;
     locale: LocaleCode;
 };
 
-declare type __VLS_Props_16 = {
+declare type __VLS_Props_18 = {
     config: ExplorerConfig;
     /** Storage names the caller may see, for the confinement picker. */
     storages: string[];
 };
 
-declare type __VLS_Props_17 = {
+declare type __VLS_Props_19 = {
     config: ExplorerConfig;
     /**
      * Draw the key list and the paste box.
@@ -106,27 +137,6 @@ declare type __VLS_Props_17 = {
     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;
-    /**
-     * Render the full self-service key manager (scopes, folder confinement,
-     * expiry) instead of the one-field minter the guides embed.
-     */
-    full?: boolean;
-    /**
-     * 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;
@@ -161,6 +171,27 @@ declare type __VLS_Props_2 = {
     theme?: 'light' | 'dark' | 'auto';
 };
 
+declare type __VLS_Props_20 = {
+    config: ExplorerConfig;
+    /** Storage names the caller may see, for the confinement picker. */
+    storages: string[];
+};
+
+declare type __VLS_Props_21 = {
+    config: ExplorerConfig;
+    /**
+     * Render the full self-service key manager (scopes, folder confinement,
+     * expiry) instead of the one-field minter the guides embed.
+     */
+    full?: boolean;
+    /**
+     * 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_3 = {
     starred: boolean;
     nodeId: number;
@@ -174,6 +205,17 @@ declare type __VLS_Props_3 = {
     authCredentials?: RequestCredentials;
     /** Compact mode for grid view (no label, just the icon). */
     compact?: boolean;
+    /**
+     * Card mode — the same button sitting ON a grid/gallery tile instead of in
+     * a list cell: a round translucent chip in the tile's corner. It is the SAME
+     * component, deliberately: a card star written separately is a second
+     * starring path, and the two drift the first time one of them is fixed.
+     */
+    card?: boolean;
+    /** Locale for the title/label. ⚠ The strings used to be hardcoded English
+     *  ("Star"/"Unstar"), which is a Turkish user's only untranslated control in
+     *  the row. */
+    locale?: LocaleCode;
 };
 
 declare type __VLS_Props_4 = {
@@ -399,11 +441,33 @@ export declare interface Capabilities {
     /** Longest life a new share link may be given, in days (0 = no ceiling).
      *  Read by the share dialogs so they offer only expiries the server keeps. */
     share_max_ttl_days?: number;
+    /** Is the caller a person (`'user'` — a session OR their own API token) or an
+     *  integration (`'app'` — a host proxy, a bot, an MCP client)? The explorer
+     *  reads it to decide whether to draw the identity-bearing surfaces; see
+     *  ExplorerConfig.callerKind. Absent on a server older than the app/user
+     *  token split, which is why every reader treats "missing" as a person. */
+    caller_kind?: 'user' | 'app';
     external?: {
         onlyoffice?: ExternalServiceStatus;
         drawio?: ExternalServiceStatus;
         mermaid?: ExternalServiceStatus;
     };
+    /** Whether this installation holds an escrow key for E2E-encrypted folders,
+     *  and the public half the browser wraps new folders' master keys to.
+     *
+     *  Published on purpose. Escrow means the operator can open the folders you
+     *  create here without your password, and someone about to create one is
+     *  entitled to know that BEFORE they create it. Fixed at install time
+     *  (FILEX_INSTALLATION_E2E_ESCROW_KEY), so this answer never changes for a
+     *  running installation. */
+    e2e_escrow?: {
+        enabled: boolean;
+        /** Short id of the escrow key (SHA-256(SPKI)[:8], hex). */
+        kid?: string;
+        alg?: string;
+        /** Base64 SPKI. Public material — it can only seal, never open. */
+        public_key?: string;
+    };
 }
 
 export declare function clearResume(store: ResumeStorage | null, key: string): void;
@@ -421,7 +485,7 @@ 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 const ConnectionGuideView: DefineComponent<__VLS_Props_17, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_17> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
 
 export declare type ConnectionsApi = ReturnType<typeof useConnections>;
 
@@ -446,13 +510,13 @@ export declare function connectionsBase(config: ExplorerConfig): string;
  */
 export declare function connectionsOrigin(config: ExplorerConfig): string;
 
-export declare const ConnectionsPanel: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+export declare const ConnectionsPanel: DefineComponent<__VLS_Props_15, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 error: (err: {
 message: string;
 }) => any;
 close: () => any;
 changed: () => any;
-}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{
+}, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{
 onError?: ((err: {
 message: string;
 }) => any) | undefined;
@@ -478,31 +542,59 @@ declare interface ContextAction {
     divider?: boolean;
 }
 
+export declare interface CreatedFolder {
+    marker: E2eMarker;
+    /** The folder master key, ready for encryptFile/decryptFile. */
+    fmk: CryptoKey;
+    /** Show this ONCE. filex never stores it and can never show it again. */
+    recoveryKey: string;
+}
+
 /**
- * Tiny per-explorer key ring: encrypted-folder root (wire path) → KEK.
- * Lives ONLY in memory — "Kilitle" drops the entry, a reload drops all.
+ * Create a v2 encrypted folder: random FMK, wrapped under the password KEK,
+ * under a freshly minted user recovery key, and — when the installation has
+ * escrow enabled — to the escrow public key.
+ */
+export declare function createEncryptedFolder(password: string, opts?: CreateFolderOptions): Promise<CreatedFolder>;
+
+export declare interface CreateFolderOptions {
+    iterations?: number;
+    /** Base64 SPKI of the installation escrow key, when escrow is enabled. */
+    escrowPublicKey?: string | null;
+}
+
+/**
+ * Tiny per-explorer key ring: encrypted-folder root (wire path) → FMK.
+ * Lives ONLY in memory — "Lock" drops the entry, a reload drops all.
  */
 export declare function createKeyRing(): {
     get(root: string): CryptoKey | undefined;
-    set(root: string, kek: CryptoKey): void;
-    /** Drop one folder's key ("Kilitle"). */
+    set(root: string, fmk: CryptoKey): void;
+    /** Drop one folder's key ("Lock"). */
     lock(root: string): void;
     has(root: string): boolean;
     clear(): void;
 };
 
-/** Create a fresh folder marker for `password` (also returns the derived KEK). */
+/**
+ * Create a v1 folder marker — the pre-0.31 format, with NO recovery of any
+ * kind.
+ *
+ * @deprecated Use `createEncryptedFolder`. Kept exported, and kept producing
+ * a genuine v1 marker, so an embedder pinned to the old API keeps creating
+ * folders this build can still open rather than half-formed v2 ones.
+ */
 export declare function createMarker(password: string, iterations?: number): Promise<{
     marker: E2eMarker;
     kek: CryptoKey;
 }>;
 
 /**
- * Decrypt a 'filexe2e' blob with the folder KEK. Throws E2eDecryptError on
- * a wrong key / tampered data, and a plain Error when the header is not an
- * e2e file at all.
+ * Decrypt a 'filexe2e' blob with the folder master key. Throws
+ * E2eDecryptError on a wrong key / tampered data, and a plain Error when the
+ * header is not an e2e file at all.
  */
-export declare function decryptFile(kek: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
+export declare function decryptFile(fmk: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;
 
 export declare const DEFAULT_THEME_ID = "default";
 
@@ -522,6 +614,9 @@ export declare function deriveKek(password: string, salt: Uint8Array, iterations
 
 export declare const E2E_DEFAULT_ITERATIONS = 600000;
 
+/** The only escrow algorithm this version understands. */
+export declare const E2E_ESCROW_ALG = "RSA-OAEP-256";
+
 export declare const E2E_MAGIC = "filexe2e";
 
 /**
@@ -529,33 +624,71 @@ export declare const E2E_MAGIC = "filexe2e";
  *
  * WebCrypto ONLY — zero dependencies. Design doc: docs/E2E-ENCRYPTION.md.
  *
- * Scheme (v1):
- *   folder password ─PBKDF2-SHA256(600k iter, per-folder 16B salt)─▶ KEK (AES-256-GCM)
- *   per-file random 32B DEK (AES-256-GCM) encrypts the content one-shot;
- *   the DEK is wrapped with the KEK and stored in the file's own header.
+ * ── Scheme ────────────────────────────────────────────────────────────
+ *
+ * Every encrypted file wraps its own random DEK under ONE key, the folder
+ * master key (FMK), and stores the wrapped copy in its own 97-byte header.
+ * The FMK is what a "key slot" in the folder marker hands back:
  *
- * File layout ('filexe2e' magic, fixed 97-byte header):
+ *   password ─PBKDF2-SHA256(600k, 16B salt)─▶ KEK ─┐
+ *   recovery key ─HKDF-SHA256(16B salt)─▶ RKEK ────┼─▶ unwraps the FMK
+ *   escrow private key ─RSA-OAEP-256───────────────┘
+ *                                                   │
+ *   per-file random 32B DEK ◀── AES-GCM-wrapped by the FMK, in the header
+ *
+ * Adding a recovery path therefore costs one more wrapped copy of a single
+ * 32-byte key in the marker — not a re-encrypt of anything. The file format
+ * below is UNCHANGED from v1 and stays that way; only the marker grew.
+ *
+ * ── Marker versions ───────────────────────────────────────────────────
+ *
+ * v1 (shipped up to 0.30.1) has no slots: the DEK is wrapped directly by
+ * the password KEK. Read that as "the FMK *is* the KEK". Such folders keep
+ * opening with nothing but their password, forever — the v1 read path is a
+ * first-class path here, not a migration shim.
+ *
+ * v2 adds the slots. It comes in two flavours, told apart by `fmk`:
+ *   - `fmk: 'wrapped'` — a fresh random FMK, held in `fmk_pw` wrapped under
+ *     the password KEK. Every folder created from 0.31 on.
+ *   - `fmk: 'kek'`     — a v1 folder that was given recovery keys in place.
+ *     Its files were already wrapped under the KEK and are not rewritten, so
+ *     the FMK stays defined as "the password-derived KEK" and the recovery
+ *     slots wrap those raw 32 bytes. The password path is byte-identical to
+ *     v1; only the extra slots are new.
+ *
+ * ── Invariants ────────────────────────────────────────────────────────
+ *
+ *   - No key, password or recovery key is ever stored, logged or sent to a
+ *     server. The FMK lives in an in-memory key ring and dies with the tab.
+ *   - `deriveKek` imports non-extractable. Raw KEK bytes are produced ONLY
+ *     by `deriveKekBits`, only while upgrading a v1 marker, and only long
+ *     enough to wrap them into the new slots.
+ *   - A folder created while escrow was off carries no escrow slot, so the
+ *     escrow key cannot open it. That is arithmetic, not policy.
+ *
+ * File layout ('filexe2e' magic, fixed 97-byte header) — UNCHANGED in v2:
  *   [0..8)   magic  "filexe2e"
  *   [8]      version 0x01
  *   [9..21)  wrapIV  (12B)  — GCM IV of the DEK wrap
- *   [21..69) wrappedDEK (48B = 32B DEK + 16B GCM tag)
+ *   [21..69) wrappedDEK (48B = 32B DEK + 16B GCM tag), wrapped by the FMK
  *   [69..81) dataIV  (12B)  — GCM IV of the content
  *   [81..97) reserved (zeros; v2 chunking/metadata)
  *   [97..)   ciphertext (content + 16B GCM tag)
- *
- * Folder marker `.filex-e2e.json` at the encrypted-folder root:
- *   { v:1, salt:<b64 16B>, iter:600000, verify:<b64 12B IV || GCM('filex-e2e-verify-v1')> }
- *
- * The KEK NEVER leaves memory — no storage of any kind. Password loss is
- * data loss by design (no recovery path exists anywhere).
  */
 export declare const E2E_MARKER_NAME = ".filex-e2e.json";
 
+/** Marker schema version written by this build. v1 markers still read. */
+export declare const E2E_MARKER_VERSION = 2;
+
 /** MVP single-shot in-memory ceiling — larger uploads are refused with a warning. */
 export declare const E2E_MAX_FILE_BYTES: number;
 
 export declare const E2E_MIN_PASSWORD_LEN = 8;
 
+/** Entropy of a user recovery key: 20 bytes = 160 bits = exactly 32 base32 chars. */
+export declare const E2E_RECOVERY_KEY_BYTES = 20;
+
+/** File-header version byte. Unchanged by the recovery work. */
 export declare const E2E_VERSION = 1;
 
 /** Thrown on wrong password / corrupted ciphertext (GCM tag mismatch). */
@@ -563,6 +696,17 @@ export declare class E2eDecryptError extends Error {
     constructor(msg?: string);
 }
 
+/** Escrow slot: the FMK encrypted to the installation's escrow public key. */
+export declare interface E2eEscrowSlot {
+    /** First 8 bytes of SHA-256(SPKI), hex — names WHICH escrow key this is. */
+    kid: string;
+    alg: string;
+    blob: string;
+}
+
+/** How the folder master key is obtained from the password slot. */
+export declare type E2eFmkMode = 'kek' | 'wrapped';
+
 export declare type E2eKeyRing = ReturnType<typeof createKeyRing>;
 
 export declare interface E2eMarker {
@@ -570,8 +714,36 @@ export declare interface E2eMarker {
     salt: string;
     iter: number;
     verify: string;
+    /** v2 only. Absent on a v1 marker, where the FMK is implicitly the KEK. */
+    fmk?: E2eFmkMode;
+    /** v2 + fmk==='wrapped' only: base64 12B IV || AES-GCM(KEK, FMK). */
+    fmk_pw?: string;
+    /** v2 only, optional: the user recovery key slot. */
+    rk?: E2eRecoverySlot;
+    /** v2 only, optional: the operator escrow slot. */
+    esc?: E2eEscrowSlot;
+}
+
+/** User-recovery-key slot: HKDF salt + the FMK wrapped under the derived key. */
+export declare interface E2eRecoverySlot {
+    salt: string;
+    blob: string;
 }
 
+export declare const E2eRecoveryUnlockModal: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+close: () => any;
+submit: (payload: {
+mode: "recovery" | "escrow";
+value: string;
+}) => any;
+}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{
+onClose?: (() => any) | undefined;
+onSubmit?: ((payload: {
+mode: "recovery" | "escrow";
+value: string;
+}) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
 /** Current combo for an action ('' = unbound). */
 export declare function effectiveCombo(id: string): string;
 
@@ -593,11 +765,14 @@ password: string;
 }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /**
- * Encrypt `content` under the folder KEK: mints a fresh DEK, encrypts the
- * content one-shot, wraps the DEK with the KEK and prepends the fixed
+ * Encrypt `content` under the folder master key: mints a fresh DEK, encrypts
+ * the content one-shot, wraps the DEK with the FMK and prepends the fixed
  * 'filexe2e' header. Throws when content exceeds E2E_MAX_FILE_BYTES.
+ *
+ * `fmk` is the key an unlock returned. On a v1 folder that is the password
+ * KEK, which is why v1 files keep working untouched.
  */
-export declare function encryptFile(kek: CryptoKey, content: ArrayBuffer): Promise<ArrayBuffer>;
+export declare function encryptFile(fmk: CryptoKey, content: ArrayBuffer): Promise<ArrayBuffer>;
 
 /**
  * Resolved endpoint map. `useFileApi` derives this once on construction
@@ -635,6 +810,8 @@ export declare interface EndpointMap {
     restore: string | null;
     trashList: string | null;
     trashRestore: string | null;
+    e2eEscrowChallenge: string | null;
+    e2eEscrowUsed: string | null;
 }
 
 export declare function ensureHighlight(): Promise<unknown | null>;
@@ -646,6 +823,13 @@ export declare function ensureHighlight(): Promise<unknown | null>;
  */
 export declare function ensureMonaco(): Promise<unknown | null>;
 
+/**
+ * Stable short name for an escrow key: first 8 bytes of SHA-256(SPKI), hex.
+ * Written into every escrow slot so a marker says WHICH key opens it, and so
+ * the UI can tell "this server's escrow key" from "some other one".
+ */
+export declare function escrowKeyId(spkiB64: string): Promise<string>;
+
 export declare interface ExplorerConfig {
     /**
      * Modern shorthand: URL prefix for the standard /api/files/* layout.
@@ -707,6 +891,10 @@ export declare interface ExplorerConfig {
     trashList?: string;
     /** filex trash restore endpoint — `POST { node_id }`. */
     trashRestore?: string;
+    /** E2E escrow proof-of-possession — `POST { path } → { id, challenge }`. */
+    e2eEscrowChallenge?: string;
+    /** E2E escrow use report — `POST { path, id, nonce }`. */
+    e2eEscrowUsed?: string;
     /** Public share base URL — `${shareBase}/${uuid}` */
     shareBase?: string;
     /** Auth strategy (see AuthConfig). */
@@ -848,11 +1036,37 @@ export declare interface ExplorerConfig {
      * the bug this became: for a year the sole place to mint the token the FTPS
      * guide told you to use was the admin panel.
      *
+     * ⚠ Role is not the same question as `callerKind`. "API keys" IS hidden for
+     * an app token — not because of what that caller may do, but because there is
+     * no single person behind it whose keys they would be. See `callerKind`.
+     *
      * ⚠ The entries live in the panel, so `sideNav: false` takes them with it.
      * Hosts that want the surface without the panel mount `<filex-connections>`
      * (or `ConnectionsPanel`) on a page of their own.
      */
     connections?: boolean;
+    /**
+     * Who is behind this explorer — a person, or an integration?
+     *
+     * `'user'` (a signed-in human, or their own API token) draws everything.
+     * `'app'` suppresses the surfaces that only mean something for ONE person:
+     * **API keys**, **Recent**, **Starred** and **Shared with me**. Upload, the
+     * storage list, Trash and "How to connect" stay — an embed's users still
+     * upload files and still need mount instructions.
+     *
+     * Why it exists: a filex API token authenticates AS its owner, and the embeds
+     * we run authenticate every visitor with ONE shared token injected by the
+     * host's proxy. v0.30.0 put "API keys" in the panel, so under that token an
+     * embed visitor could list and revoke the credential the embed itself runs
+     * on — and "your Recent" meant the token owner's history shown to a stranger.
+     *
+     * Default: read from `GET /api/files/capabilities` (`caller_kind`), which is
+     * authoritative because only the server knows the token's kind (migration
+     * 00030). Set this only to answer BEFORE that request lands — a host that
+     * already knows it proxies with an app token spares its users the flash of a
+     * Starred row that then disappears. A value here wins over the server's.
+     */
+    callerKind?: 'user' | 'app';
     /** Default view. */
     viewMode?: 'list' | 'grid';
     /** Override max upload size (MB) — falls back to /limits otherwise. */
@@ -1454,6 +1668,12 @@ export declare interface FileNode {
  */
 export declare function findShortcutConflict(combo: string, excludeId: string): ShortcutConflict | null;
 
+/**
+ * Format 20 raw bytes as the string the user writes down:
+ * `XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX` (160 bits, no padding waste).
+ */
+export declare function formatRecoveryKey(raw: Uint8Array): string;
+
 /** What an FTP client needs to be told, computed on the server. */
 declare interface FTPSFacts {
     enabled: boolean;
@@ -1470,6 +1690,9 @@ declare interface FTPSFacts {
     self_signed: boolean;
 }
 
+/** Mint a fresh user recovery key. Shown once, never stored by filex. */
+export declare function generateRecoveryKey(): string;
+
 /**
  * Generate a stylesheet that mirrors styles/variables.css' selector
  * cascade 1:1 (light base → explicit-dark selectors → prefers-dark media
@@ -1627,11 +1850,17 @@ export declare interface GuideFact {
 export declare function guideProtocols(): string[];
 
 /** True when the buffer starts with the 'filexe2e' magic. */
-export declare function hasMagic(buf: ArrayBuffer | Uint8Array): boolean;
+export declare function hasMagic(data: ArrayBuffer | Uint8Array): boolean;
 
 /** `https://fm.example.com` → `fm.example.com`; anything unparseable comes back whole. */
 export declare function hostOf(origin: string): string;
 
+/** Import the escrow private key the admin pastes in (base64 PKCS#8, PEM tolerated). */
+export declare function importEscrowPrivateKey(pkcs8B64: string): Promise<CryptoKey>;
+
+/** Import the installation escrow public key (base64 SPKI, as the server serves it). */
+export declare function importEscrowPublicKey(spkiB64: string): Promise<CryptoKey>;
+
 declare interface InviteResponse {
     mode: 'granted' | 'user_created' | 'shared';
     user_id?: number;
@@ -1685,6 +1914,12 @@ export declare interface ManagerResponse {
     files: FileNode[];
 }
 
+/** True when the folder has an operator escrow slot. */
+export declare function markerHasEscrow(m: E2eMarker | null): boolean;
+
+/** True when the folder has a user recovery key slot. */
+export declare function markerHasRecovery(m: E2eMarker | null): boolean;
+
 /** True when the hit matched (at least partly) inside file CONTENT. */
 export declare function matchedInContent(matched: unknown): boolean;
 
@@ -1737,7 +1972,7 @@ export declare interface NFSExportCreated extends NFSConnection {
     path: string;
 }
 
-export declare const NFSExportsPanel: DefineComponent<__VLS_Props_18, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+export declare const NFSExportsPanel: DefineComponent<__VLS_Props_20, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 active: (v: {
 host: string;
 port: number;
@@ -1745,7 +1980,7 @@ enabled: boolean;
 path?: string;
 readOnly: boolean;
 }) => any;
-}, string, PublicProps, Readonly<__VLS_Props_18> & Readonly<{
+}, string, PublicProps, Readonly<__VLS_Props_20> & Readonly<{
 onActive?: ((v: {
 host: string;
 port: number;
@@ -1865,9 +2100,16 @@ export declare type OperationsStore = ReturnType<typeof useOperations>;
 
 export declare type OperationStatus = 'running' | 'done' | 'error' | 'aborted';
 
-/** Parse marker JSON text; returns null when the shape is not a v1 marker. */
+/** Parse marker JSON text; returns null when the shape is not a marker we read. */
 export declare function parseMarker(text: string): E2eMarker | null;
 
+/**
+ * Parse a typed-in recovery key back to its 20 bytes, or null when it is not
+ * one. Forgiving about how a human retypes it: case, dashes, spaces and the
+ * Crockford look-alikes (O to 0, I/L to 1) are all normalised away.
+ */
+export declare function parseRecoveryKey(s: string): Uint8Array | null;
+
 export declare interface PendingOp {
     id: number;
     op_type: 'copy' | 'move' | 'delete';
@@ -1988,6 +2230,12 @@ declare interface RecentNode {
     last_opened?: string;
 }
 
+export declare const RecoveryKeyModal: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+close: () => any;
+}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{
+onClose?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
 declare function reload(): Promise<void>;
 
 export declare function resetAllShortcuts(): void;
@@ -2096,14 +2344,14 @@ export declare interface S3KeyRequest {
     expires_at?: string;
 }
 
-export declare const S3KeysPanel: DefineComponent<__VLS_Props_16, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+export declare const S3KeysPanel: DefineComponent<__VLS_Props_18, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 active: (v: {
 accessKeyID: string;
 secret?: string;
 endpoint: string;
 pathStyle: boolean;
 }) => any;
-}, string, PublicProps, Readonly<__VLS_Props_16> & Readonly<{
+}, string, PublicProps, Readonly<__VLS_Props_18> & Readonly<{
 onActive?: ((v: {
 accessKeyID: string;
 secret?: string;
@@ -2220,6 +2468,7 @@ export declare interface ShortcutHandlers {
     onShowHelp?: () => void;
     onToggleInspector?: () => void;
     onToggleHidden?: () => void;
+    onStar?: () => void;
     onQuickLook?: () => void;
     onTabNew?: () => void;
     onTabClose?: () => void;
@@ -2286,7 +2535,7 @@ export declare interface SSHConnection {
     ftps?: FTPSFacts;
 }
 
-export declare const SSHKeysPanel: DefineComponent<__VLS_Props_17, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+export declare const SSHKeysPanel: DefineComponent<__VLS_Props_19, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 active: (v: {
 host: string;
 port: number;
@@ -2295,7 +2544,7 @@ enabled: boolean;
 hasKey: boolean;
 ftps?: FTPSFacts;
 }) => any;
-}, string, PublicProps, Readonly<__VLS_Props_17> & Readonly<{
+}, string, PublicProps, Readonly<__VLS_Props_19> & Readonly<{
 onActive?: ((v: {
 host: string;
 port: number;
@@ -2391,9 +2640,9 @@ export declare interface StorageFieldOption {
     i18n_key?: string;
 }
 
-export declare const StorageFields: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+export declare const StorageFields: DefineComponent<__VLS_Props_16, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 "update:modelValue": (v: Record<string, unknown>) => any;
-}, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{
+}, string, PublicProps, Readonly<__VLS_Props_16> & Readonly<{
 "onUpdate:modelValue"?: ((v: Record<string, unknown>) => any) | undefined;
 }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
 
@@ -2550,11 +2799,11 @@ 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, {} & {
+export declare const TokensPanel: DefineComponent<__VLS_Props_21, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 active: (v: {
 hasToken: boolean;
 }) => any;
-}, string, PublicProps, Readonly<__VLS_Props_19> & Readonly<{
+}, string, PublicProps, Readonly<__VLS_Props_21> & Readonly<{
 onActive?: ((v: {
 hasToken: boolean;
 }) => any) | undefined;
@@ -2600,6 +2849,44 @@ declare interface TrashEntry {
     ttl_days?: number | null;
 }
 
+/**
+ * Unlock with the installation escrow private key.
+ *
+ * Returns null when the folder has no escrow slot — which is the case for
+ * every folder created while escrow was off, and is why escrow cannot be
+ * turned on retroactively.
+ */
+export declare function unlockWithEscrowKey(marker: E2eMarker, privateKey: CryptoKey): Promise<CryptoKey | null>;
+
+/**
+ * Unlock with the folder password. Returns the FMK (the key `decryptFile`
+ * wants) or null when the password is wrong.
+ */
+export declare function unlockWithPassword(marker: E2eMarker, password: string): Promise<CryptoKey | null>;
+
+/**
+ * Unlock with the user recovery key shown when the folder was created.
+ * Returns null for a malformed key, a wrong key, or a folder that has no
+ * recovery slot at all — the caller cannot tell those apart, and neither can
+ * an attacker.
+ */
+export declare function unlockWithRecoveryKey(marker: E2eMarker, recoveryKey: string): Promise<CryptoKey | null>;
+
+/**
+ * Give an existing v1 folder recovery keys, in place and without rewriting a
+ * single file.
+ *
+ * The v1 files are wrapped under the password KEK, so the FMK stays defined
+ * as "the KEK" (`fmk: 'kek'`) and the new slots wrap those raw bytes. The
+ * password path afterwards is byte-identical to what it was.
+ *
+ * ⚠ Requires the password — this is only callable at the one moment filex
+ * ever has it. There is no way to give a v1 folder recovery without it.
+ * ⚠ When the installation has escrow on, this ALSO hands the operator a key
+ * to a folder that did not have one. The caller must say so before asking.
+ */
+export declare function upgradeMarkerV1(marker: E2eMarker, password: string, opts?: CreateFolderOptions): Promise<CreatedFolder>;
+
 export declare interface UploadFinalizeResponse {
     s3Key: string;
     url?: string;
@@ -2759,6 +3046,19 @@ export declare function useFileApi(config: ExplorerConfig): {
     fetchArrayBuffer: (path: string) => Promise<ArrayBuffer>;
     limits: () => Promise<UploadLimits>;
     capabilities: () => Promise<Capabilities>;
+    e2eEscrowChallenge: (path: string) => Promise<{
+        id: string;
+        challenge: string;
+        kid: string;
+    }>;
+    e2eEscrowUsed: (payload: {
+        path: string;
+        id: string;
+        nonce: string;
+    }) => Promise<{
+        ok: boolean;
+        notified: boolean;
+    }>;
     createShare: (payload: {
         path: string;
         password?: boolean;
@@ -3271,6 +3571,10 @@ export declare function useUploadChunked(config: ExplorerConfig, api: FileApi, s
  * Check `password` against a folder marker. Resolves to the derived KEK on
  * success, or `null` on a wrong password (GCM tag mismatch on the verify
  * blob). Never talks to any server.
+ *
+ * ⚠ This returns the KEK, not the FMK. On a v1 folder they are the same key;
+ * on a v2 `fmk: 'wrapped'` folder they are not. Use `unlockWithPassword` to
+ * get the key that actually decrypts files.
  */
 export declare function verifyPassword(marker: E2eMarker, password: string): Promise<CryptoKey | null>;