@moxxy/plugin-channel-imessage 0.29.0

package/src/index.ts

@@ -0,0 +1,273 @@
+import { defineChannel, definePlugin, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { ImessageChannel, type ImessageChannelOptions } from './channel.js';
+import {
+  IMESSAGE_ALLOWED_HANDLES_KEY,
+  IMESSAGE_OWNER_HANDLES_KEY,
+  IMESSAGE_SERVER_PASSWORD_ENV,
+  IMESSAGE_SERVER_PASSWORD_KEY,
+  IMESSAGE_SERVER_URL_ENV,
+  IMESSAGE_SERVER_URL_KEY,
+  parseHandleList,
+} from './keys.js';
+import { runImessageWizard } from './setup-wizard.js';
+
+export {
+  ImessageChannel,
+  type ImessageChannelOptions,
+  type ImessageStartOpts,
+} from './channel.js';
+export { buildImessagePermissionResolver } from './permission.js';
+export {
+  BlueBubblesClient,
+  makeTempGuid,
+  type BlueBubblesClientLike,
+  type BlueBubblesClientOptions,
+  type SocketLike,
+} from './bluebubbles-client.js';
+export { gateInboundMessage, type GateState, type GateVerdict } from './message-gate.js';
+export { messageSchema, MAX_INBOUND_TEXT_CHARS, type ImessageMessage } from './schema.js';
+export {
+  ChunkedSender,
+  takeChunk,
+  splitForImessage,
+  IMESSAGE_CHUNK_SOFT_LIMIT,
+  IMESSAGE_CHUNK_HARD_LIMIT,
+} from './channel/chunker.js';
+export {
+  IMESSAGE_SERVER_URL_KEY,
+  IMESSAGE_SERVER_URL_ENV,
+  IMESSAGE_SERVER_PASSWORD_KEY,
+  IMESSAGE_SERVER_PASSWORD_ENV,
+  IMESSAGE_ALLOWED_HANDLES_KEY,
+  IMESSAGE_OWNER_HANDLES_KEY,
+  parseHandleList,
+  parseDmChatGuid,
+  normalizeHandle,
+  isHandle,
+  E164_RE,
+  EMAIL_RE,
+} from './keys.js';
+
+export interface BuildImessagePluginOptions {
+  /** Host-injected encrypted secret store (available immediately). */
+  readonly vault: VaultStore;
+}
+
+/**
+ * Build the iMessage channel plugin with a host-injected vault (mirrors the
+ * Signal/WhatsApp plugins' vault injection).
+ */
+export function buildImessagePlugin(opts: BuildImessagePluginOptions): Plugin {
+  return makeImessagePlugin(() => opts.vault);
+}
+
+/**
+ * Discovery-loadable default export: resolves the vault from the inter-plugin
+ * service registry in `onInit` (the vault plugin publishes `'vault'`). Requires
+ * `@moxxy/plugin-vault` to load first (declared in `package.json`
+ * `moxxy.requirements`).
+ */
+export const imessagePlugin: Plugin = (() => {
+  let resolved: VaultStore | null = null;
+  const getVault = (): VaultStore => {
+    if (!resolved) {
+      throw new Error(
+        '@moxxy/plugin-channel-imessage: the "vault" service is unavailable — @moxxy/plugin-vault must load first',
+      );
+    }
+    return resolved;
+  };
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      resolved = ctx.services.require<VaultStore>('vault');
+    },
+  };
+  return makeImessagePlugin(getVault, hooks);
+})();
+
+export default imessagePlugin;
+
+function readStringArray(value: unknown): string[] | undefined {
+  if (Array.isArray(value)) return value.map((x) => String(x));
+  if (typeof value === 'string' && value.trim()) {
+    return value
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+  return undefined;
+}
+
+function envConfigured(): boolean {
+  const url = process.env[IMESSAGE_SERVER_URL_ENV];
+  const pass = process.env[IMESSAGE_SERVER_PASSWORD_ENV];
+  return typeof url === 'string' && url.trim().length > 0 && typeof pass === 'string' && pass.trim().length > 0;
+}
+
+function makeImessagePlugin(getVault: () => VaultStore, hooks?: LifecycleHooks): Plugin {
+  return definePlugin({
+    name: '@moxxy/plugin-channel-imessage',
+    version: '0.0.0',
+    ...(hooks ? { hooks } : {}),
+    channels: [
+      defineChannel({
+        name: 'imessage',
+        description:
+          'iMessage channel via a localhost BlueBubbles server (macOS only). Allow-listed handles (and your own self-chat) drive the agent; replies go out as buffered chunked sends.',
+        // A BlueBubbles server sees ALL the account owner's messages, so this
+        // channel runs on its own dedicated, isolated runner (separate socket +
+        // sticky session), like Signal — it keeps its own persistent history
+        // apart from the user's desktop/TUI work.
+        dedicatedRunner: true,
+        sessionSource: 'imessage',
+        config: {
+          fields: [
+            {
+              name: 'serverUrl',
+              label: 'BlueBubbles server URL',
+              vaultKey: IMESSAGE_SERVER_URL_KEY,
+              required: true,
+              secret: false,
+              placeholder: 'http://localhost:1234',
+              help: 'The BlueBubbles server running on this Mac (default port 1234)',
+            },
+            {
+              name: 'password',
+              label: 'BlueBubbles server password',
+              vaultKey: IMESSAGE_SERVER_PASSWORD_KEY,
+              required: true,
+              secret: true,
+              help: 'The password set in the BlueBubbles app (sent as a query param on every request)',
+            },
+          ],
+          hasRequestUrl: false,
+          runHint:
+            'Install the BlueBubbles server on this Mac, sign in to Messages, set a password, then run `moxxy channels imessage setup` to add allowed handles.',
+          connect: {
+            kind: 'instructions',
+            title: 'Connect BlueBubbles',
+            steps: [
+              'Install the BlueBubbles server on this Mac from https://bluebubbles.app and sign in to Messages.',
+              'In the BlueBubbles app, set a server password and note the port (default 1234).',
+              'Run `moxxy channels imessage setup` and paste the URL + password, then add the handles allowed to talk to moxxy.',
+            ],
+          },
+        },
+        create: (deps) => {
+          const options = deps.options;
+          const channelOpts: ImessageChannelOptions = {
+            vault: getVault(),
+            ...(typeof options?.['serverUrl'] === 'string' ? { serverUrl: options['serverUrl'] } : {}),
+            ...(typeof options?.['password'] === 'string' ? { password: options['password'] } : {}),
+            ...(() => {
+              const tools = readStringArray(options?.['allowedTools']);
+              return tools ? { allowedTools: tools } : {};
+            })(),
+            ...(() => {
+              const handles = readStringArray(options?.['allowedHandles']);
+              return handles ? { allowedHandles: handles } : {};
+            })(),
+            ...(() => {
+              const handles = readStringArray(options?.['ownerHandles']);
+              return handles ? { ownerHandles: handles } : {};
+            })(),
+            logger: deps.logger as never,
+          };
+          return new ImessageChannel(channelOpts);
+        },
+        isAvailable: async () => {
+          // Pure check — NO network probe (this runs on every `moxxy channels
+          // list` / `moxxy doctor`). The reachability ping is deferred to start().
+          if (process.platform !== 'darwin') {
+            return {
+              ok: false,
+              reason: 'iMessage requires macOS (a BlueBubbles server running on this Mac).',
+            };
+          }
+          // Env pair short-circuit (the vault may not be wired in a probe context).
+          if (envConfigured()) return { ok: true };
+          try {
+            const vault = getVault();
+            if ((await vault.has(IMESSAGE_SERVER_URL_KEY)) && (await vault.has(IMESSAGE_SERVER_PASSWORD_KEY))) {
+              return { ok: true };
+            }
+          } catch {
+            /* vault unavailable in a probe context — fall through */
+          }
+          return {
+            ok: false,
+            reason: 'No BlueBubbles server configured. Run `moxxy channels imessage setup`.',
+          };
+        },
+        interactiveCommand: 'setup',
+        subcommands: {
+          setup: {
+            description:
+              'Interactive setup: store the BlueBubbles server URL + password, the handle allow-list and your own self-chat handles, pick the tool allow-list, then start. Shown by default for `moxxy imessage` on a TTY.',
+            run: async (ctx) => {
+              if (process.stdin.isTTY !== true) {
+                // Headless: just start the channel (server must already be configured).
+                return ctx.startChannel();
+              }
+              return runImessageWizard(ctx);
+            },
+          },
+          status: {
+            description: 'Report platform / server-config / allow-list state as JSON.',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const serverUrl =
+                process.env[IMESSAGE_SERVER_URL_ENV]?.trim() || (await vault.get(IMESSAGE_SERVER_URL_KEY));
+              const passwordSet =
+                (process.env[IMESSAGE_SERVER_PASSWORD_ENV]?.trim() ?? '').length > 0 ||
+                (await vault.has(IMESSAGE_SERVER_PASSWORD_KEY));
+              const allowedHandles = parseHandleList(await vault.get(IMESSAGE_ALLOWED_HANDLES_KEY));
+              const ownerHandles = parseHandleList(await vault.get(IMESSAGE_OWNER_HANDLES_KEY));
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    platform: process.platform,
+                    supported: process.platform === 'darwin',
+                    serverUrl: serverUrl || null,
+                    passwordSet,
+                    allowedHandles,
+                    ownerHandles,
+                  },
+                  null,
+                  2,
+                ) + '\n',
+              );
+              return 0;
+            },
+          },
+          unpair: {
+            description:
+              'Forget the stored BlueBubbles server URL + password and the handle allow-list. (The BlueBubbles app itself is untouched — uninstall or reset it there to fully disconnect.)',
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const removedUrl = await vault.delete(IMESSAGE_SERVER_URL_KEY);
+              await vault.delete(IMESSAGE_SERVER_PASSWORD_KEY);
+              await vault.delete(IMESSAGE_ALLOWED_HANDLES_KEY);
+              await vault.delete(IMESSAGE_OWNER_HANDLES_KEY);
+              process.stdout.write(
+                removedUrl
+                  ? 'unpaired (vault cleared). The BlueBubbles server app is untouched — reset it there to fully disconnect.\n'
+                  : 'no BlueBubbles server was configured\n',
+              );
+              return 0;
+            },
+          },
+        },
+      }),
+    ],
+  });
+}

