@kodelyth/nextcloud-talk 2026.5.39 → 2026.5.42

package/src/core.test.ts

@@ -0,0 +1,325 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  looksLikeNextcloudTalkTargetId,
+  normalizeNextcloudTalkMessagingTarget,
+  stripNextcloudTalkTargetPrefix,
+} from "./normalize.js";
+import { resolveNextcloudTalkAllowlistMatch } from "./policy.js";
+import { createNextcloudTalkReplayGuard } from "./replay-guard.js";
+import { resolveNextcloudTalkOutboundSessionRoute } from "./session-route.js";
+import {
+  extractNextcloudTalkHeaders,
+  generateNextcloudTalkSignature,
+  verifyNextcloudTalkSignature,
+} from "./signature.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "nextcloud-talk-replay-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function requireFirstTimingSafeEqualCall(mock: ReturnType<typeof vi.fn>): [unknown, unknown] {
+  const [call] = mock.mock.calls;
+  if (!call) {
+    throw new Error("expected timingSafeEqual call");
+  }
+  return call as [unknown, unknown];
+}
+
+describe("nextcloud talk core", () => {
+  it("builds an outbound session route for normalized room targets", () => {
+    const route = resolveNextcloudTalkOutboundSessionRoute({
+      cfg: {},
+      agentId: "main",
+      accountId: "acct-1",
+      target: "nextcloud-talk:room-123",
+    });
+
+    expect(route).toEqual({
+      sessionKey: "agent:main:nextcloud-talk:group:room-123",
+      baseSessionKey: "agent:main:nextcloud-talk:group:room-123",
+      peer: {
+        kind: "group",
+        id: "room-123",
+      },
+      chatType: "group",
+      from: "nextcloud-talk:room:room-123",
+      to: "nextcloud-talk:room-123",
+    });
+  });
+
+  it("returns null when the target cannot be normalized to a room id", () => {
+    expect(
+      resolveNextcloudTalkOutboundSessionRoute({
+        cfg: {},
+        agentId: "main",
+        accountId: "acct-1",
+        target: "",
+      }),
+    ).toBeNull();
+  });
+
+  it("normalizes and recognizes supported room target formats", () => {
+    expect(stripNextcloudTalkTargetPrefix(" room:abc123 ")).toBe("abc123");
+    expect(stripNextcloudTalkTargetPrefix("nextcloud-talk:room:AbC123")).toBe("AbC123");
+    expect(stripNextcloudTalkTargetPrefix("nc-talk:room:ops")).toBe("ops");
+    expect(stripNextcloudTalkTargetPrefix("nc:room:ops")).toBe("ops");
+    expect(stripNextcloudTalkTargetPrefix("room:   ")).toBeUndefined();
+
+    expect(normalizeNextcloudTalkMessagingTarget("room:AbC123")).toBe("nextcloud-talk:abc123");
+    expect(normalizeNextcloudTalkMessagingTarget("nc-talk:room:Ops")).toBe("nextcloud-talk:ops");
+
+    expect(looksLikeNextcloudTalkTargetId("nextcloud-talk:room:abc12345")).toBe(true);
+    expect(looksLikeNextcloudTalkTargetId("nc:opsroom1")).toBe(true);
+    expect(looksLikeNextcloudTalkTargetId("abc12345")).toBe(true);
+    expect(looksLikeNextcloudTalkTargetId("")).toBe(false);
+  });
+
+  it("verifies generated signatures and extracts normalized headers", () => {
+    const body = JSON.stringify({ hello: "world" });
+    const generated = generateNextcloudTalkSignature({
+      body,
+      secret: "secret-123",
+    });
+
+    expect(generated.random).toMatch(/^[0-9a-f]{64}$/);
+    expect(generated.signature).toMatch(/^[0-9a-f]{64}$/);
+    expect(
+      verifyNextcloudTalkSignature({
+        signature: generated.signature,
+        random: generated.random,
+        body,
+        secret: "secret-123",
+      }),
+    ).toBe(true);
+    expect(
+      verifyNextcloudTalkSignature({
+        signature: "",
+        random: "abc",
+        body: "body",
+        secret: "secret",
+      }),
+    ).toBe(false);
+    expect(
+      verifyNextcloudTalkSignature({
+        signature: "deadbeef",
+        random: "abc",
+        body: "body",
+        secret: "secret",
+      }),
+    ).toBe(false);
+
+    expect(
+      extractNextcloudTalkHeaders({
+        "x-nextcloud-talk-signature": "sig",
+        "x-nextcloud-talk-random": "rand",
+        "x-nextcloud-talk-backend": "backend",
+      }),
+    ).toEqual({
+      signature: "sig",
+      random: "rand",
+      backend: "backend",
+    });
+    expect(
+      extractNextcloudTalkHeaders({
+        "X-Nextcloud-Talk-Signature": "sig",
+      }),
+    ).toBeNull();
+  });
+
+  it("rejects tampered bodies, wrong secrets, and tampered signatures", () => {
+    const body = JSON.stringify({ hello: "world" });
+    const generated = generateNextcloudTalkSignature({
+      body,
+      secret: "secret-123",
+    });
+
+    expect(
+      verifyNextcloudTalkSignature({
+        signature: generated.signature,
+        random: generated.random,
+        body: JSON.stringify({ hello: "tampered" }),
+        secret: "secret-123",
+      }),
+    ).toBe(false);
+    expect(
+      verifyNextcloudTalkSignature({
+        signature: generated.signature,
+        random: generated.random,
+        body,
+        secret: "wrong-secret",
+      }),
+    ).toBe(false);
+    expect(
+      verifyNextcloudTalkSignature({
+        signature: "a".repeat(generated.signature.length),
+        random: generated.random,
+        body,
+        secret: "secret-123",
+      }),
+    ).toBe(false);
+  });
+
+  it("takes the first value from array-backed headers", () => {
+    expect(
+      extractNextcloudTalkHeaders({
+        "x-nextcloud-talk-signature": ["sig1", "sig2"],
+        "x-nextcloud-talk-random": ["rand1", "rand2"],
+        "x-nextcloud-talk-backend": ["backend1", "backend2"],
+      }),
+    ).toEqual({
+      signature: "sig1",
+      random: "rand1",
+      backend: "backend1",
+    });
+  });
+
+  it("still runs timingSafeEqual when the supplied signature length mismatches", async () => {
+    const timingSafeEqualMock = vi.fn();
+
+    vi.resetModules();
+    vi.doMock("node:crypto", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("node:crypto")>();
+      return {
+        ...actual,
+        timingSafeEqual: vi.fn((left: NodeJS.ArrayBufferView, right: NodeJS.ArrayBufferView) => {
+          timingSafeEqualMock(left, right);
+          return actual.timingSafeEqual(left, right);
+        }),
+      };
+    });
+
+    try {
+      const { generateNextcloudTalkSignature, verifyNextcloudTalkSignature } =
+        await import("./signature.js");
+      const body = JSON.stringify({ hello: "world" });
+      const generated = generateNextcloudTalkSignature({
+        body,
+        secret: "secret-123",
+      });
+      const shortSignature = generated.signature.slice(0, 12);
+
+      expect(
+        verifyNextcloudTalkSignature({
+          signature: shortSignature,
+          random: generated.random,
+          body,
+          secret: "secret-123",
+        }),
+      ).toBe(false);
+
+      expect(timingSafeEqualMock).toHaveBeenCalledOnce();
+      const [leftBuffer, rightBuffer] = requireFirstTimingSafeEqualCall(timingSafeEqualMock);
+      expect(Buffer.isBuffer(leftBuffer)).toBe(true);
+      expect(Buffer.isBuffer(rightBuffer)).toBe(true);
+      if (!Buffer.isBuffer(leftBuffer) || !Buffer.isBuffer(rightBuffer)) {
+        throw new TypeError("Expected timingSafeEqual to receive Buffer arguments");
+      }
+      expect(leftBuffer).toHaveLength(rightBuffer.length);
+    } finally {
+      vi.doUnmock("node:crypto");
+      vi.resetModules();
+    }
+  });
+
+  it("persists replay decisions across guard instances and scopes account namespaces", async () => {
+    const stateDir = await makeTempDir();
+
+    const firstGuard = createNextcloudTalkReplayGuard({ stateDir });
+    const firstAttempt = await firstGuard.shouldProcessMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-1",
+    });
+    const replayAttempt = await firstGuard.shouldProcessMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-1",
+    });
+
+    const secondGuard = createNextcloudTalkReplayGuard({ stateDir });
+    const restartReplayAttempt = await secondGuard.shouldProcessMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-1",
+    });
+    const otherAccountFirstAttempt = await secondGuard.shouldProcessMessage({
+      accountId: "account-b",
+      roomToken: "room-1",
+      messageId: "msg-1",
+    });
+
+    expect(firstAttempt).toBe(true);
+    expect(replayAttempt).toBe(false);
+    expect(restartReplayAttempt).toBe(false);
+    expect(otherAccountFirstAttempt).toBe(true);
+  });
+
+  it("releases in-flight replay claims when processing fails", async () => {
+    const guard = createNextcloudTalkReplayGuard({});
+
+    const firstClaim = await guard.claimMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-claim",
+    });
+    const secondClaim = await guard.claimMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-claim",
+    });
+
+    expect(firstClaim).toBe("claimed");
+    expect(secondClaim).toBe("inflight");
+
+    guard.releaseMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-claim",
+      error: new Error("transient"),
+    });
+
+    const retryClaim = await guard.claimMessage({
+      accountId: "account-a",
+      roomToken: "room-1",
+      messageId: "msg-claim",
+    });
+    expect(retryClaim).toBe("claimed");
+  });
+
+  it("resolves allowlist matches", () => {
+    expect(
+      resolveNextcloudTalkAllowlistMatch({
+        allowFrom: ["*"],
+        senderId: "user-id",
+      }).allowed,
+    ).toBe(true);
+    expect(
+      resolveNextcloudTalkAllowlistMatch({
+        allowFrom: ["nc:User-Id"],
+        senderId: "user-id",
+      }),
+    ).toEqual({ allowed: true, matchKey: "user-id", matchSource: "id" });
+    expect(
+      resolveNextcloudTalkAllowlistMatch({
+        allowFrom: ["allowed"],
+        senderId: "other",
+      }).allowed,
+    ).toBe(false);
+  });
+});

