@winspan/claude-forge 8.41.0 → 8.50.6

package/src/web/routes/tasks.ts

@@ -0,0 +1,218 @@
+import { z } from 'zod';
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+
+/**
+ * /api/tasks — Task execution view.
+ *
+ * Provides a complete view of a task's execution process:
+ *   - GET /api/tasks          — list + filter + paginate tasks
+ *   - GET /api/tasks/projects — distinct project paths that have tasks
+ *   - GET /api/tasks/:taskId  — full execution detail for a single task
+ */
+
+const TaskListQuery = z.object({
+  limit:   z.coerce.number().int().min(1).default(50).transform(v => Math.min(v, 200)),
+  offset:  z.coerce.number().int().min(0).default(0),
+  /** multi-value: ?project=/a&project=/b  OR  ?project=/a */
+  project: z.union([z.string(), z.array(z.string())]).optional(),
+  from:    z.string().optional(),
+  to:      z.string().optional(),
+  search:  z.string().max(100).optional(),
+  session: z.string().optional(),
+});
+
+export function registerTasksRoutes(app: Application, ctx: RouteContext): void {
+  const { storage } = ctx;
+
+  // ── GET /api/tasks/projects — distinct project paths ──────────────────────
+  // Must be registered BEFORE /:taskId to avoid 'projects' being treated as an id.
+  app.get('/api/tasks/projects', (_req, res) => {
+    const projects = storage.queryTaskProjects();
+    res.json(projects);
+  });
+
+  // ── GET /api/tasks — paginated + filtered list ─────────────────────────────
+  app.get('/api/tasks', (req, res) => {
+    const parsed = TaskListQuery.safeParse(req.query);
+    if (!parsed.success) {
+      res.status(400).json({ error: 'Invalid query parameters', details: parsed.error.flatten() });
+      return;
+    }
+
+    const { limit, offset, project, from, to, search, session } = parsed.data;
+
+    const result = storage.queryTasksFiltered({
+      limit,
+      offset,
+      project,
+      from,
+      to,
+      search,
+      session_id: session,
+    });
+
+    res.json(result);
+  });
+
+  // ── GET /api/tasks/:taskId — full execution detail ─────────────────────────
+  app.get('/api/tasks/:taskId', (req, res) => {
+    const taskId = req.params.taskId;
+
+    // Find the task
+    const allTasks = storage.queryTasks({ limit: 5000 });
+    const task = allTasks.find(t => t.id === taskId);
+    if (!task) {
+      res.status(404).json({ error: 'Task not found' });
+      return;
+    }
+
+    // Get event IDs associated with this task
+    const eventIds = new Set(storage.getTaskEventIds(taskId));
+
+    // Fetch all events for the session, then filter to task events
+    const allEvents = storage.queryEvents({ session_id: task.session_id, limit: 5000 });
+    const taskEvents = allEvents.filter(e => e.event_id && eventIds.has(e.event_id));
+
+    // Sort by timestamp ascending (chronological order)
+    taskEvents.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+    // ── Injections ──────────────────────────────────────────────────────
+    const allInjections = storage.queryInjections({ session_id: task.session_id, limit: 500 });
+    const injections = allInjections
+      .filter(inj => inj.event_id && eventIds.has(inj.event_id))
+      .map(inj => ({
+        id: inj.id,
+        timestamp: inj.timestamp,
+        source_handler: inj.source_handler,
+        injection_type: inj.injection_type,
+        content: inj.content.slice(0, 1000),
+        content_length: inj.content.length,
+        truncated: inj.content.length > 1000,
+      }));
+
+    // ── Timeline ────────────────────────────────────────────────────────
+    const truncateField = (obj: unknown, maxLen = 300): unknown => {
+      if (!obj) return obj;
+      if (typeof obj === 'string') return obj.length > maxLen ? obj.slice(0, maxLen) + '...' : obj;
+      if (Array.isArray(obj)) return obj.slice(0, 10);
+      if (typeof obj === 'object') {
+        const result: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+          result[k] = truncateField(v, maxLen);
+        }
+        return result;
+      }
+      return obj;
+    };
+
+    const timeline = taskEvents
+      .filter(e => e.tool_name && (e.hook_type === 'PreToolUse' || e.hook_type === 'PostToolUse'))
+      .reduce<Array<{
+        timestamp: string;
+        tool_name: string;
+        hook_type: string;
+        input: unknown;
+        output: unknown;
+        is_agent_call: boolean;
+        agent_detail?: { subagent_type?: string; name?: string; prompt?: string };
+      }>>((acc, e) => {
+        // Deduplicate: only keep PreToolUse entries (PostToolUse is supplementary)
+        if (e.hook_type === 'PostToolUse') {
+          // Attach output to the matching PreToolUse entry if exists
+          const pre = acc.find(
+            a => a.tool_name === e.tool_name && !a.output && a.timestamp <= e.timestamp,
+          );
+          if (pre) {
+            pre.output = truncateField(e.tool_output);
+          }
+          return acc;
+        }
+
+        const toolInput = e.tool_input as Record<string, unknown> | null;
+        const isAgentCall = e.tool_name === 'Agent' || e.tool_name === 'Task';
+
+        const entry: (typeof acc)[number] = {
+          timestamp: e.timestamp,
+          tool_name: e.tool_name!,
+          hook_type: e.hook_type,
+          input: truncateField(toolInput),
+          output: truncateField(e.tool_output),
+          is_agent_call: isAgentCall,
+        };
+
+        if (isAgentCall && toolInput) {
+          entry.agent_detail = {
+            subagent_type: toolInput.subagent_type as string | undefined,
+            name: toolInput.name as string | undefined,
+            prompt: typeof toolInput.prompt === 'string'
+              ? toolInput.prompt
+              : undefined,
+          };
+        }
+
+        acc.push(entry);
+        return acc;
+      }, []);
+
+    // ── Skill Invocations ───────────────────────────────────────────────
+    const allSkillInvocations = storage.querySkillInvocations({ session_id: task.session_id, limit: 200 });
+    // Filter by timestamp range of the task
+    const taskStart = task.start_time;
+    const taskEnd = task.end_time || new Date().toISOString();
+    const taskStartMs = new Date(taskStart).getTime();
+    const taskEndMs = new Date(taskEnd).getTime();
+
+    const skillInvocations = allSkillInvocations
+      .filter(si => si.timestamp >= taskStartMs && si.timestamp <= taskEndMs)
+      .map(si => ({
+        id: si.id,
+        skill_id: si.skill_id,
+        agent_id: si.agent_id,
+        invocation_type: si.invocation_type,
+        reason: si.reason,
+        workflow: si.workflow,
+        phase: si.phase,
+        feature_slug: si.feature_slug,
+        success: si.success === 1,
+        error: si.error,
+        timestamp: si.timestamp,
+      }));
+
+    // ── Artifacts ───────────────────────────────────────────────────────
+    const artifacts = [...new Set(
+      taskEvents
+        .filter(e =>
+          (e.tool_name === 'Edit' || e.tool_name === 'Write') &&
+          (e.tool_input as Record<string, unknown> | null)?.file_path,
+        )
+        .map(e => (e.tool_input as Record<string, unknown>).file_path as string),
+    )];
+
+    // ── User Prompts ────────────────────────────────────────────────────
+    const userPrompts = taskEvents
+      .filter(e => e.hook_type === 'UserPromptSubmit' && (e.user_prompt || (e.tool_input as any)?.user_prompt))
+      .map(e => ({
+        timestamp: e.timestamp,
+        content: e.user_prompt || (e.tool_input as any)?.user_prompt,
+      }));
+
+    res.json({
+      task: {
+        id: task.id,
+        session_id: task.session_id,
+        title: task.title,
+        description: task.description,
+        start_time: task.start_time,
+        end_time: task.end_time,
+        status: task.status,
+        event_count: task.event_count,
+      },
+      userPrompts,
+      injections,
+      timeline,
+      skillInvocations,
+      artifacts,
+    });
+  });
+}