package/src/keys.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import {
+  E164_RE,
+  EMAIL_RE,
+  isHandle,
+  normalizeHandle,
+  parseDmChatGuid,
+  parseHandleList,
+} from './keys.js';
+
+describe('handle shapes', () => {
+  it('E164_RE accepts plausible numbers and rejects junk', () => {
+    expect(E164_RE.test('+15551234567')).toBe(true);
+    expect(E164_RE.test('+4915771234567')).toBe(true);
+    expect(E164_RE.test('15551234567')).toBe(false);
+    expect(E164_RE.test('+0155')).toBe(false);
+    expect(E164_RE.test('')).toBe(false);
+  });
+
+  it('EMAIL_RE accepts Apple-ID emails and rejects junk', () => {
+    expect(EMAIL_RE.test('friend@icloud.com')).toBe(true);
+    expect(EMAIL_RE.test('a.b+c@example.co.uk')).toBe(true);
+    expect(EMAIL_RE.test('not-an-email')).toBe(false);
+    expect(EMAIL_RE.test('two @spaces.com')).toBe(false);
+  });
+
+  it('isHandle recognises numbers and emails only', () => {
+    expect(isHandle('+15551234567')).toBe(true);
+    expect(isHandle('friend@icloud.com')).toBe(true);
+    expect(isHandle('bob')).toBe(false);
+    expect(isHandle('../../etc/passwd')).toBe(false);
+  });
+});
+
+describe('normalizeHandle', () => {
+  it('lowercases emails but preserves numbers', () => {
+    expect(normalizeHandle(' +15551234567 ')).toBe('+15551234567');
+    expect(normalizeHandle('  Friend@ICloud.com ')).toBe('friend@icloud.com');
+  });
+});
+
+describe('parseHandleList', () => {
+  it('parses a JSON array of numbers/emails', () => {
+    const raw = JSON.stringify(['+15551234567', 'Friend@iCloud.com']);
+    expect(parseHandleList(raw)).toEqual(['+15551234567', 'friend@icloud.com']);
+  });
+
+  it('fails closed on missing or corrupt values', () => {
+    expect(parseHandleList(null)).toEqual([]);
+    expect(parseHandleList(undefined)).toEqual([]);
+    expect(parseHandleList('')).toEqual([]);
+    expect(parseHandleList('not json')).toEqual([]);
+    expect(parseHandleList('"a string"')).toEqual([]);
+    expect(parseHandleList('{"a":1}')).toEqual([]);
+  });
+
+  it('drops entries that are neither E.164 nor email, and de-dupes', () => {
+    const raw = JSON.stringify(['+15551234567', 'bob', 42, '../../etc/passwd', '+15551234567']);
+    expect(parseHandleList(raw)).toEqual(['+15551234567']);
+  });
+});
+
+describe('parseDmChatGuid', () => {
+  it('parses a 1:1 chat guid', () => {
+    expect(parseDmChatGuid('iMessage;-;+15551234567')).toEqual({
+      service: 'iMessage',
+      handle: '+15551234567',
+    });
+    expect(parseDmChatGuid('SMS;-;Friend@iCloud.com')).toEqual({
+      service: 'SMS',
+      handle: 'friend@icloud.com',
+    });
+  });
+
+  it('rejects group guids (v1 is DM-only)', () => {
+    expect(parseDmChatGuid('iMessage;+;chat1234567890')).toBeNull();
+  });
+
+  it('rejects malformed / non-handle guids', () => {
+    expect(parseDmChatGuid(null)).toBeNull();
+    expect(parseDmChatGuid('')).toBeNull();
+    expect(parseDmChatGuid('iMessage;-;')).toBeNull();
+    expect(parseDmChatGuid('iMessage;-;not-a-handle')).toBeNull();
+    expect(parseDmChatGuid('iMessage;-;+1;extra')).toBeNull();
+  });
+});

