@kodelyth/synology-chat 2026.5.39 → 2026.5.42

package/src/inbound-event.ts

@@ -0,0 +1,175 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { sendMessage } from "./client.js";
+import type { SynologyInboundMessage } from "./inbound-context.js";
+import { getSynologyRuntime } from "./runtime.js";
+import { buildSynologyChatInboundSessionKey } from "./session-key.js";
+import type { ResolvedSynologyChatAccount } from "./types.js";
+
+const CHANNEL_ID = "synology-chat";
+
+type SynologyChannelLog = {
+  info?: (...args: unknown[]) => void;
+};
+
+function resolveSynologyChatInboundRoute(params: {
+  cfg: KlawConfig;
+  account: ResolvedSynologyChatAccount;
+  userId: string;
+}) {
+  const rt = getSynologyRuntime();
+  const route = rt.channel.routing.resolveAgentRoute({
+    cfg: params.cfg,
+    channel: CHANNEL_ID,
+    accountId: params.account.accountId,
+    peer: {
+      kind: "direct",
+      id: params.userId,
+    },
+  });
+  return {
+    rt,
+    route,
+    sessionKey: buildSynologyChatInboundSessionKey({
+      agentId: route.agentId,
+      accountId: params.account.accountId,
+      userId: params.userId,
+      identityLinks: params.cfg.session?.identityLinks,
+    }),
+  };
+}
+
+async function deliverSynologyChatReply(params: {
+  account: ResolvedSynologyChatAccount;
+  sendUserId: string;
+  payload: { text?: string; body?: string };
+}): Promise<{ visibleReplySent: boolean }> {
+  const text = params.payload.text ?? params.payload.body;
+  if (!text) {
+    return { visibleReplySent: false };
+  }
+  const ok = await sendMessage(
+    params.account.incomingUrl,
+    text,
+    params.sendUserId,
+    params.account.allowInsecureSsl,
+  );
+  return { visibleReplySent: ok };
+}
+
+export async function dispatchSynologyChatInboundEvent(params: {
+  account: ResolvedSynologyChatAccount;
+  msg: SynologyInboundMessage;
+  log?: SynologyChannelLog;
+}): Promise<null> {
+  const rt = getSynologyRuntime();
+  const currentCfg = rt.config.current() as KlawConfig;
+
+  // The Chat API user_id (for sending) may differ from the webhook
+  // user_id (used for sessions/pairing). Use chatUserId for API calls.
+  const sendUserId = params.msg.chatUserId ?? params.msg.from;
+  const resolved = resolveSynologyChatInboundRoute({
+    cfg: currentCfg,
+    account: params.account,
+    userId: params.msg.from,
+  });
+
+  await resolved.rt.channel.turn.run({
+    channel: CHANNEL_ID,
+    accountId: params.account.accountId,
+    raw: params.msg,
+    adapter: {
+      ingest: (msg) => ({
+        id: `${params.account.accountId}:${msg.from}`,
+        timestamp: Date.now(),
+        rawText: msg.body,
+        textForAgent: msg.body,
+        textForCommands: msg.body,
+        raw: msg,
+      }),
+      resolveTurn: (input) => {
+        const chatKind =
+          params.msg.chatType === "group" || params.msg.chatType === "channel"
+            ? params.msg.chatType
+            : "direct";
+        const msgCtx = resolved.rt.channel.turn.buildContext({
+          channel: CHANNEL_ID,
+          accountId: params.account.accountId,
+          timestamp: input.timestamp,
+          from: `synology-chat:${params.msg.from}`,
+          sender: {
+            id: params.msg.from,
+            name: params.msg.senderName,
+          },
+          conversation: {
+            kind: chatKind,
+            id: params.msg.from,
+            label: params.msg.senderName || params.msg.from,
+            routePeer: {
+              kind: "direct",
+              id: params.msg.from,
+            },
+          },
+          route: {
+            agentId: resolved.route.agentId,
+            accountId: params.account.accountId,
+            routeSessionKey: resolved.sessionKey,
+            dispatchSessionKey: resolved.sessionKey,
+          },
+          reply: {
+            to: `synology-chat:${params.msg.from}`,
+            originatingTo: `synology-chat:${params.msg.from}`,
+          },
+          message: {
+            rawBody: input.rawText,
+            commandBody: input.textForCommands,
+            bodyForAgent: input.textForAgent,
+            envelopeFrom: params.msg.senderName,
+          },
+          extra: {
+            ChatType: params.msg.chatType,
+            CommandAuthorized: params.msg.commandAuthorized,
+          },
+        });
+        const storePath = resolved.rt.channel.session.resolveStorePath(currentCfg.session?.store, {
+          agentId: resolved.route.agentId,
+        });
+        return {
+          cfg: currentCfg,
+          channel: CHANNEL_ID,
+          accountId: params.account.accountId,
+          agentId: resolved.route.agentId,
+          routeSessionKey: resolved.route.sessionKey,
+          storePath,
+          ctxPayload: msgCtx,
+          recordInboundSession: resolved.rt.channel.session.recordInboundSession,
+          dispatchReplyWithBufferedBlockDispatcher:
+            resolved.rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+          delivery: {
+            durable: () => ({
+              to: sendUserId,
+            }),
+            deliver: async (payload) => {
+              return await deliverSynologyChatReply({
+                account: params.account,
+                sendUserId,
+                payload,
+              });
+            },
+          },
+          dispatcherOptions: {
+            onReplyStart: () => {
+              params.log?.info?.(`Agent reply started for ${params.msg.from}`);
+            },
+          },
+          record: {
+            onRecordError: (err) => {
+              params.log?.info?.(`Session metadata update failed for ${params.msg.from}`, err);
+            },
+          },
+        };
+      },
+    },
+  });
+
+  return null;
+}

