@kodelyth/nextcloud-talk 2026.5.39 → 2026.5.42

package/src/message-actions.ts

@@ -0,0 +1,82 @@
+import {
+  jsonResult,
+  readStringParam,
+  resolveReactionMessageId,
+} from "klaw/plugin-sdk/channel-actions";
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+} from "klaw/plugin-sdk/channel-contract";
+import { listNextcloudTalkAccountIds, resolveNextcloudTalkAccount } from "./accounts.js";
+import { sendReactionNextcloudTalk } from "./send.js";
+import type { CoreConfig } from "./types.js";
+
+const providerId = "nextcloud-talk";
+
+function isAccountConfigured(account: {
+  enabled: boolean;
+  secret: string | null;
+  baseUrl?: string | null;
+}): boolean {
+  return Boolean(account.enabled && account.secret?.trim() && account.baseUrl?.trim());
+}
+
+function hasConfiguredAccount(cfg: CoreConfig, accountId: string | null | undefined): boolean {
+  if (accountId) {
+    const account = resolveNextcloudTalkAccount({ cfg, accountId });
+    return isAccountConfigured(account);
+  }
+  return listNextcloudTalkAccountIds(cfg)
+    .map((id) => resolveNextcloudTalkAccount({ cfg, accountId: id }))
+    .some(isAccountConfigured);
+}
+
+export const nextcloudTalkMessageActions: ChannelMessageActionAdapter = {
+  describeMessageTool: ({ cfg, accountId }) => {
+    if (!hasConfiguredAccount(cfg as CoreConfig, accountId)) {
+      return null;
+    }
+    const actions: ChannelMessageActionName[] = ["send", "react"];
+    return { actions };
+  },
+
+  supportsAction: ({ action }) => action !== "send",
+
+  handleAction: async ({ action, params, cfg, accountId, toolContext }) => {
+    if (action === "send") {
+      throw new Error("Send should be handled by outbound, not actions handler.");
+    }
+
+    if (action === "react") {
+      const target = readStringParam(params, "to", {
+        required: true,
+        label: "to (room token)",
+      });
+
+      const messageIdRaw = resolveReactionMessageId({ args: params, toolContext });
+      if (messageIdRaw == null) {
+        throw new Error("messageId required");
+      }
+      const messageId = String(messageIdRaw);
+
+      const emoji = readStringParam(params, "emoji", { required: true });
+
+      // Reaction removal is part of the shared `react` tool contract but is not
+      // yet wired through to a Nextcloud Talk DELETE sender. Reject explicitly
+      // so callers do not get the opposite of what they requested.
+      if (params.remove === true) {
+        throw new Error(
+          "Nextcloud Talk reaction removal is not supported yet; only adding reactions is implemented.",
+        );
+      }
+
+      await sendReactionNextcloudTalk(target, messageId, emoji, {
+        accountId: accountId ?? undefined,
+        cfg: cfg as CoreConfig,
+      });
+      return jsonResult({ ok: true, added: emoji });
+    }
+
+    throw new Error(`Action ${action} not supported for ${providerId}.`);
+  },
+};

package/src/message-adapter.ts

@@ -0,0 +1,28 @@
+import { defineChannelMessageAdapter } from "klaw/plugin-sdk/channel-message";
+import { sendMessageNextcloudTalk } from "./send.js";
+import type { CoreConfig } from "./types.js";
+
+export const nextcloudTalkMessageAdapter = defineChannelMessageAdapter({
+  id: "nextcloud-talk",
+  durableFinal: {
+    capabilities: {
+      text: true,
+      media: true,
+      replyTo: true,
+    },
+  },
+  send: {
+    text: async ({ cfg, to, text, accountId, replyToId }) =>
+      await sendMessageNextcloudTalk(to, text, {
+        accountId: accountId ?? undefined,
+        replyTo: replyToId ?? undefined,
+        cfg: cfg as CoreConfig,
+      }),
+    media: async ({ cfg, to, text, mediaUrl, accountId, replyToId }) =>
+      await sendMessageNextcloudTalk(to, mediaUrl ? `${text}\n\nAttachment: ${mediaUrl}` : text, {
+        accountId: accountId ?? undefined,
+        replyTo: replyToId ?? undefined,
+        cfg: cfg as CoreConfig,
+      }),
+  },
+});

package/src/monitor-runtime.ts

