@takosjp/yurucommu-core 3.2.1 → 3.4.0

package/src/backend/routes/realtime/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Realtime stream routes.
+ *
+ *   GET  /api/realtime/config   capability probe ({ available }) — clients
+ *                               gate their fallback polling on this
+ *   POST /api/realtime/ticket   mint a one-time short-lived WS ticket
+ *   GET  /api/realtime/socket   browser WebSocket upgrade -> per-user stream
+ *
+ * Two upgrade auth paths, both terminating in the worker BEFORE the DO is
+ * reached (the DO binding is the trust boundary):
+ *   - session: the same-origin browser sends its session cookie; the /api/*
+ *     middleware resolved the actor already.
+ *   - ticket: a cross-origin or bearer-auth client (the browser WebSocket API
+ *     cannot set an Authorization header) first POSTs /ticket over the normal
+ *     authenticated fetch path, then connects with ?actor=&ticket=. The ticket
+ *     is minted inside — and re-verified + consumed by — the target user's own
+ *     stream DO, so it is single-use, expires in ~60s, and never carries the
+ *     raw session credential in a URL.
+ */
+
+import { Hono } from "hono";
+import type { Env, Variables } from "../../types.ts";
+import {
+  getRealtimeHub,
+  isRealtimeAvailable,
+} from "../../runtime/realtime-hub.ts";
+
+const realtime = new Hono<{ Bindings: Env; Variables: Variables }>();
+
+realtime.get("/config", (c) => {
+  return c.json({ available: isRealtimeAvailable(c.env) });
+});
+
+realtime.post("/ticket", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "unauthorized" }, 401);
+  if (!isRealtimeAvailable(c.env)) {
+    return c.json({ error: "realtime_unavailable" }, 503);
+  }
+  const ticket = await getRealtimeHub(c.env).mintTicket(actor.ap_id);
+  if (!ticket) return c.json({ error: "ticket_mint_failed" }, 500);
+  return c.json({ ticket, actor_ap_id: actor.ap_id });
+});
+
+realtime.get("/socket", async (c) => {
+  if (!isRealtimeAvailable(c.env)) {
+    return c.json({ error: "realtime_unavailable" }, 503);
+  }
+  const hub = getRealtimeHub(c.env);
+
+  const sessionActor = c.get("actor");
+  if (sessionActor) {
+    return hub.upgrade(c.req.raw, sessionActor.ap_id, "session");
+  }
+
+  const actorParam = c.req.query("actor")?.trim();
+  const ticket = c.req.query("ticket")?.trim();
+  if (actorParam && ticket) {
+    // The actor param only selects WHICH stream DO verifies the ticket; a
+    // forged actor value fails inside that DO (it never minted the ticket).
+    return hub.upgrade(c.req.raw, actorParam, "ticket", ticket);
+  }
+
+  return c.json({ error: "unauthorized" }, 401);
+});
+
+export default realtime;

package/src/backend/routes/rtc/index.ts