package/src/doctor-contract.ts

@@ -0,0 +1,9 @@
+import { createLegacyPrivateNetworkDoctorContract } from "klaw/plugin-sdk/ssrf-runtime";
+
+const contract = createLegacyPrivateNetworkDoctorContract({
+  channelKey: "nextcloud-talk",
+});
+
+export const legacyConfigRules = contract.legacyConfigRules;
+
+export const normalizeCompatibilityConfig = contract.normalizeCompatibilityConfig;

package/src/doctor.test.ts

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const hoisted = vi.hoisted(() => ({
+  probeNextcloudTalkBotResponseFeature: vi.fn(),
+}));
+
+vi.mock("./bot-preflight.js", () => ({
+  probeNextcloudTalkBotResponseFeature: hoisted.probeNextcloudTalkBotResponseFeature,
+}));
+
+const { nextcloudTalkDoctor } = await import("./doctor.js");
+
+function getNextcloudTalkCompatibilityNormalizer(): NonNullable<
+  typeof nextcloudTalkDoctor.normalizeCompatibilityConfig
+> {
+  const normalize = nextcloudTalkDoctor.normalizeCompatibilityConfig;
+  if (!normalize) {
+    throw new Error("Expected nextcloud-talk doctor to expose normalizeCompatibilityConfig");
+  }
+  return normalize;
+}
+
+describe("nextcloud-talk doctor", () => {
+  beforeEach(() => {
+    hoisted.probeNextcloudTalkBotResponseFeature.mockReset();
+  });
+
+  it("normalizes legacy private-network aliases", () => {
+    const normalize = getNextcloudTalkCompatibilityNormalizer();
+
+    const result = normalize({
+      cfg: {
+        channels: {
+          "nextcloud-talk": {
+            allowPrivateNetwork: true,
+            accounts: {
+              work: {
+                allowPrivateNetwork: false,
+              },
+            },
+          },
+        },
+      } as never,
+    });
+
+    expect(result.config.channels?.["nextcloud-talk"]?.network).toEqual({
+      dangerouslyAllowPrivateNetwork: true,
+    });
+    expect(
+      (
+        result.config.channels?.["nextcloud-talk"]?.accounts?.work as
+          | { network?: Record<string, unknown> }
+          | undefined
+      )?.network,
+    ).toEqual({
+      dangerouslyAllowPrivateNetwork: false,
+    });
+  });
+
+  it("warns when the configured bot is missing the response feature", async () => {
+    hoisted.probeNextcloudTalkBotResponseFeature.mockResolvedValueOnce({
+      ok: false,
+      code: "missing_response_feature",
+      message:
+        'Nextcloud Talk bot "Klaw" (1) is missing the response feature (features=9); outbound replies will fail.',
+    });
+
+    await expect(
+      nextcloudTalkDoctor.collectPreviewWarnings?.({
+        cfg: {
+          channels: {
+            "nextcloud-talk": {
+              baseUrl: "https://cloud.example.com",
+              botSecret: "secret",
+              apiUser: "admin",
+              apiPassword: "app-password",
+              webhookPublicUrl: "https://gateway.example.com/nextcloud-talk-webhook",
+            },
+          },
+        } as never,
+        doctorFixCommand: "klaw doctor --fix",
+      }),
+    ).resolves.toEqual([
+      '- channels.nextcloud-talk.default: Nextcloud Talk bot "Klaw" (1) is missing the response feature (features=9); outbound replies will fail.',
+    ]);
+  });
+});