package/src/keys.ts

@@ -0,0 +1,109 @@
+/**
+ * Vault keys + pure handle helpers shared by the channel, its subcommands, and
+ * the interactive setup wizard. Kept in their own module (the signal/whatsapp
+ * `keys.ts` pattern) so wizard helpers can import them without pulling in the
+ * plugin's full index (or, worse, socket.io-client — which stays behind a lazy
+ * import in `bluebubbles-client.ts`).
+ *
+ * Note on custody: the BlueBubbles server (a native macOS app) holds the actual
+ * iMessage identity + message store. The moxxy vault only stores the localhost
+ * server URL, its password, and two JSON handle arrays — the allow-list of OTHER
+ * people who may drive the agent, and the owner's own handle(s) that enable
+ * texting moxxy from your own devices (the "self-chat").
+ */
+
+/** Vault key for the BlueBubbles server URL (e.g. http://localhost:1234). */
+export const IMESSAGE_SERVER_URL_KEY = 'imessage_server_url';
+/** Env override for the server URL — beats the vault (shared precedence). */
+export const IMESSAGE_SERVER_URL_ENV = 'MOXXY_IMESSAGE_SERVER_URL';
+/** Vault key for the BlueBubbles server password. */
+export const IMESSAGE_SERVER_PASSWORD_KEY = 'imessage_server_password';
+/** Env override for the server password — beats the vault. */
+export const IMESSAGE_SERVER_PASSWORD_ENV = 'MOXXY_IMESSAGE_SERVER_PASSWORD';
+/**
+ * Vault key for the allow-list: a JSON array of iMessage handles (E.164 phone
+ * numbers and/or Apple-ID emails) that OTHER people may use to drive the
+ * session. The owner's own handle is NOT listed here — it lives in
+ * {@link IMESSAGE_OWNER_HANDLES_KEY} so an inbound from a friend and an outbound
+ * from the owner stay distinguishable (never react to the owner's private
+ * conversations with allow-listed friends).
+ */
+export const IMESSAGE_ALLOWED_HANDLES_KEY = 'imessage_allowed_handles';
+/**
+ * Vault key for the owner's OWN handle(s): a JSON array of the account owner's
+ * E.164 numbers / Apple-ID emails. A message the account itself sent
+ * (`isFromMe`) drives a turn only when it lands in a 1:1 chat with one of these
+ * handles — i.e. the owner texting their own "self-chat" from any Apple device.
+ * Empty (the default) means self-chat is off and every `isFromMe` message is
+ * dropped (fail closed); the friend allow-list path is unaffected.
+ */
+export const IMESSAGE_OWNER_HANDLES_KEY = 'imessage_owner_handles';
+
+/** E.164 shape: `+` then 7–15 digits, no leading zero. */
+export const E164_RE = /^\+[1-9]\d{6,14}$/;
+
+/** Pragmatic email shape (Apple-ID handles). Deliberately loose but anchored. */
+export const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Whether a normalized string is a plausible iMessage handle. */
+export function isHandle(value: string): boolean {
+  return E164_RE.test(value) || EMAIL_RE.test(value);
+}
+
+/**
+ * Canonical handle for allow-list comparisons: trimmed, and lowercased when it
+ * is an email (Apple-ID handles are case-insensitive). Phone numbers are left
+ * as-is (they are already digits + `+`).
+ */
+export function normalizeHandle(raw: string): string {
+  const trimmed = raw.trim();
+  return trimmed.includes('@') ? trimmed.toLowerCase() : trimmed;
+}
+
+/**
+ * Parse a stored handle list. Returns `[]` for a missing OR corrupt value
+ * rather than throwing — a corrupt vault entry must degrade to "nobody extra is
+ * allowed" (fail closed), never crash the channel or silently allow. Non-string
+ * entries and entries that are neither an E.164 number nor an email are dropped.
+ */
+export function parseHandleList(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const out = new Set<string>();
+  for (const entry of parsed) {
+    if (typeof entry !== 'string') continue;
+    const handle = normalizeHandle(entry);
+    if (isHandle(handle)) out.add(handle);
+  }
+  return [...out];
+}
+
+/**
+ * Parse the chat GUID BlueBubbles stamps on every message
+ * (`SERVICE;TYPE;IDENTIFIER`, e.g. `iMessage;-;+15551234567`). TYPE is `-` for a
+ * 1:1 chat and `+` for a group. Returns null for anything that is not a
+ * well-formed 1:1 GUID (groups included) so callers treat it as "not a DM" and
+ * drop it (v1 is direct-message only).
+ */
+export function parseDmChatGuid(
+  guid: string | null | undefined,
+): { readonly service: string; readonly handle: string } | null {
+  if (typeof guid !== 'string') return null;
+  const parts = guid.split(';');
+  if (parts.length !== 3) return null;
+  const [rawService, rawType, rawIdentifier] = parts;
+  if (rawService === undefined || rawType === undefined || rawIdentifier === undefined) return null;
+  const service = rawService.trim();
+  const type = rawType.trim();
+  const identifier = rawIdentifier.trim();
+  if (service.length === 0 || type !== '-' || identifier.length === 0) return null;
+  const handle = normalizeHandle(identifier);
+  if (!isHandle(handle)) return null;
+  return { service, handle };
+}

