@mcinteerj/openclaw-gmail 1.2.0

package/src/normalize.ts

@@ -0,0 +1,42 @@
+export function isGmailThreadId(id: string): boolean {
+  // Gmail thread IDs are hex strings, variable length (often ~16 chars)
+  return /^[0-9a-fA-F]{16,}$/.test(id) && !id.includes("@");
+}
+
+export function isEmail(id: string): boolean {
+  // Simple email validation
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(id);
+}
+
+export function normalizeGmailTarget(raw: string): string | null {
+  const trimmed = raw?.trim();
+  if (!trimmed) return null;
+
+  if (isEmail(trimmed)) {
+    return trimmed.toLowerCase();
+  }
+
+  if (isGmailThreadId(trimmed)) {
+    return trimmed.toLowerCase();
+  }
+
+  return null;
+}
+
+export function isAllowed(senderId: string, allowList: string[]): boolean {
+  if (allowList.length === 0) return false;
+  if (allowList.includes("*")) return true;
+
+  const normalizedSender = senderId.toLowerCase();
+  return allowList.some((entry) => {
+    const normalized = entry.toLowerCase().trim();
+    if (!normalized) return false;
+    // Exact match
+    if (normalizedSender === normalized) return true;
+    // Domain wildcard match (e.g., "@gmail.com")
+    if (normalized.startsWith("@") && normalizedSender.endsWith(normalized)) {
+      return true;
+    }
+    return false;
+  });
+}

package/src/onboarding.ts

