@moxxy/plugin-channel-signal 0.27.0

package/src/keys.ts

@@ -0,0 +1,56 @@
+/**
+ * Vault keys + validation shared by the channel, its subcommands, and the
+ * interactive setup wizard. Kept in their own module (the telegram/slack
+ * `keys.ts` pattern) so wizard / pair-flow helpers can import them without
+ * pulling in the plugin's full index.
+ *
+ * Note on secret custody: signal-cli keeps the actual Signal identity keys +
+ * message store in ITS OWN data dir (`$XDG_DATA_HOME/signal-cli/`, i.e.
+ * `~/.local/share/signal-cli/` by default — see {@link signalCliDataDir}).
+ * The moxxy vault only stores the account NUMBER and the sender allow-list;
+ * there is no API token in this channel at all.
+ */
+
+/** Vault key for the linked Signal account number (E.164). */
+export const SIGNAL_ACCOUNT_KEY = 'signal_account';
+/** Env override for the account number — beats the vault (shared precedence). */
+export const SIGNAL_ACCOUNT_ENV = 'MOXXY_SIGNAL_ACCOUNT';
+/**
+ * Vault key for the sender allow-list: a JSON array of E.164 numbers and/or
+ * Signal account UUIDs that may drive the session. The linked account's own
+ * "Note to Self" is allowed implicitly and does not need an entry here.
+ */
+export const SIGNAL_ALLOWED_SENDERS_KEY = 'signal_allowed_senders';
+
+/** E.164 shape: `+` then 7–15 digits, no leading zero. */
+export const E164_RE = /^\+[1-9]\d{6,14}$/;
+
+/** Loose UUID shape (Signal ACIs are UUIDv4; accept any hex-dash UUID). */
+export const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/** Canonical sender identity for allow-list comparisons: trimmed, UUIDs lowercased. */
+export function normalizeSender(raw: string): string {
+  const trimmed = raw.trim();
+  return UUID_RE.test(trimmed) ? trimmed.toLowerCase() : trimmed;
+}
+
+/**
+ * Parse the stored allow-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 look like neither an E.164 number nor a
+ * UUID are dropped.
+ */
+export function parseAllowedSenders(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((x): x is string => typeof x === 'string')
+      .map(normalizeSender)
+      .filter((x) => E164_RE.test(x) || UUID_RE.test(x));
+  } catch {
+    return [];
+  }
+}

package/src/pair-flow.ts

