@open-workspace/email 0.0.0-stage → 0.1.0

package/worker/mcp/mail-safety-tools.ts

@@ -0,0 +1,452 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type { InboundAuthentication, MessageSecurity } from "../../shared/mail-authentication";
+import type { SenderIntel } from "../../shared/mail-sender-intel";
+import { reportStatusSchema, workspaceBlockSchema } from "@open-workspace/core/worker/admin/schemas.ts";
+import { mailRuleSchema } from "../mail/schemas";
+import { AccountApiClient, apiPath } from "@open-workspace/core/worker/mcp/account-client.ts";
+import { runTool } from "@open-workspace/core/worker/mcp/results.ts";
+import { entityIdSchema, mailboxIdSchema } from "@open-workspace/core/worker/mcp/schemas.ts";
+
+const readOnly = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+const write = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+const messageInputSchema = z.object({
+  mailboxId: mailboxIdSchema,
+  messageId: entityIdSchema,
+});
+
+const blockPatternSchema = z.string().trim().min(3).max(320).describe(
+  "An email address (alex@example.com) or a domain (example.com or @example.com; also matches its subdomains).",
+);
+
+const reportKindSchema = z.enum(["spam", "phishing"]);
+
+const RULE_SEMANTICS = "Rules run in list order on new incoming mail. Every condition present must match: from/to take an address (exact) or a domain (matches subdomains); subjectContains is a case-insensitive substring; listId is the List-Id. Actions: at most one destination (folderId of a custom folder, archive, or spam), plus optional markRead and neverSpam (overrides the AI spam verdict; cannot combine with spam).";
+
+const mailRuleInputSchema = z.object({
+  mailboxId: mailboxIdSchema,
+  ...mailRuleSchema.shape,
+});
+
+type AuthenticationResponse = {
+  original: {
+    subject: string;
+    from: string;
+    to: string[];
+    messageId: string | null;
+    receivedAt: string;
+    envelopeFrom: string | null;
+    envelopeTo: string | null;
+  };
+  authentication: InboundAuthentication | null;
+  security: MessageSecurity | null;
+  senderIntel: SenderIntel | null;
+};
+
+function authLine(result: string, details: Array<string | null | false | undefined>) {
+  const extra = details.filter(Boolean).join(", ");
+  return extra ? `${result} (${extra})` : result;
+}
+
+function compactAuthentication(auth: InboundAuthentication | null) {
+  if (!auth) return null;
+  return {
+    spf: auth.spf
+      ? authLine(auth.spf.result, [auth.spf.domain, auth.spf.aligned && "aligned"])
+      : null,
+    dkim: auth.dkim.map((dkim) => authLine(dkim.result, [
+      dkim.domain,
+      dkim.selector && `s=${dkim.selector}`,
+      dkim.aligned && "aligned",
+    ])),
+    dmarc: auth.dmarc
+      ? authLine(auth.dmarc.result, [
+        auth.dmarc.headerFrom,
+        auth.dmarc.policy && `p=${auth.dmarc.policy}`,
+        auth.dmarc.alignedVia.length > 0 && `via ${auth.dmarc.alignedVia.join("+")}`,
+      ])
+      : null,
+    arc: auth.arc
+      ? authLine(auth.arc.result, [
+        auth.arc.chainLength > 1 && `forwarded through ${auth.arc.sealers
+          .map((sealer) => sealer.domain ?? "unknown").join(", ")}`,
+      ])
+      : null,
+    remoteIp: auth.remoteIp,
+    helo: auth.helo,
+    envelopeFrom: auth.envelopeFrom,
+    spamScore: auth.spamScore,
+  };
+}
+
+function compactSenderIntel(intel: SenderIntel | null) {
+  if (!intel) return null;
+  const spamhausHits = intel.spamhaus
+    ? [...intel.spamhaus.zen.listings, ...intel.spamhaus.dbl.listings].map((listing) => ({
+      zone: listing.zone,
+      target: listing.target,
+      list: listing.list,
+      severity: listing.severity,
+    }))
+    : null;
+  return {
+    checkedAt: new Date(intel.checkedAt).toISOString(),
+    ip: intel.ip,
+    ptr: intel.ptr.confirmed ?? intel.ptr.names[0] ?? null,
+    forwardConfirmedPtr: intel.ptr.fcrdns,
+    genericPtr: intel.ptr.generic,
+    heloMatchesPtr: intel.heloMatchesPtr,
+    asn: intel.network.asn,
+    asName: intel.network.asName,
+    country: intel.network.country,
+    /** null means Spamhaus is not configured for this workspace. */
+    spamhausHits,
+  };
+}
+
+function compactSecurity(messageId: string, response: AuthenticationResponse) {
+  const security = response.security;
+  const unsubscribe = security?.listUnsubscribe ?? null;
+  return {
+    ok: true,
+    messageId,
+    from: response.original.from,
+    subject: response.original.subject,
+    receivedAt: response.original.receivedAt,
+    verdict: security?.verdict ?? response.authentication?.verdict ?? "unavailable",
+    verdictReason: security?.verdictReason ?? response.authentication?.verdictReason ?? null,
+    fromDomain: security?.fromDomain ?? null,
+    mailedBy: security?.mailedBy ?? null,
+    signedBy: security?.signedBy ?? null,
+    via: security?.via ?? null,
+    external: security?.external ?? null,
+    firstTimeSender: security?.firstTimeSender ?? false,
+    replyToMismatch: security?.replyToMismatch ?? null,
+    warnings: security?.warnings ?? [],
+    authentication: compactAuthentication(response.authentication),
+    senderIntel: compactSenderIntel(response.senderIntel),
+    unsubscribe: {
+      available: Boolean(unsubscribe?.httpsUrl || unsubscribe?.mailto),
+      oneClick: unsubscribe?.oneClick ?? false,
+      byEmail: Boolean(unsubscribe?.mailto),
+      pageUrl: unsubscribe?.httpsUrl ?? null,
+    },
+  };
+}
+
+export function registerMailSafetyTools(server: McpServer, api: AccountApiClient) {
+  server.registerTool(
+    "get_message_security",
+    {
+      title: "Get message security assessment",
+      description: "Summarize whether an incoming message is safe to trust: sender verdict (verified/unverified/suspicious/unavailable), one-line SPF/DKIM/DMARC/ARC results, mailed-by/signed-by/via, whether the sender is external, security warnings (lookalike domain, impersonation, Spamhaus listings, reply-to mismatch), sender server intel (IP, PTR, ASN, country, Spamhaus hits), and whether the message offers an unsubscribe option. Use this before acting on a suspicious message; use get_message_authentication only when the full parsed header data is needed. Blocked/trusted sender state is in get_conversation's per-message `sender` field.",
+      inputSchema: messageInputSchema,
+      annotations: readOnly,
+    },
+    ({ mailboxId, messageId }) => runTool(async () => compactSecurity(
+      messageId,
+      await api.json(apiPath(
+        `/mail/messages/${encodeURIComponent(messageId)}/authentication`,
+        { mailboxId },
+      )) as unknown as AuthenticationResponse,
+    )),
+  );
+
+  server.registerTool(
+    "unsubscribe_from_mailing_list",
+    {
+      title: "Unsubscribe from mailing list",
+      description: "OUTBOUND ACTION: unsubscribe this mailbox from the mailing list that sent an incoming message. With method \"auto\" the server tries, in order: an RFC 8058 one-click POST to the sender's URL (outcome \"done\"); an unsubscribe email sent from this mailbox, which requires send access (outcome \"requested\"); otherwise it returns the sender's unsubscribe page URL for the user to open themselves (outcome \"link\"). Method \"link\" only records that the user is opening the page and returns its URL; it contacts no one. Confirm with the user before calling. Rate-limited to 20 requests per minute. Check get_message_security's unsubscribe field first.",
+      inputSchema: messageInputSchema.extend({
+        method: z.enum(["auto", "link"]).default("auto"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    ({ mailboxId, messageId, method }) => runTool(() => api.json(apiPath(
+      `/mail/messages/${encodeURIComponent(messageId)}/unsubscribe`,
+      { mailboxId },
+    ), { method: "POST", json: { method } })),
+  );
+
+  server.registerTool(
+    "report_message",
+    {
+      title: "Report spam or phishing",
+      description: "Report an incoming message as spam or phishing: labels it, trains the sender's reputation, and moves its conversation to Spam. Phishing also opens a report for workspace administrators. Nothing is sent outside the workspace. Confirm with the user before reporting.",
+      inputSchema: messageInputSchema.extend({ kind: reportKindSchema }),
+      annotations: { ...write, idempotentHint: false },
+    },
+    ({ mailboxId, messageId, kind }) => runTool(() => api.json(apiPath(
+      `/mail/messages/${encodeURIComponent(messageId)}/report`,
+      { mailboxId },
+    ), { method: "POST", json: { kind } })),
+  );
+
+  server.registerTool(
+    "report_conversations",
+    {
+      title: "Report conversations as spam or phishing",
+      description: "Report the newest incoming message of up to 100 conversations as spam or phishing and move them to Spam. Phishing also opens administrator reports. Confirm with the user first.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        kind: reportKindSchema,
+        conversationIds: z.array(entityIdSchema).min(1).max(100)
+          .transform((ids) => [...new Set(ids)]),
+      }),
+      annotations: { ...write, idempotentHint: false },
+    },
+    ({ mailboxId, kind, conversationIds }) => runTool(() => api.json(apiPath(
+      "/mail/conversations/report",
+      { mailboxId },
+    ), { method: "POST", json: { kind, conversationIds } })),
+  );
+
+  server.registerTool(
+    "mark_message_not_spam",
+    {
+      title: "Mark message not spam",
+      description: "Move an incoming message's conversation from Spam back to Inbox, clear its spam/phishing label, record the feedback, and mark the sender as trusted in this mailbox.",
+      inputSchema: messageInputSchema,
+      annotations: write,
+    },
+    ({ mailboxId, messageId }) => runTool(() => api.json(apiPath(
+      `/mail/messages/${encodeURIComponent(messageId)}/not-spam`,
+      { mailboxId },
+    ), { method: "POST" })),
+  );
+
+  server.registerTool(
+    "set_sender_trusted",
+    {
+      title: "Trust or untrust sender",
+      description: "Mark a sender address as trusted (or not) for everyone using this mailbox. Trusted senders have caution warnings hidden; danger warnings still show.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        address: z.email(),
+        trusted: z.boolean(),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, address, trusted }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/trusted-senders`,
+      { method: "PUT", json: { address, trusted } },
+    )),
+  );
+
+  server.registerTool(
+    "list_blocked_senders",
+    {
+      title: "List blocked senders",
+      description: "List addresses and domains blocked in this mailbox, plus workspace-wide blocks set by administrators (which the mailbox cannot remove).",
+      inputSchema: z.object({ mailboxId: mailboxIdSchema }),
+      annotations: readOnly,
+    },
+    ({ mailboxId }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/blocked-senders`,
+    )),
+  );
+
+  server.registerTool(
+    "block_sender",
+    {
+      title: "Block sender or domain",
+      description: "Block an address or domain for everyone using this mailbox: future mail from it goes to Spam. With moveExisting, existing conversations from it are also moved to Spam. The mailbox's own address or domain cannot be blocked.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        pattern: blockPatternSchema,
+        moveExisting: z.boolean().default(false),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, pattern, moveExisting }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/blocked-senders`,
+      { method: "POST", json: { pattern, moveExisting } },
+    )),
+  );
+
+  server.registerTool(
+    "unblock_sender",
+    {
+      title: "Unblock sender or domain",
+      description: "Remove a mailbox block. Mail already moved to Spam stays there. Workspace-wide blocks can only be removed by an administrator.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        pattern: blockPatternSchema,
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, pattern }) => runTool(() => api.json(apiPath(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/blocked-senders`,
+      { pattern },
+    ), { method: "DELETE" })),
+  );
+
+  server.registerTool(
+    "list_mail_rules",
+    {
+      title: "List mail rules",
+      description: `List the mailbox's filter rules in the order they run. ${RULE_SEMANTICS}`,
+      inputSchema: z.object({ mailboxId: mailboxIdSchema }),
+      annotations: readOnly,
+    },
+    ({ mailboxId }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/rules`,
+    )),
+  );
+
+  server.registerTool(
+    "create_mail_rule",
+    {
+      title: "Create mail rule",
+      description: `Create a filter rule shared by everyone using the mailbox, appended to the end of the list. It applies to new mail only; call apply_mail_rule to run it on existing mail. ${RULE_SEMANTICS}`,
+      inputSchema: mailRuleInputSchema,
+      annotations: { ...write, idempotentHint: false },
+    },
+    ({ mailboxId, ...rule }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/rules`,
+      { method: "POST", json: rule },
+    )),
+  );
+
+  server.registerTool(
+    "update_mail_rule",
+    {
+      title: "Update mail rule",
+      description: `Replace a rule's name, enabled state, conditions, and actions. ${RULE_SEMANTICS}`,
+      inputSchema: mailRuleInputSchema.extend({ ruleId: entityIdSchema }),
+      annotations: write,
+    },
+    ({ mailboxId, ruleId, ...rule }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/rules/${encodeURIComponent(ruleId)}`,
+      { method: "PUT", json: rule },
+    )),
+  );
+
+  server.registerTool(
+    "delete_mail_rule",
+    {
+      title: "Delete mail rule",
+      description: "Delete a mail rule. Mail it already filed stays where it is.",
+      inputSchema: z.object({ mailboxId: mailboxIdSchema, ruleId: entityIdSchema }),
+      annotations: { ...write, destructiveHint: true },
+    },
+    ({ mailboxId, ruleId }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/rules/${encodeURIComponent(ruleId)}`,
+      { method: "DELETE" },
+    )),
+  );
+
+  server.registerTool(
+    "reorder_mail_rules",
+    {
+      title: "Reorder mail rules",
+      description: "Set the complete run order of the mailbox's rules. ruleIds must list every existing rule exactly once; otherwise the call fails and the rules should be listed again.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        ruleIds: z.array(entityIdSchema).max(100),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, ruleIds }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/rules-order`,
+      { method: "PUT", json: { ruleIds } },
+    )),
+  );
+
+  server.registerTool(
+    "apply_mail_rule",
+    {
+      title: "Apply mail rule to existing mail",
+      description: "Run one rule over the newest 5,000 incoming messages already in the mailbox. Matching Inbox conversations move to the rule's destination (a Spam rule also takes archived ones); markRead applies only for the current account. This moves many conversations at once; confirm with the user first.",
+      inputSchema: z.object({ mailboxId: mailboxIdSchema, ruleId: entityIdSchema }),
+      annotations: { ...write, idempotentHint: false },
+    },
+    ({ mailboxId, ruleId }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/rules/${encodeURIComponent(ruleId)}/apply`,
+      { method: "POST" },
+    )),
+  );
+}
+
+export function registerAdminSafetyTools(server: McpServer, api: AccountApiClient) {
+  server.registerTool(
+    "list_reported_messages",
+    {
+      title: "List reported phishing",
+      description: "Administrator: list the 200 most recent phishing reports across the workspace (sender, subject, reporter, security snapshot, status, whether the sender or domain is blocked workspace-wide), plus every workspace-wide block. Reported messages can only be inspected through their report.",
+      inputSchema: z.object({
+        status: z.enum(["open", "resolved", "dismissed"]).optional()
+          .describe("Return only reports with this status."),
+      }),
+      annotations: readOnly,
+    },
+    ({ status }) => runTool(async () => {
+      const result = await api.json("/admin/reported-messages");
+      if (!status || !Array.isArray(result.reports)) return result;
+      return {
+        ...result,
+        reports: (result.reports as Array<{ status: string }>)
+          .filter((report) => report.status === status),
+      };
+    }),
+  );
+
+  server.registerTool(
+    "set_report_status",
+    {
+      title: "Resolve or dismiss phishing report",
+      description: "Administrator: set a phishing report to open, resolved, or dismissed.",
+      inputSchema: reportStatusSchema.safeExtend({ reportId: entityIdSchema }),
+      annotations: write,
+    },
+    ({ reportId, status }) => runTool(() => api.json(
+      `/admin/reported-messages/${encodeURIComponent(reportId)}`,
+      { method: "PATCH", json: { status } },
+    )),
+  );
+
+  server.registerTool(
+    "block_sender_for_workspace",
+    {
+      title: "Block sender for everyone",
+      description: "Administrator: block an address or domain for every mailbox in the workspace; its future mail goes to Spam everywhere, and by default (moveExisting) mail already delivered from it is moved to Spam in every mailbox too. Workspace domains cannot be blocked. Pass reportId to also resolve the phishing report that prompted the block. Confirm with the user first.",
+      inputSchema: workspaceBlockSchema.safeExtend({ pattern: blockPatternSchema }),
+      annotations: write,
+    },
+    (input) => runTool(() => api.json("/admin/blocked-senders", {
+      method: "POST",
+      json: input,
+    })),
+  );
+
+  server.registerTool(
+    "unblock_sender_for_workspace",
+    {
+      title: "Remove workspace-wide block",
+      description: "Administrator: remove a workspace-wide block. Mailbox-level blocks are unaffected.",
+      inputSchema: z.object({ pattern: blockPatternSchema }),
+      annotations: write,
+    },
+    ({ pattern }) => runTool(() => api.json(
+      apiPath("/admin/blocked-senders", { pattern }),
+      { method: "DELETE" },
+    )),
+  );
+}

package/worker/mcp/tools.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceModule } from "@open-workspace/core/worker/modules.ts";
+import { registerMailActionTools } from "./mail-action-tools";
+import { registerMailComposeTools } from "./mail-compose-tools";
+import { registerMailQueryTools } from "./mail-query-tools";
+import { registerAdminSafetyTools, registerMailSafetyTools } from "./mail-safety-tools";
+
+export const registerMailTools: NonNullable<WorkspaceModule["mcpTools"]> = (server, input) => {
+  registerMailQueryTools(server, input.api);
+  registerMailActionTools(server, input.api);
+  registerMailComposeTools(server, input.api);
+  registerMailSafetyTools(server, input.api);
+  if (input.permissions.includes("review_reports")) {
+    registerAdminSafetyTools(server, input.api);
+  }
+};

package/worker/module.ts

@@ -0,0 +1,59 @@
+import { Hono } from "hono";
+import type { AppEnv } from "@open-workspace/core/worker/env.ts";
+import type { WorkspaceModule } from "@open-workspace/core/worker/modules.ts";
+import { reportAdminRoutes } from "./admin/report-routes";
+import { consumeDeliveryEvents } from "./mail/delivery-events";
+import { demoRoutes } from "./mail/demo-routes";
+import { mailDownloadRoutes } from "./mail/downloads";
+import { receiveEmail } from "./mail/receive";
+import { deleteMailboxStorage } from "./mail/mailbox-deletion";
+import { consumeOfficePreviews } from "./mail/office-preview-queue";
+import {
+  consumePushNotifications,
+  pushNotificationRoutes,
+} from "./mail/push-notifications";
+import { mailRoutes } from "./mail/routes";
+import { emailWebhookData } from "./mail/webhook-source";
+import { seedEmailDemo } from "./mailbox/demo-seed";
+import { registerMailTools } from "./mcp/tools";
+
+/** Routes the browser and MCP use under /api. */
+export const mailAccountApi = new Hono<AppEnv>()
+  .route("/mail", mailRoutes)
+  .route("/admin", reportAdminRoutes);
+
+const mailPublicRoutes = new Hono<AppEnv>()
+  .route("/api/downloads", mailDownloadRoutes)
+  .route("/api/demo", demoRoutes)
+  .route("/api/notifications", pushNotificationRoutes);
+
+/** The routes this module adds, for the browser's typed client. */
+export const mailBrowserApi = new Hono<AppEnv>()
+  .route("/api", mailAccountApi)
+  .route("/", mailPublicRoutes);
+export type MailAppType = typeof mailBrowserApi;
+
+/**
+ * Team mail: personal and shared inboxes, mailing lists, previews, safety,
+ * and push. Pass `email()` to `createWorkspace({ modules })`, and export
+ * `MailboxDO` and `OfficePreviewContainer` from the Worker entry.
+ */
+export function email(): WorkspaceModule {
+  return {
+    name: "email",
+    accountApi: mailAccountApi,
+    routes: mailPublicRoutes,
+    email: (message, env) => receiveEmail(message, env),
+    queues: {
+      "office-previews": (batch, env) => consumeOfficePreviews(batch, env),
+      "push-notifications": (batch, env) => consumePushNotifications(batch, env),
+      "delivery-events": (batch, env) => consumeDeliveryEvents(batch, env),
+    },
+    mcpTools: registerMailTools,
+    webhookSources: { email: emailWebhookData },
+    hooks: {
+      mailboxDeleted: deleteMailboxStorage,
+      seedDemo: (env, input) => seedEmailDemo(env, input),
+    },
+  };
+}