ghid

A deterministic identity firewall for Git and GitHub.

ghid 是面向 Git 与 GitHub 的确定性身份防火墙。它根据仓库上下文解析应使用的开发者身份，验证 Git 作者、提交签名、SSH/HTTPS 认证与 GitHub CLI 账号是否一致，并在身份错配时给出可解释的诊断或阻止高风险操作。

为什么需要 ghid

同时使用个人、工作、客户或 GitHub Enterprise 账号时，一次完整的“身份选择”横跨多个彼此独立的系统：

• Git 作者与提交者：user.name、user.email
• Git 提交签名：SSH 或 GPG Signing Key
• Git 传输认证：SSH Key 或 HTTPS Credential
• GitHub CLI：Host、OAuth Account 与 Token
• 仓库上下文：Remote Host、Owner、Repository、工作目录与 Worktree

现有工具通常只切换其中一部分。局部状态看似正确，最终提交或推送仍可能落到另一个账号。ghid 的目标是把这些状态统一成一份可解析、可验证、可解释的身份契约。

项目目标

1. 确定性身份解析

为每个仓库计算唯一的期望身份，并公开完整解析过程。初步优先级为：

repository binding
  > exact remote repository
  > remote owner or organization
  > remote host
  > directory rule
  > session override
  > default profile

规则冲突必须显式报告，不进行静默猜测。

2. 统一身份契约

一个 Profile 应描述并关联：

• Git author 与 committer
• Commit signing format 与 key
• SSH identity
• HTTPS credential provider
• GitHub Host 与 Account
• 可选的仓库或组织约束

3. 验证实际身份，而不只读取配置

ghid 应同时检查期望状态与外部工具的实际结果：

• Git 最终生效的 author、committer 和 signing 配置
• SSH 最终选择的 Key 及 GitHub 识别出的账号
• HTTPS Credential 的账号来源
• gh OAuth Token 对应的 GitHub 账号
• Remote Owner、Repository 与 Profile 的匹配关系

4. 仓库级与进程级隔离

身份状态优先绑定到 Repository、Worktree、Remote 和子进程，避免依赖一份供所有终端共享的全局 Active Profile。

多个终端、IDE、GUI Git 客户端和后台任务应能并行使用不同身份。

5. 默认阻止身份串线

在明确配置了身份策略的仓库中，以下情况应产生清晰错误并阻止对应操作：

• Git author 或 committer 不匹配
• Signing Key 不匹配或缺失
• SSH / HTTPS 认证账号不匹配
• gh Account 不匹配
• 规则冲突或 Profile 解析结果不唯一

6. 可解释、可审计、可自动化

所有关键判断都应支持人类可读输出和稳定 JSON 输出：

ghid status
ghid status --explain
ghid doctor
ghid audit PATH
ghid status --json

7. 非破坏性配置管理

ghid 应优先维护自己的配置与生成文件，通过 Git 原生机制和进程级环境完成组合。所有外部配置变更都应支持预览、原子写入、来源标记和恢复。

8. 跨平台一致性

目标平台包括：

• macOS
• Linux
• Windows
• WSL

各平台适配应保持相同的身份解析和验证语义。

v0.1 目标范围

• Profile 的创建、导入、查看与删除
• 从 GitHub CLI 导入已登录账号，不复制明文 Token
• Repository-local 身份绑定
• Remote Host / Owner / Repository 规则
• Git author、committer 与 signing 验证
• SSH 与 gh 实际账号验证
• status --explain
• doctor
• Commit / Push 身份检查 Hook
• 在指定身份上下文中执行子进程
• 稳定 JSON 输出
• Worktree、Submodule、多个 Remote 和并发终端测试

首期非目标

• 自建 OAuth 或 Token Vault
• 替代 GitHub CLI、系统 Keychain 或成熟 Credential Helper
• 完整 Git GUI
• 自动重写已有提交历史
• 云端团队管理平台
• 同时覆盖所有 Git 托管平台

首期专注 GitHub.com 与 GitHub Enterprise；底层模型保留扩展到其他托管平台的边界。

成功标准

ghid v0.1 应能在执行 Commit、Push 或 gh 命令前，可靠回答：

这个仓库应该使用哪个身份？
Git 实际会以谁的名义提交？
提交会使用哪把签名密钥？
GitHub 最终会把本次认证识别成哪个账号？
为什么选择这个身份？

当这些答案不一致时，ghid 应准确指出冲突来源，并给出可预览的修复方案。

开发状态

项目当前处于目标定义与架构设计阶段。首个实现里程碑将在身份模型、解析优先级、凭据边界和验证契约确定后开始。

License

MIT