@moxxy/plugin-channel-imessage 0.29.0

package/src/permission.ts

@@ -0,0 +1,40 @@
+import { createAuditedAllowListResolver } from '@moxxy/channel-kit';
+import type { PermissionResolver } from '@moxxy/sdk';
+
+export interface ImessagePermissionLogger {
+  info?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+/**
+ * Build the iMessage channel's autonomous permission resolver.
+ *
+ * Like Signal and Slack (and unlike Telegram's inline-keyboard prompts), the
+ * iMessage channel runs hands-off: the operator declares trust upfront via
+ * `channels.imessage.allowedTools`, and any tool NOT in that list is denied.
+ * The trust check + `'*'` expansion + audit-on-auto-approve wiring is the shared
+ * {@link createAuditedAllowListResolver} from `@moxxy/channel-kit`; this wrapper
+ * binds it to the channel logger so every auto-approved call leaves a trail. An
+ * empty list denies everything (effectively read-only).
+ *
+ * Because this resolver decides synchronously (no deferred operator prompt), it
+ * has no pending-prompt state, so `stop()` has nothing to `abortAll` — aborting
+ * the in-flight turn is enough.
+ */
+export function buildImessagePermissionResolver(opts: {
+  allowedTools: ReadonlyArray<string>;
+  allToolNames: ReadonlyArray<string>;
+  logger?: ImessagePermissionLogger;
+}): PermissionResolver {
+  return createAuditedAllowListResolver({
+    name: 'imessage-allow-list',
+    allowedTools: opts.allowedTools,
+    allToolNames: opts.allToolNames,
+    onAutoApprove: (call, { wildcard }) => {
+      opts.logger?.info?.('imessage: auto-approved tool call', {
+        tool: call.name,
+        callId: call.callId,
+        wildcard,
+      });
+    },
+  });
+}

package/src/schema.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { MAX_INBOUND_TEXT_CHARS, messageSchema } from './schema.js';
+
+describe('messageSchema', () => {
+  it('accepts a well-formed new-message payload', () => {
+    const parsed = messageSchema.safeParse({
+      guid: 'msg-1',
+      tempGuid: 'temp-abc',
+      text: 'hello',
+      isFromMe: false,
+      handle: { address: '+15551234567' },
+      chats: [{ guid: 'iMessage;-;+15551234567' }],
+      dateCreated: 1_700_000_000_000,
+      // an un-modeled extra passes through untouched
+      subject: null,
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      expect(parsed.data.guid).toBe('msg-1');
+      expect(parsed.data.text).toBe('hello');
+    }
+  });
+
+  it('rejects a payload with no guid', () => {
+    expect(messageSchema.safeParse({ text: 'hi', chats: [] }).success).toBe(false);
+  });
+
+  it('rejects non-object payloads', () => {
+    expect(messageSchema.safeParse(null).success).toBe(false);
+    expect(messageSchema.safeParse('garbage').success).toBe(false);
+    expect(messageSchema.safeParse(42).success).toBe(false);
+  });
+
+  it('rejects a numeric text (wrong type)', () => {
+    expect(messageSchema.safeParse({ guid: 'm', text: 42 }).success).toBe(false);
+  });
+
+  it('rejects oversized text', () => {
+    const parsed = messageSchema.safeParse({
+      guid: 'm',
+      text: 'a'.repeat(MAX_INBOUND_TEXT_CHARS + 1),
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects a chat entry without a guid', () => {
+    expect(messageSchema.safeParse({ guid: 'm', chats: [{ chatIdentifier: 'x' }] }).success).toBe(
+      false,
+    );
+  });
+});

package/src/schema.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+/**
+ * Zod validation for the BlueBubbles socket.io `new-message` payload — a
+ * serialized Message object. Every inbound message is validated + size-capped
+ * BEFORE any field reaches the session (channel invariant A8). Only the fields
+ * the channel consumes are typed; unknown extras pass through untouched so a
+ * newer BlueBubbles server doesn't fail validation, but nothing un-modeled is
+ * ever read.
+ */
+
+/** Cap on inbound prompt text we will forward to the model. */
+export const MAX_INBOUND_TEXT_CHARS = 16_000;
+
+/** A single participant handle on a chat / message (`{ address, ... }`). */
+export const handleSchema = z
+  .object({
+    address: z.string().min(1).max(256).nullable().optional(),
+  })
+  .passthrough();
+
+/** A chat the message belongs to. `guid` is `SERVICE;TYPE;IDENTIFIER`. */
+export const chatSchema = z
+  .object({
+    guid: z.string().min(1).max(256),
+  })
+  .passthrough();
+
+/**
+ * The serialized Message. `guid` is the stable per-message id (used for the
+ * anti-echo drop); `tempGuid` echoes back the value the sender chose for an
+ * apple-script send, so our own replies can be recognised even before their
+ * permanent guid is known.
+ */
+export const messageSchema = z
+  .object({
+    guid: z.string().min(1).max(256),
+    tempGuid: z.string().min(1).max(256).nullable().optional(),
+    text: z.string().max(MAX_INBOUND_TEXT_CHARS).nullable().optional(),
+    isFromMe: z.boolean().nullable().optional(),
+    handle: handleSchema.nullable().optional(),
+    chats: z.array(chatSchema).max(16).optional(),
+    dateCreated: z.number().nullable().optional(),
+  })
+  .passthrough();
+
+export type ImessageMessage = z.infer<typeof messageSchema>;

package/src/setup-wizard.ts

@@ -0,0 +1,155 @@
+import { cancel, intro, isCancel, log, note, outro, password, text } from '@clack/prompts';
+import type { ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import {
+  IMESSAGE_ALLOWED_HANDLES_KEY,
+  IMESSAGE_OWNER_HANDLES_KEY,
+  IMESSAGE_SERVER_PASSWORD_KEY,
+  IMESSAGE_SERVER_URL_KEY,
+  isHandle,
+  normalizeHandle,
+  parseHandleList,
+} from './keys.js';
+import { BlueBubblesClient } from './bluebubbles-client.js';
+
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const bold = (s: string): string => (ANSI ? `\x1b[1m${s}\x1b[22m` : s);
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+/**
+ * Interactive iMessage (BlueBubbles) setup wizard (the channel's
+ * `interactiveCommand`).
+ *
+ * Walks the operator through:
+ *   1. the BlueBubbles server URL + password (stored in the vault),
+ *   2. a best-effort reachability check against that server,
+ *   3. the handle allow-list — who besides yourself may talk to the agent,
+ *   4. your own handle(s), so texting your own "self-chat" reaches moxxy,
+ *   5. the autonomous tool allow-list,
+ * then starts the channel.
+ */
+export async function runImessageWizard(ctx: ChannelSubcommandContext): Promise<number> {
+  const vault = ctx.deps.vault as VaultStore;
+  intro(bold('moxxy imessage setup'));
+
+  note(
+    'moxxy talks to iMessage through a BlueBubbles server running on THIS Mac.\n' +
+      'Install it from https://bluebubbles.app, sign in to Messages, and set a\n' +
+      'server password. This channel uses the stock apple-script send method — no\n' +
+      'SIP changes or Private API needed. v1 handles 1:1 text chats only.',
+    'how the iMessage channel works',
+  );
+
+  const existingUrl = await vault.get(IMESSAGE_SERVER_URL_KEY);
+  const serverUrl = await text({
+    message: 'BlueBubbles server URL',
+    placeholder: 'http://localhost:1234',
+    initialValue: existingUrl ?? 'http://localhost:1234',
+    validate: (v) => {
+      if (!v || !v.trim()) return 'required';
+      try {
+        // eslint-disable-next-line no-new
+        new URL(v.trim());
+        return undefined;
+      } catch {
+        return 'expected a URL, e.g. http://localhost:1234';
+      }
+    },
+  });
+  if (isCancel(serverUrl)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const url = String(serverUrl).trim();
+
+  const serverPassword = await password({
+    message: 'BlueBubbles server password',
+    validate: (v) => (v && v.length > 0 ? undefined : 'required'),
+  });
+  if (isCancel(serverPassword)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const pass = String(serverPassword);
+
+  await vault.set(IMESSAGE_SERVER_URL_KEY, url, ['imessage']);
+  await vault.set(IMESSAGE_SERVER_PASSWORD_KEY, pass, ['imessage']);
+  log.success('Stored the BlueBubbles server URL + password in the vault.');
+
+  // Best-effort reachability probe — the ping only uses fetch, no socket.
+  try {
+    await new BlueBubblesClient({ serverUrl: url, password: pass }).ping();
+    log.success('Reached the BlueBubbles server.');
+  } catch (err) {
+    log.warn(
+      `Could not reach the server yet: ${err instanceof Error ? err.message : String(err)}\n` +
+        'You can still finish setup — the channel will retry when it starts.',
+    );
+  }
+
+  const allowAnswer = await text({
+    message: 'Handles allowed to talk to moxxy (comma-separated E.164 numbers / Apple-ID emails)',
+    placeholder: '+15551234567, friend@icloud.com',
+    initialValue: parseHandleList(await vault.get(IMESSAGE_ALLOWED_HANDLES_KEY)).join(', '),
+  });
+  if (isCancel(allowAnswer)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const allowed = parseHandleInput(String(allowAnswer));
+  await vault.set(IMESSAGE_ALLOWED_HANDLES_KEY, JSON.stringify(allowed), ['imessage']);
+  log.success(
+    allowed.length > 0
+      ? `Allow-list saved (${allowed.length} handle(s)).`
+      : 'Allow-list cleared (no external senders allowed).',
+  );
+
+  note(
+    'To talk to moxxy from your OWN Apple devices (texting your "self-chat"),\n' +
+      'add your own iMessage handle(s) below. Leave blank to keep self-chat off —\n' +
+      "your outbound messages to other people are never treated as prompts.",
+    'your own handles (self-chat)',
+  );
+  const ownerAnswer = await text({
+    message: 'Your own handle(s) (comma-separated; blank to skip)',
+    placeholder: '+15559876543, you@icloud.com',
+    initialValue: parseHandleList(await vault.get(IMESSAGE_OWNER_HANDLES_KEY)).join(', '),
+  });
+  if (isCancel(ownerAnswer)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const owner = parseHandleInput(String(ownerAnswer));
+  await vault.set(IMESSAGE_OWNER_HANDLES_KEY, JSON.stringify(owner), ['imessage']);
+  log.success(
+    owner.length > 0 ? `Self-chat enabled for ${owner.length} handle(s).` : 'Self-chat left off.',
+  );
+
+  const allowToolsAnswer = await text({
+    message: 'Autonomous tool allow-list (comma-separated; "*" = all, blank = read-only)',
+    placeholder: 'Read, Grep, Glob',
+  });
+  if (isCancel(allowToolsAnswer)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const allowedTools = String(allowToolsAnswer)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  log.info('Starting the channel. Press Ctrl+C to stop.');
+  outro(dim('handing off to the channel…'));
+  return ctx.startChannel({ allowedTools });
+}
+
+/** Split comma/whitespace-separated handle input, normalize, drop non-handles. */
+function parseHandleInput(raw: string): string[] {
+  const out = new Set<string>();
+  for (const token of raw.split(/[,\s]+/)) {
+    if (!token) continue;
+    const handle = normalizeHandle(token);
+    if (isHandle(handle)) out.add(handle);
+  }
+  return [...out];
+}

package/src/subcommands.test.ts

@@ -0,0 +1,194 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { VaultStore, createStaticKeySource, deriveKey, generateSalt } from '@moxxy/plugin-vault';
+import type { ChannelDef } from '@moxxy/sdk';
+import { buildImessagePlugin } from './index.js';
+import {
+  IMESSAGE_ALLOWED_HANDLES_KEY,
+  IMESSAGE_OWNER_HANDLES_KEY,
+  IMESSAGE_SERVER_PASSWORD_KEY,
+  IMESSAGE_SERVER_URL_KEY,
+} from './keys.js';
+
+let tmp: string;
+let vault: VaultStore;
+let def: ChannelDef;
+let writeOut: string[];
+let writeErr: string[];
+let origStdoutWrite: typeof process.stdout.write;
+let origStderrWrite: typeof process.stderr.write;
+const origPlatform = process.platform;
+
+function setPlatform(value: NodeJS.Platform): void {
+  Object.defineProperty(process, 'platform', { value, configurable: true });
+}
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-imsg-sub-'));
+  vault = new VaultStore({
+    filePath: path.join(tmp, 'vault.json'),
+    keySource: createStaticKeySource(deriveKey('test', generateSalt())),
+  });
+  const plugin = buildImessagePlugin({ vault });
+  const channels = plugin.channels ?? [];
+  def = channels[0] as ChannelDef;
+  writeOut = [];
+  writeErr = [];
+  origStdoutWrite = process.stdout.write.bind(process.stdout);
+  origStderrWrite = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    writeOut.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString());
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    writeErr.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString());
+    return true;
+  }) as typeof process.stderr.write;
+  vi.stubEnv('MOXXY_IMESSAGE_SERVER_URL', '');
+  vi.stubEnv('MOXXY_IMESSAGE_SERVER_PASSWORD', '');
+});
+
+afterEach(async () => {
+  process.stdout.write = origStdoutWrite;
+  process.stderr.write = origStderrWrite;
+  setPlatform(origPlatform);
+  vi.unstubAllEnvs();
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+function ctx(overrides: { startChannel?: () => Promise<number> } = {}) {
+  return {
+    deps: { cwd: tmp, vault, logger: undefined, options: {} },
+    args: { positional: [], flags: {} },
+    startChannel: overrides.startChannel ?? (async () => 0),
+    session: { setPermissionResolver: () => {} },
+  } as never;
+}
+
+describe('imessage ChannelDef shape', () => {
+  it('declares a dedicated runner with the imessage session source', () => {
+    expect(def.name).toBe('imessage');
+    expect(def.dedicatedRunner).toBe(true);
+    expect(def.sessionSource).toBe('imessage');
+    expect(def.interactiveCommand).toBe('setup');
+    expect(Object.keys(def.subcommands ?? {})).toEqual(
+      expect.arrayContaining(['setup', 'status', 'unpair']),
+    );
+    expect(Object.keys(def.subcommands ?? {})).not.toContain('pair');
+    expect(def.config?.fields.map((f) => f.vaultKey)).toEqual([
+      IMESSAGE_SERVER_URL_KEY,
+      IMESSAGE_SERVER_PASSWORD_KEY,
+    ]);
+    expect(def.config?.connect?.kind).toBe('instructions');
+    expect(def.config?.hasRequestUrl).toBeFalsy();
+    // The password field is the only secret; the URL is plain text.
+    const password = def.config?.fields.find((f) => f.vaultKey === IMESSAGE_SERVER_PASSWORD_KEY);
+    expect(password?.secret).toBe(true);
+  });
+});
+
+describe('isAvailable', () => {
+  it('is unavailable off macOS (never throws)', async () => {
+    setPlatform('linux');
+    const availability = await def.isAvailable?.({ cwd: tmp, vault });
+    expect(availability?.ok).toBe(false);
+    expect(availability?.reason).toMatch(/macOS/);
+  });
+
+  it('asks for configuration on macOS when nothing is stored', async () => {
+    setPlatform('darwin');
+    const availability = await def.isAvailable?.({ cwd: tmp, vault });
+    expect(availability?.ok).toBe(false);
+    expect(availability?.reason).toMatch(/imessage setup/);
+  });
+
+  it('is available on macOS with the env pair set', async () => {
+    setPlatform('darwin');
+    vi.stubEnv('MOXXY_IMESSAGE_SERVER_URL', 'http://localhost:1234');
+    vi.stubEnv('MOXXY_IMESSAGE_SERVER_PASSWORD', 'secret');
+    const availability = await def.isAvailable?.({ cwd: tmp, vault });
+    expect(availability).toEqual({ ok: true });
+  });
+
+  it('is available on macOS with the vault pair set', async () => {
+    setPlatform('darwin');
+    await vault.set(IMESSAGE_SERVER_URL_KEY, 'http://localhost:1234');
+    await vault.set(IMESSAGE_SERVER_PASSWORD_KEY, 'secret');
+    const availability = await def.isAvailable?.({ cwd: tmp, vault });
+    expect(availability).toEqual({ ok: true });
+  });
+});
+
+describe('imessage channel subcommands', () => {
+  it('`status` reports unconfigured state as JSON', async () => {
+    const code = await def.subcommands?.status?.run(ctx());
+    expect(code).toBe(0);
+    const parsed = JSON.parse(writeOut.join(''));
+    expect(parsed.serverUrl).toBeNull();
+    expect(parsed.passwordSet).toBe(false);
+    expect(parsed.allowedHandles).toEqual([]);
+    expect(parsed.ownerHandles).toEqual([]);
+    expect(parsed.supported).toBe(process.platform === 'darwin');
+  });
+
+  it('`status` surfaces the stored server + allow-list (never the password)', async () => {
+    await vault.set(IMESSAGE_SERVER_URL_KEY, 'http://localhost:1234');
+    await vault.set(IMESSAGE_SERVER_PASSWORD_KEY, 'super-secret');
+    await vault.set(IMESSAGE_ALLOWED_HANDLES_KEY, JSON.stringify(['+14440002222']));
+    await vault.set(IMESSAGE_OWNER_HANDLES_KEY, JSON.stringify(['+19998887777']));
+    const code = await def.subcommands?.status?.run(ctx());
+    expect(code).toBe(0);
+    const out = writeOut.join('');
+    expect(out).not.toContain('super-secret');
+    const parsed = JSON.parse(out);
+    expect(parsed.serverUrl).toBe('http://localhost:1234');
+    expect(parsed.passwordSet).toBe(true);
+    expect(parsed.allowedHandles).toEqual(['+14440002222']);
+    expect(parsed.ownerHandles).toEqual(['+19998887777']);
+  });
+
+  it('`unpair` clears server config + handle lists', async () => {
+    await vault.set(IMESSAGE_SERVER_URL_KEY, 'http://localhost:1234');
+    await vault.set(IMESSAGE_SERVER_PASSWORD_KEY, 'secret');
+    await vault.set(IMESSAGE_ALLOWED_HANDLES_KEY, JSON.stringify(['+14440002222']));
+    const code = await def.subcommands?.unpair?.run(ctx());
+    expect(code).toBe(0);
+    expect(writeOut.join('')).toContain('unpaired');
+    expect(await vault.get(IMESSAGE_SERVER_URL_KEY)).toBeNull();
+    expect(await vault.get(IMESSAGE_SERVER_PASSWORD_KEY)).toBeNull();
+    expect(await vault.get(IMESSAGE_ALLOWED_HANDLES_KEY)).toBeNull();
+  });
+
+  it('`unpair` is a no-op when nothing is configured', async () => {
+    const code = await def.subcommands?.unpair?.run(ctx());
+    expect(code).toBe(0);
+    expect(writeOut.join('')).toContain('no BlueBubbles server was configured');
+  });
+
+  it('`setup` starts the channel directly when headless', async () => {
+    const originalIsTTY = process.stdin.isTTY;
+    Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+    try {
+      const startChannel = vi.fn(async () => 0);
+      const code = await def.subcommands?.setup?.run(ctx({ startChannel }));
+      expect(code).toBe(0);
+      expect(startChannel).toHaveBeenCalledTimes(1);
+    } finally {
+      Object.defineProperty(process.stdin, 'isTTY', { value: originalIsTTY, configurable: true });
+    }
+  });
+
+  it('subcommands return 1 when the vault is unavailable', async () => {
+    const badCtx = {
+      deps: { cwd: tmp, vault: undefined, logger: undefined, options: {} },
+      args: { positional: [], flags: {} },
+      startChannel: async () => 0,
+      session: { setPermissionResolver: () => {} },
+    } as never;
+    const code = await def.subcommands?.status?.run(badCtx);
+    expect(code).toBe(1);
+    expect(writeErr.join('')).toContain('vault unavailable');
+  });
+});