@@ -0,0 +1,161 @@
+import { log, outro, spinner } from '@clack/prompts';
+import QRCode from 'qrcode';
+import { exitAfterPairRequested, type ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { SignalChannel } from './channel.js';
+
+// Tiny zero-dep ANSI dim helper, so this flow stays inside the plugin.
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+/**
+ * Drive the Signal linked-device pairing end-to-end in a terminal — the SAME
+ * mechanism the desktop Channels panel uses (the channel's `pair: true` link
+ * window), just rendered inline here.
+ *
+ * Steps:
+ *   1. Build a SignalChannel from the subcommand ctx and wire the session's
+ *      permission resolver.
+ *   2. Subscribe to "linked" BEFORE starting so a fast scan can't race us.
+ *   3. Start the channel in pairing mode — it spawns `signal-cli link` and
+ *      publishes the `sgnl://linkdevice…` URI as `channel.requestUrl`.
+ *   4. Render that URI as a scannable QR (+ the raw URI).
+ *   5. On the phone: Signal → Settings → Linked Devices → Link New Device →
+ *      scan; the channel stores the account and boots the daemon.
+ *   6. Keep the channel running until the user Ctrl-Cs.
+ */
+export async function runSignalPairFlow(
+  ctx: ChannelSubcommandContext,
+  overrides: { readonly allowedTools?: ReadonlyArray<string> } = {},
+): Promise<number> {
+  const session = ctx.session;
+  const channel = new SignalChannel({
+    vault: ctx.deps.vault as VaultStore,
+    ...(typeof ctx.deps.options?.['account'] === 'string'
+      ? { account: ctx.deps.options['account'] as string }
+      : {}),
+    ...(overrides.allowedTools ? { allowedTools: overrides.allowedTools } : {}),
+    logger: ctx.deps.logger as never,
+  });
+  session.setPermissionResolver(channel.permissionResolver);
+
+  // Subscribe BEFORE start so the first scan can't fire before us.
+  let linkedResolve: ((account: string) => void) | null = null;
+  const linkedPromise = new Promise<string>((resolve) => {
+    linkedResolve = resolve;
+  });
+  const unsubscribe = channel.onLinked((account) => {
+    linkedResolve?.(account);
+    linkedResolve = null;
+  });
+
+  outro(dim('opening Signal linking window...'));
+
+  const handle = await channel.start({ session, pair: true });
+
+  const stopChannel = async (): Promise<void> => {
+    unsubscribe();
+    try {
+      await handle.stop('pair-flow');
+    } catch {
+      /* ignore */
+    }
+  };
+
+  // Already linked (no window was opened): nothing to scan.
+  if (channel.connected) {
+    log.info(
+      'This machine is already linked to a Signal account. The channel is running; ' +
+        'to link a different account, remove this device from Signal → Linked Devices first, ' +
+        'then run `moxxy channels signal unpair` and pair again.',
+    );
+    if (exitAfterPairRequested(ctx)) {
+      await stopChannel();
+      return 0;
+    }
+    log.info('Press Ctrl+C to stop.');
+    installSignalHandlers(stopChannel, session);
+    await handle.running;
+    return 0;
+  }
+
+  const uri = channel.requestUrl;
+  if (!uri) {
+    log.error('Could not obtain a linking URI from signal-cli.');
+    await stopChannel();
+    return 1;
+  }
+
+  await printLinkQr(uri);
+  log.info(
+    'On your phone: Signal → Settings → Linked Devices → Link New Device, then scan the QR. ' +
+      'The QR expires after a few minutes; re-run `moxxy channels signal pair` if it does.',
+  );
+
+  const removeSignalHandlers = installSignalHandlers(stopChannel, session);
+
+  const spin = spinner();
+  spin.start('Waiting for you to scan in Signal...');
+  const account = await Promise.race([
+    linkedPromise,
+    handle.running.then(() => null as string | null),
+  ]).catch((err: unknown) => {
+    spin.stop('Linking failed.');
+    log.error(err instanceof Error ? err.message : String(err));
+    return null;
+  });
+  if (account == null) {
+    await stopChannel();
+    return 1;
+  }
+  spin.stop(`Linked ✓ — this machine is now a device of ${account}.`);
+
+  if (exitAfterPairRequested(ctx)) {
+    // Orchestrated pairing (`moxxy onboard`): hand control back — the caller
+    // starts the channel under its own service afterwards. Our SIGINT
+    // handlers would `process.exit` the orchestrator, so drop them first.
+    removeSignalHandlers();
+    await stopChannel();
+    return 0;
+  }
+
+  log.info(
+    'Message your own "Note to Self" in Signal to talk to moxxy. The channel is running; press Ctrl+C to stop.',
+  );
+
+  await handle.running;
+  return 0;
+}
+
+function installSignalHandlers(
+  stopChannel: () => Promise<void>,
+  session: ChannelSubcommandContext['session'],
+): () => void {
+  let stopping = false;
+  const shutdown = async (): Promise<void> => {
+    if (stopping) return;
+    stopping = true;
+    await stopChannel();
+    await session.close('SIGINT').catch(() => undefined);
+    process.exit(0);
+  };
+  const onSignal = (): void => void shutdown();
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  return () => {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  };
+}
+
+/** Render the linking URI as a scannable terminal QR + the raw URI. */
+async function printLinkQr(uri: string): Promise<void> {
+  let qr = '';
+  try {
+    qr = await QRCode.toString(uri, { type: 'terminal', small: true });
+  } catch {
+    qr = '';
+  }
+  // CLI surface — intentional stdout.
+  console.log(['', qr, `  link URI: ${uri}`, ''].join('\n'));
+}

package/src/permission.ts

@@ -0,0 +1,36 @@
+import { createAuditedAllowListResolver } from '@moxxy/channel-kit';
+import type { PermissionResolver } from '@moxxy/sdk';
+
+export interface SignalPermissionLogger {
+  info?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+/**
+ * Build the Signal channel's autonomous permission resolver.
+ *
+ * Like Slack (and unlike Telegram's inline-keyboard prompts), the Signal
+ * channel runs hands-off: the operator declares trust upfront via
+ * `channels.signal.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).
+ */
+export function buildSignalPermissionResolver(opts: {
+  allowedTools: ReadonlyArray<string>;
+  allToolNames: ReadonlyArray<string>;
+  logger?: SignalPermissionLogger;
+}): PermissionResolver {
+  return createAuditedAllowListResolver({
+    name: 'signal-allow-list',
+    allowedTools: opts.allowedTools,
+    allToolNames: opts.allToolNames,
+    onAutoApprove: (call, { wildcard }) => {
+      opts.logger?.info?.('signal: auto-approved tool call', {
+        tool: call.name,
+        callId: call.callId,
+        wildcard,
+      });
+    },
+  });
+}

package/src/schema.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+
+/**
+ * Zod validation for signal-cli `receive` notification params — every inbound
+ * envelope is validated + size-capped BEFORE any field reaches the session
+ * (channel invariant A8). We only type the fields the channel consumes;
+ * unknown extras pass through untouched so a newer signal-cli 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;
+
+/**
+ * Attachment ids become filenames under signal-cli's attachments dir; a strict
+ * charset (no separators, no dots-only names) makes path traversal impossible
+ * before we ever join() it.
+ */
+export const attachmentIdSchema = z
+  .string()
+  .min(1)
+  .max(256)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'invalid attachment id');
+
+export const attachmentSchema = z
+  .object({
+    id: attachmentIdSchema.optional(),
+    contentType: z.string().max(128).optional(),
+    filename: z.string().max(512).nullable().optional(),
+    size: z.number().int().nonnegative().optional(),
+  })
+  .passthrough();
+
+export type SignalAttachment = z.infer<typeof attachmentSchema>;
+
+const groupInfoSchema = z
+  .object({
+    groupId: z.string().max(256).optional(),
+  })
+  .passthrough();
+
+const dataMessageSchema = z
+  .object({
+    timestamp: z.number().int().optional(),
+    message: z.string().max(MAX_INBOUND_TEXT_CHARS).nullable().optional(),
+    groupInfo: groupInfoSchema.nullable().optional(),
+    attachments: z.array(attachmentSchema).max(16).optional(),
+  })
+  .passthrough();
+
+/**
+ * A sync'd copy of a message the ACCOUNT OWNER sent from another of their
+ * devices (their phone, Signal Desktop, …). "Note to Self" prompts arrive this
+ * way — and so can echoes of our OWN sends, which is why the channel filters
+ * these by sent-timestamp before acting (loop protection).
+ */
+const sentMessageSchema = z
+  .object({
+    timestamp: z.number().int().optional(),
+    message: z.string().max(MAX_INBOUND_TEXT_CHARS).nullable().optional(),
+    destination: z.string().max(128).nullable().optional(),
+    destinationNumber: z.string().max(32).nullable().optional(),
+    destinationUuid: z.string().max(64).nullable().optional(),
+    groupInfo: groupInfoSchema.nullable().optional(),
+    attachments: z.array(attachmentSchema).max(16).optional(),
+  })
+  .passthrough();
+
+const syncMessageSchema = z
+  .object({
+    sentMessage: sentMessageSchema.optional(),
+  })
+  .passthrough();
+
+export const envelopeSchema = z
+  .object({
+    source: z.string().max(128).nullable().optional(),
+    sourceNumber: z.string().max(32).nullable().optional(),
+    sourceUuid: z.string().max(64).nullable().optional(),
+    sourceName: z.string().max(256).nullable().optional(),
+    sourceDevice: z.number().int().optional(),
+    timestamp: z.number().int().optional(),
+    dataMessage: dataMessageSchema.nullable().optional(),
+    syncMessage: syncMessageSchema.nullable().optional(),
+    // typingMessage / receiptMessage / receiptMessage etc. pass through and are
+    // simply not consumed.
+  })
+  .passthrough();
+
+export const receiveParamsSchema = z
+  .object({
+    account: z.string().max(64).optional(),
+    envelope: envelopeSchema,
+  })
+  .passthrough();
+
+export type SignalEnvelope = z.infer<typeof envelopeSchema>;
+export type SignalReceiveParams = z.infer<typeof receiveParamsSchema>;

package/src/setup-wizard.ts

@@ -0,0 +1,98 @@
+import { cancel, intro, isCancel, log, note, outro, text } from '@clack/prompts';
+import type { ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { E164_RE, SIGNAL_ACCOUNT_KEY } from './keys.js';
+import { SIGNAL_CLI_INSTALL_HINT, findSignalCliOnPath, listSignalAccounts } from './sidecar.js';
+import { runSignalPairFlow } from './pair-flow.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 Signal setup wizard (the channel's `interactiveCommand`).
+ *
+ * Walks the operator through:
+ *   1. verify the `signal-cli` binary is installed (install hint when missing),
+ *   2. store the account number (E.164) in the vault — no API token exists for
+ *      Signal; identity comes from device linking,
+ *   3. choose the autonomous tool allow-list,
+ *   4. hand off to the pair flow (QR link) when the account isn't linked yet,
+ *      or start the channel directly when it is.
+ */
+export async function runSignalWizard(ctx: ChannelSubcommandContext): Promise<number> {
+  const vault = ctx.deps.vault as VaultStore;
+  intro(bold('moxxy signal setup'));
+
+  const binary = findSignalCliOnPath();
+  if (!binary) {
+    log.error(SIGNAL_CLI_INSTALL_HINT);
+    return 1;
+  }
+  log.success(`Found signal-cli: ${binary}`);
+
+  note(
+    'moxxy joins your Signal account as a LINKED DEVICE (like Signal Desktop).\n' +
+      'It will see the messages your account receives, so it runs on its own\n' +
+      'dedicated, isolated runner. After linking, message your own "Note to Self"\n' +
+      'to talk to moxxy; other senders must be allow-listed explicitly.',
+    'how the Signal channel works',
+  );
+
+  const existing = await vault.get(SIGNAL_ACCOUNT_KEY);
+  const account = await text({
+    message: 'Your Signal account number (E.164)',
+    placeholder: '+15551234567',
+    ...(existing ? { initialValue: existing } : {}),
+    validate: (v) => {
+      if (!v || !v.trim()) return 'required';
+      if (!E164_RE.test(v.trim())) return 'expected E.164, e.g. +15551234567';
+      return undefined;
+    },
+  });
+  if (isCancel(account)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const accountNumber = String(account).trim();
+  await vault.set(SIGNAL_ACCOUNT_KEY, accountNumber, ['signal']);
+  log.success(`Stored account ${accountNumber} in the vault.`);
+
+  const allow = await text({
+    message: 'Autonomous tool allow-list (comma-separated; "*" = all, blank = read-only)',
+    placeholder: 'Read, Grep, Glob',
+  });
+  if (isCancel(allow)) {
+    cancel('cancelled.');
+    return 0;
+  }
+  const allowedTools = String(allow)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  // Linked already? (one-shot listAccounts spawn; on probe failure fall through
+  // to the pair flow, which handles the already-linked case gracefully too).
+  let linked = false;
+  try {
+    linked = (await listSignalAccounts({ binary })).includes(accountNumber);
+  } catch {
+    linked = false;
+  }
+
+  if (linked) {
+    log.info('This machine is already linked. Starting the channel…');
+    outro(dim('handing off to the channel…'));
+    return ctx.startChannel({ allowedTools });
+  }
+
+  note(
+    'Next: link this machine to your Signal account. A QR will appear —\n' +
+      'on your phone open Signal → Settings → Linked Devices → Link New Device\n' +
+      'and scan it. signal-cli keeps the linked-device keys in\n' +
+      '~/.local/share/signal-cli/ (moxxy stores only the number + allow-list).',
+    'link your phone',
+  );
+  outro(dim('opening the linking QR…'));
+  return runSignalPairFlow(ctx, { allowedTools });
+}