@brftech/filex-core 0.31.0 → 0.33.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 = {
@@ -85,9 +92,15 @@ declare type __VLS_Props_14 = {
     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. */
+    /**
+     * 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. */
@@ -287,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`).
  *
@@ -589,6 +636,19 @@ export declare function createMarker(password: string, iterations?: number): Pro
     kek: CryptoKey;
 }>;
 
+/**
+ * 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
@@ -612,6 +672,15 @@ declare type Density = 'comfortable' | 'compact';
  */
 export declare function deriveKek(password: string, salt: Uint8Array, iterations: number): Promise<CryptoKey>;
 
+/**
+ * The browser's preference, or `en`.
+ *
+ * ⚠ Guarded for a non-browser runtime: this package is imported by SSR and by
+ * unit tests under Node, where `navigator` is absent — and an exception here
+ * would take down the whole explorer over a language choice.
+ */
+export declare function detectLocale(): LocaleCode;
+
 export declare const E2E_DEFAULT_ITERATIONS = 600000;
 
 /** The only escrow algorithm this version understands. */
@@ -661,10 +730,19 @@ export declare const E2E_MAGIC = "filexe2e";
  *   - 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.
+ *     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. That is arithmetic, not policy.
+ *     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"
@@ -722,6 +800,23 @@ export declare interface E2eMarker {
     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. */
@@ -823,6 +918,41 @@ 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
@@ -830,6 +960,27 @@ export declare function ensureMonaco(): Promise<unknown | null>;
  */
 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.
@@ -872,7 +1023,7 @@ export declare interface ExplorerConfig {
      */
     onlyOfficeConfig?: string;
     /**
-     * Standalone editor page base — when set, "Aç" on an office file
+     * Standalone editor page base — when set, "Open" on an office file
      * opens `${openPageBase}?path=...&mode=edit` in a new tab instead
      * of the modal preview.
      */
@@ -988,6 +1139,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
@@ -999,7 +1166,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
@@ -1324,6 +1491,8 @@ inspectorOpen?: boolean;
 navOpen?: boolean;
 navEnabled?: boolean;
 viewModes?: ViewMode[];
+shell?: "classic" | "drive";
+scopeLabel?: string;
 }> & Readonly<{
 onAction?: ((key: string) => any) | undefined;
 onUpload?: (() => any) | undefined;
@@ -1338,6 +1507,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, {} & {
@@ -1354,6 +1524,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;
@@ -1463,6 +1634,8 @@ inspectorOpen?: boolean;
 navOpen?: boolean;
 navEnabled?: boolean;
 viewModes?: ViewMode[];
+shell?: "classic" | "drive";
+scopeLabel?: string;
 }> & Readonly<{
 onAction?: ((key: string) => any) | undefined;
 onUpload?: (() => any) | undefined;
@@ -1477,6 +1650,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;
@@ -1496,6 +1670,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[];
@@ -1550,6 +1725,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[];
@@ -2054,7 +2230,7 @@ export declare interface OperationInput {
     percent: number | null;
     status: OperationStatus;
     error?: string | null;
-    /** Queue op accepted but not started yet ("Sırada"). */
+    /** Queue op accepted but not started yet ("Queued"). */
     queued?: boolean;
     /** Progress counters for queue ops (3/5 items). */
     doneCount?: number;
@@ -2082,9 +2258,9 @@ export declare interface OperationInput {
  * are registered per row so the panel can route user intent back to the
  * owning surface without the store knowing any transport details.
  *
- * Lifecycle rules (per the İşlem Merkezi contract):
+ * Lifecycle rules (per the Operations Center contract):
  *   - running rows live in `active`;
- *   - done/aborted rows linger in `active` for DONE_LINGER_MS ("bitti"
+ *   - done/aborted rows linger in `active` for DONE_LINGER_MS ("done"
  *     flash) then move to `history` (session-only, capped);
  *   - error rows are STICKY: they stay in `active` until the user
  *     dismisses or retries them — even after the source list swept them
@@ -2213,6 +2389,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;
@@ -2260,6 +2444,31 @@ declare interface ResolveEmailResponse {
  */
 export declare function resolveEndpoints(config: ExplorerConfig): EndpointMap;
 
+/**
+ * Resolve the locale to render in.
+ *
+ * Order, and the reasoning for it:
+ *
+ *   1. **What the host asked for.** An explicit `locale` always wins. A host
+ *      that names a language has made a decision, and guessing over it would
+ *      make the prop advisory.
+ *   2. **What the browser asks for**, via `navigator.languages` /
+ *      `navigator.language` — the same signal `Accept-Language` carries, and
+ *      the reason a Turkish reader gets Turkish without the embedder doing
+ *      anything.
+ *   3. **`en`.**
+ *
+ * ⚠ Step 2 makes the same embed render differently for two people. That is
+ * deliberate — it is what "follow the browser" means — but it also means a
+ * screenshot, a test or a bug report about this component must state its
+ * locale, because the component alone no longer determines it. Pass an
+ * explicit `locale` anywhere the answer has to be stable.
+ *
+ * Matching is on the primary subtag, so `tr-TR` and `en-GB` resolve; anything
+ * with no catalogue falls through rather than half-rendering.
+ */
+export declare function resolveLocale(explicit?: LocaleCode | '' | null): LocaleCode;
+
 /** 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
@@ -2945,10 +3154,17 @@ export declare interface UploadOptions {
     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.
+     * Wait for the backend transfer before resolving. Defaults to TRUE, because
+     * "the server has the bytes" and "the storage has the bytes" are different
+     * claims and only the second one is an upload.
+     *
+     * ⚠ It used to default to false and no caller ever set it, so the job went
+     * straight to `done` on the 202 — a transfer that failed afterwards in the
+     * ops worker left the user looking at a finished upload for a file that was
+     * never stored (issue #16: every file over the chunk threshold, on every S3
+     * backend). The `transferring` phase is short for a healthy storage and is
+     * the only place a failure can still be shown, so it is the default; pass
+     * false to opt out where the wait is genuinely unwanted.
      */
     waitForTransfer?: boolean;
 }
@@ -3008,6 +3224,7 @@ export declare function useFileApi(config: ExplorerConfig): {
         limit?: number;
         scope?: GlobalSearchScope;
     }) => Promise<GlobalSearchHit[]>;
+    quotaMe: () => Promise<QuotaSnapshot | null>;
     subfolders: (path: string) => Promise<{
         folders: FileNode[];
     }>;
@@ -3038,7 +3255,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;