package/src/runtime.ts

@@ -0,0 +1,8 @@
+import { createPluginRuntimeStore, type PluginRuntime } from "klaw/plugin-sdk/runtime-store";
+
+const { setRuntime: setSynologyRuntime, getRuntime: getSynologyRuntime } =
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "synology-chat",
+    errorMessage: "Synology Chat runtime not initialized - plugin not registered",
+  });
+export { getSynologyRuntime, setSynologyRuntime };

package/src/security-audit.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { collectSynologyChatSecurityAuditFindings } from "./security-audit.js";
+import type { ResolvedSynologyChatAccount } from "./types.js";
+
+function createAccount(params: {
+  accountId: string;
+  dangerouslyAllowNameMatching?: boolean;
+}): ResolvedSynologyChatAccount {
+  return {
+    accountId: params.accountId,
+    enabled: true,
+    token: "t",
+    incomingUrl: "https://nas.example.com/incoming",
+    nasHost: "https://nas.example.com",
+    webhookPath: "/webapi/entry.cgi",
+    webhookPathSource: "explicit",
+    dangerouslyAllowNameMatching: params.dangerouslyAllowNameMatching ?? false,
+    dangerouslyAllowInheritedWebhookPath: false,
+    dmPolicy: "allowlist",
+    allowedUserIds: [],
+    rateLimitPerMinute: 30,
+    botName: "Klaw",
+    allowInsecureSsl: false,
+  };
+}
+
+describe("Synology Chat security audit findings", () => {
+  it.each([
+    {
+      name: "audits base dangerous name matching",
+      accountId: "default",
+      orderedAccountIds: [] as string[],
+      hasExplicitAccountPath: false,
+      expectedFinding: {
+        checkId: "channels.synology-chat.reply.dangerous_name_matching_enabled",
+        severity: "info",
+        title: "Synology Chat dangerous name matching is enabled",
+        detail:
+          "dangerouslyAllowNameMatching=true re-enables mutable username/nickname matching for reply delivery. This is a break-glass compatibility mode, not a hardened default.",
+        remediation:
+          "Prefer stable numeric Synology Chat user IDs for reply delivery, then disable dangerouslyAllowNameMatching.",
+      },
+    },
+    {
+      name: "audits non-default accounts for dangerous name matching",
+      accountId: "beta",
+      orderedAccountIds: ["alpha", "beta"],
+      hasExplicitAccountPath: true,
+      expectedFinding: {
+        checkId: "channels.synology-chat.reply.dangerous_name_matching_enabled",
+        severity: "info",
+        title: "Synology Chat dangerous name matching is enabled (account: beta)",
+        detail:
+          "dangerouslyAllowNameMatching=true re-enables mutable username/nickname matching for reply delivery. This is a break-glass compatibility mode, not a hardened default.",
+        remediation:
+          "Prefer stable numeric Synology Chat user IDs for reply delivery, then disable dangerouslyAllowNameMatching.",
+      },
+    },
+  ])("$name", (testCase) => {
+    const findings = collectSynologyChatSecurityAuditFindings({
+      account: createAccount({
+        accountId: testCase.accountId,
+        dangerouslyAllowNameMatching: true,
+      }),
+      accountId: testCase.accountId,
+      orderedAccountIds: testCase.orderedAccountIds,
+      hasExplicitAccountPath: testCase.hasExplicitAccountPath,
+    });
+
+    expect(findings).toEqual([testCase.expectedFinding]);
+  });
+});

package/src/security-audit.ts

