@openclaw/nextcloud-talk 2026.1.29

package/src/format.ts

@@ -0,0 +1,79 @@
+/**
+ * Format utilities for Nextcloud Talk messages.
+ *
+ * Nextcloud Talk supports markdown natively, so most formatting passes through.
+ * This module handles any edge cases or transformations needed.
+ */
+
+/**
+ * Convert markdown to Nextcloud Talk compatible format.
+ * Nextcloud Talk supports standard markdown, so minimal transformation needed.
+ */
+export function markdownToNextcloudTalk(text: string): string {
+  return text.trim();
+}
+
+/**
+ * Escape special characters in text to prevent markdown interpretation.
+ */
+export function escapeNextcloudTalkMarkdown(text: string): string {
+  return text.replace(/([*_`~[\]()#>+\-=|{}!\\])/g, "\\$1");
+}
+
+/**
+ * Format a mention for a Nextcloud user.
+ * Nextcloud Talk uses @user format for mentions.
+ */
+export function formatNextcloudTalkMention(userId: string): string {
+  return `@${userId.replace(/^@/, "")}`;
+}
+
+/**
+ * Format a code block for Nextcloud Talk.
+ */
+export function formatNextcloudTalkCodeBlock(code: string, language?: string): string {
+  const lang = language ?? "";
+  return `\`\`\`${lang}\n${code}\n\`\`\``;
+}
+
+/**
+ * Format inline code for Nextcloud Talk.
+ */
+export function formatNextcloudTalkInlineCode(code: string): string {
+  if (code.includes("`")) {
+    return `\`\` ${code} \`\``;
+  }
+  return `\`${code}\``;
+}
+
+/**
+ * Strip Nextcloud Talk specific formatting from text.
+ * Useful for extracting plain text content.
+ */
+export function stripNextcloudTalkFormatting(text: string): string {
+  return (
+    text
+      .replace(/```[\s\S]*?```/g, "")
+      .replace(/`[^`]+`/g, "")
+      .replace(/\*\*([^*]+)\*\*/g, "$1")
+      .replace(/\*([^*]+)\*/g, "$1")
+      .replace(/_([^_]+)_/g, "$1")
+      .replace(/~~([^~]+)~~/g, "$1")
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      .replace(/\s+/g, " ")
+      .trim()
+  );
+}
+
+/**
+ * Truncate text to a maximum length, preserving word boundaries.
+ */
+export function truncateNextcloudTalkText(text: string, maxLength: number, suffix = "..."): string {
+  if (text.length <= maxLength) return text;
+  const truncated = text.slice(0, maxLength - suffix.length);
+  const lastSpace = truncated.lastIndexOf(" ");
+  if (lastSpace > maxLength * 0.7) {
+    return truncated.slice(0, lastSpace) + suffix;
+  }
+  return truncated + suffix;
+}

package/src/inbound.ts

@@ -0,0 +1,336 @@
+import {
+  logInboundDrop,
+  resolveControlCommandGate,
+  type OpenClawConfig,
+  type RuntimeEnv,
+} from "openclaw/plugin-sdk";
+
+import type { ResolvedNextcloudTalkAccount } from "./accounts.js";
+import {
+  normalizeNextcloudTalkAllowlist,
+  resolveNextcloudTalkAllowlistMatch,
+  resolveNextcloudTalkGroupAllow,
+  resolveNextcloudTalkMentionGate,
+  resolveNextcloudTalkRequireMention,
+  resolveNextcloudTalkRoomMatch,
+} from "./policy.js";
+import { resolveNextcloudTalkRoomKind } from "./room-info.js";
+import { sendMessageNextcloudTalk } from "./send.js";
+import { getNextcloudTalkRuntime } from "./runtime.js";
+import type { CoreConfig, NextcloudTalkInboundMessage } from "./types.js";
+
+const CHANNEL_ID = "nextcloud-talk" as const;
+
+async function deliverNextcloudTalkReply(params: {
+  payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string; replyToId?: string };
+  roomToken: string;
+  accountId: string;
+  statusSink?: (patch: { lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  const { payload, roomToken, accountId, statusSink } = params;
+  const text = payload.text ?? "";
+  const mediaList = payload.mediaUrls?.length
+    ? payload.mediaUrls
+    : payload.mediaUrl
+      ? [payload.mediaUrl]
+      : [];
+
+  if (!text.trim() && mediaList.length === 0) return;
+
+  const mediaBlock = mediaList.length
+    ? mediaList.map((url) => `Attachment: ${url}`).join("\n")
+    : "";
+  const combined = text.trim()
+    ? mediaBlock
+      ? `${text.trim()}\n\n${mediaBlock}`
+      : text.trim()
+    : mediaBlock;
+
+  await sendMessageNextcloudTalk(roomToken, combined, {
+    accountId,
+    replyTo: payload.replyToId,
+  });
+  statusSink?.({ lastOutboundAt: Date.now() });
+}
+
+export async function handleNextcloudTalkInbound(params: {
+  message: NextcloudTalkInboundMessage;
+  account: ResolvedNextcloudTalkAccount;
+  config: CoreConfig;
+  runtime: RuntimeEnv;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  const { message, account, config, runtime, statusSink } = params;
+  const core = getNextcloudTalkRuntime();
+
+  const rawBody = message.text?.trim() ?? "";
+  if (!rawBody) return;
+
+  const roomKind = await resolveNextcloudTalkRoomKind({
+    account,
+    roomToken: message.roomToken,
+    runtime,
+  });
+  const isGroup =
+    roomKind === "direct" ? false : roomKind === "group" ? true : message.isGroupChat;
+  const senderId = message.senderId;
+  const senderName = message.senderName;
+  const roomToken = message.roomToken;
+  const roomName = message.roomName;
+
+  statusSink?.({ lastInboundAt: message.timestamp });
+
+  const dmPolicy = account.config.dmPolicy ?? "pairing";
+  const defaultGroupPolicy = config.channels?.defaults?.groupPolicy;
+  const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+
+  const configAllowFrom = normalizeNextcloudTalkAllowlist(account.config.allowFrom);
+  const configGroupAllowFrom = normalizeNextcloudTalkAllowlist(account.config.groupAllowFrom);
+  const storeAllowFrom = await core.channel.pairing
+    .readAllowFromStore(CHANNEL_ID)
+    .catch(() => []);
+  const storeAllowList = normalizeNextcloudTalkAllowlist(storeAllowFrom);
+
+  const roomMatch = resolveNextcloudTalkRoomMatch({
+    rooms: account.config.rooms,
+    roomToken,
+    roomName,
+  });
+  const roomConfig = roomMatch.roomConfig;
+  if (isGroup && !roomMatch.allowed) {
+    runtime.log?.(`nextcloud-talk: drop room ${roomToken} (not allowlisted)`);
+    return;
+  }
+  if (roomConfig?.enabled === false) {
+    runtime.log?.(`nextcloud-talk: drop room ${roomToken} (disabled)`);
+    return;
+  }
+
+  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,
+    surface: CHANNEL_ID,
+  });
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const senderAllowedForCommands = resolveNextcloudTalkAllowlistMatch({
+    allowFrom: isGroup ? effectiveGroupAllowFrom : effectiveAllowFrom,
+    senderId,
+    senderName,
+  }).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 commandAuthorized = commandGate.commandAuthorized;
+
+  if (isGroup) {
+    const groupAllow = resolveNextcloudTalkGroupAllow({
+      groupPolicy,
+      outerAllowFrom: effectiveGroupAllowFrom,
+      innerAllowFrom: roomAllowFrom,
+      senderId,
+      senderName,
+    });
+    if (!groupAllow.allowed) {
+      runtime.log?.(
+        `nextcloud-talk: drop group sender ${senderId} (policy=${groupPolicy})`,
+      );
+      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,
+        senderName,
+      }).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)}`,
+              );
+            }
+          }
+        }
+        runtime.log?.(
+          `nextcloud-talk: drop DM sender ${senderId} (dmPolicy=${dmPolicy})`,
+        );
+        return;
+      }
+    }
+  }
+
+  if (isGroup && commandGate.shouldBlock) {
+    logInboundDrop({
+      log: (message) => runtime.log?.(message),
+      channel: CHANNEL_ID,
+      reason: "control command (unauthorized)",
+      target: senderId,
+    });
+    return;
+  }
+
+  const mentionRegexes = core.channel.mentions.buildMentionRegexes(
+    config as OpenClawConfig,
+  );
+  const wasMentioned = mentionRegexes.length
+    ? core.channel.mentions.matchesMentionPatterns(rawBody, mentionRegexes)
+    : false;
+  const shouldRequireMention = isGroup
+    ? resolveNextcloudTalkRequireMention({
+        roomConfig,
+        wildcardConfig: roomMatch.wildcardConfig,
+      })
+    : false;
+  const mentionGate = resolveNextcloudTalkMentionGate({
+    isGroup,
+    requireMention: shouldRequireMention,
+    wasMentioned,
+    allowTextCommands,
+    hasControlCommand,
+    commandAuthorized,
+  });
+  if (isGroup && mentionGate.shouldSkip) {
+    runtime.log?.(`nextcloud-talk: drop room ${roomToken} (no mention)`);
+    return;
+  }
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config as OpenClawConfig,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "dm",
+      id: isGroup ? roomToken : senderId,
+    },
+  });
+
+  const fromLabel = isGroup
+    ? `room:${roomName || roomToken}`
+    : senderName || `user:${senderId}`;
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(
+    config as OpenClawConfig,
+  );
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "Nextcloud Talk",
+    from: fromLabel,
+    timestamp: message.timestamp,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: rawBody,
+  });
+
+  const groupSystemPrompt = roomConfig?.systemPrompt?.trim() || undefined;
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: isGroup ? `nextcloud-talk:room:${roomToken}` : `nextcloud-talk:${senderId}`,
+    To: `nextcloud-talk:${roomToken}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: senderName || undefined,
+    SenderId: senderId,
+    GroupSubject: isGroup ? roomName || roomToken : undefined,
+    GroupSystemPrompt: isGroup ? groupSystemPrompt : undefined,
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    WasMentioned: isGroup ? wasMentioned : undefined,
+    MessageSid: message.messageId,
+    Timestamp: message.timestamp,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: `nextcloud-talk:${roomToken}`,
+    CommandAuthorized: commandAuthorized,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      runtime.error?.(`nextcloud-talk: failed updating session meta: ${String(err)}`);
+    },
+  });
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config as OpenClawConfig,
+    dispatcherOptions: {
+      deliver: async (payload) => {
+        await deliverNextcloudTalkReply({
+          payload: payload as {
+            text?: string;
+            mediaUrls?: string[];
+            mediaUrl?: string;
+            replyToId?: string;
+          },
+          roomToken,
+          accountId: account.accountId,
+          statusSink,
+        });
+      },
+      onError: (err, info) => {
+        runtime.error?.(
+          `nextcloud-talk ${info.kind} reply failed: ${String(err)}`,
+        );
+      },
+    },
+    replyOptions: {
+      skillFilter: roomConfig?.skills,
+      disableBlockStreaming:
+        typeof account.config.blockStreaming === "boolean"
+          ? !account.config.blockStreaming
+          : undefined,
+    },
+  });
+}

package/src/monitor.ts

@@ -0,0 +1,246 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+
+import { resolveNextcloudTalkAccount } from "./accounts.js";
+import { handleNextcloudTalkInbound } from "./inbound.js";
+import { getNextcloudTalkRuntime } from "./runtime.js";
+import { extractNextcloudTalkHeaders, verifyNextcloudTalkSignature } from "./signature.js";
+import type {
+  CoreConfig,
+  NextcloudTalkInboundMessage,
+  NextcloudTalkWebhookPayload,
+  NextcloudTalkWebhookServerOptions,
+} from "./types.js";
+
+const DEFAULT_WEBHOOK_PORT = 8788;
+const DEFAULT_WEBHOOK_HOST = "0.0.0.0";
+const DEFAULT_WEBHOOK_PATH = "/nextcloud-talk-webhook";
+const HEALTH_PATH = "/healthz";
+
+function formatError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return typeof err === "string" ? err : JSON.stringify(err);
+}
+
+function parseWebhookPayload(body: string): NextcloudTalkWebhookPayload | null {
+  try {
+    const data = JSON.parse(body);
+    if (
+      !data.type ||
+      !data.actor?.type ||
+      !data.actor?.id ||
+      !data.object?.type ||
+      !data.object?.id ||
+      !data.target?.type ||
+      !data.target?.id
+    ) {
+      return null;
+    }
+    return data as NextcloudTalkWebhookPayload;
+  } catch {
+    return null;
+  }
+}
+
+function payloadToInboundMessage(
+  payload: NextcloudTalkWebhookPayload,
+): NextcloudTalkInboundMessage {
+  // Payload doesn't indicate DM vs room; mark as group and let inbound handler refine.
+  const isGroupChat = true;
+
+  return {
+    messageId: String(payload.object.id),
+    roomToken: payload.target.id,
+    roomName: payload.target.name,
+    senderId: payload.actor.id,
+    senderName: payload.actor.name,
+    text: payload.object.content || payload.object.name || "",
+    mediaType: payload.object.mediaType || "text/plain",
+    timestamp: Date.now(),
+    isGroupChat,
+  };
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+export function createNextcloudTalkWebhookServer(opts: NextcloudTalkWebhookServerOptions): {
+  server: Server;
+  start: () => Promise<void>;
+  stop: () => void;
+} {
+  const { port, host, path, secret, onMessage, onError, abortSignal } = opts;
+
+  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.url === HEALTH_PATH) {
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end("ok");
+      return;
+    }
+
+    if (req.url !== path || req.method !== "POST") {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+
+    try {
+      const body = await readBody(req);
+
+      const headers = extractNextcloudTalkHeaders(
+        req.headers as Record<string, string | string[] | undefined>,
+      );
+      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,
+        body,
+        secret,
+      });
+
+      if (!isValid) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid signature" }));
+        return;
+      }
+
+      const payload = parseWebhookPayload(body);
+      if (!payload) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid payload format" }));
+        return;
+      }
+
+      if (payload.type !== "Create") {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+
+      const message = payloadToInboundMessage(payload);
+
+      res.writeHead(200);
+      res.end();
+
+      try {
+        await onMessage(message);
+      } catch (err) {
+        onError?.(err instanceof Error ? err : new Error(formatError(err)));
+      }
+    } catch (err) {
+      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" }));
+      }
+    }
+  });
+
+  const start = (): Promise<void> => {
+    return new Promise((resolve) => {
+      server.listen(port, host, () => resolve());
+    });
+  };
+
+  const stop = () => {
+    server.close();
+  };
+
+  if (abortSignal) {
+    abortSignal.addEventListener("abort", stop, { once: true });
+  }
+
+  return { server, start, stop };
+}
+
+export type NextcloudTalkMonitorOptions = {
+  accountId?: string;
+  config?: CoreConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  onMessage?: (message: NextcloudTalkInboundMessage) => void | Promise<void>;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export async function monitorNextcloudTalkProvider(
+  opts: NextcloudTalkMonitorOptions,
+): Promise<{ stop: () => void }> {
+  const core = getNextcloudTalkRuntime();
+  const cfg = opts.config ?? (core.config.loadConfig() as CoreConfig);
+  const account = resolveNextcloudTalkAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const runtime: RuntimeEnv = opts.runtime ?? {
+    log: (message: string) => core.logging.getChildLogger().info(message),
+    error: (message: string) => core.logging.getChildLogger().error(message),
+    exit: () => {
+      throw new Error("Runtime exit not available");
+    },
+  };
+
+  if (!account.secret) {
+    throw new Error(`Nextcloud Talk bot secret not configured for account "${account.accountId}"`);
+  }
+
+  const port = account.config.webhookPort ?? DEFAULT_WEBHOOK_PORT;
+  const host = account.config.webhookHost ?? DEFAULT_WEBHOOK_HOST;
+  const path = account.config.webhookPath ?? DEFAULT_WEBHOOK_PATH;
+
+  const logger = core.logging.getChildLogger({
+    channel: "nextcloud-talk",
+    accountId: account.accountId,
+  });
+
+  const { start, stop } = createNextcloudTalkWebhookServer({
+    port,
+    host,
+    path,
+    secret: account.secret,
+    onMessage: async (message) => {
+      core.channel.activity.record({
+        channel: "nextcloud-talk",
+        accountId: account.accountId,
+        direction: "inbound",
+        at: message.timestamp,
+      });
+      if (opts.onMessage) {
+        await opts.onMessage(message);
+        return;
+      }
+      await handleNextcloudTalkInbound({
+        message,
+        account,
+        config: cfg,
+        runtime,
+        statusSink: opts.statusSink,
+      });
+    },
+    onError: (error) => {
+      logger.error(`[nextcloud-talk:${account.accountId}] webhook error: ${error.message}`);
+    },
+    abortSignal: opts.abortSignal,
+  });
+
+  await start();
+
+  const publicUrl =
+    account.config.webhookPublicUrl ??
+    `http://${host === "0.0.0.0" ? "localhost" : host}:${port}${path}`;
+  logger.info(`[nextcloud-talk:${account.accountId}] webhook listening on ${publicUrl}`);
+
+  return { stop };
+}

package/src/normalize.ts

@@ -0,0 +1,31 @@
+export function normalizeNextcloudTalkMessagingTarget(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+
+  let normalized = trimmed;
+
+  if (normalized.startsWith("nextcloud-talk:")) {
+    normalized = normalized.slice("nextcloud-talk:".length).trim();
+  } else if (normalized.startsWith("nc-talk:")) {
+    normalized = normalized.slice("nc-talk:".length).trim();
+  } else if (normalized.startsWith("nc:")) {
+    normalized = normalized.slice("nc:".length).trim();
+  }
+
+  if (normalized.startsWith("room:")) {
+    normalized = normalized.slice("room:".length).trim();
+  }
+
+  if (!normalized) return undefined;
+
+  return `nextcloud-talk:${normalized}`.toLowerCase();
+}
+
+export function looksLikeNextcloudTalkTargetId(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) return false;
+
+  if (/^(nextcloud-talk|nc-talk|nc):/i.test(trimmed)) return true;
+
+  return /^[a-z0-9]{8,}$/i.test(trimmed);
+}