@moxxy/plugin-channel-signal 0.27.0

package/src/index.ts

@@ -0,0 +1,289 @@
+import { defineChannel, definePlugin, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { SignalChannel, type SignalChannelOptions } from './channel.js';
+import {
+  SIGNAL_ACCOUNT_ENV,
+  SIGNAL_ACCOUNT_KEY,
+  SIGNAL_ALLOWED_SENDERS_KEY,
+  parseAllowedSenders,
+} from './keys.js';
+import {
+  SIGNAL_CLI_INSTALL_HINT,
+  findSignalCliOnPath,
+  listSignalAccounts,
+  signalCliDataDir,
+} from './sidecar.js';
+import { runSignalWizard } from './setup-wizard.js';
+import { runSignalPairFlow } from './pair-flow.js';
+
+export {
+  SignalChannel,
+  type SignalChannelOptions,
+  type SignalStartOpts,
+  type SendTarget,
+  type SignalRpcLike,
+  type SignalSidecarLike,
+} from './channel.js';
+export { buildSignalPermissionResolver } from './permission.js';
+export { SignalRpcClient, type RpcStream } from './jsonrpc.js';
+export {
+  SignalSidecar,
+  startLinkProcess,
+  listSignalAccounts,
+  findSignalCliOnPath,
+  signalCliDataDir,
+  signalCliAttachmentsDir,
+  SIGNAL_CLI_INSTALL_HINT,
+  type LinkProcessHandle,
+  type SpawnFn,
+  type SpawnedProcess,
+} from './sidecar.js';
+export {
+  receiveParamsSchema,
+  envelopeSchema,
+  attachmentSchema,
+  MAX_INBOUND_TEXT_CHARS,
+  type SignalEnvelope,
+  type SignalAttachment,
+} from './schema.js';
+export {
+  ChunkedSender,
+  takeChunk,
+  splitForSignal,
+  SIGNAL_CHUNK_SOFT_LIMIT,
+  SIGNAL_CHUNK_HARD_LIMIT,
+} from './channel/chunker.js';
+export {
+  SIGNAL_ACCOUNT_KEY,
+  SIGNAL_ACCOUNT_ENV,
+  SIGNAL_ALLOWED_SENDERS_KEY,
+  parseAllowedSenders,
+  normalizeSender,
+  E164_RE,
+} from './keys.js';
+
+export interface BuildSignalPluginOptions {
+  /** Host-injected encrypted secret store (available immediately). */
+  readonly vault: VaultStore;
+}
+
+/**
+ * Build the Signal channel plugin with a host-injected vault (mirrors the
+ * Telegram/Slack plugins' vault injection).
+ */
+export function buildSignalPlugin(opts: BuildSignalPluginOptions): Plugin {
+  return makeSignalPlugin(() => 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`). The channel + subcommands read the vault via
+ * `getVault()`, so resolution is deferred to call time — after `onInit` wired it.
+ */
+export const signalPlugin: Plugin = (() => {
+  let resolved: VaultStore | null = null;
+  const getVault = (): VaultStore => {
+    if (!resolved) {
+      throw new Error(
+        '@moxxy/plugin-channel-signal: 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 makeSignalPlugin(getVault, hooks);
+})();
+
+export default signalPlugin;
+
+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 makeSignalPlugin(getVault: () => VaultStore, hooks?: LifecycleHooks): Plugin {
+  return definePlugin({
+    name: '@moxxy/plugin-channel-signal',
+    version: '0.0.0',
+    ...(hooks ? { hooks } : {}),
+    channels: [
+      defineChannel({
+        name: 'signal',
+        description:
+          'Signal messenger channel via a signal-cli JSON-RPC sidecar. Links as a secondary device (QR); Note-to-Self + allow-listed senders drive the agent.',
+        // A linked device sees ALL the account owner's messages, so this
+        // channel runs on its own dedicated, isolated runner (separate socket +
+        // sticky session), like Slack — the bot keeps its own persistent
+        // history apart from the user's desktop/TUI work.
+        dedicatedRunner: true,
+        sessionSource: 'signal',
+        // Self-described config so a control surface (TUI `/channels`, `moxxy
+        // channels start`, the desktop panel) can configure + run Signal
+        // without a hardcoded table.
+        config: {
+          fields: [
+            {
+              name: 'account',
+              label: 'Account number (E.164)',
+              vaultKey: SIGNAL_ACCOUNT_KEY,
+              required: true,
+              secret: false,
+              placeholder: '+15551234567',
+              help: 'The Signal account moxxy links to as a secondary device (needs signal-cli on PATH)',
+            },
+          ],
+          hasRequestUrl: false,
+          runHint:
+            'Scan the QR with your phone (Signal → Settings → Linked Devices → Link New Device); then message your own "Note to Self" to talk to moxxy.',
+          connect: {
+            kind: 'qr',
+            title: 'Link your Signal',
+            hint: 'On your phone: Signal → Settings → Linked Devices → Link New Device, then scan the QR.',
+          },
+        },
+        create: (deps) => {
+          const options = deps.options;
+          const channelOpts: SignalChannelOptions = {
+            vault: getVault(),
+            ...(typeof options?.['account'] === 'string' ? { account: options['account'] } : {}),
+            ...(typeof options?.['binary'] === 'string' ? { binary: options['binary'] } : {}),
+            ...(() => {
+              const tools = readStringArray(options?.['allowedTools']);
+              return tools ? { allowedTools: tools } : {};
+            })(),
+            ...(() => {
+              const senders = readStringArray(options?.['allowedSenders']);
+              return senders ? { allowedSenders: senders } : {};
+            })(),
+            logger: deps.logger as never,
+          };
+          return new SignalChannel(channelOpts);
+        },
+        isAvailable: async () => {
+          // Gate 1: the signal-cli binary. A pure PATH scan (no spawn — this
+          // runs on every `moxxy channels list` / `moxxy doctor`), and a miss
+          // must NEVER crash discovery: return a friendly install hint.
+          try {
+            if (!findSignalCliOnPath()) {
+              return { ok: false, reason: SIGNAL_CLI_INSTALL_HINT };
+            }
+          } catch {
+            return { ok: false, reason: SIGNAL_CLI_INSTALL_HINT };
+          }
+          // Gate 2: an account number (env first — the vault may not be wired
+          // in a probe/listing context).
+          if (process.env[SIGNAL_ACCOUNT_ENV]?.trim()) return { ok: true };
+          try {
+            if (await getVault().has(SIGNAL_ACCOUNT_KEY)) return { ok: true };
+          } catch {
+            /* vault unavailable in a probe context — fall through */
+          }
+          return {
+            ok: false,
+            reason: `No Signal account configured. Run \`moxxy channels signal setup\`, set ${SIGNAL_ACCOUNT_ENV}, or store one in the vault as '${SIGNAL_ACCOUNT_KEY}'.`,
+          };
+        },
+        interactiveCommand: 'setup',
+        subcommands: {
+          setup: {
+            description:
+              'Interactive setup: check signal-cli, store the account number, pick the tool allow-list, then link + start. Shown by default for `moxxy signal` on a TTY.',
+            run: async (ctx) => {
+              if (process.stdin.isTTY !== true) {
+                // Headless: just start the channel (account must already be
+                // configured + linked).
+                return ctx.startChannel();
+              }
+              return runSignalWizard(ctx);
+            },
+          },
+          pair: {
+            description:
+              'Link this machine to your Signal account: prints a QR to scan from Signal → Settings → Linked Devices — the same mechanism the desktop uses.',
+            run: async (ctx) => {
+              if (process.stdin.isTTY !== true) {
+                process.stderr.write(
+                  'Pairing needs a TTY to show the QR. Run `moxxy channels signal pair` on a workstation, or pair from the desktop Channels panel.\n',
+                );
+                return 1;
+              }
+              return runSignalPairFlow(ctx);
+            },
+          },
+          status: {
+            description:
+              'Report signal-cli / account / linking / 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 binary = findSignalCliOnPath();
+              const account =
+                process.env[SIGNAL_ACCOUNT_ENV]?.trim() || (await vault.get(SIGNAL_ACCOUNT_KEY));
+              const allowedSenders = parseAllowedSenders(
+                await vault.get(SIGNAL_ALLOWED_SENDERS_KEY),
+              );
+              // Linked state needs a one-shot signal-cli spawn (slow JVM);
+              // report null when the probe isn't possible/fails.
+              let linked: boolean | null = null;
+              if (binary && account) {
+                try {
+                  linked = (await listSignalAccounts({ binary })).includes(account);
+                } catch {
+                  linked = null;
+                }
+              }
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    binaryFound: binary != null,
+                    account: account || null,
+                    linked,
+                    allowedSenders,
+                    dataDir: signalCliDataDir(),
+                  },
+                  null,
+                  2,
+                ) + '\n',
+              );
+              return 0;
+            },
+          },
+          unpair: {
+            description:
+              "Forget the stored account + sender allow-list. (signal-cli's own linked-device store is untouched; remove the device from Signal → Linked Devices on your phone to fully unlink.)",
+            run: async (ctx) => {
+              const vault = ctx.deps.vault as VaultStore | undefined;
+              if (!vault) {
+                process.stderr.write('vault unavailable\n');
+                return 1;
+              }
+              const removedAccount = await vault.delete(SIGNAL_ACCOUNT_KEY);
+              await vault.delete(SIGNAL_ALLOWED_SENDERS_KEY);
+              process.stdout.write(
+                removedAccount
+                  ? 'unpaired (vault cleared). To fully unlink, remove the "moxxy" device in Signal → Settings → Linked Devices on your phone.\n'
+                  : 'no account was configured\n',
+              );
+              return 0;
+            },
+          },
+        },
+      }),
+    ],
+  });
+}

