@takosjp/yurucommu-core 3.2.1 → 3.3.0

package/packages/api/src/types/call.ts

@@ -0,0 +1,306 @@
+/**
+ * Call signaling wire contract (voice + video).
+ *
+ * SINGLE SOURCE OF TRUTH shared by:
+ *   - the backend cross-instance signaling ingest (`/ap/rtc/signal`) + the
+ *     Signaling Durable Object (server-to-server + browser fan-out), and
+ *   - the browser `CallClient` (`../lib/rtc-client.ts`).
+ *
+ * Kept deliberately DOM-structural (no `RTCIceCandidateInit` / `RTCIceServer`
+ * imports) so the same file type-checks in the server context (which never runs
+ * the browser WebRTC APIs) and the browser bundle. The `CallClient` maps these
+ * structural shapes to/from the real DOM `RTCSessionDescriptionInit` /
+ * `RTCIceCandidateInit` / `RTCIceServer`, which are structurally compatible.
+ *
+ * Design: signaling travels over federation (server-to-server, HTTP-Signature
+ * authenticated) as `RtcSignalEnvelopeV1`; media is P2P WebRTC + STUN/TURN for
+ * 1:1 (`sfuFocus: null`) and a pluggable WHIP/WHEP SFU focus for group calls.
+ */
+
+export const RTC_SIGNAL_ENVELOPE_VERSION = 1 as const;
+
+/** Which media tracks a call carries. `video:false` => audio-only call. */
+export interface CallMediaKind {
+  audio: boolean;
+  video: boolean;
+}
+
+/** Cross-instance signaling message kinds (Matrix-VoIP inspired). */
+export type RtcSignalType =
+  | "offer"
+  | "answer"
+  | "candidate"
+  | "accept"
+  | "reject"
+  | "hangup"
+  | "cancel";
+
+/**
+ * Selected SFU focus for a group call. `null`/absent means pure P2P (1:1).
+ * `kind` names the adapter (`whip` / `livekit` / `cloudflare-realtime` / ...);
+ * the client talks WHIP/WHEP so the SFU backend stays vendor-neutral.
+ */
+export interface SfuFocus {
+  kind: string;
+  /** WHIP (publish) / WHEP (subscribe) endpoint base, or SFU signaling URL. */
+  url: string;
+  /** Short-lived join token when the adapter requires one. */
+  token?: string;
+  room?: string;
+}
+
+/** Structural mirror of `RTCIceCandidateInit` (no DOM dependency). */
+export interface CallIceCandidate {
+  candidate: string;
+  sdpMid?: string | null;
+  sdpMLineIndex?: number | null;
+  usernameFragment?: string | null;
+}
+
+/** Structural mirror of `RTCIceServer` (no DOM dependency). */
+export interface IceServerConfig {
+  urls: string | string[];
+  username?: string;
+  credential?: string;
+}
+
+/**
+ * Server-to-server signaling envelope. Delivered by the sending instance to the
+ * recipient instance's `/ap/rtc/signal` endpoint, signed with the sender actor's
+ * HTTP Signature key (keyId-owner === `from`). `callId` doubles as the anti-
+ * replay nonce; `ts`/`ttlMs` bound its freshness (the DO drops stale frames).
+ */
+export interface RtcSignalEnvelopeV1 {
+  v: typeof RTC_SIGNAL_ENVELOPE_VERSION;
+  callId: string;
+  from: string;
+  to: string;
+  type: RtcSignalType;
+  media?: CallMediaKind;
+  /** SDP for `offer` / `answer`. */
+  sdp?: string;
+  /** Half-trickle ICE bundle for `offer` / `answer` / `candidate`. */
+  candidates?: CallIceCandidate[];
+  sfuFocus?: SfuFocus | null;
+  /** Free-text end/reject reason (`busy`, `declined`, `timeout`, ...). */
+  reason?: string;
+  ts: number;
+  ttlMs: number;
+}
+
+/** Lifecycle of a single call, mirrored client-side and in `call_sessions`. */
+export type CallState =
+  | "idle"
+  | "ringing"
+  | "connecting"
+  | "connected"
+  | "ended"
+  | "rejected"
+  | "missed"
+  | "failed"
+  | "cancelled";
+
+export type CallDirection = "incoming" | "outgoing";
+
+/** Terminal states — a call in one of these is over and not resumable. */
+export const TERMINAL_CALL_STATES: readonly CallState[] = [
+  "ended",
+  "rejected",
+  "missed",
+  "failed",
+  "cancelled",
+];
+
+export function isTerminalCallState(state: CallState): boolean {
+  return TERMINAL_CALL_STATES.includes(state);
+}
+
+// ---------------------------------------------------------------------------
+// Browser <-> Signaling Durable Object WebSocket frames
+// ---------------------------------------------------------------------------
+
+/** Frames the browser sends up to its own instance's Signaling DO. */
+export type ClientToHubFrame =
+  | { t: "hello" }
+  | { t: "invite"; callId: string; to: string; media: CallMediaKind }
+  | { t: "offer"; callId: string; sdp: string }
+  | { t: "answer"; callId: string; sdp: string }
+  | { t: "candidates"; callId: string; candidates: CallIceCandidate[] }
+  | { t: "accept"; callId: string }
+  | { t: "reject"; callId: string; reason?: string }
+  | { t: "hangup"; callId: string; reason?: string }
+  | { t: "resume"; callId: string }
+  | { t: "ping" };
+
+/** Frames the Signaling DO pushes down to the browser. */
+export type HubToClientFrame =
+  | { t: "ready" }
+  | { t: "ringing"; callId: string; from: string; media: CallMediaKind }
+  | { t: "offer"; callId: string; sdp: string; media?: CallMediaKind }
+  | { t: "answer"; callId: string; sdp: string }
+  | { t: "candidates"; callId: string; candidates: CallIceCandidate[] }
+  | { t: "peer-accepted"; callId: string }
+  | { t: "peer-rejected"; callId: string; reason?: string }
+  | { t: "peer-hangup"; callId: string; reason?: string }
+  | {
+      t: "ice-servers";
+      callId: string;
+      iceServers: IceServerConfig[];
+      sfuFocus?: SfuFocus | null;
+    }
+  | { t: "call-state"; callId: string; state: CallState }
+  | { t: "pong" }
+  | { t: "error"; code: string; message?: string };
+
+// ---------------------------------------------------------------------------
+// REST contract (start call / mint ICE / call history)
+// ---------------------------------------------------------------------------
+
+export interface StartCallRequest {
+  to: string;
+  media: CallMediaKind;
+}
+
+export interface StartCallResponse {
+  callId: string;
+  iceServers: IceServerConfig[];
+  sfuFocus?: SfuFocus | null;
+}
+
+export interface IceServersResponse {
+  iceServers: IceServerConfig[];
+}
+
+export interface CallSessionSummary {
+  id: string;
+  peer: string;
+  direction: CallDirection;
+  state: CallState;
+  media: CallMediaKind;
+  createdAt: string;
+  connectedAt?: string | null;
+  endedAt?: string | null;
+  endReason?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime validation (used by the backend ingest to reject malformed frames)
+// ---------------------------------------------------------------------------
+
+const SIGNAL_TYPES: readonly RtcSignalType[] = [
+  "offer",
+  "answer",
+  "candidate",
+  "accept",
+  "reject",
+  "hangup",
+  "cancel",
+];
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isCallMediaKind(value: unknown): value is CallMediaKind {
+  return (
+    isPlainObject(value) &&
+    typeof value.audio === "boolean" &&
+    typeof value.video === "boolean"
+  );
+}
+
+function parseCandidates(value: unknown): CallIceCandidate[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) return undefined;
+  const out: CallIceCandidate[] = [];
+  for (const raw of value) {
+    if (!isPlainObject(raw) || typeof raw.candidate !== "string") continue;
+    out.push({
+      candidate: raw.candidate,
+      sdpMid: typeof raw.sdpMid === "string" ? raw.sdpMid : null,
+      sdpMLineIndex:
+        typeof raw.sdpMLineIndex === "number" ? raw.sdpMLineIndex : null,
+      usernameFragment:
+        typeof raw.usernameFragment === "string" ? raw.usernameFragment : null,
+    });
+  }
+  return out;
+}
+
+function parseSfuFocus(value: unknown): SfuFocus | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (!isPlainObject(value)) return undefined;
+  if (typeof value.kind !== "string" || typeof value.url !== "string") {
+    return undefined;
+  }
+  return {
+    kind: value.kind,
+    url: value.url,
+    token: typeof value.token === "string" ? value.token : undefined,
+    room: typeof value.room === "string" ? value.room : undefined,
+  };
+}
+
+/**
+ * Parse + validate an inbound cross-instance signaling envelope. Returns the
+ * normalized envelope or `null` when the shape is invalid. Callers additionally
+ * enforce that the HTTP-Signature signer equals `from` and that the recipient
+ * (`to`) is a local actor.
+ */
+export function parseRtcSignalEnvelope(
+  input: unknown,
+): RtcSignalEnvelopeV1 | null {
+  if (!isPlainObject(input)) return null;
+  if (input.v !== RTC_SIGNAL_ENVELOPE_VERSION) return null;
+  const { callId, from, to, type, ts, ttlMs } = input;
+  if (
+    typeof callId !== "string" ||
+    callId.length === 0 ||
+    callId.length > 200 ||
+    typeof from !== "string" ||
+    from.length === 0 ||
+    typeof to !== "string" ||
+    to.length === 0 ||
+    typeof type !== "string" ||
+    !SIGNAL_TYPES.includes(type as RtcSignalType) ||
+    typeof ts !== "number" ||
+    !Number.isFinite(ts) ||
+    typeof ttlMs !== "number" ||
+    !Number.isFinite(ttlMs) ||
+    ttlMs < 0
+  ) {
+    return null;
+  }
+  const sdp = typeof input.sdp === "string" ? input.sdp : undefined;
+  // Guard against absurd SDP blobs abusing the endpoint as a relay.
+  if (sdp !== undefined && sdp.length > 100_000) return null;
+  return {
+    v: RTC_SIGNAL_ENVELOPE_VERSION,
+    callId,
+    from,
+    to,
+    type: type as RtcSignalType,
+    media: isCallMediaKind(input.media) ? input.media : undefined,
+    sdp,
+    candidates: parseCandidates(input.candidates),
+    sfuFocus: parseSfuFocus(input.sfuFocus),
+    reason:
+      typeof input.reason === "string"
+        ? input.reason.slice(0, 200)
+        : undefined,
+    ts,
+    ttlMs,
+  };
+}
+
+/** True when the envelope is still within its freshness window. */
+export function isEnvelopeFresh(
+  envelope: RtcSignalEnvelopeV1,
+  now: number,
+): boolean {
+  // Reject frames from the future (clock skew tolerance) or past their TTL.
+  const skewToleranceMs = 30_000;
+  if (envelope.ts - now > skewToleranceMs) return false;
+  return now - envelope.ts <= envelope.ttlMs;
+}

