agent-inbox 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inbox",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Agent Inbox — message routing, traceability, and MCP tools for multi-agent systems",
   "type": "module",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
     "bench:growth": "vitest run --config vitest.bench.config.ts",
     "start": "node dist/index.js",
     "publish:npm": "npm publish --access public",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run build && publint",
     "version:patch": "npm version patch && git push && git push --tags",
     "version:minor": "npm version minor && git push && git push --tags",
     "version:major": "npm version major && git push && git push --tags"
@@ -42,7 +42,12 @@
   },
   "peerDependencies": {
     "@multi-agent-protocol/sdk": "*",
-    "agentic-mesh": "*"
+    "agentic-mesh": "*",
+    "mailauth": "*",
+    "mailparser": "*",
+    "nodemailer": "*",
+    "postmark": "*",
+    "smtp-server": "*"
   },
   "peerDependenciesMeta": {
     "@multi-agent-protocol/sdk": {
@@ -50,12 +55,32 @@
     },
     "agentic-mesh": {
       "optional": true
+    },
+    "mailauth": {
+      "optional": true
+    },
+    "mailparser": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    },
+    "postmark": {
+      "optional": true
+    },
+    "smtp-server": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
     "agentic-mesh": "^0.2.0",
+    "mailauth": "^4.6.6",
+    "mailparser": "^3.6.6",
+    "nodemailer": "^6.9.0",
+    "publint": "^0.3.21",
+    "smtp-server": "^3.13.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/renovate.json5

@@ -0,0 +1,6 @@
+{
+  // Dependency-update policy is shared across the swarm/openhive ecosystem.
+  // See github.com/alexngai/swarm-renovate-config.
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>alexngai/swarm-renovate-config"]
+}

package/rules/agent-inbox.md

@@ -60,6 +60,7 @@ read_thread({ threadTag: "deploy-v2" })
 - `"bob"` — local agent on this system
 - `"bob@system-2"` — agent on a federated remote system
 - `"@system-2"` — broadcast to all agents on a remote system
+- `"person@example.com"` — an external email address (only when email interop is enabled for that domain; otherwise the send is rejected). Replies from that person arrive back in your inbox like any other message, and threading is preserved.
 
 ## Discovering other agents
 

package/src/federation/connection-manager.ts

