switchroom 0.14.61 → 0.14.62

package/telegram-plugin/gateway/with-deadline.ts

@@ -0,0 +1,43 @@
+/**
+ * withDeadline — bound a promise so the chain off it ALWAYS settles within `ms`.
+ *
+ * Why this exists (the obligation-ledger determinism hole): the escalation send
+ * in `obligationSweep` is fire-and-forget and clears its in-flight guard
+ * (`obligationEscalateInFlight`) only in a `.finally` — which runs only if the
+ * awaited promise SETTLES. grammy's `bot.api` has no request timeout
+ * (`new Bot(TOKEN)`, no `client.timeoutSeconds`) and `retryApiCall`'s `await
+ * fn()` does not bound a hang (its retry cap applies to rejections, not to a
+ * promise that never resolves). So a stalled send (half-open TCP, unresponsive
+ * Telegram) would never settle → `.finally` never fires → the in-flight id is
+ * leaked forever → every later sweep early-returns at the guard → the
+ * obligation is stuck OPEN: never re-presented, never escalated, never closed.
+ * That is a silent loss of the "every inbound is answered-or-escalated"
+ * guarantee — the one liveness hole a total state-machine proof surfaced (a
+ * sampling test cannot, because its model never includes "send never settles").
+ *
+ * Racing the send against a deadline makes the wait bounded BY CONSTRUCTION:
+ * the returned promise settles in ≤ `ms`, so the caller's `.then/.catch/.finally`
+ * always run and the in-flight flag always clears. A hang becomes a bounded
+ * rejection that feeds the already-bounded escalate ladder
+ * (`escalateAttempts → OBLIGATION_ESCALATE_MAX`) to a terminal. The losing
+ * (still-pending) promise is given a no-op `.catch` so its eventual rejection
+ * is not an unhandled rejection, and the timer is cleared + unref'd so it
+ * neither leaks nor keeps the event loop alive.
+ *
+ * Pure (no gateway/Telegram coupling) ⇒ unit-testable; see
+ * tests/with-deadline.test.ts.
+ */
+export function withDeadline<T>(p: Promise<T>, ms: number, timeoutMessage: string): Promise<T> {
+  // Swallow a late rejection from the loser after the race has already settled,
+  // so a hung-then-eventually-rejected send is never an unhandled rejection.
+  p.catch(() => {})
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(timeoutMessage)), ms)
+    // Don't keep the process alive solely for this timer.
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+  })
+  return Promise.race([p, deadline]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer)
+  }) as Promise<T>
+}

