@kodelyth/nextcloud-talk 2026.5.39 → 2026.5.42

package/src/channel.adapters.ts

@@ -0,0 +1,52 @@
+import { formatAllowFromLowercase } from "klaw/plugin-sdk/allow-from";
+import {
+  adaptScopedAccountAccessor,
+  createScopedChannelConfigAdapter,
+  createScopedDmSecurityResolver,
+} from "klaw/plugin-sdk/channel-config-helpers";
+import { createPairingPrefixStripper } from "klaw/plugin-sdk/channel-pairing";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import {
+  listNextcloudTalkAccountIds,
+  resolveDefaultNextcloudTalkAccountId,
+  resolveNextcloudTalkAccount,
+  type ResolvedNextcloudTalkAccount,
+} from "./accounts.js";
+import type { CoreConfig } from "./types.js";
+
+export const nextcloudTalkConfigAdapter = createScopedChannelConfigAdapter<
+  ResolvedNextcloudTalkAccount,
+  ResolvedNextcloudTalkAccount,
+  CoreConfig
+>({
+  sectionKey: "nextcloud-talk",
+  listAccountIds: listNextcloudTalkAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveNextcloudTalkAccount),
+  defaultAccountId: resolveDefaultNextcloudTalkAccountId,
+  clearBaseFields: ["botSecret", "botSecretFile", "baseUrl", "name"],
+  resolveAllowFrom: (account) => account.config.allowFrom,
+  formatAllowFrom: (allowFrom) =>
+    formatAllowFromLowercase({
+      allowFrom,
+      stripPrefixRe: /^(nextcloud-talk|nc-talk|nc):/i,
+    }),
+});
+
+export const nextcloudTalkSecurityAdapter = {
+  resolveDmPolicy: createScopedDmSecurityResolver<ResolvedNextcloudTalkAccount>({
+    channelKey: "nextcloud-talk",
+    resolvePolicy: (account) => account.config.dmPolicy,
+    resolveAllowFrom: (account) => account.config.allowFrom,
+    policyPathSuffix: "dmPolicy",
+    normalizeEntry: (raw) =>
+      normalizeLowercaseStringOrEmpty(raw.trim().replace(/^(nextcloud-talk|nc-talk|nc):/i, "")),
+  }),
+};
+
+export const nextcloudTalkPairingTextAdapter = {
+  idLabel: "nextcloudUserId",
+  message: "Klaw: your access has been approved.",
+  normalizeAllowEntry: createPairingPrefixStripper(/^(nextcloud-talk|nc-talk|nc):/i, (entry) =>
+    normalizeLowercaseStringOrEmpty(entry),
+  ),
+};

