@bobfrankston/mailx-settings 0.1.4 → 0.1.7

package/cloud.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cloud storage for mailx settings — Google Drive API (drive.file scope).
+ *
+ * Uses a single app-owned "mailx" folder on Drive, accessed by folder ID.
+ * The drive.file scope only sees files/folders created by this OAuth client,
+ * which prevents conflicts with existing folders of the same name.
+ * All machines using the same OAuth client ID share the same folder.
+ *
+ * ── Restoring removed providers ──
+ * OneDrive (removed 2026-04-06): Required microsoft-credentials.json in ~/.mailx/,
+ *   MS_SCOPES = "https://graph.microsoft.com/Files.ReadWrite offline_access",
+ *   authenticateOAuth with tokenDir ~/.mailx/tokens/microsoft/.
+ *   Read/write via Graph API: GET/PUT https://graph.microsoft.com/v1.0/me/drive/root:/{path}:/content
+ *   Azure AD app registration needed: https://portal.azure.com → App registrations → Desktop app
+ *
+ * Dropbox (removed 2026-04-06): Never implemented — placeholder only.
+ *   Would need Dropbox OAuth app, token management, and Dropbox API v2 calls.
+ */
+/** Verify a cached folder ID still points to an `.rmfmail`-named folder
+ *  the user owns and isn't trashed. Returns true if the ID is good to use,
+ *  false if mailx should drop it and re-discover via gDriveFindOrCreateFolder.
+ *
+ *  Catches the cross-version-corruption case: 1.0.504 had a buggy folder
+ *  lookup that created an empty `rmfmail` folder at My Drive root and cached
+ *  its ID. Once 1.0.505 fixed the lookup, the cached ID still pointed at the
+ *  buggy folder forever — mailx kept reading the 1-account stub instead of
+ *  the user's real `home/.rmfmail/accounts.jsonc`. This validator forces a
+ *  re-discovery whenever the cached ID is wrong. */
+export declare function gDriveValidateCachedFolder(folderId: string): Promise<boolean>;
+/** Find or create the rmfmail settings folder on Google Drive.
+ *
+ *  Lookup order — match the Android side (`mailx-store-web/android-bootstrap.ts`):
+ *    1. `home/.rmfmail/` — the established convention. Bob's family-of-two
+ *       layout has been here since the rebrand. Path scope (`'root' in
+ *       parents` for `home`, then `<homeId> in parents` for `.rmfmail`) is
+ *       what the Android side does, so desktop matches.
+ *    2. `.rmfmail/` at My Drive root — fallback for users who don't have a
+ *       `home/` folder. Mostly hypothetical; included so a brand-new Drive
+ *       still works.
+ *    3. Create `.rmfmail` at My Drive root if neither exists. Don't auto-
+ *       create `home/` — that's a user-organization choice we shouldn't
+ *       make for them.
+ *
+ *  Previously this looked for a literal `rmfmail` (no dot) at root, which
+ *  on clean install created a NEW empty folder alongside the real data,
+ *  orphaning the user's accounts/contacts/etc. Switched to the dotted name
+ *  matching the actual folder convention. */
+export declare function gDriveFindOrCreateFolder(): Promise<string | null>;
+export type CloudProvider = "gdrive" | "google" | "local";
+export interface CloudFile {
+    /** Read a file. For gdrive, path is just the filename (folder ID is implicit). */
+    read(filePath: string): Promise<string | null>;
+    /** Write a file. For gdrive, path is just the filename. Throws on failure with a descriptive error. */
+    write(filePath: string, content: string): Promise<void>;
+    /** Check if a file exists. */
+    exists(filePath: string): Promise<boolean>;
+}
+/**
+ * Get a cloud file provider. For gdrive, pass the folder ID.
+ * Files are stored flat in the folder (no subdirectory navigation).
+ */
+export declare function getCloudProvider(provider: string, folderId?: string): CloudFile | null;
+/** Fetch the authenticated Google user's profile (name + email) via the People API.
+ *  Caller must supply an OAuth access token whose scopes include `contacts.readonly`
+ *  or `userinfo.profile`. The Drive token (drive.file) does NOT have the right scope
+ *  on its own — use the Gmail/IMAP OAuth token instead (mailx-imap's
+ *  ImapManager.getOAuthToken). Returns null on failure. */
+export declare function getGoogleProfile(token: string): Promise<{
+    name?: string;
+    email?: string;
+} | null>;
+//# sourceMappingURL=cloud.d.ts.map

