@bobfrankston/mailx-store 0.1.2 → 0.1.5

package/file-store.d.ts

@@ -1,22 +1,36 @@
 /**
  * File-per-message body storage backend.
- * Messages stored as: {basePath}/{accountId}/{folderName}/{uid}.eml
- * Legacy: also checks {basePath}/{accountId}/{folderId}/{uid}.eml
+ *
+ * Disk layout: {basePath}/{accountId}/<xx>/<uuid>.eml
+ * Filename is an opaque UUID. Two-char prefix dir for filesystem fan-out.
+ *
+ * CRITICAL: the on-disk filename carries NO semantic meaning — not folder
+ * id, not UID, not Message-ID. A new UUID is minted on every `putMessage`.
+ * Moves, UID renumbers, UIDVALIDITY bumps cannot shadow a body because no
+ * filename is ever reused. DB's `body_path` column is the sole authority
+ * on where a given message's body lives.
  */
 import type { MessageStore } from "@bobfrankston/mailx-types";
 export declare class FileMessageStore implements MessageStore {
     private basePath;
-    private folderNames;
     constructor(basePath: string);
-    /** Register folder ID → path mapping for human-readable directory names */
-    registerFolder(folderId: number, folderPath: string): void;
-    private folderDir;
-    private messagePath;
-    /** Check legacy path (numeric folder ID) */
-    private legacyPath;
-    putMessage(accountId: string, folderId: number, uid: number, raw: Buffer): Promise<string>;
-    getMessage(accountId: string, folderId: number, uid: number): Promise<Buffer>;
-    deleteMessage(accountId: string, folderId: number, uid: number): Promise<void>;
-    hasMessage(accountId: string, folderId: number, uid: number): Promise<boolean>;
+    /** Fresh opaque path per call. No inputs from the caller affect the name. */
+    private newMessagePath;
+    /** Verify a given path resolves inside this store's basePath — refuses
+     *  any value that doesn't (cheap directory-traversal guard). */
+    private inStore;
+    /** Write a new body. Always a fresh UUID path. Caller MUST persist the
+     *  returned path in the DB (`body_path`) and use it for all reads. The
+     *  (folderId, uid) args are kept for interface compatibility; they do
+     *  NOT affect the filename. */
+    putMessage(accountId: string, _folderId: number, _uid: number, raw: Buffer): Promise<string>;
+    /** Read by absolute path (DB `body_path`). The primary read API. */
+    readByPath(fullPath: string): Promise<Buffer>;
+    hasByPath(fullPath: string): Promise<boolean>;
+    unlinkByPath(fullPath: string): Promise<void>;
+    getMessagePath(_accountId: string, _folderId: number, _uid: number): string;
+    getMessage(_accountId: string, _folderId: number, _uid: number): Promise<Buffer>;
+    hasMessage(_accountId: string, _folderId: number, _uid: number): Promise<boolean>;
+    deleteMessage(_accountId: string, _folderId: number, _uid: number): Promise<void>;
 }
 //# sourceMappingURL=file-store.d.ts.map

package/file-store.js