package/src/message-gate.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { gateInboundMessage, type GateState } from './message-gate.js';
+import { MAX_INBOUND_TEXT_CHARS } from './schema.js';
+
+const OWNER = '+19998887777';
+const FRIEND = '+15550001111';
+const STRANGER = '+14440002222';
+
+const chatFor = (handle: string): string => `iMessage;-;${handle}`;
+
+function state(overrides: Partial<GateState> = {}): GateState {
+  return {
+    ownerHandles: new Set([OWNER]),
+    allowedHandles: new Set([FRIEND]),
+    isOwnSend: () => false,
+    ...overrides,
+  };
+}
+
+function msg(opts: {
+  chatGuid: string;
+  text?: string | null;
+  isFromMe?: boolean;
+  sender?: string;
+  guid?: string;
+  tempGuid?: string;
+}): Record<string, unknown> {
+  return {
+    guid: opts.guid ?? 'msg-1',
+    ...(opts.tempGuid ? { tempGuid: opts.tempGuid } : {}),
+    text: opts.text ?? 'hi',
+    isFromMe: opts.isFromMe ?? false,
+    ...(opts.sender ? { handle: { address: opts.sender } } : {}),
+    chats: [{ guid: opts.chatGuid }],
+  };
+}
+
+describe('gateInboundMessage', () => {
+  it('accepts an allow-listed sender text message and targets their chat', () => {
+    const v = gateInboundMessage(state(), msg({ chatGuid: chatFor(FRIEND), text: 'hi there', sender: FRIEND }));
+    expect(v).toEqual({ ok: true, chatGuid: chatFor(FRIEND), text: 'hi there' });
+  });
+
+  it("accepts the owner's own self-chat message (isFromMe in an owner chat)", () => {
+    const v = gateInboundMessage(state(), msg({ chatGuid: chatFor(OWNER), text: 'note to self', isFromMe: true }));
+    expect(v).toEqual({ ok: true, chatGuid: chatFor(OWNER), text: 'note to self' });
+  });
+
+  it('drops an isFromMe message in a FOREIGN chat (owner talking to others)', () => {
+    const v = gateInboundMessage(state(), msg({ chatGuid: chatFor(FRIEND), isFromMe: true }));
+    expect(v).toEqual({ ok: false, reason: 'own message in a foreign chat' });
+  });
+
+  it("drops the bot's OWN outbound echo by guid (loop protection)", () => {
+    const st = state({ isOwnSend: (id) => id === 'echo-guid' });
+    const v = gateInboundMessage(
+      st,
+      msg({ chatGuid: chatFor(OWNER), isFromMe: true, guid: 'echo-guid' }),
+    );
+    expect(v).toEqual({ ok: false, reason: 'own outbound echo (guid)' });
+  });
+
+  it("drops the bot's OWN outbound echo by tempGuid", () => {
+    const st = state({ isOwnSend: (id) => id === 'temp-xyz' });
+    const v = gateInboundMessage(
+      st,
+      msg({ chatGuid: chatFor(FRIEND), sender: FRIEND, guid: 'g2', tempGuid: 'temp-xyz' }),
+    );
+    expect(v).toEqual({ ok: false, reason: 'own outbound echo (tempGuid)' });
+  });
+
+  it('drops an un-allow-listed sender (silent — no reply)', () => {
+    const v = gateInboundMessage(state(), msg({ chatGuid: chatFor(STRANGER), sender: STRANGER }));
+    expect(v).toEqual({ ok: false, reason: 'sender not allow-listed' });
+  });
+
+  it('drops group messages (v1 is direct-message only)', () => {
+    const v = gateInboundMessage(state(), msg({ chatGuid: 'iMessage;+;chat123', sender: FRIEND }));
+    expect(v).toEqual({ ok: false, reason: 'not a 1:1 direct message' });
+  });
+
+  it('resolves the sender from the chat guid when the message has no handle', () => {
+    const v = gateInboundMessage(state(), msg({ chatGuid: chatFor(FRIEND) }));
+    expect(v).toEqual({ ok: true, chatGuid: chatFor(FRIEND), text: 'hi' });
+  });
+
+  it('drops self-chat when no owner handles are configured (fail closed)', () => {
+    const v = gateInboundMessage(
+      state({ ownerHandles: new Set() }),
+      msg({ chatGuid: chatFor(OWNER), isFromMe: true }),
+    );
+    expect(v).toEqual({ ok: false, reason: 'own message in a foreign chat' });
+  });
+
+  it('drops schema-invalid payloads without throwing', () => {
+    expect(gateInboundMessage(state(), null)).toEqual({ ok: false, reason: 'invalid message shape' });
+    expect(gateInboundMessage(state(), 'garbage')).toEqual({
+      ok: false,
+      reason: 'invalid message shape',
+    });
+    expect(gateInboundMessage(state(), { text: 'no guid', chats: [] })).toEqual({
+      ok: false,
+      reason: 'invalid message shape',
+    });
+  });
+
+  it('drops a message with no chat', () => {
+    expect(gateInboundMessage(state(), { guid: 'm', text: 'x' })).toEqual({
+      ok: false,
+      reason: 'message without a chat',
+    });
+  });
+
+  it('rejects oversized text at the schema boundary', () => {
+    const v = gateInboundMessage(
+      state(),
+      msg({ chatGuid: chatFor(FRIEND), sender: FRIEND, text: 'a'.repeat(MAX_INBOUND_TEXT_CHARS + 1) }),
+    );
+    expect(v).toEqual({ ok: false, reason: 'invalid message shape' });
+  });
+
+  it('drops empty / whitespace-only text', () => {
+    const v = gateInboundMessage(state(), msg({ chatGuid: chatFor(FRIEND), sender: FRIEND, text: '   ' }));
+    expect(v).toEqual({ ok: false, reason: 'no message text' });
+  });
+});

