@celilo/cli 0.13.2 → 0.14.0

package/src/services/alerting/inbound-poller.ts

@@ -0,0 +1,236 @@
+/**
+ * The inbound poller — reading replies back off a transport.
+ *
+ * celilo-mgr polls the transport; the transport never calls in. That direction
+ * matters: an inbound webhook would need public HTTPS, which means caddy, DNS
+ * and a certificate — so the ack path would depend on the very infrastructure
+ * being paged about. Polling needs none of it.
+ *
+ * Runs on a short interval (seconds, not the five-minute sweep) because "I
+ * texted ack and nothing happened" is the whole experience being bought here.
+ * It is an ordinary interval inside an already-supervised process, not a new
+ * bus primitive.
+ */
+
+import type { InboundMessage, NotificationCapability } from '@celilo/capabilities';
+import { and, eq, gt, isNull } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { type Route, modules, notificationDeliveries, people, routes } from '../../db/schema';
+import { loadCapabilityFunctions } from '../../hooks/capability-loader';
+import { createCapturingLogger } from '../../hooks/logger';
+import { type AckResult, acknowledgeAlert } from './ack';
+import { interpretInbound } from './inbound';
+import { parseInterviewAnswer } from './interview-responder';
+import type { NotificationTransport } from './notifier';
+import { composeAckBroadcastBody } from './notifier';
+import { consumeDelivery } from './tokens';
+
+export interface InboundPollDeps {
+  /** Receive from one transport module, or null when it cannot be reached. */
+  receiveFrom(
+    transportModuleId: string,
+    cursor: string | null,
+  ): Promise<{ messages: InboundMessage[]; cursor: string | null } | null>;
+  /** Persisted receive cursor per transport. */
+  readCursor(transportModuleId: string): string | null;
+  writeCursor(transportModuleId: string, cursor: string | null): void;
+  now(): Date;
+  /**
+   * Transport for a route, so an ack can be broadcast to everyone else paged.
+   * Optional: an installation with no send path still acks correctly, it just
+   * cannot tell the others.
+   */
+  transportFor?(route: Route): NotificationTransport;
+  /**
+   * Publish an interview answer against the waiting bus question. Optional:
+   * an installation with no responder attached still acks alerts, it just
+   * cannot answer deploy questions.
+   */
+  answerInterview?(eventId: string, value: string): void;
+}
+
+export interface InboundPollReport {
+  transportsPolled: number;
+  messagesRead: number;
+  acked: number;
+  ignored: number;
+  rejected: number;
+  /** Routes told that someone else took the alert. */
+  broadcast: number;
+  /** Deploy questions answered from a phone. */
+  answered: number;
+}
+
+/** Transports that have at least one route pointing at them. */
+export function transportsWithRoutes(db: DbClient): string[] {
+  const ids = new Set(
+    db
+      .select({ id: routes.transportModuleId })
+      .from(routes)
+      .where(eq(routes.enabled, true))
+      .all()
+      .map((r) => r.id),
+  );
+  return [...ids];
+}
+
+/**
+ * Poll every transport once and apply what came back.
+ *
+ * At-least-once is fine and exactly-once is not attempted: the cursor is
+ * persisted after processing, so a crash mid-batch replays it. Every action
+ * below is idempotent — consuming an already-consumed token finds nothing,
+ * and acking an already-acked alert re-writes the same row — so a replay is
+ * harmless. Trying for exactly-once would add machinery to prevent something
+ * that does not hurt.
+ */
+export async function pollInbound(db: DbClient, deps: InboundPollDeps): Promise<InboundPollReport> {
+  const report: InboundPollReport = {
+    transportsPolled: 0,
+    messagesRead: 0,
+    acked: 0,
+    ignored: 0,
+    rejected: 0,
+    broadcast: 0,
+    answered: 0,
+  };
+
+  for (const transportId of transportsWithRoutes(db)) {
+    const received = await deps.receiveFrom(transportId, deps.readCursor(transportId));
+    report.transportsPolled++;
+    // A transport that cannot be reached is not an error here — its own
+    // health check is what reports that, and one dead transport must not stop
+    // the others from being read.
+    if (!received) continue;
+
+    for (const message of received.messages) {
+      report.messagesRead++;
+
+      const outcome = interpretInbound(db, {
+        senderAddress: message.senderAddress,
+        body: message.body,
+        now: deps.now(),
+        outstandingForRoute: (routeId) => outstandingAlertDeliveries(db, routeId, deps.now()),
+      });
+
+      if (outcome.action === 'ignored') {
+        report.ignored++;
+        continue;
+      }
+      if (outcome.action === 'rejected') {
+        report.rejected++;
+        continue;
+      }
+
+      // An interview reply IS the answer rather than an acknowledgement —
+      // same token table, same sender check, different meaning for the body.
+      if (outcome.delivery.kind === 'interview') {
+        const value = parseInterviewAnswer(message.body, outcome.delivery.token);
+        if (!value || !deps.answerInterview) {
+          report.rejected++;
+          continue;
+        }
+        consumeDelivery(db, outcome.delivery.id, deps.now());
+        deps.answerInterview(outcome.delivery.targetId, value);
+        report.answered++;
+        continue;
+      }
+
+      // Consume first: a token is single-use, and a crash after acking but
+      // before consuming would let the same token act twice.
+      consumeDelivery(db, outcome.delivery.id, deps.now());
+      const ack = acknowledgeAlert(
+        db,
+        outcome.delivery.targetId,
+        outcome.route.personId,
+        deps.now(),
+      );
+      report.acked++;
+
+      // Everyone else who was paged is still expecting to act. Telling them is
+      // the entire point of a per-delivery token — it is what makes the reply
+      // identify a PERSON rather than just an alert.
+      if (ack) report.broadcast += await broadcastAck(db, ack, deps);
+    }
+
+    deps.writeCursor(transportId, received.cursor);
+  }
+
+  return report;
+}
+
+/**
+ * Tell every other paged route who took the alert.
+ *
+ * Best-effort per route: one unreachable phone must not stop the others being
+ * told, and the ack itself has already been recorded either way.
+ */
+async function broadcastAck(db: DbClient, ack: AckResult, deps: InboundPollDeps): Promise<number> {
+  if (!deps.transportFor || ack.broadcastTo.length === 0) return 0;
+
+  const acknowledger = ack.alert.ackedBy
+    ? db.select().from(people).where(eq(people.id, ack.alert.ackedBy)).get()?.name
+    : undefined;
+
+  let sent = 0;
+  for (const routeId of ack.broadcastTo) {
+    const route = db.select().from(routes).where(eq(routes.id, routeId)).get();
+    if (!route) continue;
+    try {
+      await deps.transportFor(route).send({
+        address: route.address,
+        body: composeAckBroadcastBody(ack.alert, acknowledger ?? 'Someone'),
+      });
+      sent++;
+    } catch {
+      // See above: the ack stands regardless of who could be reached.
+    }
+  }
+  return sent;
+}
+
+/**
+ * Live alert deliveries outstanding for a route — what a bare `ack` with no
+ * token could be referring to.
+ */
+function outstandingAlertDeliveries(db: DbClient, routeId: string, now: Date) {
+  return db
+    .select()
+    .from(notificationDeliveries)
+    .where(
+      and(
+        eq(notificationDeliveries.routeId, routeId),
+        eq(notificationDeliveries.kind, 'alert'),
+        isNull(notificationDeliveries.consumedAt),
+        gt(notificationDeliveries.expiresAt, now),
+      ),
+    )
+    .all();
+}
+
+/**
+ * Build the real receive function for a transport.
+ *
+ * A transport with no `receive` is unidirectional — that is not an error, it
+ * just means replies cannot arrive, which the route's `can_ack` already
+ * records.
+ */
+export function makeReceiver(db: DbClient) {
+  return async (transportModuleId: string, cursor: string | null) => {
+    const module = db.select().from(modules).where(eq(modules.id, transportModuleId)).get();
+    if (!module) return null;
+
+    try {
+      const { logger } = createCapturingLogger();
+      const capabilities = await loadCapabilityFunctions(transportModuleId, db, logger);
+      const notification = (capabilities as Record<string, unknown>).notification as
+        | NotificationCapability
+        | undefined;
+      if (!notification?.receive) return null;
+      return await notification.receive(cursor);
+    } catch {
+      // Unreachable transport: the transport's own health check reports it.
+      return null;
+    }
+  };
+}