package/src/jsonrpc.test.ts

@@ -0,0 +1,128 @@
+import { EventEmitter } from 'node:events';
+import { describe, expect, it, vi } from 'vitest';
+import { SignalRpcClient, type RpcStream } from './jsonrpc.js';
+
+class FakeStream extends EventEmitter implements RpcStream {
+  written: string[] = [];
+  ended = false;
+  write(data: string): boolean {
+    this.written.push(data);
+    return true;
+  }
+  end(): void {
+    this.ended = true;
+  }
+  /** Feed one raw chunk into the client. */
+  feed(raw: string): void {
+    this.emit('data', Buffer.from(raw, 'utf8'));
+  }
+  lastRequest(): { id: string; method: string; params: unknown } {
+    return JSON.parse(this.written.at(-1)!) as { id: string; method: string; params: unknown };
+  }
+}
+
+describe('SignalRpcClient', () => {
+  it('matches responses to requests by id', async () => {
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream });
+    const p = client.request('send', { message: 'hi' });
+    const req = stream.lastRequest();
+    expect(req.method).toBe('send');
+    stream.feed(`{"jsonrpc":"2.0","id":"${req.id}","result":{"timestamp":42}}\n`);
+    await expect(p).resolves.toEqual({ timestamp: 42 });
+  });
+
+  it('rejects on a JSON-RPC error reply', async () => {
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream });
+    const p = client.request('send', {});
+    const req = stream.lastRequest();
+    stream.feed(`{"jsonrpc":"2.0","id":"${req.id}","error":{"code":-32602,"message":"bad params"}}\n`);
+    await expect(p).rejects.toThrow(/bad params/);
+  });
+
+  it('dispatches notifications to subscribers and survives listener throw', () => {
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream });
+    const seen: unknown[] = [];
+    client.onNotification('receive', () => {
+      throw new Error('boom');
+    });
+    client.onNotification('receive', (params) => seen.push(params));
+    stream.feed('{"jsonrpc":"2.0","method":"receive","params":{"envelope":{"sourceNumber":"+1"}}}\n');
+    expect(seen).toEqual([{ envelope: { sourceNumber: '+1' } }]);
+  });
+
+  it('handles split + coalesced frames', async () => {
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream });
+    const p1 = client.request('a');
+    const p2 = client.request('b');
+    const id1 = JSON.parse(stream.written[0]!).id as string;
+    const id2 = JSON.parse(stream.written[1]!).id as string;
+    const line1 = `{"jsonrpc":"2.0","id":"${id1}","result":1}\n`;
+    const line2 = `{"jsonrpc":"2.0","id":"${id2}","result":2}\n`;
+    const combined = line1 + line2;
+    stream.feed(combined.slice(0, 10));
+    stream.feed(combined.slice(10));
+    await expect(p1).resolves.toBe(1);
+    await expect(p2).resolves.toBe(2);
+  });
+
+  it('times out a request the daemon never answers', async () => {
+    vi.useFakeTimers();
+    try {
+      const stream = new FakeStream();
+      const client = new SignalRpcClient({ stream, requestTimeoutMs: 500 });
+      const p = client.request('version');
+      const assertion = expect(p).rejects.toThrow(/timed out/);
+      await vi.advanceTimersByTimeAsync(600);
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('rejects pending requests when the stream closes', async () => {
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream });
+    const p = client.request('version');
+    stream.emit('close');
+    await expect(p).rejects.toThrow(/socket closed/);
+    await expect(client.request('version')).rejects.toThrow(/closed/);
+  });
+
+  it('notifies onClose listeners with the reason', () => {
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream });
+    const reasons: string[] = [];
+    client.onClose((r) => reasons.push(r));
+    stream.emit('error', new Error('ECONNRESET'));
+    expect(reasons).toEqual(['socket error: ECONNRESET']);
+  });
+
+  it('drops an oversized un-delimited line instead of buffering forever', () => {
+    const warn = vi.fn();
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream, logger: { warn } });
+    stream.feed('x'.repeat(9 * 1024 * 1024)); // > 8MB cap, no newline
+    expect(warn).toHaveBeenCalledWith(
+      'signal rpc: dropped oversized un-delimited line',
+      expect.objectContaining({ bytes: expect.any(Number) }),
+    );
+    // Client still works afterwards.
+    const p = client.request('version');
+    const req = stream.lastRequest();
+    stream.feed(`{"jsonrpc":"2.0","id":"${req.id}","result":"ok"}\n`);
+    return expect(p).resolves.toBe('ok');
+  });
+
+  it('ignores garbage lines and unknown ids', () => {
+    const stream = new FakeStream();
+    const client = new SignalRpcClient({ stream });
+    stream.feed('not json\n');
+    stream.feed('{"jsonrpc":"2.0","id":"999","result":1}\n');
+    // No throw — and the client still accepts requests.
+    void client;
+  });
+});