package/src/doctor.ts

@@ -0,0 +1,40 @@
+import type { ChannelDoctorAdapter } from "klaw/plugin-sdk/channel-contract";
+import { listNextcloudTalkAccountIds, resolveNextcloudTalkAccount } from "./accounts.js";
+import { probeNextcloudTalkBotResponseFeature } from "./bot-preflight.js";
+import {
+  legacyConfigRules as NEXTCLOUD_TALK_LEGACY_CONFIG_RULES,
+  normalizeCompatibilityConfig as normalizeNextcloudTalkCompatibilityConfig,
+} from "./doctor-contract.js";
+import type { CoreConfig } from "./types.js";
+
+async function collectNextcloudTalkBotResponseWarnings(params: {
+  cfg: CoreConfig;
+}): Promise<string[]> {
+  const warnings: string[] = [];
+  for (const accountId of listNextcloudTalkAccountIds(params.cfg)) {
+    const account = resolveNextcloudTalkAccount({ cfg: params.cfg, accountId });
+    if (!account.enabled || !account.secret || !account.baseUrl) {
+      continue;
+    }
+    const result = await probeNextcloudTalkBotResponseFeature({
+      account,
+      timeoutMs: 5_000,
+    });
+    if (
+      result.code === "missing_response_feature" ||
+      result.code === "bot_not_found" ||
+      result.code === "api_error" ||
+      result.code === "request_failed"
+    ) {
+      warnings.push(`- channels.nextcloud-talk.${account.accountId}: ${result.message}`);
+    }
+  }
+  return warnings;
+}
+
+export const nextcloudTalkDoctor: ChannelDoctorAdapter = {
+  legacyConfigRules: NEXTCLOUD_TALK_LEGACY_CONFIG_RULES,
+  normalizeCompatibilityConfig: normalizeNextcloudTalkCompatibilityConfig,
+  collectPreviewWarnings: async ({ cfg }) =>
+    await collectNextcloudTalkBotResponseWarnings({ cfg: cfg as CoreConfig }),
+};

