@actagent/synology-chat 2026.6.2

package/README.md

@@ -0,0 +1,11 @@
+# ACTAgent Synology Chat
+
+Official ACTAgent channel plugin for Synology Chat conversations and direct messages.
+
+Install from ACTAgent:
+
+```bash
+actagent plugin add @actagent/synology-chat
+```
+
+Configure Synology Chat credentials and allowed conversations in ACTAgent, then use the plugin to route messages between Synology Chat and ACTAgent agents.

package/actagent.plugin.json

@@ -0,0 +1,24 @@
+{
+  "id": "synology-chat",
+  "name": "Synology Chat",
+  "description": "Synology Chat channel plugin for ACTAgent channels and direct messages.",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["synology-chat"],
+  "channelEnvVars": {
+    "synology-chat": [
+      "SYNOLOGY_CHAT_TOKEN",
+      "SYNOLOGY_CHAT_INCOMING_URL",
+      "SYNOLOGY_NAS_HOST",
+      "SYNOLOGY_ALLOWED_USER_IDS",
+      "SYNOLOGY_RATE_LIMIT",
+      "ACTAGENT_BOT_NAME"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/api.ts

@@ -0,0 +1,4 @@
+// Synology Chat API module exposes the plugin public contract.
+export { synologyChatPlugin } from "./src/channel.js";
+export { setSynologyRuntime } from "./src/runtime.js";
+export { collectSynologyChatSecurityAuditFindings } from "./src/security-audit.js";

package/channel-plugin-api.ts

@@ -0,0 +1,2 @@
+// Synology Chat API module exposes the plugin public contract.
+export { synologyChatPlugin } from "./src/channel.js";

package/contract-api.ts

@@ -0,0 +1,2 @@
+// Synology Chat API module exposes the plugin public contract.
+export { collectSynologyChatSecurityAuditFindings } from "./src/security-audit.js";

package/index.ts

@@ -0,0 +1,17 @@
+// Synology Chat plugin entrypoint registers its ACTAgent integration.
+import { defineBundledChannelEntry } from "actagent/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelEntry({
+  id: "synology-chat",
+  name: "Synology Chat",
+  description: "Native Synology Chat channel plugin for ACTAgent",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "synologyChatPlugin",
+  },
+  runtime: {
+    specifier: "./api.js",
+    exportName: "setSynologyRuntime",
+  },
+});

package/npm-shrinkwrap.json

@@ -0,0 +1,24 @@
+{
+  "name": "@actagent/synology-chat",
+  "version": "2026.6.2",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@actagent/synology-chat",
+      "version": "2026.6.2",
+      "dependencies": {
+        "zod": "4.4.3"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@actagent/synology-chat",
+  "version": "2026.6.2",
+  "description": "Synology Chat channel plugin for ACTAgent channels and direct messages.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/actagent/actagent"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@actagent/plugin-sdk": "workspace:*"
+  },
+  "actagent": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "synology-chat",
+      "label": "Synology Chat",
+      "selectionLabel": "Synology Chat (Webhook)",
+      "docsPath": "/channels/synology-chat",
+      "docsLabel": "synology-chat",
+      "blurb": "Connect your Synology NAS Chat to ACTAgent with full agent capabilities.",
+      "order": 90
+    },
+    "install": {
+      "npmSpec": "@actagent/synology-chat",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.2"
+    },
+    "build": {
+      "actagentVersion": "2026.6.2"
+    },
+    "release": {
+      "publishToACTAgentHub": true,
+      "publishToNpm": true
+    }
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  }
+}

package/setup-api.ts

@@ -0,0 +1,2 @@
+// Synology Chat API module exposes the plugin public contract.
+export { synologyChatSetupAdapter, synologyChatSetupWizard } from "./src/setup-surface.js";

package/setup-entry.ts

@@ -0,0 +1,10 @@
+// Synology Chat plugin module implements setup entry behavior.
+import { defineBundledChannelSetupEntry } from "actagent/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./api.js",
+    exportName: "synologyChatPlugin",
+  },
+});