package/src/channel.core.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import {
+  nextcloudTalkConfigAdapter,
+  nextcloudTalkPairingTextAdapter,
+  nextcloudTalkSecurityAdapter,
+} from "./channel.adapters.js";
+import { NextcloudTalkConfigSchema } from "./config-schema.js";
+import type { CoreConfig } from "./types.js";
+
+describe("nextcloud talk channel core", () => {
+  it("accepts SecretRef botSecret and apiPassword at top-level", () => {
+    const result = NextcloudTalkConfigSchema.safeParse({
+      baseUrl: "https://cloud.example.com",
+      botSecret: { source: "env", provider: "default", id: "NEXTCLOUD_TALK_BOT_SECRET" },
+      apiUser: "bot",
+      apiPassword: { source: "env", provider: "default", id: "NEXTCLOUD_TALK_API_PASSWORD" },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts SecretRef botSecret and apiPassword on account", () => {
+    const result = NextcloudTalkConfigSchema.safeParse({
+      accounts: {
+        main: {
+          baseUrl: "https://cloud.example.com",
+          botSecret: {
+            source: "env",
+            provider: "default",
+            id: "NEXTCLOUD_TALK_MAIN_BOT_SECRET",
+          },
+          apiUser: "bot",
+          apiPassword: {
+            source: "env",
+            provider: "default",
+            id: "NEXTCLOUD_TALK_MAIN_API_PASSWORD",
+          },
+        },
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("normalizes trimmed DM allowlist prefixes to lowercase ids", () => {
+    const resolveDmPolicy = nextcloudTalkSecurityAdapter.resolveDmPolicy;
+    if (!resolveDmPolicy) {
+      throw new Error("resolveDmPolicy unavailable");
+    }
+
+    const cfg = {
+      channels: {
+        "nextcloud-talk": {
+          baseUrl: "https://cloud.example.com",
+          botSecret: "secret",
+          dmPolicy: "allowlist",
+          allowFrom: ["  nc:User-Id  "],
+        },
+      },
+    } as CoreConfig;
+
+    const result = resolveDmPolicy({
+      cfg,
+      account: nextcloudTalkConfigAdapter.resolveAccount(cfg, "default"),
+    });
+    if (!result) {
+      throw new Error("nextcloud-talk resolveDmPolicy returned null");
+    }
+
+    expect(result.policy).toBe("allowlist");
+    expect(result.allowFrom).toEqual(["  nc:User-Id  "]);
+    expect(result.normalizeEntry?.("  nc:User-Id  ")).toBe("user-id");
+    expect(nextcloudTalkPairingTextAdapter.normalizeAllowEntry("  nextcloud-talk:User-Id  ")).toBe(
+      "user-id",
+    );
+  });
+});

package/src/channel.lifecycle.test.ts

@@ -0,0 +1,91 @@
+import { createStartAccountContext } from "klaw/plugin-sdk/channel-test-helpers";
+import {
+  expectStopPendingUntilAbort,
+  startAccountAndTrackLifecycle,
+  waitForStartedMocks,
+} from "klaw/plugin-sdk/channel-test-helpers";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedNextcloudTalkAccount } from "./accounts.js";
+
+const hoisted = vi.hoisted(() => ({
+  monitorNextcloudTalkProvider: vi.fn(),
+}));
+
+vi.mock("./monitor-runtime.js", () => ({
+  monitorNextcloudTalkProvider: hoisted.monitorNextcloudTalkProvider,
+}));
+
+const { nextcloudTalkGatewayAdapter } = await import("./gateway.js");
+
+type NextcloudTalkStartAccount = NonNullable<typeof nextcloudTalkGatewayAdapter.startAccount>;
+
+function requireStartAccount(): NextcloudTalkStartAccount {
+  const startAccount = nextcloudTalkGatewayAdapter.startAccount;
+  if (!startAccount) {
+    throw new Error("Expected Nextcloud Talk gateway startAccount");
+  }
+  return startAccount;
+}
+
+function buildAccount(): ResolvedNextcloudTalkAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    baseUrl: "https://nextcloud.example.com",
+    secret: "secret", // pragma: allowlist secret
+    secretSource: "config", // pragma: allowlist secret
+    config: {
+      baseUrl: "https://nextcloud.example.com",
+      botSecret: "secret", // pragma: allowlist secret
+      webhookPath: "/nextcloud-talk-webhook",
+      webhookPort: 8788,
+    },
+  };
+}
+
+function mockStartedMonitor() {
+  const stop = vi.fn();
+  hoisted.monitorNextcloudTalkProvider.mockResolvedValue({ stop });
+  return stop;
+}
+
+function startNextcloudAccount(abortSignal?: AbortSignal) {
+  return requireStartAccount()(
+    createStartAccountContext({
+      account: buildAccount(),
+      abortSignal,
+    }),
+  );
+}
+
+describe("nextcloud-talk startAccount lifecycle", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("keeps startAccount pending until abort, then stops the monitor", async () => {
+    const stop = mockStartedMonitor();
+    const { abort, task, isSettled } = startAccountAndTrackLifecycle({
+      startAccount: requireStartAccount(),
+      account: buildAccount(),
+    });
+    await expectStopPendingUntilAbort({
+      waitForStarted: waitForStartedMocks(hoisted.monitorNextcloudTalkProvider),
+      isSettled,
+      abort,
+      task,
+      stop,
+    });
+  });
+
+  it("stops immediately when startAccount receives an already-aborted signal", async () => {
+    const stop = mockStartedMonitor();
+    const abort = new AbortController();
+    abort.abort();
+
+    await startNextcloudAccount(abort.signal);
+
+    expect(hoisted.monitorNextcloudTalkProvider).toHaveBeenCalledOnce();
+    expect(stop).toHaveBeenCalledOnce();
+  });
+});

package/src/channel.status.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { nextcloudTalkPlugin } from "./channel.js";
+
+describe("nextcloud-talk channel status", () => {
+  it("surfaces missing response feature probes as config issues", () => {
+    const issues = nextcloudTalkPlugin.status?.collectStatusIssues?.([
+      {
+        accountId: "default",
+        configured: true,
+        probe: {
+          ok: false,
+          code: "missing_response_feature",
+          message: "Nextcloud Talk bot is missing --feature response.",
+        },
+      },
+    ]);
+
+    expect(issues).toEqual([
+      {
+        channel: "nextcloud-talk",
+        accountId: "default",
+        kind: "config",
+        message: "Nextcloud Talk bot is missing --feature response.",
+        fix: "Add --feature response to the Talk bot.",
+      },
+    ]);
+  });
+});

package/src/channel.ts

@@ -0,0 +1,225 @@
+import { describeWebhookAccountSnapshot } from "klaw/plugin-sdk/account-helpers";
+import { createChatChannelPlugin } from "klaw/plugin-sdk/channel-core";
+import { createLoggedPairingApprovalNotifier } from "klaw/plugin-sdk/channel-pairing";
+import { createAllowlistProviderRouteAllowlistWarningCollector } from "klaw/plugin-sdk/channel-policy";
+import {
+  buildWebhookChannelStatusSummary,
+  createComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "klaw/plugin-sdk/status-helpers";
+import { resolveNextcloudTalkAccount, type ResolvedNextcloudTalkAccount } from "./accounts.js";
+import { nextcloudTalkApprovalAuth } from "./approval-auth.js";
+import { probeNextcloudTalkBotResponseFeature } from "./bot-preflight.js";
+import { buildChannelConfigSchema, DEFAULT_ACCOUNT_ID, type ChannelPlugin } from "./channel-api.js";
+import {
+  nextcloudTalkConfigAdapter,
+  nextcloudTalkPairingTextAdapter,
+  nextcloudTalkSecurityAdapter,
+} from "./channel.adapters.js";
+import { NextcloudTalkConfigSchema } from "./config-schema.js";
+import { nextcloudTalkDoctor } from "./doctor.js";
+import { nextcloudTalkGatewayAdapter } from "./gateway.js";
+import { nextcloudTalkMessageActions } from "./message-actions.js";
+import { nextcloudTalkMessageAdapter } from "./message-adapter.js";
+import {
+  looksLikeNextcloudTalkTargetId,
+  normalizeNextcloudTalkMessagingTarget,
+} from "./normalize.js";
+import { resolveNextcloudTalkGroupToolPolicy } from "./policy.js";
+import { getNextcloudTalkRuntime } from "./runtime.js";
+import { collectRuntimeConfigAssignments, secretTargetRegistryEntries } from "./secret-contract.js";
+import { resolveNextcloudTalkOutboundSessionRoute } from "./session-route.js";
+import { nextcloudTalkSetupAdapter } from "./setup-core.js";
+import { nextcloudTalkSetupWizard } from "./setup-surface.js";
+import type { CoreConfig } from "./types.js";
+
+const meta = {
+  id: "nextcloud-talk",
+  label: "Nextcloud Talk",
+  selectionLabel: "Nextcloud Talk (self-hosted)",
+  docsPath: "/channels/nextcloud-talk",
+  docsLabel: "nextcloud-talk",
+  blurb: "Self-hosted chat via Nextcloud Talk webhook bots.",
+  aliases: ["nc-talk", "nc"],
+  order: 65,
+  quickstartAllowFrom: true,
+};
+
+const collectNextcloudTalkSecurityWarnings =
+  createAllowlistProviderRouteAllowlistWarningCollector<ResolvedNextcloudTalkAccount>({
+    providerConfigPresent: (cfg) =>
+      (cfg.channels as Record<string, unknown> | undefined)?.["nextcloud-talk"] !== undefined,
+    resolveGroupPolicy: (account) => account.config.groupPolicy,
+    resolveRouteAllowlistConfigured: (account) =>
+      Boolean(account.config.rooms) && Object.keys(account.config.rooms ?? {}).length > 0,
+    restrictSenders: {
+      surface: "Nextcloud Talk rooms",
+      openScope: "any member in allowed rooms",
+      groupPolicyPath: "channels.nextcloud-talk.groupPolicy",
+      groupAllowFromPath: "channels.nextcloud-talk.groupAllowFrom",
+    },
+    noRouteAllowlist: {
+      surface: "Nextcloud Talk rooms",
+      routeAllowlistPath: "channels.nextcloud-talk.rooms",
+      routeScope: "room",
+      groupPolicyPath: "channels.nextcloud-talk.groupPolicy",
+      groupAllowFromPath: "channels.nextcloud-talk.groupAllowFrom",
+    },
+  });
+
+export const nextcloudTalkPlugin: ChannelPlugin<ResolvedNextcloudTalkAccount> =
+  createChatChannelPlugin({
+    base: {
+      id: "nextcloud-talk",
+      meta,
+      setupWizard: nextcloudTalkSetupWizard,
+      capabilities: {
+        chatTypes: ["direct", "group"],
+        reactions: true,
+        threads: false,
+        media: true,
+        nativeCommands: false,
+        blockStreaming: true,
+      },
+      reload: { configPrefixes: ["channels.nextcloud-talk"] },
+      configSchema: buildChannelConfigSchema(NextcloudTalkConfigSchema),
+      config: {
+        ...nextcloudTalkConfigAdapter,
+        isConfigured: (account) => Boolean(account.secret?.trim() && account.baseUrl?.trim()),
+        describeAccount: (account) =>
+          describeWebhookAccountSnapshot({
+            account,
+            configured: Boolean(account.secret?.trim() && account.baseUrl?.trim()),
+            extra: {
+              secretSource: account.secretSource,
+              baseUrl: account.baseUrl ? "[set]" : "[missing]",
+            },
+          }),
+      },
+      approvalCapability: nextcloudTalkApprovalAuth,
+      doctor: nextcloudTalkDoctor,
+      groups: {
+        resolveRequireMention: ({ cfg, accountId, groupId }) => {
+          const account = resolveNextcloudTalkAccount({ cfg: cfg as CoreConfig, accountId });
+          const rooms = account.config.rooms;
+          if (!rooms || !groupId) {
+            return true;
+          }
+
+          const roomConfig = rooms[groupId];
+          if (roomConfig?.requireMention !== undefined) {
+            return roomConfig.requireMention;
+          }
+
+          const wildcardConfig = rooms["*"];
+          if (wildcardConfig?.requireMention !== undefined) {
+            return wildcardConfig.requireMention;
+          }
+
+          return true;
+        },
+        resolveToolPolicy: resolveNextcloudTalkGroupToolPolicy,
+      },
+      messaging: {
+        targetPrefixes: ["nextcloud-talk", "nc-talk", "nc"],
+        normalizeTarget: normalizeNextcloudTalkMessagingTarget,
+        resolveOutboundSessionRoute: (params) => resolveNextcloudTalkOutboundSessionRoute(params),
+        targetResolver: {
+          looksLikeId: looksLikeNextcloudTalkTargetId,
+          hint: "<roomToken>",
+        },
+      },
+      secrets: {
+        secretTargetRegistryEntries,
+        collectRuntimeConfigAssignments,
+      },
+      setup: nextcloudTalkSetupAdapter,
+      status: createComputedAccountStatusAdapter<ResolvedNextcloudTalkAccount>({
+        defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+        buildChannelSummary: ({ snapshot }) =>
+          buildWebhookChannelStatusSummary(snapshot, {
+            secretSource: snapshot.secretSource ?? "none",
+          }),
+        collectStatusIssues: (accounts) =>
+          accounts.flatMap((account) => {
+            const probe = account.probe as
+              | { ok?: boolean; code?: string; message?: string }
+              | undefined;
+            if (
+              !probe ||
+              probe.ok !== false ||
+              probe.code !== "missing_response_feature" ||
+              !probe.message
+            ) {
+              return [];
+            }
+            return [
+              {
+                channel: "nextcloud-talk",
+                accountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
+                kind: "config",
+                message: probe.message,
+                fix: "Add --feature response to the Talk bot.",
+              } as const,
+            ];
+          }),
+        probeAccount: async ({ account, timeoutMs }) =>
+          await probeNextcloudTalkBotResponseFeature({ account, timeoutMs }),
+        resolveAccountSnapshot: ({ account }) => ({
+          accountId: account.accountId,
+          name: account.name,
+          enabled: account.enabled,
+          configured: Boolean(account.secret?.trim() && account.baseUrl?.trim()),
+          extra: {
+            secretSource: account.secretSource,
+            baseUrl: account.baseUrl ? "[set]" : "[missing]",
+            mode: "webhook",
+          },
+        }),
+      }),
+      gateway: nextcloudTalkGatewayAdapter,
+      message: nextcloudTalkMessageAdapter,
+      actions: nextcloudTalkMessageActions,
+    },
+    pairing: {
+      text: {
+        ...nextcloudTalkPairingTextAdapter,
+        notify: createLoggedPairingApprovalNotifier(
+          ({ id }) => `[nextcloud-talk] User ${id} approved for pairing`,
+        ),
+      },
+    },
+    security: {
+      ...nextcloudTalkSecurityAdapter,
+      collectWarnings: collectNextcloudTalkSecurityWarnings,
+    },
+    outbound: {
+      base: {
+        deliveryMode: "direct",
+        chunker: (text, limit) =>
+          getNextcloudTalkRuntime().channel.text.chunkMarkdownText(text, limit),
+        chunkerMode: "markdown",
+        textChunkLimit: 4000,
+      },
+      attachedResults: {
+        channel: "nextcloud-talk",
+        sendText: async ({ cfg, to, text, accountId, replyToId }) =>
+          await nextcloudTalkMessageAdapter.send.text({
+            cfg,
+            to,
+            text,
+            accountId,
+            replyToId,
+          }),
+        sendMedia: async ({ cfg, to, text, mediaUrl, accountId, replyToId }) =>
+          await nextcloudTalkMessageAdapter.send.media({
+            cfg,
+            to,
+            text,
+            mediaUrl: mediaUrl ?? "",
+            accountId,
+            replyToId,
+          }),
+      },
+    },
+  });

package/src/config-schema.ts

@@ -0,0 +1,79 @@
+import {
+  DmPolicySchema,
+  GroupPolicySchema,
+  MarkdownConfigSchema,
+  ReplyRuntimeConfigSchemaShape,
+  ToolPolicySchema,
+  requireOpenAllowFrom,
+} from "klaw/plugin-sdk/channel-config-schema";
+import { requireChannelOpenAllowFrom } from "klaw/plugin-sdk/extension-shared";
+import { z } from "zod";
+import { buildSecretInputSchema } from "./secret-input.js";
+
+const NextcloudTalkRoomSchema = z
+  .object({
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema,
+    skills: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.string()).optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict();
+
+const NextcloudTalkNetworkSchema = z
+  .object({
+    /** Dangerous opt-in for self-hosted Nextcloud Talk on trusted private/internal hosts. */
+    dangerouslyAllowPrivateNetwork: z.boolean().optional(),
+  })
+  .strict()
+  .optional();
+
+const NextcloudTalkAccountSchemaBase = z
+  .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    markdown: MarkdownConfigSchema,
+    baseUrl: z.string().optional(),
+    botSecret: buildSecretInputSchema().optional(),
+    botSecretFile: z.string().optional(),
+    apiUser: z.string().optional(),
+    apiPassword: buildSecretInputSchema().optional(),
+    apiPasswordFile: z.string().optional(),
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    webhookPort: z.number().int().positive().optional(),
+    webhookHost: z.string().optional(),
+    webhookPath: z.string().optional(),
+    webhookPublicUrl: z.string().optional(),
+    allowFrom: z.array(z.string()).optional(),
+    groupAllowFrom: z.array(z.string()).optional(),
+    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+    rooms: z.record(z.string(), NextcloudTalkRoomSchema.optional()).optional(),
+    /** Network policy overrides for self-hosted Nextcloud Talk on trusted private/internal hosts. */
+    network: NextcloudTalkNetworkSchema,
+    ...ReplyRuntimeConfigSchemaShape,
+  })
+  .strict();
+
+const NextcloudTalkAccountSchema = NextcloudTalkAccountSchemaBase.superRefine((value, ctx) => {
+  requireChannelOpenAllowFrom({
+    channel: "nextcloud-talk",
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    requireOpenAllowFrom,
+  });
+});
+
+export const NextcloudTalkConfigSchema = NextcloudTalkAccountSchemaBase.extend({
+  accounts: z.record(z.string(), NextcloudTalkAccountSchema.optional()).optional(),
+  defaultAccount: z.string().optional(),
+}).superRefine((value, ctx) => {
+  requireChannelOpenAllowFrom({
+    channel: "nextcloud-talk",
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    requireOpenAllowFrom,
+  });
+});