heyhank 0.1.0

package/server/metrics-collector.ts

@@ -0,0 +1,350 @@
+// In-memory runtime metrics collector for the HeyHank server.
+// Subscribes to the event bus and provides direct instrumentation methods.
+// All data is in-memory — resets on server restart.
+
+import { heyHankBus } from "./event-bus.js";
+import type { SessionPhase } from "./session-state-machine.js";
+import type {
+  MetricsSnapshot,
+  HistogramSnapshot,
+  CounterMetrics,
+  GaugeMetrics,
+} from "./metrics-types.js";
+
+// ── Histogram bucket boundaries (ms) ──────────────────────────────────────
+
+const TIMING_BUCKETS_MS = [50, 100, 250, 500, 1_000, 2_500, 5_000, 10_000, 30_000, 60_000] as const;
+
+// ── Internal histogram data structure ─────────────────────────────────────
+
+interface Histogram {
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+  /** Frequency bucket counts. buckets[i] = count of values in (TIMING_BUCKETS_MS[i-1], TIMING_BUCKETS_MS[i]]. */
+  buckets: number[];
+}
+
+function createHistogram(): Histogram {
+  return {
+    count: 0,
+    sum: 0,
+    min: Infinity,
+    max: -Infinity,
+    buckets: new Array(TIMING_BUCKETS_MS.length + 1).fill(0), // +1 for +Infinity bucket
+  };
+}
+
+function recordHistogramValue(h: Histogram, value: number): void {
+  h.count++;
+  h.sum += value;
+  if (value < h.min) h.min = value;
+  if (value > h.max) h.max = value;
+
+  // Find the appropriate bucket
+  for (let i = 0; i < TIMING_BUCKETS_MS.length; i++) {
+    if (value <= TIMING_BUCKETS_MS[i]) {
+      h.buckets[i]++;
+      return;
+    }
+  }
+  // Falls into the +Infinity bucket
+  h.buckets[TIMING_BUCKETS_MS.length]++;
+}
+
+function serializeHistogram(h: Histogram): HistogramSnapshot {
+  const buckets: Record<string, number> = {};
+  for (let i = 0; i < TIMING_BUCKETS_MS.length; i++) {
+    buckets[String(TIMING_BUCKETS_MS[i])] = h.buckets[i];
+  }
+  buckets["Infinity"] = h.buckets[TIMING_BUCKETS_MS.length];
+
+  return {
+    count: h.count,
+    sum: h.sum,
+    min: h.count > 0 ? h.min : 0,
+    max: h.count > 0 ? h.max : 0,
+    avg: h.count > 0 ? Math.round(h.sum / h.count) : 0,
+    p50Bucket: computePercentileBucket(h, 0.5),
+    p95Bucket: computePercentileBucket(h, 0.95),
+    p99Bucket: computePercentileBucket(h, 0.99),
+    buckets,
+  };
+}
+
+/** Approximate the bucket boundary for a given percentile. */
+function computePercentileBucket(h: Histogram, p: number): number {
+  if (h.count === 0) return 0;
+  const target = Math.ceil(h.count * p);
+  let cumulative = 0;
+  for (let i = 0; i < TIMING_BUCKETS_MS.length; i++) {
+    cumulative += h.buckets[i];
+    if (cumulative >= target) return TIMING_BUCKETS_MS[i];
+  }
+  return Infinity;
+}
+
+// ── Gauge data provider interface ─────────────────────────────────────────
+
+/** Minimal interface for computing gauges at snapshot time. */
+export interface GaugeDataProvider {
+  getSessionMemoryStats(): { id: string; browsers: number; historyLen: number; eventBufferLen: number; pendingMsgs: number }[];
+  getSessionPhases(): Map<string, SessionPhase>;
+}
+
+// ── MetricsCollector ──────────────────────────────────────────────────────
+
+export class MetricsCollector {
+  private startedAt: number;
+
+  // Counters
+  private sessionsCreated = new Map<string, number>();
+  private sessionsTerminated = new Map<string, number>();
+  private autoRelaunches = { attempted: 0, succeeded: 0, exhausted: 0 };
+  private messagesProcessed = new Map<string, number>();
+  private permissions = { total: 0, autoApproved: 0, autoDenied: 0, userApproved: 0, userDenied: 0 };
+  private errors = new Map<string, number>();
+  private stateTransitions = new Map<string, number>();
+  private wsConnections = { cliOpened: 0, cliClosed: 0, browserOpened: 0, browserClosed: 0 };
+
+  // Histograms
+  private sessionInitTime = createHistogram();
+  private turnDuration = createHistogram();
+  private permissionDuration = createHistogram();
+
+  // Ephemeral timing state
+  private sessionSpawnedAt = new Map<string, number>();
+  private turnStartedAt = new Map<string, number>();
+  private permissionRequestedAt = new Map<string, number>();
+  /** Maps requestId → sessionId so permission timers can be cleaned up on session exit. */
+  private permissionRequestToSession = new Map<string, string>();
+
+  // Event bus unsubscribers (for cleanup in tests)
+  private unsubscribers: (() => void)[] = [];
+
+  constructor() {
+    this.startedAt = Date.now();
+    this.wireEventBus();
+  }
+
+  // ── Event bus wiring ──────────────────────────────────────────────────
+
+  private wireEventBus(): void {
+    this.unsubscribers.push(
+      heyHankBus.on("session:phase-changed", ({ sessionId, from, to }) => {
+        // Count state transitions
+        const key = `${from}→${to}`;
+        this.stateTransitions.set(key, (this.stateTransitions.get(key) ?? 0) + 1);
+
+        // Compute session init time: initializing → ready
+        if (to === "ready" && (from === "initializing" || from === "starting")) {
+          const spawned = this.sessionSpawnedAt.get(sessionId);
+          if (spawned != null) {
+            recordHistogramValue(this.sessionInitTime, Date.now() - spawned);
+            this.sessionSpawnedAt.delete(sessionId);
+          }
+        }
+      }),
+
+      heyHankBus.on("session:exited", ({ sessionId, exitCode }) => {
+        const key = String(exitCode ?? "null");
+        this.sessionsTerminated.set(key, (this.sessionsTerminated.get(key) ?? 0) + 1);
+
+        // Clean up ephemeral timing state
+        this.sessionSpawnedAt.delete(sessionId);
+        this.turnStartedAt.delete(sessionId);
+
+        // Evict orphaned permission timers for this session
+        for (const [reqId, sid] of this.permissionRequestToSession) {
+          if (sid === sessionId) {
+            this.permissionRequestedAt.delete(reqId);
+            this.permissionRequestToSession.delete(reqId);
+          }
+        }
+      }),
+
+      heyHankBus.on("message:result", ({ sessionId }) => {
+        const started = this.turnStartedAt.get(sessionId);
+        if (started != null) {
+          recordHistogramValue(this.turnDuration, Date.now() - started);
+          this.turnStartedAt.delete(sessionId);
+        }
+      }),
+    );
+  }
+
+  // ── Direct instrumentation methods ────────────────────────────────────
+
+  recordSessionCreated(backendType: string): void {
+    this.sessionsCreated.set(backendType, (this.sessionsCreated.get(backendType) ?? 0) + 1);
+  }
+
+  recordSessionSpawned(sessionId: string): void {
+    this.sessionSpawnedAt.set(sessionId, Date.now());
+  }
+
+  recordRelaunchAttempted(): void {
+    this.autoRelaunches.attempted++;
+  }
+
+  recordRelaunchSucceeded(): void {
+    this.autoRelaunches.succeeded++;
+  }
+
+  recordRelaunchExhausted(): void {
+    this.autoRelaunches.exhausted++;
+  }
+
+  recordTurnStarted(sessionId: string): void {
+    this.turnStartedAt.set(sessionId, Date.now());
+  }
+
+  recordPermissionRequested(requestId: string, sessionId?: string): void {
+    this.permissions.total++;
+    this.permissionRequestedAt.set(requestId, Date.now());
+    if (sessionId) {
+      this.permissionRequestToSession.set(requestId, sessionId);
+    }
+  }
+
+  recordPermissionResolved(requestId: string, behavior: "allow" | "deny", isAutomatic: boolean): void {
+    if (isAutomatic) {
+      if (behavior === "allow") this.permissions.autoApproved++;
+      else this.permissions.autoDenied++;
+    } else {
+      if (behavior === "allow") this.permissions.userApproved++;
+      else this.permissions.userDenied++;
+    }
+
+    const requested = this.permissionRequestedAt.get(requestId);
+    if (requested != null) {
+      recordHistogramValue(this.permissionDuration, Date.now() - requested);
+      this.permissionRequestedAt.delete(requestId);
+      this.permissionRequestToSession.delete(requestId);
+    }
+  }
+
+  recordWsConnection(kind: "cli" | "browser", event: "open" | "close"): void {
+    if (kind === "cli") {
+      if (event === "open") this.wsConnections.cliOpened++;
+      else this.wsConnections.cliClosed++;
+    } else {
+      if (event === "open") this.wsConnections.browserOpened++;
+      else this.wsConnections.browserClosed++;
+    }
+  }
+
+  recordMessageProcessed(messageType: string): void {
+    this.messagesProcessed.set(messageType, (this.messagesProcessed.get(messageType) ?? 0) + 1);
+  }
+
+  recordError(category: string): void {
+    this.errors.set(category, (this.errors.get(category) ?? 0) + 1);
+  }
+
+  // ── Snapshot ──────────────────────────────────────────────────────────
+
+  getSnapshot(gaugeProvider?: GaugeDataProvider): MetricsSnapshot {
+    const counters = this.buildCounters();
+    const gauges = this.buildGauges(gaugeProvider);
+    const histograms = {
+      sessionInitTimeMs: serializeHistogram(this.sessionInitTime),
+      turnDurationMs: serializeHistogram(this.turnDuration),
+      permissionDurationMs: serializeHistogram(this.permissionDuration),
+    };
+
+    return {
+      serverUptimeMs: Date.now() - this.startedAt,
+      snapshotAt: Date.now(),
+      counters,
+      gauges,
+      histograms,
+    };
+  }
+
+  private buildCounters(): CounterMetrics {
+    return {
+      sessionsCreated: Object.fromEntries(this.sessionsCreated),
+      sessionsTerminated: Object.fromEntries(this.sessionsTerminated),
+      autoRelaunches: { ...this.autoRelaunches },
+      messagesProcessed: Object.fromEntries(this.messagesProcessed),
+      permissionRequests: { ...this.permissions },
+      errors: Object.fromEntries(this.errors),
+      stateTransitions: Object.fromEntries(this.stateTransitions),
+      wsConnections: { ...this.wsConnections },
+    };
+  }
+
+  private buildGauges(provider?: GaugeDataProvider): GaugeMetrics {
+    const activeSessions: Partial<Record<SessionPhase, number>> = {};
+    let totalActive = 0;
+    let connectedBrowsers = 0;
+    let totalPending = 0;
+    let totalEventBuffer = 0;
+    let totalHistory = 0;
+
+    if (provider) {
+      // Compute phase distribution
+      for (const [, phase] of provider.getSessionPhases()) {
+        activeSessions[phase] = (activeSessions[phase] ?? 0) + 1;
+        if (phase !== "terminated") totalActive++;
+      }
+
+      // Compute memory stats
+      for (const stats of provider.getSessionMemoryStats()) {
+        connectedBrowsers += stats.browsers;
+        totalPending += stats.pendingMsgs;
+        totalEventBuffer += stats.eventBufferLen;
+        totalHistory += stats.historyLen;
+      }
+    }
+
+    const mem = process.memoryUsage();
+
+    return {
+      activeSessions,
+      totalActiveSessions: totalActive,
+      connectedBrowsers,
+      totalPendingMessages: totalPending,
+      totalEventBufferSize: totalEventBuffer,
+      totalHistoryMessages: totalHistory,
+      memory: {
+        rss: mem.rss,
+        heapUsed: mem.heapUsed,
+        heapTotal: mem.heapTotal,
+        external: mem.external,
+      },
+    };
+  }
+
+  // ── Reset (for testing) ───────────────────────────────────────────────
+
+  reset(): void {
+    this.startedAt = Date.now();
+    this.sessionsCreated.clear();
+    this.sessionsTerminated.clear();
+    this.autoRelaunches = { attempted: 0, succeeded: 0, exhausted: 0 };
+    this.messagesProcessed.clear();
+    this.permissions = { total: 0, autoApproved: 0, autoDenied: 0, userApproved: 0, userDenied: 0 };
+    this.errors.clear();
+    this.stateTransitions.clear();
+    this.wsConnections = { cliOpened: 0, cliClosed: 0, browserOpened: 0, browserClosed: 0 };
+    this.sessionInitTime = createHistogram();
+    this.turnDuration = createHistogram();
+    this.permissionDuration = createHistogram();
+    this.sessionSpawnedAt.clear();
+    this.turnStartedAt.clear();
+    this.permissionRequestedAt.clear();
+    this.permissionRequestToSession.clear();
+  }
+
+  /** Unsubscribe from all event bus listeners. */
+  destroy(): void {
+    for (const unsub of this.unsubscribers) unsub();
+    this.unsubscribers = [];
+  }
+}
+
+/** Singleton instance used by the server. */
+export const metricsCollector = new MetricsCollector();