package/packages/api/src/types/index.ts

@@ -1,3 +1,6 @@
+// Call signaling wire contract + browser<->hub frames (voice + video).
+export * from "./call.ts";
+
 // ===== Yurucommu AP-Native Types =====
 
 // Actor represents a user (Person) in ActivityPub

package/src/backend/index.ts

@@ -29,6 +29,7 @@ import { moderationRoutes } from "./routes/moderation.ts";
 import { appsApiRoutes, appsServeRoutes } from "./routes/apps.ts";
 import mobileRoutes from "./routes/mobile.ts";
 import notificationPusherRoutes from "./routes/notification-pushers.ts";
+import rtcRoutes from "./routes/rtc/index.ts";
 
 import { rateLimit, RateLimitConfigs } from "./middleware/rate-limit.ts";
 import { csrfProtection } from "./middleware/csrf.ts";
@@ -254,6 +255,7 @@ function buildSocialServerDiscovery(
       authProviders: `${appUrl}/api/auth/providers`,
       mobilePasswordLogin: `${appUrl}/api/auth/mobile/login`,
       mobileOidcExchange: `${appUrl}/api/auth/mobile/oidc`,
+      mobileLogout: `${appUrl}/api/auth/logout`,
       currentUser: `${appUrl}/api/auth/me`,
       timeline: `${appUrl}/api/timeline`,
       conversations: `${appUrl}/api/dm/contacts`,
@@ -506,6 +508,11 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
   app.use("*", async (c, next) => {
     await next();
 
+    // A 101 Switching Protocols response carries a WebSocket and immutable
+    // headers (the /api/rtc/socket call upgrade). Mutating it throws and breaks
+    // the upgrade, so skip the security-header pass for it.
+    if (c.res.status === 101) return;
+
     const preserveRouteSecurityHeaders = c.req.path.startsWith("/hosted/");
     const setSecurityHeader = (name: string, value: string) => {
       if (preserveRouteSecurityHeaders && c.res.headers.has(name)) {
@@ -553,9 +560,11 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
     setSecurityHeader("X-Content-Type-Options", "nosniff");
     setSecurityHeader("X-Frame-Options", "DENY");
     setSecurityHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+    // Allow the app's OWN origin to use camera + microphone (WebRTC calls);
+    // still deny geolocation and deny camera/mic to any cross-origin frame.
     setSecurityHeader(
       "Permissions-Policy",
-      "camera=(), microphone=(), geolocation=()",
+      "camera=(self), microphone=(self), geolocation=()",
     );
     // HSTS: once a client has reached this host over HTTPS, keep it on HTTPS
     // (defeats SSL-strip / downgrade). Sent unconditionally — browsers ignore it
@@ -693,6 +702,11 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
     app.use(pattern, rateLimit(RateLimitConfigs.inbox));
   }
 
+  // Cross-instance call signaling ingest is unauthenticated at the network edge
+  // (it verifies an HTTP Signature inside the handler) and can be hit by any
+  // remote instance, so throttle it per-IP like the other federation endpoints.
+  app.use("/ap/rtc/signal", rateLimit(RateLimitConfigs.federationDiscovery));
+
   // Federation discovery endpoints are unauthenticated and can be probed by
   // any remote actor. Throttle them per-IP to mitigate enumeration / DoS.
   app.use(
@@ -766,6 +780,8 @@ function mountCoreRoutes(app: YurucommuApp): void {
   app.route("/api/moderation", moderationRoutes);
   app.route("/api/apps", appsApiRoutes);
   app.route("/hosted", appsServeRoutes);
+  // Call feature: /api/rtc/* (session) + /ap/rtc/signal (server-to-server).
+  app.route("/", rtcRoutes);
   app.route("/", activitypubRoutes);
 }
 
@@ -933,6 +949,10 @@ type WorkerBindings = EnvVars & {
   ASSETS?: Fetcher;
   DELIVERY_QUEUE?: Queue<DeliveryQueueMessageV1>;
   DELIVERY_DLQ?: Queue<DeliveryDlqMessageV1>;
+  // Signaling hub Durable Object namespace (call feature). wrapCloudflareBindings
+  // spreads it through untouched (it is not DB/MEDIA/KV/ASSETS) so app code and
+  // the rtc routes read it as c.env.CALL_SIGNALING.
+  CALL_SIGNALING?: DurableObjectNamespace;
 };
 
 export default {

package/src/backend/lib/rtc/call-store.ts

@@ -0,0 +1,101 @@
+/**
+ * Durable persistence for call sessions (history / missed-call / current state).
+ * Ephemeral SDP/ICE never touches this — only the call lifecycle does.
+ */
+
+import { and, desc, eq } from "drizzle-orm";
+import type { Database } from "../../../db/index.ts";
+import { callSessions, nowIso } from "../../../db/index.ts";
+import type {
+  CallSessionSummary,
+  CallDirection,
+  CallState,
+} from "../../../../packages/api/src/types/call.ts";
+import { isTerminalCallState } from "../../../../packages/api/src/types/call.ts";
+import type { CallRecord } from "../../runtime/call-hub-core.ts";
+
+/** Insert or update the durable row for a call transition. */
+export async function upsertCallSession(
+  db: Database,
+  localActorApId: string,
+  call: CallRecord,
+): Promise<void> {
+  const now = nowIso();
+  const terminal = isTerminalCallState(call.state);
+  const connectedAt = call.connectedAt
+    ? new Date(call.connectedAt).toISOString()
+    : null;
+  const sfuFocus = call.sfuFocus ? JSON.stringify(call.sfuFocus) : null;
+  await db
+    .insert(callSessions)
+    .values({
+      id: call.callId,
+      localActorApId,
+      peerActorApId: call.peerApId,
+      direction: call.direction,
+      state: call.state,
+      mediaAudio: call.media.audio ? 1 : 0,
+      mediaVideo: call.media.video ? 1 : 0,
+      sfuFocus,
+      peerSignalEndpoint: call.peerSignalEndpoint ?? null,
+      connectedAt,
+      endedAt: terminal ? now : null,
+    })
+    .onConflictDoUpdate({
+      target: callSessions.id,
+      set: {
+        state: call.state,
+        sfuFocus,
+        peerSignalEndpoint: call.peerSignalEndpoint ?? null,
+        connectedAt,
+        endedAt: terminal ? now : null,
+        updatedAt: now,
+      },
+    });
+}
+
+function toSummary(row: typeof callSessions.$inferSelect): CallSessionSummary {
+  return {
+    id: row.id,
+    peer: row.peerActorApId,
+    direction: row.direction as CallDirection,
+    state: row.state as CallState,
+    media: { audio: row.mediaAudio === 1, video: row.mediaVideo === 1 },
+    createdAt: row.createdAt,
+    connectedAt: row.connectedAt,
+    endedAt: row.endedAt,
+    endReason: row.endReason,
+  };
+}
+
+export async function listCallSessions(
+  db: Database,
+  localActorApId: string,
+  limit = 50,
+): Promise<CallSessionSummary[]> {
+  const rows = await db
+    .select()
+    .from(callSessions)
+    .where(eq(callSessions.localActorApId, localActorApId))
+    .orderBy(desc(callSessions.createdAt))
+    .limit(Math.min(Math.max(limit, 1), 200));
+  return rows.map(toSummary);
+}
+
+export async function getCallSession(
+  db: Database,
+  localActorApId: string,
+  callId: string,
+): Promise<CallSessionSummary | null> {
+  const row = await db
+    .select()
+    .from(callSessions)
+    .where(
+      and(
+        eq(callSessions.id, callId),
+        eq(callSessions.localActorApId, localActorApId),
+      ),
+    )
+    .get();
+  return row ? toSummary(row) : null;
+}

package/src/backend/lib/rtc/provider.ts

@@ -0,0 +1,135 @@
+/**
+ * RtcProvider — media-plane configuration for the call feature.
+ *
+ * This is the seam that keeps calling vendor-neutral: 1:1 calls are pure P2P
+ * WebRTC over the operator-configured STUN/TURN servers (no SFU, no Cloudflare),
+ * and group calls (Phase 3) select a WHIP/WHEP SFU "focus" whose backend is any
+ * of `whip` / `livekit` / `cloudflare-realtime` — Cloudflare Realtime is one
+ * adapter among equals, never required.
+ *
+ * TURN credentials, when coturn's REST scheme is configured, are minted
+ * per-request as short-lived HMAC creds (RFC 8489 long-term-credential via the
+ * `turn-rest` `timestamp:name` username convention) — no static long-lived
+ * secret is ever handed to a client.
+ */
+
+import type {
+  CallMediaKind,
+  IceServerConfig,
+  SfuFocus,
+} from "../../../../packages/api/src/types/call.ts";
+import type { EnvVars } from "../../types.ts";
+import { bufferToBase64 } from "../base64.ts";
+import { logger } from "../logger.ts";
+
+const log = logger.child({ component: "rtc.provider" });
+
+const DEFAULT_TURN_TTL_SECONDS = 3600;
+
+export interface RtcProvider {
+  /** ICE (STUN/TURN) servers for a call. Fresh (short-lived) TURN creds. */
+  getIceServers(): Promise<IceServerConfig[]>;
+  /** Group-call SFU focus, or null for pure P2P (always null for 1:1). */
+  getSfuFocus(media: CallMediaKind): Promise<SfuFocus | null>;
+}
+
+function parseStaticIceServers(raw: string | undefined): IceServerConfig[] {
+  if (!raw?.trim()) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    const out: IceServerConfig[] = [];
+    for (const entry of parsed) {
+      if (!entry || typeof entry !== "object") continue;
+      const urls = (entry as { urls?: unknown }).urls;
+      if (typeof urls !== "string" && !Array.isArray(urls)) continue;
+      const server: IceServerConfig = { urls: urls as string | string[] };
+      const username = (entry as { username?: unknown }).username;
+      const credential = (entry as { credential?: unknown }).credential;
+      if (typeof username === "string") server.username = username;
+      if (typeof credential === "string") server.credential = credential;
+      out.push(server);
+    }
+    return out;
+  } catch (err) {
+    log.warn("Invalid YURUCOMMU_RTC_ICE_SERVERS JSON", { error: String(err) });
+    return [];
+  }
+}
+
+async function mintTurnCredential(
+  uris: string[],
+  secret: string,
+  ttlSeconds: number,
+): Promise<IceServerConfig | null> {
+  if (uris.length === 0 || !secret) return null;
+  // coturn REST: username = "<unix-expiry>:<name>", credential = base64(HMAC-
+  // SHA1(secret, username)). A random name keeps creds unlinkable per call.
+  const expiry = Math.floor(Date.now() / 1000) + ttlSeconds;
+  const username = `${expiry}:yurucommu`;
+  try {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(secret),
+      { name: "HMAC", hash: "SHA-1" },
+      false,
+      ["sign"],
+    );
+    const mac = await crypto.subtle.sign(
+      "HMAC",
+      key,
+      new TextEncoder().encode(username),
+    );
+    return { urls: uris, username, credential: bufferToBase64(mac) };
+  } catch (err) {
+    log.error("Failed to mint TURN credential", { error: String(err) });
+    return null;
+  }
+}
+
+class ConfiguredRtcProvider implements RtcProvider {
+  constructor(private readonly env: EnvVars) {}
+
+  async getIceServers(): Promise<IceServerConfig[]> {
+    const servers = parseStaticIceServers(this.env.YURUCOMMU_RTC_ICE_SERVERS);
+    const uris = (this.env.YURUCOMMU_RTC_TURN_URIS ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const secret = this.env.YURUCOMMU_RTC_TURN_SECRET?.trim();
+    if (uris.length > 0 && secret) {
+      const ttl =
+        Number.parseInt(this.env.YURUCOMMU_RTC_TURN_TTL ?? "", 10) ||
+        DEFAULT_TURN_TTL_SECONDS;
+      const turn = await mintTurnCredential(uris, secret, ttl);
+      if (turn) servers.push(turn);
+    }
+    return servers;
+  }
+
+  async getSfuFocus(_media: CallMediaKind): Promise<SfuFocus | null> {
+    const adapter = (this.env.YURUCOMMU_RTC_SFU_ADAPTER ?? "p2p")
+      .trim()
+      .toLowerCase();
+    if (adapter === "" || adapter === "p2p") return null;
+    const url = this.env.YURUCOMMU_RTC_SFU_URL?.trim();
+    if (!url) {
+      log.warn("SFU adapter selected but YURUCOMMU_RTC_SFU_URL unset", {
+        adapter,
+      });
+      return null;
+    }
+    // WHIP/WHEP focus passthrough. Real per-room token minting (LiveKit JWT,
+    // Cloudflare Realtime app tokens) lands with group calls (Phase 3); today
+    // the shared/static token (if any) is advertised as-is.
+    return {
+      kind: adapter,
+      url,
+      token: this.env.YURUCOMMU_RTC_SFU_TOKEN?.trim() || undefined,
+    };
+  }
+}
+
+export function createRtcProvider(env: EnvVars): RtcProvider {
+  return new ConfiguredRtcProvider(env);
+}