@@ -0,0 +1,151 @@
+/**
+ * Call feature routes (WebRTC voice + video).
+ *
+ *   POST /ap/rtc/signal    server-to-server signaling ingest (HTTP-Signature)
+ *   GET  /api/rtc/socket   browser WebSocket upgrade -> per-user signaling hub
+ *   GET  /api/rtc/ice      mint short-lived ICE (STUN/TURN) servers
+ *   POST /api/rtc/calls    start a call (block-list gate + callId + ICE)
+ *   GET  /api/rtc/calls    call history (missed / recent)
+ *   GET  /api/rtc/calls/:id current state of one call
+ *
+ * Signaling is intentionally OUTSIDE the ActivityPub inbox pipeline: the
+ * `/ap/rtc/signal` endpoint bypasses `claimActivityForDispatch` /
+ * `parseActivity` (which would strip SDP/ICE and persist ephemeral frames to the
+ * `activities` ledger). It reuses the same HTTP-Signature auth every inbox uses.
+ */
+
+import { Hono } from "hono";
+import { eq } from "drizzle-orm";
+import type { Env, Variables } from "../../types.ts";
+import { actors } from "../../../db/index.ts";
+import { verifyHttpSignature } from "../../lib/ap-verify.ts";
+import {
+  isActorMismatch,
+  signingActorFromKeyId,
+} from "../activitypub/inbox.ts";
+import { isActorBlocked } from "../../lib/blocklist.ts";
+import {
+  getSignalingHub,
+  isSignalingAvailable,
+} from "../../runtime/signaling-hub.ts";
+import { createRtcProvider } from "../../lib/rtc/provider.ts";
+import { getCallSession, listCallSessions } from "../../lib/rtc/call-store.ts";
+import type {
+  CallMediaKind,
+  StartCallRequest,
+} from "../../../../packages/api/src/types/call.ts";
+import { parseRtcSignalEnvelope } from "../../../../packages/api/src/types/call.ts";
+
+const rtc = new Hono<{ Bindings: Env; Variables: Variables }>();
+
+function normalizeMedia(input: unknown): CallMediaKind {
+  if (input && typeof input === "object") {
+    const m = input as Partial<CallMediaKind>;
+    return { audio: m.audio !== false, video: Boolean(m.video) };
+  }
+  return { audio: true, video: false };
+}
+
+// --- Server-to-server signaling ingest -------------------------------------
+rtc.post("/ap/rtc/signal", async (c) => {
+  const db = c.get("db");
+  const body = await c.req.text();
+  const sig = await verifyHttpSignature(c.req.raw, db, body);
+  if (!sig.valid) return c.json({ error: "invalid_signature" }, 401);
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return c.json({ error: "bad_json" }, 400);
+  }
+  const envelope = parseRtcSignalEnvelope(parsed);
+  if (!envelope) return c.json({ error: "bad_envelope" }, 400);
+
+  // The HTTP-Signature signer must own the claimed `from` actor.
+  if (isActorMismatch(signingActorFromKeyId(sig.keyId), envelope.from)) {
+    return c.json({ error: "signer_mismatch" }, 403);
+  }
+
+  // The recipient must be a local actor served by this instance.
+  const local = await db.query.actors.findFirst({
+    where: eq(actors.apId, envelope.to),
+    columns: { apId: true },
+  });
+  if (!local) return c.json({ error: "unknown_recipient" }, 404);
+
+  // Never ring for a sender the local owner has blocked; drop silently.
+  if (await isActorBlocked(db, envelope.from)) return c.body(null, 204);
+
+  await getSignalingHub(c.env).deliver(envelope.to, envelope);
+  return c.body(null, 204);
+});
+
+// --- Browser WebSocket upgrade ---------------------------------------------
+rtc.get("/api/rtc/socket", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "unauthorized" }, 401);
+  if (!isSignalingAvailable(c.env)) {
+    return c.json({ error: "signaling_unavailable" }, 503);
+  }
+  return getSignalingHub(c.env).upgrade(c.req.raw, actor.ap_id);
+});
+
+// --- ICE servers ------------------------------------------------------------
+rtc.get("/api/rtc/ice", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "unauthorized" }, 401);
+  const iceServers = await createRtcProvider(c.env).getIceServers();
+  return c.json({ iceServers });
+});
+
+// --- Start a call -----------------------------------------------------------
+rtc.post("/api/rtc/calls", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "unauthorized" }, 401);
+  if (!isSignalingAvailable(c.env)) {
+    return c.json({ error: "signaling_unavailable" }, 503);
+  }
+  const db = c.get("db");
+  let payload: Partial<StartCallRequest>;
+  try {
+    payload = (await c.req.json()) as Partial<StartCallRequest>;
+  } catch {
+    return c.json({ error: "bad_json" }, 400);
+  }
+  const to = typeof payload.to === "string" ? payload.to.trim() : "";
+  if (!to || to === actor.ap_id) return c.json({ error: "bad_target" }, 400);
+  const media = normalizeMedia(payload.media);
+
+  // Do not let the local owner place a call to a contact they have blocked.
+  if (await isActorBlocked(db, to)) return c.json({ error: "blocked" }, 403);
+
+  const provider = createRtcProvider(c.env);
+  const [iceServers, sfuFocus] = await Promise.all([
+    provider.getIceServers(),
+    provider.getSfuFocus(media),
+  ]);
+  return c.json({ callId: crypto.randomUUID(), iceServers, sfuFocus });
+});
+
+// --- Call history + state ---------------------------------------------------
+rtc.get("/api/rtc/calls", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "unauthorized" }, 401);
+  const calls = await listCallSessions(c.get("db"), actor.ap_id);
+  return c.json({ calls });
+});
+
+rtc.get("/api/rtc/calls/:id", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "unauthorized" }, 401);
+  const call = await getCallSession(
+    c.get("db"),
+    actor.ap_id,
+    c.req.param("id"),
+  );
+  if (!call) return c.json({ error: "not_found" }, 404);
+  return c.json({ call });
+});
+
+export default rtc;