@@ -0,0 +1,214 @@
+import type { OpenClawConfig, ChannelOnboardingAdapter } from "openclaw/plugin-sdk";
+import { promptAccountId } from "openclaw/plugin-sdk";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { listGmailAccountIds, resolveDefaultGmailAccountId } from "./accounts.js";
+
+const execAsync = promisify(exec);
+const channel = "gmail" as const;
+
+const MIN_GOG_VERSION = "1.2.0";
+
+async function checkGogInstalled(): Promise<boolean> {
+  try {
+    await execAsync("command -v gog");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getGogVersion(): Promise<string | null> {
+  try {
+    const { stdout } = await execAsync("gog --version");
+    const match = stdout.match(/gog version (\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function isVersionAtLeast(current: string, min: string): boolean {
+  const currentParts = current.split(".").map(Number);
+  const minParts = min.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (currentParts[i] > minParts[i]) return true;
+    if (currentParts[i] < minParts[i]) return false;
+  }
+  return true;
+}
+
+async function checkGogAuth(email: string): Promise<boolean> {
+  try {
+    const { stdout } = await execAsync("gog auth list --plain");
+    return stdout.includes(email);
+  } catch {
+    return false;
+  }
+}
+
+async function authorizeGog(email: string): Promise<void> {
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve, reject) => {
+    const child = spawn("gog", ["auth", "add", email], { stdio: "inherit" });
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`gog auth failed with code ${code}`));
+    });
+  });
+}
+
+async function fetchGmailName(email: string): Promise<string | undefined> {
+  try {
+    const { stdout } = await execAsync(`gog gmail settings sendas list --account ${email} --json`);
+    const data = JSON.parse(stdout);
+    const primary = data.sendAs?.find((s: any) => s.isPrimary) || data.sendAs?.[0];
+    return primary?.displayName;
+  } catch {
+    return undefined;
+  }
+}
+
+export const gmailOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }: { cfg: OpenClawConfig }) => {
+    const ids = listGmailAccountIds(cfg);
+    const configured = ids.length > 0;
+    return {
+      channel,
+      configured,
+      statusLines: [`Gmail: ${configured ? `${ids.length} accounts` : "not configured"}`],
+      selectionHint: "Polling via gog CLI",
+      quickstartScore: configured ? 1 : 5,
+    };
+  },
+  configure: async ({
+    cfg,
+    prompter,
+    accountOverrides,
+    shouldPromptAccountIds,
+  }: {
+    cfg: OpenClawConfig;
+    prompter: {
+      text: (opts: { message: string; validate?: (val?: string) => string | undefined; initialValue?: string }) => Promise<string>;
+      confirm: (opts: { message: string; initialValue?: boolean }) => Promise<boolean>;
+      note: (message: string, title?: string) => Promise<void>;
+    };
+    accountOverrides: Record<string, string>;
+    shouldPromptAccountIds: boolean;
+  }) => {
+    if (!(await checkGogInstalled())) {
+      await prompter.note(
+        "The `gog` CLI is required for the Gmail extension.\nPlease install it and ensure it is in your PATH.",
+        "Missing Dependency"
+      );
+      throw new Error("gog CLI not found");
+    }
+
+    const version = await getGogVersion();
+    if (version && !isVersionAtLeast(version, MIN_GOG_VERSION)) {
+      await prompter.note(
+        `Your gog version (${version}) is below the recommended ${MIN_GOG_VERSION}.\nSome features may not work correctly.`,
+        "Version Warning"
+      );
+    }
+
+    const existingIds = listGmailAccountIds(cfg);
+    const gmailOverride = accountOverrides.gmail?.trim();
+    const defaultAccountId = resolveDefaultGmailAccountId(cfg);
+    let accountId = gmailOverride || defaultAccountId;
+
+    if (shouldPromptAccountIds && !gmailOverride && existingIds.length > 0) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "Gmail",
+        currentId: accountId,
+        listAccountIds: listGmailAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let email = accountId.includes("@") ? accountId : undefined;
+    if (!email) {
+      email = await prompter.text({
+        message: "Gmail address",
+        validate: (val: string | undefined) => (val?.includes("@") ? undefined : "Valid email required"),
+      });
+    }
+
+    if (!email) throw new Error("Email required");
+
+    const isAuthed = await checkGogAuth(email);
+    if (!isAuthed) {
+      await prompter.note(
+        `Gog CLI is not authorized for ${email}. We need to authorize it now.`,
+        "Authorization"
+      );
+      const doAuth = await prompter.confirm({
+        message: "Authorize gog now?",
+        initialValue: true,
+      });
+      if (doAuth) {
+        await authorizeGog(email);
+      } else {
+        await prompter.note("Skipping auth. You must run `gog auth add " + email + "` manually.", "Warning");
+      }
+    }
+
+    const allowFromRaw = await prompter.text({
+      message: "Allow emails from (comma separated, * for all)",
+      initialValue: "",
+    });
+    const allowFrom = allowFromRaw.split(",").map((s: string) => s.trim()).filter(Boolean);
+
+    const pollIntervalSecsRaw = await prompter.text({
+      message: "Polling interval (seconds)",
+      initialValue: "60",
+      validate: (val: string | undefined) => {
+        const n = parseInt(val || "", 10);
+        return isNaN(n) || n < 1 ? "Positive integer required" : undefined;
+      }
+    });
+    const pollIntervalMs = parseInt(pollIntervalSecsRaw, 10) * 1000;
+
+    const name = await fetchGmailName(email);
+
+    const accountConfig = {
+      enabled: true,
+      email,
+      name,
+      allowFrom,
+      pollIntervalMs,
+    };
+
+    const gmailConfig = cfg.channels?.gmail || {};
+    const accounts = gmailConfig.accounts || {};
+
+    const next = {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        gmail: {
+          dmPolicy: "allowlist",
+          archiveOnReply: true,
+          ...gmailConfig,
+          enabled: true,
+          accounts: {
+            ...accounts,
+            [email]: accountConfig,
+          },
+        },
+      },
+    };
+
+    return { cfg: next, accountId: email };
+  },
+  disable: (cfg: OpenClawConfig) => ({
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      gmail: { ...cfg.channels?.gmail, enabled: false },
+    },
+  }),
+};

