viber-channel 0.5.1 → 0.5.2

package/lib/conversation.ts

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { cfAccessHeaders } from "./cfAccess.js";
+import { ConversationTokenExpiredError } from "./messages.js";
 
 export interface ConversationMintResponse {
   conversation_id: string;
@@ -76,6 +77,100 @@ export async function mintConversation(
   return (await resp.json()) as ConversationMintResponse;
 }
 
+export interface RefreshTokenResponse {
+  conversation_token: string;
+  expires_at: number;
+}
+
+/**
+ * HTTP failure from /refresh-token (any non-401 non-2xx). `.retryable` lets
+ * the scheduler distinguish a transient server hiccup (5xx, 408, 409) from a
+ * permanent state mismatch (4xx other than 401), so it can back off and try
+ * again instead of immediately ending the channel.
+ */
+export class RefreshHttpError extends Error {
+  status: number;
+  detail: string;
+  retryable: boolean;
+  constructor(status: number, detail: string) {
+    super(`Refresh failed (HTTP ${status}): ${detail}`);
+    this.name = "RefreshHttpError";
+    this.status = status;
+    this.detail = detail;
+    // 5xx, 408 (timeout), 409 (concurrent-refresh race) — server/transient.
+    // 4xx others (403 fingerprint mismatch, etc.) are permanent.
+    this.retryable = status >= 500 || status === 408 || status === 409;
+  }
+}
+
+/**
+ * Wrapper for `fetch` failures (DNS, connection reset, TLS, etc.). Always
+ * retryable — by definition we never got a server response to classify.
+ */
+export class RefreshNetworkError extends Error {
+  cause: unknown;
+  retryable: true = true as const;
+  constructor(cause: unknown) {
+    super(`Refresh failed: network error: ${String(cause)}`);
+    this.name = "RefreshNetworkError";
+    this.cause = cause;
+  }
+}
+
+/**
+ * POST /api/conversations/:conversationId/refresh-token
+ *
+ * Rotates the per-conversation token in place. Worker updates the row's
+ * token+expiry and returns the new pair. The caller (scheduler) propagates
+ * the new token to module state so subsequent requests use it.
+ *
+ * @throws ConversationTokenExpiredError on HTTP 401 (token is unknown or has
+ *   already been rotated away from the value sent in the Authorization header)
+ * @throws RefreshHttpError on any other non-2xx status — inspect `.retryable`
+ * @throws RefreshNetworkError on fetch-level failure (always retryable)
+ */
+export async function refreshConversationToken(
+  baseUrl: string,
+  conversationId: string,
+  currentToken: string,
+  fingerprint: string,
+): Promise<RefreshTokenResponse> {
+  let resp: Response;
+  try {
+    resp = await fetch(
+      `${baseUrl}/api/conversations/${conversationId}/refresh-token`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${currentToken}`,
+          "X-Client-Fingerprint": fingerprint,
+          "Content-Type": "application/json",
+          ...cfAccessHeaders(),
+        },
+        body: "{}",
+      },
+    );
+  } catch (err) {
+    throw new RefreshNetworkError(err);
+  }
+
+  if (resp.status === 401) {
+    throw new ConversationTokenExpiredError();
+  }
+
+  if (!resp.ok) {
+    let detail = "";
+    try {
+      detail = await resp.text();
+    } catch {
+      // ignore
+    }
+    throw new RefreshHttpError(resp.status, detail);
+  }
+
+  return (await resp.json()) as RefreshTokenResponse;
+}
+
 export function defaultLabel(folderPath: string): string {
   const folder = basename(folderPath);
   // Local time, not UTC — the user sees this label in the UI; UTC was confusing.

package/lib/token_refresh.ts

@@ -0,0 +1,104 @@
+/**
+ * Token refresh scheduler — single-responsibility module.
+ *
+ * Fires a `refresh()` callback shortly before the conversation token expires,
+ * re-schedules itself on success, and routes failures to `onFailure()`. No
+ * knowledge of the worker, MCP server, or any channel module state.
+ */
+
+export interface TokenRefreshState {
+  /** Unix seconds — the new expiry returned by the refresh callback. */
+  expiresAt: number;
+}
+
+export interface TokenRefreshDeps {
+  /** Returns current time in unix seconds. Defaults to Date.now()/1000. */
+  now?: () => number;
+  /** Schedules a callback after `ms` milliseconds. Defaults to setTimeout. */
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  /** Cancels a previously-scheduled timer. Defaults to clearTimeout. */
+  clearTimer?: (h: unknown) => void;
+  /** Seconds before expiry to trigger the refresh. Default 300 (5 minutes). */
+  leadSeconds?: number;
+  /** Log sink. Defaults to writing to process.stderr with a newline. */
+  log?: (line: string) => void;
+}
+
+export interface TokenRefreshScheduler {
+  /** Start the scheduler with the initial token expiry (unix seconds). */
+  start: (initialExpiresAt: number) => void;
+  /** Cancel any pending refresh. Idempotent. Stops re-scheduling. */
+  cancel: () => void;
+}
+
+const DEFAULT_LEAD_SECONDS = 300;
+
+type SchedulerState = "active" | "cancelled";
+
+export function createTokenRefreshScheduler(
+  refresh: () => Promise<TokenRefreshState>,
+  onFailure: (err: unknown) => void | Promise<void>,
+  deps: TokenRefreshDeps = {},
+): TokenRefreshScheduler {
+  const now = deps.now ?? (() => Date.now() / 1000);
+  const setTimer =
+    deps.setTimer ??
+    ((fn: () => void, ms: number) => setTimeout(fn, ms) as unknown);
+  const clearTimer = deps.clearTimer ?? ((h: unknown) => clearTimeout(h as ReturnType<typeof setTimeout>));
+  const leadSeconds = deps.leadSeconds ?? DEFAULT_LEAD_SECONDS;
+  const log = deps.log ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  let handle: unknown = null;
+  let state: SchedulerState = "active";
+
+  const scheduleAt = (expiresAt: number): void => {
+    if (state === "cancelled") return;
+    const delayMs = Math.max(0, (expiresAt - leadSeconds - now()) * 1000);
+    handle = setTimer(fire, delayMs);
+  };
+
+  const fire = (): void => {
+    handle = null;
+    // void intentional — timer callback cannot be async.
+    void runRefresh();
+  };
+
+  const runRefresh = async (): Promise<void> => {
+    try {
+      const result = await refresh();
+      if (state === "cancelled") return;
+      const ttlSeconds = Math.max(0, result.expiresAt - now());
+      const nextSeconds = Math.max(0, ttlSeconds - leadSeconds);
+      const ttlMin = Math.round(ttlSeconds / 60);
+      const nextMin = Math.round(nextSeconds / 60);
+      log(
+        `[viber-channel] token refreshed, next refresh in ${nextMin}m (ttl ${ttlMin}m)`,
+      );
+      scheduleAt(result.expiresAt);
+    } catch (err) {
+      try {
+        await onFailure(err);
+      } catch {
+        // Failure callback owns its own error path; swallow.
+      }
+    }
+  };
+
+  return {
+    start(initialExpiresAt: number): void {
+      if (state === "cancelled") return;
+      if (handle !== null) {
+        clearTimer(handle);
+        handle = null;
+      }
+      scheduleAt(initialExpiresAt);
+    },
+    cancel(): void {
+      state = "cancelled";
+      if (handle !== null) {
+        clearTimer(handle);
+        handle = null;
+      }
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
   "type": "module",
   "bin": {

package/viber-channel.ts

@@ -31,6 +31,10 @@ import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { runConnect } from "./lib/connect.ts";
 import { lockFilePath } from "./lib/lockfile.ts";
+import {
+  createTokenRefreshScheduler,
+  type TokenRefreshScheduler,
+} from "./lib/token_refresh.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -138,10 +142,15 @@ function releaseLock(): void {
   }
 }
 
+// Token-refresh scheduler — null until the initial mint succeeds. Declared at
+// module scope so the early exit handlers below (which fire before the mint
+// completes on slow boots) can cancel it idempotently via optional-chaining.
+let scheduler: TokenRefreshScheduler | null = null;
+
 // Best-effort cleanup — on Windows, signals may not fire (TerminateProcess)
-process.on("exit", releaseLock);
-process.on("SIGINT", () => { releaseLock(); process.exit(0); });
-process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
+process.on("exit", () => { scheduler?.cancel(); releaseLock(); });
+process.on("SIGINT", () => { scheduler?.cancel(); releaseLock(); process.exit(0); });
+process.on("SIGTERM", () => { scheduler?.cancel(); releaseLock(); process.exit(0); });
 
 // stdin EOF — Claude Code closes its end of the pipe when the session
 // terminates (or the parent process is killed via TerminateProcess on
@@ -158,6 +167,7 @@ process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
 // orphan detection. See plan #236 step-09 for the diagnosis.
 process.stdin.on("end", () => {
   process.stderr.write("[viber-channel] stdin closed (parent exited), shutting down\n");
+  scheduler?.cancel();
   releaseLock();
   process.exit(0);
 });
@@ -185,7 +195,14 @@ if (computedFp !== auth.client_fingerprint) {
 
 // ---- Imports for mint ----
 
-import { defaultLabel, mintConversation, ReverifyRequiredError } from "./lib/conversation.ts";
+import {
+  defaultLabel,
+  mintConversation,
+  refreshConversationToken,
+  RefreshHttpError,
+  RefreshNetworkError,
+  ReverifyRequiredError,
+} from "./lib/conversation.ts";
 import { postMessage, ConversationTokenExpiredError, parseArtifact } from "./lib/messages.ts";
 import { cfAccessHeaders } from "./lib/cfAccess.ts";
 
@@ -376,6 +393,93 @@ try {
   CONVERSATION_TOKEN = minted.conversation_token;
   VOICE_BASE_URL = minted.ws_url;
   CONVERSATION_ID = minted.conversation_id;
+
+  // Schedule silent token refresh ahead of expiry (#237 step-03). On success
+  // we mutate CONVERSATION_TOKEN in place — getHeaders() reads it by closure,
+  // so subsequent SSE reconnects and send_message calls pick up the new token
+  // automatically. On failure we fall through to the existing
+  // handleConversationTokenExpired path (notification + exit code 3).
+  //
+  // VIBER_REFRESH_LEAD_SECONDS overrides the default 300s lead window — used
+  // for shortening the refresh-before-expiry gap during E2E manual testing
+  // (set close to TTL to force a refresh seconds after startup). Out of band
+  // for normal operation; the scheduler module's default applies when unset.
+  const leadOverride = process.env.VIBER_REFRESH_LEAD_SECONDS;
+  const leadSeconds = leadOverride ? Number.parseInt(leadOverride, 10) : undefined;
+  if (leadOverride !== undefined) {
+    if (!Number.isFinite(leadSeconds) || (leadSeconds as number) < 0) {
+      process.stderr.write(
+        `[viber-channel] Invalid VIBER_REFRESH_LEAD_SECONDS=${leadOverride}, ignoring.\n`
+      );
+    } else {
+      process.stderr.write(
+        `[viber-channel] token refresh lead overridden to ${leadSeconds}s via VIBER_REFRESH_LEAD_SECONDS\n`
+      );
+    }
+  }
+  const validLead =
+    leadSeconds !== undefined && Number.isFinite(leadSeconds) && leadSeconds >= 0
+      ? leadSeconds
+      : undefined;
+
+  // Track the current token's expiry so the retry path can refuse to retry
+  // past it. Updated only after a successful refresh — failed attempts leave
+  // it pointing at the still-valid current token.
+  let currentExpiresAt = minted.expires_at;
+
+  scheduler = createTokenRefreshScheduler(
+    async () => {
+      // Retry transient failures (5xx, 408, 409, network) with exponential
+      // backoff so a momentary blip during the 5-min lead window doesn't kill
+      // a channel whose token is still valid. Permanent failures (401, 403)
+      // surface immediately.
+      const MAX_ATTEMPTS = 5;
+      const HEADROOM_SECONDS = 10;
+      for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+          const refreshed = await refreshConversationToken(
+            BASE_URL,
+            CONVERSATION_ID,
+            CONVERSATION_TOKEN,
+            auth.client_fingerprint,
+          );
+          // SSE connection: the server accepts the new token immediately on
+          // subsequent requests, and any in-flight fetch still has the old
+          // token attached at the header level — the server keeps the open
+          // stream alive on the old token until its natural close. Safe to
+          // overwrite the module variable here.
+          CONVERSATION_TOKEN = refreshed.conversation_token;
+          currentExpiresAt = refreshed.expires_at;
+          return { expiresAt: refreshed.expires_at };
+        } catch (err) {
+          const retryable =
+            (err instanceof RefreshHttpError && err.retryable) ||
+            err instanceof RefreshNetworkError;
+          if (!retryable || attempt === MAX_ATTEMPTS) throw err;
+          // Bound retries by token validity: never sleep past expiry, leave
+          // a small headroom so the post-sleep request has time to land.
+          const proposedDelay = Math.min(30 * 2 ** (attempt - 1), 120);
+          const remaining = currentExpiresAt - Date.now() / 1000;
+          if (remaining - proposedDelay < HEADROOM_SECONDS) throw err;
+          process.stderr.write(
+            `[viber-channel] token refresh attempt ${attempt} failed (${String(err)}); retry in ${proposedDelay}s (${Math.round(remaining)}s until expiry)\n`,
+          );
+          await new Promise((r) => setTimeout(r, proposedDelay * 1000));
+        }
+      }
+      // Unreachable — the loop above either returns the refreshed state or
+      // throws on attempt === MAX_ATTEMPTS.
+      throw new Error("token refresh: retry loop exhausted without resolution");
+    },
+    async (err) => {
+      process.stderr.write(`[viber-channel] token refresh failed: ${String(err)}\n`);
+      // We don't call scheduler.cancel() here — we're inside the scheduler's
+      // failure path, and handleConversationTokenExpired ends the process anyway.
+      await handleConversationTokenExpired(mcp);
+    },
+    validLead !== undefined ? { leadSeconds: validLead } : undefined,
+  );
+  scheduler.start(minted.expires_at);
 } catch (err) {
   if (err instanceof ReverifyRequiredError) {
     await mcp.notification({
@@ -529,6 +633,7 @@ async function sseLoop(): Promise<void> {
 
         case "stop":
           process.stderr.write(`[viber-channel] Received stop signal, exiting.\n`);
+          scheduler?.cancel();
           releaseLock();
           process.exit(0);
           break;