package/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["cloud.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0JH;;;;;;;;;oDASoD;AACpD,wBAAsB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BnF;AAcD;;;;;;;;;;;;;;;;;6CAiB6C;AAC7C,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwBvE;AA4ED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,SAAS;IACtB,kFAAkF;IAClF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,uGAAuG;IACvG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,8BAA8B;IAC9B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAuBtF;AAED;;;;2DAI2D;AAC3D,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAoBvG"}

package/cloud.js

@@ -0,0 +1,423 @@
+/**
+ * Cloud storage for mailx settings — Google Drive API (drive.file scope).
+ *
+ * Uses a single app-owned "mailx" folder on Drive, accessed by folder ID.
+ * The drive.file scope only sees files/folders created by this OAuth client,
+ * which prevents conflicts with existing folders of the same name.
+ * All machines using the same OAuth client ID share the same folder.
+ *
+ * ── Restoring removed providers ──
+ * OneDrive (removed 2026-04-06): Required microsoft-credentials.json in ~/.mailx/,
+ *   MS_SCOPES = "https://graph.microsoft.com/Files.ReadWrite offline_access",
+ *   authenticateOAuth with tokenDir ~/.mailx/tokens/microsoft/.
+ *   Read/write via Graph API: GET/PUT https://graph.microsoft.com/v1.0/me/drive/root:/{path}:/content
+ *   Azure AD app registration needed: https://portal.azure.com → App registrations → Desktop app
+ *
+ * Dropbox (removed 2026-04-06): Never implemented — placeholder only.
+ *   Would need Dropbox OAuth app, token management, and Dropbox API v2 calls.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { authenticateOAuth } from "@bobfrankston/oauthsupport";
+const SETTINGS_DIR = path.join(process.env.USERPROFILE || process.env.HOME || ".", ".rmfmail");
+// ── Credentials ──
+// Google Drive: reuse iflow's OAuth credentials (same Google Cloud project)
+function findGoogleCredentials() {
+    // Check mailx local dir first, then iflow package
+    const local = path.join(SETTINGS_DIR, "google-credentials.json");
+    if (fs.existsSync(local))
+        return local;
+    try {
+        let dir = import.meta.dirname;
+        for (let i = 0; i < 5; i++) {
+            for (const pkg of ["iflow-direct", "iflow"]) {
+                for (const name of ["iflow-credentials.json"]) {
+                    const p = path.join(dir, "node_modules", "@bobfrankston", pkg, name);
+                    if (fs.existsSync(p))
+                        return p;
+                }
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch { /* iflow not installed */ }
+    return null;
+}
+const GDRIVE_TOKEN_DIR = path.join(SETTINGS_DIR, "tokens", "gdrive");
+// drive: full access so we can find pre-existing folders like "home/.mailx"
+// that weren't created by this OAuth client. drive.file was safer but couldn't
+// discover folders created manually or by other tools — which broke first-run
+// setup when the user's convention is a nested path.
+// The Gmail scope is already mail.google.com (full email), so this isn't a
+// bigger privacy ask. Token cache at tokens/gdrive/ will re-auth on scope change.
+const GDRIVE_SCOPES = "https://www.googleapis.com/auth/drive";
+// ── Token helpers ──
+/** Get a GDrive-capable token. Prefers the Gmail token (which now includes
+ *  drive scope) — avoids a second OAuth consent prompt. Falls back to the
+ *  dedicated GDrive token dir for non-Gmail setups or when Gmail token
+ *  doesn't have drive scope yet. */
+async function getGoogleDriveToken() {
+    // Strategy 1: reuse a Gmail token that already has drive scope.
+    // Scan the tokens/ dir for any account token with drive in its scope.
+    const tokensDir = path.join(SETTINGS_DIR, "tokens");
+    if (fs.existsSync(tokensDir)) {
+        try {
+            for (const entry of fs.readdirSync(tokensDir)) {
+                if (entry === "gdrive")
+                    continue;
+                const tokenPath = path.join(tokensDir, entry, "oauth-token.json");
+                if (!fs.existsSync(tokenPath))
+                    continue;
+                try {
+                    const tok = JSON.parse(fs.readFileSync(tokenPath, "utf-8"));
+                    if (tok.scope?.includes("drive") && tok.refresh_token) {
+                        console.log(`  [cloud] Reusing Gmail token from ${entry} (has drive scope)`);
+                        const creds = findGoogleCredentials();
+                        if (!creds)
+                            continue;
+                        const refreshed = await authenticateOAuth(creds, {
+                            scope: tok.scope,
+                            tokenDirectory: path.join(tokensDir, entry),
+                            tokenFileName: "oauth-token.json",
+                            credentialsKey: "installed",
+                            includeOfflineAccess: true,
+                        });
+                        if (refreshed?.access_token) {
+                            console.log(`  [cloud] GDrive auth: success (via Gmail token)`);
+                            return refreshed.access_token;
+                        }
+                    }
+                }
+                catch { /* skip this token */ }
+            }
+        }
+        catch { /* tokens dir unreadable */ }
+    }
+    // Strategy 2: dedicated GDrive token (legacy path or non-Gmail setups)
+    const creds = findGoogleCredentials();
+    if (!creds) {
+        console.error("  [cloud] No Google credentials found (checked ~/.rmfmail/google-credentials.json and iflow package)");
+        return null;
+    }
+    const tokenPath = path.join(GDRIVE_TOKEN_DIR, "token.json");
+    if (fs.existsSync(tokenPath)) {
+        try {
+            const existing = JSON.parse(fs.readFileSync(tokenPath, "utf-8"));
+            const expired = existing.expires_at ? Date.now() >= existing.expires_at : true;
+            const hasRefresh = !!existing.refresh_token;
+            console.log(`  [cloud] GDrive token (dedicated): ${expired ? "expired" : "valid"}, refresh_token: ${hasRefresh ? "yes" : "NO"}, scope: ${existing.scope || "?"}`);
+            if (existing.scope && existing.scope !== GDRIVE_SCOPES) {
+                console.log(`  [cloud] Scope changed (${existing.scope} → ${GDRIVE_SCOPES}) — re-authenticating...`);
+                fs.unlinkSync(tokenPath);
+            }
+        }
+        catch { /* ignore */ }
+    }
+    else {
+        console.log(`  [cloud] GDrive token: not found at ${tokenPath} (will auth)`);
+    }
+    try {
+        const token = await authenticateOAuth(creds, {
+            scope: GDRIVE_SCOPES,
+            tokenDirectory: GDRIVE_TOKEN_DIR,
+            tokenFileName: "token.json",
+            credentialsKey: "installed",
+            includeOfflineAccess: true,
+        });
+        if (token?.access_token) {
+            console.log(`  [cloud] GDrive auth: success (dedicated token)`);
+        }
+        else {
+            console.error(`  [cloud] GDrive auth: returned null — OAuth likely timed out`);
+        }
+        return token?.access_token || null;
+    }
+    catch (e) {
+        console.error(`  [cloud] GDrive auth FAILED: ${e.message}`);
+        return null;
+    }
+}
+// ── Google Drive API (folder-ID based) ──
+/** Walk a nested folder path on GDrive ("home/.mailx" → find "home", find
+ *  ".mailx" inside it). Returns the leaf folder ID, or null if any segment is
+ *  missing. When `create` is true, creates the LAST segment if missing (won't
+ *  create intermediate segments — that's a user error). */
+async function walkGDrivePath(token, segments, create) {
+    const fullPath = segments.join("/");
+    let parentId;
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        const found = await gDriveFindFolder(token, seg, parentId);
+        if (found) {
+            console.log(`  [cloud] walk '${fullPath}': '${seg}' → ${found}${parentId ? ` (in ${parentId})` : ""}`);
+            parentId = found;
+        }
+        else if (create && i === segments.length - 1) {
+            const body = { name: seg, mimeType: "application/vnd.google-apps.folder" };
+            if (parentId)
+                body.parents = [parentId];
+            const res = await fetch("https://www.googleapis.com/drive/v3/files", {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok)
+                return null;
+            const created = await res.json();
+            parentId = created.id;
+        }
+        else {
+            return null;
+        }
+    }
+    return parentId || null;
+}
+/** Verify a cached folder ID still points to an `.rmfmail`-named folder
+ *  the user owns and isn't trashed. Returns true if the ID is good to use,
+ *  false if mailx should drop it and re-discover via gDriveFindOrCreateFolder.
+ *
+ *  Catches the cross-version-corruption case: 1.0.504 had a buggy folder
+ *  lookup that created an empty `rmfmail` folder at My Drive root and cached
+ *  its ID. Once 1.0.505 fixed the lookup, the cached ID still pointed at the
+ *  buggy folder forever — mailx kept reading the 1-account stub instead of
+ *  the user's real `home/.rmfmail/accounts.jsonc`. This validator forces a
+ *  re-discovery whenever the cached ID is wrong. */
+export async function gDriveValidateCachedFolder(folderId) {
+    const token = await getGoogleDriveToken();
+    if (!token)
+        return true; // can't verify → trust the cache (no token = nothing else to do)
+    try {
+        const res = await fetch(`https://www.googleapis.com/drive/v3/files/${folderId}?fields=id,name,trashed,mimeType`, { headers: { Authorization: `Bearer ${token}` } });
+        if (res.status === 404) {
+            console.log(`  [cloud] cached folderId ${folderId} → 404 (folder deleted), re-discovering`);
+            return false;
+        }
+        if (!res.ok)
+            return true;
+        const data = await res.json();
+        if (data.trashed) {
+            console.log(`  [cloud] cached folderId ${folderId} is trashed, re-discovering`);
+            return false;
+        }
+        if (data.mimeType !== "application/vnd.google-apps.folder") {
+            console.log(`  [cloud] cached folderId ${folderId} is not a folder (${data.mimeType}), re-discovering`);
+            return false;
+        }
+        if (data.name !== ".rmfmail") {
+            console.log(`  [cloud] cached folderId ${folderId} is named '${data.name}', not '.rmfmail' — re-discovering`);
+            return false;
+        }
+        return true;
+    }
+    catch (e) {
+        console.error(`  [cloud] gDriveValidateCachedFolder: ${e.message}`);
+        return true; // network failure → trust the cache
+    }
+}
+/** Find a single folder by name, optionally inside a parent. */
+async function gDriveFindFolder(token, name, parentId) {
+    let query = `name='${name}' and mimeType='application/vnd.google-apps.folder' and trashed=false`;
+    if (parentId)
+        query += ` and '${parentId}' in parents`;
+    const res = await fetch(`https://www.googleapis.com/drive/v3/files?q=${encodeURIComponent(query)}&fields=files(id,name)`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        console.error(`  [cloud] gdrive folder search '${name}': ${res.status} ${res.statusText}`);
+        return null;
+    }
+    const data = await res.json();
+    return data.files?.[0]?.id || null;
+}
+/** Find or create the rmfmail settings folder on Google Drive.
+ *
+ *  Lookup order — match the Android side (`mailx-store-web/android-bootstrap.ts`):
+ *    1. `home/.rmfmail/` — the established convention. Bob's family-of-two
+ *       layout has been here since the rebrand. Path scope (`'root' in
+ *       parents` for `home`, then `<homeId> in parents` for `.rmfmail`) is
+ *       what the Android side does, so desktop matches.
+ *    2. `.rmfmail/` at My Drive root — fallback for users who don't have a
+ *       `home/` folder. Mostly hypothetical; included so a brand-new Drive
+ *       still works.
+ *    3. Create `.rmfmail` at My Drive root if neither exists. Don't auto-
+ *       create `home/` — that's a user-organization choice we shouldn't
+ *       make for them.
+ *
+ *  Previously this looked for a literal `rmfmail` (no dot) at root, which
+ *  on clean install created a NEW empty folder alongside the real data,
+ *  orphaning the user's accounts/contacts/etc. Switched to the dotted name
+ *  matching the actual folder convention. */
+export async function gDriveFindOrCreateFolder() {
+    const token = await getGoogleDriveToken();
+    if (!token)
+        return null;
+    try {
+        // 1. Try home/.rmfmail (the canonical location)
+        const inHome = await walkGDrivePath(token, ["home", ".rmfmail"], false);
+        if (inHome) {
+            console.log(`  [cloud] Found 'home/.rmfmail' folder (${inHome})`);
+            return inHome;
+        }
+        // 2. Try .rmfmail at root
+        const atRoot = await walkGDrivePath(token, [".rmfmail"], false);
+        if (atRoot) {
+            console.log(`  [cloud] Found '.rmfmail' folder at My Drive root (${atRoot})`);
+            return atRoot;
+        }
+        // 3. Create .rmfmail at root (don't try to create `home/`)
+        const created = await walkGDrivePath(token, [".rmfmail"], true);
+        if (created)
+            console.log(`  [cloud] Created '.rmfmail' folder at My Drive root (${created})`);
+        return created;
+    }
+    catch (e) {
+        console.error(`  [cloud] gdrive folder setup: ${e.message}`);
+        return null;
+    }
+}
+/** Read a file by name from a folder (by ID) */
+async function gDriveReadFromFolder(folderId, fileName) {
+    const token = await getGoogleDriveToken();
+    if (!token) {
+        console.error(`  [cloud] gdrive read ${fileName}: no token`);
+        return null;
+    }
+    try {
+        // Find file in folder
+        const query = `name='${fileName}' and '${folderId}' in parents and trashed=false`;
+        const res = await fetch(`https://www.googleapis.com/drive/v3/files?q=${encodeURIComponent(query)}&fields=files(id)`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            console.error(`  [cloud] gdrive lookup '${fileName}': ${res.status}`);
+            return null;
+        }
+        const data = await res.json();
+        const fileId = data.files?.[0]?.id;
+        if (!fileId)
+            return null;
+        // Download content
+        const contentRes = await fetch(`https://www.googleapis.com/drive/v3/files/${fileId}?alt=media`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!contentRes.ok) {
+            console.error(`  [cloud] gdrive download ${fileName}: ${contentRes.status}`);
+            return null;
+        }
+        return await contentRes.text();
+    }
+    catch (e) {
+        console.error(`  [cloud] gdrive read ${fileName}: ${e.message}`);
+        return null;
+    }
+}
+/** Write a file by name to a folder (by ID) — creates or updates.
+ *  Throws on failure with a descriptive error so callers can surface it to the UI. */
+async function gDriveWriteToFolder(folderId, fileName, content) {
+    const token = await getGoogleDriveToken();
+    if (!token)
+        throw new Error("Google Drive: no auth token (OAuth not granted or expired)");
+    // Check if file exists in folder
+    const query = `name='${fileName}' and '${folderId}' in parents and trashed=false`;
+    const findRes = await fetch(`https://www.googleapis.com/drive/v3/files?q=${encodeURIComponent(query)}&fields=files(id)`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!findRes.ok) {
+        const body = await findRes.text().catch(() => "");
+        throw new Error(`Google Drive: lookup '${fileName}' failed (${findRes.status} ${findRes.statusText}) ${body.slice(0, 200)}`);
+    }
+    const findData = await findRes.json();
+    const existingId = findData.files?.[0]?.id;
+    if (existingId) {
+        // Update existing file
+        const res = await fetch(`https://www.googleapis.com/upload/drive/v3/files/${existingId}?uploadType=media`, {
+            method: "PATCH",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: content,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`Google Drive: update '${fileName}' failed (${res.status} ${res.statusText}) ${body.slice(0, 200)}`);
+        }
+    }
+    else {
+        // Create new file in folder
+        const boundary = "mailx_boundary_" + Date.now();
+        const metadata = JSON.stringify({ name: fileName, parents: [folderId] });
+        const body = `--${boundary}\r\nContent-Type: application/json\r\n\r\n${metadata}\r\n--${boundary}\r\nContent-Type: application/json\r\n\r\n${content}\r\n--${boundary}--`;
+        const res = await fetch("https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": `multipart/related; boundary=${boundary}` },
+            body,
+        });
+        if (!res.ok) {
+            const errBody = await res.text().catch(() => "");
+            throw new Error(`Google Drive: create '${fileName}' failed (${res.status} ${res.statusText}) ${errBody.slice(0, 200)}`);
+        }
+    }
+}
+/**
+ * Get a cloud file provider. For gdrive, pass the folder ID.
+ * Files are stored flat in the folder (no subdirectory navigation).
+ */
+export function getCloudProvider(provider, folderId) {
+    switch (provider) {
+        case "google":
+        case "gdrive":
+            if (!folderId) {
+                console.error("  [cloud] gdrive requires a folder ID — run initCloudConfig first");
+                return null;
+            }
+            return {
+                read: (fileName) => gDriveReadFromFolder(folderId, fileName),
+                write: (fileName, content) => gDriveWriteToFolder(folderId, fileName, content),
+                exists: async (fileName) => (await gDriveReadFromFolder(folderId, fileName)) !== null,
+            };
+        case "local":
+            return {
+                read: async (p) => { try {
+                    return fs.readFileSync(p, "utf-8");
+                }
+                catch {
+                    return null;
+                } },
+                write: async (p, c) => { fs.writeFileSync(p, c); },
+                exists: async (p) => fs.existsSync(p),
+            };
+        default:
+            console.error(`  [cloud] Provider "${provider}" not supported — only gdrive is available`);
+            return null;
+    }
+}
+/** Fetch the authenticated Google user's profile (name + email) via the People API.
+ *  Caller must supply an OAuth access token whose scopes include `contacts.readonly`
+ *  or `userinfo.profile`. The Drive token (drive.file) does NOT have the right scope
+ *  on its own — use the Gmail/IMAP OAuth token instead (mailx-imap's
+ *  ImapManager.getOAuthToken). Returns null on failure. */
+export async function getGoogleProfile(token) {
+    if (!token)
+        return null;
+    try {
+        const res = await fetch("https://people.googleapis.com/v1/people/me?personFields=names,emailAddresses", {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            console.error(`  [cloud] People API: ${res.status} ${res.statusText}`);
+            return null;
+        }
+        const data = await res.json();
+        const name = data.names?.find((n) => n.displayName)?.displayName
+            || data.names?.[0]?.displayName;
+        const email = data.emailAddresses?.find((e) => e.metadata?.primary)?.value
+            || data.emailAddresses?.[0]?.value;
+        return { name, email };
+    }
+    catch (e) {
+        console.error(`  [cloud] getGoogleProfile: ${e.message}`);
+        return null;
+    }
+}
+//# sourceMappingURL=cloud.js.map

package/copy-docs.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * copy-docs.js — pre-pack hook for mailx-settings.
+ *
+ * The reference docs live at `<workspace>/app/docs/*.md` so they're easy
+ * to edit and discover in the source tree. The published npm package
+ * needs them as a sibling of index.js so `deployDocs()` can find them at
+ * runtime via `__dirname/docs/`. This script copies the workspace docs
+ * into a local `./docs/` directory just before npm publish, then npm's
+ * `files` field includes them in the tarball.
+ *
+ * Idempotent — safe to run multiple times. Source path is the workspace
+ * root resolved upward from this package.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const __dirname = import.meta.dirname;
+const src = path.join(__dirname, "..", "..", "docs");
+const dst = path.join(__dirname, "docs");
+
+if (!fs.existsSync(src)) {
+    console.log(`[mailx-settings] no source docs at ${src} — skipping copy`);
+    process.exit(0);
+}
+fs.mkdirSync(dst, { recursive: true });
+const files = fs.readdirSync(src).filter(f => f.endsWith(".md"));
+for (const f of files) {
+    fs.copyFileSync(path.join(src, f), path.join(dst, f));
+}
+console.log(`[mailx-settings] copied ${files.length} .md file(s) from app/docs/ → docs/`);

package/docs/accounts.md

@@ -0,0 +1,41 @@
+# accounts.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** The canonical copy ships with each release; this file is a deployed copy for reference. To change account *settings*, edit `accounts.jsonc` (which IS user-editable). To change *documentation*, file an issue.
+
+## What this file documents
+
+`accounts.jsonc` lists every email account rmfmail manages. It lives in your shared GDrive folder (`My Drive/home/.rmfmail/`) so all your devices read the same list.
+
+## Shape
+
+```jsonc
+{
+  "name": "Bob Frankston",         // optional; default name applied to every account that doesn't override
+  "accounts": [
+    {
+      "id": "gmail",                // short tag used in folder paths and the UI
+      "email": "you@example.com",   // primary login address
+      "name": "Bob Frankston",      // display name (optional if file-level name is set)
+      "imap": { "host": "imap.example.com", "port": 993, "tls": true, "auth": "password" },
+      "smtp": { "host": "smtp.example.com", "port": 465, "tls": true, "auth": "password" },
+      "enabled": true,              // false skips this account at startup
+      "identityDomains": ["alias.com"]  // extra domains for Reply-From auto-detect
+    }
+  ]
+}
+```
+
+## Field rules
+
+- **id** — short identifier. Used in folder paths (e.g. `bob.ma/INBOX`) and as a stable key when accounts.jsonc is edited.
+- **email** — primary login. Determines provider auto-config when `imap`/`smtp` are omitted.
+- **imap / smtp** — explicit server config. Omit for known providers (Gmail / Outlook / Yahoo / iCloud / Google Workspace are detected from the email domain via MX records).
+- **auth** — `"password"` for traditional IMAP/SMTP, `"oauth2"` for Gmail/Google Workspace/Outlook.
+- **enabled** — set `false` to keep the account record but skip sync at startup.
+- **identityDomains** — addresses you receive at on alternative domains. When you Reply, rmfmail picks the matching identity address as From instead of the account's primary.
+
+## Notes
+
+- JSONC: `// line comments` and trailing commas are allowed. The parser is lenient.
+- Adding/removing accounts requires a daemon restart (`rmfmail -kill && rmfmail`). A status banner reminds you when the file changes.
+- For OAuth accounts (Gmail, Google Workspace), the token cache lives in `~/.rmfmail/tokens/` and is per-machine.

package/docs/allowlist.md

@@ -0,0 +1,27 @@
+# allowlist.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** This is reference documentation. To change allow-list data, edit `allowlist.jsonc` itself.
+
+## What this file documents
+
+`allowlist.jsonc` controls which senders' remote content (images, etc.) loads automatically and which senders/domains are flagged with a ⚠ banner. Lives in `My Drive/home/.rmfmail/`.
+
+## Shape
+
+```jsonc
+{
+  "senders": ["alice@example.com"],         // load remote content for these senders
+  "domains": ["example.com"],                // load remote content for any sender at these domains
+  "recipients": ["you@example.com"],         // addresses you receive at — treated as "your inbox identity"
+  "flaggedSenders": ["spam@bad.com"],        // viewer shows ⚠ FLAGGED banner for these senders
+  "flaggedDomains": ["phishing.example"]     // viewer shows ⚠ FLAGGED banner for any sender at these domains
+}
+```
+
+## Notes
+
+- All entries are case-insensitive plain email or domain strings.
+- Multi-client safe: each device's save merges with the cloud copy (set-union), so adds from any device propagate.
+- Use the message viewer's "allow remote content" button to add a sender/domain to `senders`/`domains` interactively.
+- Use the right-click menu in the viewer to flag a sender/domain — adds to `flaggedSenders`/`flaggedDomains`.
+- JSONC: `// line comments` and trailing commas are allowed.

package/docs/clients.md

@@ -0,0 +1,24 @@
+# clients.jsonc
+
+> **Owned by rmfmail. Do not edit this file — your changes will be overwritten the next time the app starts.** This is reference documentation.
+
+## What this file documents
+
+`clients.jsonc` is the registry of devices running rmfmail under your account. It's auto-managed: each device adds itself on first launch and refreshes its `lastSeen` timestamp on every startup. You don't normally need to look at it.
+
+## Shape
+
+```jsonc
+{
+  "devices": [
+    { "id": "abc-uuid", "name": "Pixel 9 Pro Fold", "lastSeen": 1746381600000, "accounts": ["gmail", "bobma"] },
+    { "id": "def-uuid", "name": "rmf39 desktop",     "lastSeen": 1746399999000, "accounts": ["gmail", "bobma"] }
+  ]
+}
+```
+
+## Notes
+
+- `id` is a stable UUID generated on first launch and stored locally (`localStorage` on Android, config dir on desktop).
+- `accounts` is the list of account ids this device is currently configured for.
+- Removing a device from this file forces it to re-register on next launch — harmless but pointless.

package/docs/config.md

@@ -0,0 +1,32 @@
+# config.jsonc
+
+> **Owned by rmfmail. Do not edit this DOCUMENTATION file — changes will be overwritten.** Note: the **actual** `config.jsonc` IS user-editable; this `.md` file is just the reference for it.
+
+## What this file documents
+
+`config.jsonc` is your *local, per-machine* config. It is **NOT** synced to GDrive — every machine has its own. It points at the shared GDrive folder and overrides machine-specific paths.
+
+Lives at `~/.rmfmail/config.jsonc` on the local filesystem.
+
+## Shape
+
+```jsonc
+{
+  "sharedDir": {
+    "provider": "gdrive",
+    "path": ".rmfmail",                            // folder name in My Drive (currently My Drive/home/.rmfmail)
+    "folderId": "1AbCdEf...XYZ"                    // resolved Drive folderId, cached after first lookup
+  },
+  "storePath": "C:/Users/Bob/.rmfmail/mailxstore", // local directory for .eml message bodies
+  "historyDays": 30                                // how far back to sync; overrides the shared default
+}
+```
+
+## Notes
+
+- `sharedDir.provider`: `"gdrive"` is the only currently-supported value (OneDrive/Dropbox were removed).
+- `sharedDir.folderId` is resolved at startup if missing; caching it avoids a Drive query on every launch.
+- `storePath` is where `.eml` bodies are stored locally. Defaults to `~/.rmfmail/mailxstore` on desktop. Android uses app-private sandbox storage and ignores this field.
+- `historyDays` is a per-machine override for the cloud-synced default in `preferences.jsonc`.
+- Because this file is local, edits don't propagate to other devices. Use `accounts.jsonc` / `preferences.jsonc` for shared settings.
+- JSONC: `// line comments` and trailing commas are allowed.