@@ -0,0 +1,138 @@
+import os from "node:os";
+import { resolveLoggerBackedRuntime } from "klaw/plugin-sdk/extension-shared";
+import type { RuntimeEnv } from "klaw/plugin-sdk/runtime";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import { resolveNextcloudTalkAccount } from "./accounts.js";
+import { handleNextcloudTalkInbound } from "./inbound.js";
+import {
+  createNextcloudTalkWebhookServer,
+  processNextcloudTalkReplayGuardedMessage,
+} from "./monitor.js";
+import { createNextcloudTalkReplayGuard } from "./replay-guard.js";
+import { getNextcloudTalkRuntime } from "./runtime.js";
+import type { CoreConfig, NextcloudTalkInboundMessage } from "./types.js";
+
+const DEFAULT_WEBHOOK_PORT = 8788;
+const DEFAULT_WEBHOOK_HOST = "0.0.0.0";
+const DEFAULT_WEBHOOK_PATH = "/nextcloud-talk-webhook";
+
+function normalizeOrigin(value: string): string | null {
+  try {
+    return normalizeLowercaseStringOrEmpty(new URL(value).origin);
+  } catch {
+    return null;
+  }
+}
+
+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.current() as CoreConfig);
+  const account = resolveNextcloudTalkAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const runtime: RuntimeEnv = resolveLoggerBackedRuntime(
+    opts.runtime,
+    core.logging.getChildLogger(),
+  );
+
+  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 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;
+    },
+    processMessage: async (message) => {
+      const result = await processNextcloudTalkReplayGuardedMessage({
+        replayGuard,
+        accountId: account.accountId,
+        message,
+        handleMessage: async () => {
+          core.channel.activity.record({
+            channel: "nextcloud-talk",
+            accountId: account.accountId,
+            direction: "inbound",
+            at: message.timestamp,
+          });
+          if (opts.onMessage) {
+            await opts.onMessage(message);
+          } else {
+            await handleNextcloudTalkInbound({
+              message,
+              account,
+              config: cfg,
+              runtime,
+              statusSink: opts.statusSink,
+            });
+          }
+        },
+      });
+      if (result === "duplicate") {
+        logger.warn(
+          `[nextcloud-talk:${account.accountId}] replayed webhook ignored room=${message.roomToken} messageId=${message.messageId}`,
+        );
+        return;
+      }
+    },
+    onMessage: async () => {},
+    onError: (error) => {
+      logger.error(`[nextcloud-talk:${account.accountId}] webhook error: ${error.message}`);
+    },
+    abortSignal: opts.abortSignal,
+  });
+
+  if (opts.abortSignal?.aborted) {
+    return { stop };
+  }
+  await start();
+  if (opts.abortSignal?.aborted) {
+    stop();
+    return { stop };
+  }
+
+  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/monitor.replay.test.ts