@@ -59,6 +59,8 @@ export class ConnectionManager {
   private meshConnector: MeshConnector | null;
   private meshPeer: MeshPeerLike | null;
   private onIncoming: IncomingMessageHandler | null;
+  /** Optional predicate marking recipients owned by the mail gateway (skipped). */
+  private mailFilter: ((agentId: string) => boolean) | null = null;
   readonly routing: RoutingEngine;
   readonly queue: DeliveryQueue;
   readonly trust: TrustManager;
@@ -110,6 +112,15 @@ export class ConnectionManager {
     return this.systemId;
   }
 
+  /**
+   * Register a predicate identifying recipients handled by the mail gateway.
+   * Those recipients are skipped by route() so a `bob@example.com` address is
+   * not mistaken for a federation peer.
+   */
+  setMailRecipientFilter(fn: (agentId: string) => boolean): void {
+    this.mailFilter = fn;
+  }
+
   /**
    * Establish federation with a peer. Uses MAP federation/connect protocol.
    * If an SDK class was injected, opens a real MAP connection to the peer.
@@ -264,6 +275,7 @@ export class ConnectionManager {
   async route(message: Message): Promise<DeliveryResult> {
     // Determine target for each recipient
     for (const recipient of message.recipients) {
+      if (this.mailFilter?.(recipient.agent_id)) continue; // handled by mail gateway
       const addr = parseAddress(recipient.agent_id);
       if (!isRemoteAddress(addr)) continue;
 

package/src/federation/delivery-queue.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
 import { ulid } from "ulid";
 import type { Message, DeliveryQueueConfig, QueuedMessage } from "../types.js";
+import type { QueueStore } from "./queue-store.js";
 
 const DEFAULT_CONFIG: DeliveryQueueConfig = {
   persistence: "memory",
@@ -16,19 +17,37 @@ const DEFAULT_CONFIG: DeliveryQueueConfig = {
 /**
  * Delivery queue for messages to offline or unreachable federation peers.
  *
- * Supports configurable TTL, overflow policy, and retry strategy.
- * Currently memory-only; SQLite persistence is a future enhancement.
+ * Supports configurable TTL, overflow policy, and retry strategy. Keeps an
+ * in-memory index for fast reads; when a durable QueueStore is supplied, every
+ * mutation is write-through journaled and the index is hydrated from the store
+ * on construction so queued messages survive a restart.
  */
 export class DeliveryQueue {
   private queues = new Map<string, QueuedMessage[]>();
   private config: DeliveryQueueConfig;
   private tickTimer?: ReturnType<typeof setInterval>;
+  private store: QueueStore | null;
 
   constructor(
     private events: EventEmitter,
-    config?: Partial<DeliveryQueueConfig>
+    config?: Partial<DeliveryQueueConfig>,
+    opts?: { store?: QueueStore }
   ) {
     this.config = { ...DEFAULT_CONFIG, ...config };
+    this.store = opts?.store ?? null;
+    if (this.store) this.hydrate(this.store);
+  }
+
+  /** Load persisted entries into the in-memory index (durable mode). */
+  private hydrate(store: QueueStore): void {
+    for (const entry of store.loadAll()) {
+      let queue = this.queues.get(entry.peerId);
+      if (!queue) {
+        queue = [];
+        this.queues.set(entry.peerId, queue);
+      }
+      queue.push(entry);
+    }
   }
 
   /**
@@ -44,9 +63,11 @@ export class DeliveryQueue {
     // Check queue size limit
     if (queue.length >= this.config.maxQueueSize) {
       switch (this.config.overflow) {
-        case "drop-oldest":
-          queue.shift();
+        case "drop-oldest": {
+          const dropped = queue.shift();
+          if (dropped) this.store?.remove(peerId, dropped.id);
           break;
+        }
         case "drop-newest":
           return null; // Don't enqueue
         case "reject-new":
@@ -65,6 +86,7 @@ export class DeliveryQueue {
     };
 
     queue.push(entry);
+    this.store?.upsert(entry);
     this.events.emit("queue.enqueued", { peerId, messageId: entry.id });
     return entry.id;
   }
@@ -79,6 +101,7 @@ export class DeliveryQueue {
 
     const messages = [...queue];
     this.queues.delete(peerId);
+    this.store?.removePeer(peerId);
     this.events.emit("queue.flushed", { peerId, count: messages.length });
     return messages;
   }
@@ -123,6 +146,7 @@ export class DeliveryQueue {
         ? this.config.retryBaseInterval * Math.pow(2, entry.attempts - 1)
         : this.config.retryBaseInterval;
     entry.nextRetry = new Date(Date.now() + delay).toISOString();
+    this.store?.upsert(entry);
     return true;
   }
 
@@ -137,6 +161,7 @@ export class DeliveryQueue {
     if (idx === -1) return false;
 
     queue.splice(idx, 1);
+    this.store?.remove(peerId, messageId);
     if (queue.length === 0) this.queues.delete(peerId);
     return true;
   }
@@ -150,10 +175,15 @@ export class DeliveryQueue {
 
     for (const [peerId, queue] of this.queues.entries()) {
       const before = queue.length;
-      const remaining = queue.filter((entry) => {
+      const remaining: QueuedMessage[] = [];
+      for (const entry of queue) {
         const age = now - new Date(entry.enqueuedAt).getTime();
-        return age < this.config.maxTTL;
-      });
+        if (age < this.config.maxTTL) {
+          remaining.push(entry);
+        } else {
+          this.store?.remove(peerId, entry.id);
+        }
+      }
       expired += before - remaining.length;
 
       if (remaining.length === 0) {

package/src/federation/queue-store.ts

@@ -0,0 +1,124 @@
+/**
+ * Durable persistence for the delivery queue.
+ *
+ * The DeliveryQueue keeps an in-memory index for fast reads and write-through
+ * journals every mutation to a QueueStore. On construction it hydrates the
+ * in-memory index from the store, so queued messages survive a restart.
+ *
+ * Two impls: the default in-memory behavior needs no store (pass none), and
+ * SqliteQueueStore backs durable mode (DeliveryQueueConfig.persistence = "sqlite").
+ */
+
+import type Database from "better-sqlite3";
+import type { QueuedMessage } from "../types.js";
+
+export interface QueueStore {
+  /** Insert or replace an entry. */
+  upsert(entry: QueuedMessage): void;
+  /** Remove a single entry by peer + message id. */
+  remove(peerId: string, messageId: string): void;
+  /** Remove all entries for a peer (e.g. on flush). */
+  removePeer(peerId: string): void;
+  /** Load all persisted entries (called once on hydrate). */
+  loadAll(): QueuedMessage[];
+}
+
+/** SQLite-backed durable queue store using a borrowed better-sqlite3 handle. */
+export class SqliteQueueStore implements QueueStore {
+  private table: string;
+  private upsertStmt: Database.Statement;
+  private removeStmt: Database.Statement;
+  private removePeerStmt: Database.Statement;
+  private loadStmt: Database.Statement;
+
+  /**
+   * @param db     A better-sqlite3 handle (lifecycle owned by the caller).
+   * @param prefix Table name prefix to match the Storage convention. Default "".
+   */
+  constructor(
+    private db: Database.Database,
+    prefix: string = ""
+  ) {
+    this.table = `${prefix}delivery_queue`;
+    this.migrate();
+    this.upsertStmt = this.db.prepare(
+      `INSERT INTO ${this.table}
+         (id, peer_id, message, enqueued_at, attempts, last_attempt, next_retry)
+       VALUES (@id, @peer_id, @message, @enqueued_at, @attempts, @last_attempt, @next_retry)
+       ON CONFLICT(id) DO UPDATE SET
+         peer_id = excluded.peer_id,
+         message = excluded.message,
+         enqueued_at = excluded.enqueued_at,
+         attempts = excluded.attempts,
+         last_attempt = excluded.last_attempt,
+         next_retry = excluded.next_retry`
+    );
+    this.removeStmt = this.db.prepare(
+      `DELETE FROM ${this.table} WHERE peer_id = ? AND id = ?`
+    );
+    this.removePeerStmt = this.db.prepare(
+      `DELETE FROM ${this.table} WHERE peer_id = ?`
+    );
+    this.loadStmt = this.db.prepare(
+      `SELECT id, peer_id, message, enqueued_at, attempts, last_attempt, next_retry
+         FROM ${this.table} ORDER BY enqueued_at ASC`
+    );
+  }
+
+  private migrate(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        id TEXT PRIMARY KEY,
+        peer_id TEXT NOT NULL,
+        message TEXT NOT NULL,
+        enqueued_at TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        last_attempt TEXT,
+        next_retry TEXT
+      );
+      CREATE INDEX IF NOT EXISTS ${this.table}_peer_idx
+        ON ${this.table}(peer_id);
+    `);
+  }
+
+  upsert(entry: QueuedMessage): void {
+    this.upsertStmt.run({
+      id: entry.id,
+      peer_id: entry.peerId,
+      message: JSON.stringify(entry.message),
+      enqueued_at: entry.enqueuedAt,
+      attempts: entry.attempts,
+      last_attempt: entry.lastAttempt ?? null,
+      next_retry: entry.nextRetry ?? null,
+    });
+  }
+
+  remove(peerId: string, messageId: string): void {
+    this.removeStmt.run(peerId, messageId);
+  }
+
+  removePeer(peerId: string): void {
+    this.removePeerStmt.run(peerId);
+  }
+
+  loadAll(): QueuedMessage[] {
+    const rows = this.loadStmt.all() as Array<{
+      id: string;
+      peer_id: string;
+      message: string;
+      enqueued_at: string;
+      attempts: number;
+      last_attempt: string | null;
+      next_retry: string | null;
+    }>;
+    return rows.map((r) => ({
+      id: r.id,
+      peerId: r.peer_id,
+      message: JSON.parse(r.message),
+      enqueuedAt: r.enqueued_at,
+      attempts: r.attempts,
+      lastAttempt: r.last_attempt ?? undefined,
+      nextRetry: r.next_retry ?? undefined,
+    }));
+  }
+}

package/src/index.ts

@@ -16,6 +16,14 @@ import { DeliveryBridge } from "./mesh/delivery-bridge.js";
 import type { MeshContextLike } from "./mesh/mesh-transport.js";
 import type { MeshPeerLike, MeshMapServer } from "./map/map-client.js";
 import { WarmRegistry } from "./registry/warm-registry.js";
+import { MailGateway } from "./mail/mail-gateway.js";
+import { SmtpTransport } from "./mail/smtp-transport.js";
+import { PostmarkTransport } from "./mail/provider-transport.js";
+import type { MailTransport } from "./mail/types.js";
+import { SqliteAttachmentStore } from "./mail/attachment-store.js";
+import { FsAttachmentStore } from "./mail/fs-attachment-store.js";
+import { SqliteQueueStore } from "./federation/queue-store.js";
+import { findDomainConflicts } from "./router/destination.js";
 import type { InboxConfig } from "./types.js";
 import type { Storage } from "./storage/interface.js";
 
@@ -62,6 +70,52 @@ export type { MeshDeliveryHandler } from "./mesh/delivery-bridge.js";
 export { mapMessageToInbox, inboxMessageToMap } from "./mesh/type-mapper.js";
 export type { MapMessage as MeshMapMessage, MapAddress as MeshMapAddress } from "./mesh/type-mapper.js";
 export type { MeshPeerLike, MeshAgentConnection, MeshMapServer } from "./map/map-client.js";
+// Mail interop
+export { MailGateway, RateLimitedError } from "./mail/mail-gateway.js";
+export type { MailGatewayConfig } from "./mail/mail-gateway.js";
+export { RateLimiter } from "./mail/rate-limiter.js";
+export { SmtpTransport, parseDsnFromParsed } from "./mail/smtp-transport.js";
+export type { SmtpTransportOptions } from "./mail/smtp-transport.js";
+export {
+  PostmarkTransport,
+  outboundToPostmark,
+  postmarkInboundToMail,
+  postmarkBounceToInbound,
+  postmarkResponseToResult,
+  postmarkErrorToResult,
+} from "./mail/provider-transport.js";
+export type {
+  PostmarkTransportOptions,
+  PostmarkClient,
+  PostmarkInbound,
+  PostmarkBounce,
+} from "./mail/provider-transport.js";
+export { AddressBook } from "./mail/address-book.js";
+export { SqliteAttachmentStore } from "./mail/attachment-store.js";
+export { FsAttachmentStore } from "./mail/fs-attachment-store.js";
+export {
+  inboundMailToMessage,
+  messageToOutboundMail,
+  UnknownRecipientError,
+} from "./mail/email-mapper.js";
+export {
+  classifyDestination,
+  UnknownDestinationError,
+  domainMatches,
+  findDomainConflicts,
+} from "./router/destination.js";
+export type { Destination, DestinationContext } from "./router/destination.js";
+export type {
+  MailTransport,
+  MailCapabilities,
+  OutboundMail,
+  InboundMail,
+  MailSendResult,
+  InboundBounce,
+  InboundAuthResults,
+  AttachmentStore,
+} from "./mail/types.js";
+export type { MailEgress } from "./router/message-router.js";
 export type * from "./types.js";
 export type { Storage, InboxQuery, ThreadQuery } from "./storage/interface.js";
 
@@ -103,6 +157,7 @@ export interface AgentInbox {
   notifier: PushNotifier;
   federation: ConnectionManager | null;
   registry: WarmRegistry | null;
+  mail: MailGateway | null;
   events: EventEmitter;
   stop(): Promise<void>;
 }
@@ -328,6 +383,97 @@ export async function createAgentInbox(
     federation.queue.startTicking();
   }
 
+  // 7b. Mail interop (inbound + outbound email)
+  let mail: MailGateway | null = null;
+  if (config.mail?.enabled) {
+    const mailConfig = config.mail;
+
+    // Surface domains claimed by both a federation peer and mail config —
+    // federation wins (see classifyDestination), but operators should know.
+    const mailDomains = [
+      ...mailConfig.identity.localDomains,
+      ...(mailConfig.routableDomains ?? []),
+    ];
+    const domainConflicts = findDomainConflicts({
+      isLocalAgent: () => false,
+      federationPeers: config.federation?.peers ?? [],
+      mailDomains,
+    });
+    if (domainConflicts.length > 0) {
+      events.emit("mail.config.conflict", {
+        kind: "domain",
+        conflicts: domainConflicts,
+      });
+      console.error(
+        `Mail config warning: domain(s) claimed by both federation and mail — federation wins: ${domainConflicts.join(", ")}`
+      );
+    }
+
+    // Durable queue + attachment storage when backed by SQLite.
+    const db =
+      storage instanceof SqliteStorage ? storage.getDatabase() : undefined;
+    const queueStore = db ? new SqliteQueueStore(db) : undefined;
+
+    // Attachment storage: filesystem (opt-in) or SQLite BLOBs (default).
+    let attachmentStore: SqliteAttachmentStore | FsAttachmentStore | undefined;
+    if (mailConfig.attachments?.backend === "fs") {
+      const dir =
+        mailConfig.attachments.dir ??
+        path.join(os.homedir(), ".claude", "agent-inbox", "attachments");
+      attachmentStore = new FsAttachmentStore(dir);
+    } else if (db) {
+      attachmentStore = new SqliteAttachmentStore(db);
+    }
+
+    const transport: MailTransport =
+      mailConfig.backend === "provider"
+        ? new PostmarkTransport({
+            serverToken: mailConfig.provider?.apiKeyRef,
+            webhook: mailConfig.provider?.webhookPath
+              ? { port: 0, inboundPath: mailConfig.provider.webhookPath }
+              : undefined,
+            attachmentStore,
+          })
+        : new SmtpTransport({
+            listenPort: mailConfig.smtp?.listenPort,
+            relay: mailConfig.smtp?.relay,
+            dkim: mailConfig.smtp?.dkim
+              ? {
+                  domainName: mailConfig.smtp.dkim.domain,
+                  keySelector: mailConfig.smtp.dkim.selector,
+                  privateKey: mailConfig.smtp.dkim.privateKeyRef,
+                }
+              : undefined,
+            attachmentStore,
+          });
+
+    mail = new MailGateway({
+      transport,
+      storage,
+      router,
+      events,
+      queueStore,
+      config: {
+        identity: mailConfig.identity,
+        routableDomains: mailConfig.routableDomains,
+        allowedSenderDomains: mailConfig.allowedSenderDomains,
+        rejectDmarcFail: mailConfig.rejectDmarcFail,
+        maxAttachments: mailConfig.maxAttachments,
+        rateLimit: mailConfig.rateLimit,
+        bounce: mailConfig.bounce,
+        defaultScope: config.scope,
+        queue: mailConfig.queue,
+      },
+    });
+
+    router.setMail(mail);
+    federation?.setMailRecipientFilter((id) => mail!.ownsRecipient(id));
+    await mail.start();
+    console.error(
+      `Mail interop enabled (${mailConfig.backend}) for domains: ${mailConfig.identity.localDomains.join(", ")}`
+    );
+  }
+
   // 8. JSON-RPC server (mail/* methods)
   const jsonRpc = new MailJsonRpcServer(storage, router, events);
   if (opts.httpPort && opts.httpPort > 0) {
@@ -363,6 +509,7 @@ export async function createAgentInbox(
     if (retentionTimer) clearInterval(retentionTimer);
     await ipcServer.stop();
     await jsonRpc.stopHttp();
+    if (mail) await mail.stop();
     await mapClient.disconnect();
     if (federation) await federation.destroy();
     if (registry) registry.destroy();
@@ -381,6 +528,7 @@ export async function createAgentInbox(
     notifier,
     federation,
     registry,
+    mail,
     events,
     stop,
   };

package/src/mail/address-book.ts

@@ -0,0 +1,111 @@
+/**
+ * Mail identity / address book.
+ *
+ * Maps between agent ids and external email addresses, and declares which
+ * domains we own (for inbound RCPT acceptance). Plus-addressing aware:
+ * `agent+scope@domain` resolves to agent `agent` in inbox scope `scope`.
+ *
+ * See docs/MAIL-INTEROP-PLAN.md §6.
+ */
+
+import type { MailIdentityConfig } from "../types.js";
+import type { MailAddress } from "./types.js";
+
+export interface ResolvedInbound {
+  agentId: string;
+  /** Inbox scope from plus-addressing, if present. */
+  scope?: string;
+}
+
+export class AddressBook {
+  private localDomains: string[];
+  /** lower-cased address → agentId */
+  private byAddress = new Map<string, string>();
+  /** agentId → canonical address */
+  private byAgent = new Map<string, string>();
+  private catchAllAgentId?: string;
+  /** Address mappings that collided (same address → multiple agents). */
+  readonly conflicts: string[] = [];
+
+  constructor(config: MailIdentityConfig) {
+    this.localDomains = config.localDomains.map((d) => d.toLowerCase());
+    this.catchAllAgentId = config.catchAllAgentId;
+    for (const { agentId, address } of config.mappings) {
+      const lower = address.toLowerCase();
+      const existing = this.byAddress.get(lower);
+      if (existing !== undefined && existing !== agentId) {
+        // Two agents mapped to the same address — inbound routing would be
+        // ambiguous. Keep the first and record the collision for surfacing.
+        this.conflicts.push(`${address} → ${existing} & ${agentId}`);
+        continue;
+      }
+      this.byAddress.set(lower, agentId);
+      // First mapping for an agent is its canonical from-address.
+      if (!this.byAgent.has(agentId)) this.byAgent.set(agentId, address);
+    }
+  }
+
+  /** Primary local domain — used to mint Message-IDs and default from-addresses. */
+  primaryDomain(): string {
+    return this.localDomains[0] ?? "localhost";
+  }
+
+  /** True if `domain` (or a parent of it) is one we receive mail for. */
+  ownsDomain(domain: string): boolean {
+    const d = domain.toLowerCase();
+    return this.localDomains.some(
+      (own) => d === own || d.endsWith(`.${own}`)
+    );
+  }
+
+  /**
+   * Resolve an inbound recipient email to a local agent (+ scope).
+   * Returns undefined if the domain is not ours, or the mailbox is unknown and
+   * no catch-all is configured.
+   */
+  resolveInbound(address: string): ResolvedInbound | undefined {
+    const parsed = splitAddress(address);
+    if (!parsed) return undefined;
+    const { local, domain } = parsed;
+
+    if (!this.ownsDomain(domain)) return undefined;
+
+    // Plus-addressing: agent+scope → base agent, scope.
+    const plusIdx = local.indexOf("+");
+    const base = plusIdx === -1 ? local : local.slice(0, plusIdx);
+    const scope = plusIdx === -1 ? undefined : local.slice(plusIdx + 1) || undefined;
+
+    const canonical = `${base}@${domain}`.toLowerCase();
+    const agentId = this.byAddress.get(canonical);
+    if (agentId) return { agentId, scope };
+
+    if (this.catchAllAgentId) return { agentId: this.catchAllAgentId, scope };
+    return undefined;
+  }
+
+  /**
+   * Resolve the from-address for an outbound sender agent. Falls back to
+   * `<agentId>@<primaryDomain>` when the agent has no explicit mapping.
+   */
+  resolveFrom(agentId: string): MailAddress {
+    const mapped = this.byAgent.get(agentId);
+    if (mapped) return { address: mapped };
+    return { address: `${agentId}@${this.primaryDomain()}` };
+  }
+}
+
+/** Split an addr-spec into local-part and domain. Returns undefined if malformed. */
+function splitAddress(
+  address: string
+): { local: string; domain: string } | undefined {
+  const at = address.indexOf("@");
+  if (at <= 0 || at !== address.lastIndexOf("@") || at === address.length - 1) {
+    // Reject empty local/domain and unquoted multiple "@" (e.g. "a@b@c"), so
+    // this layer agrees with parseAddress (which splits on the first "@").
+    return undefined;
+  }
+  const domain = address.slice(at + 1);
+  // A domain must not contain "/" (a federation scope separator) — defensive.
+  if (domain.includes("/")) return undefined;
+  return { local: address.slice(0, at), domain };
+}