KeyForge 是一个确定性密码生成器。它根据以下输入生成站点密码：

• master password
• site
• username
• length
• symbols 开关

相同输入会稳定生成相同密码，因此不需要保存每个网站的密码；但也意味着你必须牢记 master password，并保持 site / username / length / symbols 配置一致。

• 功能
• 安装
  • 从源码安装
  • 从 GitHub Release 安装
• 使用
  • 生成并打印密码
  • 指定 username
  • 指定密码长度
  • 启用符号
  • 复制到剪贴板
  • 记住站点配置
  • 生成 shell completion
• 配置文件
• Site 归一化规则
• 未来计划
• 开发
• 使用风险和注意事项

• Argon2id 密钥派生
• HMAC-SHA256 扩展输出
• 拒绝采样生成密码字符，避免取模偏差
• 可选符号字符集：!@#$%^&*
• master password 隐藏输入和二次确认
• 默认将 username 转为小写
• site 归一化为 hostname 小写形式
• 可将密码打印到终端或复制到剪贴板
• 剪贴板超时自动清除
• --remember 保存站点配置
• shell completion 生成
• Unix 下 config 目录和文件权限保护

需要 Rust 工具链。

# 直接编译安装
cargo install --path . --locked
# 本地构建 release binary，需要自己添加到path
cargo build --release

可以从这里选择需要的版本下载，https://github.com/0x3ea/keyforge/releases

Linux / macOS 可以使用安装脚本：

curl -fsSL https://github.com/0x3ea/keyforge/releases/latest/download/install.sh | sh

Windows 不提供安装脚本。请从 GitHub Release 手动下载 Windows 压缩包：

keyforge-x86_64-pc-windows-msvc.zip

解压后得到：

keyforge.exe

建议放到固定目录，例如：

%LOCALAPPDATA%\Programs\keyforge\bin\keyforge.exe

然后将该目录加入用户环境变量 Path。重新打开终端后即可运行：

keyforge --version

keyforge github.com -p

程序会提示输入并确认 master password。

keyforge github.com -u alice -p

username 会被归一化为小写。

keyforge github.com -u alice -l 20 -p

当前生成密码长度范围为 12..=128。

keyforge github.com -u alice -l 24 -s -p

启用后字符集会额外包含：

!@#$%^&*

不传 -p 时，密码会写入剪贴板：

keyforge github.com -u alice --timeout 45

默认超时为 45 秒。超时后，如果剪贴板内容仍然是刚复制的密码，KeyForge 会清空当前剪贴板。

keyforge github.com -u alice -l 20 -s -r -p

--remember 会保存当前站点的：

• username
• length
• symbols

之后可以直接运行：

keyforge github.com -p

KeyForge 会从配置文件读取该站点的规则。

keyforge completion bash
keyforge completion zsh
keyforge completion fish
keyforge completion powershell

将输出内容安装到对应 shell 的补全目录即可。

配置文件位置由系统配置目录决定，通常为：

~/.config/keyforge/config.json

配置示例：

{
  "defaultUserName": "",
  "defaultLength": 16,
  "defaultSymbols": false,
  "defaultTimeout": 45,
  "defaultPrint": false,
  "defaultRemember": false,
  "sites": {
    "github.com": {
      "userName": "alice",
      "length": 20,
      "symbols": true
    }
  }
}

Unix 下 KeyForge 会尽量确保：

• 配置目录权限为 0700
• 配置文件权限为 0600

配置文件不保存 master password，也不保存生成出的密码，但会保存站点名、username 和密码规则，这些仍然属于敏感元数据。

KeyForge 会将输入 site 归一化为 hostname 小写形式。

例如：

GitHub.com                  -> github.com
https://GitHub.com/path     -> github.com
  github.com                -> github.com

注意：路径不会参与密码派生。因此下面两个输入会对应同一个 site：

https://example.com/login
https://example.com/account

它们都会归一化为：

example.com

• Chrome / Edge / Firefox 浏览器插件：在浏览器中识别当前站点，调用 KeyForge 规则生成密码，减少手动输入 site 的步骤。

.
├── Cargo.toml                 # Rust package 配置和依赖
├── Cargo.lock                 # 锁定依赖版本
├── README.md                  # 项目说明
├── keyforge.md                # 设计和实现计划
├── scripts/
│   └── install.sh             # Linux / macOS 安装脚本
├── .github/workflows/         # CI / Release workflow
├── tests/
│   └── integration.rs         # 集成测试
└── src/
    ├── lib.rs                 # library crate 模块导出
    ├── main.rs                # CLI 入口和主流程编排
    ├── cli.rs                 # clap 参数定义、子命令和 site 归一化
    ├── config.rs              # JSON 配置读写、默认值和权限处理
    ├── crypto.rs              # salt 构建和 Argon2id 密钥派生
    ├── encode.rs              # HMAC 扩展、拒绝采样和密码编码
    ├── sensitive.rs           # SecretVec，负责 zeroize 和 mlock
    ├── term.rs                # master password 隐藏输入和确认
    ├── clipboard.rs           # 剪贴板写入、超时清除和 Ctrl+C 处理
    └── completions.rs         # shell completion 生成

KeyForge 是确定性密码生成器，使用前请理解以下风险。

KeyForge 不保存密码，也没有恢复机制。如果你忘记 master password，过去生成的站点密码无法恢复。

生成结果依赖以下输入：

• master password 主密码
• site 站点
• username 用户名
• length 密码长度
• symbols 密码符号集

任意一项变化，都会生成不同密码。

例如：

github.com + alice

和：

github.com + alice@example.com

会生成不同密码。

KeyForge 会忽略 URL path、query、fragment，只使用 hostname。

这意味着：

https://example.com/login
https://example.com/admin

会使用同一个 site：

example.com

如果你希望同一域名下不同服务使用不同密码，需要通过不同 username 或不同 site 约定区分。

Alice、ALICE、alice 会被视为同一个 username：

alice

如果某个服务区分 username 大小写，需要注意这一点。

使用：

keyforge github.com -p

会将密码打印到标准输出。风险包括：

• 被旁边的人看到
• 被终端滚动历史保留
• 被录屏或日志系统记录
• 被 shell wrapper 或命令捕获工具记录

如果不是调试或手动复制，优先使用剪贴板模式。

KeyForge 可以清除当前系统剪贴板内容，但不能可靠清除剪贴板管理器已经保存的历史记录。

例如以下工具或桌面环境可能保存历史：

• KDE Klipper
• CopyQ
• GNOME clipboard extensions
• cliphist
• 其他剪贴板管理器

如果你使用剪贴板管理器，请将 KeyForge 复制的密码加入忽略规则，或关闭密码相关历史记录。

很多桌面程序都可以访问剪贴板。复制密码后，在超时清除前，其他本地程序可能读取到密码。

配置文件不包含 master password 和生成出的密码，但包含：

• 使用过的网站
• username
• 每个站点的密码长度和符号策略

这些信息可能暴露你的账户分布和登录习惯。请保护好配置文件和系统账户。

当前项目仍处于早期阶段。未来如果编码算法、site 规则或配置解析规则发生变化，相同输入可能生成不同密码。

正式使用前，建议：

• 固定使用某个 release 版本
• 记录版本号
• 升级前先验证关键站点输出是否符合预期

KeyForge 只能降低密码存储和派生过程中的部分风险，不能替代系统安全。