@@ -1,59 +1,80 @@
 /**
  * File-per-message body storage backend.
- * Messages stored as: {basePath}/{accountId}/{folderName}/{uid}.eml
- * Legacy: also checks {basePath}/{accountId}/{folderId}/{uid}.eml
+ *
+ * Disk layout: {basePath}/{accountId}/<xx>/<uuid>.eml
+ * Filename is an opaque UUID. Two-char prefix dir for filesystem fan-out.
+ *
+ * CRITICAL: the on-disk filename carries NO semantic meaning — not folder
+ * id, not UID, not Message-ID. A new UUID is minted on every `putMessage`.
+ * Moves, UID renumbers, UIDVALIDITY bumps cannot shadow a body because no
+ * filename is ever reused. DB's `body_path` column is the sole authority
+ * on where a given message's body lives.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-/** Sanitize folder path for use as directory name — replace delimiters with _ */
-function sanitizeFolderName(folderPath) {
-    return folderPath.replace(/[\/\\.:]/g, "_");
-}
+import { randomUUID } from "node:crypto";
 export class FileMessageStore {
     basePath;
-    folderNames = new Map();
     constructor(basePath) {
         this.basePath = basePath;
         fs.mkdirSync(basePath, { recursive: true });
     }
-    /** Register folder ID → path mapping for human-readable directory names */
-    registerFolder(folderId, folderPath) {
-        this.folderNames.set(folderId, sanitizeFolderName(folderPath));
-    }
-    folderDir(accountId, folderId) {
-        const name = this.folderNames.get(folderId) || String(folderId);
-        return path.join(this.basePath, accountId, name);
-    }
-    messagePath(accountId, folderId, uid) {
-        return path.join(this.folderDir(accountId, folderId), `${uid}.eml`);
+    /** Fresh opaque path per call. No inputs from the caller affect the name. */
+    newMessagePath(accountId) {
+        const uuid = randomUUID().replace(/-/g, "");
+        const prefix = uuid.slice(0, 2);
+        return path.join(this.basePath, accountId, prefix, `${uuid}.eml`);
     }
-    /** Check legacy path (numeric folder ID) */
-    legacyPath(accountId, folderId, uid) {
-        return path.join(this.basePath, accountId, String(folderId), `${uid}.eml`);
+    /** Verify a given path resolves inside this store's basePath — refuses
+     *  any value that doesn't (cheap directory-traversal guard). */
+    inStore(fullPath) {
+        if (!fullPath)
+            return false;
+        const rel = path.relative(path.resolve(this.basePath), path.resolve(fullPath));
+        return !rel.startsWith("..") && !path.isAbsolute(rel);
     }
-    async putMessage(accountId, folderId, uid, raw) {
-        const filePath = this.messagePath(accountId, folderId, uid);
+    /** Write a new body. Always a fresh UUID path. Caller MUST persist the
+     *  returned path in the DB (`body_path`) and use it for all reads. The
+     *  (folderId, uid) args are kept for interface compatibility; they do
+     *  NOT affect the filename. */
+    async putMessage(accountId, _folderId, _uid, raw) {
+        const filePath = this.newMessagePath(accountId);
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         fs.writeFileSync(filePath, raw);
         return filePath;
     }
-    async getMessage(accountId, folderId, uid) {
-        const filePath = this.messagePath(accountId, folderId, uid);
-        if (fs.existsSync(filePath))
-            return fs.readFileSync(filePath);
-        // Fallback to legacy path
-        const legacy = this.legacyPath(accountId, folderId, uid);
-        return fs.readFileSync(legacy);
-    }
-    async deleteMessage(accountId, folderId, uid) {
-        for (const p of [this.messagePath(accountId, folderId, uid), this.legacyPath(accountId, folderId, uid)]) {
-            if (fs.existsSync(p))
-                fs.unlinkSync(p);
-        }
-    }
-    async hasMessage(accountId, folderId, uid) {
-        return fs.existsSync(this.messagePath(accountId, folderId, uid)) ||
-            fs.existsSync(this.legacyPath(accountId, folderId, uid));
+    /** Read by absolute path (DB `body_path`). The primary read API. */
+    async readByPath(fullPath) {
+        if (!this.inStore(fullPath))
+            throw new Error(`refusing to read outside store: ${fullPath}`);
+        return fs.readFileSync(fullPath);
+    }
+    async hasByPath(fullPath) {
+        if (!this.inStore(fullPath))
+            return false;
+        return fs.existsSync(fullPath);
+    }
+    async unlinkByPath(fullPath) {
+        if (!this.inStore(fullPath))
+            return;
+        if (fs.existsSync(fullPath))
+            fs.unlinkSync(fullPath);
+    }
+    // MessageStore interface compatibility (unused once all callers migrate to
+    // path-based reads). These used to compose {folderId}/{uid}.eml and they
+    // would resurrect the comingling bug if restored. Kept as throwing stubs
+    // so any accidental caller surfaces loudly rather than silently misbehave.
+    getMessagePath(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.getMessagePath is retired — read body_path from DB");
+    }
+    async getMessage(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.getMessage(folder,uid) is retired — use readByPath(body_path)");
+    }
+    async hasMessage(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.hasMessage(folder,uid) is retired — use hasByPath(body_path)");
+    }
+    async deleteMessage(_accountId, _folderId, _uid) {
+        throw new Error("FileMessageStore.deleteMessage(folder,uid) is retired — use unlinkByPath(body_path)");
     }
 }
 //# sourceMappingURL=file-store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,12 +9,8 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/mailx-types": "^0.1.3",
-    "@bobfrankston/mailx-settings": "^0.1.2",
-    "better-sqlite3": "^11.7.0"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.12"
+    "@bobfrankston/mailx-types": "^0.1.5",
+    "@bobfrankston/mailx-settings": "^0.1.6"
   },
   "repository": {
     "type": "git",
@@ -22,7 +18,12 @@
   },
   ".dependencies": {
     "@bobfrankston/mailx-types": "file:../mailx-types",
-    "@bobfrankston/mailx-settings": "file:../mailx-settings",
-    "better-sqlite3": "^11.7.0"
+    "@bobfrankston/mailx-settings": "file:../mailx-settings"
+  },
+  ".transformedSnapshot": {
+    "dependencies": {
+      "@bobfrankston/mailx-types": "^0.1.5",
+      "@bobfrankston/mailx-settings": "^0.1.6"
+    }
   }
 }