@skillbuilder/minitool-cli-config 0.0.0-beta-20261027053041051

package/README.md

@@ -0,0 +1,25 @@
+# @skillbuilder/minitool-cli-config
+
+`redminitool` 的纯本地配置包：定义 `config.json` / `auth.json` schema 与路径，执行安全读写和文件权限
+控制。它不发网络请求，也不判断登录或资源权限。
+
+`config.json` 的 `credentialStore` 允许 `file` / `keychain`；本包只校验与保存选择，不访问系统凭据库。
+配置和凭据由 Zod 4 schema 定义，TypeScript 类型直接从 schema 推导，
+不再手写多套字段判断和类型声明。包根入口仅导出宿主实际需要的 `ConfigFiles`、
+`ConfigFileContentError`、`parseAuthFileConfig`、凭据长度策略和相关公共类型；路径、文件名、
+文件上限和内部 schema 不对外开放，包的 `exports` 也禁止 deep import。
+
+当前文件位于 `~/.redminitool/`；`ConfigFiles` 可注入其他 home 目录供测试或宿主隔离。CLI 尚未发布，
+因此首版直接采用双文件：`config.json` 与 `auth.json` 各自从 `schemaVersion: 1` 开始，不包含旧格式兼容
+或 v1→v2 迁移逻辑。`auth.json` 以 `method` 区分 Secret 与设备码 OAuth 凭据；OAuth 存储 access/refresh token、有效期、可选 openId、scope 和 API origin，复用相同文件与 Keyring 策略。设备码等待状态放在受限的 `pending-auth.json`，沿用相同安全 I/O。`ConfigFiles(homeDir, "beta")` 使用 `~/.redminitool/beta/` 并同时校验父配置目录。
+
+`config.json` 只保存 `schemaVersion` 和 `credentialStore`，凭据仅进入 `auth.json`
+或系统 Keyring。目录和文件除拒绝符号链接外，还会校验 POSIX owner；凭据文件必须是普通文件且拒绝
+多硬链接后再执行权限修正或读写。写入采用同目录临时文件、文件 `fsync`、原子 `rename` 和尽力执行的
+目录 `fsync`；读取兼容 UTF-8 BOM，并以 1 MiB 上限阻止异常文件耗尽内存。多个进程并发写入不会产生
+半截 JSON，冲突语义为最后一次原子替换生效。内容损坏不会阻止 logout 清理凭据；成功清理后会重置为
+无凭据的首版文件配置。符号链接、owner 异常等路径安全错误不会被吞掉或覆盖。
+
+`conf` 等通用配置库虽提供 JSON Schema、迁移和原子写入，但不覆盖本包要求的
+`O_NOFOLLOW`、POSIX owner、多硬链拒绝、固定 `~/.redminitool` 双文件布局和 Keyring 存储切换语义，
+因此本期只用 Zod 替换 schema 校验，保留已验证的安全文件 I/O。

package/lib/file-store.js