package/src/web/routes/token-usage.ts

@@ -0,0 +1,20 @@
+import type { Application } from 'express';
+import type { RouteContext } from './types.js';
+
+/**
+ * /api/token-usage/* — token usage queries by session.
+ */
+export function registerTokenUsageRoutes(app: Application, ctx: RouteContext): void {
+  const { storage } = ctx;
+
+  app.get('/api/token-usage/session/:sessionId', (req, res) => {
+    const sessionId = req.params.sessionId;
+    try {
+      const usage = storage.getTokenUsageBySession(sessionId);
+      const details = storage.listTokenUsage({ session_id: sessionId, limit: 100 });
+      res.json({ ...usage, details });
+    } catch (err) {
+      res.status(500).json({ error: String(err) });
+    }
+  });
+}

package/src/web/routes/trace.ts

@@ -0,0 +1,138 @@
+/**
+ * /api/trace/:commit — Trace a git commit to its forge session(s).
+ *
+ * Reads git notes from the project directory to find associated session IDs,
+ * then queries storage for session details.
+ */
+
+import type { Application } from 'express';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RouteContext } from './types.js';
+
+export function registerTraceRoutes(app: Application, ctx: RouteContext): void {
+  const { storage } = ctx;
+
+  app.get('/api/trace/:commit', (req, res) => {
+    const commitRef = req.params.commit;
+    const projectPath = req.query.project as string | undefined;
+
+    if (!projectPath) {
+      res.status(400).json({ error: 'Query parameter "project" is required' });
+      return;
+    }
+
+    // Security: validate projectPath to prevent command injection
+    // 1. Must be an absolute path
+    if (!path.isAbsolute(projectPath)) {
+      res.status(400).json({ error: 'Project path must be absolute' });
+      return;
+    }
+
+    // 2. Must exist and be a directory
+    try {
+      const stats = fs.statSync(projectPath);
+      if (!stats.isDirectory()) {
+        res.status(400).json({ error: 'Project path must be a directory' });
+        return;
+      }
+    } catch {
+      res.status(400).json({ error: 'Project path does not exist' });
+      return;
+    }
+
+    // 3. Must contain a .git directory
+    const gitDir = path.join(projectPath, '.git');
+    if (!fs.existsSync(gitDir)) {
+      res.status(400).json({ error: 'Project path is not a git repository' });
+      return;
+    }
+
+    // 1. Resolve commit hash
+    let commitHash: string;
+    let commitMessage: string;
+    try {
+      commitHash = execFileSync('git', ['rev-parse', commitRef], {
+        cwd: projectPath, stdio: 'pipe', timeout: 5000,
+      }).toString().trim();
+    } catch {
+      res.status(404).json({ error: `Cannot resolve commit "${commitRef}"` });
+      return;
+    }
+
+    try {
+      commitMessage = execFileSync('git', ['log', '-1', '--format=%s', commitHash], {
+        cwd: projectPath, stdio: 'pipe', timeout: 5000,
+      }).toString().trim();
+    } catch {
+      commitMessage = '';
+    }
+
+    // 2. Read git notes
+    let noteContent: string;
+    try {
+      noteContent = execFileSync('git', ['notes', 'show', commitHash], {
+        cwd: projectPath, stdio: 'pipe', timeout: 5000,
+      }).toString().trim();
+    } catch {
+      res.json({ commit: commitHash, message: commitMessage, sessions: [] });
+      return;
+    }
+
+    // 3. Parse session IDs
+    const sessionIds = noteContent
+      .split('\n')
+      .filter(line => line.startsWith('forge-session:'))
+      .map(line => line.replace('forge-session:', '').trim());
+
+    if (sessionIds.length === 0) {
+      res.json({ commit: commitHash, message: commitMessage, sessions: [] });
+      return;
+    }
+
+    // 4. Query session details
+    const db = storage.getDatabase();
+    const allSessions = storage.querySessions({ limit: 5000 });
+    const sessionDetails = sessionIds.map(sid => {
+      const session = allSessions.find(s => s.session_id === sid || s.session_id.startsWith(sid));
+      if (!session) return { session_id: sid, found: false };
+
+      const fullId = session.session_id;
+      const start = new Date(session.start_time);
+      const end = new Date(session.end_time);
+      const durationMin = Math.round((end.getTime() - start.getTime()) / 60000);
+
+      const eventBreakdown = db.prepare(`
+        SELECT hook_type, COUNT(*) as cnt FROM events
+        WHERE session_id = ? GROUP BY hook_type
+      `).all(fullId) as Array<{ hook_type: string; cnt: number }>;
+
+      const agentRows = db.prepare(`
+        SELECT json_extract(tool_input, '$.subagent_type') as agent_type, COUNT(*) as cnt
+        FROM events
+        WHERE session_id = ? AND tool_name IN ('Agent', 'Task') AND tool_input IS NOT NULL
+        GROUP BY agent_type
+      `).all(fullId) as Array<{ agent_type: string | null; cnt: number }>;
+
+      const skillRows = db.prepare(`
+        SELECT DISTINCT skill_id FROM skill_invocations WHERE session_id = ?
+      `).all(fullId) as Array<{ skill_id: string }>;
+
+      return {
+        session_id: fullId,
+        found: true,
+        first_prompt: session.first_prompt,
+        start_time: session.start_time,
+        end_time: session.end_time,
+        duration_min: durationMin,
+        event_count: session.event_count,
+        event_breakdown: Object.fromEntries(eventBreakdown.map(r => [r.hook_type, r.cnt])),
+        agent_calls: agentRows.filter(r => r.agent_type).map(r => ({ type: r.agent_type, count: r.cnt })),
+        skills: skillRows.map(r => r.skill_id),
+      };
+    });
+
+    res.json({ commit: commitHash, message: commitMessage, sessions: sessionDetails });
+  });
+}