package/src/backend/runtime/call-hub-core.ts

@@ -0,0 +1,480 @@
+/**
+ * Runtime-neutral call signaling engine.
+ *
+ * `CallHub` owns one local actor's per-call state machine and routes signaling
+ * frames between the local browser tabs and the peer instance (server-to-server).
+ * It is deliberately free of Cloudflare / Bun APIs: the Cloudflare
+ * `CallSignalingDurableObject` and the in-process `LocalSignalingHub` (Bun dev /
+ * tests) both wrap this same engine, so glare resolution, timeouts, and relay
+ * live in exactly one place.
+ *
+ * Connections are NOT held by the hub — the host owns them (the DO enumerates
+ * its live Hibernatable WebSockets on demand) and exposes `broadcast`/`hasClients`
+ * through the port. That keeps the hub correct across DO hibernation, where any
+ * in-memory socket set would be lost. Per-call state is persisted by the host
+ * (`persist`) and rehydrated via `hydrate`.
+ *
+ * The wire contract lives in the client-API package (single source of truth,
+ * shared with the browser `CallClient`).
+ */
+
+import type {
+  CallDirection,
+  CallMediaKind,
+  CallState,
+  ClientToHubFrame,
+  HubToClientFrame,
+  IceServerConfig,
+  RtcSignalEnvelopeV1,
+  SfuFocus,
+} from "../../../packages/api/src/types/call.ts";
+import {
+  isEnvelopeFresh,
+  isTerminalCallState,
+  RTC_SIGNAL_ENVELOPE_VERSION,
+} from "../../../packages/api/src/types/call.ts";
+
+/** A live browser WebSocket, abstracted from the runtime. */
+export interface HubConnection {
+  send(frame: HubToClientFrame): void;
+  close(code?: number, reason?: string): void;
+}
+
+/** In-flight call, tracked per hub (= per local actor). */
+export interface CallRecord {
+  callId: string;
+  peerApId: string;
+  peerSignalEndpoint?: string;
+  direction: CallDirection;
+  state: CallState;
+  media: CallMediaKind;
+  sfuFocus: SfuFocus | null;
+  createdAt: number;
+  updatedAt: number;
+  connectedAt?: number;
+}
+
+/** Side-effect port the hosting runtime supplies. */
+export interface HubPort {
+  /** The local actor (ap_id) this hub serves. */
+  readonly localActorApId: string;
+  /** Send a frame to every live local browser tab. */
+  broadcast(frame: HubToClientFrame): void;
+  /** Whether any local browser tab is currently connected. */
+  hasClients(): boolean;
+  /** Sign + POST a signaling envelope to the peer's instance (s2s). */
+  sendToPeer(
+    envelope: RtcSignalEnvelopeV1,
+    peerSignalEndpoint?: string,
+  ): Promise<void>;
+  /** ICE servers (+ optional SFU focus) for a call. */
+  provisionMedia(
+    media: CallMediaKind,
+  ): Promise<{ iceServers: IceServerConfig[]; sfuFocus: SfuFocus | null }>;
+  /** Best-effort persist of a call-session transition (history / missed-call). */
+  persist?(call: CallRecord): Promise<void> | void;
+  /** Best-effort wake of a possibly-offline callee (push-gateway ring). */
+  ring?(envelope: RtcSignalEnvelopeV1): Promise<void> | void;
+  now(): number;
+  log?(event: string, data?: Record<string, unknown>): void;
+}
+
+// Ringing that never gets answered becomes a missed call; a call that never
+// finishes ICE negotiation is failed. Kept generous — a slow federation hop
+// plus a human deciding to answer can legitimately take tens of seconds.
+const RINGING_TIMEOUT_MS = 45_000;
+const CONNECTING_TIMEOUT_MS = 40_000;
+// Default freshness window stamped on outbound envelopes.
+const DEFAULT_TTL_MS = 30_000;
+
+export class CallHub {
+  private readonly calls = new Map<string, CallRecord>();
+
+  constructor(private readonly port: HubPort) {}
+
+  get localActorApId(): string {
+    return this.port.localActorApId;
+  }
+
+  /** Snapshot of active (non-terminal) calls — used by the DO to persist. */
+  activeCalls(): CallRecord[] {
+    return [...this.calls.values()].filter(
+      (c) => !isTerminalCallState(c.state),
+    );
+  }
+
+  /** Restore calls from durable storage after DO hibernation. */
+  hydrate(records: CallRecord[]): void {
+    for (const rec of records) {
+      if (!isTerminalCallState(rec.state)) this.calls.set(rec.callId, rec);
+    }
+  }
+
+  private transition(call: CallRecord, state: CallState): void {
+    call.state = state;
+    call.updatedAt = this.port.now();
+    if (state === "connected" && !call.connectedAt) {
+      call.connectedAt = call.updatedAt;
+    }
+    void this.port.persist?.(call);
+    this.port.broadcast({ t: "call-state", callId: call.callId, state });
+    if (isTerminalCallState(state)) this.calls.delete(call.callId);
+  }
+
+  private makeEnvelope(
+    call: CallRecord,
+    type: RtcSignalEnvelopeV1["type"],
+    extra: Partial<RtcSignalEnvelopeV1> = {},
+  ): RtcSignalEnvelopeV1 {
+    return {
+      v: RTC_SIGNAL_ENVELOPE_VERSION,
+      callId: call.callId,
+      from: this.port.localActorApId,
+      to: call.peerApId,
+      type,
+      ts: this.port.now(),
+      ttlMs: DEFAULT_TTL_MS,
+      ...extra,
+    };
+  }
+
+  private async relay(
+    call: CallRecord,
+    type: RtcSignalEnvelopeV1["type"],
+    extra: Partial<RtcSignalEnvelopeV1> = {},
+  ): Promise<void> {
+    try {
+      await this.port.sendToPeer(
+        this.makeEnvelope(call, type, extra),
+        call.peerSignalEndpoint,
+      );
+    } catch (err) {
+      this.port.log?.("call.hub.relay_failed", {
+        callId: call.callId,
+        type,
+        error: String(err),
+      });
+      // A signaling frame we cannot deliver dooms the call; surface it.
+      this.port.broadcast({
+        t: "error",
+        code: "peer_unreachable",
+        message: "Could not reach the other party's server.",
+      });
+      this.transition(call, "failed");
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Browser -> hub
+  // -------------------------------------------------------------------------
+
+  async handleClientFrame(
+    conn: HubConnection,
+    frame: ClientToHubFrame,
+  ): Promise<void> {
+    switch (frame.t) {
+      case "hello":
+        conn.send({ t: "ready" });
+        // Re-announce any active calls so a reconnecting tab resyncs.
+        for (const call of this.activeCalls()) {
+          conn.send({
+            t: "call-state",
+            callId: call.callId,
+            state: call.state,
+          });
+        }
+        return;
+      case "ping":
+        conn.send({ t: "pong" });
+        return;
+      case "invite":
+        return this.onClientInvite(conn, frame);
+      case "offer":
+        return this.onClientOffer(frame);
+      case "answer":
+        return this.onClientAnswer(frame);
+      case "candidates":
+        return this.onClientCandidates(frame);
+      case "accept":
+        return this.onClientAccept(frame);
+      case "reject":
+        return this.onClientReject(frame);
+      case "hangup":
+        return this.onClientHangup(frame);
+      case "resume":
+        return this.onClientResume(conn, frame);
+    }
+  }
+
+  private async onClientInvite(
+    conn: HubConnection,
+    frame: Extract<ClientToHubFrame, { t: "invite" }>,
+  ): Promise<void> {
+    if (this.calls.has(frame.callId)) return;
+    const media = await this.port.provisionMedia(frame.media);
+    const now = this.port.now();
+    const call: CallRecord = {
+      callId: frame.callId,
+      peerApId: frame.to,
+      direction: "outgoing",
+      state: "ringing",
+      media: frame.media,
+      sfuFocus: media.sfuFocus,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.calls.set(call.callId, call);
+    void this.port.persist?.(call);
+    // Hand the caller its media params immediately so it can build the offer.
+    conn.send({
+      t: "ice-servers",
+      callId: call.callId,
+      iceServers: media.iceServers,
+      sfuFocus: media.sfuFocus,
+    });
+    this.port.broadcast({
+      t: "call-state",
+      callId: call.callId,
+      state: "ringing",
+    });
+  }
+
+  private async onClientOffer(
+    frame: Extract<ClientToHubFrame, { t: "offer" }>,
+  ): Promise<void> {
+    const call = this.calls.get(frame.callId);
+    if (!call) return;
+    await this.relay(call, "offer", { sdp: frame.sdp, media: call.media });
+  }
+
+  private async onClientAnswer(
+    frame: Extract<ClientToHubFrame, { t: "answer" }>,
+  ): Promise<void> {
+    const call = this.calls.get(frame.callId);
+    if (!call) return;
+    if (call.state === "ringing") this.transition(call, "connecting");
+    await this.relay(call, "answer", { sdp: frame.sdp });
+  }
+
+  private async onClientCandidates(
+    frame: Extract<ClientToHubFrame, { t: "candidates" }>,
+  ): Promise<void> {
+    const call = this.calls.get(frame.callId);
+    if (!call || frame.candidates.length === 0) return;
+    await this.relay(call, "candidate", { candidates: frame.candidates });
+  }
+
+  private async onClientAccept(
+    frame: Extract<ClientToHubFrame, { t: "accept" }>,
+  ): Promise<void> {
+    const call = this.calls.get(frame.callId);
+    if (!call) return;
+    // Local user accepted an incoming ring; tell the caller and move forward.
+    if (call.state === "ringing") this.transition(call, "connecting");
+    await this.relay(call, "accept");
+  }
+
+  private async onClientReject(
+    frame: Extract<ClientToHubFrame, { t: "reject" }>,
+  ): Promise<void> {
+    const call = this.calls.get(frame.callId);
+    if (!call) return;
+    await this.relay(call, "reject", { reason: frame.reason });
+    this.transition(call, "rejected");
+  }
+
+  private async onClientHangup(
+    frame: Extract<ClientToHubFrame, { t: "hangup" }>,
+  ): Promise<void> {
+    const call = this.calls.get(frame.callId);
+    if (!call) return;
+    // A hangup before connection from the caller side is a cancel.
+    const wasConnected = call.state === "connected";
+    await this.relay(call, wasConnected ? "hangup" : "cancel", {
+      reason: frame.reason,
+    });
+    this.transition(call, wasConnected ? "ended" : "cancelled");
+  }
+
+  private onClientResume(
+    conn: HubConnection,
+    frame: Extract<ClientToHubFrame, { t: "resume" }>,
+  ): void {
+    const call = this.calls.get(frame.callId);
+    conn.send({
+      t: "call-state",
+      callId: frame.callId,
+      state: call ? call.state : "ended",
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Peer instance -> hub (inbound cross-instance signal)
+  // -------------------------------------------------------------------------
+
+  async handleInboundSignal(envelope: RtcSignalEnvelopeV1): Promise<void> {
+    if (!isEnvelopeFresh(envelope, this.port.now())) {
+      this.port.log?.("call.hub.stale_signal", { callId: envelope.callId });
+      return;
+    }
+    switch (envelope.type) {
+      case "offer":
+        return this.onPeerOffer(envelope);
+      case "answer":
+        this.onPeerAnswer(envelope);
+        return;
+      case "candidate":
+        this.onPeerCandidate(envelope);
+        return;
+      case "accept":
+        this.onPeerAccept(envelope);
+        return;
+      case "reject":
+        this.onPeerReject(envelope);
+        return;
+      case "hangup":
+      case "cancel":
+        this.onPeerHangup(envelope);
+        return;
+    }
+  }
+
+  private async onPeerOffer(envelope: RtcSignalEnvelopeV1): Promise<void> {
+    let call = this.calls.get(envelope.callId);
+    if (!call) {
+      // Glare: we are already ringing this same peer (a DIFFERENT callId) and
+      // their offer arrives — both sides dialed at once. Perfect Negotiation:
+      // the lexicographically-lower ap_id is "impolite" and keeps its own
+      // outgoing call (ignoring the incoming offer); the "polite" higher ap_id
+      // cancels its outgoing call and accepts the incoming one. Both sides then
+      // converge on the impolite side's call.
+      const outgoingToPeer = [...this.calls.values()].find(
+        (c) =>
+          c.direction === "outgoing" &&
+          c.peerApId === envelope.from &&
+          c.state === "ringing",
+      );
+      if (outgoingToPeer) {
+        const weArePolite = this.localActorApId > envelope.from;
+        if (!weArePolite) return; // keep our outgoing offer; ignore theirs
+        await this.relay(outgoingToPeer, "cancel", { reason: "glare" });
+        this.transition(outgoingToPeer, "cancelled");
+      }
+    }
+    if (!call) {
+      const now = this.port.now();
+      call = {
+        callId: envelope.callId,
+        peerApId: envelope.from,
+        direction: "incoming",
+        state: "ringing",
+        media: envelope.media ?? { audio: true, video: false },
+        sfuFocus: envelope.sfuFocus ?? null,
+        createdAt: now,
+        updatedAt: now,
+      };
+      this.calls.set(call.callId, call);
+      void this.port.persist?.(call);
+    }
+    // Wake an offline client (best effort) and ring any live ones.
+    void this.port.ring?.(envelope);
+    if (this.port.hasClients()) {
+      const media = await this.port.provisionMedia(call.media);
+      this.port.broadcast({
+        t: "ice-servers",
+        callId: call.callId,
+        iceServers: media.iceServers,
+        sfuFocus: media.sfuFocus,
+      });
+      this.port.broadcast({
+        t: "ringing",
+        callId: call.callId,
+        from: call.peerApId,
+        media: call.media,
+      });
+    }
+    if (envelope.sdp) {
+      this.port.broadcast({
+        t: "offer",
+        callId: call.callId,
+        sdp: envelope.sdp,
+        media: call.media,
+      });
+    }
+  }
+
+  private onPeerAnswer(envelope: RtcSignalEnvelopeV1): void {
+    const call = this.calls.get(envelope.callId);
+    if (!call || !envelope.sdp) return;
+    if (call.state === "ringing") this.transition(call, "connecting");
+    this.port.broadcast({
+      t: "answer",
+      callId: call.callId,
+      sdp: envelope.sdp,
+    });
+  }
+
+  private onPeerCandidate(envelope: RtcSignalEnvelopeV1): void {
+    const call = this.calls.get(envelope.callId);
+    if (!call || !envelope.candidates?.length) return;
+    this.port.broadcast({
+      t: "candidates",
+      callId: call.callId,
+      candidates: envelope.candidates,
+    });
+  }
+
+  private onPeerAccept(envelope: RtcSignalEnvelopeV1): void {
+    const call = this.calls.get(envelope.callId);
+    if (!call) return;
+    if (call.state === "ringing") this.transition(call, "connecting");
+    this.port.broadcast({ t: "peer-accepted", callId: call.callId });
+  }
+
+  private onPeerReject(envelope: RtcSignalEnvelopeV1): void {
+    const call = this.calls.get(envelope.callId);
+    if (!call) return;
+    this.port.broadcast({
+      t: "peer-rejected",
+      callId: call.callId,
+      reason: envelope.reason,
+    });
+    this.transition(call, "rejected");
+  }
+
+  private onPeerHangup(envelope: RtcSignalEnvelopeV1): void {
+    const call = this.calls.get(envelope.callId);
+    if (!call) return;
+    this.port.broadcast({
+      t: "peer-hangup",
+      callId: call.callId,
+      reason: envelope.reason,
+    });
+    this.transition(call, call.connectedAt ? "ended" : "cancelled");
+  }
+
+  /** Promote a call to connected (client signals ICE established). */
+  markConnected(callId: string): void {
+    const call = this.calls.get(callId);
+    if (call && call.state !== "connected") this.transition(call, "connected");
+  }
+
+  // -------------------------------------------------------------------------
+  // Periodic sweep (DO alarm / dev interval) — expire stuck calls
+  // -------------------------------------------------------------------------
+
+  tick(): void {
+    const now = this.port.now();
+    for (const call of [...this.calls.values()]) {
+      const age = now - call.updatedAt;
+      if (call.state === "ringing" && age > RINGING_TIMEOUT_MS) {
+        this.transition(
+          call,
+          call.direction === "incoming" ? "missed" : "cancelled",
+        );
+      } else if (call.state === "connecting" && age > CONNECTING_TIMEOUT_MS) {
+        this.transition(call, "failed");
+      }
+    }
+  }
+}