package/server/metrics-types.ts

@@ -0,0 +1,108 @@
+// Type definitions for the HeyHank runtime metrics system.
+// Defines the shape of the JSON snapshot returned by GET /api/metrics.
+
+import type { SessionPhase } from "./session-state-machine.js";
+
+// ── Snapshot (top-level) ───────────────────────────────────────────────────
+
+export interface MetricsSnapshot {
+  /** Milliseconds since server started. */
+  serverUptimeMs: number;
+  /** Unix timestamp (ms) when this snapshot was taken. */
+  snapshotAt: number;
+  counters: CounterMetrics;
+  gauges: GaugeMetrics;
+  histograms: HistogramMetrics;
+}
+
+// ── Counters (monotonically increasing) ────────────────────────────────────
+
+export interface CounterMetrics {
+  /** Sessions created, keyed by backend type ("claude" | "codex"). */
+  sessionsCreated: Record<string, number>;
+  /** Sessions terminated, keyed by exit code (stringified). */
+  sessionsTerminated: Record<string, number>;
+  /** Auto-relaunch tracking. */
+  autoRelaunches: {
+    attempted: number;
+    succeeded: number;
+    exhausted: number;
+  };
+  /** Messages processed by the bridge, keyed by message type. */
+  messagesProcessed: Record<string, number>;
+  /** Permission request flow tracking. */
+  permissionRequests: {
+    total: number;
+    autoApproved: number;
+    autoDenied: number;
+    userApproved: number;
+    userDenied: number;
+  };
+  /** Errors by category (e.g. "invalid_state_transition", "parse_error"). */
+  errors: Record<string, number>;
+  /** State machine transitions, keyed by "from→to". */
+  stateTransitions: Record<string, number>;
+  /** WebSocket connection events. */
+  wsConnections: {
+    cliOpened: number;
+    cliClosed: number;
+    browserOpened: number;
+    browserClosed: number;
+  };
+}
+
+// ── Gauges (point-in-time values) ──────────────────────────────────────────
+
+export interface GaugeMetrics {
+  /** Active sessions grouped by phase. */
+  activeSessions: Partial<Record<SessionPhase, number>>;
+  /** Total non-terminated sessions. */
+  totalActiveSessions: number;
+  /** Total connected browser WebSockets across all sessions. */
+  connectedBrowsers: number;
+  /** Total pending messages queued across all sessions. */
+  totalPendingMessages: number;
+  /** Total event buffer entries across all sessions. */
+  totalEventBufferSize: number;
+  /** Total message history entries across all sessions. */
+  totalHistoryMessages: number;
+  /** Process memory usage in bytes. */
+  memory: {
+    rss: number;
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+  };
+}
+
+// ── Histograms (distributions) ─────────────────────────────────────────────
+
+export interface HistogramSnapshot {
+  /** Number of observations. */
+  count: number;
+  /** Sum of all observed values. */
+  sum: number;
+  /** Minimum observed value (0 if no observations). */
+  min: number;
+  /** Maximum observed value (0 if no observations). */
+  max: number;
+  /** Average (0 if no observations). */
+  avg: number;
+  /** Approximate bucket boundary for the 50th percentile. */
+  p50Bucket: number;
+  /** Approximate bucket boundary for the 95th percentile. */
+  p95Bucket: number;
+  /** Approximate bucket boundary for the 99th percentile. */
+  p99Bucket: number;
+  /** Cumulative counts per bucket boundary (stringified keys). */
+  buckets: Record<string, number>;
+}
+
+export interface HistogramMetrics {
+  /** Session initialization time: spawn → ready (ms). */
+  sessionInitTimeMs: HistogramSnapshot;
+  /** Turn duration: user message → result (ms). */
+  turnDurationMs: HistogramSnapshot;
+  /** Permission request duration: request → response (ms). */
+  permissionDurationMs: HistogramSnapshot;
+}