package/telegram-plugin/tests/microsoft-connect-flow.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  startMicrosoftConnect,
+  runMicrosoftConnectPoll,
+} from '../gateway/microsoft-connect-flow.js'
+import { DEFAULT_MICROSOFT_CLIENT_ID } from '../../src/auth/default-oauth-clients.js'
+import type {
+  MicrosoftDeviceCodeResponse,
+  MicrosoftOAuthClientConfig,
+  MicrosoftTokenResponse,
+} from '../../src/microsoft/oauth.js'
+
+const PERSONAL_MSA_TID = '9188040d-6c67-4c5b-b112-36a304b66dad'
+
+const DEVICE: MicrosoftDeviceCodeResponse = {
+  device_code: 'dc-abc',
+  user_code: 'ABCD-EFGH',
+  verification_uri: 'https://microsoft.com/devicelogin',
+  expires_in: 900,
+  interval: 5,
+}
+
+function fakeIdToken(payload: Record<string, unknown>): string {
+  const b64 = (o: unknown) => Buffer.from(JSON.stringify(o)).toString('base64url')
+  return `${b64({ alg: 'none' })}.${b64(payload)}.sig`
+}
+
+describe('startMicrosoftConnect', () => {
+  it('uses the shipped default client_id + default scopes when there is no config', async () => {
+    let seen: MicrosoftOAuthClientConfig | undefined
+    const res = await startMicrosoftConnect({
+      requestDeviceCode: async (cfg) => {
+        seen = cfg
+        return DEVICE
+      },
+    })
+    expect(res.kind).toBe('started')
+    if (res.kind === 'started') {
+      expect(res.source).toBe('default')
+      expect(res.clientId).toBe(DEFAULT_MICROSOFT_CLIENT_ID)
+      expect(res.scopes).toContain('offline_access')
+      expect(res.device.user_code).toBe('ABCD-EFGH')
+    }
+    expect(seen?.client_id).toBe(DEFAULT_MICROSOFT_CLIENT_ID)
+  })
+
+  it('refuses a vaulted BYO client (gateway can\'t resolve vault refs)', async () => {
+    const res = await startMicrosoftConnect({
+      configClientId: 'vault:microsoft-oauth-client-id',
+      requestDeviceCode: async () => DEVICE,
+    })
+    expect(res.kind).toBe('byo-vault')
+    if (res.kind === 'byo-vault') {
+      expect(res.ref).toBe('vault:microsoft-oauth-client-id')
+    }
+  })
+
+  it('uses a literal BYO config client_id (source=config)', async () => {
+    const res = await startMicrosoftConnect({
+      configClientId: 'byo-literal-123',
+      requestDeviceCode: async () => DEVICE,
+    })
+    expect(res.kind).toBe('started')
+    if (res.kind === 'started') {
+      expect(res.source).toBe('config')
+      expect(res.clientId).toBe('byo-literal-123')
+    }
+  })
+
+  it('returns an error when the device-code request fails', async () => {
+    const res = await startMicrosoftConnect({
+      requestDeviceCode: async () => {
+        throw new Error('device_code request failed (400): boom')
+      },
+    })
+    expect(res.kind).toBe('error')
+    if (res.kind === 'error') expect(res.message).toContain('boom')
+  })
+})
+
+describe('runMicrosoftConnectPoll', () => {
+  const flow = {
+    device: DEVICE,
+    clientId: 'client-1',
+    scopes: ['offline_access', 'Mail.ReadWrite'],
+    cancelled: false,
+  }
+
+  function tokens(o: Partial<MicrosoftTokenResponse> = {}): MicrosoftTokenResponse {
+    return {
+      access_token: 'at',
+      refresh_token: 'rt',
+      expires_in: 3600,
+      token_type: 'Bearer',
+      scope: 'Mail.ReadWrite',
+      ...o,
+    }
+  }
+
+  it('connects: registers the account via the broker keyed by the authenticated email', async () => {
+    const id_token = fakeIdToken({
+      tid: PERSONAL_MSA_TID,
+      oid: 'oid-1',
+      preferred_username: 'Lisa@Outlook.com',
+    })
+    const calls: Array<{ label: string; opts: unknown; refreshToken: string }> = []
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => tokens({ id_token }),
+      addAccount: async (label, creds, opts) => {
+        calls.push({
+          label,
+          opts,
+          refreshToken: creds.microsoftOauth.refreshToken,
+        })
+        return { label }
+      },
+    })
+    expect(res.kind).toBe('connected')
+    if (res.kind === 'connected') {
+      expect(res.account).toBe('lisa@outlook.com')
+      expect(res.accountType).toBe('personal')
+    }
+    expect(calls).toHaveLength(1)
+    expect(calls[0].label).toBe('lisa@outlook.com')
+    expect(calls[0].opts).toEqual({ provider: 'microsoft', replace: true })
+    expect(calls[0].refreshToken).toBe('rt')
+  })
+
+  it('cancelled: does NOT register if the flow was cancelled during the poll', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(
+      { ...flow, cancelled: true },
+      {
+        pollDeviceToken: async () => tokens(),
+        addAccount: async () => {
+          added = true
+          return { label: 'x' }
+        },
+      },
+    )
+    expect(res.kind).toBe('cancelled')
+    expect(added).toBe(false)
+  })
+
+  it('no-refresh-token: refuses to register an un-refreshable account', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => tokens({ refresh_token: undefined }),
+      addAccount: async () => {
+        added = true
+        return { label: 'x' }
+      },
+    })
+    expect(res.kind).toBe('no-refresh-token')
+    expect(added).toBe(false)
+  })
+
+  it('failed: surfaces a poll error (e.g. a work account rejected at /common)', async () => {
+    const res = await runMicrosoftConnectPoll(flow, {
+      pollDeviceToken: async () => {
+        throw new Error('Token poll failed: AADSTS9001023 work account')
+      },
+      addAccount: async () => ({ label: 'x' }),
+    })
+    expect(res.kind).toBe('failed')
+    if (res.kind === 'failed') expect(res.message).toContain('AADSTS9001023')
+  })
+
+  it('failed: refuses to register when Microsoft returns no id_token (no account identity)', async () => {
+    let added = false
+    const res = await runMicrosoftConnectPoll(flow, {
+      // Has a refresh token but no id_token → no resolvable email to key
+      // the broker account by; must NOT register a label-less account.
+      pollDeviceToken: async () => tokens({ id_token: undefined }),
+      addAccount: async () => {
+        added = true
+        return { label: 'x' }
+      },
+    })
+    expect(res.kind).toBe('failed')
+    if (res.kind === 'failed') expect(res.message).toContain('account identity')
+    expect(added).toBe(false)
+  })
+})

package/telegram-plugin/tests/obligation-determinism.test.ts