package/src/web/routes/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared types & helpers for route modules.
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { SkillRegistry } from '../../skills/registry.js';
+
+export interface RouteContext {
+  storage: SQLiteStorage;
+  skillRegistry?: SkillRegistry;
+}
+
+/**
+ * Resolve the concrete on-disk path + backup dir for a patchable target.
+ */
+export function resolvePatchTarget(
+  targetType: string,
+  targetName: string,
+): { filePath: string; backupDir: string } {
+  // Security: prevent path traversal attacks
+  if (!targetName || targetName.includes('/') || targetName.includes('\\') || targetName.includes('..')) {
+    throw new Error('Invalid target name: path traversal detected');
+  }
+
+  if (targetType === 'skill') {
+    return {
+      filePath: path.join(homedir(), '.claude', 'skills', `${targetName}.md`),
+      backupDir: path.join(homedir(), '.claude-forge', 'backups', 'skills'),
+    };
+  }
+  if (targetType === 'routing_rule') {
+    return {
+      filePath: path.join(homedir(), '.claude-forge', 'routing.yaml'),
+      backupDir: path.join(homedir(), '.claude-forge', 'backups', 'routing'),
+    };
+  }
+  throw new Error(`Unsupported targetType: ${targetType}`);
+}
+
+/**
+ * Locate the static assets directory.
+ */
+export function resolveStaticDir(moduleUrl: string): string | null {
+  const dir = path.dirname(fileURLToPath(moduleUrl));
+  const candidates = [
+    path.join(dir, '..', 'static'),
+    path.join(dir, '../../../src/web/static'),
+    path.join(dir, '../static'),
+    path.join(dir, '../../src/web/static'),
+  ];
+  return candidates.find(d => fs.existsSync(d)) ?? null;
+}

