@kodelyth/nextcloud-talk 2026.5.39 → 2026.5.42

package/src/send.cfg-threading.test.ts

@@ -0,0 +1,359 @@
+import { verifyChannelMessageAdapterCapabilityProofs } from "klaw/plugin-sdk/channel-message";
+import {
+  createSendCfgThreadingRuntime,
+  expectProvidedCfgSkipsRuntimeLoad,
+} from "klaw/plugin-sdk/channel-test-helpers";
+import type { KlawConfig as CoreConfig } from "klaw/plugin-sdk/config-contracts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const hoisted = vi.hoisted(() => ({
+  loadConfig: vi.fn(),
+  resolveMarkdownTableMode: vi.fn(() => "preserve"),
+  convertMarkdownTables: vi.fn((text: string) => text),
+  record: vi.fn(),
+  resolveNextcloudTalkAccount: vi.fn(),
+  ssrfPolicyFromPrivateNetworkOptIn: vi.fn(() => undefined),
+  generateNextcloudTalkSignature: vi.fn(() => ({
+    random: "r",
+    signature: "s",
+  })),
+  mockFetchGuard: vi.fn(),
+}));
+
+vi.mock("./send.runtime.js", () => {
+  return {
+    convertMarkdownTables: hoisted.convertMarkdownTables,
+    fetchWithSsrFGuard: hoisted.mockFetchGuard,
+    generateNextcloudTalkSignature: hoisted.generateNextcloudTalkSignature,
+    getNextcloudTalkRuntime: () => createSendCfgThreadingRuntime(hoisted),
+    requireRuntimeConfig: (cfg: unknown, context: string) => {
+      if (cfg) {
+        return cfg;
+      }
+      throw new Error(`${context} requires a resolved runtime config`);
+    },
+    resolveNextcloudTalkAccount: hoisted.resolveNextcloudTalkAccount,
+    resolveMarkdownTableMode: hoisted.resolveMarkdownTableMode,
+    ssrfPolicyFromPrivateNetworkOptIn: hoisted.ssrfPolicyFromPrivateNetworkOptIn,
+  };
+});
+
+const { nextcloudTalkMessageAdapter } = await import("./message-adapter.js");
+const { sendMessageNextcloudTalk, sendReactionNextcloudTalk } = await import("./send.js");
+
+function expectProvidedMessageCfgThreading(cfg: unknown): void {
+  expectProvidedCfgSkipsRuntimeLoad({
+    loadConfig: hoisted.loadConfig,
+    resolveAccount: hoisted.resolveNextcloudTalkAccount,
+    cfg,
+    accountId: "work",
+  });
+  expect(hoisted.resolveMarkdownTableMode).toHaveBeenCalledWith({
+    cfg,
+    channel: "nextcloud-talk",
+    accountId: "default",
+  });
+  expect(hoisted.convertMarkdownTables).toHaveBeenCalledWith("hello", "preserve");
+}
+
+describe("nextcloud-talk send cfg threading", () => {
+  const fetchMock = vi.fn<typeof fetch>();
+  const fixedSentAt = 1_800_000_000_000;
+  const defaultAccount = {
+    accountId: "default",
+    baseUrl: "https://nextcloud.example.com",
+    secret: "secret-value",
+  };
+
+  function mockNextcloudMessageResponse(messageId: number, timestamp: number): void {
+    fetchMock.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          ocs: { data: { id: messageId, timestamp } },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+  }
+
+  beforeEach(() => {
+    vi.setSystemTime(fixedSentAt);
+    vi.stubGlobal("fetch", fetchMock);
+    // Route the SSRF guard mock through the global fetch mock.
+    hoisted.mockFetchGuard.mockImplementation(async (p: { url: string; init?: RequestInit }) => {
+      const response = await globalThis.fetch(p.url, p.init);
+      return { response, release: async () => {}, finalUrl: p.url };
+    });
+    hoisted.loadConfig.mockReset();
+    hoisted.resolveMarkdownTableMode.mockClear();
+    hoisted.convertMarkdownTables.mockClear();
+    hoisted.record.mockReset();
+    hoisted.ssrfPolicyFromPrivateNetworkOptIn.mockClear();
+    hoisted.generateNextcloudTalkSignature.mockClear();
+    hoisted.resolveNextcloudTalkAccount.mockReset();
+    hoisted.resolveNextcloudTalkAccount.mockReturnValue(defaultAccount);
+  });
+
+  afterEach(() => {
+    fetchMock.mockReset();
+    hoisted.mockFetchGuard.mockReset();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("uses provided cfg for sendMessage and skips runtime loadConfig", async () => {
+    const cfg = { source: "provided" } as const;
+    mockNextcloudMessageResponse(12345, 1_706_000_000);
+
+    const result = await sendMessageNextcloudTalk("room:abc123", "hello", {
+      cfg,
+      accountId: "work",
+    });
+
+    expectProvidedMessageCfgThreading(cfg);
+    expect(hoisted.record).toHaveBeenCalledWith({
+      channel: "nextcloud-talk",
+      accountId: "default",
+      direction: "outbound",
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({
+      messageId: "12345",
+      receipt: {
+        platformMessageIds: ["12345"],
+        primaryPlatformMessageId: "12345",
+        parts: [
+          {
+            index: 0,
+            kind: "text",
+            platformMessageId: "12345",
+            raw: {
+              channel: "nextcloud-talk",
+              conversationId: "abc123",
+              messageId: "12345",
+            },
+          },
+        ],
+        raw: [
+          {
+            channel: "nextcloud-talk",
+            conversationId: "abc123",
+            messageId: "12345",
+          },
+        ],
+        sentAt: fixedSentAt,
+      },
+      roomToken: "abc123",
+      timestamp: 1_706_000_000,
+    });
+  });
+
+  it("sends with provided cfg even when the runtime store is not initialized", async () => {
+    const cfg = { source: "provided" } as const;
+    hoisted.record.mockImplementation(() => {
+      throw new Error("Nextcloud Talk runtime not initialized");
+    });
+    mockNextcloudMessageResponse(12346, 1_706_000_001);
+
+    const result = await sendMessageNextcloudTalk("room:abc123", "hello", {
+      cfg,
+      accountId: "work",
+    });
+
+    expectProvidedMessageCfgThreading(cfg);
+    expect(result).toEqual({
+      messageId: "12346",
+      receipt: {
+        platformMessageIds: ["12346"],
+        primaryPlatformMessageId: "12346",
+        parts: [
+          {
+            index: 0,
+            kind: "text",
+            platformMessageId: "12346",
+            raw: {
+              channel: "nextcloud-talk",
+              conversationId: "abc123",
+              messageId: "12346",
+            },
+          },
+        ],
+        raw: [
+          {
+            channel: "nextcloud-talk",
+            conversationId: "abc123",
+            messageId: "12346",
+          },
+        ],
+        sentAt: fixedSentAt,
+      },
+      roomToken: "abc123",
+      timestamp: 1_706_000_001,
+    });
+  });
+
+  it("preserves reply ids in receipts", async () => {
+    const cfg = { source: "provided" } as const;
+    mockNextcloudMessageResponse(12347, 1_706_000_002);
+
+    const result = await sendMessageNextcloudTalk("room:abc123", "hello", {
+      cfg,
+      accountId: "work",
+      replyTo: "parent-1",
+    });
+
+    expect(result.receipt).toEqual({
+      platformMessageIds: ["12347"],
+      primaryPlatformMessageId: "12347",
+      replyToId: "parent-1",
+      parts: [
+        {
+          index: 0,
+          kind: "text",
+          replyToId: "parent-1",
+          platformMessageId: "12347",
+          raw: {
+            channel: "nextcloud-talk",
+            conversationId: "abc123",
+            messageId: "12347",
+          },
+        },
+      ],
+      raw: [
+        {
+          channel: "nextcloud-talk",
+          conversationId: "abc123",
+          messageId: "12347",
+        },
+      ],
+      sentAt: fixedSentAt,
+    });
+  });
+
+  it("explains that 401 sends can mean the response feature is missing", async () => {
+    const cfg = { source: "provided" } as const;
+    fetchMock.mockResolvedValueOnce(new Response("{}", { status: 401 }));
+
+    await expect(
+      sendMessageNextcloudTalk("room:abc123", "hello", {
+        cfg,
+        accountId: "work",
+      }),
+    ).rejects.toThrow("--feature response");
+  });
+
+  it("declares message adapter durable text, media, and reply with receipt proofs", async () => {
+    const cfg = { source: "provided" } as const;
+    mockNextcloudMessageResponse(22345, 1_706_000_003);
+    mockNextcloudMessageResponse(22346, 1_706_000_004);
+    mockNextcloudMessageResponse(22347, 1_706_000_005);
+
+    const proofResults = await verifyChannelMessageAdapterCapabilityProofs({
+      adapterName: "nextcloud-talk",
+      adapter: nextcloudTalkMessageAdapter,
+      proofs: {
+        text: async () => {
+          const result = await nextcloudTalkMessageAdapter.send?.text?.({
+            cfg: cfg as CoreConfig,
+            to: "room:abc123",
+            text: "hello",
+            accountId: "work",
+          });
+          expect(result?.receipt.platformMessageIds).toEqual(["22345"]);
+        },
+        media: async () => {
+          const result = await nextcloudTalkMessageAdapter.send?.media?.({
+            cfg: cfg as CoreConfig,
+            to: "room:abc123",
+            text: "image",
+            mediaUrl: "https://example.com/image.png",
+            accountId: "work",
+          });
+          expect(result?.receipt.platformMessageIds).toEqual(["22346"]);
+          const mediaSendCall = fetchMock.mock.calls.at(1);
+          expect(mediaSendCall?.[0]).toBe(
+            "https://nextcloud.example.com/ocs/v2.php/apps/spreed/api/v1/bot/abc123/message",
+          );
+          expect(mediaSendCall?.[1]?.body).toBe(
+            JSON.stringify({
+              message: "image\n\nAttachment: https://example.com/image.png",
+            }),
+          );
+        },
+        replyTo: async () => {
+          const result = await nextcloudTalkMessageAdapter.send?.text?.({
+            cfg: cfg as CoreConfig,
+            to: "room:abc123",
+            text: "threaded",
+            replyToId: "parent-1",
+            accountId: "work",
+          });
+          expect(result?.receipt.replyToId).toBe("parent-1");
+        },
+      },
+    });
+
+    expect(proofResults.find((result) => result.capability === "text")?.status).toBe("verified");
+    expect(proofResults.find((result) => result.capability === "media")?.status).toBe("verified");
+    expect(proofResults.find((result) => result.capability === "replyTo")?.status).toBe("verified");
+  });
+
+  it("fails hard for sendReaction when cfg is omitted", async () => {
+    fetchMock.mockResolvedValueOnce(new Response("{}", { status: 200 }));
+
+    await expect(
+      sendReactionNextcloudTalk("room:ops", "m-1", "👍", {
+        accountId: "default",
+      } as never),
+    ).rejects.toThrow("Nextcloud Talk send requires a resolved runtime config");
+
+    expect(hoisted.loadConfig).not.toHaveBeenCalled();
+    expect(hoisted.resolveNextcloudTalkAccount).not.toHaveBeenCalled();
+  });
+
+  it("uses provided cfg for sendReaction and posts the reaction payload", async () => {
+    const cfg = { source: "provided" } as const;
+    fetchMock.mockResolvedValueOnce(new Response("{}", { status: 200 }));
+
+    const result = await sendReactionNextcloudTalk("room:ops", "m-1", "👍", {
+      cfg,
+      accountId: "work",
+    });
+
+    expectProvidedCfgSkipsRuntimeLoad({
+      loadConfig: hoisted.loadConfig,
+      resolveAccount: hoisted.resolveNextcloudTalkAccount,
+      cfg,
+      accountId: "work",
+    });
+    expect(hoisted.generateNextcloudTalkSignature).toHaveBeenCalledWith({
+      body: "👍",
+      secret: "secret-value",
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://nextcloud.example.com/ocs/v2.php/apps/spreed/api/v1/bot/ops/reaction/m-1",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "OCS-APIRequest": "true",
+          "X-Nextcloud-Talk-Bot-Random": "r",
+          "X-Nextcloud-Talk-Bot-Signature": "s",
+        },
+        body: JSON.stringify({ reaction: "👍" }),
+      },
+    );
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("surfaces sendReaction HTTP failures", async () => {
+    fetchMock.mockResolvedValueOnce(new Response("forbidden", { status: 403 }));
+
+    await expect(
+      sendReactionNextcloudTalk("room:ops", "m-1", "👍", {
+        cfg: { source: "provided" },
+        accountId: "work",
+      }),
+    ).rejects.toThrow("Nextcloud Talk reaction failed: 403 forbidden");
+  });
+});

package/src/send.runtime.ts

@@ -0,0 +1,8 @@
+export { requireRuntimeConfig } from "klaw/plugin-sdk/plugin-config-runtime";
+export { resolveMarkdownTableMode } from "klaw/plugin-sdk/markdown-table-runtime";
+export { ssrfPolicyFromPrivateNetworkOptIn } from "klaw/plugin-sdk/ssrf-runtime";
+export { convertMarkdownTables } from "klaw/plugin-sdk/text-chunking";
+export { fetchWithSsrFGuard } from "../runtime-api.js";
+export { resolveNextcloudTalkAccount } from "./accounts.js";
+export { getNextcloudTalkRuntime } from "./runtime.js";
+export { generateNextcloudTalkSignature } from "./signature.js";

package/src/send.ts

@@ -0,0 +1,269 @@
+import { createMessageReceiptFromOutboundResults } from "klaw/plugin-sdk/channel-message";
+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;
+};
+
+function resolveCredentials(
+  explicit: { baseUrl?: string; secret?: string },
+  account: { baseUrl: string; secret: string; accountId: string },
+): { baseUrl: string; secret: string } {
+  const baseUrl = explicit.baseUrl?.trim() ?? account.baseUrl;
+  const secret = explicit.secret?.trim() ?? account.secret;
+
+  if (!baseUrl) {
+    throw new Error(
+      `Nextcloud Talk baseUrl missing for account "${account.accountId}" (set channels.nextcloud-talk.baseUrl).`,
+    );
+  }
+  if (!secret) {
+    throw new Error(
+      `Nextcloud Talk bot secret missing for account "${account.accountId}" (set channels.nextcloud-talk.botSecret/botSecretFile or NEXTCLOUD_TALK_BOT_SECRET for default).`,
+    );
+  }
+
+  return { baseUrl, secret };
+}
+
+function normalizeRoomToken(to: string): string {
+  const normalized = stripNextcloudTalkTargetPrefix(to);
+  if (!normalized) {
+    throw new Error("Room token is required for Nextcloud Talk sends");
+  }
+  return normalized;
+}
+
+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,
+  });
+  const { baseUrl, secret } = resolveCredentials(
+    { 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;
+    }
+  }
+}
+
+function createNextcloudTalkSendReceipt(params: {
+  messageId: string;
+  roomToken: string;
+  replyTo?: string;
+}) {
+  const messageId = params.messageId.trim();
+  return createMessageReceiptFromOutboundResults({
+    results:
+      messageId && messageId !== "unknown"
+        ? [
+            {
+              channel: "nextcloud-talk",
+              messageId,
+              conversationId: params.roomToken,
+            },
+          ]
+        : [],
+    kind: "text",
+    ...(params.replyTo ? { replyToId: params.replyTo } : {}),
+  });
+}
+
+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 = resolveMarkdownTableMode({
+    cfg,
+    channel: "nextcloud-talk",
+    accountId: account.accountId,
+  });
+  const message = convertMarkdownTables(text.trim(), tableMode);
+
+  const body: Record<string, unknown> = {
+    message,
+  };
+  if (opts.replyTo) {
+    body.replyTo = opts.replyTo;
+  }
+  const bodyStr = JSON.stringify(body);
+
+  // Nextcloud Talk verifies signature against the extracted message text,
+  // not the full JSON body. See ChecksumVerificationService.php:
+  //   hash_hmac('sha256', $random . $data, $secret)
+  // where $data is the "message" parameter, not the raw request body.
+  const { random, signature } = generateNextcloudTalkSignature({
+    body: message,
+    secret,
+  });
+
+  const url = `${baseUrl}/ocs/v2.php/apps/spreed/api/v1/bot/${roomToken}/message`;
+
+  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,
+    },
+    auditContext: "nextcloud-talk-send",
+    policy: ssrfPolicyFromPrivateNetworkOptIn(account.config),
+  });
+
+  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: bot send was rejected - check the bot secret and ensure the bot was installed with --feature response";
+      } 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);
+    }
+
+    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 (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}`);
+    }
+
+    recordNextcloudTalkOutboundActivity(account.accountId);
+
+    return {
+      messageId,
+      roomToken,
+      receipt: createNextcloudTalkSendReceipt({
+        messageId,
+        roomToken,
+        ...(opts.replyTo ? { replyTo: opts.replyTo } : {}),
+      }),
+      timestamp,
+    };
+  } finally {
+    await release();
+  }
+}
+
+export async function sendReactionNextcloudTalk(
+  roomToken: string,
+  messageId: string,
+  reaction: string,
+  opts: Omit<NextcloudTalkSendOpts, "replyTo">,
+): Promise<{ ok: true }> {
+  const { account, baseUrl, secret } = resolveNextcloudTalkSendContext(opts);
+  const normalizedToken = normalizeRoomToken(roomToken);
+
+  const body = JSON.stringify({ reaction });
+  // Sign only the reaction string, not the full JSON body
+  const { random, signature } = generateNextcloudTalkSignature({
+    body: reaction,
+    secret,
+  });
+
+  const url = `${baseUrl}/ocs/v2.php/apps/spreed/api/v1/bot/${normalizedToken}/reaction/${messageId}`;
+
+  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,
+    },
+    auditContext: "nextcloud-talk-reaction",
+    policy: ssrfPolicyFromPrivateNetworkOptIn(account.config),
+  });
+
+  try {
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      throw new Error(`Nextcloud Talk reaction failed: ${response.status} ${errorBody}`.trim());
+    }
+
+    return { ok: true };
+  } finally {
+    await release();
+  }
+}

package/src/session-route.ts

@@ -0,0 +1,40 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { buildOutboundBaseSessionKey } from "klaw/plugin-sdk/routing";
+import { stripNextcloudTalkTargetPrefix } from "./normalize.js";
+
+type NextcloudTalkOutboundSessionRouteParams = {
+  cfg: KlawConfig;
+  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}`,
+  };
+}