package/src/jsonrpc.ts

@@ -0,0 +1,198 @@
+/**
+ * Minimal newline-delimited JSON-RPC 2.0 client for the signal-cli daemon
+ * socket (`signal-cli -a <account> daemon --socket <path>`).
+ *
+ * The daemon speaks one JSON object per line over the UNIX socket:
+ *   → {"jsonrpc":"2.0","id":"…","method":"send","params":{…}}
+ *   ← {"jsonrpc":"2.0","id":"…","result":{…}} | {"…","error":{code,message}}
+ *   ← {"jsonrpc":"2.0","method":"receive","params":{"envelope":{…}}}   (notification)
+ *
+ * The transport is injected as a plain duplex-ish stream so tests never open a
+ * real socket (mirrors the browser sidecar's injectable spawn).
+ */
+
+/** The stream slice this client needs — `net.Socket` satisfies it. */
+export interface RpcStream {
+  write(data: string): unknown;
+  on(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
+  on(event: 'close', listener: () => void): unknown;
+  on(event: 'error', listener: (err: Error) => void): unknown;
+  end?(): unknown;
+  destroy?(): unknown;
+}
+
+export interface RpcLogger {
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface SignalRpcClientOptions {
+  readonly stream: RpcStream;
+  /** Per-request timeout. signal-cli sends synchronously to the Signal server,
+   *  so allow generous headroom. Default 30s. */
+  readonly requestTimeoutMs?: number;
+  readonly logger?: RpcLogger;
+}
+
+/**
+ * Cap on a single buffered line. Receive envelopes are small (attachments are
+ * written to signal-cli's data dir, not inlined), so anything beyond this is a
+ * malformed/hostile peer; we drop the buffer instead of growing unbounded.
+ */
+const MAX_LINE_BUFFER = 8 * 1024 * 1024;
+
+interface PendingCall {
+  resolve(value: unknown): void;
+  reject(err: Error): void;
+}
+
+export class SignalRpcClient {
+  private readonly stream: RpcStream;
+  private readonly requestTimeoutMs: number;
+  private readonly logger: RpcLogger | undefined;
+  private readonly pending = new Map<string, PendingCall>();
+  private readonly notificationListeners = new Map<string, Set<(params: unknown) => void>>();
+  private readonly closeListeners = new Set<(reason: string) => void>();
+  private buffer = '';
+  private nextId = 1;
+  private closed = false;
+
+  constructor(opts: SignalRpcClientOptions) {
+    this.stream = opts.stream;
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 30_000;
+    this.logger = opts.logger;
+    this.stream.on('data', (chunk) => this.onData(chunk));
+    this.stream.on('close', () => this.teardown('socket closed'));
+    this.stream.on('error', (err) => this.teardown(`socket error: ${err.message}`));
+  }
+
+  /** Subscribe to a JSON-RPC notification method (e.g. 'receive'). */
+  onNotification(method: string, listener: (params: unknown) => void): () => void {
+    let set = this.notificationListeners.get(method);
+    if (!set) {
+      set = new Set();
+      this.notificationListeners.set(method, set);
+    }
+    set.add(listener);
+    return () => set.delete(listener);
+  }
+
+  /** Fires once when the underlying stream closes/errors (daemon died). */
+  onClose(listener: (reason: string) => void): () => void {
+    this.closeListeners.add(listener);
+    return () => this.closeListeners.delete(listener);
+  }
+
+  request(method: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    if (this.closed) {
+      return Promise.reject(new Error(`signal-cli rpc closed (cannot call ${method})`));
+    }
+    const id = String(this.nextId++);
+    const payload = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+    return new Promise<unknown>((resolve, reject) => {
+      // Per-call timeout so a wedged daemon never strands the caller.
+      const timer = setTimeout(() => {
+        if (this.pending.delete(id)) {
+          reject(new Error(`signal-cli rpc "${method}" timed out after ${this.requestTimeoutMs}ms`));
+        }
+      }, this.requestTimeoutMs);
+      timer.unref?.();
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(timer);
+          resolve(v);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      });
+      try {
+        this.stream.write(payload + '\n');
+      } catch (err) {
+        this.pending.delete(id);
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+
+  close(): void {
+    this.teardown('client closed');
+    try {
+      this.stream.end?.();
+      this.stream.destroy?.();
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  private teardown(reason: string): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const [, p] of this.pending) p.reject(new Error(`signal-cli rpc: ${reason}`));
+    this.pending.clear();
+    for (const listener of this.closeListeners) {
+      try {
+        listener(reason);
+      } catch {
+        /* listener errors must not break teardown */
+      }
+    }
+    this.closeListeners.clear();
+  }
+
+  private onData(chunk: Buffer | string): void {
+    this.buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    let nl: number;
+    while ((nl = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, nl);
+      this.buffer = this.buffer.slice(nl + 1);
+      if (line.trim()) this.handleLine(line);
+    }
+    if (this.buffer.length > MAX_LINE_BUFFER) {
+      this.logger?.warn?.('signal rpc: dropped oversized un-delimited line', {
+        bytes: this.buffer.length,
+      });
+      this.buffer = '';
+    }
+  }
+
+  private handleLine(line: string): void {
+    let msg: {
+      id?: string | number;
+      method?: string;
+      params?: unknown;
+      result?: unknown;
+      error?: { code?: number; message?: string };
+    };
+    try {
+      msg = JSON.parse(line) as typeof msg;
+    } catch {
+      this.logger?.warn?.('signal rpc: ignoring unparseable line');
+      return;
+    }
+    // Notification: has a method, no id.
+    if (msg.method !== undefined && msg.id === undefined) {
+      const listeners = this.notificationListeners.get(msg.method);
+      if (!listeners) return;
+      for (const listener of listeners) {
+        try {
+          listener(msg.params);
+        } catch (err) {
+          this.logger?.warn?.('signal rpc: notification listener threw', { err: String(err) });
+        }
+      }
+      return;
+    }
+    // Response: match by id.
+    const id = msg.id !== undefined ? String(msg.id) : null;
+    const p = id ? this.pending.get(id) : undefined;
+    if (!p || !id) return; // late/unknown reply — ignore
+    this.pending.delete(id);
+    if (msg.error) {
+      p.reject(new Error(`signal-cli rpc error ${msg.error.code ?? ''}: ${msg.error.message ?? 'unknown'}`));
+    } else {
+      p.resolve(msg.result);
+    }
+  }
+}

package/src/keys.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { E164_RE, normalizeSender, parseAllowedSenders } from './keys.js';
+
+describe('E164_RE', () => {
+  it('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('+1555123456789012345')).toBe(false);
+    expect(E164_RE.test('')).toBe(false);
+  });
+});
+
+describe('normalizeSender', () => {
+  it('lowercases UUIDs but preserves numbers', () => {
+    expect(normalizeSender(' +15551234567 ')).toBe('+15551234567');
+    expect(normalizeSender('AB0F5EAD-0000-4000-8000-00805F9B34FB')).toBe(
+      'ab0f5ead-0000-4000-8000-00805f9b34fb',
+    );
+  });
+});
+
+describe('parseAllowedSenders', () => {
+  it('parses a JSON array of numbers/uuids', () => {
+    const raw = JSON.stringify(['+15551234567', 'AB0F5EAD-0000-4000-8000-00805F9B34FB']);
+    expect(parseAllowedSenders(raw)).toEqual([
+      '+15551234567',
+      'ab0f5ead-0000-4000-8000-00805f9b34fb',
+    ]);
+  });
+
+  it('fails closed on corrupt values', () => {
+    expect(parseAllowedSenders(null)).toEqual([]);
+    expect(parseAllowedSenders('')).toEqual([]);
+    expect(parseAllowedSenders('not json')).toEqual([]);
+    expect(parseAllowedSenders('"a string"')).toEqual([]);
+    expect(parseAllowedSenders('{"a":1}')).toEqual([]);
+  });
+
+  it('drops entries that are neither E.164 nor uuid', () => {
+    const raw = JSON.stringify(['+15551234567', 'bob', 42, '../../etc/passwd']);
+    expect(parseAllowedSenders(raw)).toEqual(['+15551234567']);
+  });
+});