package/src/accounts.ts

@@ -0,0 +1,159 @@
+/**
+ * Account resolution: reads config from channels.synology-chat,
+ * merges per-account overrides, falls back to environment variables.
+ */
+
+import {
+  DEFAULT_ACCOUNT_ID,
+  listCombinedAccountIds,
+  resolveMergedAccountConfig,
+  type ACTAgentConfig,
+} from "actagent/plugin-sdk/account-resolution";
+import { resolveDangerousNameMatchingEnabled } from "actagent/plugin-sdk/dangerous-name-runtime";
+import { parseStrictInteger } from "actagent/plugin-sdk/number-runtime";
+import { normalizeStringEntries } from "actagent/plugin-sdk/string-coerce-runtime";
+import type {
+  SynologyChatChannelConfig,
+  ResolvedSynologyChatAccount,
+  SynologyWebhookPathSource,
+} from "./types.js";
+
+/** Extract the channel config from the full ACTAgent config object. */
+function getChannelConfig(cfg: ACTAgentConfig): SynologyChatChannelConfig | undefined {
+  return cfg?.channels?.["synology-chat"] as SynologyChatChannelConfig | undefined;
+}
+
+function resolveImplicitAccountId(channelCfg: SynologyChatChannelConfig): string | undefined {
+  return channelCfg.token || process.env.SYNOLOGY_CHAT_TOKEN ? DEFAULT_ACCOUNT_ID : undefined;
+}
+
+function getRawAccountConfig(
+  channelCfg: SynologyChatChannelConfig,
+  accountId: string,
+): SynologyChatChannelConfig {
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return channelCfg;
+  }
+  return channelCfg.accounts?.[accountId] ?? {};
+}
+
+function hasExplicitWebhookPath(rawAccount: SynologyChatChannelConfig | undefined): boolean {
+  return typeof rawAccount?.webhookPath === "string" && rawAccount.webhookPath.trim().length > 0;
+}
+
+function resolveWebhookPathSource(params: {
+  accountId: string;
+  channelCfg: SynologyChatChannelConfig;
+  rawAccount: SynologyChatChannelConfig;
+}): SynologyWebhookPathSource {
+  if (hasExplicitWebhookPath(params.rawAccount)) {
+    return "explicit";
+  }
+  if (params.accountId !== DEFAULT_ACCOUNT_ID && hasExplicitWebhookPath(params.channelCfg)) {
+    return "inherited-base";
+  }
+  return "default";
+}
+
+/** Parse allowedUserIds from string or array to string[]. */
+function parseAllowedUserIds(raw: string | string[] | undefined): string[] {
+  if (!raw) {
+    return [];
+  }
+  if (Array.isArray(raw)) {
+    return raw.filter(Boolean);
+  }
+  return normalizeStringEntries(raw.split(","));
+}
+
+function normalizeRateLimitPerMinuteValue(raw: unknown): number | undefined {
+  if (typeof raw === "number") {
+    return Number.isSafeInteger(raw) && raw >= 0 ? raw : undefined;
+  }
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return undefined;
+  }
+  const parsed = parseStrictInteger(trimmed);
+  return parsed != null && parsed >= 0 ? parsed : undefined;
+}
+
+function parseRateLimitPerMinute(raw: string | undefined): number {
+  return normalizeRateLimitPerMinuteValue(raw) ?? 30;
+}
+
+/**
+ * List all configured account IDs for this channel.
+ * Returns ["default"] if there's a base config, plus any named accounts.
+ */
+export function listAccountIds(cfg: ACTAgentConfig): string[] {
+  const channelCfg = getChannelConfig(cfg);
+  if (!channelCfg) {
+    return [];
+  }
+
+  return listCombinedAccountIds({
+    configuredAccountIds: Object.keys(channelCfg.accounts ?? {}),
+    implicitAccountId: resolveImplicitAccountId(channelCfg),
+  });
+}
+
+/**
+ * Resolve a specific account by ID with full defaults applied.
+ * Falls back to env vars for the "default" account.
+ */
+export function resolveAccount(
+  cfg: ACTAgentConfig,
+  accountId?: string | null,
+): ResolvedSynologyChatAccount {
+  const channelCfg = getChannelConfig(cfg) ?? {};
+  const id = accountId || DEFAULT_ACCOUNT_ID;
+  const accountOverrides =
+    id === DEFAULT_ACCOUNT_ID ? undefined : (channelCfg.accounts?.[id] ?? undefined);
+  const rawAccount = getRawAccountConfig(channelCfg, id);
+  const merged = resolveMergedAccountConfig<Record<string, unknown> & SynologyChatChannelConfig>({
+    channelConfig: channelCfg as Record<string, unknown> & SynologyChatChannelConfig,
+    accounts: channelCfg.accounts as
+      | Record<string, Partial<Record<string, unknown> & SynologyChatChannelConfig>>
+      | undefined,
+    accountId: id,
+  });
+
+  // Env var fallbacks (primarily for the "default" account)
+  const envToken = process.env.SYNOLOGY_CHAT_TOKEN ?? "";
+  const envIncomingUrl = process.env.SYNOLOGY_CHAT_INCOMING_URL ?? "";
+  const envNasHost = process.env.SYNOLOGY_NAS_HOST ?? "localhost";
+  const envAllowedUserIds = process.env.SYNOLOGY_ALLOWED_USER_IDS ?? "";
+  const envRateLimitValue = parseRateLimitPerMinute(process.env.SYNOLOGY_RATE_LIMIT);
+  const envBotName = process.env.ACTAGENT_BOT_NAME ?? "ACTAgent";
+  const webhookPathSource = resolveWebhookPathSource({ accountId: id, channelCfg, rawAccount });
+  const dangerouslyAllowInheritedWebhookPath =
+    rawAccount.dangerouslyAllowInheritedWebhookPath ??
+    channelCfg.dangerouslyAllowInheritedWebhookPath ??
+    false;
+
+  // Merge: account override > base channel config > env var
+  return {
+    accountId: id,
+    enabled: merged.enabled ?? true,
+    token: merged.token ?? envToken,
+    incomingUrl: merged.incomingUrl ?? envIncomingUrl,
+    nasHost: merged.nasHost ?? envNasHost,
+    webhookPath: merged.webhookPath ?? "/webhook/synology",
+    webhookPathSource,
+    dangerouslyAllowNameMatching: resolveDangerousNameMatchingEnabled({
+      providerConfig: channelCfg,
+      accountConfig: accountOverrides,
+    }),
+    dangerouslyAllowInheritedWebhookPath,
+    dmPolicy: merged.dmPolicy ?? "allowlist",
+    allowedUserIds: parseAllowedUserIds(merged.allowedUserIds ?? envAllowedUserIds),
+    rateLimitPerMinute:
+      normalizeRateLimitPerMinuteValue(merged.rateLimitPerMinute) ?? envRateLimitValue,
+    botName: merged.botName ?? envBotName,
+    allowInsecureSsl: merged.allowInsecureSsl ?? false,
+  };
+}

