create-safest-tools 0.2.0

package/template/src/report-presence.ts

@@ -0,0 +1,398 @@
+import { DurableObject } from "cloudflare:workers";
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+
+export type AnalystActivity = "online" | "viewing" | "editing" | "away";
+
+export interface AnalystProfile {
+  actorId: string;
+  displayName: string;
+  email: string | null;
+  avatarUrl: string | null;
+  avatarColor: string;
+  roles: string[];
+}
+
+export interface AnalystPresence extends AnalystProfile {
+  activity: AnalystActivity;
+  activeReportId: string | null;
+  connectedAt: string;
+  lastSeenAt: string;
+}
+
+interface PresenceAttachment {
+  version: 1;
+  actorId: string;
+  sessionId: string;
+  activity: AnalystActivity;
+  activeReportId: string | null;
+  allowedQueueIds: string[] | null;
+}
+
+interface PresenceRow {
+  actor_id: string;
+  display_name: string;
+  email: string | null;
+  avatar_url: string | null;
+  avatar_color: string;
+  roles_json: string;
+  activity_state: AnalystActivity;
+  active_report_id: string | null;
+  connected_at: string;
+  last_seen_at: string;
+}
+
+const colors = ["#315d4d", "#5d4f82", "#8a5a3b", "#2f657a", "#7a4b57", "#59683d", "#6b5635", "#3f5f88"];
+const activities = new Set<AnalystActivity>(["online", "viewing", "editing", "away"]);
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
+function validActorId(value: string): boolean {
+  return value.length > 0 && value.length <= 200 && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function subtractSeconds(timestamp: string, seconds: number): string {
+  return new Date(Date.parse(timestamp) - seconds * 1_000).toISOString();
+}
+
+function addMinutes(timestamp: string, minutes: number): string {
+  return new Date(Date.parse(timestamp) + minutes * 60_000).toISOString();
+}
+
+export function analystAvatarColor(actorId: string): string {
+  let hash = 2_166_136_261;
+  for (const character of actorId) {
+    hash ^= character.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16_777_619);
+  }
+  return colors[(hash >>> 0) % colors.length] ?? colors[0]!;
+}
+
+function parseRoles(value: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((role): role is string => typeof role === "string").slice(0, 20) : [];
+  } catch {
+    return [];
+  }
+}
+
+function profileFromRow(row: PresenceRow): AnalystProfile {
+  return {
+    actorId: row.actor_id,
+    displayName: row.display_name,
+    email: row.email,
+    avatarUrl: row.avatar_url,
+    avatarColor: row.avatar_color,
+    roles: parseRoles(row.roles_json),
+  };
+}
+
+export async function recordAnalystAuthentication(db: D1Database, session: OperatorSession): Promise<AnalystProfile> {
+  const authenticatedAt = now();
+  const avatarColor = analystAvatarColor(session.actor.id);
+  const rolesJson = canonicalJson(session.roles);
+  await db.prepare(`
+    INSERT INTO analyst_profiles (
+      actor_id, display_name, email, avatar_url, avatar_color, roles_json,
+      created_at, updated_at, last_authenticated_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?7, ?7)
+    ON CONFLICT(actor_id) DO UPDATE SET
+      display_name = excluded.display_name,
+      email = excluded.email,
+      avatar_url = excluded.avatar_url,
+      avatar_color = excluded.avatar_color,
+      roles_json = excluded.roles_json,
+      updated_at = excluded.updated_at,
+      last_authenticated_at = excluded.last_authenticated_at
+    WHERE analyst_profiles.display_name != excluded.display_name
+       OR COALESCE(analyst_profiles.email, '') != COALESCE(excluded.email, '')
+       OR COALESCE(analyst_profiles.avatar_url, '') != COALESCE(excluded.avatar_url, '')
+       OR analyst_profiles.roles_json != excluded.roles_json
+       OR analyst_profiles.last_authenticated_at <= ?8
+  `).bind(
+    session.actor.id, session.displayName, session.email ?? null, session.avatarUrl ?? null,
+    avatarColor, rolesJson, authenticatedAt, subtractSeconds(authenticatedAt, 3_600),
+  ).run();
+  return {
+    actorId: session.actor.id,
+    displayName: session.displayName,
+    email: session.email ?? null,
+    avatarUrl: session.avatarUrl ?? null,
+    avatarColor,
+    roles: session.roles,
+  };
+}
+
+export async function listAnalystPresence(
+  db: D1Database,
+  staleAfterSeconds = 45,
+  allowedQueueIds?: string[] | null,
+): Promise<AnalystPresence[]> {
+  const cutoff = subtractSeconds(now(), Math.max(15, Math.min(300, staleAfterSeconds)));
+  const rows = await db.prepare(`
+    WITH ranked_sessions AS (
+      SELECT s.*,
+        ROW_NUMBER() OVER (
+          PARTITION BY s.actor_id
+          ORDER BY CASE s.activity_state WHEN 'editing' THEN 0 WHEN 'viewing' THEN 1 WHEN 'online' THEN 2 ELSE 3 END,
+                   s.last_seen_at DESC, s.id DESC
+        ) AS rank
+      FROM analyst_sessions s
+      WHERE s.last_seen_at > ?1
+    )
+    SELECT p.actor_id, p.display_name, p.email, p.avatar_url, p.avatar_color, p.roles_json,
+           s.activity_state,
+           CASE WHEN ?2 = 1 OR s.active_report_id IS NULL OR EXISTS (
+             SELECT 1 FROM reports r
+             WHERE r.id = s.active_report_id AND r.queue_id IN (SELECT value FROM json_each(?3))
+           ) THEN s.active_report_id ELSE NULL END AS active_report_id,
+           s.connected_at, s.last_seen_at
+    FROM ranked_sessions s
+    JOIN analyst_profiles p ON p.actor_id = s.actor_id
+    WHERE s.rank = 1
+    ORDER BY CASE s.activity_state WHEN 'editing' THEN 0 WHEN 'viewing' THEN 1 WHEN 'online' THEN 2 ELSE 3 END,
+             p.display_name, p.actor_id
+  `).bind(
+    cutoff,
+    allowedQueueIds === null || allowedQueueIds === undefined ? 1 : 0,
+    canonicalJson(allowedQueueIds ?? []),
+  ).all<PresenceRow>();
+  return rows.results.map((row) => ({
+    ...profileFromRow(row),
+    activity: row.activity_state,
+    activeReportId: row.active_report_id,
+    connectedAt: row.connected_at,
+    lastSeenAt: row.last_seen_at,
+  }));
+}
+
+export async function touchAnalystSession(
+  db: D1Database,
+  input: {
+    sessionId: string;
+    actorId: string;
+    activity: AnalystActivity;
+    activeReportId: string | null;
+    allowedQueueIds?: string[] | null;
+    claimTtlMinutes: number;
+  },
+): Promise<{ claimRenewed: boolean; activeReportId: string | null }> {
+  const seenAt = now();
+  let activeReportId = input.activeReportId;
+  if (activeReportId && input.allowedQueueIds !== null && input.allowedQueueIds !== undefined) {
+    const accessible = input.allowedQueueIds.length
+      ? await db.prepare(`
+          SELECT id FROM reports
+          WHERE id = ?1 AND queue_id IN (SELECT value FROM json_each(?2)) LIMIT 1
+        `).bind(activeReportId, canonicalJson(input.allowedQueueIds)).first()
+      : null;
+    if (!accessible) activeReportId = null;
+  }
+  const claimTtl = Math.max(1, Math.min(1_440, input.claimTtlMinutes));
+  const renewBefore = addMinutes(seenAt, Math.max(1, Math.floor(claimTtl / 2)));
+  const expiresAt = addMinutes(seenAt, claimTtl);
+  const results = await db.batch([
+    db.prepare(`
+      INSERT INTO analyst_sessions (
+        id, actor_id, activity_state, active_report_id, connected_at, last_seen_at
+      ) VALUES (
+        ?1, ?2, ?3,
+        CASE WHEN ?4 IS NOT NULL AND EXISTS (SELECT 1 FROM reports WHERE id = ?4) THEN ?4 ELSE NULL END,
+        ?5, ?5
+      )
+      ON CONFLICT(id) DO UPDATE SET
+        activity_state = excluded.activity_state,
+        active_report_id = excluded.active_report_id,
+        last_seen_at = excluded.last_seen_at
+      WHERE analyst_sessions.actor_id = excluded.actor_id
+    `).bind(input.sessionId, input.actorId, input.activity, activeReportId, seenAt),
+    db.prepare(`
+      UPDATE review_claims
+      SET expires_at = ?3
+      WHERE report_id = ?1 AND reviewer_id = ?2 AND expires_at > ?4 AND expires_at < ?5
+        AND ?6 = 'editing'
+    `).bind(activeReportId, input.actorId, expiresAt, seenAt, renewBefore, input.activity),
+  ]);
+  return { claimRenewed: (results[1]?.meta.changes ?? 0) > 0, activeReportId };
+}
+
+export async function removeAnalystSession(db: D1Database, sessionId: string, actorId: string): Promise<void> {
+  await db.prepare(`DELETE FROM analyst_sessions WHERE id = ?1 AND actor_id = ?2`).bind(sessionId, actorId).run();
+}
+
+export async function pruneStaleAnalystSessions(db: D1Database, staleAfterSeconds = 300): Promise<number> {
+  const result = await db.prepare(`DELETE FROM analyst_sessions WHERE last_seen_at <= ?1`)
+    .bind(subtractSeconds(now(), Math.max(60, Math.min(3_600, staleAfterSeconds)))).run();
+  return result.meta.changes ?? 0;
+}
+
+function attachment(value: unknown): PresenceAttachment | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const candidate = value as Partial<PresenceAttachment>;
+  if (candidate.version !== 1 || typeof candidate.actorId !== "string" || typeof candidate.sessionId !== "string"
+    || !activities.has(candidate.activity as AnalystActivity)
+    || candidate.activeReportId !== null && typeof candidate.activeReportId !== "string"
+    || candidate.allowedQueueIds !== null && (!Array.isArray(candidate.allowedQueueIds)
+      || candidate.allowedQueueIds.length > 100
+      || candidate.allowedQueueIds.some((queueId) => typeof queueId !== "string" || queueId.length > 100))) return null;
+  return candidate as PresenceAttachment;
+}
+
+function queueScope(value: string | null): string[] | null {
+  if (!value || value.length > 12_000) return [];
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (parsed === null) return null;
+    if (!Array.isArray(parsed) || parsed.length > 100
+      || parsed.some((queueId) => typeof queueId !== "string" || queueId.length > 100)) return [];
+    return parsed;
+  } catch {
+    return [];
+  }
+}
+
+function websocketMessage(value: string | ArrayBuffer): { type: "heartbeat" | "focus_report" | "blur_report"; reportId: string | null; activity: AnalystActivity } | null {
+  if (typeof value !== "string" || value.length > 4_096) return null;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const input = parsed as Record<string, unknown>;
+    if (input.type === "heartbeat") {
+      const activity = activities.has(input.activity as AnalystActivity) ? input.activity as AnalystActivity : "online";
+      const reportId = typeof input.report_id === "string" && input.report_id.length <= 100 ? input.report_id : null;
+      return { type: "heartbeat", reportId, activity };
+    }
+    if (input.type === "focus_report" && typeof input.report_id === "string" && input.report_id.length <= 100) {
+      return { type: "focus_report", reportId: input.report_id, activity: input.editing === true ? "editing" : "viewing" };
+    }
+    if (input.type === "blur_report") return { type: "blur_report", reportId: null, activity: "online" };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export class WorkspacePresence extends DurableObject<Env> {
+  private send(ws: WebSocket, value: unknown): void {
+    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(value));
+  }
+
+  private broadcast(value: unknown): void {
+    for (const ws of this.ctx.getWebSockets()) this.send(ws, value);
+  }
+
+  private async broadcastSnapshot(): Promise<void> {
+    const snapshots = new Map<string, AnalystPresence[]>();
+    for (const ws of this.ctx.getWebSockets()) {
+      const scope = attachment(ws.deserializeAttachment())?.allowedQueueIds ?? [];
+      const key = canonicalJson(scope);
+      let analysts = snapshots.get(key);
+      if (!analysts) {
+        analysts = await listAnalystPresence(this.env.DB, 45, scope);
+        snapshots.set(key, analysts);
+      }
+      this.send(ws, { type: "presence_snapshot", analysts, sent_at: now() });
+    }
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("WebSocket upgrade required", { status: 426, headers: { upgrade: "websocket" } });
+    }
+    const actorId = request.headers.get("x-safest-actor-id") ?? "";
+    const sessionId = request.headers.get("x-safest-session-id") ?? "";
+    const allowedQueueIds = queueScope(request.headers.get("x-safest-queue-scope"));
+    if (!validActorId(actorId) || !uuid.test(sessionId)) {
+      return new Response("Invalid presence session", { status: 400 });
+    }
+    await touchAnalystSession(this.env.DB, {
+      sessionId, actorId, activity: "online", activeReportId: null,
+      allowedQueueIds,
+      claimTtlMinutes: Number.parseInt(this.env.CLAIM_TTL_MINUTES, 10) || 15,
+    });
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair);
+    const state: PresenceAttachment = {
+      version: 1, actorId, sessionId, activity: "online", activeReportId: null, allowedQueueIds,
+    };
+    server.serializeAttachment(state);
+    this.ctx.acceptWebSocket(server);
+    await this.broadcastSnapshot();
+    return new Response(null, { status: 101, webSocket: client });
+  }
+
+  async publish(event: { type: "claim_changed" | "reports_changed"; reportId?: string }): Promise<void> {
+    this.broadcast({ type: event.type, report_id: null, sent_at: now() });
+  }
+
+  async webSocketMessage(ws: WebSocket, value: string | ArrayBuffer): Promise<void> {
+    const current = attachment(ws.deserializeAttachment());
+    const message = websocketMessage(value);
+    if (!current || !message) {
+      this.send(ws, { type: "error", code: "invalid_presence_message" });
+      return;
+    }
+    const next: PresenceAttachment = {
+      ...current,
+      activity: message.activity,
+      activeReportId: message.reportId,
+    };
+    const result = await touchAnalystSession(this.env.DB, {
+      sessionId: next.sessionId,
+      actorId: next.actorId,
+      activity: next.activity,
+      activeReportId: next.activeReportId,
+      allowedQueueIds: next.allowedQueueIds,
+      claimTtlMinutes: Number.parseInt(this.env.CLAIM_TTL_MINUTES, 10) || 15,
+    });
+    next.activeReportId = result.activeReportId;
+    ws.serializeAttachment(next);
+    this.send(ws, { type: "heartbeat_ack", sent_at: now(), claim_renewed: result.claimRenewed });
+    if (message.type !== "heartbeat" || result.claimRenewed) await this.broadcastSnapshot();
+  }
+
+  async webSocketClose(ws: WebSocket): Promise<void> {
+    const current = attachment(ws.deserializeAttachment());
+    if (!current) return;
+    await removeAnalystSession(this.env.DB, current.sessionId, current.actorId);
+    await this.broadcastSnapshot();
+  }
+
+  async webSocketError(ws: WebSocket): Promise<void> {
+    const current = attachment(ws.deserializeAttachment());
+    if (!current) return;
+    await removeAnalystSession(this.env.DB, current.sessionId, current.actorId);
+    await this.broadcastSnapshot();
+  }
+}
+
+export function parsePresenceHeartbeat(value: Record<string, unknown>): {
+  sessionId: string;
+  activity: AnalystActivity;
+  activeReportId: string | null;
+} {
+  const allowed = new Set(["session_id", "activity", "active_report_id"]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    throw new ApiError(400, "invalid_presence_heartbeat", "The presence heartbeat contains unsupported fields.");
+  }
+  if (typeof value.session_id !== "string" || !uuid.test(value.session_id)) {
+    throw new ApiError(400, "invalid_presence_heartbeat", "session_id must be a UUID.");
+  }
+  if (typeof value.activity !== "string" || !activities.has(value.activity as AnalystActivity)) {
+    throw new ApiError(400, "invalid_presence_heartbeat", "activity is invalid.");
+  }
+  if (value.active_report_id !== null && value.active_report_id !== undefined
+    && (typeof value.active_report_id !== "string" || value.active_report_id.length > 100)) {
+    throw new ApiError(400, "invalid_presence_heartbeat", "active_report_id is invalid.");
+  }
+  return {
+    sessionId: value.session_id,
+    activity: value.activity as AnalystActivity,
+    activeReportId: typeof value.active_report_id === "string" ? value.active_report_id : null,
+  };
+}