package/src/web/server.ts

@@ -0,0 +1,134 @@
+/**
+ * Web API server — Express entry for the Forge dashboard.
+ *
+ * server.ts is intentionally thin: it wires middleware, composes the route
+ * modules under src/web/routes/, and owns lifecycle (start/stop).
+ */
+
+import express from 'express';
+import type { SQLiteStorage } from '../core/storage/sqlite.js';
+import type { SkillRegistry } from '../skills/registry.js';
+import type { InvocationGuard } from '../skills/invocation-guard.js';
+import { logger } from '../core/utils/logger.js';
+import { ErrorHandler } from '../core/utils/error-handler.js';
+import { requireAuth } from './auth-middleware.js';
+import { mountMcpServer } from '../mcp/server.js';
+import { errorHandler, notFoundHandler } from './routes/error-handler.js';
+
+import type { RouteContext } from './routes/types.js';
+import { registerAuthRoutes } from './routes/auth.js';
+import { registerStaticAssets, registerStaticFallback } from './routes/static.js';
+import { registerStatusRoutes } from './routes/status.js';
+import { registerEventsRoutes } from './routes/events.js';
+import { registerSessionsRoutes } from './routes/sessions.js';
+import { registerTokenUsageRoutes } from './routes/token-usage.js';
+import { registerAIRoutes } from './routes/ai.js';
+import { registerPatchRoutes } from './routes/patch.js';
+import { registerSkillsRoutes } from './routes/skills.js';
+import { registerTasksRoutes } from './routes/tasks.js';
+import { registerStatsRoutes } from './routes/stats.js';
+import { registerSkillStatsRoutes } from './routes/skill-stats.js';
+import { registerRulesRoutes } from './routes/rules.js';
+import { registerDriftRoutes } from './routes/drift.js';
+import { registerTraceRoutes } from './routes/trace.js';
+import { registerReportsRoutes } from './routes/reports.js';
+import { registerInsightsRoutes } from './routes/insights.js';
+
+export interface WebServerOptions {
+  port: number;
+  storage: SQLiteStorage;
+  skillRegistry?: SkillRegistry;
+  invocationGuard?: InvocationGuard;
+}
+
+export class WebServer {
+  private app: express.Application;
+  private server: ReturnType<express.Application['listen']> | null = null;
+
+  constructor(private options: WebServerOptions) {
+    this.app = express();
+
+    // Security: limit request body size to prevent DoS attacks
+    this.app.use(express.json({ limit: '10mb' }));
+    this.app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+
+    this.setupRoutes();
+  }
+
+  private setupRoutes(): void {
+    this.app.use('/api', (req, res, next) => {
+      if (req.method === 'GET') return next();
+      return requireAuth(req, res, next);
+    });
+
+    const ctx: RouteContext = {
+      storage: this.options.storage,
+      skillRegistry: this.options.skillRegistry,
+    };
+
+    // 1. Auth bootstrap
+    registerAuthRoutes(this.app, ctx);
+
+    // 2. Static assets (serves UI; fallback registered last)
+    registerStaticAssets(this.app, ctx);
+
+    // 3. API routes
+    registerStatusRoutes(this.app, ctx);
+    registerEventsRoutes(this.app, ctx);
+    registerSessionsRoutes(this.app, ctx);
+    registerTokenUsageRoutes(this.app, ctx);
+    registerAIRoutes(this.app, ctx);
+    registerPatchRoutes(this.app, ctx);
+    registerSkillsRoutes(this.app, ctx);
+    registerTasksRoutes(this.app, ctx);
+    registerStatsRoutes(this.app, ctx);
+    registerSkillStatsRoutes(this.app, ctx);
+    registerRulesRoutes(this.app, ctx);
+    registerDriftRoutes(this.app, ctx);
+    registerTraceRoutes(this.app, ctx);
+    registerReportsRoutes(this.app, ctx);
+    registerInsightsRoutes(this.app, ctx);
+
+    // 4. MCP server — mounted on /mcp (Streamable HTTP)
+    if (this.options.skillRegistry) {
+      mountMcpServer(this.app, {
+        skillRegistry: this.options.skillRegistry,
+        storage: this.options.storage,
+        guard: this.options.invocationGuard,
+      });
+    } else {
+      logger.warn('[MCP] Skipped mounting: skillRegistry not provided');
+    }
+
+    // 5. SPA catch-all — must be LAST
+    registerStaticFallback(this.app, ctx);
+
+    // 6. Error handlers — must be AFTER all routes
+    this.app.use(notFoundHandler);
+    this.app.use(errorHandler);
+  }
+
+  async start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server = this.app.listen(this.options.port, () => {
+        logger.info(`[Web] Server started on port ${this.options.port}`);
+        resolve();
+      });
+
+      this.server?.on('error', (error: any) => {
+        if (error.code === 'EADDRINUSE') {
+          ErrorHandler.handle(error, 'Web Server');
+        }
+        reject(error);
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (this.server) {
+      return new Promise(resolve => {
+        this.server!.close(() => resolve());
+      });
+    }
+  }
+}

package/src/web/ssrf-guard.ts

@@ -0,0 +1,112 @@
+/**
+ * SSRF 防护 — Web API 对外 fetch 前的 URL 白名单校验
+ *
+ * 背景：`/api/ai/test` 与 `/api/ai/models` 允许请求方指定上游 `baseUrl`，
+ * 若不加约束可被滥用为 SSRF 通道（访问 169.254.169.254 / 127.0.0.1 / 内网 API
+ * 等），并通过 res.json 回显响应体。此模块统一做协议、主机、白名单校验。
+ */
+
+/** 校验结果 */
+export interface SsrfValidationResult {
+  ok: boolean;
+  error?: string;
+}
+
+/** 默认允许访问的上游主机（已知 AI 服务商的官方域名） */
+export const DEFAULT_ALLOWED_HOSTS: ReadonlySet<string> = new Set([
+  'api.anthropic.com',
+  'api.openai.com',
+  'generativelanguage.googleapis.com',
+]);
+
+/** 统一的跨端点 fetch 超时（毫秒） */
+export const UPSTREAM_TIMEOUT_MS = 10_000;
+
+/** 判断字符串是否为 IPv4 字面量 */
+function isIPv4Literal(host: string): boolean {
+  return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+
+/** 判断主机是否为 loopback / 保留名 */
+function isLocalhostLike(host: string): boolean {
+  const h = host.toLowerCase();
+  return (
+    h === 'localhost' ||
+    h.endsWith('.localhost') ||
+    h === '0.0.0.0' ||
+    h === '::' ||
+    h === '::1'
+  );
+}
+
+/**
+ * 校验用户提供的 baseUrl 是否允许被 daemon 代为访问。
+ *
+ * 规则：
+ * 1. 必须能解析为 URL；
+ * 2. 协议必须是 http 或 https；
+ * 3. 禁止 IPv4 / IPv6 字面量、localhost 等本机/内网地址；
+ * 4. 主机必须在默认白名单或 extraHosts 中。
+ *
+ * @param baseUrl 待校验的 URL
+ * @param extraHosts 额外允许的主机（通常来自 config.yaml 里已配置的 base_url）
+ */
+export function validateBaseUrl(
+  baseUrl: unknown,
+  extraHosts: Iterable<string> = [],
+): SsrfValidationResult {
+  if (typeof baseUrl !== 'string' || baseUrl.length === 0) {
+    return { ok: false, error: 'baseUrl is required' };
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    return { ok: false, error: 'Invalid URL' };
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    return { ok: false, error: 'Only http/https protocols allowed' };
+  }
+
+  const host = parsed.hostname.toLowerCase();
+
+  if (isIPv4Literal(host)) {
+    return { ok: false, error: 'Direct IP access blocked (SSRF protection)' };
+  }
+  // URL parser strips brackets from IPv6 hostname; detect by ':' or '::'
+  if (host.includes(':')) {
+    return { ok: false, error: 'Direct IPv6 access blocked (SSRF protection)' };
+  }
+  if (isLocalhostLike(host)) {
+    return { ok: false, error: 'localhost access blocked (SSRF protection)' };
+  }
+
+  const allowed = new Set<string>(DEFAULT_ALLOWED_HOSTS);
+  for (const extra of extraHosts) {
+    if (extra) allowed.add(extra.toLowerCase());
+  }
+
+  if (!allowed.has(host)) {
+    return {
+      ok: false,
+      error: `Host ${host} not in allowlist. Allowed: ${[...allowed].sort().join(', ')}`,
+    };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * 从已配置的 base_url 中提取主机名，作为额外允许项。
+ * 无效/为空返回 null，调用方可忽略。
+ */
+export function extractHostFromBaseUrl(baseUrl: string | undefined | null): string | null {
+  if (!baseUrl) return null;
+  try {
+    return new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}