@openclaw/bluebubbles 2026.2.19 → 2026.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.2.19",
+  "version": "2026.2.21",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
   "devDependencies": {

package/src/config-schema.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { BlueBubblesConfigSchema } from "./config-schema.js";
+
+describe("BlueBubblesConfigSchema", () => {
+  it("accepts account config when serverUrl and password are both set", () => {
+    const parsed = BlueBubblesConfigSchema.safeParse({
+      serverUrl: "http://localhost:1234",
+      password: "secret",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("requires password when top-level serverUrl is configured", () => {
+    const parsed = BlueBubblesConfigSchema.safeParse({
+      serverUrl: "http://localhost:1234",
+    });
+    expect(parsed.success).toBe(false);
+    if (parsed.success) {
+      return;
+    }
+    expect(parsed.error.issues[0]?.path).toEqual(["password"]);
+    expect(parsed.error.issues[0]?.message).toBe(
+      "password is required when serverUrl is configured",
+    );
+  });
+
+  it("requires password when account serverUrl is configured", () => {
+    const parsed = BlueBubblesConfigSchema.safeParse({
+      accounts: {
+        work: {
+          serverUrl: "http://localhost:1234",
+        },
+      },
+    });
+    expect(parsed.success).toBe(false);
+    if (parsed.success) {
+      return;
+    }
+    expect(parsed.error.issues[0]?.path).toEqual(["accounts", "work", "password"]);
+    expect(parsed.error.issues[0]?.message).toBe(
+      "password is required when serverUrl is configured",
+    );
+  });
+
+  it("allows password omission when serverUrl is not configured", () => {
+    const parsed = BlueBubblesConfigSchema.safeParse({
+      accounts: {
+        work: {
+          name: "Work iMessage",
+        },
+      },
+    });
+    expect(parsed.success).toBe(true);
+  });
+});

package/src/config-schema.ts

@@ -24,27 +24,39 @@ const bluebubblesGroupConfigSchema = z.object({
   tools: ToolPolicySchema,
 });
 
-const bluebubblesAccountSchema = z.object({
-  name: z.string().optional(),
-  enabled: z.boolean().optional(),
-  markdown: MarkdownConfigSchema,
-  serverUrl: z.string().optional(),
-  password: z.string().optional(),
-  webhookPath: z.string().optional(),
-  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
-  allowFrom: z.array(allowFromEntry).optional(),
-  groupAllowFrom: z.array(allowFromEntry).optional(),
-  groupPolicy: z.enum(["open", "disabled", "allowlist"]).optional(),
-  historyLimit: z.number().int().min(0).optional(),
-  dmHistoryLimit: z.number().int().min(0).optional(),
-  textChunkLimit: z.number().int().positive().optional(),
-  chunkMode: z.enum(["length", "newline"]).optional(),
-  mediaMaxMb: z.number().int().positive().optional(),
-  mediaLocalRoots: z.array(z.string()).optional(),
-  sendReadReceipts: z.boolean().optional(),
-  blockStreaming: z.boolean().optional(),
-  groups: z.object({}).catchall(bluebubblesGroupConfigSchema).optional(),
-});
+const bluebubblesAccountSchema = z
+  .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    markdown: MarkdownConfigSchema,
+    serverUrl: z.string().optional(),
+    password: z.string().optional(),
+    webhookPath: z.string().optional(),
+    dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+    allowFrom: z.array(allowFromEntry).optional(),
+    groupAllowFrom: z.array(allowFromEntry).optional(),
+    groupPolicy: z.enum(["open", "disabled", "allowlist"]).optional(),
+    historyLimit: z.number().int().min(0).optional(),
+    dmHistoryLimit: z.number().int().min(0).optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    chunkMode: z.enum(["length", "newline"]).optional(),
+    mediaMaxMb: z.number().int().positive().optional(),
+    mediaLocalRoots: z.array(z.string()).optional(),
+    sendReadReceipts: z.boolean().optional(),
+    blockStreaming: z.boolean().optional(),
+    groups: z.object({}).catchall(bluebubblesGroupConfigSchema).optional(),
+  })
+  .superRefine((value, ctx) => {
+    const serverUrl = value.serverUrl?.trim() ?? "";
+    const password = value.password?.trim() ?? "";
+    if (serverUrl && !password) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["password"],
+        message: "password is required when serverUrl is configured",
+      });
+    }
+  });
 
 export const BlueBubblesConfigSchema = bluebubblesAccountSchema.extend({
   accounts: z.object({}).catchall(bluebubblesAccountSchema).optional(),

package/src/monitor.test.ts

@@ -452,6 +452,45 @@ describe("BlueBubbles webhook monitor", () => {
       expect(res.statusCode).toBe(400);
     });
 
+    it("accepts URL-encoded payload wrappers", async () => {
+      const account = createMockAccount();
+      const config: OpenClawConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          date: Date.now(),
+        },
+      };
+      const encodedBody = new URLSearchParams({
+        payload: JSON.stringify(payload),
+      }).toString();
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", encodedBody);
+      const res = createMockResponse();
+
+      const handled = await handleBlueBubblesWebhookRequest(req, res);
+
+      expect(handled).toBe(true);
+      expect(res.statusCode).toBe(200);
+      expect(res.body).toBe("ok");
+    });
+
     it("returns 408 when request body times out (Slow-Loris protection)", async () => {
       vi.useFakeTimers();
       try {
@@ -659,15 +698,15 @@ describe("BlueBubbles webhook monitor", () => {
       expect(sinkB).not.toHaveBeenCalled();
     });
 
-    it("does not route to passwordless targets when a password-authenticated target matches", async () => {
+    it("ignores targets without passwords when a password-authenticated target matches", async () => {
       const accountStrict = createMockAccount({ password: "secret-token" });
-      const accountFallback = createMockAccount({ password: undefined });
+      const accountWithoutPassword = createMockAccount({ password: undefined });
       const config: OpenClawConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
       const sinkStrict = vi.fn();
-      const sinkFallback = vi.fn();
+      const sinkWithoutPassword = vi.fn();
 
       const req = createMockRequest("POST", "/bluebubbles-webhook?password=secret-token", {
         type: "new-message",
@@ -691,17 +730,17 @@ describe("BlueBubbles webhook monitor", () => {
         path: "/bluebubbles-webhook",
         statusSink: sinkStrict,
       });
-      const unregisterFallback = registerBlueBubblesWebhookTarget({
-        account: accountFallback,
+      const unregisterNoPassword = registerBlueBubblesWebhookTarget({
+        account: accountWithoutPassword,
         config,
         runtime: { log: vi.fn(), error: vi.fn() },
         core,
         path: "/bluebubbles-webhook",
-        statusSink: sinkFallback,
+        statusSink: sinkWithoutPassword,
       });
       unregister = () => {
         unregisterStrict();
-        unregisterFallback();
+        unregisterNoPassword();
       };
 
       const res = createMockResponse();
@@ -710,7 +749,7 @@ describe("BlueBubbles webhook monitor", () => {
       expect(handled).toBe(true);
       expect(res.statusCode).toBe(200);
       expect(sinkStrict).toHaveBeenCalledTimes(1);
-      expect(sinkFallback).not.toHaveBeenCalled();
+      expect(sinkWithoutPassword).not.toHaveBeenCalled();
     });
 
     it("requires authentication for loopback requests when password is configured", async () => {
@@ -750,65 +789,12 @@ describe("BlueBubbles webhook monitor", () => {
       }
     });
 
-    it("rejects passwordless targets when the request looks proxied (has forwarding headers)", async () => {
+    it("rejects targets without passwords for loopback and proxied-looking requests", async () => {
       const account = createMockAccount({ password: undefined });
       const config: OpenClawConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
 
-      const req = createMockRequest(
-        "POST",
-        "/bluebubbles-webhook",
-        {
-          type: "new-message",
-          data: {
-            text: "hello",
-            handle: { address: "+15551234567" },
-            isGroup: false,
-            isFromMe: false,
-            guid: "msg-1",
-          },
-        },
-        { "x-forwarded-for": "203.0.113.10", host: "localhost" },
-      );
-      (req as unknown as { socket: { remoteAddress: string } }).socket = {
-        remoteAddress: "127.0.0.1",
-      };
-
-      unregister = registerBlueBubblesWebhookTarget({
-        account,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-      });
-
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(401);
-    });
-
-    it("accepts passwordless targets for direct localhost loopback requests (no forwarding headers)", async () => {
-      const account = createMockAccount({ password: undefined });
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
-
-      const req = createMockRequest("POST", "/bluebubbles-webhook", {
-        type: "new-message",
-        data: {
-          text: "hello",
-          handle: { address: "+15551234567" },
-          isGroup: false,
-          isFromMe: false,
-          guid: "msg-1",
-        },
-      });
-      (req as unknown as { socket: { remoteAddress: string } }).socket = {
-        remoteAddress: "127.0.0.1",
-      };
-
       unregister = registerBlueBubblesWebhookTarget({
         account,
         config,
@@ -817,10 +803,35 @@ describe("BlueBubbles webhook monitor", () => {
         path: "/bluebubbles-webhook",
       });
 
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(200);
+      const headerVariants: Record<string, string>[] = [
+        { host: "localhost" },
+        { host: "localhost", "x-forwarded-for": "203.0.113.10" },
+        { host: "localhost", forwarded: "for=203.0.113.10;proto=https;host=example.com" },
+      ];
+      for (const headers of headerVariants) {
+        const req = createMockRequest(
+          "POST",
+          "/bluebubbles-webhook",
+          {
+            type: "new-message",
+            data: {
+              text: "hello",
+              handle: { address: "+15551234567" },
+              isGroup: false,
+              isFromMe: false,
+              guid: "msg-1",
+            },
+          },
+          headers,
+        );
+        (req as unknown as { socket: { remoteAddress: string } }).socket = {
+          remoteAddress: "127.0.0.1",
+        };
+        const res = createMockResponse();
+        const handled = await handleBlueBubblesWebhookRequest(req, res);
+        expect(handled).toBe(true);
+        expect(res.statusCode).toBe(401);
+      }
     });
 
     it("ignores unregistered webhook paths", async () => {

package/src/monitor.ts

@@ -2,8 +2,12 @@ import { timingSafeEqual } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import {
+  isRequestBodyLimitError,
+  readRequestBodyWithLimit,
   registerWebhookTarget,
   rejectNonPostWebhookRequest,
+  requestBodyErrorToText,
+  resolveSingleWebhookTarget,
   resolveWebhookTargets,
 } from "openclaw/plugin-sdk";
 import {
@@ -239,64 +243,61 @@ export function registerBlueBubblesWebhookTarget(target: WebhookTarget): () => v
   };
 }
 
-async function readJsonBody(req: IncomingMessage, maxBytes: number, timeoutMs = 30_000) {
-  const chunks: Buffer[] = [];
-  let total = 0;
-  return await new Promise<{ ok: boolean; value?: unknown; error?: string }>((resolve) => {
-    let done = false;
-    const finish = (result: { ok: boolean; value?: unknown; error?: string }) => {
-      if (done) {
-        return;
-      }
-      done = true;
-      clearTimeout(timer);
-      resolve(result);
-    };
+type ReadBlueBubblesWebhookBodyResult =
+  | { ok: true; value: unknown }
+  | { ok: false; statusCode: number; error: string };
 
-    const timer = setTimeout(() => {
-      finish({ ok: false, error: "request body timeout" });
-      req.destroy();
-    }, timeoutMs);
+function parseBlueBubblesWebhookPayload(
+  rawBody: string,
+): { ok: true; value: unknown } | { ok: false; error: string } {
+  const trimmed = rawBody.trim();
+  if (!trimmed) {
+    return { ok: false, error: "empty payload" };
+  }
+  try {
+    return { ok: true, value: JSON.parse(trimmed) as unknown };
+  } catch {
+    const params = new URLSearchParams(rawBody);
+    const payload = params.get("payload") ?? params.get("data") ?? params.get("message");
+    if (!payload) {
+      return { ok: false, error: "invalid json" };
+    }
+    try {
+      return { ok: true, value: JSON.parse(payload) as unknown };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+}
 
-    req.on("data", (chunk: Buffer) => {
-      total += chunk.length;
-      if (total > maxBytes) {
-        finish({ ok: false, error: "payload too large" });
-        req.destroy();
-        return;
-      }
-      chunks.push(chunk);
-    });
-    req.on("end", () => {
-      try {
-        const raw = Buffer.concat(chunks).toString("utf8");
-        if (!raw.trim()) {
-          finish({ ok: false, error: "empty payload" });
-          return;
-        }
-        try {
-          finish({ ok: true, value: JSON.parse(raw) as unknown });
-          return;
-        } catch {
-          const params = new URLSearchParams(raw);
-          const payload = params.get("payload") ?? params.get("data") ?? params.get("message");
-          if (payload) {
-            finish({ ok: true, value: JSON.parse(payload) as unknown });
-            return;
-          }
-          throw new Error("invalid json");
-        }
-      } catch (err) {
-        finish({ ok: false, error: err instanceof Error ? err.message : String(err) });
-      }
-    });
-    req.on("error", (err) => {
-      finish({ ok: false, error: err instanceof Error ? err.message : String(err) });
-    });
-    req.on("close", () => {
-      finish({ ok: false, error: "connection closed" });
+async function readBlueBubblesWebhookBody(
+  req: IncomingMessage,
+  maxBytes: number,
+): Promise<ReadBlueBubblesWebhookBodyResult> {
+  try {
+    const rawBody = await readRequestBodyWithLimit(req, {
+      maxBytes,
+      timeoutMs: 30_000,
     });
-  });
+    const parsed = parseBlueBubblesWebhookPayload(rawBody);
+    if (!parsed.ok) {
+      return { ok: false, statusCode: 400, error: parsed.error };
+    }
+    return parsed;
+  } catch (error) {
+    if (isRequestBodyLimitError(error)) {
+      return {
+        ok: false,
+        statusCode: error.statusCode,
+        error: requestBodyErrorToText(error.code),
+      };
+    }
+    return {
+      ok: false,
+      statusCode: 400,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
 }
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -337,48 +338,6 @@ function safeEqualSecret(aRaw: string, bRaw: string): boolean {
   return timingSafeEqual(bufA, bufB);
 }
 
-function getHostName(hostHeader?: string | string[]): string {
-  const host = (Array.isArray(hostHeader) ? hostHeader[0] : (hostHeader ?? ""))
-    .trim()
-    .toLowerCase();
-  if (!host) {
-    return "";
-  }
-  // Bracketed IPv6: [::1]:18789
-  if (host.startsWith("[")) {
-    const end = host.indexOf("]");
-    if (end !== -1) {
-      return host.slice(1, end);
-    }
-  }
-  const [name] = host.split(":");
-  return name ?? "";
-}
-
-function isDirectLocalLoopbackRequest(req: IncomingMessage): boolean {
-  const remote = (req.socket?.remoteAddress ?? "").trim().toLowerCase();
-  const remoteIsLoopback =
-    remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1";
-  if (!remoteIsLoopback) {
-    return false;
-  }
-
-  const host = getHostName(req.headers?.host);
-  const hostIsLocal = host === "localhost" || host === "127.0.0.1" || host === "::1";
-  if (!hostIsLocal) {
-    return false;
-  }
-
-  // If a reverse proxy is in front, it will usually inject forwarding headers.
-  // Passwordless webhooks must never be accepted through a proxy.
-  const hasForwarded = Boolean(
-    req.headers?.["x-forwarded-for"] ||
-    req.headers?.["x-real-ip"] ||
-    req.headers?.["x-forwarded-host"],
-  );
-  return !hasForwarded;
-}
-
 export async function handleBlueBubblesWebhookRequest(
   req: IncomingMessage,
   res: ServerResponse,
@@ -394,15 +353,9 @@ export async function handleBlueBubblesWebhookRequest(
     return true;
   }
 
-  const body = await readJsonBody(req, 1024 * 1024);
+  const body = await readBlueBubblesWebhookBody(req, 1024 * 1024);
   if (!body.ok) {
-    if (body.error === "payload too large") {
-      res.statusCode = 413;
-    } else if (body.error === "request body timeout") {
-      res.statusCode = 408;
-    } else {
-      res.statusCode = 400;
-    }
+    res.statusCode = body.statusCode;
     res.end(body.error ?? "invalid payload");
     console.warn(`[bluebubbles] webhook rejected: ${body.error ?? "invalid payload"}`);
     return true;
@@ -466,31 +419,12 @@ export async function handleBlueBubblesWebhookRequest(
     req.headers["x-bluebubbles-guid"] ??
     req.headers["authorization"];
   const guid = (Array.isArray(headerToken) ? headerToken[0] : headerToken) ?? guidParam ?? "";
-
-  const strictMatches: WebhookTarget[] = [];
-  const passwordlessTargets: WebhookTarget[] = [];
-  for (const target of targets) {
+  const matchedTarget = resolveSingleWebhookTarget(targets, (target) => {
     const token = target.account.config.password?.trim() ?? "";
-    if (!token) {
-      passwordlessTargets.push(target);
-      continue;
-    }
-    if (safeEqualSecret(guid, token)) {
-      strictMatches.push(target);
-      if (strictMatches.length > 1) {
-        break;
-      }
-    }
-  }
-
-  const matching =
-    strictMatches.length > 0
-      ? strictMatches
-      : isDirectLocalLoopbackRequest(req)
-        ? passwordlessTargets
-        : [];
+    return safeEqualSecret(guid, token);
+  });
 
-  if (matching.length === 0) {
+  if (matchedTarget.kind === "none") {
     res.statusCode = 401;
     res.end("unauthorized");
     console.warn(
@@ -499,14 +433,14 @@ export async function handleBlueBubblesWebhookRequest(
     return true;
   }
 
-  if (matching.length > 1) {
+  if (matchedTarget.kind === "ambiguous") {
     res.statusCode = 401;
     res.end("ambiguous webhook target");
     console.warn(`[bluebubbles] webhook rejected: ambiguous target match path=${path}`);
     return true;
   }
 
-  const target = matching[0];
+  const target = matchedTarget.target;
   target.statusSink?.({ lastInboundAt: Date.now() });
   if (reaction) {
     processReaction(reaction, target).catch((err) => {