package/src/services/alerting/inbound.test.ts

@@ -0,0 +1,201 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { DbClient } from '../../db/client';
+import { type NotificationDelivery, modules, people, routes } from '../../db/schema';
+import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { interpretInbound, parseInbound } from './inbound';
+import { mintDelivery } from './tokens';
+
+const NOW = new Date('2026-07-28T03:00:00Z');
+const TTL_MS = 24 * 60 * 60_000;
+
+const PETER = '+15550001';
+const WIFE = '+15550002';
+const STRANGER = '+15559999';
+
+describe('parseInbound', () => {
+  test.each(['ack', 'ACK', 'ok', 'K', '  ack  ', '👍'])('%p is a bare ack', (body) => {
+    expect(parseInbound(body)).toEqual({ kind: 'bare_ack' });
+  });
+
+  test('a bare token acknowledges', () => {
+    expect(parseInbound('K7QM2X')).toEqual({ kind: 'ack', token: 'K7QM2X' });
+  });
+
+  test('a token typed in lower case still parses', () => {
+    expect(parseInbound('k7qm2x')).toEqual({ kind: 'ack', token: 'K7QM2X' });
+  });
+
+  // The verb is optional in v1 — people will type it anyway.
+  test('a trailing verb is accepted and ignored', () => {
+    expect(parseInbound('K7QM2X ack')).toEqual({ kind: 'ack', token: 'K7QM2X' });
+  });
+
+  test.each(['', '   ', 'what is going on', 'K7QM', 'K7QM2XY'])('%p is unrecognised', (body) => {
+    expect(parseInbound(body)).toEqual({ kind: 'unrecognised' });
+  });
+});
+
+describe('interpretInbound', () => {
+  let dir: string;
+  let db: DbClient;
+
+  const outstanding: NotificationDelivery[] = [];
+  const context = (senderAddress: string, body: string) => ({
+    senderAddress,
+    body,
+    now: NOW,
+    outstandingForRoute: (routeId: string) => outstanding.filter((d) => d.routeId === routeId),
+  });
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'inbound-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabase(dbPath);
+    outstanding.length = 0;
+
+    db.insert(modules)
+      .values({
+        id: 'signal',
+        name: 'Signal',
+        version: '1.0.0',
+        manifestData: {},
+        sourcePath: '/tmp/signal',
+      })
+      .run();
+    db.insert(people).values({ id: 'p1', name: 'peter', timezone: 'UTC' }).run();
+    db.insert(people).values({ id: 'p2', name: 'wife', timezone: 'UTC' }).run();
+    db.insert(routes)
+      .values({ id: 'r-peter', personId: 'p1', transportModuleId: 'signal', address: PETER })
+      .run();
+    db.insert(routes)
+      .values({ id: 'r-wife', personId: 'p2', transportModuleId: 'signal', address: WIFE })
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  const mintFor = (routeId: string, targetId = 'alert-1') =>
+    mintDelivery(db, { kind: 'alert', targetId, routeId, now: NOW, ttlMs: TTL_MS });
+
+  test('a valid token from the right sender acknowledges', () => {
+    const delivery = mintFor('r-peter');
+    const outcome = interpretInbound(db, context(PETER, delivery.token));
+    expect(outcome).toMatchObject({ action: 'ack' });
+    expect(outcome.action === 'ack' && outcome.route.id).toBe('r-peter');
+  });
+
+  // Factor two. A token glimpsed over a shoulder is useless from another phone.
+  test('a valid token from the WRONG sender is refused', () => {
+    const delivery = mintFor('r-peter');
+    expect(interpretInbound(db, context(WIFE, delivery.token))).toEqual({
+      action: 'rejected',
+      reason: 'wrong_sender',
+    });
+  });
+
+  // Silence, not a reply — a reply confirms the number is live and that this
+  // is a celilo instance.
+  test('a message from an unknown number is ignored, not answered', () => {
+    const delivery = mintFor('r-peter');
+    expect(interpretInbound(db, context(STRANGER, delivery.token))).toEqual({
+      action: 'ignored',
+      reason: 'unknown_sender',
+    });
+  });
+
+  test('an unknown token from a known sender is rejected', () => {
+    expect(interpretInbound(db, context(PETER, 'ZZZZZZ'))).toEqual({
+      action: 'rejected',
+      reason: 'unknown_token',
+    });
+  });
+
+  test('an expired token is rejected', () => {
+    const delivery = mintFor('r-peter');
+    const late = { ...context(PETER, delivery.token), now: new Date(NOW.getTime() + TTL_MS + 1) };
+    expect(interpretInbound(db, late)).toEqual({ action: 'rejected', reason: 'unknown_token' });
+  });
+
+  test('gibberish from a known sender is rejected as unrecognised', () => {
+    expect(interpretInbound(db, context(PETER, 'what is going on'))).toEqual({
+      action: 'rejected',
+      reason: 'unrecognised',
+    });
+  });
+
+  describe('bare ack', () => {
+    test('works when exactly one delivery is outstanding', () => {
+      outstanding.push(mintFor('r-peter'));
+      const outcome = interpretInbound(db, context(PETER, 'ack'));
+      expect(outcome).toMatchObject({ action: 'ack' });
+    });
+
+    // Guessing which alert they meant would ack the wrong one.
+    test('is refused as ambiguous when several are outstanding', () => {
+      outstanding.push(mintFor('r-peter', 'alert-1'));
+      outstanding.push(mintFor('r-peter', 'alert-2'));
+      expect(interpretInbound(db, context(PETER, 'ack'))).toEqual({
+        action: 'rejected',
+        reason: 'ambiguous',
+      });
+    });
+
+    test('is refused when nothing is outstanding', () => {
+      expect(interpretInbound(db, context(PETER, 'ack'))).toEqual({
+        action: 'rejected',
+        reason: 'unknown_token',
+      });
+    });
+
+    // Another person's outstanding page is not this person's to ack blindly.
+    test('only considers the sender own outstanding deliveries', () => {
+      outstanding.push(mintFor('r-wife'));
+      expect(interpretInbound(db, context(PETER, 'ack'))).toEqual({
+        action: 'rejected',
+        reason: 'unknown_token',
+      });
+    });
+  });
+});
+
+/**
+ * An earlier cut ignored any verb after the token, so `<token> resolve`
+ * silently ACKNOWLEDGED — the operator believes they cleared the alert while it
+ * is still firing. Raised in review of #420.
+ */
+describe('reply verbs', () => {
+  test('a bare token acknowledges', () => {
+    expect(parseInbound('K7QM2X')).toEqual({ kind: 'ack', token: 'K7QM2X' });
+  });
+
+  test('an explicit ack synonym acknowledges', () => {
+    for (const verb of ['ack', 'ok', 'k', '👍']) {
+      expect(parseInbound(`K7QM2X ${verb}`)).toEqual({ kind: 'ack', token: 'K7QM2X' });
+    }
+  });
+
+  // Doing nothing and saying so beats doing the wrong thing quietly.
+  test('resolve is REJECTED rather than treated as an ack', () => {
+    expect(parseInbound('K7QM2X resolve')).toEqual({ kind: 'unrecognised' });
+  });
+
+  test('silence is REJECTED rather than treated as an ack', () => {
+    expect(parseInbound('K7QM2X silence 2h')).toEqual({ kind: 'unrecognised' });
+  });
+
+  test('a typo after the token is rejected, not guessed at', () => {
+    expect(parseInbound('K7QM2X akc')).toEqual({ kind: 'unrecognised' });
+  });
+});

