@castlekit/castle 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@castlekit/castle",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "The multi-agent workspace",
   "type": "module",
   "bin": {
@@ -42,6 +42,7 @@
     "@types/node": "^25.2.1",
     "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.1",
     "clsx": "^2.1.1",
     "commander": "^14.0.3",
     "json5": "^2.2.3",
@@ -53,12 +54,15 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "recharts": "^3.7.0",
+    "sharp": "^0.34.5",
     "swr": "^2.4.0",
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "ws": "^8.19.0",
-    "@types/ws": "^8.18.1"
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/sharp": "^0.31.1"
   }
 }

package/src/app/api/avatars/[id]/route.ts

@@ -2,13 +2,11 @@ import { NextRequest, NextResponse } from "next/server";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { ensureGateway } from "@/lib/gateway-connection";
 
 export const dynamic = "force-dynamic";
 
-const AVATAR_DIRS = [
-  join(homedir(), ".castle", "avatars"),
-  join(homedir(), ".openclaw", "avatars"),
-];
+const EXTENSIONS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"];
 
 const MIME_TYPES: Record<string, string> = {
   ".png": "image/png",
@@ -19,10 +17,17 @@ const MIME_TYPES: Record<string, string> = {
   ".svg": "image/svg+xml",
 };
 
+const CACHE_HEADERS = { "Cache-Control": "public, max-age=3600" };
+
 /**
  * GET /api/avatars/[id]
- * Serves avatar images from ~/.castle/avatars/ or ~/.openclaw/avatars/
- * Supports IDs with or without extension (tries .png, .jpg, .webp)
+ *
+ * Proxies avatar images so they work from any device (mobile, Tailscale, etc).
+ *
+ * Resolution order:
+ *   1. Stored URL from Gateway → workspace path or HTTP fetch
+ *   2. Local file in ~/.castle/avatars/ or ~/.openclaw/avatars/
+ *   3. 404
  */
 export async function GET(
   _request: NextRequest,
@@ -30,46 +35,88 @@ export async function GET(
 ) {
   const { id } = await params;
 
-  // Sanitize -- prevent path traversal
+  // Sanitize
   const safeId = id.replace(/[^a-zA-Z0-9._-]/g, "");
   if (!safeId || safeId.includes("..")) {
     return new NextResponse("Not found", { status: 404 });
   }
 
-  // Try each avatar directory
-  for (const dir of AVATAR_DIRS) {
+  // 1. Try stored URL from Gateway
+  try {
+    const gw = ensureGateway();
+    const storedUrl = gw.getAvatarUrl(safeId);
+
+    if (storedUrl) {
+      // Workspace-relative: workspace:///absolute/path/to/workspace/avatars/file.png
+      if (storedUrl.startsWith("workspace://")) {
+        const pathPart = storedUrl.slice("workspace://".length);
+        // Resolve ~ in workspace path
+        const resolved = pathPart.startsWith("~")
+          ? join(homedir(), pathPart.slice(1))
+          : pathPart;
+        // Prevent traversal
+        if (!resolved.includes("..") && existsSync(resolved)) {
+          return serveFile(resolved);
+        }
+      }
+      // HTTP(S) URL: fetch server-side and proxy
+      else if (storedUrl.startsWith("http://") || storedUrl.startsWith("https://")) {
+        const response = await fetchAvatar(storedUrl);
+        if (response) return response;
+      }
+    }
+  } catch {
+    // Gateway unavailable
+  }
+
+  // 2. Local avatar directories
+  const localDirs = [
+    join(homedir(), ".castle", "avatars"),
+    join(homedir(), ".openclaw", "avatars"),
+  ];
+
+  for (const dir of localDirs) {
     if (!existsSync(dir)) continue;
 
-    // Try exact filename first (if it has an extension)
-    const hasExtension = /\.\w+$/.test(safeId);
-    if (hasExtension) {
+    if (/\.\w+$/.test(safeId)) {
       const filePath = join(dir, safeId);
-      if (existsSync(filePath)) {
-        return serveFile(filePath);
-      }
+      if (existsSync(filePath)) return serveFile(filePath);
     }
 
-    // Try common extensions
-    for (const ext of [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"]) {
+    for (const ext of EXTENSIONS) {
       const filePath = join(dir, `${safeId}${ext}`);
-      if (existsSync(filePath)) {
-        return serveFile(filePath);
-      }
+      if (existsSync(filePath)) return serveFile(filePath);
     }
   }
 
   return new NextResponse("Not found", { status: 404 });
 }
 
+/** Fetch an avatar from an HTTP URL with a short timeout */
+async function fetchAvatar(url: string): Promise<NextResponse | null> {
+  try {
+    const resp = await fetch(url, { signal: AbortSignal.timeout(2000) });
+    if (!resp.ok) return null;
+
+    const contentType = resp.headers.get("content-type") || "image/png";
+    if (!contentType.startsWith("image/")) return null;
+
+    const data = Buffer.from(await resp.arrayBuffer());
+    return new NextResponse(data, {
+      headers: { "Content-Type": contentType, ...CACHE_HEADERS },
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** Serve a local file with appropriate content type */
 function serveFile(filePath: string): NextResponse {
   const data = readFileSync(filePath);
   const ext = filePath.substring(filePath.lastIndexOf(".")).toLowerCase();
   const contentType = MIME_TYPES[ext] || "application/octet-stream";
 
   return new NextResponse(data, {
-    headers: {
-      "Content-Type": contentType,
-      "Cache-Control": "public, max-age=86400, immutable",
-    },
+    headers: { "Content-Type": contentType, ...CACHE_HEADERS },
   });
 }

package/src/app/api/openclaw/agents/[id]/avatar/route.ts

@@ -0,0 +1,216 @@
+import { NextRequest, NextResponse } from "next/server";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import JSON5 from "json5";
+import sharp from "sharp";
+import { ensureGateway } from "@/lib/gateway-connection";
+import { checkCsrf } from "@/lib/api-security";
+
+export const dynamic = "force-dynamic";
+
+const MAX_UPLOAD_SIZE = 5 * 1024 * 1024; // 5MB raw upload limit
+const AVATAR_SIZE = 256; // px (square)
+const MAX_OUTPUT_SIZE = 100 * 1024; // 100KB after processing
+
+const ALLOWED_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+
+interface AgentConfig {
+  id: string;
+  workspace?: string;
+  identity?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface OpenClawConfig {
+  agents?: {
+    list?: AgentConfig[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/**
+ * Resize and compress an avatar image to 256x256, under 100KB.
+ */
+async function processAvatar(input: Buffer): Promise<{ data: Buffer; ext: string }> {
+  const processed = sharp(input)
+    .resize(AVATAR_SIZE, AVATAR_SIZE, { fit: "cover", position: "centre" });
+
+  // Try PNG first (transparency support)
+  let data = await processed.png({ quality: 80, compressionLevel: 9 }).toBuffer();
+  if (data.length <= MAX_OUTPUT_SIZE) return { data, ext: ".png" };
+
+  // WebP (better compression, keeps transparency)
+  data = await processed.webp({ quality: 80 }).toBuffer();
+  if (data.length <= MAX_OUTPUT_SIZE) return { data, ext: ".webp" };
+
+  // JPEG with lower quality
+  data = await processed.jpeg({ quality: 70 }).toBuffer();
+  if (data.length <= MAX_OUTPUT_SIZE) return { data, ext: ".jpg" };
+
+  // Last resort
+  data = await processed.jpeg({ quality: 40 }).toBuffer();
+  return { data, ext: ".jpg" };
+}
+
+/**
+ * Find the OpenClaw config file path.
+ */
+function getOpenClawConfigPath(): string | null {
+  const paths = [
+    join(homedir(), ".openclaw", "openclaw.json"),
+    join(homedir(), ".openclaw", "openclaw.json5"),
+  ];
+  for (const p of paths) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * POST /api/openclaw/agents/[id]/avatar
+ *
+ * Upload a new avatar image for an agent.
+ * - Resizes to 256x256 and compresses under 100KB
+ * - Saves to the agent's workspace directory
+ * - Writes config file directly (Gateway hot-reloads identity changes, no restart needed)
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const csrfError = checkCsrf(request);
+  if (csrfError) return csrfError;
+
+  const { id: agentId } = await params;
+
+  const safeId = agentId.replace(/[^a-zA-Z0-9._-]/g, "");
+  if (!safeId) {
+    return NextResponse.json({ error: "Invalid agent ID" }, { status: 400 });
+  }
+
+  const formData = await request.formData();
+  const file = formData.get("avatar") as File | null;
+
+  if (!file) {
+    return NextResponse.json({ error: "No file provided" }, { status: 400 });
+  }
+
+  if (!ALLOWED_TYPES.has(file.type)) {
+    return NextResponse.json(
+      { error: "Unsupported format. Use PNG, JPEG, WebP, or GIF." },
+      { status: 400 }
+    );
+  }
+
+  if (file.size > MAX_UPLOAD_SIZE) {
+    return NextResponse.json(
+      { error: "File too large (max 5MB)" },
+      { status: 400 }
+    );
+  }
+
+  // Process image: resize to 256x256, compress to <100KB
+  let processed: { data: Buffer; ext: string };
+  try {
+    const rawBuffer = Buffer.from(await file.arrayBuffer());
+    processed = await processAvatar(rawBuffer);
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to process image: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 400 }
+    );
+  }
+
+  // Read the OpenClaw config file directly
+  const configPath = getOpenClawConfigPath();
+  if (!configPath) {
+    return NextResponse.json(
+      { error: "OpenClaw config file not found" },
+      { status: 500 }
+    );
+  }
+
+  let config: OpenClawConfig;
+  try {
+    config = JSON5.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to read config: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 500 }
+    );
+  }
+
+  const agents = config.agents?.list || [];
+  const agent = agents.find((a) => a.id === safeId);
+
+  if (!agent) {
+    return NextResponse.json({ error: "Agent not found" }, { status: 404 });
+  }
+
+  if (!agent.workspace) {
+    return NextResponse.json(
+      { error: "Agent has no workspace configured" },
+      { status: 400 }
+    );
+  }
+
+  const workspacePath = agent.workspace.startsWith("~")
+    ? join(homedir(), agent.workspace.slice(1))
+    : agent.workspace;
+
+  // Save processed avatar to workspace
+  const avatarsDir = join(workspacePath, "avatars");
+  const fileName = `avatar${processed.ext}`;
+  const filePath = join(avatarsDir, fileName);
+
+  try {
+    mkdirSync(avatarsDir, { recursive: true, mode: 0o755 });
+    writeFileSync(filePath, processed.data);
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to save avatar: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 500 }
+    );
+  }
+
+  // Update config file directly — Gateway's file watcher hot-reloads identity changes
+  // No config.patch, no restart, no WebSocket disconnect
+  try {
+    agent.identity = agent.identity || {};
+    agent.identity.avatar = `avatars/${fileName}`;
+    writeFileSync(configPath, JSON5.stringify(config, null, 2), "utf-8");
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to update config: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 500 }
+    );
+  }
+
+  // Wait briefly for Gateway's file watcher to hot-reload (~300ms debounce)
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  // Refresh Castle's agent list from the Gateway
+  try {
+    const gw = ensureGateway();
+    if (gw.isConnected) {
+      // Emit a signal so SSE clients re-fetch agents
+      gw.emit("agentAvatarUpdated", { agentId: safeId });
+    }
+  } catch {
+    // Non-critical
+  }
+
+  return NextResponse.json({
+    success: true,
+    avatar: `avatars/${fileName}`,
+    size: processed.data.length,
+    message: "Avatar updated",
+  });
+}

package/src/app/api/openclaw/agents/route.ts

@@ -24,34 +24,66 @@ interface AgentsListPayload {
   agents: GatewayAgent[];
 }
 
+interface AgentConfig {
+  id: string;
+  workspace?: string;
+}
+
+interface ConfigGetPayload {
+  hash: string;
+  parsed: {
+    agents?: {
+      list?: AgentConfig[];
+    };
+  };
+}
+
+/** Avatar URL patterns containing a hash */
+const AVATAR_HASH_PATTERNS = [
+  /\/api\/v\d+\/avatars\/([a-f0-9]+)/i,
+  /\/avatars\/([a-f0-9]+)/i,
+];
+
 /**
- * Rewrite avatar URLs to local /api/avatars/ endpoint.
- * Handles URLs like "http://localhost:8787/api/v1/avatars/HASH" -> "/api/avatars/HASH"
+ * Resolve an avatar value into a Castle-proxied URL.
+ *
+ * Handles three formats:
+ *   1. Data URI       → pass through (self-contained)
+ *   2. HTTP(S) URL    → proxy via /api/avatars/:key
+ *   3. Relative path  → proxy via /api/avatars/:key (resolved server-side against workspace)
  */
-function rewriteAvatarUrl(url: string | null): string | null {
-  if (!url) return null;
-
-  // Extract hash from known avatar URL patterns
-  const patterns = [
-    /\/api\/v\d+\/avatars\/([a-f0-9]+)/i,
-    /\/avatars\/([a-f0-9]+)/i,
-  ];
-
-  for (const pattern of patterns) {
-    const match = url.match(pattern);
-    if (match) {
-      return `/api/avatars/${match[1]}`;
+function resolveAvatarUrl(
+  avatar: string | null,
+  agentId: string,
+  workspace: string | undefined,
+  gw: ReturnType<typeof ensureGateway>,
+): string | null {
+  if (!avatar) return null;
+
+  // Data URIs are self-contained
+  if (avatar.startsWith("data:")) return avatar;
+
+  // HTTP(S) URL — proxy through Castle
+  if (avatar.startsWith("http://") || avatar.startsWith("https://")) {
+    // Try to extract a hash for a cleaner key
+    for (const pattern of AVATAR_HASH_PATTERNS) {
+      const match = avatar.match(pattern);
+      if (match) {
+        gw.setAvatarUrl(match[1], avatar);
+        return `/api/avatars/${match[1]}`;
+      }
     }
+    // No hash — use agent ID as key
+    const key = `agent-${agentId}`;
+    gw.setAvatarUrl(key, avatar);
+    return `/api/avatars/${key}`;
   }
 
-  // If it's already a relative path or data URI, pass through
-  if (url.startsWith("/") || url.startsWith("data:")) {
-    return url;
-  }
-
-  // Only allow http/https URLs through; reject file:, javascript:, etc.
-  if (url.startsWith("http://") || url.startsWith("https://")) {
-    return url;
+  // Relative path (e.g. "avatars/sam.png") — resolve against workspace
+  if (workspace && !avatar.startsWith("/")) {
+    const key = `agent-${agentId}`;
+    gw.setAvatarUrl(key, `workspace://${workspace}/${avatar}`);
+    return `/api/avatars/${key}`;
   }
 
   return null;
@@ -59,7 +91,8 @@ function rewriteAvatarUrl(url: string | null): string | null {
 
 /**
  * GET /api/openclaw/agents
- * Discover agents from OpenClaw Gateway via agents.list
+ * Discover agents from OpenClaw Gateway via agents.list,
+ * with workspace info from config.get for avatar resolution.
  */
 export async function GET() {
   const gw = ensureGateway();
@@ -72,31 +105,34 @@ export async function GET() {
   }
 
   try {
-    const result = await gw.request<AgentsListPayload>("agents.list", {});
+    // Fetch agents and config in parallel
+    const [agentsResult, configResult] = await Promise.all([
+      gw.request<AgentsListPayload>("agents.list", {}),
+      gw.request<ConfigGetPayload>("config.get", {}).catch(() => null),
+    ]);
+
+    // Build workspace lookup from config
+    const workspaceMap = new Map<string, string>();
+    if (configResult?.parsed?.agents?.list) {
+      for (const a of configResult.parsed.agents.list) {
+        if (a.workspace) workspaceMap.set(a.id, a.workspace);
+      }
+    }
 
-    const agents = (result?.agents || []).map((agent: GatewayAgent) => {
-      const name =
-        agent.identity?.name || agent.name || agent.id;
-      const rawAvatar =
-        agent.identity?.avatarUrl || agent.identity?.avatar || null;
+    const agents = (agentsResult?.agents || []).map((agent: GatewayAgent) => {
+      const name = agent.identity?.name || agent.name || agent.id;
+      const rawAvatar = agent.identity?.avatarUrl || agent.identity?.avatar || null;
       const emoji = agent.identity?.emoji || null;
       const description = agent.identity?.theme || null;
+      const workspace = workspaceMap.get(agent.id);
+      const avatar = resolveAvatarUrl(rawAvatar, agent.id, workspace, gw);
 
-      // Rewrite external avatar URLs to our local /api/avatars/ endpoint
-      const avatar = rewriteAvatarUrl(rawAvatar);
-
-      return {
-        id: agent.id,
-        name,
-        description,
-        avatar,
-        emoji,
-      };
+      return { id: agent.id, name, description, avatar, emoji };
     });
 
     return NextResponse.json({
       agents,
-      defaultId: result?.defaultId,
+      defaultId: agentsResult?.defaultId,
     });
   } catch (err) {
     return NextResponse.json(

package/src/app/api/openclaw/config/route.ts

@@ -1,15 +1,53 @@
 import { NextRequest, NextResponse } from "next/server";
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import JSON5 from "json5";
 import { getOpenClawDir } from "@/lib/config";
 import { ensureGateway } from "@/lib/gateway-connection";
+import { checkCsrf } from "@/lib/api-security";
 
 export const dynamic = "force-dynamic";
 
+/**
+ * Deep-clone a config object, redacting sensitive fields so they
+ * are never returned over HTTP.
+ */
+function redactSecrets(obj: unknown): unknown {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(redactSecrets);
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    // Redact any key that looks like a token or secret
+    const lower = key.toLowerCase();
+    if (
+      lower === "token" ||
+      lower === "secret" ||
+      lower === "password" ||
+      lower === "apikey" ||
+      lower === "api_key" ||
+      lower === "privatekey" ||
+      lower === "private_key"
+    ) {
+      if (typeof value === "string" && value.length > 0) {
+        result[key] = value.slice(0, 4) + "***";
+      } else {
+        result[key] = "***";
+      }
+    } else if (typeof value === "object") {
+      result[key] = redactSecrets(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 /**
  * GET /api/openclaw/config
- * God mode: reads OpenClaw config from filesystem
+ * Reads OpenClaw config from filesystem.
+ * Sensitive fields (tokens, secrets, keys) are redacted before returning.
  */
 export async function GET() {
   const configPath = join(getOpenClawDir(), "openclaw.json");
@@ -27,7 +65,7 @@ export async function GET() {
     try {
       const raw = readFileSync(json5Path, "utf-8");
       const config = JSON5.parse(raw);
-      return NextResponse.json({ config, format: "json5" });
+      return NextResponse.json({ config: redactSecrets(config), format: "json5" });
     } catch (err) {
       return NextResponse.json(
         { error: err instanceof Error ? err.message : "Failed to parse config" },
@@ -39,7 +77,7 @@ export async function GET() {
   try {
     const raw = readFileSync(configPath, "utf-8");
     const config = JSON5.parse(raw);
-    return NextResponse.json({ config, format: "json" });
+    return NextResponse.json({ config: redactSecrets(config), format: "json" });
   } catch (err) {
     return NextResponse.json(
       { error: err instanceof Error ? err.message : "Failed to parse config" },
@@ -51,9 +89,12 @@ export async function GET() {
 /**
  * PATCH /api/openclaw/config
  * Update OpenClaw config via Gateway's config.patch method.
+ * Protected against CSRF — only requests from the Castle UI are allowed.
  * Body: { patch: { ... } } -- the patch to apply
  */
 export async function PATCH(request: NextRequest) {
+  const csrf = checkCsrf(request);
+  if (csrf) return csrf;
   const gw = ensureGateway();
 
   if (!gw.isConnected) {

package/src/app/api/openclaw/events/route.ts

@@ -3,6 +3,34 @@ import { ensureGateway, type GatewayEvent } from "@/lib/gateway-connection";
 export const dynamic = "force-dynamic";
 export const runtime = "nodejs";
 
+/**
+ * Strip sensitive fields (tokens, keys) from event payloads
+ * before forwarding to the browser.
+ */
+function redactEventPayload(evt: GatewayEvent): GatewayEvent {
+  if (!evt.payload || typeof evt.payload !== "object") return evt;
+
+  const payload = { ...(evt.payload as Record<string, unknown>) };
+
+  // Redact deviceToken from pairing events
+  if (typeof payload.deviceToken === "string") {
+    payload.deviceToken = "[REDACTED]";
+  }
+  // Redact nested auth.deviceToken
+  if (payload.auth && typeof payload.auth === "object") {
+    const auth = { ...(payload.auth as Record<string, unknown>) };
+    if (typeof auth.deviceToken === "string") auth.deviceToken = "[REDACTED]";
+    if (typeof auth.token === "string") auth.token = "[REDACTED]";
+    payload.auth = auth;
+  }
+  // Redact any top-level token field
+  if (typeof payload.token === "string") {
+    payload.token = "[REDACTED]";
+  }
+
+  return { ...evt, payload };
+}
+
 /**
  * GET /api/openclaw/events
  * SSE endpoint -- streams OpenClaw Gateway events to the browser in real-time.
@@ -27,11 +55,12 @@ export async function GET() {
       };
       controller.enqueue(encoder.encode(`data: ${JSON.stringify(initial)}\n\n`));
 
-      // Forward gateway events
+      // Forward gateway events (with sensitive fields redacted)
       const onGatewayEvent = (evt: GatewayEvent) => {
         if (closed) return;
         try {
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify(evt)}\n\n`));
+          const safe = redactEventPayload(evt);
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(safe)}\n\n`));
         } catch {
           // Stream may have closed
         }