package/src/outbound-check.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect } from "vitest";
+import { isEmailAllowed, parseEmailAddresses } from "./outbound-check.js";
+
+describe("parseEmailAddresses", () => {
+  describe("simple emails", () => {
+    it("parses plain email address", () => {
+      const result = parseEmailAddresses("user@example.com");
+      expect(result).toEqual([{ email: "user@example.com" }]);
+    });
+
+    it("lowercases email addresses", () => {
+      const result = parseEmailAddresses("User@Example.COM");
+      expect(result).toEqual([{ email: "user@example.com" }]);
+    });
+  });
+
+  describe("named addresses", () => {
+    it("parses Name <email> format", () => {
+      const result = parseEmailAddresses("John Doe <john@example.com>");
+      expect(result).toEqual([{ name: "John Doe", email: "john@example.com" }]);
+    });
+
+    it("parses quoted name with special chars", () => {
+      const result = parseEmailAddresses('"Last, First" <user@example.com>');
+      expect(result).toEqual([{ name: "Last, First", email: "user@example.com" }]);
+    });
+
+    it("handles name with quotes", () => {
+      const result = parseEmailAddresses('"John \\"Johnny\\" Doe" <john@example.com>');
+      expect(result[0].email).toBe("john@example.com");
+    });
+  });
+
+  describe("multiple addresses", () => {
+    it("parses comma-separated addresses", () => {
+      const result = parseEmailAddresses("a@example.com, b@example.com");
+      expect(result).toHaveLength(2);
+      expect(result[0].email).toBe("a@example.com");
+      expect(result[1].email).toBe("b@example.com");
+    });
+
+    it("parses mixed formats", () => {
+      const result = parseEmailAddresses("John <john@example.com>, jane@example.com");
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({ name: "John", email: "john@example.com" });
+      expect(result[1]).toEqual({ email: "jane@example.com" });
+    });
+
+    it("handles quoted names with commas among multiple addresses", () => {
+      const result = parseEmailAddresses('"Last, First" <a@example.com>, b@example.com');
+      expect(result).toHaveLength(2);
+      expect(result[0].name).toBe("Last, First");
+      expect(result[0].email).toBe("a@example.com");
+      expect(result[1].email).toBe("b@example.com");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns empty array for empty string", () => {
+      expect(parseEmailAddresses("")).toEqual([]);
+    });
+
+    it("returns empty array for null/undefined", () => {
+      expect(parseEmailAddresses(null as any)).toEqual([]);
+      expect(parseEmailAddresses(undefined as any)).toEqual([]);
+    });
+
+    it("ignores malformed entries without @", () => {
+      const result = parseEmailAddresses("not-an-email, valid@example.com");
+      expect(result).toHaveLength(1);
+      expect(result[0].email).toBe("valid@example.com");
+    });
+
+    it("handles extra whitespace", () => {
+      const result = parseEmailAddresses("  user@example.com  ");
+      expect(result).toEqual([{ email: "user@example.com" }]);
+    });
+  });
+});
+
+describe("isEmailAllowed", () => {
+  describe("empty allowlist", () => {
+    it("allows any email when allowlist is empty", () => {
+      expect(isEmailAllowed("anyone@example.com", [])).toBe(true);
+    });
+  });
+
+  describe("wildcard", () => {
+    it("allows any email with * wildcard", () => {
+      expect(isEmailAllowed("anyone@anywhere.com", ["*"])).toBe(true);
+    });
+
+    it("allows any email with * among other entries", () => {
+      expect(isEmailAllowed("random@test.com", ["specific@example.com", "*"])).toBe(true);
+    });
+  });
+
+  describe("exact match", () => {
+    it("allows exact email match", () => {
+      expect(isEmailAllowed("user@example.com", ["user@example.com"])).toBe(true);
+    });
+
+    it("matches case-insensitively", () => {
+      expect(isEmailAllowed("User@Example.COM", ["user@example.com"])).toBe(true);
+    });
+
+    it("rejects non-matching email", () => {
+      expect(isEmailAllowed("other@example.com", ["user@example.com"])).toBe(false);
+    });
+  });
+
+  describe("domain wildcard", () => {
+    it("allows email matching domain wildcard", () => {
+      expect(isEmailAllowed("anyone@company.com", ["@company.com"])).toBe(true);
+    });
+
+    it("matches domain case-insensitively", () => {
+      expect(isEmailAllowed("user@COMPANY.COM", ["@company.com"])).toBe(true);
+    });
+
+    it("rejects email from different domain", () => {
+      expect(isEmailAllowed("user@other.com", ["@company.com"])).toBe(false);
+    });
+
+    it("does not match partial domain names", () => {
+      // @company.com should not match @notcompany.com
+      expect(isEmailAllowed("user@notcompany.com", ["@company.com"])).toBe(false);
+    });
+
+    it("matches subdomain when specified", () => {
+      expect(isEmailAllowed("user@sub.company.com", ["@sub.company.com"])).toBe(true);
+    });
+  });
+
+  describe("multiple entries", () => {
+    it("allows if any entry matches", () => {
+      const allowList = ["admin@example.com", "@trusted.com", "vip@special.org"];
+      
+      expect(isEmailAllowed("admin@example.com", allowList)).toBe(true);
+      expect(isEmailAllowed("anyone@trusted.com", allowList)).toBe(true);
+      expect(isEmailAllowed("vip@special.org", allowList)).toBe(true);
+      expect(isEmailAllowed("random@other.com", allowList)).toBe(false);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles whitespace in allowlist entries", () => {
+      expect(isEmailAllowed("user@example.com", ["  user@example.com  "])).toBe(true);
+    });
+
+    it("ignores empty entries", () => {
+      expect(isEmailAllowed("user@example.com", ["", "  ", "user@example.com"])).toBe(true);
+    });
+
+    it("handles empty email gracefully", () => {
+      expect(isEmailAllowed("", ["user@example.com"])).toBe(false);
+    });
+  });
+});

