@openclaw/nextcloud-talk 2026.3.12 → 2026.5.1-beta.2

package/src/send.ts

@@ -1,15 +1,23 @@
-import { resolveNextcloudTalkAccount } from "./accounts.js";
-import { getNextcloudTalkRuntime } from "./runtime.js";
-import { generateNextcloudTalkSignature } from "./signature.js";
+import { stripNextcloudTalkTargetPrefix } from "./normalize.js";
+import {
+  convertMarkdownTables,
+  fetchWithSsrFGuard,
+  generateNextcloudTalkSignature,
+  getNextcloudTalkRuntime,
+  requireRuntimeConfig,
+  resolveMarkdownTableMode,
+  resolveNextcloudTalkAccount,
+  ssrfPolicyFromPrivateNetworkOptIn,
+} from "./send.runtime.js";
 import type { CoreConfig, NextcloudTalkSendResult } from "./types.js";
 
 type NextcloudTalkSendOpts = {
+  cfg: CoreConfig;
   baseUrl?: string;
   secret?: string;
   accountId?: string;
   replyTo?: string;
   verbose?: boolean;
-  cfg?: CoreConfig;
 };
 
 function resolveCredentials(
@@ -34,34 +42,20 @@ function resolveCredentials(
 }
 
 function normalizeRoomToken(to: string): string {
-  const trimmed = to.trim();
-  if (!trimmed) {
-    throw new Error("Room token is required for Nextcloud Talk sends");
-  }
-
-  let normalized = trimmed;
-  if (normalized.startsWith("nextcloud-talk:")) {
-    normalized = normalized.slice("nextcloud-talk:".length).trim();
-  } else if (normalized.startsWith("nc:")) {
-    normalized = normalized.slice("nc:".length).trim();
-  }
-
-  if (normalized.startsWith("room:")) {
-    normalized = normalized.slice("room:".length).trim();
-  }
-
+  const normalized = stripNextcloudTalkTargetPrefix(to);
   if (!normalized) {
     throw new Error("Room token is required for Nextcloud Talk sends");
   }
   return normalized;
 }
 
-export async function sendMessageNextcloudTalk(
-  to: string,
-  text: string,
-  opts: NextcloudTalkSendOpts = {},
-): Promise<NextcloudTalkSendResult> {
-  const cfg = (opts.cfg ?? getNextcloudTalkRuntime().config.loadConfig()) as CoreConfig;
+function resolveNextcloudTalkSendContext(opts: NextcloudTalkSendOpts): {
+  cfg: CoreConfig;
+  account: ReturnType<typeof resolveNextcloudTalkAccount>;
+  baseUrl: string;
+  secret: string;
+} {
+  const cfg = requireRuntimeConfig(opts.cfg, "Nextcloud Talk send") as CoreConfig;
   const account = resolveNextcloudTalkAccount({
     cfg,
     accountId: opts.accountId,
@@ -70,21 +64,41 @@ export async function sendMessageNextcloudTalk(
     { baseUrl: opts.baseUrl, secret: opts.secret },
     account,
   );
+  return { cfg, account, baseUrl, secret };
+}
+
+function recordNextcloudTalkOutboundActivity(accountId: string): void {
+  try {
+    getNextcloudTalkRuntime().channel.activity.record({
+      channel: "nextcloud-talk",
+      accountId,
+      direction: "outbound",
+    });
+  } catch (error) {
+    if (!(error instanceof Error) || error.message !== "Nextcloud Talk runtime not initialized") {
+      throw error;
+    }
+  }
+}
+
+export async function sendMessageNextcloudTalk(
+  to: string,
+  text: string,
+  opts: NextcloudTalkSendOpts,
+): Promise<NextcloudTalkSendResult> {
+  const { cfg, account, baseUrl, secret } = resolveNextcloudTalkSendContext(opts);
   const roomToken = normalizeRoomToken(to);
 
   if (!text?.trim()) {
     throw new Error("Message must be non-empty for Nextcloud Talk sends");
   }
 
-  const tableMode = getNextcloudTalkRuntime().channel.text.resolveMarkdownTableMode({
+  const tableMode = resolveMarkdownTableMode({
     cfg,
     channel: "nextcloud-talk",
     accountId: account.accountId,
   });
-  const message = getNextcloudTalkRuntime().channel.text.convertMarkdownTables(
-    text.trim(),
-    tableMode,
-  );
+  const message = convertMarkdownTables(text.trim(), tableMode);
 
   const body: Record<string, unknown> = {
     message,
@@ -105,86 +119,83 @@ export async function sendMessageNextcloudTalk(
 
   const url = `${baseUrl}/ocs/v2.php/apps/spreed/api/v1/bot/${roomToken}/message`;
 
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "OCS-APIRequest": "true",
-      "X-Nextcloud-Talk-Bot-Random": random,
-      "X-Nextcloud-Talk-Bot-Signature": signature,
+  const { response, release } = await fetchWithSsrFGuard({
+    url,
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "OCS-APIRequest": "true",
+        "X-Nextcloud-Talk-Bot-Random": random,
+        "X-Nextcloud-Talk-Bot-Signature": signature,
+      },
+      body: bodyStr,
     },
-    body: bodyStr,
+    auditContext: "nextcloud-talk-send",
+    policy: ssrfPolicyFromPrivateNetworkOptIn(account.config),
   });
 
-  if (!response.ok) {
-    const errorBody = await response.text().catch(() => "");
-    const status = response.status;
-    let errorMsg = `Nextcloud Talk send failed (${status})`;
-
-    if (status === 400) {
-      errorMsg = `Nextcloud Talk: bad request - ${errorBody || "invalid message format"}`;
-    } else if (status === 401) {
-      errorMsg = "Nextcloud Talk: authentication failed - check bot secret";
-    } else if (status === 403) {
-      errorMsg = "Nextcloud Talk: forbidden - bot may not have permission in this room";
-    } else if (status === 404) {
-      errorMsg = `Nextcloud Talk: room not found (token=${roomToken})`;
-    } else if (errorBody) {
-      errorMsg = `Nextcloud Talk send failed: ${errorBody}`;
+  try {
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      const status = response.status;
+      let errorMsg = `Nextcloud Talk send failed (${status})`;
+
+      if (status === 400) {
+        errorMsg = `Nextcloud Talk: bad request - ${errorBody || "invalid message format"}`;
+      } else if (status === 401) {
+        errorMsg = "Nextcloud Talk: authentication failed - check bot secret";
+      } else if (status === 403) {
+        errorMsg = "Nextcloud Talk: forbidden - bot may not have permission in this room";
+      } else if (status === 404) {
+        errorMsg = `Nextcloud Talk: room not found (token=${roomToken})`;
+      } else if (errorBody) {
+        errorMsg = `Nextcloud Talk send failed: ${errorBody}`;
+      }
+
+      throw new Error(errorMsg);
     }
 
-    throw new Error(errorMsg);
-  }
-
-  let messageId = "unknown";
-  let timestamp: number | undefined;
-  try {
-    const data = (await response.json()) as {
-      ocs?: {
-        data?: {
-          id?: number | string;
-          timestamp?: number;
+    let messageId = "unknown";
+    let timestamp: number | undefined;
+    try {
+      const data = (await response.json()) as {
+        ocs?: {
+          data?: {
+            id?: number | string;
+            timestamp?: number;
+          };
         };
       };
-    };
-    if (data.ocs?.data?.id != null) {
-      messageId = String(data.ocs.data.id);
+      if (data.ocs?.data?.id != null) {
+        messageId = String(data.ocs.data.id);
+      }
+      if (typeof data.ocs?.data?.timestamp === "number") {
+        timestamp = data.ocs.data.timestamp;
+      }
+    } catch {
+      // Response parsing failed, but message was sent.
     }
-    if (typeof data.ocs?.data?.timestamp === "number") {
-      timestamp = data.ocs.data.timestamp;
-    }
-  } catch {
-    // Response parsing failed, but message was sent.
-  }
 
-  if (opts.verbose) {
-    console.log(`[nextcloud-talk] Sent message ${messageId} to room ${roomToken}`);
-  }
+    if (opts.verbose) {
+      console.log(`[nextcloud-talk] Sent message ${messageId} to room ${roomToken}`);
+    }
 
-  getNextcloudTalkRuntime().channel.activity.record({
-    channel: "nextcloud-talk",
-    accountId: account.accountId,
-    direction: "outbound",
-  });
+    recordNextcloudTalkOutboundActivity(account.accountId);
 
-  return { messageId, roomToken, timestamp };
+    return { messageId, roomToken, timestamp };
+  } finally {
+    await release();
+  }
 }
 
 export async function sendReactionNextcloudTalk(
   roomToken: string,
   messageId: string,
   reaction: string,
-  opts: Omit<NextcloudTalkSendOpts, "replyTo"> = {},
+  opts: Omit<NextcloudTalkSendOpts, "replyTo">,
 ): Promise<{ ok: true }> {
-  const cfg = (opts.cfg ?? getNextcloudTalkRuntime().config.loadConfig()) as CoreConfig;
-  const account = resolveNextcloudTalkAccount({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const { baseUrl, secret } = resolveCredentials(
-    { baseUrl: opts.baseUrl, secret: opts.secret },
-    account,
-  );
+  const { account, baseUrl, secret } = resolveNextcloudTalkSendContext(opts);
   const normalizedToken = normalizeRoomToken(roomToken);
 
   const body = JSON.stringify({ reaction });
@@ -196,21 +207,30 @@ export async function sendReactionNextcloudTalk(
 
   const url = `${baseUrl}/ocs/v2.php/apps/spreed/api/v1/bot/${normalizedToken}/reaction/${messageId}`;
 
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "OCS-APIRequest": "true",
-      "X-Nextcloud-Talk-Bot-Random": random,
-      "X-Nextcloud-Talk-Bot-Signature": signature,
+  const { response, release } = await fetchWithSsrFGuard({
+    url,
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "OCS-APIRequest": "true",
+        "X-Nextcloud-Talk-Bot-Random": random,
+        "X-Nextcloud-Talk-Bot-Signature": signature,
+      },
+      body,
     },
-    body,
+    auditContext: "nextcloud-talk-reaction",
+    policy: ssrfPolicyFromPrivateNetworkOptIn(account.config),
   });
 
-  if (!response.ok) {
-    const errorBody = await response.text().catch(() => "");
-    throw new Error(`Nextcloud Talk reaction failed: ${response.status} ${errorBody}`.trim());
-  }
+  try {
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      throw new Error(`Nextcloud Talk reaction failed: ${response.status} ${errorBody}`.trim());
+    }
 
-  return { ok: true };
+    return { ok: true };
+  } finally {
+    await release();
+  }
 }

package/src/session-route.ts

@@ -0,0 +1,40 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { buildOutboundBaseSessionKey } from "openclaw/plugin-sdk/routing";
+import { stripNextcloudTalkTargetPrefix } from "./normalize.js";
+
+type NextcloudTalkOutboundSessionRouteParams = {
+  cfg: OpenClawConfig;
+  agentId: string;
+  accountId?: string | null;
+  target: string;
+};
+
+export function resolveNextcloudTalkOutboundSessionRoute(
+  params: NextcloudTalkOutboundSessionRouteParams,
+) {
+  const roomId = stripNextcloudTalkTargetPrefix(params.target);
+  if (!roomId) {
+    return null;
+  }
+  const baseSessionKey = buildOutboundBaseSessionKey({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "nextcloud-talk",
+    accountId: params.accountId,
+    peer: {
+      kind: "group",
+      id: roomId,
+    },
+  });
+  return {
+    sessionKey: baseSessionKey,
+    baseSessionKey,
+    peer: {
+      kind: "group" as const,
+      id: roomId,
+    },
+    chatType: "group" as const,
+    from: `nextcloud-talk:room:${roomId}`,
+    to: `nextcloud-talk:${roomId}`,
+  };
+}

package/src/setup-core.ts

@@ -0,0 +1,248 @@
+import type { ChannelSetupAdapter, ChannelSetupInput } from "openclaw/plugin-sdk/channel-setup";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/routing";
+import {
+  applyAccountNameToChannelSection,
+  patchScopedAccountConfig,
+} from "openclaw/plugin-sdk/setup";
+import {
+  createSetupInputPresenceValidator,
+  mergeAllowFromEntries,
+  promptParsedAllowFromForAccount,
+  resolveSetupAccountId,
+  type ChannelSetupDmPolicy,
+  type WizardPrompter,
+} from "openclaw/plugin-sdk/setup-runtime";
+import { formatDocsLink } from "openclaw/plugin-sdk/setup-tools";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+import { resolveDefaultNextcloudTalkAccountId, resolveNextcloudTalkAccount } from "./accounts.js";
+import type { CoreConfig } from "./types.js";
+
+const channel = "nextcloud-talk" as const;
+
+type NextcloudSetupInput = ChannelSetupInput & {
+  baseUrl?: string;
+  secret?: string;
+  secretFile?: string;
+};
+type NextcloudTalkSection = NonNullable<CoreConfig["channels"]>["nextcloud-talk"];
+
+function addWildcardAllowFrom(allowFrom?: Array<string | number> | null): string[] {
+  return mergeAllowFromEntries(allowFrom, ["*"]);
+}
+
+export function normalizeNextcloudTalkBaseUrl(value: string | undefined): string {
+  return value?.trim().replace(/\/+$/, "") ?? "";
+}
+
+export function validateNextcloudTalkBaseUrl(value: string): string | undefined {
+  if (!value) {
+    return "Required";
+  }
+  if (!value.startsWith("http://") && !value.startsWith("https://")) {
+    return "URL must start with http:// or https://";
+  }
+  return undefined;
+}
+
+export function setNextcloudTalkAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+  updates: Record<string, unknown>,
+): CoreConfig {
+  return patchScopedAccountConfig({
+    cfg,
+    channelKey: channel,
+    accountId,
+    patch: updates,
+  }) as CoreConfig;
+}
+
+export function clearNextcloudTalkAccountFields(
+  cfg: CoreConfig,
+  accountId: string,
+  fields: string[],
+): CoreConfig {
+  const section = cfg.channels?.["nextcloud-talk"];
+  if (!section) {
+    return cfg;
+  }
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const nextSection = { ...section } as Record<string, unknown>;
+    for (const field of fields) {
+      delete nextSection[field];
+    }
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        "nextcloud-talk": nextSection as NextcloudTalkSection,
+      },
+    } as CoreConfig;
+  }
+
+  const currentAccount = section.accounts?.[accountId];
+  if (!currentAccount) {
+    return cfg;
+  }
+
+  const nextAccount = { ...currentAccount } as Record<string, unknown>;
+  for (const field of fields) {
+    delete nextAccount[field];
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "nextcloud-talk": {
+        ...section,
+        accounts: {
+          ...section.accounts,
+          [accountId]: nextAccount as NonNullable<typeof section.accounts>[string],
+        },
+      },
+    },
+  } as CoreConfig;
+}
+
+async function promptNextcloudTalkAllowFrom(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<CoreConfig> {
+  return await promptParsedAllowFromForAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    defaultAccountId: params.accountId,
+    prompter: params.prompter,
+    noteTitle: "Nextcloud Talk user id",
+    noteLines: [
+      "1) Check the Nextcloud admin panel for user IDs",
+      "2) Or look at the webhook payload logs when someone messages",
+      "3) User IDs are typically lowercase usernames in Nextcloud",
+      `Docs: ${formatDocsLink("/channels/nextcloud-talk", "nextcloud-talk")}`,
+    ],
+    message: "Nextcloud Talk allowFrom (user id)",
+    placeholder: "username",
+    parseEntries: (raw) => ({
+      entries: raw
+        .split(/[\n,;]+/g)
+        .map(normalizeLowercaseStringOrEmpty)
+        .filter(Boolean),
+    }),
+    getExistingAllowFrom: ({ cfg, accountId }) =>
+      resolveNextcloudTalkAccount({ cfg, accountId }).config.allowFrom ?? [],
+    mergeEntries: ({ existing, parsed }) =>
+      mergeAllowFromEntries(
+        existing.map((value) => normalizeLowercaseStringOrEmpty(String(value))),
+        parsed,
+      ),
+    applyAllowFrom: ({ cfg, accountId, allowFrom }) =>
+      setNextcloudTalkAccountConfig(cfg, accountId, {
+        dmPolicy: "allowlist",
+        allowFrom,
+      }),
+  });
+}
+
+async function promptNextcloudTalkAllowFromForAccount(params: {
+  cfg: OpenClawConfig;
+  prompter: WizardPrompter;
+  accountId?: string;
+}): Promise<OpenClawConfig> {
+  const accountId = resolveSetupAccountId({
+    accountId: params.accountId,
+    defaultAccountId: resolveDefaultNextcloudTalkAccountId(params.cfg as CoreConfig),
+  });
+  return await promptNextcloudTalkAllowFrom({
+    cfg: params.cfg as CoreConfig,
+    prompter: params.prompter,
+    accountId,
+  });
+}
+
+export const nextcloudTalkDmPolicy: ChannelSetupDmPolicy = {
+  label: "Nextcloud Talk",
+  channel,
+  policyKey: "channels.nextcloud-talk.dmPolicy",
+  allowFromKey: "channels.nextcloud-talk.allowFrom",
+  resolveConfigKeys: (cfg, accountId) =>
+    (accountId ?? resolveDefaultNextcloudTalkAccountId(cfg as CoreConfig)) !== DEFAULT_ACCOUNT_ID
+      ? {
+          policyKey: `channels.nextcloud-talk.accounts.${accountId ?? resolveDefaultNextcloudTalkAccountId(cfg as CoreConfig)}.dmPolicy`,
+          allowFromKey: `channels.nextcloud-talk.accounts.${accountId ?? resolveDefaultNextcloudTalkAccountId(cfg as CoreConfig)}.allowFrom`,
+        }
+      : {
+          policyKey: "channels.nextcloud-talk.dmPolicy",
+          allowFromKey: "channels.nextcloud-talk.allowFrom",
+        },
+  getCurrent: (cfg, accountId) =>
+    resolveNextcloudTalkAccount({
+      cfg: cfg as CoreConfig,
+      accountId: accountId ?? resolveDefaultNextcloudTalkAccountId(cfg as CoreConfig),
+    }).config.dmPolicy ?? "pairing",
+  setPolicy: (cfg, policy, accountId) => {
+    const resolvedAccountId = accountId ?? resolveDefaultNextcloudTalkAccountId(cfg as CoreConfig);
+    const resolved = resolveNextcloudTalkAccount({
+      cfg: cfg as CoreConfig,
+      accountId: resolvedAccountId,
+    });
+    return setNextcloudTalkAccountConfig(cfg as CoreConfig, resolvedAccountId, {
+      dmPolicy: policy,
+      ...(policy === "open" ? { allowFrom: addWildcardAllowFrom(resolved.config.allowFrom) } : {}),
+    });
+  },
+  promptAllowFrom: promptNextcloudTalkAllowFromForAccount,
+};
+
+export const nextcloudTalkSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+  applyAccountName: ({ cfg, accountId, name }) =>
+    applyAccountNameToChannelSection({
+      cfg,
+      channelKey: channel,
+      accountId,
+      name,
+    }),
+  validateInput: createSetupInputPresenceValidator({
+    defaultAccountOnlyEnvError:
+      "NEXTCLOUD_TALK_BOT_SECRET can only be used for the default account.",
+    validate: ({ input }) => {
+      const setupInput = input as NextcloudSetupInput;
+      if (!setupInput.useEnv && !setupInput.secret && !setupInput.secretFile) {
+        return "Nextcloud Talk requires bot secret or --secret-file (or --use-env).";
+      }
+      if (!setupInput.baseUrl) {
+        return "Nextcloud Talk requires --base-url.";
+      }
+      return null;
+    },
+  }),
+  applyAccountConfig: ({ cfg, accountId, input }) => {
+    const setupInput = input as NextcloudSetupInput;
+    const namedConfig = applyAccountNameToChannelSection({
+      cfg,
+      channelKey: channel,
+      accountId,
+      name: setupInput.name,
+    });
+    const next = setupInput.useEnv
+      ? clearNextcloudTalkAccountFields(namedConfig as CoreConfig, accountId, [
+          "botSecret",
+          "botSecretFile",
+        ])
+      : namedConfig;
+    const patch = {
+      baseUrl: normalizeNextcloudTalkBaseUrl(setupInput.baseUrl),
+      ...(setupInput.useEnv
+        ? {}
+        : setupInput.secretFile
+          ? { botSecretFile: setupInput.secretFile }
+          : setupInput.secret
+            ? { botSecret: setupInput.secret }
+            : {}),
+    };
+    return setNextcloudTalkAccountConfig(next as CoreConfig, accountId, patch);
+  },
+};