package/src/gateway.ts

@@ -0,0 +1,109 @@
+import { createAccountStatusSink } from "klaw/plugin-sdk/channel-lifecycle";
+import { runStoppablePassiveMonitor } from "klaw/plugin-sdk/extension-shared";
+import { resolveNextcloudTalkAccount, type ResolvedNextcloudTalkAccount } from "./accounts.js";
+import {
+  clearAccountEntryFields,
+  DEFAULT_ACCOUNT_ID,
+  type ChannelPlugin,
+  type KlawConfig,
+} from "./channel-api.js";
+import { monitorNextcloudTalkProvider } from "./monitor-runtime.js";
+import { getNextcloudTalkRuntime } from "./runtime.js";
+import type { CoreConfig } from "./types.js";
+
+export const nextcloudTalkGatewayAdapter: NonNullable<
+  ChannelPlugin<ResolvedNextcloudTalkAccount>["gateway"]
+> = {
+  startAccount: async (ctx) => {
+    const account = ctx.account;
+    if (!account.secret || !account.baseUrl) {
+      throw new Error(
+        `Nextcloud Talk not configured for account "${account.accountId}" (missing secret or baseUrl)`,
+      );
+    }
+
+    ctx.log?.info(`[${account.accountId}] starting Nextcloud Talk webhook server`);
+
+    const statusSink = createAccountStatusSink({
+      accountId: ctx.accountId,
+      setStatus: ctx.setStatus,
+    });
+
+    await runStoppablePassiveMonitor({
+      abortSignal: ctx.abortSignal,
+      start: async () =>
+        await monitorNextcloudTalkProvider({
+          accountId: account.accountId,
+          config: ctx.cfg as CoreConfig,
+          runtime: ctx.runtime,
+          abortSignal: ctx.abortSignal,
+          statusSink,
+        }),
+    });
+  },
+  logoutAccount: async ({ accountId, cfg }) => {
+    const nextCfg = { ...cfg } as KlawConfig;
+    const nextSection = cfg.channels?.["nextcloud-talk"]
+      ? { ...cfg.channels["nextcloud-talk"] }
+      : undefined;
+    let cleared = false;
+    let changed = false;
+
+    if (nextSection) {
+      if (accountId === DEFAULT_ACCOUNT_ID && nextSection.botSecret) {
+        delete nextSection.botSecret;
+        cleared = true;
+        changed = true;
+      }
+      const accountCleanup = clearAccountEntryFields({
+        accounts: nextSection.accounts as Record<string, object> | undefined,
+        accountId,
+        fields: ["botSecret"],
+      });
+      if (accountCleanup.changed) {
+        changed = true;
+        if (accountCleanup.cleared) {
+          cleared = true;
+        }
+        if (accountCleanup.nextAccounts) {
+          nextSection.accounts = accountCleanup.nextAccounts as Record<string, unknown>;
+        } else {
+          delete nextSection.accounts;
+        }
+      }
+    }
+
+    if (changed) {
+      if (nextSection && Object.keys(nextSection).length > 0) {
+        nextCfg.channels = { ...nextCfg.channels, "nextcloud-talk": nextSection };
+      } else {
+        const nextChannels = { ...nextCfg.channels } as Record<string, unknown>;
+        delete nextChannels["nextcloud-talk"];
+        if (Object.keys(nextChannels).length > 0) {
+          nextCfg.channels = nextChannels as KlawConfig["channels"];
+        } else {
+          delete nextCfg.channels;
+        }
+      }
+    }
+
+    const resolved = resolveNextcloudTalkAccount({
+      cfg: changed ? (nextCfg as CoreConfig) : (cfg as CoreConfig),
+      accountId,
+    });
+    const loggedOut = resolved.secretSource === "none";
+
+    if (changed) {
+      await getNextcloudTalkRuntime().config.replaceConfigFile({
+        nextConfig: nextCfg,
+        afterWrite: { mode: "auto" },
+      });
+    }
+
+    return {
+      cleared,
+      envSecret: Boolean(process.env.NEXTCLOUD_TALK_BOT_SECRET?.trim()),
+      loggedOut,
+    };
+  },
+};