@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/dist/capabilities/flyai-config.js

@@ -0,0 +1,337 @@
+/**
+ * FlyAI API key 配置面(issue #521;供应商 skill setup 体验核心)。
+ *
+ * 与官方 @fly-ai/flyai-cli 1.0.16 的配置机制严格对齐(解包核实,非猜测):
+ *   key = env FLYAI_API_KEY(trim 非空)→ env DEBUG_FLYAI_API_KEY(trim 非空)
+ *       → ~/.flyai/config.json 的 FLYAI_API_KEY 字段 → 内置共享 key(匿名试用);
+ *   endpoint = env DEBUG_FLYAI_MCP_URL(trim 非空)→ 官方默认;
+ *   空串/纯空白 env 一律视为未设置(官方 helper 用 c&&c.trim()!=='' 判定,
+ *   不是 nullish 判定)。
+ *
+ * 文件路径/格式 = 官方 `flyai config set` 的 ~/.flyai/config.json 扁平 JSON;
+ * 写时读入整对象只动 FLYAI_API_KEY,其他字段原样保留。
+ *
+ * 安全契约:
+ *   - 原配置损坏(坏 JSON/非对象)→ save/clear/write 全部拒绝并保留原字节,
+ *     由调用方向用户显式报错;绝不静默覆盖丢字段;
+ *   - 原子写 = tmp 文件 + rename;finally 中删除本操作拥有的 tmp,
+ *     rename 失败也不留含明文的残留文件;
+ *   - 权限是硬要求:目录 0700、文件 0600 必须实测;chmod 失败即整体失败,
+ *     best-effort 不算安全存储;
+ *   - 对外面只回显 maskFlyaiKey 脱敏值。
+ *
+ * @module capabilities/flyai-config
+ */
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function flyaiConfigPath(homeDir) {
+    return join(homeDir, '.flyai', 'config.json');
+}
+/** ~/.gotry/flyai-verification.json(与 calendar.json 同 ~/.gotry) */
+export function flyaiVerificationPath(homeDir) {
+    return join(homeDir, '.gotry', 'flyai-verification.json');
+}
+/** 与官方 1.0.16 同款:存在且 trim 非空才算值;空串/空白/非字符串 = undefined */
+function nonEmpty(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    return text || undefined;
+}
+/**
+ * 严格读取 config.json:
+ *   不存在/空文件 → ok+空对象;
+ *   JSON 损坏/顶层非对象 → ok:false(调用方必须拒绝写入并保留字节)。
+ */
+export function readFlyaiConfig(configPath) {
+    try {
+        if (!existsSync(configPath))
+            return { ok: true, data: {} };
+        const text = readFileSync(configPath, 'utf8');
+        if (!text.trim())
+            return { ok: true, data: {} };
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { ok: false, error: 'config 顶层不是 JSON 对象' };
+        }
+        return { ok: true, data: parsed };
+    }
+    catch {
+        return { ok: false, error: 'config JSON 解析失败（为保护凭据，不显示原文）' };
+    }
+}
+/**
+ * 解析当前生效 FlyAI key(官方 1.0.16 同优先级):
+ *   FLYAI_API_KEY → DEBUG_FLYAI_API_KEY → config 文件 → none(官方内置共享)。
+ */
+export function resolveFlyaiKey(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const env = opts.env ?? process.env;
+    const configPath = flyaiConfigPath(homeDir);
+    const envKey = nonEmpty(env.FLYAI_API_KEY);
+    if (envKey)
+        return { key: envKey, source: 'env', configPath, maskedKey: maskFlyaiKey(envKey) };
+    const debugKey = nonEmpty(env.DEBUG_FLYAI_API_KEY);
+    if (debugKey)
+        return { key: debugKey, source: 'env-debug', configPath, maskedKey: maskFlyaiKey(debugKey) };
+    const read = readFlyaiConfig(configPath);
+    const fileKey = read.ok ? nonEmpty(read.data.FLYAI_API_KEY) : undefined;
+    if (fileKey)
+        return { key: fileKey, source: 'config', configPath, maskedKey: maskFlyaiKey(fileKey) };
+    return { source: 'none', configPath };
+}
+/** 解析 endpoint;DEBUG_FLYAI_MCP_URL trim 非空覆盖,显式标注调试态 */
+export function resolveFlyaiEndpoint(opts = {}) {
+    const env = opts.env ?? process.env;
+    const debugUrl = nonEmpty(env.DEBUG_FLYAI_MCP_URL);
+    if (debugUrl)
+        return { url: debugUrl, debug: true };
+    return { url: 'https://flyai.open.fliggy.com/mcp', debug: false };
+}
+/** 脱敏:仅尾 4 位;短串(≤4)全掩 */
+export function maskFlyaiKey(key) {
+    const text = typeof key === 'string' ? key.trim() : '';
+    if (!text)
+        return '';
+    if (text.length <= 4)
+        return '****';
+    return `****${text.slice(-4)}`;
+}
+export function sha256Hex(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+/** 明显占位/模板串——拒绝把文档示例当 key */
+export function isPlaceholderFlyaiKey(key) {
+    const text = key.trim().toLowerCase();
+    if (!text)
+        return true;
+    return /^(your?-?(key|api[._-]?key)|xxxx+|<[^>]+>|sk-[a-z]*$|test|placeholder|changeme|foo|bar)$/.test(text);
+}
+/**
+ * 权限硬校验:dir 必须 0700,file(存在时)必须 0600。
+ * Windows 无 POSIX 位:返回 unsupported(调用方按平台说明,不冒充通过)。
+ */
+export function verifySecureMode(dir, file) {
+    if (process.platform === 'win32')
+        return { ok: false, unsupported: true };
+    try {
+        const dirMode = statSync(dir).mode & 0o777;
+        if (dirMode !== 0o700)
+            return { ok: false, error: `目录权限 ${dirMode.toString(8)} ≠ 700` };
+        if (existsSync(file)) {
+            const fileMode = statSync(file).mode & 0o777;
+            if (fileMode !== 0o600)
+                return { ok: false, error: `文件权限 ${fileMode.toString(8)} ≠ 600` };
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+/**
+ * 官方 CLI 1.0.16 首次运行可能先创建 ~/.flyai 为 0755，并在其中写入
+ * 0600 device-id。仅对当前用户拥有且本身不是 symlink 的配置目录收紧到
+ * 0700；验证回执所在 ~/.gotry 仍严格拒绝既有 0755 目录。
+ */
+function prepareFlyaiConfigDir(dir, file) {
+    if (process.platform === 'win32')
+        return { ok: false, unsupported: true, error: 'Windows 无 0700/0600 权限位,安全写不支持' };
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const entry = lstatSync(dir);
+        if (entry.isSymbolicLink())
+            return { ok: false, error: '.flyai 目录是符号链接,拒绝写入' };
+        if (!entry.isDirectory())
+            return { ok: false, error: '.flyai 路径不是目录,拒绝写入' };
+        if (typeof process.getuid === 'function' && entry.uid !== process.getuid()) {
+            return { ok: false, error: '.flyai 目录不属于当前用户,拒绝写入' };
+        }
+        if ((entry.mode & 0o777) !== 0o700)
+            chmodSync(dir, 0o700);
+        const after = lstatSync(dir);
+        if (after.isSymbolicLink() || !after.isDirectory())
+            return { ok: false, error: '.flyai 目录状态发生变化,拒绝写入' };
+        if (typeof process.getuid === 'function' && after.uid !== process.getuid())
+            return { ok: false, error: '.flyai 目录所有者发生变化,拒绝写入' };
+        return verifySecureMode(dir, file);
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+/**
+ * 原子写 JSON 文件(本模块 save/clear/verification 共用的唯一写面):
+ *   1. dir 不存在则建,chmod 0700;已存在则先按 0700 校验;
+ *   2. tmp(同目录,mode 0600)写内容 → 校验 tmp 0600 → rename;
+ *   3. rename 后校验目标 0600;任一步失败:删除本 tmp 并返回 error;
+ *   4. tmp 清理放在 finally——rename 失败也不留含明文残留。
+ * 永不抛错。
+ */
+export function atomicWriteJson(path, value) {
+    const dir = dirname(path);
+    let tmp;
+    try {
+        const dirExisted = existsSync(dir);
+        mkdirSync(dir, { recursive: true });
+        if (!dirExisted)
+            chmodSync(dir, 0o700);
+        const dirCheck = verifySecureMode(dir, path);
+        if (dirCheck.unsupported)
+            return { ok: false, error: 'Windows 无 0700/0600 权限位,安全写不支持' };
+        if (!dirCheck.ok)
+            return { ok: false, error: dirCheck.error };
+        tmp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        let modeCheck = verifySecureMode(dir, tmp);
+        if (!modeCheck.ok)
+            return { ok: false, error: modeCheck.error };
+        renameSync(tmp, path);
+        tmp = undefined;
+        modeCheck = verifySecureMode(dir, path);
+        if (!modeCheck.ok)
+            return { ok: false, error: modeCheck.error };
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+    finally {
+        if (tmp) {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch { /* tmp 清理 best effort */ }
+        }
+    }
+}
+/**
+ * 保存 key 到 ~/.flyai/config.json:
+ *   非空/非占位;原配置损坏 → 拒绝保留字节;只改 FLYAI_API_KEY 字段;
+ *   原子写 + 权限硬校验。失败不动旧文件。
+ */
+export function saveFlyaiKey(key, opts = {}) {
+    const text = typeof key === 'string' ? key.trim() : '';
+    const homeDir = opts.homeDir ?? homedir();
+    const env = opts.env ?? process.env;
+    const configPath = flyaiConfigPath(homeDir);
+    if (!text)
+        return { ok: false, error: 'API key 不能为空' };
+    if (isPlaceholderFlyaiKey(text))
+        return { ok: false, error: '拒绝保存:这是文档占位串,不是真实 API key' };
+    const read = readFlyaiConfig(configPath);
+    if (!read.ok)
+        return { ok: false, error: `原配置损坏,已拒绝覆盖(${read.error});请先人工修复 ${configPath}` };
+    const configDir = prepareFlyaiConfigDir(dirname(configPath), configPath);
+    if (!configDir.ok)
+        return { ok: false, error: configDir.error };
+    const write = atomicWriteJson(configPath, { ...read.data, FLYAI_API_KEY: text });
+    if (!write.ok)
+        return { ok: false, error: write.error };
+    const envKey = nonEmpty(env.FLYAI_API_KEY);
+    const debugKey = nonEmpty(env.DEBUG_FLYAI_API_KEY);
+    const source = envKey ? 'env' : debugKey ? 'env-debug' : 'config';
+    return {
+        ok: true,
+        savedTo: configPath,
+        source,
+        maskedKey: maskFlyaiKey(text),
+        ...(envKey || debugKey ? { envActive: true } : {}),
+    };
+}
+/**
+ * 清除 config.json 的 FLYAI_API_KEY 字段:
+ *   原配置损坏 → 拒绝保留字节;含字段则删(对象空=移除文件,否则原子写保留其他键);
+ *   不含字段=幂等成功;env/debug 来源文件操作清不掉,source 如实标注。
+ */
+export function clearFlyaiKey(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const env = opts.env ?? process.env;
+    const configPath = flyaiConfigPath(homeDir);
+    const read = readFlyaiConfig(configPath);
+    if (!read.ok)
+        return { ok: false, source: 'none', error: `原配置损坏,已拒绝操作(${read.error});请先人工修复 ${configPath}` };
+    let removedFrom;
+    if (Object.prototype.hasOwnProperty.call(read.data, 'FLYAI_API_KEY')) {
+        const next = { ...read.data };
+        delete next.FLYAI_API_KEY;
+        if (Object.keys(next).length === 0) {
+            try {
+                rmSync(configPath, { force: true });
+            }
+            catch (e) {
+                return { ok: false, source: 'none', error: `移除文件失败:${e.message}` };
+            }
+        }
+        else {
+            const configDir = prepareFlyaiConfigDir(dirname(configPath), configPath);
+            if (!configDir.ok)
+                return { ok: false, source: 'none', error: configDir.error };
+            const write = atomicWriteJson(configPath, next);
+            if (!write.ok)
+                return { ok: false, source: 'none', error: write.error };
+        }
+        removedFrom = configPath;
+    }
+    const envKey = nonEmpty(env.FLYAI_API_KEY);
+    const debugKey = nonEmpty(env.DEBUG_FLYAI_API_KEY);
+    if (envKey)
+        return { ok: true, ...(removedFrom ? { removedFrom } : {}), source: 'env', maskedKey: maskFlyaiKey(envKey) };
+    if (debugKey)
+        return { ok: true, ...(removedFrom ? { removedFrom } : {}), source: 'env-debug', maskedKey: maskFlyaiKey(debugKey) };
+    return { ok: true, ...(removedFrom ? { removedFrom } : {}), source: 'none' };
+}
+export function readFlyaiVerification(homeDir) {
+    try {
+        const path = flyaiVerificationPath(homeDir);
+        if (!existsSync(path))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return undefined;
+        const v = parsed;
+        if (v.schema !== 'gotry.flyai-verification.v1' || typeof v.keySha256 !== 'string')
+            return undefined;
+        return v;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 原子写验证记录(权限硬校验);成功=true;失败不抛错 */
+export function writeFlyaiVerification(entry, homeDir) {
+    return atomicWriteJson(flyaiVerificationPath(homeDir), entry).ok;
+}
+export function removeFlyaiVerification(homeDir) {
+    try {
+        rmSync(flyaiVerificationPath(homeDir), { force: true });
+    }
+    catch { /* best effort */ }
+}
+/** 完整归一化 endpoint，保留 path/query 以使其变化使回执失效。 */
+export function normalizeEndpoint(url) {
+    try {
+        return new URL(url).href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** endpoint 指纹不可逆，避免调试 URL 的 userinfo/query 落盘。 */
+export function endpointFingerprint(url) {
+    const normalized = normalizeEndpoint(url);
+    return normalized ? sha256Hex(normalized) : undefined;
+}
+/** 对外展示 endpoint：移除 userinfo、query、fragment；比较仍使用完整指纹。 */
+export function displayEndpoint(url) {
+    try {
+        const u = new URL(url);
+        return `${u.protocol}//${u.host}${u.pathname || '/'}${u.search || u.hash ? '?(已隐藏敏感参数)' : ''}`;
+    }
+    catch {
+        return '<非法 endpoint>';
+    }
+}