@@ -0,0 +1,276 @@
+import { createMockIncomingRequest } from "klaw/plugin-sdk/test-env";
+import { describe, expect, it, vi } from "vitest";
+import {
+  NextcloudTalkRetryableWebhookError,
+  processNextcloudTalkReplayGuardedMessage,
+  readNextcloudTalkWebhookBody,
+} from "./monitor.js";
+import { createSignedCreateMessageRequest } from "./monitor.test-fixtures.js";
+import { startWebhookServer } from "./monitor.test-harness.js";
+import { createNextcloudTalkReplayGuard } from "./replay-guard.js";
+import { generateNextcloudTalkSignature } from "./signature.js";
+import type { NextcloudTalkInboundMessage } from "./types.js";
+
+describe("readNextcloudTalkWebhookBody", () => {
+  it("reads valid body within max bytes", async () => {
+    const req = createMockIncomingRequest(['{"type":"Create"}']);
+    const body = await readNextcloudTalkWebhookBody(req, 1024);
+    expect(body).toBe('{"type":"Create"}');
+  });
+
+  it("rejects when payload exceeds max bytes", async () => {
+    const req = createMockIncomingRequest(["x".repeat(300)]);
+    await expect(readNextcloudTalkWebhookBody(req, 128)).rejects.toThrow("PayloadTooLarge");
+  });
+});
+
+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();
+  });
+});
+
+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 { body, headers } = createSignedCreateMessageRequest({
+      backend: "https://nextcloud.unexpected",
+    });
+    const response = await fetch(harness.webhookUrl, {
+      method: "POST",
+      headers,
+      body,
+    });
+
+    expect(response.status).toBe(401);
+    expect(await response.json()).toEqual({ error: "Invalid backend" });
+    expect(onMessage).not.toHaveBeenCalled();
+  });
+});
+
+describe("createNextcloudTalkWebhookServer replay handling", () => {
+  function createReplayGuardedProcess(params: {
+    stateDir?: string;
+    accountId?: string;
+    handleMessage: () => Promise<void>;
+  }) {
+    const replayGuard = createNextcloudTalkReplayGuard(
+      params.stateDir ? { stateDir: params.stateDir } : {},
+    );
+
+    return (message: NextcloudTalkInboundMessage) =>
+      processNextcloudTalkReplayGuardedMessage({
+        replayGuard,
+        accountId: params.accountId ?? "acct",
+        message,
+        handleMessage: params.handleMessage,
+      });
+  }
+
+  function buildInboundMessage(): NextcloudTalkInboundMessage {
+    return {
+      messageId: "msg-1",
+      roomToken: "room-token",
+      roomName: "Room 1",
+      senderId: "alice",
+      senderName: "Alice",
+      text: "hello",
+      mediaType: "text/plain",
+      timestamp: 1_700_000_000_000,
+      isGroupChat: true,
+    };
+  }
+
+  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 { body, headers } = createSignedCreateMessageRequest();
+
+    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);
+  });
+
+  it("allows a retry after replay-guarded processing fails before commit", async () => {
+    let attempts = 0;
+    const handleMessage = vi.fn(async () => {
+      attempts += 1;
+      if (attempts === 1) {
+        throw new NextcloudTalkRetryableWebhookError("transient nextcloud failure");
+      }
+    });
+    const processMessage = createReplayGuardedProcess({
+      handleMessage,
+    });
+    const message = buildInboundMessage();
+
+    await expect(processMessage(message)).rejects.toThrow("transient nextcloud failure");
+    await expect(processMessage(message)).resolves.toBe("processed");
+
+    expect(handleMessage).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps replay committed after a non-retryable replay-guarded processing failure", async () => {
+    const visibleSideEffect = vi.fn();
+    const handleMessage = vi.fn(async () => {
+      visibleSideEffect();
+      throw new Error("post-send failure");
+    });
+    const processMessage = createReplayGuardedProcess({
+      handleMessage,
+    });
+    const message = buildInboundMessage();
+
+    await expect(processMessage(message)).rejects.toThrow("post-send failure");
+    await expect(processMessage(message)).resolves.toBe("duplicate");
+
+    expect(handleMessage).toHaveBeenCalledTimes(1);
+    expect(visibleSideEffect).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("createNextcloudTalkWebhookServer payload validation", () => {
+  it("rejects malformed webhook payloads after signature verification", async () => {
+    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: "", name: "Room 1" },
+    };
+    const body = JSON.stringify(payload);
+    const { random, signature } = generateNextcloudTalkSignature({
+      body,
+      secret: "nextcloud-secret", // pragma: allowlist secret
+    });
+    const harness = await startWebhookServer({
+      path: "/nextcloud-invalid-payload",
+      onMessage: vi.fn(),
+    });
+
+    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.example",
+      },
+      body,
+    });
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({ error: "Invalid payload format" });
+  });
+});
+
+describe("createNextcloudTalkWebhookServer auth rate limiting", () => {
+  it("rate limits repeated invalid signature attempts from the same source", async () => {
+    const maxRequests = 1;
+    const harness = await startWebhookServer({
+      path: "/nextcloud-auth-rate-limit",
+      authRateLimit: { maxRequests },
+      onMessage: vi.fn(),
+    });
+    const { body, headers } = createSignedCreateMessageRequest();
+    const invalidHeaders = {
+      ...headers,
+      "x-nextcloud-talk-signature": "invalid-signature",
+    };
+
+    let firstResponse: Response | undefined;
+    let lastResponse: Response | undefined;
+    for (let attempt = 0; attempt <= maxRequests; attempt += 1) {
+      const response = await fetch(harness.webhookUrl, {
+        method: "POST",
+        headers: invalidHeaders,
+        body,
+      });
+      if (attempt === 0) {
+        firstResponse = response;
+      }
+      lastResponse = response;
+    }
+
+    expect(firstResponse?.status).toBe(401);
+    expect(lastResponse?.status).toBe(429);
+    expect(await lastResponse?.text()).toBe("Too Many Requests");
+  });
+
+  it("does not rate limit valid signed webhook bursts from the same source", async () => {
+    const maxRequests = 1;
+    const harness = await startWebhookServer({
+      path: "/nextcloud-auth-rate-limit-valid",
+      authRateLimit: { maxRequests },
+      onMessage: vi.fn(),
+    });
+    const { body, headers } = createSignedCreateMessageRequest();
+
+    let lastResponse: Response | undefined;
+    for (let attempt = 0; attempt <= maxRequests; attempt += 1) {
+      lastResponse = await fetch(harness.webhookUrl, {
+        method: "POST",
+        headers,
+        body,
+      });
+    }
+
+    expect(lastResponse?.status).toBe(200);
+  });
+});

package/src/monitor.test-fixtures.ts

@@ -0,0 +1,30 @@
+import { generateNextcloudTalkSignature } from "./signature.js";
+
+export function createSignedCreateMessageRequest(params?: { backend?: string }) {
+  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", // pragma: allowlist secret
+  });
+  return {
+    body,
+    headers: {
+      "content-type": "application/json",
+      "x-nextcloud-talk-random": random,
+      "x-nextcloud-talk-signature": signature,
+      "x-nextcloud-talk-backend": params?.backend ?? "https://nextcloud.example",
+    },
+  };
+}

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";
+
+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();
+    }
+  }
+});
+
+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;
+}