@brftech/filex-core 0.5.0 → 0.7.0

package/src/composables/useFileApi.ts

@@ -55,6 +55,13 @@ export interface ManagerResponse {
   /** RBAC effective level for the current user on this directory ('' when ACL
    *  is not enforced on the storage). Gates the folder-level write actions. */
   perm?: 'none' | 'viewer' | 'editor' | 'owner';
+  /* wiring:e2 — E2E-encrypted folder awareness: `e2e` is true when the listed
+   * dir IS an encrypted root; `e2e_root` is the adapter-qualified path of the
+   * nearest encrypted root covering this dir (set for the root itself AND for
+   * every subfolder inside the subtree). Absent on plain folders / old
+   * backends — consumers must stay undefined-safe. */
+  e2e?: boolean;
+  e2e_root?: string;
   files: FileNode[];
 }
 
@@ -106,6 +113,23 @@ export interface UserSearchResponse {
   users: UserSuggestion[];
 }
 
+/* === calisma:d3 — node comments (inspector panel) === */
+
+/** Mirrors backend `model.NodeComment` (GET /api/files/comments?node_id=…). */
+export interface NodeComment {
+  id: number;
+  node_id: number;
+  user_id: number;
+  body: string;
+  created_at: string;
+  updated_at?: string;
+  /** Joined author display name (email fallback), filled by the backend. */
+  author_name?: string;
+  /** Whether the CURRENT caller may delete this row (author or admin). */
+  can_delete?: boolean;
+}
+/* === /calisma:d3 === */
+
 export interface InviteResponse {
   mode: 'granted' | 'user_created' | 'shared';
   user_id?: number;
@@ -741,6 +765,38 @@ export function useFileApi(config: ExplorerConfig) {
   }
   /* === /koru:k1 === */
 
+  /* === calisma:d3 — node comments (inspector panel) ===
+   * Same manager-URL derivation trick as versions/permissions so embedded
+   * proxies forwarding the whole /api/files/* subtree keep working.
+   *   GET    /api/files/comments?node_id=N → {comments, node_id}
+   *   POST   /api/files/comments           → {node_id, body}
+   *   DELETE /api/files/comments/{id}      → {ok}
+   */
+  function commentsUrl(sub = ''): string {
+    const base = endpoints.manager.replace(/\/manager(\?.*)?$/, '/comments');
+    return base + sub;
+  }
+  async function listComments(nodeId: number): Promise<NodeComment[]> {
+    const data = await jsonFetch<{ comments?: NodeComment[] | null }>(
+      commentsUrl() + '?node_id=' + encodeURIComponent(String(nodeId)),
+    );
+    return Array.isArray(data?.comments) ? data.comments : [];
+  }
+  async function addComment(nodeId: number, body: string): Promise<NodeComment> {
+    const data = await jsonFetch<{ comment: NodeComment }>(commentsUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ node_id: nodeId, body }),
+    });
+    return data.comment;
+  }
+  async function deleteComment(id: number): Promise<void> {
+    await jsonFetch(commentsUrl('/' + encodeURIComponent(String(id))), {
+      method: 'DELETE',
+    });
+  }
+  /* === /calisma:d3 === */
+
   // Mint a short-lived WebSocket auth ticket for the realtime layer. Derived
   // from the manager URL (so it flows through the same host proxy) and uses the
   // same auth/creds as every other call. Returns null on any failure (a backend
