@openclaw/nextcloud-talk 2026.2.24 → 2026.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/nextcloud-talk",
-  "version": "2026.2.24",
+  "version": "2026.3.1",
   "description": "OpenClaw Nextcloud Talk channel plugin",
   "type": "module",
   "openclaw": {

package/src/accounts.ts

@@ -1,5 +1,9 @@
 import { readFileSync } from "node:fs";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "openclaw/plugin-sdk/account-id";
 import type { CoreConfig, NextcloudTalkAccountConfig } from "./types.js";
 
 function isTruthyEnvValue(value?: string): boolean {
@@ -48,6 +52,15 @@ export function listNextcloudTalkAccountIds(cfg: CoreConfig): string[] {
 }
 
 export function resolveDefaultNextcloudTalkAccountId(cfg: CoreConfig): string {
+  const preferred = normalizeOptionalAccountId(cfg.channels?.["nextcloud-talk"]?.defaultAccount);
+  if (
+    preferred &&
+    listNextcloudTalkAccountIds(cfg).some(
+      (accountId) => normalizeAccountId(accountId) === preferred,
+    )
+  ) {
+    return preferred;
+  }
   const ids = listNextcloudTalkAccountIds(cfg);
   if (ids.includes(DEFAULT_ACCOUNT_ID)) {
     return DEFAULT_ACCOUNT_ID;
@@ -76,8 +89,14 @@ function mergeNextcloudTalkAccountConfig(
   cfg: CoreConfig,
   accountId: string,
 ): NextcloudTalkAccountConfig {
-  const { accounts: _ignored, ...base } = (cfg.channels?.["nextcloud-talk"] ??
-    {}) as NextcloudTalkAccountConfig & { accounts?: unknown };
+  const {
+    accounts: _ignored,
+    defaultAccount: _ignoredDefaultAccount,
+    ...base
+  } = (cfg.channels?.["nextcloud-talk"] ?? {}) as NextcloudTalkAccountConfig & {
+    accounts?: unknown;
+    defaultAccount?: unknown;
+  };
   const account = resolveAccountConfig(cfg, accountId) ?? {};
   return { ...base, ...account };
 }

package/src/channel.startup.test.ts

@@ -0,0 +1,115 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelGatewayContext,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createRuntimeEnv } from "../../test-utils/runtime-env.js";
+import type { ResolvedNextcloudTalkAccount } from "./accounts.js";
+
+const hoisted = vi.hoisted(() => ({
+  monitorNextcloudTalkProvider: vi.fn(),
+}));
+
+vi.mock("./monitor.js", async () => {
+  const actual = await vi.importActual<typeof import("./monitor.js")>("./monitor.js");
+  return {
+    ...actual,
+    monitorNextcloudTalkProvider: hoisted.monitorNextcloudTalkProvider,
+  };
+});
+
+import { nextcloudTalkPlugin } from "./channel.js";
+
+function createStartAccountCtx(params: {
+  account: ResolvedNextcloudTalkAccount;
+  abortSignal: AbortSignal;
+}): ChannelGatewayContext<ResolvedNextcloudTalkAccount> {
+  const snapshot: ChannelAccountSnapshot = {
+    accountId: params.account.accountId,
+    configured: true,
+    enabled: true,
+    running: false,
+  };
+  return {
+    accountId: params.account.accountId,
+    account: params.account,
+    cfg: {} as OpenClawConfig,
+    runtime: createRuntimeEnv(),
+    abortSignal: params.abortSignal,
+    log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+    getStatus: () => snapshot,
+    setStatus: (next) => {
+      Object.assign(snapshot, next);
+    },
+  };
+}
+
+function buildAccount(): ResolvedNextcloudTalkAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    baseUrl: "https://nextcloud.example.com",
+    secret: "secret",
+    secretSource: "config",
+    config: {
+      baseUrl: "https://nextcloud.example.com",
+      botSecret: "secret",
+      webhookPath: "/nextcloud-talk-webhook",
+      webhookPort: 8788,
+    },
+  };
+}
+
+describe("nextcloudTalkPlugin gateway.startAccount", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("keeps startAccount pending until abort, then stops the monitor", async () => {
+    const stop = vi.fn();
+    hoisted.monitorNextcloudTalkProvider.mockResolvedValue({ stop });
+    const abort = new AbortController();
+
+    const task = nextcloudTalkPlugin.gateway!.startAccount!(
+      createStartAccountCtx({
+        account: buildAccount(),
+        abortSignal: abort.signal,
+      }),
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    let settled = false;
+    void task.then(() => {
+      settled = true;
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(settled).toBe(false);
+    expect(hoisted.monitorNextcloudTalkProvider).toHaveBeenCalledOnce();
+    expect(stop).not.toHaveBeenCalled();
+
+    abort.abort();
+    await task;
+
+    expect(stop).toHaveBeenCalledOnce();
+  });
+
+  it("stops immediately when startAccount receives an already-aborted signal", async () => {
+    const stop = vi.fn();
+    hoisted.monitorNextcloudTalkProvider.mockResolvedValue({ stop });
+    const abort = new AbortController();
+    abort.abort();
+
+    await nextcloudTalkPlugin.gateway!.startAccount!(
+      createStartAccountCtx({
+        account: buildAccount(),
+        abortSignal: abort.signal,
+      }),
+    );
+
+    expect(hoisted.monitorNextcloudTalkProvider).toHaveBeenCalledOnce();
+    expect(stop).toHaveBeenCalledOnce();
+  });
+});

package/src/channel.ts

@@ -12,6 +12,7 @@ import {
   type OpenClawConfig,
   type ChannelSetupInput,
 } from "openclaw/plugin-sdk";
+import { waitForAbortSignal } from "../../../src/infra/abort-signal.js";
 import {
   listNextcloudTalkAccountIds,
   resolveDefaultNextcloudTalkAccountId,
@@ -332,7 +333,9 @@ export const nextcloudTalkPlugin: ChannelPlugin<ResolvedNextcloudTalkAccount> =
         statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
       });
 
-      return { stop };
+      // Keep webhook channels pending for the account lifecycle.
+      await waitForAbortSignal(ctx.abortSignal);
+      stop();
     },
     logoutAccount: async ({ accountId, cfg }) => {
       const nextCfg = { ...cfg } as OpenClawConfig;

package/src/config-schema.ts

@@ -60,6 +60,7 @@ export const NextcloudTalkAccountSchema = NextcloudTalkAccountSchemaBase.superRe
 
 export const NextcloudTalkConfigSchema = NextcloudTalkAccountSchemaBase.extend({
   accounts: z.record(z.string(), NextcloudTalkAccountSchema.optional()).optional(),
+  defaultAccount: z.string().optional(),
 }).superRefine((value, ctx) => {
   requireOpenAllowFrom({
     policy: value.dmPolicy,

package/src/inbound.authz.test.ts

@@ -0,0 +1,84 @@
+import type { PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+import type { ResolvedNextcloudTalkAccount } from "./accounts.js";
+import { handleNextcloudTalkInbound } from "./inbound.js";
+import { setNextcloudTalkRuntime } from "./runtime.js";
+import type { CoreConfig, NextcloudTalkInboundMessage } from "./types.js";
+
+describe("nextcloud-talk inbound authz", () => {
+  it("does not treat DM pairing-store entries as group allowlist entries", async () => {
+    const readAllowFromStore = vi.fn(async () => ["attacker"]);
+    const buildMentionRegexes = vi.fn(() => [/@openclaw/i]);
+
+    setNextcloudTalkRuntime({
+      channel: {
+        pairing: {
+          readAllowFromStore,
+        },
+        commands: {
+          shouldHandleTextCommands: () => false,
+        },
+        text: {
+          hasControlCommand: () => false,
+        },
+        mentions: {
+          buildMentionRegexes,
+          matchesMentionPatterns: () => false,
+        },
+      },
+    } as unknown as PluginRuntime);
+
+    const message: NextcloudTalkInboundMessage = {
+      messageId: "m-1",
+      roomToken: "room-1",
+      roomName: "Room 1",
+      senderId: "attacker",
+      senderName: "Attacker",
+      text: "hello",
+      mediaType: "text/plain",
+      timestamp: Date.now(),
+      isGroupChat: true,
+    };
+
+    const account: ResolvedNextcloudTalkAccount = {
+      accountId: "default",
+      enabled: true,
+      baseUrl: "",
+      secret: "",
+      secretSource: "none",
+      config: {
+        dmPolicy: "pairing",
+        allowFrom: [],
+        groupPolicy: "allowlist",
+        groupAllowFrom: [],
+      },
+    };
+
+    const config: CoreConfig = {
+      channels: {
+        "nextcloud-talk": {
+          dmPolicy: "pairing",
+          allowFrom: [],
+          groupPolicy: "allowlist",
+          groupAllowFrom: [],
+        },
+      },
+    };
+
+    await handleNextcloudTalkInbound({
+      message,
+      account,
+      config,
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+      } as unknown as RuntimeEnv,
+    });
+
+    expect(readAllowFromStore).toHaveBeenCalledWith({
+      channel: "nextcloud-talk",
+      accountId: "default",
+    });
+    expect(buildMentionRegexes).not.toHaveBeenCalled();
+  });
+});

package/src/inbound.ts

@@ -1,10 +1,12 @@
 import {
   GROUP_POLICY_BLOCKED_LABEL,
+  createScopedPairingAccess,
   createNormalizedOutboundDeliverer,
   createReplyPrefixOptions,
   formatTextWithAttachmentLinks,
   logInboundDrop,
-  resolveControlCommandGate,
+  readStoreAllowFromForDmPolicy,
+  resolveDmGroupAccessWithCommandGate,
   resolveOutboundMediaUrls,
   resolveAllowlistProviderRuntimeGroupPolicy,
   resolveDefaultGroupPolicy,
@@ -57,6 +59,11 @@ export async function handleNextcloudTalkInbound(params: {
 }): Promise<void> {
   const { message, account, config, runtime, statusSink } = params;
   const core = getNextcloudTalkRuntime();
+  const pairing = createScopedPairingAccess({
+    core,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+  });
 
   const rawBody = message.text?.trim() ?? "";
   if (!rawBody) {
@@ -96,10 +103,12 @@ export async function handleNextcloudTalkInbound(params: {
 
   const configAllowFrom = normalizeNextcloudTalkAllowlist(account.config.allowFrom);
   const configGroupAllowFrom = normalizeNextcloudTalkAllowlist(account.config.groupAllowFrom);
-  const storeAllowFrom =
-    dmPolicy === "allowlist"
-      ? []
-      : await core.channel.pairing.readAllowFromStore(CHANNEL_ID).catch(() => []);
+  const storeAllowFrom = await readStoreAllowFromForDmPolicy({
+    provider: CHANNEL_ID,
+    accountId: account.accountId,
+    dmPolicy,
+    readStore: pairing.readStoreForDmPolicy,
+  });
   const storeAllowList = normalizeNextcloudTalkAllowlist(storeAllowFrom);
 
   const roomMatch = resolveNextcloudTalkRoomMatch({
@@ -118,11 +127,6 @@ export async function handleNextcloudTalkInbound(params: {
   }
 
   const roomAllowFrom = normalizeNextcloudTalkAllowlist(roomConfig?.allowFrom);
-  const baseGroupAllowFrom =
-    configGroupAllowFrom.length > 0 ? configGroupAllowFrom : configAllowFrom;
-
-  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowList].filter(Boolean);
-  const effectiveGroupAllowFrom = [...baseGroupAllowFrom, ...storeAllowList].filter(Boolean);
 
   const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
     cfg: config as OpenClawConfig,
@@ -130,25 +134,33 @@ export async function handleNextcloudTalkInbound(params: {
   });
   const useAccessGroups =
     (config.commands as Record<string, unknown> | undefined)?.useAccessGroups !== false;
-  const senderAllowedForCommands = resolveNextcloudTalkAllowlistMatch({
-    allowFrom: isGroup ? effectiveGroupAllowFrom : effectiveAllowFrom,
-    senderId,
-  }).allowed;
   const hasControlCommand = core.channel.text.hasControlCommand(rawBody, config as OpenClawConfig);
-  const commandGate = resolveControlCommandGate({
-    useAccessGroups,
-    authorizers: [
-      {
-        configured: (isGroup ? effectiveGroupAllowFrom : effectiveAllowFrom).length > 0,
-        allowed: senderAllowedForCommands,
-      },
-    ],
-    allowTextCommands,
-    hasControlCommand,
+  const access = resolveDmGroupAccessWithCommandGate({
+    isGroup,
+    dmPolicy,
+    groupPolicy,
+    allowFrom: configAllowFrom,
+    groupAllowFrom: configGroupAllowFrom,
+    storeAllowFrom: storeAllowList,
+    isSenderAllowed: (allowFrom) =>
+      resolveNextcloudTalkAllowlistMatch({
+        allowFrom,
+        senderId,
+      }).allowed,
+    command: {
+      useAccessGroups,
+      allowTextCommands,
+      hasControlCommand,
+    },
   });
-  const commandAuthorized = commandGate.commandAuthorized;
+  const commandAuthorized = access.commandAuthorized;
+  const effectiveGroupAllowFrom = access.effectiveGroupAllowFrom;
 
   if (isGroup) {
+    if (access.decision !== "allow") {
+      runtime.log?.(`nextcloud-talk: drop group sender ${senderId} (reason=${access.reason})`);
+      return;
+    }
     const groupAllow = resolveNextcloudTalkGroupAllow({
       groupPolicy,
       outerAllowFrom: effectiveGroupAllowFrom,
@@ -160,48 +172,35 @@ export async function handleNextcloudTalkInbound(params: {
       return;
     }
   } else {
-    if (dmPolicy === "disabled") {
-      runtime.log?.(`nextcloud-talk: drop DM sender=${senderId} (dmPolicy=disabled)`);
-      return;
-    }
-    if (dmPolicy !== "open") {
-      const dmAllowed = resolveNextcloudTalkAllowlistMatch({
-        allowFrom: effectiveAllowFrom,
-        senderId,
-      }).allowed;
-      if (!dmAllowed) {
-        if (dmPolicy === "pairing") {
-          const { code, created } = await core.channel.pairing.upsertPairingRequest({
-            channel: CHANNEL_ID,
-            id: senderId,
-            meta: { name: senderName || undefined },
-          });
-          if (created) {
-            try {
-              await sendMessageNextcloudTalk(
-                roomToken,
-                core.channel.pairing.buildPairingReply({
-                  channel: CHANNEL_ID,
-                  idLine: `Your Nextcloud user id: ${senderId}`,
-                  code,
-                }),
-                { accountId: account.accountId },
-              );
-              statusSink?.({ lastOutboundAt: Date.now() });
-            } catch (err) {
-              runtime.error?.(
-                `nextcloud-talk: pairing reply failed for ${senderId}: ${String(err)}`,
-              );
-            }
+    if (access.decision !== "allow") {
+      if (access.decision === "pairing") {
+        const { code, created } = await pairing.upsertPairingRequest({
+          id: senderId,
+          meta: { name: senderName || undefined },
+        });
+        if (created) {
+          try {
+            await sendMessageNextcloudTalk(
+              roomToken,
+              core.channel.pairing.buildPairingReply({
+                channel: CHANNEL_ID,
+                idLine: `Your Nextcloud user id: ${senderId}`,
+                code,
+              }),
+              { accountId: account.accountId },
+            );
+            statusSink?.({ lastOutboundAt: Date.now() });
+          } catch (err) {
+            runtime.error?.(`nextcloud-talk: pairing reply failed for ${senderId}: ${String(err)}`);
           }
         }
-        runtime.log?.(`nextcloud-talk: drop DM sender ${senderId} (dmPolicy=${dmPolicy})`);
-        return;
       }
+      runtime.log?.(`nextcloud-talk: drop DM sender ${senderId} (reason=${access.reason})`);
+      return;
     }
   }
 
-  if (isGroup && commandGate.shouldBlock) {
+  if (access.shouldBlockControlCommand) {
     logInboundDrop({
       log: (message) => runtime.log?.(message),
       channel: CHANNEL_ID,

package/src/monitor.auth-order.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it, vi } from "vitest";
+import { startWebhookServer } from "./monitor.test-harness.js";
+
+describe("createNextcloudTalkWebhookServer auth order", () => {
+  it("rejects missing signature headers before reading request body", async () => {
+    const readBody = vi.fn(async () => {
+      throw new Error("should not be called for missing signature headers");
+    });
+    const harness = await startWebhookServer({
+      path: "/nextcloud-auth-order",
+      maxBodyBytes: 128,
+      readBody,
+      onMessage: vi.fn(),
+    });
+
+    const response = await fetch(harness.webhookUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+      },
+      body: "{}",
+    });
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({ error: "Missing signature headers" });
+    expect(readBody).not.toHaveBeenCalled();
+  });
+});

package/src/monitor.backend.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+import { startWebhookServer } from "./monitor.test-harness.js";
+import { generateNextcloudTalkSignature } from "./signature.js";
+
+describe("createNextcloudTalkWebhookServer backend allowlist", () => {
+  it("rejects requests from unexpected backend origins", async () => {
+    const onMessage = vi.fn(async () => {});
+    const harness = await startWebhookServer({
+      path: "/nextcloud-backend-check",
+      isBackendAllowed: (backend) => backend === "https://nextcloud.expected",
+      onMessage,
+    });
+
+    const payload = {
+      type: "Create",
+      actor: { type: "Person", id: "alice", name: "Alice" },
+      object: {
+        type: "Note",
+        id: "msg-1",
+        name: "hello",
+        content: "hello",
+        mediaType: "text/plain",
+      },
+      target: { type: "Collection", id: "room-1", name: "Room 1" },
+    };
+    const body = JSON.stringify(payload);
+    const { random, signature } = generateNextcloudTalkSignature({
+      body,
+      secret: "nextcloud-secret",
+    });
+    const response = await fetch(harness.webhookUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-nextcloud-talk-random": random,
+        "x-nextcloud-talk-signature": signature,
+        "x-nextcloud-talk-backend": "https://nextcloud.unexpected",
+      },
+      body,
+    });
+
+    expect(response.status).toBe(401);
+    expect(await response.json()).toEqual({ error: "Invalid backend" });
+    expect(onMessage).not.toHaveBeenCalled();
+  });
+});

package/src/monitor.replay.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from "vitest";
+import { startWebhookServer } from "./monitor.test-harness.js";
+import { generateNextcloudTalkSignature } from "./signature.js";
+import type { NextcloudTalkInboundMessage } from "./types.js";
+
+function createSignedRequest(body: string): { random: string; signature: string } {
+  return generateNextcloudTalkSignature({
+    body,
+    secret: "nextcloud-secret",
+  });
+}
+
+describe("createNextcloudTalkWebhookServer replay handling", () => {
+  it("acknowledges replayed requests and skips onMessage side effects", async () => {
+    const seen = new Set<string>();
+    const onMessage = vi.fn(async () => {});
+    const shouldProcessMessage = vi.fn(async (message: NextcloudTalkInboundMessage) => {
+      if (seen.has(message.messageId)) {
+        return false;
+      }
+      seen.add(message.messageId);
+      return true;
+    });
+    const harness = await startWebhookServer({
+      path: "/nextcloud-replay",
+      shouldProcessMessage,
+      onMessage,
+    });
+
+    const payload = {
+      type: "Create",
+      actor: { type: "Person", id: "alice", name: "Alice" },
+      object: {
+        type: "Note",
+        id: "msg-1",
+        name: "hello",
+        content: "hello",
+        mediaType: "text/plain",
+      },
+      target: { type: "Collection", id: "room-1", name: "Room 1" },
+    };
+    const body = JSON.stringify(payload);
+    const { random, signature } = createSignedRequest(body);
+    const headers = {
+      "content-type": "application/json",
+      "x-nextcloud-talk-random": random,
+      "x-nextcloud-talk-signature": signature,
+      "x-nextcloud-talk-backend": "https://nextcloud.example",
+    };
+
+    const first = await fetch(harness.webhookUrl, {
+      method: "POST",
+      headers,
+      body,
+    });
+    const second = await fetch(harness.webhookUrl, {
+      method: "POST",
+      headers,
+      body,
+    });
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(shouldProcessMessage).toHaveBeenCalledTimes(2);
+    expect(onMessage).toHaveBeenCalledTimes(1);
+  });
+});

package/src/monitor.test-harness.ts

@@ -0,0 +1,59 @@
+import { type AddressInfo } from "node:net";
+import { afterEach } from "vitest";
+import { createNextcloudTalkWebhookServer } from "./monitor.js";
+import type { NextcloudTalkWebhookServerOptions } from "./types.js";
+
+export type WebhookHarness = {
+  webhookUrl: string;
+  stop: () => Promise<void>;
+};
+
+const cleanupFns: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanupFns.length > 0) {
+    const cleanup = cleanupFns.pop();
+    if (cleanup) {
+      await cleanup();
+    }
+  }
+});
+
+export type StartWebhookServerParams = Omit<
+  NextcloudTalkWebhookServerOptions,
+  "port" | "host" | "path" | "secret"
+> & {
+  path: string;
+  secret?: string;
+  host?: string;
+  port?: number;
+};
+
+export async function startWebhookServer(
+  params: StartWebhookServerParams,
+): Promise<WebhookHarness> {
+  const host = params.host ?? "127.0.0.1";
+  const port = params.port ?? 0;
+  const secret = params.secret ?? "nextcloud-secret";
+  const { server, start } = createNextcloudTalkWebhookServer({
+    ...params,
+    port,
+    host,
+    secret,
+  });
+  await start();
+  const address = server.address() as AddressInfo | null;
+  if (!address) {
+    throw new Error("missing server address");
+  }
+
+  const harness: WebhookHarness = {
+    webhookUrl: `http://${host}:${address.port}${params.path}`,
+    stop: () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      }),
+  };
+  cleanupFns.push(harness.stop);
+  return harness;
+}

package/src/monitor.ts

@@ -1,4 +1,5 @@
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import os from "node:os";
 import {
   createLoggerBackedRuntime,
   type RuntimeEnv,
@@ -8,11 +9,13 @@ import {
 } from "openclaw/plugin-sdk";
 import { resolveNextcloudTalkAccount } from "./accounts.js";
 import { handleNextcloudTalkInbound } from "./inbound.js";
+import { createNextcloudTalkReplayGuard } from "./replay-guard.js";
 import { getNextcloudTalkRuntime } from "./runtime.js";
 import { extractNextcloudTalkHeaders, verifyNextcloudTalkSignature } from "./signature.js";
 import type {
   CoreConfig,
   NextcloudTalkInboundMessage,
+  NextcloudTalkWebhookHeaders,
   NextcloudTalkWebhookPayload,
   NextcloudTalkWebhookServerOptions,
 } from "./types.js";
@@ -23,6 +26,14 @@ const DEFAULT_WEBHOOK_PATH = "/nextcloud-talk-webhook";
 const DEFAULT_WEBHOOK_MAX_BODY_BYTES = 1024 * 1024;
 const DEFAULT_WEBHOOK_BODY_TIMEOUT_MS = 30_000;
 const HEALTH_PATH = "/healthz";
+const WEBHOOK_ERRORS = {
+  missingSignatureHeaders: "Missing signature headers",
+  invalidBackend: "Invalid backend",
+  invalidSignature: "Invalid signature",
+  invalidPayloadFormat: "Invalid payload format",
+  payloadTooLarge: "Payload too large",
+  internalServerError: "Internal server error",
+} as const;
 
 function formatError(err: unknown): string {
   if (err instanceof Error) {
@@ -31,6 +42,14 @@ function formatError(err: unknown): string {
   return typeof err === "string" ? err : JSON.stringify(err);
 }
 
+function normalizeOrigin(value: string): string | null {
+  try {
+    return new URL(value).origin.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
 function parseWebhookPayload(body: string): NextcloudTalkWebhookPayload | null {
   try {
     const data = JSON.parse(body);
@@ -51,6 +70,83 @@ function parseWebhookPayload(body: string): NextcloudTalkWebhookPayload | null {
   }
 }
 
+function writeJsonResponse(
+  res: ServerResponse,
+  status: number,
+  body?: Record<string, unknown>,
+): void {
+  if (body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+    return;
+  }
+  res.writeHead(status);
+  res.end();
+}
+
+function writeWebhookError(res: ServerResponse, status: number, error: string): void {
+  if (res.headersSent) {
+    return;
+  }
+  writeJsonResponse(res, status, { error });
+}
+
+function validateWebhookHeaders(params: {
+  req: IncomingMessage;
+  res: ServerResponse;
+  isBackendAllowed?: (backend: string) => boolean;
+}): NextcloudTalkWebhookHeaders | null {
+  const headers = extractNextcloudTalkHeaders(
+    params.req.headers as Record<string, string | string[] | undefined>,
+  );
+  if (!headers) {
+    writeWebhookError(params.res, 400, WEBHOOK_ERRORS.missingSignatureHeaders);
+    return null;
+  }
+  if (params.isBackendAllowed && !params.isBackendAllowed(headers.backend)) {
+    writeWebhookError(params.res, 401, WEBHOOK_ERRORS.invalidBackend);
+    return null;
+  }
+  return headers;
+}
+
+function verifyWebhookSignature(params: {
+  headers: NextcloudTalkWebhookHeaders;
+  body: string;
+  secret: string;
+  res: ServerResponse;
+}): boolean {
+  const isValid = verifyNextcloudTalkSignature({
+    signature: params.headers.signature,
+    random: params.headers.random,
+    body: params.body,
+    secret: params.secret,
+  });
+  if (!isValid) {
+    writeWebhookError(params.res, 401, WEBHOOK_ERRORS.invalidSignature);
+    return false;
+  }
+  return true;
+}
+
+function decodeWebhookCreateMessage(params: {
+  body: string;
+  res: ServerResponse;
+}):
+  | { kind: "message"; message: NextcloudTalkInboundMessage }
+  | { kind: "ignore" }
+  | { kind: "invalid" } {
+  const payload = parseWebhookPayload(params.body);
+  if (!payload) {
+    writeWebhookError(params.res, 400, WEBHOOK_ERRORS.invalidPayloadFormat);
+    return { kind: "invalid" };
+  }
+  if (payload.type !== "Create") {
+    return { kind: "ignore" };
+  }
+  return { kind: "message", message: payloadToInboundMessage(payload) };
+}
+
 function payloadToInboundMessage(
   payload: NextcloudTalkWebhookPayload,
 ): NextcloudTalkInboundMessage {
@@ -92,6 +188,9 @@ export function createNextcloudTalkWebhookServer(opts: NextcloudTalkWebhookServe
     opts.maxBodyBytes > 0
       ? Math.floor(opts.maxBodyBytes)
       : DEFAULT_WEBHOOK_MAX_BODY_BYTES;
+  const readBody = opts.readBody ?? readNextcloudTalkWebhookBody;
+  const isBackendAllowed = opts.isBackendAllowed;
+  const shouldProcessMessage = opts.shouldProcessMessage;
 
   const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
     if (req.url === HEALTH_PATH) {
@@ -107,47 +206,49 @@ export function createNextcloudTalkWebhookServer(opts: NextcloudTalkWebhookServe
     }
 
     try {
-      const body = await readNextcloudTalkWebhookBody(req, maxBodyBytes);
-
-      const headers = extractNextcloudTalkHeaders(
-        req.headers as Record<string, string | string[] | undefined>,
-      );
+      const headers = validateWebhookHeaders({
+        req,
+        res,
+        isBackendAllowed,
+      });
       if (!headers) {
-        res.writeHead(400, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Missing signature headers" }));
         return;
       }
 
-      const isValid = verifyNextcloudTalkSignature({
-        signature: headers.signature,
-        random: headers.random,
+      const body = await readBody(req, maxBodyBytes);
+
+      const hasValidSignature = verifyWebhookSignature({
+        headers,
         body,
         secret,
+        res,
       });
-
-      if (!isValid) {
-        res.writeHead(401, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Invalid signature" }));
+      if (!hasValidSignature) {
         return;
       }
 
-      const payload = parseWebhookPayload(body);
-      if (!payload) {
-        res.writeHead(400, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Invalid payload format" }));
+      const decoded = decodeWebhookCreateMessage({
+        body,
+        res,
+      });
+      if (decoded.kind === "invalid") {
         return;
       }
-
-      if (payload.type !== "Create") {
-        res.writeHead(200);
-        res.end();
+      if (decoded.kind === "ignore") {
+        writeJsonResponse(res, 200);
         return;
       }
 
-      const message = payloadToInboundMessage(payload);
+      const message = decoded.message;
+      if (shouldProcessMessage) {
+        const shouldProcess = await shouldProcessMessage(message);
+        if (!shouldProcess) {
+          writeJsonResponse(res, 200);
+          return;
+        }
+      }
 
-      res.writeHead(200);
-      res.end();
+      writeJsonResponse(res, 200);
 
       try {
         await onMessage(message);
@@ -156,25 +257,16 @@ export function createNextcloudTalkWebhookServer(opts: NextcloudTalkWebhookServe
       }
     } catch (err) {
       if (isRequestBodyLimitError(err, "PAYLOAD_TOO_LARGE")) {
-        if (!res.headersSent) {
-          res.writeHead(413, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Payload too large" }));
-        }
+        writeWebhookError(res, 413, WEBHOOK_ERRORS.payloadTooLarge);
         return;
       }
       if (isRequestBodyLimitError(err, "REQUEST_BODY_TIMEOUT")) {
-        if (!res.headersSent) {
-          res.writeHead(408, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: requestBodyErrorToText("REQUEST_BODY_TIMEOUT") }));
-        }
+        writeWebhookError(res, 408, requestBodyErrorToText("REQUEST_BODY_TIMEOUT"));
         return;
       }
       const error = err instanceof Error ? err : new Error(formatError(err));
       onError?.(error);
-      if (!res.headersSent) {
-        res.writeHead(500, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Internal server error" }));
-      }
+      writeWebhookError(res, 500, WEBHOOK_ERRORS.internalServerError);
     }
   });
 
@@ -184,12 +276,25 @@ export function createNextcloudTalkWebhookServer(opts: NextcloudTalkWebhookServe
     });
   };
 
+  let stopped = false;
   const stop = () => {
-    server.close();
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    try {
+      server.close();
+    } catch {
+      // ignore close races while shutting down
+    }
   };
 
   if (abortSignal) {
-    abortSignal.addEventListener("abort", stop, { once: true });
+    if (abortSignal.aborted) {
+      stop();
+    } else {
+      abortSignal.addEventListener("abort", stop, { once: true });
+    }
   }
 
   return { server, start, stop };
@@ -232,12 +337,41 @@ export async function monitorNextcloudTalkProvider(
     channel: "nextcloud-talk",
     accountId: account.accountId,
   });
+  const expectedBackendOrigin = normalizeOrigin(account.baseUrl);
+  const replayGuard = createNextcloudTalkReplayGuard({
+    stateDir: core.state.resolveStateDir(process.env, os.homedir),
+    onDiskError: (error) => {
+      logger.warn(
+        `[nextcloud-talk:${account.accountId}] replay guard disk error: ${String(error)}`,
+      );
+    },
+  });
 
   const { start, stop } = createNextcloudTalkWebhookServer({
     port,
     host,
     path,
     secret: account.secret,
+    isBackendAllowed: (backend) => {
+      if (!expectedBackendOrigin) {
+        return true;
+      }
+      const backendOrigin = normalizeOrigin(backend);
+      return backendOrigin === expectedBackendOrigin;
+    },
+    shouldProcessMessage: async (message) => {
+      const shouldProcess = await replayGuard.shouldProcessMessage({
+        accountId: account.accountId,
+        roomToken: message.roomToken,
+        messageId: message.messageId,
+      });
+      if (!shouldProcess) {
+        logger.warn(
+          `[nextcloud-talk:${account.accountId}] replayed webhook ignored room=${message.roomToken} messageId=${message.messageId}`,
+        );
+      }
+      return shouldProcess;
+    },
     onMessage: async (message) => {
       core.channel.activity.record({
         channel: "nextcloud-talk",
@@ -263,7 +397,14 @@ export async function monitorNextcloudTalkProvider(
     abortSignal: opts.abortSignal,
   });
 
+  if (opts.abortSignal?.aborted) {
+    return { stop };
+  }
   await start();
+  if (opts.abortSignal?.aborted) {
+    stop();
+    return { stop };
+  }
 
   const publicUrl =
     account.config.webhookPublicUrl ??

package/src/replay-guard.test.ts

@@ -0,0 +1,70 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createNextcloudTalkReplayGuard } from "./replay-guard.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "nextcloud-talk-replay-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe("createNextcloudTalkReplayGuard", () => {
+  it("persists replay decisions across guard instances", async () => {
+    const stateDir = await makeTempDir();
+
+    const firstGuard = createNextcloudTalkReplayGuard({ stateDir });
+    const firstAttempt = await firstGuard.shouldProcessMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-1",
+    });
+    const replayAttempt = await firstGuard.shouldProcessMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-1",
+    });
+
+    const secondGuard = createNextcloudTalkReplayGuard({ stateDir });
+    const restartReplayAttempt = await secondGuard.shouldProcessMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-1",
+    });
+
+    expect(firstAttempt).toBe(true);
+    expect(replayAttempt).toBe(false);
+    expect(restartReplayAttempt).toBe(false);
+  });
+
+  it("scopes replay state by account namespace", async () => {
+    const stateDir = await makeTempDir();
+    const guard = createNextcloudTalkReplayGuard({ stateDir });
+
+    const accountAFirst = await guard.shouldProcessMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-9",
+    });
+    const accountBFirst = await guard.shouldProcessMessage({
+      accountId: "account-b",
+      roomToken: "room-1",
+      messageId: "msg-9",
+    });
+
+    expect(accountAFirst).toBe(true);
+    expect(accountBFirst).toBe(true);
+  });
+});

package/src/replay-guard.ts

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { createPersistentDedupe } from "openclaw/plugin-sdk";
+
+const DEFAULT_REPLAY_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MEMORY_MAX_SIZE = 1_000;
+const DEFAULT_FILE_MAX_ENTRIES = 10_000;
+
+function sanitizeSegment(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "default";
+  }
+  return trimmed.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function buildReplayKey(params: { roomToken: string; messageId: string }): string | null {
+  const roomToken = params.roomToken.trim();
+  const messageId = params.messageId.trim();
+  if (!roomToken || !messageId) {
+    return null;
+  }
+  return `${roomToken}:${messageId}`;
+}
+
+export type NextcloudTalkReplayGuardOptions = {
+  stateDir: string;
+  ttlMs?: number;
+  memoryMaxSize?: number;
+  fileMaxEntries?: number;
+  onDiskError?: (error: unknown) => void;
+};
+
+export type NextcloudTalkReplayGuard = {
+  shouldProcessMessage: (params: {
+    accountId: string;
+    roomToken: string;
+    messageId: string;
+  }) => Promise<boolean>;
+};
+
+export function createNextcloudTalkReplayGuard(
+  options: NextcloudTalkReplayGuardOptions,
+): NextcloudTalkReplayGuard {
+  const stateDir = options.stateDir.trim();
+  const persistentDedupe = createPersistentDedupe({
+    ttlMs: options.ttlMs ?? DEFAULT_REPLAY_TTL_MS,
+    memoryMaxSize: options.memoryMaxSize ?? DEFAULT_MEMORY_MAX_SIZE,
+    fileMaxEntries: options.fileMaxEntries ?? DEFAULT_FILE_MAX_ENTRIES,
+    resolveFilePath: (namespace) =>
+      path.join(stateDir, "nextcloud-talk", "replay-dedupe", `${sanitizeSegment(namespace)}.json`),
+  });
+
+  return {
+    shouldProcessMessage: async ({ accountId, roomToken, messageId }) => {
+      const replayKey = buildReplayKey({ roomToken, messageId });
+      if (!replayKey) {
+        return true;
+      }
+      return await persistentDedupe.checkAndRecord(replayKey, {
+        namespace: accountId,
+        onDiskError: options.onDiskError,
+      });
+    },
+  };
+}

package/src/types.ts

@@ -79,6 +79,8 @@ export type NextcloudTalkAccountConfig = {
 export type NextcloudTalkConfig = {
   /** Optional per-account Nextcloud Talk configuration (multi-account). */
   accounts?: Record<string, NextcloudTalkAccountConfig>;
+  /** Optional default account id when multiple accounts are configured. */
+  defaultAccount?: string;
 } & NextcloudTalkAccountConfig;
 
 export type CoreConfig = {
@@ -169,6 +171,9 @@ export type NextcloudTalkWebhookServerOptions = {
   path: string;
   secret: string;
   maxBodyBytes?: number;
+  readBody?: (req: import("node:http").IncomingMessage, maxBodyBytes: number) => Promise<string>;
+  isBackendAllowed?: (backend: string) => boolean;
+  shouldProcessMessage?: (message: NextcloudTalkInboundMessage) => boolean | Promise<boolean>;
   onMessage: (message: NextcloudTalkInboundMessage) => void | Promise<void>;
   onError?: (error: Error) => void;
   abortSignal?: AbortSignal;