package/src/approval-auth.test.ts

@@ -0,0 +1,18 @@
+// Synology Chat tests cover approval auth plugin behavior.
+import { describe, expect, it } from "vitest";
+import { synologyChatApprovalAuth } from "./approval-auth.js";
+
+describe("synologyChatApprovalAuth", () => {
+  it("authorizes numeric Synology Chat user ids", () => {
+    const cfg = { channels: { "synology-chat": { allowedUserIds: ["123"] } } };
+
+    expect(
+      synologyChatApprovalAuth.authorizeActorAction({
+        cfg,
+        senderId: "123",
+        action: "approve",
+        approvalKind: "plugin",
+      }),
+    ).toEqual({ authorized: true });
+  });
+});

package/src/approval-auth.ts

@@ -0,0 +1,23 @@
+// Synology Chat plugin module implements approval auth behavior.
+import {
+  createResolvedApproverActionAuthAdapter,
+  resolveApprovalApprovers,
+} from "actagent/plugin-sdk/approval-auth-runtime";
+import { resolveAccount } from "./accounts.js";
+
+function normalizeSynologyChatApproverId(value: string | number): string | undefined {
+  const trimmed = String(value).trim();
+  return /^\d+$/.test(trimmed) ? trimmed : undefined;
+}
+
+export const synologyChatApprovalAuth = createResolvedApproverActionAuthAdapter({
+  channelLabel: "Synology Chat",
+  resolveApprovers: ({ cfg, accountId }) => {
+    const account = resolveAccount(cfg ?? {}, accountId);
+    return resolveApprovalApprovers({
+      allowFrom: account.allowedUserIds,
+      normalizeApprover: normalizeSynologyChatApproverId,
+    });
+  },
+  normalizeSenderId: (value) => normalizeSynologyChatApproverId(value),
+});