@@ -0,0 +1,316 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigFiles = exports.ConfigFileContentError = void 0;
+exports.parseAuthFileConfig = parseAuthFileConfig;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const schemas_1 = require("./schemas");
+const CONFIG_DIRNAME = ".redminitool";
+const CONFIG_FILENAME = "config.json";
+const AUTH_FILENAME = "auth.json";
+const MAX_CONFIG_FILE_BYTES = 1024 * 1024;
+/** JSON/schema/大小等内容错误；与符号链接、所有者异常等路径安全错误区分。 */
+class ConfigFileContentError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ConfigFileContentError";
+    }
+}
+exports.ConfigFileContentError = ConfigFileContentError;
+function getConfigPaths(homeDir, environment) {
+    const root = path.join(homeDir, CONFIG_DIRNAME);
+    const directory = environment === "beta" ? path.join(root, "beta") : root;
+    return {
+        directory,
+        config: path.join(directory, CONFIG_FILENAME),
+        auth: path.join(directory, AUTH_FILENAME),
+        pendingAuth: path.join(directory, "pending-auth.json"),
+    };
+}
+function parseSchema(schema, value, message) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new ConfigFileContentError(message, { cause: result.error });
+    return result.data;
+}
+function parseAuthFileConfig(value) {
+    return parseSchema(schemas_1.authFileConfigSchema, value, "无效的 redminitool 凭据文件");
+}
+function parseGlobalConfig(value) {
+    return parseSchema(schemas_1.globalConfigSchema, value, "不支持的 redminitool 全局配置版本或凭据存储方式");
+}
+function isENOENT(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/** 无网络、无认证流程；只负责路径、schema 与安全文件 I/O。 */
+class ConfigFiles {
+    paths;
+    rootDirectory;
+    constructor(homeDir = os.homedir(), environment = "prod") {
+        this.rootDirectory = path.join(homeDir, CONFIG_DIRNAME);
+        this.paths = getConfigPaths(homeDir, environment);
+    }
+    readGlobal() {
+        const value = this.readJson(this.paths.config);
+        return value === null
+            ? { schemaVersion: 1, credentialStore: "file" }
+            : parseGlobalConfig(value);
+    }
+    writeGlobal(config) {
+        this.writeJson(this.paths.config, parseGlobalConfig(config));
+    }
+    readAuth() {
+        const value = this.readJson(this.paths.auth);
+        return value === null ? null : parseAuthFileConfig(value);
+    }
+    writeAuth(auth) {
+        this.writeJson(this.paths.auth, parseAuthFileConfig(auth));
+    }
+    readPendingAuth() {
+        const value = this.readJson(this.paths.pendingAuth);
+        return value === null ? null : parseSchema(schemas_1.pendingAuthSchema, value, "无效的扫码登录等待状态");
+    }
+    writePendingAuth(value) {
+        this.writeJson(this.paths.pendingAuth, parseSchema(schemas_1.pendingAuthSchema, value, "无效的扫码登录等待状态"));
+    }
+    clearPendingAuth() {
+        this.assertSafeDirectory(false);
+        try {
+            this.assertSafeFile(this.paths.pendingAuth);
+            fs.unlinkSync(this.paths.pendingAuth);
+        }
+        catch (error) {
+            if (!isENOENT(error))
+                throw error;
+        }
+    }
+    clearAuth() {
+        // logout 要能清理损坏的凭据文件；非敏感配置有效时继续保留。
+        let resetGlobal = false;
+        try {
+            const rawGlobal = this.readJson(this.paths.config);
+            if (rawGlobal !== null)
+                parseGlobalConfig(rawGlobal);
+        }
+        catch (error) {
+            // 配置内容损坏不应阻止删除凭据；路径、所有者等安全错误仍必须暴露。
+            if (!(error instanceof ConfigFileContentError))
+                throw error;
+            resetGlobal = true;
+        }
+        this.assertSafeDirectory(false);
+        try {
+            this.assertSafeFile(this.paths.auth);
+            fs.unlinkSync(this.paths.auth);
+        }
+        catch (error) {
+            if (!isENOENT(error))
+                throw error;
+        }
+        if (resetGlobal) {
+            // 成功 logout 后将损坏配置覆盖为不含凭据的干净首版配置。
+            this.writeJson(this.paths.config, {
+                schemaVersion: 1,
+                credentialStore: "file",
+            });
+        }
+    }
+    assertSafeDirectory(create) {
+        this.assertSafeDirectoryPath(this.rootDirectory, create);
+        if (this.paths.directory !== this.rootDirectory)
+            this.assertSafeDirectoryPath(this.paths.directory, create);
+    }
+    assertSafeDirectoryPath(directory, create) {
+        try {
+            const stat = fs.lstatSync(directory);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error("redminitool 配置目录不安全");
+            const fd = fs.openSync(directory, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+            try {
+                const opened = fs.fstatSync(fd);
+                if (!opened.isDirectory())
+                    throw new Error("redminitool 配置目录不安全");
+                this.assertCurrentUserOwner(opened, "配置目录");
+                fs.fchmodSync(fd, 0o700);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch (error) {
+            if (!isENOENT(error))
+                throw error;
+            if (create) {
+                fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+                this.assertSafeDirectoryPath(directory, false);
+            }
+        }
+    }
+    assertSafeFile(filePath) {
+        const fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const opened = fs.fstatSync(fd);
+            this.assertSafeOpenedFile(opened);
+            fs.fchmodSync(fd, 0o600);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    readJson(filePath) {
+        this.assertSafeDirectory(false);
+        let fd;
+        try {
+            // 不跟随符号链接打开，之后只对这个 fd 做校验、收紧权限和读取：
+            // 确认是当前用户的普通文件且没有硬链接，超过 1MB 按内容错误拒绝，
+            // 权限收到仅所有者可读写，避免按路径二次打开时被换成链接或并发替换。
+            fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            const stat = fs.fstatSync(fd);
+            this.assertSafeOpenedFile(stat);
+            if (stat.size > MAX_CONFIG_FILE_BYTES) {
+                throw new ConfigFileContentError(`redminitool 配置文件超过 ${MAX_CONFIG_FILE_BYTES} 字节上限`);
+            }
+            // 校验通过后再改权限、再读：fchmod 作用在已打开的 inode 上，把模式收到 0o600；
+            // 读也走同一个 fd，不再按路径打开一次。权限改失败就不会把内容读出来。
+            fs.fchmodSync(fd, 0o600);
+            const source = fs.readFileSync(fd, "utf8");
+            if (Buffer.byteLength(source, "utf8") > MAX_CONFIG_FILE_BYTES) {
+                throw new ConfigFileContentError(`redminitool 配置文件超过 ${MAX_CONFIG_FILE_BYTES} 字节上限`);
+            }
+            try {
+                return JSON.parse(source.charCodeAt(0) === 0xfeff ? source.slice(1) : source);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    throw new ConfigFileContentError("redminitool 配置文件不是有效 JSON", {
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            if (isENOENT(error))
+                return null;
+            throw error;
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+        }
+    }
+    writeJson(filePath, value) {
+        this.assertSafeDirectory(true);
+        try {
+            this.assertSafeFile(filePath);
+        }
+        catch (error) {
+            if (!isENOENT(error))
+                throw error;
+        }
+        const temp = path.join(this.paths.directory, `.${path.basename(filePath)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+        const source = `${JSON.stringify(value, null, 2)}\n`;
+        if (Buffer.byteLength(source, "utf8") > MAX_CONFIG_FILE_BYTES) {
+            throw new ConfigFileContentError(`redminitool 配置文件超过 ${MAX_CONFIG_FILE_BYTES} 字节上限`);
+        }
+        let tempFd;
+        try {
+            tempFd = fs.openSync(temp, fs.constants.O_WRONLY |
+                fs.constants.O_CREAT |
+                fs.constants.O_EXCL |
+                fs.constants.O_NOFOLLOW, 0o600);
+            fs.writeFileSync(tempFd, source, "utf8");
+            fs.fsyncSync(tempFd);
+            fs.closeSync(tempFd);
+            tempFd = undefined;
+            fs.renameSync(temp, filePath);
+            fs.chmodSync(filePath, 0o600);
+            this.syncDirectoryBestEffort();
+        }
+        catch (error) {
+            if (tempFd !== undefined) {
+                try {
+                    fs.closeSync(tempFd);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            try {
+                fs.unlinkSync(temp);
+            }
+            catch {
+                /* best effort */
+            }
+            throw error;
+        }
+    }
+    syncDirectoryBestEffort() {
+        let fd;
+        try {
+            fd = fs.openSync(this.paths.directory, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+            fs.fsyncSync(fd);
+        }
+        catch {
+            // Windows/部分文件系统不支持目录 fsync；文件本身已经完成 fsync + 原子 rename。
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        }
+    }
+    assertSafeOpenedFile(stat) {
+        // 并发原子替换后，已打开的旧 inode 可能变为 nlink=0；它仍是完整且安全的快照。
+        if (!stat.isFile() || stat.nlink > 1)
+            throw new Error("redminitool 配置文件不安全");
+        this.assertCurrentUserOwner(stat, "配置文件");
+    }
+    assertCurrentUserOwner(stat, target) {
+        const uid = process.getuid?.();
+        if (uid !== undefined && stat.uid !== uid) {
+            throw new Error(`redminitool ${target}不属于当前用户`);
+        }
+    }
+}
+exports.ConfigFiles = ConfigFiles;

package/lib/file-store.test.js

@@ -0,0 +1,219 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const node_test_1 = __importDefault(require("node:test"));
+const index_1 = require("./index");
+const MAX_CONFIG_FILE_BYTES = 1024 * 1024;
+function temporaryHome(t) {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "redminitool-config-test-"));
+    t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+    return home;
+}
+(0, node_test_1.default)("拒绝符号链接配置目录", (t) => {
+    const home = temporaryHome(t);
+    fs.symlinkSync(os.tmpdir(), path.join(home, ".redminitool"));
+    strict_1.default.throws(() => new index_1.ConfigFiles(home).readGlobal(), /配置目录不安全/);
+});
+(0, node_test_1.default)("拒绝符号链接凭据文件", (t) => {
+    const home = temporaryHome(t);
+    const files = new index_1.ConfigFiles(home);
+    fs.mkdirSync(files.paths.directory, { mode: 0o700 });
+    const outside = path.join(home, "outside.json");
+    fs.writeFileSync(outside, "{}");
+    fs.symlinkSync(outside, files.paths.auth);
+    strict_1.default.throws(() => files.readAuth());
+    strict_1.default.equal(fs.readFileSync(outside, "utf8"), "{}");
+});
+(0, node_test_1.default)("拒绝硬链接凭据文件，避免权限修正或写入影响其他路径", (t) => {
+    const home = temporaryHome(t);
+    const files = new index_1.ConfigFiles(home);
+    fs.mkdirSync(files.paths.directory, { mode: 0o700 });
+    const outside = path.join(home, "outside.json");
+    fs.writeFileSync(outside, "{}");
+    fs.linkSync(outside, files.paths.auth);
+    strict_1.default.throws(() => files.readAuth(), /配置文件不安全/);
+    strict_1.default.equal(fs.readFileSync(outside, "utf8"), "{}");
+});
+(0, node_test_1.default)("logout 能删除损坏的 auth.json，并保留非敏感配置", (t) => {
+    const files = new index_1.ConfigFiles(temporaryHome(t));
+    fs.mkdirSync(files.paths.directory, { mode: 0o700 });
+    fs.writeFileSync(files.paths.config, JSON.stringify({ schemaVersion: 1, credentialStore: "file" }));
+    fs.writeFileSync(files.paths.auth, "{broken-json");
+    files.clearAuth();
+    strict_1.default.equal(fs.existsSync(files.paths.auth), false);
+    strict_1.default.equal(files.readGlobal().credentialStore, "file");
+});
+(0, node_test_1.default)("config.json 损坏时 logout 删除 auth.json，并重置为无凭据配置", (t) => {
+    const files = new index_1.ConfigFiles(temporaryHome(t));
+    fs.mkdirSync(files.paths.directory, { mode: 0o700 });
+    fs.writeFileSync(files.paths.config, "{broken-config");
+    fs.writeFileSync(files.paths.auth, "{broken-auth");
+    files.clearAuth();
+    strict_1.default.equal(fs.existsSync(files.paths.auth), false);
+    strict_1.default.deepEqual(JSON.parse(fs.readFileSync(files.paths.config, "utf8")), {
+        schemaVersion: 1,
+        credentialStore: "file",
+    });
+});
+(0, node_test_1.default)("config.json 超限时 logout 仍删除 auth.json", (t) => {
+    const files = new index_1.ConfigFiles(temporaryHome(t));
+    fs.mkdirSync(files.paths.directory, { mode: 0o700 });
+    fs.writeFileSync(files.paths.config, Buffer.alloc(MAX_CONFIG_FILE_BYTES + 1, 0x20));
+    fs.writeFileSync(files.paths.auth, "{broken-auth");
+    files.clearAuth();
+    strict_1.default.equal(fs.existsSync(files.paths.auth), false);
+    strict_1.default.deepEqual(files.readGlobal(), { schemaVersion: 1, credentialStore: "file" });
+});
+(0, node_test_1.default)("兼容带 UTF-8 BOM 的配置，并修复目录和文件权限", (t) => {
+    const files = new index_1.ConfigFiles(temporaryHome(t));
+    fs.mkdirSync(files.paths.directory, { mode: 0o777 });
+    fs.writeFileSync(files.paths.config, `\ufeff${JSON.stringify({ schemaVersion: 1, credentialStore: "file" })}`, { mode: 0o666 });
+    strict_1.default.equal(files.readGlobal().credentialStore, "file");
+    strict_1.default.equal(fs.statSync(files.paths.directory).mode & 0o777, 0o700);
+    strict_1.default.equal(fs.statSync(files.paths.config).mode & 0o777, 0o600);
+});
+(0, node_test_1.default)("凭据 schema 拒绝超限与非法时间字段，并清理未知字段", (t) => {
+    const files = new index_1.ConfigFiles(temporaryHome(t));
+    fs.mkdirSync(files.paths.directory, { mode: 0o700 });
+    fs.writeFileSync(files.paths.config, Buffer.alloc(MAX_CONFIG_FILE_BYTES + 1, 0x20));
+    strict_1.default.throws(() => files.readGlobal(), /超过 .* 字节上限/);
+    strict_1.default.throws(() => (0, index_1.parseAuthFileConfig)({
+        schemaVersion: 1,
+        method: "secret",
+        secretId: "x".repeat(index_1.MAX_SECRET_ID_BYTES + 1),
+        sessionToken: "session",
+        issuedAt: "2026-01-01T00:00:00.000Z",
+        expiresAt: "2027-01-01T00:00:00.000Z",
+    }), /无效的 redminitool 凭据文件/);
+    strict_1.default.throws(() => (0, index_1.parseAuthFileConfig)({
+        schemaVersion: 1,
+        method: "secret",
+        secretId: "id",
+        sessionToken: "session",
+        issuedAt: "not-an-iso-time",
+        expiresAt: "2027-01-01T00:00:00.000Z",
+    }), /无效的 redminitool 凭据文件/);
+    const normalized = (0, index_1.parseAuthFileConfig)({
+        schemaVersion: 1,
+        method: "secret",
+        secretId: "id",
+        sessionToken: "session",
+        issuedAt: "2026-01-01T00:00:00.000Z",
+        expiresAt: "2027-01-01T00:00:00.000Z",
+        ignored: "field",
+    });
+    strict_1.default.equal("ignored" in normalized, false);
+});
+(0, node_test_1.default)("多个进程并发写配置不会产生截断 JSON 或临时文件残留", async (t) => {
+    const home = temporaryHome(t);
+    const modulePath = path.join(__dirname, "index.js");
+    const worker = `
+    const { ConfigFiles } = require(process.argv[1]);
+    const files = new ConfigFiles(process.argv[2]);
+    for (let index = 0; index < 20; index += 1) {
+      files.writeGlobal({ schemaVersion: 1, credentialStore: index % 2 ? "file" : "keychain" });
+    }
+  `;
+    const exits = await Promise.all(Array.from({ length: 4 }, () => new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(process.execPath, ["-e", worker, modulePath, home], {
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code !== 0)
+                reject(new Error(stderr));
+            else
+                resolve(code);
+        });
+    })));
+    strict_1.default.deepEqual(exits, [0, 0, 0, 0]);
+    strict_1.default.equal(new index_1.ConfigFiles(home).readGlobal().schemaVersion, 1);
+    strict_1.default.deepEqual(fs.readdirSync(path.join(home, ".redminitool")).filter((name) => name.endsWith(".tmp")), []);
+});
+(0, node_test_1.default)("扫码凭据、等待状态和 beta 环境沿用安全存储且互相隔离", () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "redminitool-device-config-"));
+    try {
+        const prod = new index_1.ConfigFiles(home);
+        const beta = new index_1.ConfigFiles(home, "beta");
+        const credential = {
+            schemaVersion: 1,
+            method: "device",
+            apiBaseUrl: "https://auth.example",
+            accessToken: "private-access",
+            refreshToken: "private-refresh",
+            openId: "creator",
+            scope: "base_info,skill_publish",
+            issuedAt: "2026-10-26T00:00:00Z",
+            expiresAt: "2026-10-26T02:00:00Z",
+            refreshExpiresAt: "2026-11-26T00:00:00Z",
+        };
+        prod.writeAuth(credential);
+        strict_1.default.deepEqual(prod.readAuth(), credential);
+        strict_1.default.equal(beta.readAuth(), null);
+        beta.writePendingAuth({
+            apiBaseUrl: "https://auth.example",
+            deviceCode: "private-device",
+            codeVerifier: "v".repeat(64),
+            authorizeCommonUrl: "https://auth.example/scan",
+            authorizeH5Url: "https://auth.example/web",
+            userCode: "CODE",
+            expiresAt: "2026-10-26T01:00:00Z",
+            pollIntervalSeconds: 5,
+        });
+        strict_1.default.equal(prod.readPendingAuth(), null);
+        strict_1.default.equal(beta.readPendingAuth()?.deviceCode, "private-device");
+        if (process.platform !== "win32")
+            strict_1.default.equal(fs.statSync(beta.paths.pendingAuth).mode & 0o777, 0o600);
+        beta.clearPendingAuth();
+        strict_1.default.equal(beta.readPendingAuth(), null);
+        strict_1.default.throws(() => (0, index_1.parseAuthFileConfig)({ ...credential, refreshExpiresAt: credential.issuedAt }));
+    }
+    finally {
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+});

package/lib/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SESSION_TOKEN_BYTES = exports.MAX_SECRET_ID_BYTES = exports.parseAuthFileConfig = exports.ConfigFiles = exports.ConfigFileContentError = void 0;
+var file_store_1 = require("./file-store");
+Object.defineProperty(exports, "ConfigFileContentError", { enumerable: true, get: function () { return file_store_1.ConfigFileContentError; } });
+Object.defineProperty(exports, "ConfigFiles", { enumerable: true, get: function () { return file_store_1.ConfigFiles; } });
+Object.defineProperty(exports, "parseAuthFileConfig", { enumerable: true, get: function () { return file_store_1.parseAuthFileConfig; } });
+var schemas_1 = require("./schemas");
+Object.defineProperty(exports, "MAX_SECRET_ID_BYTES", { enumerable: true, get: function () { return schemas_1.MAX_SECRET_ID_BYTES; } });
+Object.defineProperty(exports, "MAX_SESSION_TOKEN_BYTES", { enumerable: true, get: function () { return schemas_1.MAX_SESSION_TOKEN_BYTES; } });

package/lib/schemas.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalConfigSchema = exports.pendingAuthSchema = exports.authFileConfigSchema = exports.creatorCacheSchema = exports.MAX_SESSION_TOKEN_BYTES = exports.MAX_SECRET_ID_BYTES = void 0;
+const zod_1 = require("zod");
+exports.MAX_SECRET_ID_BYTES = 4 * 1024;
+exports.MAX_SESSION_TOKEN_BYTES = 64 * 1024;
+const MAX_CREATOR_TEXT_BYTES = 16 * 1024;
+function utf8String(maxBytes) {
+    return zod_1.z.string().refine((value) => Buffer.byteLength(value, "utf8") <= maxBytes);
+}
+const optionalCreatorText = utf8String(MAX_CREATOR_TEXT_BYTES).optional().catch(undefined);
+exports.creatorCacheSchema = zod_1.z.object({
+    creatorId: optionalCreatorText,
+    displayName: optionalCreatorText,
+    avatarUrl: optionalCreatorText,
+    description: optionalCreatorText,
+});
+const authPayloadSchema = zod_1.z.object({
+    method: zod_1.z.literal("secret"),
+    secretId: utf8String(exports.MAX_SECRET_ID_BYTES).refine((value) => value.trim().length > 0),
+    sessionToken: utf8String(exports.MAX_SESSION_TOKEN_BYTES).refine((value) => value.trim().length > 0),
+    issuedAt: zod_1.z.iso.datetime({ offset: true }),
+    expiresAt: zod_1.z.iso.datetime({ offset: true }),
+    creator: exports.creatorCacheSchema.optional().catch(undefined),
+});
+function expiresAfterIssue(value) {
+    return Date.parse(value.expiresAt) > Date.parse(value.issuedAt);
+}
+const secretAuthFileConfigSchema = authPayloadSchema
+    .extend({ schemaVersion: zod_1.z.literal(1) })
+    .refine(expiresAfterIssue, { path: ["expiresAt"] });
+const token = utf8String(exports.MAX_SESSION_TOKEN_BYTES).refine((value) => value.trim().length > 0);
+const deviceAuthFileConfigSchema = zod_1.z
+    .object({
+    schemaVersion: zod_1.z.literal(1),
+    method: zod_1.z.literal("device"),
+    apiBaseUrl: zod_1.z.url(),
+    accessToken: token,
+    refreshToken: token,
+    issuedAt: zod_1.z.iso.datetime({ offset: true }),
+    expiresAt: zod_1.z.iso.datetime({ offset: true }),
+    refreshExpiresAt: zod_1.z.iso.datetime({ offset: true }),
+    openId: utf8String(MAX_CREATOR_TEXT_BYTES).min(1).optional(),
+    scope: utf8String(MAX_CREATOR_TEXT_BYTES),
+    creator: exports.creatorCacheSchema.optional().catch(undefined),
+})
+    .refine(expiresAfterIssue, { path: ["expiresAt"] })
+    .refine((value) => Date.parse(value.refreshExpiresAt) > Date.parse(value.issuedAt), {
+    path: ["refreshExpiresAt"],
+});
+exports.authFileConfigSchema = zod_1.z.discriminatedUnion("method", [
+    secretAuthFileConfigSchema,
+    deviceAuthFileConfigSchema,
+]);
+exports.pendingAuthSchema = zod_1.z.object({
+    apiBaseUrl: zod_1.z.url(),
+    deviceCode: token,
+    codeVerifier: zod_1.z.string().regex(/^[A-Za-z0-9._~-]{43,128}$/),
+    authorizeCommonUrl: zod_1.z.url(),
+    authorizeH5Url: zod_1.z.url(),
+    userCode: utf8String(MAX_CREATOR_TEXT_BYTES),
+    expiresAt: zod_1.z.iso.datetime({ offset: true }),
+    pollIntervalSeconds: zod_1.z.number().int().min(1).max(60),
+});
+exports.globalConfigSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    credentialStore: zod_1.z.enum(["file", "keychain"]),
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@skillbuilder/minitool-cli-config",
+  "version": "0.0.0-beta-20261027053041051",
+  "description": "redminitool configuration schemas, paths and safe file IO",
+  "main": "lib/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "types"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "zod": "4.3.5"
+  },
+  "license": "ISC"
+}

package/types/file-store.d.ts

@@ -0,0 +1,35 @@
+import { type AuthFileConfig, type GlobalConfig, type PendingAuth } from "./schemas";
+/** JSON/schema/大小等内容错误；与符号链接、所有者异常等路径安全错误区分。 */
+export declare class ConfigFileContentError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+interface ConfigPaths {
+    directory: string;
+    config: string;
+    auth: string;
+    pendingAuth: string;
+}
+export declare function parseAuthFileConfig(value: unknown): AuthFileConfig;
+/** 无网络、无认证流程；只负责路径、schema 与安全文件 I/O。 */
+export declare class ConfigFiles {
+    readonly paths: ConfigPaths;
+    private readonly rootDirectory;
+    constructor(homeDir?: string, environment?: "prod" | "beta");
+    readGlobal(): GlobalConfig;
+    writeGlobal(config: GlobalConfig): void;
+    readAuth(): AuthFileConfig | null;
+    writeAuth(auth: AuthFileConfig): void;
+    readPendingAuth(): PendingAuth | null;
+    writePendingAuth(value: PendingAuth): void;
+    clearPendingAuth(): void;
+    clearAuth(): void;
+    private assertSafeDirectory;
+    private assertSafeDirectoryPath;
+    private assertSafeFile;
+    private readJson;
+    private writeJson;
+    private syncDirectoryBestEffort;
+    private assertSafeOpenedFile;
+    private assertCurrentUserOwner;
+}
+export {};

package/types/file-store.test.d.ts

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

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export { ConfigFileContentError, ConfigFiles, parseAuthFileConfig } from "./file-store";
+export { MAX_SECRET_ID_BYTES, MAX_SESSION_TOKEN_BYTES } from "./schemas";
+export type { AuthFileConfig, CreatorCache, GlobalConfig, SecretAuthFileConfig, DeviceAuthFileConfig, PendingAuth, } from "./schemas";

package/types/schemas.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+export declare const MAX_SECRET_ID_BYTES: number;
+export declare const MAX_SESSION_TOKEN_BYTES: number;
+export declare const creatorCacheSchema: z.ZodObject<{
+    creatorId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    displayName: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    avatarUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    description: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+declare const secretAuthFileConfigSchema: z.ZodObject<{
+    method: z.ZodLiteral<"secret">;
+    secretId: z.ZodString;
+    sessionToken: z.ZodString;
+    issuedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    creator: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        creatorId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        displayName: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        avatarUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        description: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>;
+    schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strip>;
+declare const deviceAuthFileConfigSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    method: z.ZodLiteral<"device">;
+    apiBaseUrl: z.ZodURL;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodString;
+    issuedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    refreshExpiresAt: z.ZodISODateTime;
+    openId: z.ZodOptional<z.ZodString>;
+    scope: z.ZodString;
+    creator: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        creatorId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        displayName: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        avatarUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        description: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const authFileConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    method: z.ZodLiteral<"secret">;
+    secretId: z.ZodString;
+    sessionToken: z.ZodString;
+    issuedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    creator: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        creatorId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        displayName: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        avatarUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        description: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>;
+    schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    method: z.ZodLiteral<"device">;
+    apiBaseUrl: z.ZodURL;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodString;
+    issuedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    refreshExpiresAt: z.ZodISODateTime;
+    openId: z.ZodOptional<z.ZodString>;
+    scope: z.ZodString;
+    creator: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        creatorId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        displayName: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        avatarUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+        description: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>], "method">;
+export declare const pendingAuthSchema: z.ZodObject<{
+    apiBaseUrl: z.ZodURL;
+    deviceCode: z.ZodString;
+    codeVerifier: z.ZodString;
+    authorizeCommonUrl: z.ZodURL;
+    authorizeH5Url: z.ZodURL;
+    userCode: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    pollIntervalSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type SecretAuthFileConfig = z.infer<typeof secretAuthFileConfigSchema>;
+export type DeviceAuthFileConfig = z.infer<typeof deviceAuthFileConfigSchema>;
+export type PendingAuth = z.infer<typeof pendingAuthSchema>;
+export declare const globalConfigSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    credentialStore: z.ZodEnum<{
+        file: "file";
+        keychain: "keychain";
+    }>;
+}, z.core.$strip>;
+export type GlobalConfig = z.infer<typeof globalConfigSchema>;
+export type CreatorCache = z.infer<typeof creatorCacheSchema>;
+export type AuthFileConfig = z.infer<typeof authFileConfigSchema>;
+export {};