Game Boy 上的 TOTP 双因素验证器：兼容 Google Authenticator 协议

一个真正的 RFC 6238 TOTP 身份验证器，适用于 Game Boy、Game Boy Color 和 Super Game Boy。通过卡带上的字符拨盘添加账户，将它们存储在电池备份的 SRAM 中，生成每 30 秒滚动一次的实时 6 位验证码——与 Google Authenticator、Authy 等使用相同的协议。把卡带插入真正的 DMG，看着你的磷光绿秘密跳动。

一个原生 Game Boy Advance 移植版位于同级仓库 totp-gba（240×160 布局，ARM7TDMI，libtonc）。

屏幕



主列表 — 实时验证码 + 30 秒进度条	查看账户 — 完整密钥 + 删除	设置 — 调色板 + 声音

设置时间 — 年/月/日/时/分/秒光标	添加账户 — 字符拨盘

完整图库 + 复现说明见 docs/screens/README.md。

试一试

预构建的 ROM 已签入 artifacts/ 下：

文件	目标	备注
`totp-gb.gb`	DMG / Pocket / Light / SGB	MBC3+TIMER+RAM+BATTERY，支持 SGB
`totp-gbc.gbc`	Game Boy Color、GBA 兼容模式、SGB	兼容 CGB，全彩调色板
`totp-gb-test.gb`	DMG	带自动种子 `Test` 账户的调试构建

在 mGBA、BGB 或 SameBoy 中加载其中任意一个即可开始。在真实硬件上，你需要一个 MBC3+RAM+BATTERY 烧录卡（EZ-FLASH Junior、EverDrive GB 或任何克隆版）。

首次启动会提示你设置 UTC 时间——TOTP 按 UTC 计算，所以请对照 https://www.utctime.net/ 这样的时钟，而不是你的本地时间。之后，Start 添加账户（先名称后 base32 密钥），A 查看并可选删除，B 重新同步时钟，SELECT 打开设置，L/R 在主界面循环切换调色板。

从源码构建

需要将 GBDK-2020（https://github.com/gbdk-2020/gbdk-2020/releases）解压到这里的 gbdk/ 中，或者如果你设置了 GBDK_DIR，可以放在任何位置。

build.bat            # both DMG and CGB variants
build.bat dmg        # DMG only
build.bat gbc        # GBC only
build.bat test       # DMG with TEST_SEED_ON_BOOT (preloads a Hello! account)

监视模式会在源码更改时重新构建：

watch.bat            # rebuilds both ROMs on save

功能

HMAC-SHA1 / TOTP 遵循 RFC 6238，以纯 C 移植——无 GBDK 依赖，被 GBA 构建原样复用
持久存储，在 MBC3 SRAM 中最多支持 8 个账户
卡带内账户输入 — 字符拨盘（L/R 滚动，A 追加，B 退格）
实时时钟 通过 MBC3 定时器；用户可设置，跨电源循环持久保存（每 30 秒心跳保存）
多平台色彩 — 12 种 GBC 调色板（磷光绿、琥珀 CRT、Pip-Boy、Solarized、Atari 2600、GB Camera、亮粉色、冰蓝……）和 8 种 DMG BGP 变体（正常、反色、高对比度、柔和、深色模式……）
Super Game Boy 支持 — 启动时磷光绿 PAL01 数据包，加上通过 SGB_CHR_TRN / SGB_PCT_TRN 的程序化深蓝色边框与绿色强调线
GBC 双倍速 模式，在真实 CGB 上实现流畅 UI
音效 — APU 点击 / 确认 / 错误 / 窗口翻转提示音，设置中有静音开关
自动滚动长账户名、紧迫倒计时（窗口最后 5 秒内每剩余一秒 !）、动画启动画面

测试

带种子的测试 ROM（build.bat test）通过一个 Lua 脚本进行端到端验证，该脚本从 BG 图块映射中读取实时验证码，并与 720 窗口的预计算表进行匹配——在真实 GB 硬件上证明了完整的加密 + RTC + UI 流水线：

.\build.bat test
mGBA -> File -> Load ROM -> artifacts\totp-gb-test.gb
mGBA -> Tools -> Scripting -> File -> Load script -> tests\verify_test_rom.lua

输出：

[ OK ] Seed string present in ROM (0x1569)
[INFO] Visible code field: '813 431'
[PASS] Displayed code 813431 matches window +120s (epoch 1778088210, T=59269607).
       Crypto pipeline + RTC + UI all verified end-to-end.

完整说明见 tests/README.md。

布局

src/                Pure-C sources (algorithm + GBDK platform code)
  ├ sha1.c hmac.c base32.c totp.c   crypto core (no GBDK deps)
  ├ rtc.c storage.c input.c audio.c platform glue
  ├ ui.c                            screens + widgets
  └ sgb_border.c                    procedural SGB border
artifacts/          Prebuilt ROMs (committed)
docs/screens/       Reference screenshots
tests/              Lua verifier + expected-code table
gbdk/               GBDK-2020 toolchain (vendored locally, gitignored)
build.bat           Windows build script (parallel DMG + CGB)
watch.bat           Auto-rebuild on save

致谢

GBDK-2020 — Z80 工具链 + libgb
mGBA — 支持 SGB 和 RTC 的精确模拟器
pandocs — 权威的 GB 硬件参考
mcp-mgba — 用于驱动 mGBA 进行截图库和验证自动化的 MCP 服务器

许可证

在 MIT 许可证下发布。