@@ -0,0 +1,28 @@
+import type { ResolvedSynologyChatAccount } from "./types.js";
+
+export function collectSynologyChatSecurityAuditFindings(params: {
+  accountId?: string | null;
+  account: ResolvedSynologyChatAccount;
+  orderedAccountIds: string[];
+  hasExplicitAccountPath: boolean;
+}) {
+  if (!params.account.dangerouslyAllowNameMatching) {
+    return [];
+  }
+  const accountId = params.accountId?.trim() || params.account.accountId || "default";
+  const accountNote =
+    params.orderedAccountIds.length > 1 || params.hasExplicitAccountPath
+      ? ` (account: ${accountId})`
+      : "";
+  return [
+    {
+      checkId: "channels.synology-chat.reply.dangerous_name_matching_enabled",
+      severity: "info" as const,
+      title: `Synology Chat dangerous name matching is enabled${accountNote}`,
+      detail:
+        "dangerouslyAllowNameMatching=true re-enables mutable username/nickname matching for reply delivery. This is a break-glass compatibility mode, not a hardened default.",
+      remediation:
+        "Prefer stable numeric Synology Chat user IDs for reply delivery, then disable dangerouslyAllowNameMatching.",
+    },
+  ];
+}

package/src/security.ts

@@ -0,0 +1,107 @@
+/**
+ * Security module: token validation, rate limiting, input sanitization, user allowlist.
+ */
+
+import { resolveStableChannelMessageIngress } from "klaw/plugin-sdk/channel-ingress-runtime";
+import { safeEqualSecret } from "klaw/plugin-sdk/security-runtime";
+import {
+  createFixedWindowRateLimiter,
+  type FixedWindowRateLimiter,
+} from "klaw/plugin-sdk/webhook-ingress";
+
+/**
+ * Validate webhook token using constant-time comparison.
+ * Reject empty tokens explicitly; use shared constant-time comparison otherwise.
+ */
+export function validateToken(received: string, expected: string): boolean {
+  if (!received || !expected) {
+    return false;
+  }
+  return safeEqualSecret(received, expected);
+}
+
+export async function authorizeUserForDmWithIngress(params: {
+  accountId: string;
+  userId: string;
+  dmPolicy: "open" | "allowlist" | "disabled";
+  allowedUserIds: string[];
+}) {
+  return await resolveStableChannelMessageIngress({
+    channelId: "synology-chat",
+    accountId: params.accountId,
+    identity: {
+      key: "sender-id",
+      entryIdPrefix: "synology-chat-entry",
+    },
+    subject: { stableId: params.userId },
+    conversation: {
+      kind: "direct",
+      id: "direct",
+    },
+    event: { mayPair: false },
+    dmPolicy: params.dmPolicy,
+    allowFrom: params.allowedUserIds,
+  });
+}
+
+/**
+ * Sanitize user input to prevent prompt injection attacks.
+ * Filters known dangerous patterns and truncates long messages.
+ */
+export function sanitizeInput(text: string): string {
+  const dangerousPatterns = [
+    /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?)/gi,
+    /you\s+are\s+now\s+/gi,
+    /system:\s*/gi,
+    /<\|.*?\|>/g, // special tokens
+  ];
+
+  let sanitized = text;
+  for (const pattern of dangerousPatterns) {
+    sanitized = sanitized.replace(pattern, "[FILTERED]");
+  }
+
+  const maxLength = 4000;
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.slice(0, maxLength) + "... [truncated]";
+  }
+
+  return sanitized;
+}
+
+/**
+ * Sliding window rate limiter per user ID.
+ */
+export class RateLimiter {
+  private readonly limiter: FixedWindowRateLimiter;
+  private readonly limit: number;
+
+  constructor(limit = 30, windowSeconds = 60, maxTrackedUsers = 5_000) {
+    this.limit = limit;
+    this.limiter = createFixedWindowRateLimiter({
+      windowMs: Math.max(1, Math.floor(windowSeconds * 1000)),
+      maxRequests: Math.max(1, Math.floor(limit)),
+      maxTrackedKeys: Math.max(1, Math.floor(maxTrackedUsers)),
+    });
+  }
+
+  /** Returns true if the request is allowed, false if rate-limited. */
+  check(userId: string): boolean {
+    return !this.limiter.isRateLimited(userId);
+  }
+
+  /** Exposed for tests and diagnostics. */
+  size(): number {
+    return this.limiter.size();
+  }
+
+  /** Exposed for tests and account lifecycle cleanup. */
+  clear(): void {
+    this.limiter.clear();
+  }
+
+  /** Exposed for tests. */
+  maxRequests(): number {
+    return this.limit;
+  }
+}

package/src/session-key.ts

@@ -0,0 +1,21 @@
+import { buildAgentSessionKey } from "klaw/plugin-sdk/routing";
+
+const CHANNEL_ID = "synology-chat";
+
+export function buildSynologyChatInboundSessionKey(params: {
+  agentId: string;
+  accountId: string;
+  userId: string;
+  identityLinks?: Record<string, string[]>;
+}): string {
+  return buildAgentSessionKey({
+    agentId: params.agentId,
+    channel: CHANNEL_ID,
+    accountId: params.accountId,
+    peer: { kind: "direct", id: params.userId },
+    // Synology Chat supports multiple independent accounts on one gateway.
+    // Keep direct-message sessions isolated per account and user.
+    dmScope: "per-account-channel-peer",
+    identityLinks: params.identityLinks,
+  });
+}