@yijiancaotang/cli 0.0.0-stage → 1.0.0

package/dist/credential-store.js

@@ -0,0 +1,594 @@
+import { createHash } from "node:crypto";
+import { agentIdentity } from "./agent-identity.js";
+import { constants, lstatSync, openSync, fstatSync, readSync, writeFileSync, fsyncSync, fchmodSync, ftruncateSync, closeSync } from "node:fs";
+import { lstat, realpath, mkdir, open, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { CliError, asRecord, validToken } from "./errors.js";
+import { acquireLocalLock } from "./local-lock.js";
+import { productionOrigin, legacyProductionOrigin } from "./config.js";
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const sameVersion = (a, b) => sameFile(a, b) && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+const missing = (error) => asRecord(error)?.code === "ENOENT";
+const unsafe = () => new CliError("credential_unsafe", "本地凭证位置或记录未通过安全检查。", "请检查属主、符号链接、目标环境和权限，不要输出凭证内容。");
+const unsafeLinks = () => new CliError("credential_unsafe", "本地凭据文件的链接数不是 1，已拒绝使用或报告保存成功。", "请由本人核查硬链接或路径替换；不要自动删除链接、放宽权限或输出凭据内容。", 2, { reason: "multiple_links" });
+const unsafeSymlink = () => new CliError("credential_symlink", "本地凭证路径包含符号链接，已拒绝访问。", "请由本人改用不含符号链接的真实用户目录和凭证路径后重试；不要自动删除链接、迁移凭证或放宽权限，也不要输出凭证内容。");
+const conflict = () => new CliError("credential_conflict", "当前环境已有另一份凭证。", "请保留原凭证，在网页核对并吊销未保存的设备后，再决定是否重新授权。");
+const cleanupFailed = () => new CliError("credential_cleanup_failed", "本地凭据尚未确认清理完成。", "请由本人检查凭据文件的清空或删除限制；不要输出内容、绕过保护或声称断开完成。");
+const permissionFailure = (error) => ["EPERM", "EACCES"].includes(String(asRecord(error)?.code));
+const permissionDenied = (path, error) => new CliError("installation_permission_denied", "没有权限完成本地凭据操作。", "请由本人核对详情中目标目录的访问、清空或删除限制；不要自动提权、放宽权限或声称操作完成。", 4, { target_directory: path, system_code: String(asRecord(error)?.code) });
+class FileCredentialStore {
+    path;
+    origin;
+    home;
+    directoryPath;
+    lockPath;
+    environment;
+    constructor(homeDir, environment, origin, isolated, fileKey, marker = false) {
+        if (!homeDir || !["production", "test"].includes(environment))
+            throw unsafe();
+        let url;
+        try {
+            url = new URL(origin);
+        }
+        catch {
+            throw unsafe();
+        }
+        if (url.origin !== origin || url.username || url.password || !["https:", "http:"].includes(url.protocol))
+            throw unsafe();
+        this.home = resolve(homeDir);
+        this.environment = environment;
+        this.origin = origin;
+        this.directoryPath = join(this.home, isolated ? ".caotang-credentials" : ".caotang");
+        this.path = join(this.directoryPath, marker ? `LEGACY_CLAIM.${environment}.json` : isolated ? `DO_NOT_READ.${environment}${fileKey ? `.${fileKey}` : ""}.json` : `${environment}.json`);
+        this.lockPath = join(this.directoryPath, `.${environment}${marker ? ".legacy-claim" : fileKey ? `.${fileKey}` : ""}.lock`);
+    }
+    owned(stat) {
+        return typeof process.getuid === "function" && stat.uid === process.getuid();
+    }
+    async checkHome() {
+        const stat = await lstat(this.home);
+        if (stat.isSymbolicLink())
+            throw unsafeSymlink();
+        if (!stat.isDirectory() || !this.owned(stat) || (stat.mode & 0o022) !== 0)
+            throw unsafe();
+        if (await realpath(this.home) !== this.home) {
+            // A canonical-path mismatch can also be casing/normalization. Only name
+            // a symlink cause when metadata proves it; never follow it or repair it.
+            for (let parent = dirname(this.home);; parent = dirname(parent)) {
+                if ((await lstat(parent)).isSymbolicLink())
+                    throw unsafeSymlink();
+                if (dirname(parent) === parent)
+                    break;
+            }
+            throw unsafe();
+        }
+    }
+    checkFile(stat) {
+        if (stat.isSymbolicLink())
+            throw unsafeSymlink();
+        if (!stat.isFile() || !this.owned(stat) || (stat.mode & 0o7777) !== 0o600 || stat.size > 16384)
+            throw unsafe();
+        if (stat.nlink !== 1)
+            throw unsafeLinks();
+    }
+    async directory(create) {
+        await this.checkHome();
+        if (create) {
+            try {
+                await mkdir(this.directoryPath, { mode: 0o700 });
+            }
+            catch (error) {
+                if (asRecord(error)?.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        let stat;
+        try {
+            stat = await lstat(this.directoryPath);
+        }
+        catch (error) {
+            if (missing(error) && !create)
+                return null;
+            throw error;
+        }
+        if (stat.isSymbolicLink())
+            throw unsafeSymlink();
+        if (!stat.isDirectory() || !this.owned(stat) || (stat.mode & 0o7777) !== 0o700)
+            throw unsafe();
+        const handle = await open(this.directoryPath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            if (!sameFile(stat, await handle.stat()))
+                throw unsafe();
+            return { handle, stat };
+        }
+        catch (error) {
+            await handle.close();
+            throw error;
+        }
+    }
+    async checkDirectory(directory) {
+        await this.checkHome();
+        const stat = await lstat(this.directoryPath);
+        if (stat.isSymbolicLink())
+            throw unsafeSymlink();
+        if (!stat.isDirectory() || !sameFile(stat, directory.stat) || !this.owned(stat) || (stat.mode & 0o7777) !== 0o700)
+            throw unsafe();
+    }
+    validate(value) {
+        const item = asRecord(value);
+        const recordOrigin = item?.origin;
+        const matchesOrigin = recordOrigin === this.origin || (this.environment === "production" && this.origin === productionOrigin && recordOrigin === legacyProductionOrigin);
+        if (!item || Object.keys(item).sort().join(",") !== "kind,origin,savedAt,scope,token,tokenId" || !validToken(item.token)
+            || typeof recordOrigin !== "string" || !matchesOrigin || item.kind !== "device" || !["read_only", "read_write"].includes(String(item.scope))
+            || typeof item.tokenId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(item.tokenId)
+            || typeof item.savedAt !== "string" || !/^\d{4}-\d\d-\d\dT/.test(item.savedAt) || !Number.isFinite(Date.parse(item.savedAt)))
+            throw unsafe();
+        return { token: item.token, origin: recordOrigin, kind: "device", scope: item.scope, tokenId: item.tokenId, savedAt: item.savedAt };
+    }
+    async readBytes(directory) {
+        await this.checkDirectory(directory);
+        let stat;
+        try {
+            stat = await lstat(this.path);
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+        this.checkFile(stat);
+        const handle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const opened = await handle.stat();
+            this.checkFile(opened);
+            if (!sameVersion(stat, opened))
+                throw unsafe();
+            // A fixed buffer also bounds a file that grows after the initial fstat.
+            const buffer = Buffer.alloc(16385);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if (bytesRead > 16384 || bytesRead !== opened.size)
+                throw unsafe();
+            const after = await handle.stat();
+            this.checkFile(after);
+            const current = await lstat(this.path);
+            this.checkFile(current);
+            if (!sameVersion(opened, after) || !sameVersion(after, current))
+                throw unsafe();
+            await this.checkDirectory(directory);
+            if (bytesRead === 0)
+                return null;
+            return { bytes: buffer.subarray(0, bytesRead), stat: current };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async read(directory) {
+        const value = await this.readBytes(directory);
+        return value ? { record: this.validate(JSON.parse(value.bytes.toString("utf8"))), stat: value.stat } : null;
+    }
+    claim(value) {
+        const item = asRecord(value);
+        if (!item || Object.keys(item).sort().join(",") !== "owner,source_sha256,version" || item.version !== 1 || item.owner !== "命令行" || typeof item.source_sha256 !== "string" || !/^[0-9a-f]{64}$/.test(item.source_sha256))
+            throw unsafe();
+        return { version: 1, owner: "命令行", source_sha256: item.source_sha256 };
+    }
+    async loadClaim() {
+        return this.guarded(async () => {
+            const directory = await this.directory(false);
+            if (!directory)
+                return null;
+            try {
+                const value = await this.readBytes(directory);
+                return value ? this.claim(JSON.parse(value.bytes.toString("utf8"))) : null;
+            }
+            finally {
+                await directory.handle.close();
+            }
+        });
+    }
+    async saveClaim(value) {
+        return this.guarded(async () => {
+            const record = this.claim(value), directory = await this.directory(true);
+            if (!directory)
+                throw unsafe();
+            try {
+                await this.locked(directory, async () => {
+                    const existing = await this.readBytes(directory);
+                    if (existing) {
+                        if (this.claim(JSON.parse(existing.bytes.toString("utf8"))).source_sha256 !== record.source_sha256)
+                            throw conflict();
+                        return;
+                    }
+                    await this.checkDirectory(directory);
+                    this.writeWithoutDelete(directory, record);
+                    await directory.handle.sync();
+                    const saved = await this.readBytes(directory);
+                    if (!saved || this.claim(JSON.parse(saved.bytes.toString("utf8"))).source_sha256 !== record.source_sha256)
+                        throw conflict();
+                });
+            }
+            finally {
+                await directory.handle.close();
+            }
+        });
+    }
+    async guarded(action) {
+        try {
+            return await action();
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            if (asRecord(error)?.code === "ELOOP")
+                throw unsafeSymlink();
+            if (permissionFailure(error))
+                throw permissionDenied(this.directoryPath, error);
+            throw unsafe();
+        }
+    }
+    async locked(directory, action) {
+        await this.checkDirectory(directory);
+        const release = acquireLocalLock(this.lockPath, { path: this.directoryPath, identity: directory.stat }, {
+            unsafe,
+            busy: () => new CliError("credential_busy", "有另一项凭证操作正在进行或锁状态无法确认。", "请等待同环境命令结束；不确定时保留现状，由你人工核查，不要自动删锁或重新授权。"),
+        });
+        try {
+            await action();
+        }
+        finally {
+            await this.checkDirectory(directory);
+            release();
+        }
+    }
+    writeWithoutDelete(directory, record) {
+        const original = process.cwd();
+        let fd = -1;
+        try {
+            process.chdir(this.directoryPath);
+            const parent = lstatSync(".");
+            if (!sameFile(parent, directory.stat) || !this.owned(parent) || (parent.mode & 0o7777) !== 0o700)
+                throw unsafe();
+            const name = basename(this.path);
+            try {
+                fd = openSync(name, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0);
+            }
+            catch (error) {
+                if (asRecord(error)?.code !== "EEXIST")
+                    throw error;
+                const named = lstatSync(name);
+                this.checkFile(named);
+                if (named.size !== 0)
+                    throw conflict();
+                fd = openSync(name, constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                const opened = fstatSync(fd);
+                this.checkFile(opened);
+                if (!sameVersion(named, opened) || !sameVersion(opened, lstatSync(name)) || opened.size !== 0)
+                    throw unsafe();
+                fchmodSync(fd, 0);
+                fsyncSync(fd);
+            }
+            const initial = fstatSync(fd);
+            if (!initial.isFile() || !this.owned(initial) || initial.size !== 0 || (initial.mode & 0o7777) !== 0)
+                throw unsafe();
+            if (initial.nlink !== 1)
+                throw unsafeLinks();
+            const bytes = Buffer.from(JSON.stringify(record));
+            writeFileSync(fd, bytes);
+            fsyncSync(fd);
+            const written = fstatSync(fd), current = lstatSync(name);
+            const verify = Buffer.alloc(bytes.length + 1);
+            if (written.nlink !== 1 || current.nlink !== 1)
+                throw unsafeLinks();
+            if (!sameFile(initial, written) || !sameFile(written, current) || written.size !== bytes.length || current.size !== bytes.length
+                || (written.mode & 0o7777) !== 0 || (current.mode & 0o7777) !== 0 || readSync(fd, verify, 0, verify.length, 0) !== bytes.length || !verify.subarray(0, bytes.length).equals(bytes))
+                throw unsafe();
+            fchmodSync(fd, 0o600);
+            fsyncSync(fd);
+            const published = lstatSync(name), final = fstatSync(fd);
+            this.checkFile(published);
+            this.checkFile(final);
+            if (!sameFile(initial, final) || !sameFile(final, published) || final.size !== bytes.length || published.size !== bytes.length || final.mtimeMs !== written.mtimeMs
+                || readSync(fd, verify, 0, verify.length, 0) !== bytes.length || !verify.subarray(0, bytes.length).equals(bytes))
+                throw unsafe();
+        }
+        catch (error) {
+            if (fd !== -1) {
+                try {
+                    fchmodSync(fd, 0);
+                    fsyncSync(fd);
+                }
+                catch { /* Never report an incomplete credential as saved. */ }
+            }
+            throw error;
+        }
+        finally {
+            try {
+                if (fd !== -1)
+                    closeSync(fd);
+            }
+            finally {
+                process.chdir(original);
+            }
+        }
+    }
+    clearContents(directory, existing) {
+        const original = process.cwd();
+        let fd = -1;
+        try {
+            process.chdir(this.directoryPath);
+            const parent = lstatSync(".");
+            if (!sameFile(parent, directory.stat) || !this.owned(parent) || (parent.mode & 0o7777) !== 0o700)
+                throw unsafe();
+            const name = basename(this.path);
+            fd = openSync(name, constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const opened = fstatSync(fd), named = lstatSync(name);
+            this.checkFile(opened);
+            this.checkFile(named);
+            if (!sameVersion(existing.stat, opened) || !sameVersion(opened, named))
+                throw unsafe();
+            const bytes = Buffer.alloc(16385), count = readSync(fd, bytes, 0, bytes.length, 0);
+            if (count !== opened.size || count > 16384)
+                throw unsafe();
+            if (!sameStoredRecord(this.validate(JSON.parse(bytes.subarray(0, count).toString("utf8"))), existing.record))
+                throw conflict();
+            const checked = fstatSync(fd), current = lstatSync(name);
+            this.checkFile(checked);
+            this.checkFile(current);
+            if (!sameVersion(opened, checked) || !sameVersion(checked, current))
+                throw unsafe();
+            // Clear the pinned inode before a delete broker can move it to Trash.
+            // Keep snapshot validation and truncation in one synchronous section.
+            try {
+                ftruncateSync(fd, 0);
+                fsyncSync(fd);
+            }
+            catch (error) {
+                if (permissionFailure(error))
+                    throw error;
+                throw cleanupFailed();
+            }
+            const cleared = fstatSync(fd), published = lstatSync(name);
+            this.checkFile(cleared);
+            this.checkFile(published);
+            if (!sameFile(opened, cleared) || !sameVersion(cleared, published))
+                throw unsafe();
+            if (cleared.size !== 0 || readSync(fd, bytes, 0, 1, 0) !== 0)
+                throw cleanupFailed();
+            return cleared;
+        }
+        finally {
+            try {
+                if (fd !== -1)
+                    closeSync(fd);
+            }
+            finally {
+                process.chdir(original);
+            }
+        }
+    }
+    async load() {
+        return this.guarded(async () => {
+            const directory = await this.directory(false);
+            if (!directory)
+                return null;
+            try {
+                return (await this.read(directory))?.record ?? null;
+            }
+            finally {
+                await directory.handle.close();
+            }
+        });
+    }
+    async save(value) {
+        return this.guarded(async () => {
+            const record = this.validate(value);
+            const directory = await this.directory(true);
+            if (!directory)
+                throw unsafe();
+            try {
+                await this.locked(directory, async () => {
+                    const existing = await this.read(directory);
+                    if (existing) {
+                        if (existing.record.token !== record.token || existing.record.tokenId !== record.tokenId || existing.record.scope !== record.scope)
+                            throw conflict();
+                        return;
+                    }
+                    await this.checkDirectory(directory);
+                    this.writeWithoutDelete(directory, record);
+                    await directory.handle.sync();
+                    await this.read(directory);
+                });
+            }
+            finally {
+                await directory.handle.close();
+            }
+        });
+    }
+    async remove(expectedToken, expectedRecord) {
+        return this.guarded(async () => {
+            if (!validToken(expectedToken))
+                throw unsafe();
+            const directory = await this.directory(false);
+            if (!directory)
+                return;
+            try {
+                await this.locked(directory, async () => {
+                    const existing = await this.read(directory);
+                    if (!existing || existing.record.token !== expectedToken)
+                        return;
+                    if (expectedRecord && !sameStoredRecord(existing.record, expectedRecord))
+                        throw conflict();
+                    await this.checkDirectory(directory);
+                    const current = await lstat(this.path);
+                    this.checkFile(current);
+                    if (!sameVersion(existing.stat, current))
+                        throw unsafe();
+                    const cleared = this.clearContents(directory, existing);
+                    await this.checkDirectory(directory);
+                    const beforeDelete = await lstat(this.path);
+                    this.checkFile(beforeDelete);
+                    if (!sameVersion(cleared, beforeDelete))
+                        throw unsafe();
+                    try {
+                        await unlink(this.path);
+                    }
+                    catch (error) {
+                        if (permissionFailure(error))
+                            throw error;
+                        throw cleanupFailed();
+                    }
+                    await directory.handle.sync();
+                    await this.checkDirectory(directory);
+                    try {
+                        await lstat(this.path);
+                    }
+                    catch (error) {
+                        if (missing(error))
+                            return;
+                        throw error;
+                    }
+                    throw cleanupFailed();
+                });
+            }
+            finally {
+                await directory.handle.close();
+            }
+        });
+    }
+}
+function sameCredential(a, b) {
+    const canonical = (origin) => origin === legacyProductionOrigin ? productionOrigin : origin;
+    return a.token === b.token && a.tokenId === b.tokenId && a.kind === b.kind && a.scope === b.scope && canonical(a.origin) === canonical(b.origin);
+}
+function sameStoredRecord(a, b) {
+    return sameCredential(a, b) && a.savedAt === b.savedAt;
+}
+export class CredentialStore {
+    path;
+    origin;
+    current;
+    legacy;
+    shared;
+    legacyClaim;
+    agent;
+    homeDir;
+    environment;
+    constructor(homeDir, environment, origin, agentName) {
+        this.agent = agentName === undefined ? undefined : agentIdentity(agentName);
+        this.homeDir = homeDir;
+        this.environment = environment;
+        this.current = new FileCredentialStore(homeDir, environment, origin, true, this.agent?.fileKey);
+        this.shared = new FileCredentialStore(homeDir, environment, origin, true);
+        this.legacyClaim = new FileCredentialStore(homeDir, environment, origin, true, undefined, true);
+        this.legacy = new FileCredentialStore(homeDir, environment, origin, false);
+        this.path = this.current.path;
+        this.origin = this.current.origin;
+    }
+    async load() {
+        if (this.agent)
+            return this.current.load();
+        const current = await this.current.load();
+        const legacy = await this.legacy.load();
+        if (current && legacy && !sameStoredRecord(current, legacy))
+            throw conflict();
+        return current ?? legacy;
+    }
+    async save(value) {
+        const record = this.current.validate(value);
+        if (this.agent) {
+            await this.current.save(record);
+            return;
+        }
+        const legacy = await this.legacy.load();
+        if (legacy && !sameStoredRecord(legacy, record))
+            throw conflict();
+        await this.current.save(record);
+        const checked = await this.load();
+        if (!checked || !sameCredential(checked, record))
+            throw conflict();
+    }
+    // Scoped reads use only their own file. Only an explicit 命令行 setup/login
+    // claims a retained shared key; logout finalizes its tombstone before clear.
+    // The unscoped branch preserves the pre-N105 low-level compatibility API.
+    async migrate() {
+        if (this.agent) {
+            // Retired records and the existing validation API have no client name.
+            // Their deterministic owner is 命令行. Other AI setups never read them.
+            if (this.agent.key !== agentIdentity("命令行").key)
+                return { migrated: false };
+            if (await this.legacyClaim.loadClaim())
+                return { migrated: false };
+            const shared = await this.shared.load(), legacy = await this.legacy.load();
+            if (shared && legacy && !sameStoredRecord(shared, legacy))
+                throw conflict();
+            const source = shared ?? legacy;
+            if (!source)
+                return { migrated: false };
+            const previous = await this.current.load();
+            // A newer named connection supersedes the retained old source. Preserve
+            // it, and finish the old source's tombstone without ever replacing it.
+            if (!previous)
+                await this.current.save(source);
+            const copied = await this.current.load();
+            if (!copied || (!previous && !sameStoredRecord(copied, source)))
+                throw conflict();
+            const checkedShared = await this.shared.load(), checkedLegacy = await this.legacy.load();
+            if ((shared && (!checkedShared || !sameStoredRecord(shared, checkedShared))) || (legacy && (!checkedLegacy || !sameStoredRecord(legacy, checkedLegacy))))
+                throw conflict();
+            // Publish only after the target and original sources have been verified.
+            // Remove also finalizes this claim, so a crash between copy and marker
+            // cannot resurrect an old key after an explicit logout/reconnect.
+            await this.legacyClaim.saveClaim({ version: 1, owner: "命令行", source_sha256: createHash("sha256").update(JSON.stringify(source)).digest("hex") });
+            return { migrated: !previous };
+        }
+        const legacy = await this.legacy.load();
+        const current = await this.current.load();
+        if (current && legacy && !sameStoredRecord(current, legacy))
+            throw conflict();
+        if (!legacy)
+            return { migrated: false };
+        // The retired production name is a read-only alias, not a file migration.
+        if (this.origin === productionOrigin && legacy.origin === legacyProductionOrigin)
+            return { migrated: false };
+        await this.current.save(legacy);
+        const copied = await this.current.load();
+        if (!copied || !sameStoredRecord(copied, legacy))
+            throw conflict();
+        try {
+            await this.legacy.remove(legacy.token, legacy);
+        }
+        catch (error) {
+            if (error instanceof CliError && error.code === "credential_conflict")
+                throw error;
+            const details = error instanceof CliError && error.code === "installation_permission_denied" ? { cause: error.code, ...error.details } : {};
+            throw new CliError("credential_migration_incomplete", "新位置的凭据已保存，但旧凭据尚未确认清理。", "请由本人处理旧凭据的访问或删除限制；不要读取其内容、绕过保护、重新授权或声称迁移完成。", 4, details);
+        }
+        if (await this.legacy.load())
+            throw conflict();
+        const verified = await this.current.load();
+        if (!verified || !sameStoredRecord(verified, legacy))
+            throw conflict();
+        return { migrated: true };
+    }
+    async remove(expectedToken) {
+        if (!validToken(expectedToken))
+            throw unsafe();
+        if (this.agent) {
+            const existing = await this.current.load();
+            if (!existing || existing.token !== expectedToken)
+                return;
+            if (this.agent.key === agentIdentity("命令行").key)
+                await this.migrate();
+            await this.current.remove(expectedToken, existing);
+            return;
+        }
+        const existing = await this.load();
+        if (!existing || existing.token !== expectedToken)
+            return;
+        await this.current.remove(expectedToken, existing);
+        await this.legacy.remove(expectedToken, existing);
+        if (await this.load())
+            throw conflict();
+    }
+}