package/src/outbound-check.ts

@@ -0,0 +1,233 @@
+/**
+ * Thread recipient validation for Gmail outbound.
+ * 
+ * Validates that thread reply recipients are permitted by allowOutboundTo.
+ */
+
+import { spawn } from "node:child_process";
+
+export interface ThreadParticipant {
+  email: string;
+  name?: string;
+}
+
+export interface ThreadData {
+  participants: ThreadParticipant[];
+  originalSender: string | null;
+}
+
+/**
+ * Fetch thread data (participants and original sender) in a single call.
+ */
+export async function fetchThreadData(
+  threadId: string, 
+  accountEmail: string
+): Promise<ThreadData> {
+  return new Promise((resolve, reject) => {
+    const args = ["gmail", "thread", "get", threadId, "--json", "--account", accountEmail];
+    const proc = spawn("gog", args, { stdio: "pipe" });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timeout = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        proc.kill();
+        reject(new Error("Timeout fetching thread data"));
+      }
+    }, 10000);
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+    };
+
+    proc.stdout.on("data", (d) => (stdout += d.toString()));
+    proc.stderr.on("data", (d) => (stderr += d.toString()));
+
+    proc.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+
+      if (code !== 0) {
+        reject(new Error(`Failed to fetch thread: ${stderr}`));
+        return;
+      }
+
+      try {
+        const data = JSON.parse(stdout);
+        const messages = data.thread?.messages || [];
+        const participants = new Map<string, ThreadParticipant>();
+        let originalSender: string | null = null;
+
+        for (let i = 0; i < messages.length; i++) {
+          const msg = messages[i];
+          const headers = msg.payload?.headers || [];
+          
+          for (const header of headers) {
+            const name = header.name.toLowerCase();
+            if (["from", "to", "cc"].includes(name)) {
+              const addresses = parseEmailAddresses(header.value);
+              for (const addr of addresses) {
+                if (addr.email.toLowerCase() !== accountEmail.toLowerCase()) {
+                  participants.set(addr.email.toLowerCase(), addr);
+                }
+                
+                // Capture original sender from first message's From header
+                if (i === 0 && name === "from" && !originalSender) {
+                  originalSender = addr.email;
+                }
+              }
+            }
+          }
+        }
+
+        resolve({
+          participants: Array.from(participants.values()),
+          originalSender,
+        });
+      } catch (e) {
+        reject(new Error(`Failed to parse thread: ${e}`));
+      }
+    });
+
+    proc.on("error", (e) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new Error(`Failed to spawn gog: ${e.message}`));
+    });
+  });
+}
+
+/**
+ * Parse email addresses from a header value like "Name <email>, Other <email2>"
+ * 
+ * Handles:
+ * - Simple: email@example.com
+ * - Named: Name <email@example.com>
+ * - Quoted names with commas: "Last, First" <email@example.com>
+ * - Multiple addresses separated by commas
+ */
+export function parseEmailAddresses(value: string): ThreadParticipant[] {
+  const results: ThreadParticipant[] = [];
+  if (!value || typeof value !== "string") return results;
+  
+  // Split by comma, but respect quoted strings
+  // This regex splits on commas that are NOT inside quotes
+  const parts = value.split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/);
+  
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    
+    // Try to match "Name" <email> or Name <email>
+    const match = trimmed.match(/^(?:"?([^"<]*)"?\s*)?<([^>]+)>$/);
+    
+    if (match) {
+      const name = match[1]?.trim().replace(/^"|"$/g, "");
+      const email = match[2].trim().toLowerCase();
+      if (email.includes("@")) {
+        results.push({ name: name || undefined, email });
+      }
+    } else if (trimmed.includes("@")) {
+      // Plain email address
+      results.push({ email: trimmed.toLowerCase() });
+    }
+  }
+  
+  return results;
+}
+
+/**
+ * Check if an email is allowed by the allowlist.
+ * 
+ * Rules:
+ * - Empty list = no restriction (returns true)
+ * - "*" in list = allow all
+ * - Exact match (case-insensitive)
+ * - Domain wildcard: "@company.com" matches any @company.com address
+ */
+export function isEmailAllowed(email: string, allowList: string[]): boolean {
+  // Empty list = no restriction
+  if (allowList.length === 0) return true;
+  if (allowList.includes("*")) return true;
+  
+  if (!email) return false;
+  const normalized = email.toLowerCase();
+  
+  return allowList.some((entry) => {
+    const e = entry.toLowerCase().trim();
+    if (!e) return false;
+    if (normalized === e) return true;
+    // Domain wildcard: must start with @ and email must end with it
+    if (e.startsWith("@") && normalized.endsWith(e)) return true;
+    return false;
+  });
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  blocked?: string[];
+  reason?: string;
+}
+
+/**
+ * Validate thread recipients against policy.
+ * 
+ * Policies:
+ * - "open": Allow replies to anyone (default, backwards compatible)
+ * - "allowlist": All recipients must be in allowOutboundTo
+ * - "sender-only": Only reply if original sender is allowed (ignore CC'd parties)
+ */
+export async function validateThreadReply(
+  threadId: string,
+  accountEmail: string,
+  allowOutboundTo: string[],
+  policy: "open" | "allowlist" | "sender-only"
+): Promise<ValidationResult> {
+  if (policy === "open") {
+    return { ok: true };
+  }
+
+  let threadData: ThreadData;
+  try {
+    threadData = await fetchThreadData(threadId, accountEmail);
+  } catch (err) {
+    console.error(`[gmail] Failed to fetch thread data for validation: ${err}`);
+    return { ok: false, reason: `Could not fetch thread data: ${err}` };
+  }
+
+  if (policy === "sender-only") {
+    if (!threadData.originalSender) {
+      console.error(`[gmail] Could not determine original sender for thread ${threadId}`);
+      return { ok: false, reason: "Could not determine thread sender" };
+    }
+    
+    if (!isEmailAllowed(threadData.originalSender, allowOutboundTo)) {
+      return { 
+        ok: false, 
+        blocked: [threadData.originalSender], 
+        reason: "Thread sender not in allowOutboundTo" 
+      };
+    }
+    
+    return { ok: true };
+  }
+
+  // policy === "allowlist"
+  const blocked: string[] = [];
+
+  for (const p of threadData.participants) {
+    if (!isEmailAllowed(p.email, allowOutboundTo)) {
+      blocked.push(p.email);
+    }
+  }
+
+  if (blocked.length > 0) {
+    return { ok: false, blocked, reason: "Recipients not in allowOutboundTo" };
+  }
+
+  return { ok: true };
+}