@downcity/plugins 1.0.4

package/src/auth/Plugin.ts

@@ -0,0 +1,221 @@
+/**
+ * Auth Plugin。
+ *
+ * 关键点（中文）
+ * - auth 是内建且必需的 plugin，不走可选启停语义。
+ * - 静态授权配置与动态观测态都收敛在项目 `.downcity/chat/authorization/`。
+ * - auth plugin 只负责统一暴露扩展点 / action 边界，不再依赖宿主平台读写授权配置。
+ */
+
+import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
+import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import { CHAT_PLUGIN_POINTS } from "@/chat/runtime/PluginPoints.js";
+import {
+  AUTH_ACTIONS,
+  type AuthObservePrincipalPayload,
+  type AuthSetUserRolePayload,
+  type AuthWriteConfigPayload,
+  type ChatAuthorizationConfig,
+  type ChatAuthorizationEvaluateInput,
+  type ChatAuthorizationSnapshot,
+} from "@/auth/types/AuthPlugin.js";
+import {
+  readChatAuthorizationConfig,
+  setChatAuthorizationUserRole,
+  writeChatAuthorizationConfig,
+} from "@/auth/runtime/AuthorizationConfig.js";
+import {
+  evaluateIncomingChatAuthorization,
+  resolveAuthorizedUserRole,
+} from "@/auth/runtime/AuthorizationPolicy.js";
+import {
+  readAuthorizationSnapshot,
+  recordObservedAuthorizationPrincipal,
+} from "@/auth/runtime/AuthorizationStore.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+
+function toChannel(value: unknown): ChatDispatchChannel | null {
+  const text = String(value || "").trim().toLowerCase();
+  if (text === "telegram" || text === "feishu" || text === "qq") return text;
+  return null;
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function toEvaluateInput(payload: Record<string, unknown>): ChatAuthorizationEvaluateInput {
+  const channel = toChannel(payload.channel);
+  if (!channel) {
+    throw new Error("auth.authorize_incoming requires a valid channel");
+  }
+  return {
+    channel,
+    chatId: String(payload.chatId || "").trim(),
+    ...(typeof payload.chatType === "string" ? { chatType: payload.chatType.trim() } : {}),
+    ...(typeof payload.userId === "string" ? { userId: payload.userId.trim() } : {}),
+    ...(typeof payload.username === "string" ? { username: payload.username.trim() } : {}),
+    ...(typeof payload.chatTitle === "string" ? { chatTitle: payload.chatTitle.trim() } : {}),
+  };
+}
+
+function toSnapshotData(snapshot: ChatAuthorizationSnapshot): JsonValue {
+  return {
+    config: snapshot.config as unknown as JsonValue,
+    users: snapshot.users as unknown as JsonValue,
+    chats: snapshot.chats as unknown as JsonValue,
+  };
+}
+
+function createAuthPluginDefinition(): Plugin {
+  return {
+    name: "auth",
+  title: "User Authorization System",
+  description:
+    "Controls who can talk to the agent in chat channels, records observed users and chats, and resolves each user's effective role for downstream service decisions.",
+  availability() {
+    return {
+      enabled: true,
+      available: true,
+      reasons: [],
+    };
+  },
+  hooks: {
+    guard: {
+      [CHAT_PLUGIN_POINTS.authorizeIncoming]: [
+        async ({ context, value }) => {
+          const input =
+            value && typeof value === "object" && !Array.isArray(value)
+              ? (value as Record<string, unknown>)
+              : {};
+          const evaluateInput = toEvaluateInput(input);
+          const authorizationConfig = readChatAuthorizationConfig(context);
+          const result = evaluateIncomingChatAuthorization({
+            config: context.config,
+            channel: evaluateInput.channel,
+            input: evaluateInput,
+            authorizationConfig,
+          });
+          if (result.decision !== "allow") {
+            throw new Error(result.reason || "chat authorization blocked");
+          }
+        },
+      ],
+    },
+    effect: {
+      [CHAT_PLUGIN_POINTS.observePrincipal]: [
+        async ({ context, value }) => {
+          const input = toRecord(value) as unknown as AuthObservePrincipalPayload;
+          const channel = toChannel(input.channel);
+          if (!channel) {
+            throw new Error("chat.observePrincipal requires a valid channel");
+          }
+          await recordObservedAuthorizationPrincipal({
+            context,
+            channel,
+            chatId: String(input.chatId || "").trim(),
+            ...(typeof input.chatType === "string" ? { chatType: input.chatType.trim() } : {}),
+            ...(typeof input.chatTitle === "string" ? { chatTitle: input.chatTitle.trim() } : {}),
+            ...(typeof input.userId === "string" ? { userId: input.userId.trim() } : {}),
+            ...(typeof input.username === "string" ? { username: input.username.trim() } : {}),
+          });
+        },
+      ],
+    },
+  },
+  resolves: {
+    [CHAT_PLUGIN_POINTS.resolveUserRole]: async ({ context, value }) => {
+      const input =
+        value && typeof value === "object" && !Array.isArray(value)
+          ? (value as Record<string, unknown>)
+          : {};
+      const channel = toChannel(input.channel);
+      if (!channel) {
+        throw new Error("chat.resolveUserRole requires a valid channel");
+      }
+      const role = resolveAuthorizedUserRole({
+        channel,
+        userId: String(input.userId || "").trim(),
+        rootPath: context.rootPath,
+      });
+      return ((role || null) as unknown) as JsonValue;
+    },
+  },
+  actions: {
+    [AUTH_ACTIONS.snapshot]: {
+      execute: async ({ context }) => {
+        const snapshot = await readAuthorizationSnapshot({
+          context,
+        });
+        return {
+          success: true,
+          data: toSnapshotData(snapshot),
+        };
+      },
+    },
+    [AUTH_ACTIONS.readConfig]: {
+      execute: async ({ context }) => {
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+    [AUTH_ACTIONS.writeConfig]: {
+      execute: async ({ context, payload }) => {
+        const body = toRecord(payload) as unknown as AuthWriteConfigPayload;
+        const nextConfig =
+          body.config && typeof body.config === "object" && !Array.isArray(body.config)
+            ? (body.config as ChatAuthorizationConfig)
+            : {};
+        await writeChatAuthorizationConfig({
+          context,
+          nextConfig,
+        });
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+    [AUTH_ACTIONS.setUserRole]: {
+      execute: async ({ context, payload }) => {
+        const body = toRecord(payload) as unknown as AuthSetUserRolePayload;
+        const channel = toChannel(body.channel);
+        if (!channel) {
+          return {
+            success: false,
+            error: "set-user-role requires a valid channel",
+            message: "set-user-role requires a valid channel",
+          };
+        }
+        await setChatAuthorizationUserRole({
+          context,
+          channel,
+          userId: String(body.userId || "").trim(),
+          roleId: String(body.roleId || "").trim(),
+        });
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+  },
+  };
+}
+
+/**
+ * AuthPlugin：统一承载授权能力。
+ */
+export class AuthPlugin extends BasePlugin {
+  readonly name = "auth";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createAuthPluginDefinition());
+  }
+}

package/src/auth/runtime/AuthorizationConfig.ts

@@ -0,0 +1,247 @@
+/**
+ * Auth 授权配置读写工具。
+ *
+ * 关键点（中文）
+ * - 静态授权规则直接存放在项目 `.downcity/chat/authorization/config.json`。
+ * - 授权核心模型为 role / permission / binding。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ChatAuthorizationConfig,
+  ChatAuthorizationChannel,
+  ChatAuthorizationPermission,
+  ChatAuthorizationRole,
+  ChatChannelAuthorizationConfig,
+} from "@/auth/types/AuthPlugin.js";
+import {
+  CHAT_AUTHORIZATION_CHANNELS,
+  CHAT_AUTHORIZATION_PERMISSIONS,
+  createDefaultChatAuthorizationRoles,
+} from "@/auth/types/AuthPlugin.js";
+
+const CHANNELS: ChatAuthorizationChannel[] = [...CHAT_AUTHORIZATION_CHANNELS];
+
+export const DEFAULT_CHAT_AUTHORIZATION_PERMISSIONS: ChatAuthorizationPermission[] = [
+  ...CHAT_AUTHORIZATION_PERMISSIONS,
+];
+
+function normalizeText(value: unknown): string | undefined {
+  const text = String(value || "").trim();
+  return text ? text : undefined;
+}
+
+function normalizePermissionList(values: unknown[] | undefined): ChatAuthorizationPermission[] {
+  const allowed = new Set<string>(DEFAULT_CHAT_AUTHORIZATION_PERMISSIONS);
+  if (!Array.isArray(values)) return [];
+  return [
+    ...new Set(
+      values
+        .map((value) => normalizeText(value))
+        .filter(
+          (value): value is ChatAuthorizationPermission =>
+            Boolean(value && allowed.has(value)),
+        ),
+    ),
+  ];
+}
+
+function buildDefaultRole(roleId: "default" | "member" | "admin"): ChatAuthorizationRole {
+  return createDefaultChatAuthorizationRoles()[roleId];
+}
+
+function normalizeRoleMap(input: unknown): Record<string, ChatAuthorizationRole> {
+  const defaultRoles = createDefaultChatAuthorizationRoles();
+  if (!input || typeof input !== "object" || Array.isArray(input)) return defaultRoles;
+  const roles: Record<string, ChatAuthorizationRole> = {};
+  for (const [rawRoleId, rawRole] of Object.entries(input)) {
+    const roleId = normalizeText(rawRoleId);
+    if (!roleId) continue;
+    const roleObj =
+      rawRole && typeof rawRole === "object" && !Array.isArray(rawRole)
+        ? (rawRole as {
+            name?: unknown;
+            description?: unknown;
+            permissions?: unknown[];
+            roleId?: unknown;
+          })
+        : null;
+    if (!roleObj) continue;
+    const builtinRole = defaultRoles[roleId];
+    roles[roleId] = {
+      roleId,
+      name: normalizeText(roleObj.name) || builtinRole?.name || roleId,
+      ...(normalizeText(roleObj.description) || builtinRole?.description
+        ? {
+            description:
+              normalizeText(roleObj.description) || builtinRole?.description || undefined,
+          }
+        : {}),
+      permissions: normalizePermissionList(roleObj.permissions),
+    };
+  }
+  if (Object.keys(roles).length === 0) return defaultRoles;
+  if (!roles.default) roles.default = buildDefaultRole("default");
+  return roles;
+}
+
+function normalizeBindingMap(
+  input: unknown,
+  roles: Record<string, ChatAuthorizationRole>,
+): Record<string, string> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+  const out: Record<string, string> = {};
+  for (const [rawId, rawRoleId] of Object.entries(input)) {
+    const entityId = normalizeText(rawId);
+    const roleId = normalizeText(rawRoleId);
+    if (!entityId || !roleId || !roles[roleId]) continue;
+    out[entityId] = roleId;
+  }
+  return out;
+}
+
+function normalizeChannelConfig(
+  input: unknown,
+  roles: Record<string, ChatAuthorizationRole>,
+): ChatChannelAuthorizationConfig {
+  const raw =
+    input && typeof input === "object" && !Array.isArray(input)
+      ? (input as {
+          defaultUserRoleId?: unknown;
+          userRoles?: unknown;
+        })
+      : {};
+  const defaultUserRoleId = normalizeText(raw.defaultUserRoleId) || "default";
+  return {
+    defaultUserRoleId: roles[defaultUserRoleId] ? defaultUserRoleId : "default",
+    userRoles: normalizeBindingMap(raw.userRoles, roles),
+  };
+}
+
+function normalizeAuthorizationConfig(input: unknown): ChatAuthorizationConfig {
+  const raw =
+    input && typeof input === "object" && !Array.isArray(input)
+      ? (input as { roles?: unknown; channels?: Record<string, unknown> })
+      : {};
+  const roles = normalizeRoleMap(raw.roles);
+  const channels: Partial<Record<ChatAuthorizationChannel, ChatChannelAuthorizationConfig>> = {};
+  for (const channel of CHANNELS) {
+    channels[channel] = normalizeChannelConfig(raw.channels?.[channel], roles);
+  }
+  return { roles, channels };
+}
+
+function cloneAuthorizationConfig(
+  input: ChatAuthorizationConfig | undefined,
+): ChatAuthorizationConfig {
+  return normalizeAuthorizationConfig(input ? JSON.parse(JSON.stringify(input)) : {});
+}
+
+function getChatAuthorizationConfigPath(projectRoot: string): string {
+  return path.join(projectRoot, ".downcity", "chat", "authorization", "config.json");
+}
+
+function readAuthorizationConfigFromProjectRoot(projectRoot: string): ChatAuthorizationConfig {
+  const normalizedProjectRoot = normalizeText(projectRoot);
+  if (!normalizedProjectRoot) return normalizeAuthorizationConfig({});
+  const file = getChatAuthorizationConfigPath(normalizedProjectRoot);
+  if (!fs.existsSync(file)) return normalizeAuthorizationConfig({});
+  try {
+    return normalizeAuthorizationConfig(fs.readJsonSync(file));
+  } catch {
+    return normalizeAuthorizationConfig({});
+  }
+}
+
+async function writeAuthorizationConfigToPlatform(params: {
+  projectRoot: string;
+  nextConfig: ChatAuthorizationConfig;
+}): Promise<void> {
+  const normalizedProjectRoot = normalizeText(params.projectRoot);
+  if (!normalizedProjectRoot) throw new Error("projectRoot is required");
+  const file = getChatAuthorizationConfigPath(normalizedProjectRoot);
+  await fs.ensureDir(path.dirname(file));
+  await fs.writeJson(file, normalizeAuthorizationConfig(params.nextConfig), {
+    spaces: 2,
+  });
+}
+
+function ensureChannelConfig(
+  config: ChatAuthorizationConfig,
+  channel: ChatAuthorizationChannel,
+): ChatChannelAuthorizationConfig {
+  config.roles = normalizeRoleMap(config.roles);
+  config.channels ??= {};
+  config.channels[channel] = normalizeChannelConfig(config.channels[channel], config.roles);
+  return config.channels[channel] as ChatChannelAuthorizationConfig;
+}
+
+/**
+ * 同步读取当前 agent 的授权配置。
+ */
+export function readChatAuthorizationConfigSync(projectRoot: string): ChatAuthorizationConfig {
+  return readAuthorizationConfigFromProjectRoot(projectRoot);
+}
+
+/**
+ * 读取当前 agent 的授权配置。
+ */
+export function readChatAuthorizationConfig(
+  contextOrProjectRoot: Pick<AgentContext, "rootPath"> | string,
+): ChatAuthorizationConfig {
+  if (typeof contextOrProjectRoot === "string") {
+    return readAuthorizationConfigFromProjectRoot(contextOrProjectRoot);
+  }
+  return readAuthorizationConfigFromProjectRoot(contextOrProjectRoot.rootPath);
+}
+
+/**
+ * 覆盖写入整份授权配置。
+ */
+export async function writeChatAuthorizationConfig(params: {
+  context: Pick<AgentContext, "rootPath">;
+  nextConfig: ChatAuthorizationConfig;
+}): Promise<void> {
+  await writeAuthorizationConfigToPlatform({
+    projectRoot: params.context.rootPath,
+    nextConfig: params.nextConfig,
+  });
+}
+
+/**
+ * 读取角色列表。
+ */
+export function listChatAuthorizationRoles(params: {
+  config: ChatAuthorizationConfig;
+}): ChatAuthorizationRole[] {
+  const config = normalizeAuthorizationConfig(params.config);
+  return Object.values(config.roles || {}).sort((a, b) => a.roleId.localeCompare(b.roleId));
+}
+
+/**
+ * 设置用户角色。
+ */
+export async function setChatAuthorizationUserRole(params: {
+  context: Pick<AgentContext, "rootPath">;
+  channel: ChatAuthorizationChannel;
+  userId: string;
+  roleId: string;
+}): Promise<void> {
+  const userId = normalizeText(params.userId);
+  const roleId = normalizeText(params.roleId);
+  if (!userId || !roleId) throw new Error("userId and roleId are required");
+  const authorization = cloneAuthorizationConfig(
+    readAuthorizationConfigFromProjectRoot(params.context.rootPath),
+  );
+  authorization.roles = normalizeRoleMap(authorization.roles);
+  const channelConfig = ensureChannelConfig(authorization, params.channel);
+  if (!authorization.roles?.[roleId]) throw new Error(`Unknown roleId: ${roleId}`);
+  channelConfig.userRoles ??= {};
+  channelConfig.userRoles[userId] = roleId;
+  await writeAuthorizationConfigToPlatform({
+    projectRoot: params.context.rootPath,
+    nextConfig: authorization,
+  });
+}

package/src/auth/runtime/AuthorizationPolicy.ts

@@ -0,0 +1,167 @@
+/**
+ * Auth 授权判定逻辑。
+ *
+ * 关键点（中文）
+ * - 角色模型替代旧的 allowlist/pairing 模型。
+ * - 判定统一走“用户角色 + 权限集合”，群聊只看发言用户自身权限。
+ */
+
+import type { DowncityConfig } from "@downcity/agent/internal/types/config/DowncityConfig.js";
+import type {
+  ChatAuthorizationConfig,
+  ChatAuthorizationChannel,
+  ChatAuthorizationEvaluateInput,
+  ChatAuthorizationEvaluateResult,
+  ChatAuthorizationPermission,
+  ChatAuthorizationRole,
+  ChatChannelAuthorizationConfig,
+} from "@/auth/types/AuthPlugin.js";
+import { createDefaultChatAuthorizationRoles } from "@/auth/types/AuthPlugin.js";
+import { readChatAuthorizationConfigSync } from "@/auth/runtime/AuthorizationConfig.js";
+
+function normalizeText(value: unknown): string | undefined {
+  const text = String(value || "").trim();
+  return text ? text : undefined;
+}
+
+function isDirectMessage(channel: ChatAuthorizationChannel, chatType?: string): boolean {
+  const type = String(chatType || "").trim().toLowerCase();
+  if (!type) return true;
+  if (channel === "telegram") return type === "private";
+  if (channel === "feishu") return type === "p2p";
+  if (channel === "qq") return type === "private" || type === "c2c";
+  return false;
+}
+
+function resolveAuthorizationRoles(
+  authorizationConfig?: ChatAuthorizationConfig,
+): Record<string, ChatAuthorizationRole> {
+  const raw = authorizationConfig?.roles;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return createDefaultChatAuthorizationRoles();
+  }
+  return Object.keys(raw).length > 0 ? raw : createDefaultChatAuthorizationRoles();
+}
+
+function resolveChannelAuthorizationConfig(
+  channel: ChatAuthorizationChannel,
+  authorizationConfig?: ChatAuthorizationConfig,
+): ChatChannelAuthorizationConfig {
+  const raw = authorizationConfig?.channels?.[channel];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return {
+      defaultUserRoleId: "default",
+      userRoles: {},
+    };
+  }
+  return raw;
+}
+
+function resolveRole(
+  roleId: string | undefined,
+  roles: Record<string, ChatAuthorizationRole> | undefined,
+): ChatAuthorizationRole {
+  if (roleId && roles?.[roleId]) return roles[roleId];
+  if (roles?.default) return roles.default;
+  return { roleId: "default", name: "Default", permissions: [] };
+}
+
+function hasPermission(
+  role: ChatAuthorizationRole,
+  permission: ChatAuthorizationPermission,
+): boolean {
+  return role.permissions.includes(permission);
+}
+
+function resolveUserRole(params: {
+  roles: Record<string, ChatAuthorizationRole>;
+  channelConfig: ChatChannelAuthorizationConfig;
+  userId?: string;
+}): ChatAuthorizationRole {
+  const userId = normalizeText(params.userId);
+  const defaultRoleId = normalizeText(params.channelConfig.defaultUserRoleId) || "default";
+  const boundRoleId = userId ? normalizeText(params.channelConfig.userRoles?.[userId]) : undefined;
+  return resolveRole(boundRoleId || defaultRoleId, params.roles);
+}
+
+/**
+ * 解析用户授权角色。
+ */
+export function resolveAuthorizedUserRole(params: {
+  channel: ChatAuthorizationChannel;
+  userId?: string;
+  authorizationConfig?: ChatAuthorizationConfig;
+  rootPath?: string;
+}): ChatAuthorizationRole | undefined {
+  const userId = normalizeText(params.userId);
+  if (!userId) return undefined;
+  const authorizationConfig =
+    params.authorizationConfig ||
+    (params.rootPath
+      ? readChatAuthorizationConfigSync(params.rootPath)
+      : undefined);
+  const roles = resolveAuthorizationRoles(authorizationConfig);
+  const channelConfig = resolveChannelAuthorizationConfig(params.channel, authorizationConfig);
+  return resolveUserRole({
+    roles,
+    channelConfig,
+    userId,
+  });
+}
+
+/**
+ * 执行入站授权判定。
+ */
+export function evaluateIncomingChatAuthorization(params: {
+  config: DowncityConfig;
+  channel: ChatAuthorizationChannel;
+  input: ChatAuthorizationEvaluateInput;
+  authorizationConfig?: ChatAuthorizationConfig;
+}): ChatAuthorizationEvaluateResult {
+  const channelConfig = resolveChannelAuthorizationConfig(
+    params.channel,
+    params.authorizationConfig,
+  );
+  const roles = resolveAuthorizationRoles(params.authorizationConfig);
+  const direct = isDirectMessage(params.channel, params.input.chatType);
+  const userRole = resolveUserRole({
+    roles,
+    channelConfig,
+    userId: params.input.userId,
+  });
+  const isOwner = hasPermission(userRole, "agent.manage");
+
+  if (direct) {
+    return hasPermission(userRole, "chat.dm.use")
+      ? {
+          decision: "allow",
+          isOwner,
+          userRoleId: userRole.roleId,
+          userPermissions: [...userRole.permissions],
+          reason: "dm_role_allowed",
+        }
+      : {
+          decision: "block",
+          isOwner,
+          userRoleId: userRole.roleId,
+          userPermissions: [...userRole.permissions],
+          reason: "dm_role_blocked",
+        };
+  }
+
+  return hasPermission(userRole, "chat.group.use")
+    ? {
+        decision: "allow",
+        isOwner,
+        userRoleId: userRole.roleId,
+        userPermissions: [...userRole.permissions],
+        reason: "group_user_role_allowed",
+      }
+    : {
+        decision: "block",
+        isOwner,
+        userRoleId: userRole.roleId,
+        userPermissions: [...userRole.permissions],
+        reason: "user_group_permission_blocked",
+      };
+}