package/src/services/alerting/inbound.ts

@@ -0,0 +1,112 @@
+/**
+ * Inbound replies — turning a message from a phone into an acknowledgement.
+ *
+ * Authentication is two factors, both cheap:
+ *
+ *   1. the token must be valid, unexpired, and unconsumed
+ *   2. the SENDER must be the address that token was issued to
+ *
+ * Either alone is insufficient. A token seen over someone's shoulder is
+ * useless from another number; a known number is useless without a live token.
+ *
+ * A message from an address matching no route is discarded and logged WITHOUT
+ * a reply. Replying would confirm the number is live and that this is a celilo
+ * instance, which is free reconnaissance for anyone probing.
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { type NotificationDelivery, type Route, routes } from '../../db/schema';
+import { findLiveDelivery, normaliseToken } from './tokens';
+
+/**
+ * v1 grammar: a bare token acknowledges. `snooze` and `resolve` verbs are
+ * deferred — ack is what an operator does at 3am, and every extra verb is
+ * another thing to mistype under stress.
+ *
+ * A bare `ack` with no token is accepted when the sender has exactly one
+ * outstanding delivery, since the token adds nothing when there is no ambiguity.
+ */
+export type InboundIntent =
+  | { kind: 'ack'; token: string }
+  | { kind: 'bare_ack' }
+  | { kind: 'unrecognised' };
+
+const ACK_VERB = /^(ack|ok|k|👍)$/iu;
+const TOKEN_SHAPE = /^[0-9ABCDEFGHJKMNPQRSTVWXYZ]{6}$/;
+
+export function parseInbound(body: string): InboundIntent {
+  const trimmed = body.trim();
+  if (!trimmed) return { kind: 'unrecognised' };
+
+  if (ACK_VERB.test(trimmed)) return { kind: 'bare_ack' };
+
+  const [first, ...rest] = trimmed.split(/\s+/);
+  const token = normaliseToken(first);
+  if (!TOKEN_SHAPE.test(token)) return { kind: 'unrecognised' };
+
+  // A verb after the token must be an ack synonym or nothing. An earlier cut
+  // ignored the verb entirely, which meant `<token> resolve` silently
+  // ACKNOWLEDGED — the operator believes they cleared the alert and it is
+  // still firing. Doing nothing and saying so is strictly better than doing
+  // the wrong thing quietly.
+  //
+  // `resolve` and `silence` are terminal operations, not reply verbs (design
+  // D10): every extra verb is another thing to mistype at 3am.
+  if (rest.length > 0 && !ACK_VERB.test(rest.join(' '))) {
+    return { kind: 'unrecognised' };
+  }
+
+  return { kind: 'ack', token };
+}
+
+export type InboundOutcome =
+  | { action: 'ack'; delivery: NotificationDelivery; route: Route }
+  | { action: 'ignored'; reason: 'unknown_sender' }
+  | { action: 'rejected'; reason: 'unknown_token' | 'wrong_sender' | 'ambiguous' | 'unrecognised' };
+
+function routeForAddress(db: DbClient, senderAddress: string): Route | undefined {
+  return db.select().from(routes).where(eq(routes.address, senderAddress)).get();
+}
+
+export interface InboundContext {
+  senderAddress: string;
+  body: string;
+  now: Date;
+  /** Live alert-kind deliveries outstanding for this route, newest first. */
+  outstandingForRoute(routeId: string): NotificationDelivery[];
+}
+
+/**
+ * Decide what an inbound message means.
+ *
+ * Returns the action to take; the caller performs it. Keeping the decision
+ * separate is what lets every rejection path be asserted without a transport.
+ */
+export function interpretInbound(db: DbClient, context: InboundContext): InboundOutcome {
+  const route = routeForAddress(db, context.senderAddress);
+
+  // Unknown sender: drop silently. No reply, by design.
+  if (!route) return { action: 'ignored', reason: 'unknown_sender' };
+
+  const intent = parseInbound(context.body);
+
+  if (intent.kind === 'unrecognised') {
+    return { action: 'rejected', reason: 'unrecognised' };
+  }
+
+  if (intent.kind === 'bare_ack') {
+    const outstanding = context.outstandingForRoute(route.id);
+    if (outstanding.length === 0) return { action: 'rejected', reason: 'unknown_token' };
+    if (outstanding.length > 1) return { action: 'rejected', reason: 'ambiguous' };
+    return { action: 'ack', delivery: outstanding[0], route };
+  }
+
+  const delivery = findLiveDelivery(db, intent.token, context.now);
+  if (!delivery) return { action: 'rejected', reason: 'unknown_token' };
+
+  // Factor two: a valid token replayed from a different number is refused.
+  if (delivery.routeId !== route.id) return { action: 'rejected', reason: 'wrong_sender' };
+
+  return { action: 'ack', delivery, route };
+}