@nextclaw/channel-plugin-feishu 0.2.29-beta.0 → 0.2.29-beta.2

package/dist/src/nextclaw-sdk/secrets-prompt.js

@@ -0,0 +1,193 @@
+import { DEFAULT_SECRET_PROVIDER_ALIAS, ENV_SECRET_REF_ID_RE, formatExecSecretRefIdValidationMessage, isValidExecSecretRefId, isValidFileSecretRefId } from "./secrets-core.js";
+import fs from "node:fs";
+//#region src/nextclaw-sdk/secrets-prompt.ts
+function resolveDefaultSecretProviderAlias(cfg, source) {
+	const configured = source === "env" ? cfg.secrets?.defaults?.env : source === "file" ? cfg.secrets?.defaults?.file : cfg.secrets?.defaults?.exec;
+	if (configured?.trim()) return configured.trim();
+	const providers = cfg.secrets?.providers;
+	if (providers) {
+		for (const [name, provider] of Object.entries(providers)) if (provider?.source === source) return name;
+	}
+	return DEFAULT_SECRET_PROVIDER_ALIAS;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJsonPointerValue(payload, pointer) {
+	if (pointer === "value") return typeof payload === "string" ? payload : null;
+	const segments = pointer.slice(1).split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+	let cursor = payload;
+	for (const segment of segments) {
+		if (!isRecord(cursor) && !Array.isArray(cursor)) return null;
+		cursor = cursor[segment];
+	}
+	return typeof cursor === "string" ? cursor : null;
+}
+function tryResolveFileProviderValue(cfg, provider, id) {
+	const providerConfig = cfg.secrets?.providers?.[provider];
+	if (!providerConfig || providerConfig.source !== "file" || !providerConfig.path) return null;
+	try {
+		const raw = fs.readFileSync(providerConfig.path, "utf-8");
+		if (providerConfig.mode === "singleValue") return raw.trim();
+		return readJsonPointerValue(JSON.parse(raw), id);
+	} catch {
+		return null;
+	}
+}
+function promptSingleChannelToken(params) {
+	const promptToken = async () => String(await params.prompter.text({
+		message: params.inputPrompt,
+		validate: (value) => value?.trim() ? void 0 : "Required"
+	})).trim();
+	return (async () => {
+		if (params.canUseEnv) {
+			if (await params.prompter.confirm({
+				message: params.envPrompt,
+				initialValue: true
+			})) return {
+				useEnv: true,
+				token: null
+			};
+			return {
+				useEnv: false,
+				token: await promptToken()
+			};
+		}
+		if (params.hasConfigToken && params.accountConfigured) {
+			if (await params.prompter.confirm({
+				message: params.keepPrompt,
+				initialValue: true
+			})) return {
+				useEnv: false,
+				token: null
+			};
+		}
+		return {
+			useEnv: false,
+			token: await promptToken()
+		};
+	})();
+}
+async function resolveSecretInputMode(params) {
+	if (params.explicitMode) return params.explicitMode;
+	return await params.prompter.select({
+		message: `How do you want to provide this ${params.credentialLabel}?`,
+		initialValue: "plaintext",
+		options: [{
+			value: "plaintext",
+			label: `Enter ${params.credentialLabel}`,
+			hint: "Stores the credential directly in NextClaw config"
+		}, {
+			value: "ref",
+			label: "Use secret reference",
+			hint: "Stores a reference to env or configured secret providers"
+		}]
+	});
+}
+async function promptSecretRefForSetup(params) {
+	const providers = Object.entries(params.cfg.secrets?.providers ?? {}).filter(([, provider]) => provider?.source === "file" || provider?.source === "exec");
+	if (await params.prompter.select({
+		message: "Where is this secret stored?",
+		initialValue: "env",
+		options: [{
+			value: "env",
+			label: "Environment variable",
+			hint: "Reference an env var"
+		}, ...providers.length > 0 ? [{
+			value: "provider",
+			label: "Configured provider",
+			hint: "Reference file/exec provider"
+		}] : []]
+	}) === "env") {
+		const envVar = String(await params.prompter.text({
+			message: "Environment variable name",
+			initialValue: params.preferredEnvVar,
+			placeholder: params.preferredEnvVar ?? "NEXTCLAW_SECRET",
+			validate: (value) => {
+				const candidate = value.trim();
+				if (!ENV_SECRET_REF_ID_RE.test(candidate)) return "Use an env var name like \"OPENAI_API_KEY\".";
+				if (!process.env[candidate]?.trim()) return `Environment variable "${candidate}" is missing or empty in this session.`;
+			}
+		})).trim();
+		return {
+			value: {
+				source: "env",
+				provider: resolveDefaultSecretProviderAlias(params.cfg, "env"),
+				id: envVar
+			},
+			resolvedValue: process.env[envVar]?.trim() ?? ""
+		};
+	}
+	const provider = await params.prompter.select({
+		message: "Select secret provider",
+		initialValue: providers[0]?.[0],
+		options: providers.map(([name, providerConfig]) => ({
+			value: name,
+			label: name,
+			hint: providerConfig?.source === "exec" ? "Exec provider" : "File provider"
+		}))
+	});
+	const providerConfig = params.cfg.secrets?.providers?.[provider];
+	const id = String(await params.prompter.text({
+		message: providerConfig?.source === "file" ? "Secret id (JSON pointer, or 'value' for singleValue mode)" : "Secret id for the exec provider",
+		initialValue: providerConfig?.source === "file" ? "/providers/feishu/appSecret" : void 0,
+		validate: (value) => {
+			const candidate = value.trim();
+			if (!candidate) return "Required";
+			if (providerConfig?.source === "file") return isValidFileSecretRefId(candidate) ? void 0 : "Invalid file secret reference id.";
+			return isValidExecSecretRefId(candidate) ? void 0 : formatExecSecretRefIdValidationMessage();
+		}
+	})).trim();
+	const resolvedValue = providerConfig?.source === "file" ? tryResolveFileProviderValue(params.cfg, provider, id) ?? "" : "";
+	if (!resolvedValue && providerConfig?.source === "exec") await params.prompter.note("Exec provider reference saved. Connection probe will rely on runtime secret resolution later.", "Secret reference saved");
+	return {
+		value: {
+			source: providerConfig?.source === "exec" ? "exec" : "file",
+			provider,
+			id
+		},
+		resolvedValue
+	};
+}
+async function promptSingleChannelSecretInput(params) {
+	if (await resolveSecretInputMode({
+		prompter: params.prompter,
+		explicitMode: params.secretInputMode,
+		credentialLabel: params.credentialLabel
+	}) === "plaintext") {
+		const plainResult = await promptSingleChannelToken({
+			prompter: params.prompter,
+			accountConfigured: params.accountConfigured,
+			canUseEnv: params.canUseEnv,
+			hasConfigToken: params.hasConfigToken,
+			envPrompt: params.envPrompt,
+			keepPrompt: params.keepPrompt,
+			inputPrompt: params.inputPrompt
+		});
+		if (plainResult.useEnv) return { action: "use-env" };
+		if (plainResult.token) return {
+			action: "set",
+			value: plainResult.token,
+			resolvedValue: plainResult.token
+		};
+		return { action: "keep" };
+	}
+	if (params.hasConfigToken && params.accountConfigured) {
+		if (await params.prompter.confirm({
+			message: params.keepPrompt,
+			initialValue: true
+		})) return { action: "keep" };
+	}
+	const refResult = await promptSecretRefForSetup({
+		cfg: params.cfg,
+		prompter: params.prompter,
+		preferredEnvVar: params.preferredEnvVar
+	});
+	return {
+		action: "set",
+		value: refResult.value,
+		resolvedValue: refResult.resolvedValue
+	};
+}
+//#endregion
+export { promptSingleChannelSecretInput };

package/dist/src/nextclaw-sdk/secrets.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/src/nextclaw-sdk/secrets.js

@@ -0,0 +1,4 @@
+import "./secrets-core.js";
+import "./secrets-config.js";
+import "./secrets-prompt.js";
+export {};

package/dist/src/nextclaw-sdk/types.d.ts

@@ -0,0 +1,242 @@
+//#region src/nextclaw-sdk/types.d.ts
+type LogFn = (message: string) => void;
+type SecretRefSource = "env" | "file" | "exec";
+type DmPolicy = "open" | "pairing" | "allowlist";
+type BaseProbeResult<TTarget = string> = {
+  ok: boolean;
+  target?: TTarget;
+  error?: string;
+  [key: string]: unknown;
+};
+type ChannelMeta = {
+  id: string;
+  label: string;
+  selectionLabel?: string;
+  docsPath?: string;
+  docsLabel?: string;
+  blurb?: string;
+  aliases?: string[];
+  order?: number;
+  [key: string]: unknown;
+};
+type ChannelPlugin<ResolvedAccount = unknown> = {
+  id: string;
+  meta: ChannelMeta;
+  config?: Record<string, unknown>;
+  onboarding?: ChannelOnboardingAdapter;
+  [key: string]: unknown;
+  __resolvedAccountType__?: ResolvedAccount;
+};
+type AnyAgentTool = {
+  name?: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+  execute?: (toolCallId: string, params: unknown) => Promise<unknown> | unknown;
+  [key: string]: unknown;
+};
+type ResolvedAgentRoute = {
+  agentId?: string;
+  sessionKey?: string;
+  [key: string]: unknown;
+};
+type InboundDebouncer<T> = {
+  run: (key: string, value: T, task: (value: T) => Promise<void>) => void;
+  clear: () => void;
+};
+type PluginRuntime = {
+  version?: string;
+  config: {
+    loadConfig?: () => OpenClawConfig;
+    writeConfigFile: (next: OpenClawConfig) => Promise<void>;
+  };
+  logging: {
+    shouldLogVerbose: () => boolean;
+  };
+  media: {
+    detectMime: (params: {
+      buffer: Buffer;
+    }) => Promise<string | undefined>;
+    loadWebMedia: (url: string, options?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  };
+  channel: {
+    media: {
+      fetchRemoteMedia: (params: {
+        url: string;
+        maxBytes?: number;
+      }) => Promise<Record<string, unknown>>;
+      saveMediaBuffer: (buffer: Buffer, contentType?: string, direction?: string, maxBytes?: number) => Promise<{
+        path: string;
+        contentType?: string;
+      }>;
+    };
+    text: {
+      chunkMarkdownText: (text: string, limit: number) => string[];
+      resolveMarkdownTableMode: (params: Record<string, unknown>) => unknown;
+      convertMarkdownTables: (text: string, mode?: unknown) => string;
+      resolveTextChunkLimit: (cfg: OpenClawConfig, channel: string, accountId?: string, options?: Record<string, unknown>) => number;
+      resolveChunkMode: (cfg: OpenClawConfig, channel: string) => string;
+      chunkTextWithMode: (text: string, limit: number, mode?: unknown) => string[];
+      hasControlCommand: (text: string, cfg: OpenClawConfig) => boolean;
+    };
+    reply: {
+      resolveEnvelopeFormatOptions: (cfg: OpenClawConfig) => Record<string, unknown>;
+      formatAgentEnvelope: (params: Record<string, unknown>) => string;
+      finalizeInboundContext: (params: Record<string, unknown>) => Record<string, unknown>;
+      withReplyDispatcher: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+      dispatchReplyFromConfig: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+      createReplyDispatcherWithTyping: (params: Record<string, unknown>) => {
+        dispatcher: unknown;
+        replyOptions: Record<string, unknown>;
+        markDispatchIdle: () => void;
+      };
+      resolveHumanDelayConfig: (cfg: OpenClawConfig, agentId: string) => unknown;
+      dispatchReplyWithBufferedBlockDispatcher?: (params: Record<string, unknown>) => Promise<void>;
+    };
+    routing: {
+      resolveAgentRoute: (params: Record<string, unknown>) => ResolvedAgentRoute | null;
+    };
+    pairing: {
+      readAllowFromStore: (params: {
+        channel: string;
+        accountId?: string;
+      }) => unknown;
+      upsertPairingRequest: (params: Record<string, unknown>) => Promise<{
+        code: string;
+        created: boolean;
+      }>;
+    };
+    commands: {
+      shouldComputeCommandAuthorized: (text: string) => boolean;
+      resolveCommandAuthorizedFromAuthorizers: (params: Record<string, unknown>) => Promise<boolean> | boolean;
+    };
+    debounce: {
+      resolveInboundDebounceMs: (params: Record<string, unknown>) => number;
+      createInboundDebouncer: <T>(params: Record<string, unknown>) => InboundDebouncer<T>;
+    };
+  };
+  [key: string]: unknown;
+};
+type RuntimeEnv = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+  warn?: (message: string) => void;
+  debug?: (message: string) => void;
+  info?: (message: string) => void;
+  [key: string]: unknown;
+};
+type OpenClawPluginApi = {
+  config: ClawdbotConfig;
+  runtime: PluginRuntime;
+  logger: {
+    info: LogFn;
+    warn: LogFn;
+    error: LogFn;
+    debug?: LogFn;
+  };
+  registerTool: (tool: AnyAgentTool | ((ctx: Record<string, unknown>) => AnyAgentTool | AnyAgentTool[] | null | undefined), opts?: {
+    name?: string;
+    names?: string[];
+    optional?: boolean;
+  }) => void;
+  registerChannel: (registration: unknown) => void;
+  [key: string]: unknown;
+};
+type WizardSelectOption<T extends string = string> = {
+  value: T;
+  label: string;
+  hint?: string;
+};
+type WizardPrompter = {
+  note: (message: string, title?: string) => Promise<void>;
+  text: (params: {
+    message: string;
+    placeholder?: string;
+    initialValue?: string;
+    validate?: (value: string) => string | undefined;
+  }) => Promise<string>;
+  confirm: (params: {
+    message: string;
+    initialValue?: boolean;
+  }) => Promise<boolean>;
+  select: <T extends string = string>(params: {
+    message: string;
+    options: WizardSelectOption<T>[];
+    initialValue?: T | string;
+  }) => Promise<T>;
+};
+type ChannelOnboardingDmPolicy = {
+  label: string;
+  channel: string;
+  policyKey: string;
+  allowFromKey: string;
+  getCurrent: (cfg: ClawdbotConfig) => DmPolicy;
+  setPolicy: (cfg: ClawdbotConfig, policy: DmPolicy) => ClawdbotConfig;
+  promptAllowFrom: (params: {
+    cfg: ClawdbotConfig;
+    prompter: WizardPrompter;
+  }) => Promise<ClawdbotConfig>;
+};
+type ChannelOnboardingAdapter = {
+  channel: string;
+  getStatus: (params: {
+    cfg: ClawdbotConfig;
+  }) => Promise<{
+    channel: string;
+    configured: boolean;
+    statusLines: string[];
+    selectionHint?: string;
+    quickstartScore?: number;
+  }>;
+  configure: (params: {
+    cfg: ClawdbotConfig;
+    prompter: WizardPrompter;
+  }) => Promise<{
+    cfg: ClawdbotConfig;
+    accountId?: string;
+  }>;
+  dmPolicy?: ChannelOnboardingDmPolicy;
+  disable?: (cfg: ClawdbotConfig) => ClawdbotConfig;
+};
+type OpenClawConfig = {
+  channels?: Record<string, Record<string, unknown> | undefined>;
+  bindings?: Array<{
+    agentId?: string;
+    match?: {
+      channel?: string;
+      peer?: {
+        kind?: string;
+        id?: string;
+      };
+    };
+  }>;
+  agents?: {
+    list?: Array<{
+      id: string;
+      workspace?: string;
+      agentDir?: string;
+      [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+  };
+  broadcast?: Record<string, string[]>;
+  secrets?: {
+    defaults?: {
+      env?: string;
+      file?: string;
+      exec?: string;
+    };
+    providers?: Record<string, {
+      source?: SecretRefSource;
+      path?: string;
+      mode?: "singleValue" | "json";
+      command?: string;
+      args?: string[];
+      [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+type ClawdbotConfig = OpenClawConfig;
+//#endregion
+export { AnyAgentTool, BaseProbeResult, ChannelMeta, ChannelOnboardingAdapter, ChannelOnboardingDmPolicy, ChannelPlugin, ClawdbotConfig, DmPolicy, OpenClawConfig, OpenClawPluginApi, PluginRuntime, RuntimeEnv, WizardPrompter };

package/dist/src/oauth.js

@@ -0,0 +1,171 @@
+import { getAllKnownScopes } from "./tool-scopes.js";
+import { getTicket } from "./lark-ticket.js";
+import { feishuFetch } from "./feishu-fetch.js";
+import { pollDeviceToken, requestDeviceAuthorization } from "./device-flow.js";
+import { getStoredToken, setStoredToken, tokenStatus } from "./token-store.js";
+import { revokeUAT } from "./uat-client.js";
+import { createUserToolClient } from "./user-tool-client.js";
+import { jsonToolResult } from "./tool-result.js";
+import { resolveRegisteredFeishuToolsConfig } from "./tool-account.js";
+import { Type } from "@sinclair/typebox";
+//#region src/oauth.ts
+const FeishuOAuthSchema = Type.Object({
+	action: Type.Union([
+		Type.Literal("authorize"),
+		Type.Literal("status"),
+		Type.Literal("revoke")
+	]),
+	scope: Type.Optional(Type.String({ description: "可选，自定义 scope 空格串；不传时默认申请当前集成能力需要的全部高价值 scope。" })),
+	wait_seconds: Type.Optional(Type.Integer({
+		description: "authorize 后轮询等待秒数，默认 15，最大 60。",
+		minimum: 0,
+		maximum: 60
+	}))
+});
+function json(data) {
+	return jsonToolResult(data);
+}
+async function verifyTokenIdentity(domain, accessToken, expectedOpenId) {
+	const data = await (await feishuFetch(`${domain === "lark" ? "https://open.larksuite.com" : "https://open.feishu.cn"}/open-apis/authen/v1/user_info`, { headers: { Authorization: `Bearer ${accessToken}` } })).json();
+	const actualOpenId = data.data?.open_id;
+	return {
+		valid: data.code === 0 && actualOpenId === expectedOpenId,
+		actualOpenId
+	};
+}
+async function handleOAuthStatus(params) {
+	const stored = await getStoredToken(params.appId, params.senderOpenId);
+	if (!stored) return json({
+		authorized: false,
+		user_open_id: params.senderOpenId
+	});
+	return json({
+		authorized: true,
+		user_open_id: params.senderOpenId,
+		scope: stored.scope,
+		token_status: tokenStatus(stored),
+		granted_at: new Date(stored.grantedAt).toISOString(),
+		expires_at: new Date(stored.expiresAt).toISOString(),
+		refresh_expires_at: new Date(stored.refreshExpiresAt).toISOString()
+	});
+}
+async function handleOAuthRevoke(params) {
+	await revokeUAT(params.appId, params.senderOpenId);
+	return json({
+		success: true,
+		user_open_id: params.senderOpenId,
+		message: "当前用户的飞书 OAuth 授权已撤销。"
+	});
+}
+async function handleOAuthAuthorize(params) {
+	const scope = params.scope?.trim() || getAllKnownScopes().join(" ");
+	const waitSeconds = Math.min(Math.max(params.waitSeconds ?? 15, 0), 60);
+	const deviceFlow = await requestDeviceAuthorization({
+		appId: params.account.appId,
+		appSecret: params.account.appSecret,
+		domain: params.account.domain,
+		scope
+	});
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), waitSeconds * 1e3);
+	try {
+		const result = await pollDeviceToken({
+			appId: params.account.appId,
+			appSecret: params.account.appSecret,
+			domain: params.account.domain,
+			deviceCode: deviceFlow.deviceCode,
+			interval: deviceFlow.interval,
+			expiresIn: deviceFlow.expiresIn,
+			signal: controller.signal
+		});
+		if (!result.ok) return json({
+			authorized: false,
+			status: result.error,
+			message: result.message,
+			user_open_id: params.senderOpenId,
+			verification_uri: deviceFlow.verificationUri,
+			verification_uri_complete: deviceFlow.verificationUriComplete,
+			user_code: deviceFlow.userCode,
+			requested_scope: scope
+		});
+		const verified = await verifyTokenIdentity(params.account.domain, result.token.accessToken, params.senderOpenId);
+		if (!verified.valid) return json({
+			authorized: false,
+			status: "identity_mismatch",
+			message: "完成授权的飞书账号与当前消息发送者不一致，已拒绝写入令牌。",
+			expected_open_id: params.senderOpenId,
+			actual_open_id: verified.actualOpenId
+		});
+		const now = Date.now();
+		await setStoredToken({
+			userOpenId: params.senderOpenId,
+			appId: params.account.appId,
+			accessToken: result.token.accessToken,
+			refreshToken: result.token.refreshToken,
+			expiresAt: now + result.token.expiresIn * 1e3,
+			refreshExpiresAt: now + result.token.refreshExpiresIn * 1e3,
+			scope: result.token.scope,
+			grantedAt: now
+		});
+		return json({
+			authorized: true,
+			user_open_id: params.senderOpenId,
+			scope: result.token.scope,
+			expires_at: new Date(now + result.token.expiresIn * 1e3).toISOString(),
+			message: "飞书 OAuth 授权成功，后续工具将按当前用户身份执行。"
+		});
+	} catch (error) {
+		if (!controller.signal.aborted) throw error;
+		return json({
+			authorized: false,
+			status: "authorization_pending",
+			message: "授权请求已创建，但在等待窗口内尚未完成。请打开链接完成授权后重新调用 feishu_oauth status 或再次 authorize。",
+			user_open_id: params.senderOpenId,
+			verification_uri: deviceFlow.verificationUri,
+			verification_uri_complete: deviceFlow.verificationUriComplete,
+			user_code: deviceFlow.userCode,
+			requested_scope: scope
+		});
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+function registerFeishuOAuthTool(api) {
+	if (!api.config) return;
+	if (!resolveRegisteredFeishuToolsConfig(api.config).oauth) return;
+	api.registerTool({
+		name: "feishu_oauth",
+		label: "Feishu OAuth",
+		description: "管理当前消息发送者的飞书 OAuth 授权。支持 authorize/status/revoke，授权后 calendar/task/sheets/identity 工具即可按本人身份执行。",
+		parameters: FeishuOAuthSchema,
+		async execute(_toolCallId, params) {
+			const payload = params;
+			const senderOpenId = getTicket()?.senderOpenId;
+			if (!senderOpenId) return json({
+				error: "missing_sender_identity",
+				message: "当前不在飞书消息上下文中，无法按本人身份管理 OAuth。"
+			});
+			try {
+				const account = createUserToolClient(api.config).account;
+				if (payload.action === "status") return handleOAuthStatus({
+					appId: account.appId,
+					senderOpenId
+				});
+				if (payload.action === "revoke") return handleOAuthRevoke({
+					appId: account.appId,
+					senderOpenId
+				});
+				return handleOAuthAuthorize({
+					account,
+					senderOpenId,
+					scope: payload.scope,
+					waitSeconds: payload.wait_seconds
+				});
+			} catch (error) {
+				return json({ error: error instanceof Error ? error.message : String(error) });
+			}
+		}
+	}, { name: "feishu_oauth" });
+}
+//#endregion
+export { registerFeishuOAuthTool };