package/src/message-gate.ts

@@ -0,0 +1,94 @@
+import { normalizeHandle, parseDmChatGuid } from './keys.js';
+import { messageSchema } from './schema.js';
+
+/**
+ * The single inbound gate every session-reaching path goes through (AGENTS.md:
+ * gate EVERY session-reaching path behind pairing; A8: zod-validate inbound
+ * before it touches the session). Pure — the channel feeds it the raw
+ * BlueBubbles `new-message` payload plus its identity/allow-list state and
+ * branches on the verdict.
+ *
+ * Order of checks (each is load-bearing, mirroring the WhatsApp gate):
+ *  1. shape-validate + size-cap the consumed fields (zod).
+ *  2. drop own echoes: BlueBubbles emits `new-message` for the account's OWN
+ *     sends too (our replies come back `isFromMe`), so without the sent-id check
+ *     the bot would answer itself in a loop — and a self-chat reply would be
+ *     mistaken for a fresh owner prompt.
+ *  3. direct messages only (v1): a group chat GUID is dropped — group fan-in
+ *     needs its own trust story.
+ *  4. drop `isFromMe` messages outside the owner's self-chat: those are the
+ *     owner talking to OTHER people from an Apple device — never a prompt. Only
+ *     `isFromMe` in a 1:1 chat with one of the owner's own handles drives a turn.
+ *  5. allow-list by normalized handle for inbound (non-`isFromMe`) messages.
+ *     Unauthorized senders are dropped SILENTLY — replying would leak the bot's
+ *     existence.
+ */
+
+export type GateVerdict =
+  | { readonly ok: false; readonly reason: string }
+  | { readonly ok: true; readonly chatGuid: string; readonly text: string };
+
+export interface GateState {
+  /** The owner's own normalized handle(s) — the self-chat identities. */
+  readonly ownerHandles: ReadonlySet<string>;
+  /** Normalized handles of OTHER people allowed to drive the session. */
+  readonly allowedHandles: ReadonlySet<string>;
+  /** True for a guid/tempGuid of THIS channel's own recent send (echo/loop protection). */
+  readonly isOwnSend: (id: string) => boolean;
+}
+
+export function gateInboundMessage(state: GateState, raw: unknown): GateVerdict {
+  const parsed = messageSchema.safeParse(raw);
+  if (!parsed.success) return drop('invalid message shape');
+  const message = parsed.data;
+
+  const chats = message.chats;
+  const firstChat = chats && chats.length > 0 ? chats[0] : undefined;
+  if (!firstChat) return drop('message without a chat');
+  const chatGuid = firstChat.guid;
+
+  // Own-echo drop FIRST — a reply we sent into a self-chat comes back isFromMe
+  // and would otherwise re-enter as an owner prompt (loop).
+  if (state.isOwnSend(message.guid)) return drop('own outbound echo (guid)');
+  const tempGuid = message.tempGuid;
+  if (tempGuid && state.isOwnSend(tempGuid)) return drop('own outbound echo (tempGuid)');
+
+  const dm = parseDmChatGuid(chatGuid);
+  if (!dm) return drop('not a 1:1 direct message');
+
+  if (message.isFromMe === true) {
+    // Same-account messages: only the owner's own self-chat is a prompt surface.
+    if (!state.ownerHandles.has(dm.handle)) {
+      return drop('own message in a foreign chat');
+    }
+  } else {
+    const senderHandle = resolveSender(message.handle, dm.handle);
+    if (!state.allowedHandles.has(senderHandle)) {
+      return drop('sender not allow-listed');
+    }
+  }
+
+  const text = typeof message.text === 'string' ? message.text.trim() : '';
+  if (text.length === 0) return drop('no message text');
+
+  return { ok: true, chatGuid, text };
+}
+
+/**
+ * The sender's handle for an inbound message: the message's own `handle`
+ * address when present, else the 1:1 chat's counterpart (they are the same
+ * party in a DM). Narrowed once, then plain access — no optional-chain depth.
+ */
+function resolveSender(
+  handle: { readonly address?: string | null } | null | undefined,
+  chatHandle: string,
+): string {
+  if (handle && typeof handle.address === 'string' && handle.address.length > 0) {
+    return normalizeHandle(handle.address);
+  }
+  return chatHandle;
+}
+
+function drop(reason: string): GateVerdict {
+  return { ok: false, reason };
+}