@@ -7,30 +7,30 @@ import {
 } from "../gateway/obligation-store.js";
 
 /**
- * DETERMINISM PROOF (by exhaustive simulation, not live observation).
+ * REGRESSION GUARD — not the proof.
  *
- * The operator's requirement: be confident — by reasoning — that EVERY real
- * inbound reaches answered-or-escalated for ANY model behaviour and ANY timing,
- * including across a restart, with no silent drop and no double-ask of a message
- * that WAS answered.
+ * The actual determinism argument is closed-form and lives WITH the code: the
+ * ledger is a finite FSM with a total transition function and a strictly-
+ * decreasing measure μ = (REPRESENT_MAX - representCount) + (ESCALATE_MAX -
+ * escalateAttempts) ⇒ every OPEN reaches a terminal (see the proof comment on
+ * obligationSweep in gateway.ts and the ledger methods in obligation-ledger.ts).
+ * A total state-machine proof also found — and a fix closed — the one liveness
+ * hole this kind of SAMPLING test structurally cannot reach: a hung escalation
+ * send leaking the in-flight flag (now bounded by withDeadline; guarded by
+ * with-deadline.test.ts). The lesson stands: a random-schedule test only
+ * exercises the behaviours its model encodes; it is evidence, never the proof.
  *
- * This drives the REAL ObligationLedger + the REAL durable snapshot store
- * (obligation-store, over an in-memory fs whose rename is atomic) through a
- * faithful model of the gateway's obligation lifecycle:
- *
- *   OPEN     — on receipt (handleInbound, idempotent).
- *   close    — at turn_end iff the turn delivered a final answer (finalAnswerDelivered).
- *   represent— idle sweep, bounded by maxRepresents, drives a fresh must-answer turn.
- *   escalate — ladder exhausted: send the operator nudge; close ONLY after it
- *              lands; a transient send failure stays OPEN and retries; a permanent
- *              one is bounded (OBLIGATION_ESCALATE_MAX) → close best-effort.
- *   restart  — fresh ledger hydrated from the durable snapshot (counters intact).
- *
- * Over thousands of random schedules it asserts the invariant holds and the
- * engine always terminates (no infinite loop). The COALESCED PARTIAL-ANSWER
- * residual is deliberately NOT modelled — it is the one honest hard limit (a
- * turn-keyed ledger cannot see "answered half" without parsing model prose) and
- * is mitigated by coalescing policy, not the ledger.
+ * What this file still earns its keep doing: drive the REAL ObligationLedger +
+ * REAL durable snapshot store over many random {model-behaviour × timing ×
+ * restart} schedules to catch a regression that breaks the FSM invariant
+ * (no silent drop, no double-ask of an answered message, bounded termination).
+ * It models the lifecycle SYNCHRONOUSLY (open at receipt; close at turn_end on a
+ * delivered answer; bounded represent→escalate; restart = hydrate from snapshot)
+ * — so it does NOT and cannot cover async/coupling liveness (hung send, gate
+ * never opening, drain wedging); those are proven/bounded in the code, not here.
+ * The coalesced PARTIAL-ANSWER residual is also out of model — the one honest
+ * hard limit (a turn-keyed ledger can't see "answered half" without parsing the
+ * model's prose), mitigated by coalescing policy, not the ledger.
  */
 
 // Mirrors the gateway constants under test.

package/telegram-plugin/tests/with-deadline.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { withDeadline } from "../gateway/with-deadline.js";
+
+const tick = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("withDeadline — bounds the obligation escalation send so a hang can't leak the in-flight flag", () => {
+  it("resolves with the inner value when the promise settles before the deadline", async () => {
+    await expect(withDeadline(Promise.resolve("ok"), 1000, "timed out")).resolves.toBe("ok");
+  });
+
+  it("rejects with the inner error when the promise rejects before the deadline", async () => {
+    await expect(withDeadline(Promise.reject(new Error("boom")), 1000, "timed out")).rejects.toThrow(
+      "boom",
+    );
+  });
+
+  it("rejects with the timeout message when the promise NEVER settles (the hang case)", async () => {
+    // The whole point: a promise that never resolves/rejects (a stalled send)
+    // must still settle the chain so the caller's .finally clears the in-flight flag.
+    const neverSettles = new Promise<string>(() => {});
+    await expect(withDeadline(neverSettles, 20, "obligation escalation send timed out")).rejects.toThrow(
+      "obligation escalation send timed out",
+    );
+  });
+
+  it("the .finally chained after it ALWAYS runs even when the inner promise hangs", async () => {
+    // This mirrors the gateway's obligationEscalateInFlight clear: it lives in a
+    // .finally on withDeadline(...), and must fire within the deadline regardless.
+    let flagCleared = false;
+    await withDeadline(new Promise<void>(() => {}), 20, "timed out")
+      .catch(() => {})
+      .finally(() => {
+        flagCleared = true;
+      });
+    expect(flagCleared).toBe(true);
+  });
+
+  it("a hung-then-late-rejecting inner promise does not produce an unhandled rejection", async () => {
+    const seen: unknown[] = [];
+    const onUnhandled = (reason: unknown) => seen.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+      const lateReject = new Promise<void>((_, reject) => {
+        setTimeout(() => reject(new Error("late-zombie-rejection")), 30);
+      });
+      // withDeadline rejects at 10ms; the inner promise rejects later at 30ms.
+      await withDeadline(lateReject, 10, "timed out").catch(() => {});
+      await tick(60); // let the late rejection fire
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+    expect(seen.some((r) => r instanceof Error && r.message === "late-zombie-rejection")).toBe(false);
+  });
+
+  it("clears its timer on a fast settle (no dangling work keeps the loop alive)", async () => {
+    // Sanity: a fast resolve settles immediately, not after the deadline.
+    const start = Date.now();
+    await withDeadline(Promise.resolve(1), 5000, "timed out");
+    expect(Date.now() - start).toBeLessThan(500);
+  });
+});