@bobfrankston/mailx-store 0.1.3 → 0.1.7

package/file-store.d.ts

@@ -1,22 +1,54 @@
 /**
  * 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, returned RELATIVE to `basePath`. The DB
+     *  stores this relative form so the body store can be relocated (or
+     *  the user folder renamed — e.g. `.mailx → .rmfmail`) without the
+     *  body_path entries breaking. */
+    private newRelativePath;
+    /** Resolve a stored path. Accepts either a relative path (post-2026-05
+     *  format) or an absolute path (legacy entries until next-launch
+     *  migration rewrites them). Either way, refuse anything outside the
+     *  store as a directory-traversal guard. */
+    private resolveStored;
+    /** Write a new body. Returns a path RELATIVE to basePath; caller stores
+     *  it in `body_path`. 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 stored path (relative or absolute). */
+    readByPath(stored: string): Promise<Buffer>;
+    hasByPath(stored: string): Promise<boolean>;
+    unlinkByPath(stored: string): Promise<void>;
+    /** One-shot migration: rewrite absolute body_path values that point at
+     *  this store's basePath into relative form. Called once from db.ts on
+     *  startup (gated by a kv flag); silently skipped after first run.
+     *  Returns the count of rewritten paths.
+     *
+     *  Bodies whose absolute path is OUTSIDE basePath (the legacy
+     *  `~/.mailx/mailxstore/...` entries on a machine where basePath is
+     *  now `~/.rmfmail/mailxstore`) are left alone — the migration in
+     *  mailx-settings already moves the files; this rewrite is purely
+     *  about getting body_path to a relative shape. */
+    rewriteAbsoluteToRelative(rows: Array<{
+        id: number;
+        body_path: string;
+    }>, update: (id: number, newPath: string) => void): number;
+    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,124 @@
 /**
  * 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`);
-    }
-    /** Check legacy path (numeric folder ID) */
-    legacyPath(accountId, folderId, uid) {
-        return path.join(this.basePath, accountId, String(folderId), `${uid}.eml`);
-    }
-    async putMessage(accountId, folderId, uid, raw) {
-        const filePath = this.messagePath(accountId, folderId, uid);
-        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);
+    /** Fresh opaque path per call, returned RELATIVE to `basePath`. The DB
+     *  stores this relative form so the body store can be relocated (or
+     *  the user folder renamed — e.g. `.mailx → .rmfmail`) without the
+     *  body_path entries breaking. */
+    newRelativePath(accountId) {
+        const uuid = randomUUID().replace(/-/g, "");
+        const prefix = uuid.slice(0, 2);
+        return path.join(accountId, prefix, `${uuid}.eml`);
+    }
+    /** Resolve a stored path. Accepts either a relative path (post-2026-05
+     *  format) or an absolute path (legacy entries until next-launch
+     *  migration rewrites them). Either way, refuse anything outside the
+     *  store as a directory-traversal guard. */
+    resolveStored(p) {
+        if (!p)
+            return "";
+        const abs = path.isAbsolute(p) ? p : path.resolve(this.basePath, p);
+        const rel = path.relative(path.resolve(this.basePath), abs);
+        if (rel.startsWith("..") || path.isAbsolute(rel))
+            return "";
+        return abs;
+    }
+    /** Write a new body. Returns a path RELATIVE to basePath; caller stores
+     *  it in `body_path`. The (folderId, uid) args are kept for interface
+     *  compatibility; they do NOT affect the filename. */
+    async putMessage(accountId, _folderId, _uid, raw) {
+        const rel = this.newRelativePath(accountId);
+        const abs = path.join(this.basePath, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, raw);
+        return rel;
+    }
+    /** Read by stored path (relative or absolute). */
+    async readByPath(stored) {
+        const abs = this.resolveStored(stored);
+        if (!abs)
+            throw new Error(`refusing to read outside store: ${stored}`);
+        return fs.readFileSync(abs);
+    }
+    async hasByPath(stored) {
+        const abs = this.resolveStored(stored);
+        return !!abs && fs.existsSync(abs);
+    }
+    async unlinkByPath(stored) {
+        const abs = this.resolveStored(stored);
+        if (!abs)
+            return;
+        if (fs.existsSync(abs))
+            fs.unlinkSync(abs);
+    }
+    /** One-shot migration: rewrite absolute body_path values that point at
+     *  this store's basePath into relative form. Called once from db.ts on
+     *  startup (gated by a kv flag); silently skipped after first run.
+     *  Returns the count of rewritten paths.
+     *
+     *  Bodies whose absolute path is OUTSIDE basePath (the legacy
+     *  `~/.mailx/mailxstore/...` entries on a machine where basePath is
+     *  now `~/.rmfmail/mailxstore`) are left alone — the migration in
+     *  mailx-settings already moves the files; this rewrite is purely
+     *  about getting body_path to a relative shape. */
+    rewriteAbsoluteToRelative(rows, update) {
+        let n = 0;
+        const baseAbs = path.resolve(this.basePath);
+        for (const r of rows) {
+            if (!r.body_path || !path.isAbsolute(r.body_path))
+                continue;
+            const rel = path.relative(baseAbs, path.resolve(r.body_path));
+            if (rel.startsWith("..") || path.isAbsolute(rel)) {
+                // Outside this store — try mapping `.mailx → .rmfmail` if the
+                // legacy dir was the source. Then re-test.
+                const remapped = r.body_path.replace(/[\\/]\.mailx[\\/]mailxstore[\\/]/i, `${path.sep}.rmfmail${path.sep}mailxstore${path.sep}`);
+                if (remapped !== r.body_path) {
+                    const rel2 = path.relative(baseAbs, path.resolve(remapped));
+                    if (!rel2.startsWith("..") && !path.isAbsolute(rel2)) {
+                        update(r.id, rel2.replace(/\\/g, "/"));
+                        n++;
+                    }
+                }
+                continue;
+            }
+            update(r.id, rel.replace(/\\/g, "/"));
+            n++;
         }
+        return n;
+    }
+    // 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 hasMessage(accountId, folderId, uid) {
-        return fs.existsSync(this.messagePath(accountId, folderId, uid)) ||
-            fs.existsSync(this.legacyPath(accountId, folderId, uid));
+    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.3",
+  "version": "0.1.7",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,20 +9,24 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/mailx-types": "^0.1.3",
-    "@bobfrankston/mailx-settings": "^0.1.4",
-    "better-sqlite3": "^11.7.0"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.12"
+    "@bobfrankston/mailx-types": "^0.1.6",
+    "@bobfrankston/mailx-settings": "^0.1.7"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/BobFrankston/mailx-store.git"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   ".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.6",
+      "@bobfrankston/mailx-settings": "^0.1.7"
+    }
   }
 }