package/src/channel.integration.test.ts

@@ -0,0 +1,205 @@
+// Synology Chat tests cover channel.integration plugin behavior.
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  buildChannelInboundEventContextMock,
+  dispatchReplyWithBufferedBlockDispatcher,
+  finalizeInboundContextMock,
+  registerPluginHttpRouteMock,
+  resolveAgentRouteMock,
+  setSynologyRuntimeConfigForTest,
+} from "./channel.test-mocks.js";
+import { makeFormBody, makeReq, makeRes } from "./test-http-utils.js";
+
+type _RegisteredRoute = {
+  path: string;
+  accountId: string;
+  handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};
+
+let createSynologyChatPlugin: typeof import("./channel.js").createSynologyChatPlugin;
+
+function makeStartContext<T>(cfg: T, accountId: string, abortSignal: AbortSignal) {
+  setSynologyRuntimeConfigForTest(cfg);
+  return {
+    cfg,
+    accountId,
+    log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    abortSignal,
+  };
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`expected ${label} to be a record`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireMockCall<TArgs extends unknown[]>(
+  mock: { mock: { calls: TArgs[] } },
+  index: number,
+  label: string,
+): TArgs {
+  const call = mock.mock.calls[index];
+  if (!call) {
+    throw new Error(`expected ${label}`);
+  }
+  return call;
+}
+
+describe("Synology channel wiring integration", () => {
+  beforeAll(async () => {
+    ({ createSynologyChatPlugin } = await import("./channel.js"));
+  });
+
+  beforeEach(() => {
+    registerPluginHttpRouteMock.mockClear();
+    dispatchReplyWithBufferedBlockDispatcher.mockClear();
+    buildChannelInboundEventContextMock.mockClear();
+    finalizeInboundContextMock.mockClear();
+    resolveAgentRouteMock.mockClear();
+    setSynologyRuntimeConfigForTest({});
+  });
+
+  it("registers real webhook handler with resolved account config and enforces allowlist", async () => {
+    const plugin = createSynologyChatPlugin();
+    const abortController = new AbortController();
+    const cfg = {
+      channels: {
+        "synology-chat": {
+          enabled: true,
+          accounts: {
+            alerts: {
+              enabled: true,
+              token: "valid-token",
+              incomingUrl: "https://nas.example.com/incoming",
+              webhookPath: "/webhook/synology-alerts",
+              dmPolicy: "allowlist",
+              allowedUserIds: ["456"],
+            },
+          },
+        },
+      },
+    };
+
+    const started = plugin.gateway.startAccount(
+      makeStartContext(cfg, "alerts", abortController.signal),
+    );
+    expect(registerPluginHttpRouteMock).toHaveBeenCalledTimes(1);
+
+    const firstCall = registerPluginHttpRouteMock.mock.calls[0];
+    if (!firstCall) {
+      throw new Error("Expected registerPluginHttpRoute to be called");
+    }
+    const registered = firstCall[0];
+    expect(registered.path).toBe("/webhook/synology-alerts");
+    expect(registered.accountId).toBe("alerts");
+
+    const req = makeReq(
+      "POST",
+      makeFormBody({
+        token: "valid-token",
+        user_id: "123",
+        username: "unauthorized-user",
+        text: "Hello",
+      }),
+    );
+    const res = makeRes();
+    await registered.handler(req, res);
+
+    expect(res.status).toBe(403);
+    expect(res.body).toContain("not authorized");
+    expect(dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    abortController.abort();
+    await started;
+  });
+
+  it("isolates same user_id across different accounts", async () => {
+    const plugin = createSynologyChatPlugin();
+    const alphaAbortController = new AbortController();
+    const betaAbortController = new AbortController();
+    const cfg = {
+      channels: {
+        "synology-chat": {
+          enabled: true,
+          accounts: {
+            alpha: {
+              enabled: true,
+              token: "token-alpha",
+              incomingUrl: "https://nas.example.com/incoming-alpha",
+              webhookPath: "/webhook/synology-alpha",
+              dmPolicy: "open",
+              allowedUserIds: ["*"],
+            },
+            beta: {
+              enabled: true,
+              token: "token-beta",
+              incomingUrl: "https://nas.example.com/incoming-beta",
+              webhookPath: "/webhook/synology-beta",
+              dmPolicy: "open",
+              allowedUserIds: ["*"],
+            },
+          },
+        },
+      },
+      session: {
+        dmScope: "main" as const,
+      },
+    };
+
+    const alphaStarted = plugin.gateway.startAccount(
+      makeStartContext(cfg, "alpha", alphaAbortController.signal),
+    );
+    const betaStarted = plugin.gateway.startAccount(
+      makeStartContext(cfg, "beta", betaAbortController.signal),
+    );
+
+    expect(registerPluginHttpRouteMock).toHaveBeenCalledTimes(2);
+    const [alphaRoute] = requireMockCall(registerPluginHttpRouteMock, 0, "alpha Synology route");
+    const [betaRoute] = requireMockCall(registerPluginHttpRouteMock, 1, "beta Synology route");
+
+    const alphaReq = makeReq(
+      "POST",
+      makeFormBody({
+        token: "token-alpha",
+        user_id: "123",
+        username: "alice",
+        text: "alpha secret",
+      }),
+    );
+    const alphaRes = makeRes();
+    await alphaRoute.handler(alphaReq, alphaRes);
+
+    const betaReq = makeReq(
+      "POST",
+      makeFormBody({
+        token: "token-beta",
+        user_id: "123",
+        username: "bob",
+        text: "beta secret",
+      }),
+    );
+    const betaRes = makeRes();
+    await betaRoute.handler(betaReq, betaRes);
+
+    expect(alphaRes.status).toBe(204);
+    expect(betaRes.status).toBe(204);
+    expect(dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(2);
+    expect(finalizeInboundContextMock).toHaveBeenCalledTimes(2);
+
+    const [alphaCtx] = requireMockCall(finalizeInboundContextMock, 0, "alpha inbound context");
+    const [betaCtx] = requireMockCall(finalizeInboundContextMock, 1, "beta inbound context");
+    const alphaContext = requireRecord(alphaCtx, "alpha inbound context");
+    expect(alphaContext.AccountId).toBe("alpha");
+    expect(alphaContext.SessionKey).toBe("agent:agent-alpha:synology-chat:alpha:direct:123");
+    const betaContext = requireRecord(betaCtx, "beta inbound context");
+    expect(betaContext.AccountId).toBe("beta");
+    expect(betaContext.SessionKey).toBe("agent:agent-beta:synology-chat:beta:direct:123");
+
+    alphaAbortController.abort();
+    betaAbortController.abort();
+    await alphaStarted;
+    await betaStarted;
+  });
+});