@brftech/filex-core 0.30.1 → 0.32.0

package/dist/index.d.ts

@@ -54,6 +54,13 @@ declare type __VLS_Props_11 = {
     /** ui-fix — mirror the main panel's virtual `.trash` row at storage root
      *  so both split panes list identical rows (no row-offset). Defaults on. */
     trashVisible?: boolean;
+    /**
+     * The navigation panel is already offering Trash, so neither pane draws the
+     * virtual row. Passed down rather than worked out here: the panel belongs to
+     * the host explorer, and a pane that guessed at it is how the two halves of a
+     * split end up listing different rows.
+     */
+    navOffersTrash?: boolean;
 };
 
 declare type __VLS_Props_12 = {
@@ -61,9 +68,46 @@ 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;
+    /**
+     * Whether the escrow door applies to THIS folder — see escrowAvailability.
+     * 'predates' and 'other-key' are not "no escrow tab"; they are two
+     * different facts the dialog has to state, because an admin who knows the
+     * installation has escrow reads a missing tab as a bug and tries the key
+     * anyway.
+     */
+    escrowState: EscrowAvailability;
+    /** Short id of the escrow key THIS FOLDER was sealed to, when it has one. */
+    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 +116,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 +125,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 +150,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 +184,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 +218,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 = {
@@ -245,6 +300,40 @@ declare type __VLS_Props_9 = {
     narrow?: boolean;
 };
 
+/**
+ * Give an EXISTING v2 folder an escrow slot, in place, using the folder
+ * password its owner has just typed.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────
+ *
+ * Escrow used to be all-or-nothing at install time, and then adoptable but
+ * never retroactive: on any installation that had been running for a while,
+ * escrow covered only folders nobody had created yet. On a real deployment
+ * the folders that matter already exist, so "new folders only" means escrow
+ * covers nothing anyone cares about.
+ *
+ * The server still cannot do this, and that has not changed: adding a slot
+ * needs the folder master key, which needs a credential the server has never
+ * held. What CAN do it is the browser, at the one moment the password is in
+ * memory — exactly where `upgradeMarkerV1` already lives. Same moment, same
+ * shape, different slot.
+ *
+ * ⚠⚠ Accepting hands the operator of this installation a second, permanent
+ * way into this folder. It is the folder's owner who decides, from inside,
+ * with the password; no configuration change and no admin action can do it
+ * for them. The caller MUST say that in those words before calling this —
+ * see `e2e.escrowoffer.*` in the locales.
+ *
+ * ⚠ v2 only. A v1 marker has no slots at all; the path for those is
+ * `upgradeMarkerV1`, which already seals an escrow slot when the
+ * installation has a key and already discloses it. Two doors into the same
+ * room would be two chances to get the disclosure wrong.
+ *
+ * ⚠ No file is re-encrypted, moved or rewritten. Only `.filex-e2e.json`
+ * changes, and only by gaining `esc` (and losing `esc_declined`).
+ */
+export declare function addEscrowSlot(marker: E2eMarker, password: string, escrowPublicKey: string): Promise<E2eMarker>;
+
 /**
  * The self-service API-token surface (`/api/tokens`).
  *
@@ -399,11 +488,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 +532,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 +557,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 +589,72 @@ 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.
+ * Record that this folder's owner was offered an escrow slot and declined.
+ *
+ * A refusal is a decision, not a delay: without this the offer would come
+ * back on every single unlock, which is how people learn to click past
+ * security dialogs without reading them. Nothing about the folder's keys
+ * changes — the only effect is that filex stops asking.
+ *
+ * Reversible by `addEscrowSlot`, which is the way back for somebody who
+ * says no today and changes their mind next month.
+ */
+export declare function declineEscrowSlot(marker: E2eMarker, when: string): E2eMarker;
+
+/**
+ * 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 +674,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 +684,80 @@ 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:
+ *
+ *   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 ───────────────────────────────────────────────────
  *
- * File layout ('filexe2e' magic, fixed 97-byte header):
+ * 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 for a marker whose FMK *is* the KEK
+ *     (`upgradeMarkerV1`, and `addEscrowSlot` on a folder it produced), and
+ *     only long enough to wrap them into a slot.
+ *   - A folder created while escrow was off carries no escrow slot, so the
+ *     escrow key cannot open it, and nothing the OPERATOR does changes
+ *     that — not enabling escrow, not adopting it, not any admin action or
+ *     future version. That is arithmetic, not policy: adding a slot needs
+ *     the folder master key, and the server has never held a credential
+ *     that produces one.
+ *   - The folder's OWNER can, from inside, with the password:
+ *     `addEscrowSlot`. That is the only door, it opens from one side only,
+ *     and it is the reason `escrowAvailability` says "not as things stand"
+ *     rather than "never".
+ *
+ * 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 +765,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 +783,53 @@ 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;
+    /**
+     * v2 only, optional: an ISO timestamp recording that this folder's owner
+     * was OFFERED an escrow slot and said no.
+     *
+     * It lives in the marker rather than in browser storage because the unit
+     * of the decision is the FOLDER, not the device: the same person opening
+     * the folder from their phone must not be asked again, and a decision
+     * that vanished when someone cleared their site data would be no decision
+     * at all. It travels with the folder through a move, a backup and a
+     * restore, for the same reason the key slots do.
+     *
+     * It holds no key material and hides nothing from the operator — it is a
+     * record of an answer, and its only effect is that filex stops asking.
+     * `addEscrowSlot` clears it, so a decline is reversible by the one person
+     * who can reverse it.
+     */
+    esc_declined?: string;
+}
+
+/** 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 +851,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 +896,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 +909,69 @@ export declare function ensureHighlight(): Promise<unknown | null>;
  */
 export declare function ensureMonaco(): Promise<unknown | null>;
 
+/**
+ * Why the escrow door is, or is not, on offer for this folder.
+ *
+ *   'off'        this installation has no escrow key at all.
+ *   'available'  the folder is sealed to THIS installation's escrow key.
+ *   'predates'   the installation has an escrow key, and this folder has no
+ *                escrow slot: it was created before escrow existed here.
+ *   'other-key'  the folder carries an escrow slot sealed to a DIFFERENT
+ *                key id — it came from another installation, via a restore
+ *                or a copied data directory.
+ *
+ * ⚠ 'predates' exists because escrow can be ADOPTED by an installation
+ * that already has folders (FILEX_INSTALLATION_E2E_ESCROW_ADOPT), and
+ * adoption is not retroactive: the folder's master key was wrapped to its
+ * recovery paths when the folder was created. Before this distinction
+ * existed the dialog simply showed no Escrow tab, which is true but says
+ * nothing — an admin who knows escrow is on reads a missing tab as a bug,
+ * tries the key anyway, and learns the real answer from a failure. The UI
+ * has to say it instead.
+ *
+ * ⚠⚠ 'predates' means "not as things stand", NOT "never". The folder's
+ * owner can add a slot from inside with the password (`addEscrowSlot`,
+ * offered at unlock). Any wording built on this state has to leave that
+ * door visible, or it tells an operator their escrow key can never reach a
+ * folder whose owner could hand it over this afternoon.
+ *
+ * ⚠ 'other-key' was a quieter lie: the dialog labelled the escrow field
+ * with the INSTALLATION's key id whatever the folder's slot said, so a
+ * folder restored from another install looked openable by the key the
+ * operator has, and was not.
+ */
+export declare type EscrowAvailability = 'off' | 'available' | 'predates' | 'other-key';
+
+export declare function escrowAvailability(m: E2eMarker | null, installationKid: string | null | undefined): EscrowAvailability;
+
+/**
+ * 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>;
+
+/**
+ * Whether this folder's owner should be offered an escrow slot, and whether
+ * they have already answered.
+ *
+ *   'n/a'       nothing to offer: the installation has no escrow key, the
+ *               folder already has a slot, or the marker is v1 (whose path
+ *               is `upgradeMarkerV1`).
+ *   'offer'     the offer applies and no answer has been recorded.
+ *   'declined'  the offer applies and the owner said no. Do not ask again;
+ *               leave a way back.
+ *
+ * ⚠ This deliberately does NOT look at whether the folder is unlocked. That
+ * is the caller's business, and it matters: the offer may only be shown
+ * after an unlock actually succeeded, because accepting needs the password
+ * and because asking someone who cannot open the folder to give away a key
+ * to it is asking the wrong person.
+ */
+export declare type EscrowOfferState = 'n/a' | 'offer' | 'declined';
+
+export declare function escrowOfferState(m: E2eMarker | null, installationKid: string | null | undefined): EscrowOfferState;
+
 export declare interface ExplorerConfig {
     /**
      * Modern shorthand: URL prefix for the standard /api/files/* layout.
@@ -707,6 +1033,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). */
@@ -800,6 +1130,22 @@ export declare interface ExplorerConfig {
      *                          navigation panel starts expanded, the tab strip
      *                          and split pane are off, the gallery view mode and
      *                          the host's "How to connect" surface are hidden.
+     *   'drive'              — everything `simple` does, plus the shell an end
+     *                          user already knows: one primary "New" menu, one
+     *                          search field in the header (with its ⌘K/Ctrl+K
+     *                          escalation into the command palette), a filter row
+     *                          under the breadcrumb, Folders and Files as
+     *                          labelled sections in grid view, the details panel
+     *                          split into Details / Activity, and a storage line
+     *                          under the navigation.
+     *
+     * ⚠ `drive` is a SUPERSET of `simple`, not a sibling: everything `simple`
+     * turns off stays off, and the code asks `simpleUi` for those questions so a
+     * later change to `simple` cannot silently miss `drive`. It is a third value
+     * rather than a second boolean because "which chrome" is ONE question with
+     * three answers — a `driveShell: true` next to `uiProfile: 'standard'` would
+     * be a combination nobody can describe, and keeping that question single is
+     * why `uiProfile` was a preset to begin with.
      *
      * Why it exists (GitHub #14): the reporter's users are not in IT and read
      * split panes, tabs and mount instructions as a file manager they would have
@@ -811,7 +1157,7 @@ export declare interface ExplorerConfig {
      * rest of the chrome differ. A viewer's own collapse choice, once made,
      * outranks the profile — it is a per-viewer preference, not a policy.
      */
-    uiProfile?: 'standard' | 'simple';
+    uiProfile?: 'standard' | 'simple' | 'drive';
     /**
      * Render the navigation panel (Upload · Recent / Starred / Shared with me /
      * Trash · the storage list). Collapsible to an icon rail by the viewer, whose
@@ -848,11 +1194,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. */
@@ -1110,6 +1482,8 @@ inspectorOpen?: boolean;
 navOpen?: boolean;
 navEnabled?: boolean;
 viewModes?: ViewMode[];
+shell?: "classic" | "drive";
+scopeLabel?: string;
 }> & Readonly<{
 onAction?: ((key: string) => any) | undefined;
 onUpload?: (() => any) | undefined;
@@ -1124,6 +1498,7 @@ onRefresh?: (() => any) | undefined;
 "onToggle-nav"?: (() => any) | undefined;
 "onOpen-theme"?: (() => any) | undefined;
 "onOpen-shortcut-settings"?: (() => any) | undefined;
+"onOpen-palette"?: ((query: string) => any) | undefined;
 }>, {
 focusSearch: () => Promise<void>;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
@@ -1140,6 +1515,7 @@ refresh: () => any;
 "toggle-nav": () => any;
 "open-theme": () => any;
 "open-shortcut-settings": () => any;
+"open-palette": (query: string) => any;
 }, PublicProps, {}, false, {}, {}, GlobalComponents, GlobalDirectives, string, {
 primaryEl: HTMLDivElement;
 wideMoreBtnEl: HTMLButtonElement;
@@ -1249,6 +1625,8 @@ inspectorOpen?: boolean;
 navOpen?: boolean;
 navEnabled?: boolean;
 viewModes?: ViewMode[];
+shell?: "classic" | "drive";
+scopeLabel?: string;
 }> & Readonly<{
 onAction?: ((key: string) => any) | undefined;
 onUpload?: (() => any) | undefined;
@@ -1263,6 +1641,7 @@ onRefresh?: (() => any) | undefined;
 "onToggle-nav"?: (() => any) | undefined;
 "onOpen-theme"?: (() => any) | undefined;
 "onOpen-shortcut-settings"?: (() => any) | undefined;
+"onOpen-palette"?: ((query: string) => any) | undefined;
 }>, {
 focusSearch: () => Promise<void>;
 }, {}, {}, {}, {}> | null;
@@ -1282,6 +1661,7 @@ viewMode?: ViewMode;
 thumbSrc?: (n: FileNode) => string | null;
 keepBadgeFor?: (n: FileNode) => "kept" | "syncing" | "cloud" | "partial" | null;
 trashVisible?: boolean;
+navOffersTrash?: boolean;
 }> & Readonly<{
 onTransfer?: ((p: {
 sources: string[];
@@ -1336,6 +1716,7 @@ viewMode?: ViewMode;
 thumbSrc?: (n: FileNode) => string | null;
 keepBadgeFor?: (n: FileNode) => "kept" | "syncing" | "cloud" | "partial" | null;
 trashVisible?: boolean;
+navOffersTrash?: boolean;
 }> & Readonly<{
 onTransfer?: ((p: {
 sources: string[];
@@ -1454,6 +1835,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 +1857,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 +2017,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 +2081,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 +2139,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 +2147,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 +2267,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';
@@ -1971,6 +2380,14 @@ onNav?: ((delta: number) => any) | undefined;
 "onOpen-full"?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
+/** surucu:d1 — `GET /api/files/quota/me` (quota.Snapshot). */
+declare interface QuotaSnapshot {
+    used_bytes: number;
+    quota_bytes: number;
+    percent_used: number;
+    unlimited: boolean;
+}
+
 export declare const RecentlyOpened: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 error: (message: string) => any;
 open: (node: RecentNode) => any;
@@ -1988,6 +2405,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 +2519,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 +2643,7 @@ export declare interface ShortcutHandlers {
     onShowHelp?: () => void;
     onToggleInspector?: () => void;
     onToggleHidden?: () => void;
+    onStar?: () => void;
     onQuickLook?: () => void;
     onTabNew?: () => void;
     onTabClose?: () => void;
@@ -2286,7 +2710,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 +2719,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 +2815,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 +2974,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 +3024,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;
@@ -2721,6 +3183,7 @@ export declare function useFileApi(config: ExplorerConfig): {
         limit?: number;
         scope?: GlobalSearchScope;
     }) => Promise<GlobalSearchHit[]>;
+    quotaMe: () => Promise<QuotaSnapshot | null>;
     subfolders: (path: string) => Promise<{
         folders: FileNode[];
     }>;
@@ -2751,7 +3214,9 @@ export declare function useFileApi(config: ExplorerConfig): {
     uploadMultipart: (path: string, files: File[], onProgress?: (p: number) => void) => Promise<ManagerResponse>;
     downloadUrl: (path: string) => string;
     previewUrl: (path: string) => string;
-    fetchBlob: (path: string) => Promise<{
+    fetchBlob: (path: string, opts?: {
+        fresh?: boolean;
+    }) => Promise<{
         url: string;
         blob: Blob;
         mime: string;
@@ -2759,6 +3224,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 +3749,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>;