package/server/middleware/managed-auth.ts

@@ -0,0 +1,195 @@
+import { createMiddleware } from "hono/factory";
+import type { Context } from "hono";
+
+/**
+ * Auth middleware for managed HeyHank Cloud instances.
+ *
+ * Only active when HEYHANK_AUTH_ENABLED=1. Validates a JWT from a cookie
+ * or query parameter, signed by the control plane using HEYHANK_AUTH_SECRET.
+ *
+ * Skipped paths:
+ *  - /ws/cli/*  — internal CLI WebSocket (Claude Code connects from within the machine)
+ *  - /health    — monitoring endpoint used by control plane health checks
+ */
+export const managedAuth = createMiddleware(async (c: Context, next) => {
+  // This middleware is only registered by index.ts when managed auth is
+  // enabled (HEYHANK_AUTH_ENABLED=1 or HEYHANK_AUTH_SECRET is set).
+  // No redundant env check needed here.
+
+  const path = c.req.path;
+
+  // Internal paths that bypass auth
+  if (path.startsWith("/ws/cli/") || path === "/health") return next();
+
+  const cookieToken = getCookie(c, "heyhank_token") || getCookie(c, "companion_token");
+  const queryToken = c.req.query("token");
+  // Give explicit URL token precedence so reconnect links can always override
+  // stale/expired cookies in the browser.
+  const token = queryToken || cookieToken;
+
+  if (!token) {
+    return redirectOrUnauthorized(c);
+  }
+
+  const secret = process.env.HEYHANK_AUTH_SECRET || process.env.COMPANION_AUTH_SECRET;
+  if (!secret) {
+    console.error("[managed-auth] HEYHANK_AUTH_SECRET is not set");
+    return c.json({ error: "Server misconfigured" }, 500);
+  }
+
+  const valid = await verifyToken(token, secret);
+  if (!valid) {
+    return redirectOrUnauthorized(c);
+  }
+
+  // When auth arrives via URL query once, persist it to a cookie so static
+  // assets and subsequent API calls are authenticated without ?token=...
+  if (queryToken && queryToken !== cookieToken) {
+    setAuthCookie(c, queryToken);
+  }
+
+  return next();
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getCookie(c: Context, name: string): string | undefined {
+  const header = c.req.header("cookie");
+  if (!header) return undefined;
+  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match?.[1];
+}
+
+function setAuthCookie(c: Context, token: string): void {
+  const encoded = encodeURIComponent(token);
+  const secure = shouldUseSecureCookie(c) ? "; Secure" : "";
+  c.header(
+    "Set-Cookie",
+    `heyhank_token=${encoded}; Path=/; HttpOnly${secure}; SameSite=Lax; Max-Age=900`,
+  );
+}
+
+function shouldUseSecureCookie(c: Context): boolean {
+  const forwardedProto = c.req.header("x-forwarded-proto")?.split(",")[0]?.trim().toLowerCase();
+  if (forwardedProto) return forwardedProto === "https";
+
+  try {
+    return new URL(c.req.url).protocol === "https:";
+  } catch {
+    return true;
+  }
+}
+
+function redirectOrUnauthorized(c: Context): Response {
+  const loginUrl = process.env.HEYHANK_LOGIN_URL || process.env.COMPANION_LOGIN_URL;
+  if (loginUrl) {
+    return c.redirect(loginUrl);
+  }
+  return c.json({ error: "Unauthorized" }, 401);
+}
+
+/**
+ * Verify a JWT-like HMAC-SHA256 token.
+ * Token format: base64url(payload).base64url(signature)
+ * Payload: { exp: number } (Unix seconds)
+ */
+export async function verifyToken(
+  token: string,
+  secret: string,
+): Promise<boolean> {
+  const parts = token.split(".");
+  if (parts.length !== 2) return false;
+
+  const [payloadB64, signatureB64] = parts;
+
+  // Verify signature using HMAC-SHA256
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+
+  const expectedSig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(payloadB64),
+  );
+
+  const expectedB64 = base64UrlEncode(new Uint8Array(expectedSig));
+  if (!timingSafeEqual(expectedB64, signatureB64)) return false;
+
+  // Check expiration
+  try {
+    const payload = JSON.parse(
+      new TextDecoder().decode(base64UrlDecode(payloadB64)),
+    );
+    if (typeof payload.exp === "number" && payload.exp < Date.now() / 1000) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Create a signed token for the control plane to issue.
+ * Exported for use by the control plane's token endpoint.
+ */
+export async function createToken(
+  secret: string,
+  ttlSeconds = 900, // 15 minutes
+): Promise<string> {
+  const payload = { exp: Math.floor(Date.now() / 1000) + ttlSeconds };
+  const payloadB64 = base64UrlEncode(
+    new TextEncoder().encode(JSON.stringify(payload)),
+  );
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(payloadB64),
+  );
+
+  return `${payloadB64}.${base64UrlEncode(new Uint8Array(sig))}`;
+}
+
+// ─── Base64url ───────────────────────────────────────────────────────────────
+
+function base64UrlEncode(data: Uint8Array): string {
+  let binary = "";
+  for (const byte of data) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64UrlDecode(str: string): Uint8Array {
+  const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}