@openclaw/nextcloud-talk 2026.1.29

package/src/onboarding.ts

@@ -0,0 +1,341 @@
+import {
+  addWildcardAllowFrom,
+  formatDocsLink,
+  promptAccountId,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type ChannelOnboardingAdapter,
+  type ChannelOnboardingDmPolicy,
+  type WizardPrompter,
+} from "openclaw/plugin-sdk";
+
+import {
+  listNextcloudTalkAccountIds,
+  resolveDefaultNextcloudTalkAccountId,
+  resolveNextcloudTalkAccount,
+} from "./accounts.js";
+import type { CoreConfig, DmPolicy } from "./types.js";
+
+const channel = "nextcloud-talk" as const;
+
+function setNextcloudTalkDmPolicy(cfg: CoreConfig, dmPolicy: DmPolicy): CoreConfig {
+  const existingConfig = cfg.channels?.["nextcloud-talk"];
+  const existingAllowFrom: string[] = (existingConfig?.allowFrom ?? []).map((x) => String(x));
+  const allowFrom: string[] =
+    dmPolicy === "open" ? (addWildcardAllowFrom(existingAllowFrom) as string[]) : existingAllowFrom;
+
+  const newNextcloudTalkConfig = {
+    ...existingConfig,
+    dmPolicy,
+    allowFrom,
+  };
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "nextcloud-talk": newNextcloudTalkConfig,
+    },
+  } as CoreConfig;
+}
+
+async function noteNextcloudTalkSecretHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "1) SSH into your Nextcloud server",
+      '2) Run: ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction',
+      "3) Copy the shared secret you used in the command",
+      "4) Enable the bot in your Nextcloud Talk room settings",
+      "Tip: you can also set NEXTCLOUD_TALK_BOT_SECRET in your env.",
+      `Docs: ${formatDocsLink("/channels/nextcloud-talk", "channels/nextcloud-talk")}`,
+    ].join("\n"),
+    "Nextcloud Talk bot setup",
+  );
+}
+
+async function noteNextcloudTalkUserIdHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "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", "channels/nextcloud-talk")}`,
+    ].join("\n"),
+    "Nextcloud Talk user id",
+  );
+}
+
+async function promptNextcloudTalkAllowFrom(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<CoreConfig> {
+  const { cfg, prompter, accountId } = params;
+  const resolved = resolveNextcloudTalkAccount({ cfg, accountId });
+  const existingAllowFrom = resolved.config.allowFrom ?? [];
+  await noteNextcloudTalkUserIdHelp(prompter);
+
+  const parseInput = (value: string) =>
+    value
+      .split(/[\n,;]+/g)
+      .map((entry) => entry.trim().toLowerCase())
+      .filter(Boolean);
+
+  let resolvedIds: string[] = [];
+  while (resolvedIds.length === 0) {
+    const entry = await prompter.text({
+      message: "Nextcloud Talk allowFrom (user id)",
+      placeholder: "username",
+      initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    });
+    resolvedIds = parseInput(String(entry));
+    if (resolvedIds.length === 0) {
+      await prompter.note("Please enter at least one valid user ID.", "Nextcloud Talk allowlist");
+    }
+  }
+
+  const merged = [
+    ...existingAllowFrom.map((item) => String(item).trim().toLowerCase()).filter(Boolean),
+    ...resolvedIds,
+  ];
+  const unique = [...new Set(merged)];
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        "nextcloud-talk": {
+          ...cfg.channels?.["nextcloud-talk"],
+          enabled: true,
+          dmPolicy: "allowlist",
+          allowFrom: unique,
+        },
+      },
+    };
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "nextcloud-talk": {
+        ...cfg.channels?.["nextcloud-talk"],
+        enabled: true,
+        accounts: {
+          ...cfg.channels?.["nextcloud-talk"]?.accounts,
+          [accountId]: {
+            ...cfg.channels?.["nextcloud-talk"]?.accounts?.[accountId],
+            enabled: cfg.channels?.["nextcloud-talk"]?.accounts?.[accountId]?.enabled ?? true,
+            dmPolicy: "allowlist",
+            allowFrom: unique,
+          },
+        },
+      },
+    },
+  };
+}
+
+async function promptNextcloudTalkAllowFromForAccount(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  accountId?: string;
+}): Promise<CoreConfig> {
+  const accountId =
+    params.accountId && normalizeAccountId(params.accountId)
+      ? (normalizeAccountId(params.accountId) ?? DEFAULT_ACCOUNT_ID)
+      : resolveDefaultNextcloudTalkAccountId(params.cfg);
+  return promptNextcloudTalkAllowFrom({
+    cfg: params.cfg,
+    prompter: params.prompter,
+    accountId,
+  });
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "Nextcloud Talk",
+  channel,
+  policyKey: "channels.nextcloud-talk.dmPolicy",
+  allowFromKey: "channels.nextcloud-talk.allowFrom",
+  getCurrent: (cfg) => cfg.channels?.["nextcloud-talk"]?.dmPolicy ?? "pairing",
+  setPolicy: (cfg, policy) => setNextcloudTalkDmPolicy(cfg as CoreConfig, policy as DmPolicy),
+  promptAllowFrom: promptNextcloudTalkAllowFromForAccount,
+};
+
+export const nextcloudTalkOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const configured = listNextcloudTalkAccountIds(cfg as CoreConfig).some((accountId) => {
+      const account = resolveNextcloudTalkAccount({ cfg: cfg as CoreConfig, accountId });
+      return Boolean(account.secret && account.baseUrl);
+    });
+    return {
+      channel,
+      configured,
+      statusLines: [`Nextcloud Talk: ${configured ? "configured" : "needs setup"}`],
+      selectionHint: configured ? "configured" : "self-hosted chat",
+      quickstartScore: configured ? 1 : 5,
+    };
+  },
+  configure: async ({
+    cfg,
+    prompter,
+    accountOverrides,
+    shouldPromptAccountIds,
+    forceAllowFrom,
+  }) => {
+    const nextcloudTalkOverride = accountOverrides["nextcloud-talk"]?.trim();
+    const defaultAccountId = resolveDefaultNextcloudTalkAccountId(cfg as CoreConfig);
+    let accountId = nextcloudTalkOverride
+      ? normalizeAccountId(nextcloudTalkOverride)
+      : defaultAccountId;
+
+    if (shouldPromptAccountIds && !nextcloudTalkOverride) {
+      accountId = await promptAccountId({
+        cfg: cfg as CoreConfig,
+        prompter,
+        label: "Nextcloud Talk",
+        currentId: accountId,
+        listAccountIds: listNextcloudTalkAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg as CoreConfig;
+    const resolvedAccount = resolveNextcloudTalkAccount({
+      cfg: next,
+      accountId,
+    });
+    const accountConfigured = Boolean(resolvedAccount.secret && resolvedAccount.baseUrl);
+    const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+    const canUseEnv = allowEnv && Boolean(process.env.NEXTCLOUD_TALK_BOT_SECRET?.trim());
+    const hasConfigSecret = Boolean(
+      resolvedAccount.config.botSecret || resolvedAccount.config.botSecretFile,
+    );
+
+    let baseUrl = resolvedAccount.baseUrl;
+    if (!baseUrl) {
+      baseUrl = String(
+        await prompter.text({
+          message: "Enter Nextcloud instance URL (e.g., https://cloud.example.com)",
+          validate: (value) => {
+            const v = String(value ?? "").trim();
+            if (!v) return "Required";
+            if (!v.startsWith("http://") && !v.startsWith("https://")) {
+              return "URL must start with http:// or https://";
+            }
+            return undefined;
+          },
+        }),
+      ).trim();
+    }
+
+    let secret: string | null = null;
+    if (!accountConfigured) {
+      await noteNextcloudTalkSecretHelp(prompter);
+    }
+
+    if (canUseEnv && !resolvedAccount.config.botSecret) {
+      const keepEnv = await prompter.confirm({
+        message: "NEXTCLOUD_TALK_BOT_SECRET detected. Use env var?",
+        initialValue: true,
+      });
+      if (keepEnv) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            "nextcloud-talk": {
+              ...next.channels?.["nextcloud-talk"],
+              enabled: true,
+              baseUrl,
+            },
+          },
+        };
+      } else {
+        secret = String(
+          await prompter.text({
+            message: "Enter Nextcloud Talk bot secret",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else if (hasConfigSecret) {
+      const keep = await prompter.confirm({
+        message: "Nextcloud Talk secret already configured. Keep it?",
+        initialValue: true,
+      });
+      if (!keep) {
+        secret = String(
+          await prompter.text({
+            message: "Enter Nextcloud Talk bot secret",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else {
+      secret = String(
+        await prompter.text({
+          message: "Enter Nextcloud Talk bot secret",
+          validate: (value) => (value?.trim() ? undefined : "Required"),
+        }),
+      ).trim();
+    }
+
+    if (secret || baseUrl !== resolvedAccount.baseUrl) {
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            "nextcloud-talk": {
+              ...next.channels?.["nextcloud-talk"],
+              enabled: true,
+              baseUrl,
+              ...(secret ? { botSecret: secret } : {}),
+            },
+          },
+        };
+      } else {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            "nextcloud-talk": {
+              ...next.channels?.["nextcloud-talk"],
+              enabled: true,
+              accounts: {
+                ...next.channels?.["nextcloud-talk"]?.accounts,
+                [accountId]: {
+                  ...next.channels?.["nextcloud-talk"]?.accounts?.[accountId],
+                  enabled: next.channels?.["nextcloud-talk"]?.accounts?.[accountId]?.enabled ?? true,
+                  baseUrl,
+                  ...(secret ? { botSecret: secret } : {}),
+                },
+              },
+            },
+          },
+        };
+      }
+    }
+
+    if (forceAllowFrom) {
+      next = await promptNextcloudTalkAllowFrom({
+        cfg: next,
+        prompter,
+        accountId,
+      });
+    }
+
+    return { cfg: next, accountId };
+  },
+  dmPolicy,
+  disable: (cfg) => ({
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      "nextcloud-talk": { ...cfg.channels?.["nextcloud-talk"], enabled: false },
+    },
+  }),
+};

package/src/policy.ts

@@ -0,0 +1,175 @@
+import type { AllowlistMatch, ChannelGroupContext, GroupPolicy, GroupToolPolicyConfig } from "openclaw/plugin-sdk";
+import {
+  buildChannelKeyCandidates,
+  normalizeChannelSlug,
+  resolveChannelEntryMatchWithFallback,
+  resolveMentionGatingWithBypass,
+  resolveNestedAllowlistDecision,
+} from "openclaw/plugin-sdk";
+
+import type { NextcloudTalkRoomConfig } from "./types.js";
+
+function normalizeAllowEntry(raw: string): string {
+  return raw.trim().toLowerCase().replace(/^(nextcloud-talk|nc-talk|nc):/i, "");
+}
+
+export function normalizeNextcloudTalkAllowlist(
+  values: Array<string | number> | undefined,
+): string[] {
+  return (values ?? []).map((value) => normalizeAllowEntry(String(value))).filter(Boolean);
+}
+
+export function resolveNextcloudTalkAllowlistMatch(params: {
+  allowFrom: Array<string | number> | undefined;
+  senderId: string;
+  senderName?: string | null;
+}): AllowlistMatch<"wildcard" | "id" | "name"> {
+  const allowFrom = normalizeNextcloudTalkAllowlist(params.allowFrom);
+  if (allowFrom.length === 0) return { allowed: false };
+  if (allowFrom.includes("*")) {
+    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
+  }
+  const senderId = normalizeAllowEntry(params.senderId);
+  if (allowFrom.includes(senderId)) {
+    return { allowed: true, matchKey: senderId, matchSource: "id" };
+  }
+  const senderName = params.senderName ? normalizeAllowEntry(params.senderName) : "";
+  if (senderName && allowFrom.includes(senderName)) {
+    return { allowed: true, matchKey: senderName, matchSource: "name" };
+  }
+  return { allowed: false };
+}
+
+export type NextcloudTalkRoomMatch = {
+  roomConfig?: NextcloudTalkRoomConfig;
+  wildcardConfig?: NextcloudTalkRoomConfig;
+  roomKey?: string;
+  matchSource?: "direct" | "parent" | "wildcard";
+  allowed: boolean;
+  allowlistConfigured: boolean;
+};
+
+export function resolveNextcloudTalkRoomMatch(params: {
+  rooms?: Record<string, NextcloudTalkRoomConfig>;
+  roomToken: string;
+  roomName?: string | null;
+}): NextcloudTalkRoomMatch {
+  const rooms = params.rooms ?? {};
+  const allowlistConfigured = Object.keys(rooms).length > 0;
+  const roomName = params.roomName?.trim() || undefined;
+  const roomCandidates = buildChannelKeyCandidates(
+    params.roomToken,
+    roomName,
+    roomName ? normalizeChannelSlug(roomName) : undefined,
+  );
+  const match = resolveChannelEntryMatchWithFallback({
+    entries: rooms,
+    keys: roomCandidates,
+    wildcardKey: "*",
+    normalizeKey: normalizeChannelSlug,
+  });
+  const roomConfig = match.entry;
+  const allowed = resolveNestedAllowlistDecision({
+    outerConfigured: allowlistConfigured,
+    outerMatched: Boolean(roomConfig),
+    innerConfigured: false,
+    innerMatched: false,
+  });
+
+  return {
+    roomConfig,
+    wildcardConfig: match.wildcardEntry,
+    roomKey: match.matchKey ?? match.key,
+    matchSource: match.matchSource,
+    allowed,
+    allowlistConfigured,
+  };
+}
+
+export function resolveNextcloudTalkGroupToolPolicy(
+  params: ChannelGroupContext,
+): GroupToolPolicyConfig | undefined {
+  const cfg = params.cfg as { channels?: { "nextcloud-talk"?: { rooms?: Record<string, NextcloudTalkRoomConfig> } } };
+  const roomToken = params.groupId?.trim();
+  if (!roomToken) return undefined;
+  const roomName = params.groupChannel?.trim() || undefined;
+  const match = resolveNextcloudTalkRoomMatch({
+    rooms: cfg.channels?.["nextcloud-talk"]?.rooms,
+    roomToken,
+    roomName,
+  });
+  return match.roomConfig?.tools ?? match.wildcardConfig?.tools;
+}
+
+export function resolveNextcloudTalkRequireMention(params: {
+  roomConfig?: NextcloudTalkRoomConfig;
+  wildcardConfig?: NextcloudTalkRoomConfig;
+}): boolean {
+  if (typeof params.roomConfig?.requireMention === "boolean") {
+    return params.roomConfig.requireMention;
+  }
+  if (typeof params.wildcardConfig?.requireMention === "boolean") {
+    return params.wildcardConfig.requireMention;
+  }
+  return true;
+}
+
+export function resolveNextcloudTalkGroupAllow(params: {
+  groupPolicy: GroupPolicy;
+  outerAllowFrom: Array<string | number> | undefined;
+  innerAllowFrom: Array<string | number> | undefined;
+  senderId: string;
+  senderName?: string | null;
+}): { allowed: boolean; outerMatch: AllowlistMatch; innerMatch: AllowlistMatch } {
+  if (params.groupPolicy === "disabled") {
+    return { allowed: false, outerMatch: { allowed: false }, innerMatch: { allowed: false } };
+  }
+  if (params.groupPolicy === "open") {
+    return { allowed: true, outerMatch: { allowed: true }, innerMatch: { allowed: true } };
+  }
+
+  const outerAllow = normalizeNextcloudTalkAllowlist(params.outerAllowFrom);
+  const innerAllow = normalizeNextcloudTalkAllowlist(params.innerAllowFrom);
+  if (outerAllow.length === 0 && innerAllow.length === 0) {
+    return { allowed: false, outerMatch: { allowed: false }, innerMatch: { allowed: false } };
+  }
+
+  const outerMatch = resolveNextcloudTalkAllowlistMatch({
+    allowFrom: params.outerAllowFrom,
+    senderId: params.senderId,
+    senderName: params.senderName,
+  });
+  const innerMatch = resolveNextcloudTalkAllowlistMatch({
+    allowFrom: params.innerAllowFrom,
+    senderId: params.senderId,
+    senderName: params.senderName,
+  });
+  const allowed = resolveNestedAllowlistDecision({
+    outerConfigured: outerAllow.length > 0 || innerAllow.length > 0,
+    outerMatched: outerAllow.length > 0 ? outerMatch.allowed : true,
+    innerConfigured: innerAllow.length > 0,
+    innerMatched: innerMatch.allowed,
+  });
+
+  return { allowed, outerMatch, innerMatch };
+}
+
+export function resolveNextcloudTalkMentionGate(params: {
+  isGroup: boolean;
+  requireMention: boolean;
+  wasMentioned: boolean;
+  allowTextCommands: boolean;
+  hasControlCommand: boolean;
+  commandAuthorized: boolean;
+}): { shouldSkip: boolean; shouldBypassMention: boolean } {
+  const result = resolveMentionGatingWithBypass({
+    isGroup: params.isGroup,
+    requireMention: params.requireMention,
+    canDetectMention: true,
+    wasMentioned: params.wasMentioned,
+    allowTextCommands: params.allowTextCommands,
+    hasControlCommand: params.hasControlCommand,
+    commandAuthorized: params.commandAuthorized,
+  });
+  return { shouldSkip: result.shouldSkip, shouldBypassMention: result.shouldBypassMention };
+}

package/src/room-info.ts

@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+
+import type { ResolvedNextcloudTalkAccount } from "./accounts.js";
+
+const ROOM_CACHE_TTL_MS = 5 * 60 * 1000;
+const ROOM_CACHE_ERROR_TTL_MS = 30 * 1000;
+
+const roomCache = new Map<
+  string,
+  { kind?: "direct" | "group"; fetchedAt: number; error?: string }
+>();
+
+function resolveRoomCacheKey(params: { accountId: string; roomToken: string }) {
+  return `${params.accountId}:${params.roomToken}`;
+}
+
+function readApiPassword(params: {
+  apiPassword?: string;
+  apiPasswordFile?: string;
+}): string | undefined {
+  if (params.apiPassword?.trim()) return params.apiPassword.trim();
+  if (!params.apiPasswordFile) return undefined;
+  try {
+    const value = readFileSync(params.apiPasswordFile, "utf-8").trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function coerceRoomType(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function resolveRoomKindFromType(type: number | undefined): "direct" | "group" | undefined {
+  if (!type) return undefined;
+  if (type === 1 || type === 5 || type === 6) return "direct";
+  return "group";
+}
+
+export async function resolveNextcloudTalkRoomKind(params: {
+  account: ResolvedNextcloudTalkAccount;
+  roomToken: string;
+  runtime?: RuntimeEnv;
+}): Promise<"direct" | "group" | undefined> {
+  const { account, roomToken, runtime } = params;
+  const key = resolveRoomCacheKey({ accountId: account.accountId, roomToken });
+  const cached = roomCache.get(key);
+  if (cached) {
+    const age = Date.now() - cached.fetchedAt;
+    if (cached.kind && age < ROOM_CACHE_TTL_MS) return cached.kind;
+    if (cached.error && age < ROOM_CACHE_ERROR_TTL_MS) return undefined;
+  }
+
+  const apiUser = account.config.apiUser?.trim();
+  const apiPassword = readApiPassword({
+    apiPassword: account.config.apiPassword,
+    apiPasswordFile: account.config.apiPasswordFile,
+  });
+  if (!apiUser || !apiPassword) return undefined;
+
+  const baseUrl = account.baseUrl?.trim();
+  if (!baseUrl) return undefined;
+
+  const url = `${baseUrl}/ocs/v2.php/apps/spreed/api/v4/room/${roomToken}`;
+  const auth = Buffer.from(`${apiUser}:${apiPassword}`, "utf-8").toString("base64");
+
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Basic ${auth}`,
+        "OCS-APIRequest": "true",
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      roomCache.set(key, {
+        fetchedAt: Date.now(),
+        error: `status:${response.status}`,
+      });
+      runtime?.log?.(
+        `nextcloud-talk: room lookup failed (${response.status}) token=${roomToken}`,
+      );
+      return undefined;
+    }
+
+    const payload = (await response.json()) as {
+      ocs?: { data?: { type?: number | string } };
+    };
+    const type = coerceRoomType(payload.ocs?.data?.type);
+    const kind = resolveRoomKindFromType(type);
+    roomCache.set(key, { fetchedAt: Date.now(), kind });
+    return kind;
+  } catch (err) {
+    roomCache.set(key, {
+      fetchedAt: Date.now(),
+      error: err instanceof Error ? err.message : String(err),
+    });
+    runtime?.error?.(`nextcloud-talk: room lookup error: ${String(err)}`);
+    return undefined;
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setNextcloudTalkRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getNextcloudTalkRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Nextcloud Talk runtime not initialized");
+  }
+  return runtime;
+}