@@ -790,6 +846,10 @@ export function useFileApi(config: ExplorerConfig) {
     listVersions,
     restoreVersion,
     snapshotVersion,
+    // Node comments (calisma:d3 inspector)
+    listComments,
+    addComment,
+    deleteComment,
     // Permissions (RBAC panel)
     listPermissions,
     resolveEmail,

package/src/composables/useKeyboardShortcuts.ts

@@ -38,6 +38,12 @@ export interface ShortcutHandlers {
   onShowHelp?: () => void; // ? (Shift+/ on most layouts)
   onToggleInspector?: () => void; // i (koru:k1 details panel)
   onQuickLook?: () => void; // Space (wiring:c2 quick-look overlay)
+  /* wiring:d1 — tab strip actions */
+  onTabNew?: () => void; // Ctrl+T
+  onTabClose?: () => void; // Ctrl+W
+  onTabNext?: () => void; // Ctrl+Tab
+  onTabPrev?: () => void; // Ctrl+Shift+Tab
+  /* /wiring:d1 */
   hasSelection?: () => boolean; // disambiguates Backspace
 }
 
@@ -87,6 +93,14 @@ export const SHORTCUT_ACTIONS: ShortcutActionDef[] = [
   { id: 'cut', defaultCombo: 'Ctrl+X', labelKey: 'shortcuts.cut', groupKey: 'shortcuts.group.file' },
   { id: 'copy', defaultCombo: 'Ctrl+C', labelKey: 'shortcuts.copy', groupKey: 'shortcuts.group.file' },
   { id: 'paste', defaultCombo: 'Ctrl+V', labelKey: 'shortcuts.paste', groupKey: 'shortcuts.group.file' },
+  /* wiring:d1 — tabs. Note: browsers reserve Ctrl+T/W/Tab in normal pages
+   * (preventDefault can't stop them there); they work in webcomponent/PWA/
+   * kiosk contexts and stay remappable through the settings modal. */
+  { id: 'tab-new', defaultCombo: 'Ctrl+T', labelKey: 'shortcuts.tab_new', groupKey: 'shortcuts.group.tabs' },
+  { id: 'tab-close', defaultCombo: 'Ctrl+W', labelKey: 'shortcuts.tab_close', groupKey: 'shortcuts.group.tabs' },
+  { id: 'tab-next', defaultCombo: 'Ctrl+Tab', labelKey: 'shortcuts.tab_next', groupKey: 'shortcuts.group.tabs' },
+  { id: 'tab-prev', defaultCombo: 'Ctrl+Shift+Tab', labelKey: 'shortcuts.tab_prev', groupKey: 'shortcuts.group.tabs' },
+  /* /wiring:d1 */
 ];
 
 /** action id → ShortcutHandlers callback name. */
@@ -105,6 +119,11 @@ const HANDLER_KEY: Record<string, keyof ShortcutHandlers> = {
   cut: 'onCut',
   copy: 'onCopy',
   paste: 'onPaste',
+  /* wiring:d1 */
+  'tab-new': 'onTabNew',
+  'tab-close': 'onTabClose',
+  'tab-next': 'onTabNext',
+  'tab-prev': 'onTabPrev',
 };
 
 // --------------------------------------------------------------------

package/src/composables/useTabs.ts

@@ -0,0 +1,222 @@
+/**
+ * useTabs — wiring:d1 sekmeler (çalışma alanı tab şeridi).
+ *
+ * A LAYER ABOVE FileExplorer's location state, never a replacement for
+ * it: each tab is a location snapshot `{ id, path, viewMode, split }`.
+ * The composable performs no fetching and owns no navigation — the host
+ * activates a tab by running its EXISTING `load(path)` pipeline and
+ * reports navigations back through `syncActive()`, which keeps the
+ * active snapshot glued to wherever the user actually is.
+ *
+ * `path` is stored in the SAME form as FileExplorer's `currentPath`
+ * (virtual `<storage>/<rel>` in multi-storage mode, bare relative path
+ * in single-storage mode) — i.e. the exact string `load(path)` accepts.
+ * Storing the wire form (`adapter://rel`) instead would break the
+ * rootPath-floor clamp inside load() (the floor is compared in user-path
+ * form), so the user-path form is deliberate.
+ *
+ * Persistence: localStorage under a host-supplied key (the host derives
+ * it from the pathPersist scope: disabled when `pathPersist: 'none'`,
+ * suffixed with the rootPath confine so embedded instances with
+ * different confines never clobber each other). Schema:
+ *
+ *   { "v": 1, "active": "<id>",
+ *     "tabs": [ { "id", "path", "viewMode", "split": {"path"}|null } ] }
+ */
+
+import { computed, ref, watch, type Ref } from 'vue';
+import type { ViewMode } from '../types/FileNode';
+
+/** Per-tab split state — the secondary pane's own location. */
+export interface TabSplit {
+  path: string;
+}
+
+export interface TabState {
+  id: string;
+  /** Location snapshot in `currentPath` form (see module docs). */
+  path: string;
+  viewMode: ViewMode;
+  split: TabSplit | null;
+}
+
+export interface UseTabsOptions {
+  /** localStorage key; null disables persistence entirely. */
+  storageKey: string | null;
+}
+
+function makeId(): string {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `t${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+}
+
+export function useTabs(opts: UseTabsOptions) {
+  const tabs: Ref<TabState[]> = ref([]);
+  const activeId = ref<string>('');
+
+  const activeTab = computed<TabState | null>(
+    () => tabs.value.find((t) => t.id === activeId.value) ?? null,
+  );
+  const activeIndex = computed(() => tabs.value.findIndex((t) => t.id === activeId.value));
+  const hasMultiple = computed(() => tabs.value.length > 1);
+
+  // ------------------------------------------------------------------
+  // Persistence
+  // ------------------------------------------------------------------
+
+  /** Restore from storage. Returns true when at least one tab loaded. */
+  function restore(): boolean {
+    if (!opts.storageKey) return false;
+    try {
+      const raw = localStorage.getItem(opts.storageKey);
+      if (!raw) return false;
+      const parsed = JSON.parse(raw) as { v?: unknown; active?: unknown; tabs?: unknown };
+      if (!parsed || !Array.isArray(parsed.tabs) || parsed.tabs.length === 0) return false;
+      const clean: TabState[] = [];
+      for (const t of parsed.tabs as Array<Record<string, unknown>>) {
+        if (!t || typeof t.path !== 'string') continue;
+        // ViewMode is validated loosely on purpose: future modes (e.g. the
+        // gallery wave) must survive a round-trip through an older schema.
+        const vm =
+          typeof t.viewMode === 'string' && t.viewMode ? (t.viewMode as ViewMode) : 'list';
+        const rawSplit = t.split as { path?: unknown } | null | undefined;
+        const split =
+          rawSplit && typeof rawSplit === 'object' && typeof rawSplit.path === 'string'
+            ? { path: rawSplit.path }
+            : null;
+        clean.push({
+          id: typeof t.id === 'string' && t.id ? t.id : makeId(),
+          path: t.path,
+          viewMode: vm,
+          split,
+        });
+      }
+      if (clean.length === 0) return false;
+      tabs.value = clean;
+      activeId.value = clean.some((t) => t.id === parsed.active)
+        ? String(parsed.active)
+        : clean[0].id;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function persist(): void {
+    if (!opts.storageKey) return;
+    try {
+      localStorage.setItem(
+        opts.storageKey,
+        JSON.stringify({ v: 1, active: activeId.value, tabs: tabs.value }),
+      );
+    } catch {
+      /* private mode / quota */
+    }
+  }
+
+  watch([tabs, activeId], persist, { deep: true });
+
+  // ------------------------------------------------------------------
+  // Mutations
+  // ------------------------------------------------------------------
+
+  /** Create the first tab (no-op once any tab exists). */
+  function seed(path: string, viewMode: ViewMode): void {
+    if (tabs.value.length > 0) return;
+    const t: TabState = { id: makeId(), path, viewMode, split: null };
+    tabs.value = [t];
+    activeId.value = t.id;
+  }
+
+  /** Update the ACTIVE tab's snapshot (navigation / view-mode change). */
+  function syncActive(patch: Partial<Pick<TabState, 'path' | 'viewMode'>>): void {
+    const t = activeTab.value;
+    if (!t) return;
+    if (patch.path !== undefined) t.path = patch.path;
+    if (patch.viewMode !== undefined) t.viewMode = patch.viewMode;
+  }
+
+  /** Open a new tab right after the active one (browser convention). */
+  function openTab(
+    path: string,
+    o: { viewMode: ViewMode; background?: boolean; split?: TabSplit | null },
+  ): TabState {
+    const t: TabState = { id: makeId(), path, viewMode: o.viewMode, split: o.split ?? null };
+    const idx = activeIndex.value;
+    tabs.value.splice(idx === -1 ? tabs.value.length : idx + 1, 0, t);
+    if (!o.background) activeId.value = t.id;
+    return t;
+  }
+
+  /**
+   * Close a tab. The last remaining tab never closes. Returns the tab
+   * the host must ACTIVATE (right neighbour, else left) when the active
+   * one was closed; null when the visible location is unchanged.
+   */
+  function closeTab(id: string): TabState | null {
+    if (tabs.value.length <= 1) return null;
+    const idx = tabs.value.findIndex((t) => t.id === id);
+    if (idx === -1) return null;
+    const wasActive = tabs.value[idx].id === activeId.value;
+    tabs.value.splice(idx, 1);
+    if (!wasActive) return null;
+    const next = tabs.value[Math.min(idx, tabs.value.length - 1)];
+    activeId.value = next.id;
+    return next;
+  }
+
+  /** Make a tab active. Returns it when the active tab actually changed. */
+  function activate(id: string): TabState | null {
+    const t = tabs.value.find((x) => x.id === id);
+    if (!t || t.id === activeId.value) return null;
+    activeId.value = t.id;
+    return t;
+  }
+
+  /** Cycle: +1 = next, -1 = previous (wraps). */
+  function step(delta: number): TabState | null {
+    if (tabs.value.length < 2) return null;
+    const idx = activeIndex.value === -1 ? 0 : activeIndex.value;
+    const next = tabs.value[(idx + delta + tabs.value.length) % tabs.value.length];
+    return activate(next.id);
+  }
+
+  /** Drag-sort support: move the tab at `from` to position `to`. */
+  function move(from: number, to: number): void {
+    if (from === to) return;
+    if (from < 0 || to < 0 || from >= tabs.value.length || to >= tabs.value.length) return;
+    const list = [...tabs.value];
+    const [t] = list.splice(from, 1);
+    list.splice(to, 0, t);
+    tabs.value = list;
+  }
+
+  /** Set (or clear with null) the ACTIVE tab's split state. */
+  function setSplit(split: TabSplit | null): void {
+    const t = activeTab.value;
+    if (!t) return;
+    t.split = split;
+  }
+
+  return {
+    tabs,
+    activeId,
+    activeTab,
+    activeIndex,
+    hasMultiple,
+    restore,
+    seed,
+    syncActive,
+    openTab,
+    closeTab,
+    activate,
+    step,
+    move,
+    setSplit,
+  };
+}
+
+export type TabsApi = ReturnType<typeof useTabs>;

package/src/index.ts

@@ -127,3 +127,30 @@ export type {
   OperationsStore,
 } from './composables/useOperations';
 export { default as OperationsCenter } from './components/OperationsCenter.vue';
+/* wiring:d1 — sekmeler + split panel */
+export { useTabs } from './composables/useTabs';
+export type { TabState, TabSplit, TabsApi } from './composables/useTabs';
+export { default as TabBar } from './components/TabBar.vue';
+export { default as SecondaryPane } from './components/SecondaryPane.vue';
+/* /wiring:d1 */
+/* wiring:e2 — uçtan uca şifreli klasörler (WebCrypto; docs/E2E-ENCRYPTION.md) */
+export {
+  E2E_MARKER_NAME,
+  E2E_MAGIC,
+  E2E_VERSION,
+  E2E_DEFAULT_ITERATIONS,
+  E2E_MAX_FILE_BYTES,
+  E2E_MIN_PASSWORD_LEN,
+  E2eDecryptError,
+  deriveKek,
+  createMarker,
+  parseMarker,
+  verifyPassword,
+  hasMagic,
+  encryptFile,
+  decryptFile,
+  createKeyRing,
+} from './lib/e2ecrypto';
+export type { E2eMarker, E2eKeyRing } from './lib/e2ecrypto';
+export { default as EncryptedFolderModal } from './components/EncryptedFolderModal.vue';
+/* /wiring:e2 */

package/src/lib/e2ecrypto.ts

@@ -0,0 +1,299 @@
+/**
+ * e2ecrypto — client-side crypto for E2E-encrypted folders (wiring:e2).
+ *
+ * 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.
+ *
+ * File layout ('filexe2e' magic, fixed 97-byte header):
+ *   [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)
+ *   [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 const E2E_MARKER_NAME = '.filex-e2e.json';
+export const E2E_MAGIC = 'filexe2e';
+export const E2E_VERSION = 1;
+export const E2E_DEFAULT_ITERATIONS = 600_000;
+export const E2E_MIN_ITERATIONS = 600_000;
+/** MVP single-shot in-memory ceiling — larger uploads are refused with a warning. */
+export const E2E_MAX_FILE_BYTES = 200 * 1024 * 1024;
+export const E2E_MIN_PASSWORD_LEN = 8;
+
+const VERIFY_PLAINTEXT = 'filex-e2e-verify-v1';
+const MAGIC_BYTES = new TextEncoder().encode(E2E_MAGIC); // 8 bytes
+const HEADER_LEN = 97;
+const WRAP_IV_OFF = 9;
+const WRAPPED_DEK_OFF = 21;
+const WRAPPED_DEK_LEN = 48;
+const DATA_IV_OFF = 69;
+const IV_LEN = 12;
+
+export interface E2eMarker {
+  v: number;
+  salt: string; // base64
+  iter: number;
+  verify: string; // base64: 12B IV || AES-GCM ciphertext of VERIFY_PLAINTEXT
+}
+
+/** Thrown on wrong password / corrupted ciphertext (GCM tag mismatch). */
+export class E2eDecryptError extends Error {
+  constructor(msg = 'e2e: decrypt failed') {
+    super(msg);
+    this.name = 'E2eDecryptError';
+  }
+}
+
+// ---------------------------------------------------------------------
+// base64 helpers (no deps)
+// ---------------------------------------------------------------------
+
+export function bytesToB64(b: Uint8Array): string {
+  let s = '';
+  for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i]);
+  return btoa(s);
+}
+
+export function b64ToBytes(s: string): Uint8Array {
+  const raw = atob(s);
+  const out = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+  return out;
+}
+
+// ---------------------------------------------------------------------
+// Key derivation
+// ---------------------------------------------------------------------
+
+/**
+ * Derive the folder KEK from a password. Returns a NON-extractable
+ * AES-256-GCM CryptoKey — it can encrypt/decrypt but never be exported,
+ * so even a same-origin script can't read the raw key material back.
+ */
+export async function deriveKek(
+  password: string,
+  salt: Uint8Array,
+  iterations: number,
+): Promise<CryptoKey> {
+  const material = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(password),
+    'PBKDF2',
+    false,
+    ['deriveKey'],
+  );
+  return crypto.subtle.deriveKey(
+    // Copy into a fresh ArrayBuffer-backed view — TS 5.9 BufferSource typing
+    // rejects Uint8Array<ArrayBufferLike> that may wrap a SharedArrayBuffer.
+    { name: 'PBKDF2', salt: new Uint8Array(salt).buffer as ArrayBuffer, iterations, hash: 'SHA-256' },
+    material,
+    { name: 'AES-GCM', length: 256 },
+    false, // non-extractable
+    ['encrypt', 'decrypt'],
+  );
+}
+
+// ---------------------------------------------------------------------
+// Marker create / verify
+// ---------------------------------------------------------------------
+
+/** Create a fresh folder marker for `password` (also returns the derived KEK). */
+export async function createMarker(
+  password: string,
+  iterations: number = E2E_DEFAULT_ITERATIONS,
+): Promise<{ marker: E2eMarker; kek: CryptoKey }> {
+  const iter = Math.max(E2E_MIN_ITERATIONS, iterations);
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const kek = await deriveKek(password, salt, iter);
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const ct = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: iv.buffer as ArrayBuffer },
+      kek,
+      new TextEncoder().encode(VERIFY_PLAINTEXT),
+    ),
+  );
+  const verify = new Uint8Array(IV_LEN + ct.length);
+  verify.set(iv, 0);
+  verify.set(ct, IV_LEN);
+  return {
+    marker: { v: E2E_VERSION, salt: bytesToB64(salt), iter, verify: bytesToB64(verify) },
+    kek,
+  };
+}
+
+/** Parse marker JSON text; returns null when the shape is not a v1 marker. */
+export function parseMarker(text: string): E2eMarker | null {
+  try {
+    const m = JSON.parse(text) as E2eMarker;
+    if (!m || m.v !== E2E_VERSION) return null;
+    if (typeof m.salt !== 'string' || typeof m.verify !== 'string') return null;
+    if (typeof m.iter !== 'number' || m.iter < 1) return null;
+    return m;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+export async function verifyPassword(
+  marker: E2eMarker,
+  password: string,
+): Promise<CryptoKey | null> {
+  const salt = b64ToBytes(marker.salt);
+  const kek = await deriveKek(password, salt, marker.iter);
+  const verify = b64ToBytes(marker.verify);
+  if (verify.length <= IV_LEN) return null;
+  try {
+    const pt = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: verify.slice(0, IV_LEN).buffer as ArrayBuffer },
+      kek,
+      verify.slice(IV_LEN).buffer as ArrayBuffer,
+    );
+    if (new TextDecoder().decode(pt) !== VERIFY_PLAINTEXT) return null;
+    return kek;
+  } catch {
+    return null; // wrong password
+  }
+}
+
+// ---------------------------------------------------------------------
+// Magic sniff
+// ---------------------------------------------------------------------
+
+/** True when the buffer starts with the 'filexe2e' magic. */
+export function hasMagic(buf: ArrayBuffer | Uint8Array): boolean {
+  const b = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  if (b.length < MAGIC_BYTES.length) return false;
+  for (let i = 0; i < MAGIC_BYTES.length; i++) {
+    if (b[i] !== MAGIC_BYTES[i]) return false;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------
+// File encrypt / decrypt (one-shot MVP)
+// ---------------------------------------------------------------------
+
+/**
+ * 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
+ * 'filexe2e' header. Throws when content exceeds E2E_MAX_FILE_BYTES.
+ */
+export async function encryptFile(kek: CryptoKey, content: ArrayBuffer): Promise<ArrayBuffer> {
+  if (content.byteLength > E2E_MAX_FILE_BYTES) {
+    throw new Error('e2e: file exceeds the 200MB single-shot limit');
+  }
+  const rawDek = crypto.getRandomValues(new Uint8Array(32));
+  const dek = await crypto.subtle.importKey('raw', rawDek.buffer as ArrayBuffer, { name: 'AES-GCM' }, false, [
+    'encrypt',
+  ]);
+  const wrapIV = crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const dataIV = crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const wrappedDek = new Uint8Array(
+    await crypto.subtle.encrypt({ name: 'AES-GCM', iv: wrapIV.buffer as ArrayBuffer }, kek, rawDek.buffer as ArrayBuffer),
+  );
+  const ct = new Uint8Array(
+    await crypto.subtle.encrypt({ name: 'AES-GCM', iv: dataIV.buffer as ArrayBuffer }, dek, content),
+  );
+  // Zero the raw DEK copy as a hygiene measure (best-effort — GC may have
+  // other copies, but don't leave the obvious one around).
+  rawDek.fill(0);
+
+  const out = new Uint8Array(HEADER_LEN + ct.length);
+  out.set(MAGIC_BYTES, 0);
+  out[8] = E2E_VERSION;
+  out.set(wrapIV, WRAP_IV_OFF);
+  out.set(wrappedDek, WRAPPED_DEK_OFF); // 48 bytes
+  out.set(dataIV, DATA_IV_OFF);
+  // [81..97) reserved zeros
+  out.set(ct, HEADER_LEN);
+  return out.buffer;
+}
+
+/**
+ * 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.
+ */
+export async function decryptFile(kek: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer> {
+  const b = new Uint8Array(data);
+  if (!hasMagic(b) || b.length < HEADER_LEN) {
+    throw new Error('e2e: not an encrypted file');
+  }
+  if (b[8] !== E2E_VERSION) {
+    throw new Error(`e2e: unsupported version ${b[8]}`);
+  }
+  const wrapIV = b.slice(WRAP_IV_OFF, WRAP_IV_OFF + IV_LEN);
+  const wrappedDek = b.slice(WRAPPED_DEK_OFF, WRAPPED_DEK_OFF + WRAPPED_DEK_LEN);
+  const dataIV = b.slice(DATA_IV_OFF, DATA_IV_OFF + IV_LEN);
+  let rawDek: ArrayBuffer;
+  try {
+    rawDek = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: wrapIV.buffer as ArrayBuffer },
+      kek,
+      wrappedDek.buffer as ArrayBuffer,
+    );
+  } catch {
+    throw new E2eDecryptError('e2e: DEK unwrap failed (wrong password?)');
+  }
+  const dek = await crypto.subtle.importKey('raw', rawDek, { name: 'AES-GCM' }, false, ['decrypt']);
+  try {
+    return await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: dataIV.buffer as ArrayBuffer },
+      dek,
+      b.slice(HEADER_LEN).buffer as ArrayBuffer,
+    );
+  } catch {
+    throw new E2eDecryptError('e2e: content decrypt failed');
+  }
+}
+
+// ---------------------------------------------------------------------
+// In-memory session key ring
+// ---------------------------------------------------------------------
+
+/**
+ * Tiny per-explorer key ring: encrypted-folder root (wire path) → KEK.
+ * Lives ONLY in memory — "Kilitle" drops the entry, a reload drops all.
+ */
+export function createKeyRing() {
+  const keys = new Map<string, CryptoKey>();
+  return {
+    get(root: string): CryptoKey | undefined {
+      return keys.get(root);
+    },
+    set(root: string, kek: CryptoKey): void {
+      keys.set(root, kek);
+    },
+    /** Drop one folder's key ("Kilitle"). */
+    lock(root: string): void {
+      keys.delete(root);
+    },
+    has(root: string): boolean {
+      return keys.has(root);
+    },
+    clear(): void {
+      keys.clear();
+    },
+  };
+}
+
+export type E2eKeyRing = ReturnType<typeof createKeyRing>;