name: otp-challenger
version: 1.0.3
description: 在执行敏感操作前，使代理和技能能够要求用户提供最新的双因素身份验证证明（TOTP 或 YubiKey）。用于审批流程中的身份验证——部署命令、财务操作、数据访问、管理员操作和变更控制。
metadata: {"openclaw": {"emoji": "🔐", "homepage": "https://github.com/ryancnelson/otp-challenger", "requires": {"bins": ["jq", "python3", "curl", "openssl", "base64"], "anyBins": ["oathtool", "node"]}, "envVars": {"required": [], "conditionallyRequired": [{"name": "OTP_SECRET", "condition": "TOTP 模式", "description": "Base32 TOTP 密钥（16-128 个字符）"}, {"name": "YUBIKEY_CLIENT_ID", "condition": "YubiKey 模式", "description": "Yubico API 客户端 ID"}, {"name": "YUBIKEY_SECRET_KEY", "condition": "YubiKey 模式", "description": "Yubico API 密钥（base64 编码）"}], "optional": [{"name": "OTP_INTERVAL_HOURS", "default": "24", "description": "验证有效期"}, {"name": "OTP_MAX_FAILURES", "default": "3", "description": "触发速率限制前的失败尝试次数"}, {"name": "OTP_FAILURE_HOOK", "description": "验证失败时执行的脚本（特权功能——可运行任意命令）"}]}, "privilegedFeatures": ["OTP_FAILURE_HOOK 可在失败事件时执行任意 shell 命令"], "install": [{"id": "jq", "kind": "brew", "formula": "jq", "bins": ["jq"], "label": "通过 Homebrew 安装 jq", "os": ["darwin", "linux"]}, {"id": "python3", "kind": "brew", "formula": "python3", "bins": ["python3"], "label": "通过 Homebrew 安装 Python 3", "os": ["darwin", "linux"]}, {"id": "oathtool", "kind": "brew", "formula": "oath-toolkit", "bins": ["oathtool"], "label": "通过 Homebrew 安装 OATH Toolkit", "os": ["darwin", "linux"]}]}}

OTP 身份验证技能

在执行敏感操作前，要求用户提供最新的双因素身份验证。

使用场景

在以下操作前要求 OTP 验证：
- 部署命令（kubectl apply、terraform apply）
- 财务操作（转账、付款审批）
- 数据访问（PII 导出、客户数据）
- 管理员操作（用户修改、权限变更）

脚本

verify.sh

验证用户的 OTP 代码并记录验证状态。

./verify.sh <user_id> <code>

参数：
- user_id - 用户标识符（例如：邮箱、用户名）
- code - 6 位 TOTP 代码或 44 位 YubiKey OTP

退出码：
- 0 - 验证成功
- 1 - 无效代码或触发速率限制
- 2 - 配置错误（缺少密钥、格式无效）

成功输出：

✅ OTP 已验证，用户：<user_id>（有效期 24 小时）
✅ YubiKey 已验证，用户：<user_id>（有效期 24 小时）

失败输出：

❌ OTP 代码无效
❌ 尝试次数过多。请 X 分钟后重试。
❌ 代码格式无效。应为 6 位 TOTP 或 44 位 YubiKey OTP。

check-status.sh

检查用户的验证是否仍然有效。

./check-status.sh <user_id>

退出码：
- 0 - 用户具有有效（未过期）的验证
- 1 - 用户未验证或验证已过期

输出：

✅ 剩余有效期：23 小时
⚠️ 已于 2 小时前过期
❌ 从未验证

generate-secret.sh

生成新的 TOTP 密钥并附带二维码（需要安装 qrencode）。

./generate-secret.sh <account_name>

使用模式

#!/bin/bash
source ../otp/verify.sh

if ! verify_otp "$USER_ID" "$OTP_CODE"; then
  echo "🔒 此操作需要 OTP 验证"
  exit 1
fi

# 继续执行敏感操作

配置

TOTP 必需配置：
- OTP_SECRET - Base32 TOTP 密钥

YubiKey 必需配置：
- YUBIKEY_CLIENT_ID - Yubico API 客户端 ID
- YUBIKEY_SECRET_KEY - Yubico API 密钥（base64 编码）

可选配置：
- OTP_INTERVAL_HOURS - 验证过期时间（默认：24）
- OTP_MAX_FAILURES - 触发速率限制前的失败尝试次数（默认：3）
- OTP_STATE_FILE - 状态文件路径（默认：memory/otp-state.json）

可通过环境变量或在 ~/.openclaw/config.yaml 中设置配置：

security:
  otp:
    secret: "BASE32_SECRET"
  yubikey:
    clientId: "12345"
    secretKey: "base64secret"

代码格式自动检测

脚本自动检测代码类型：
- 6 位数字（123456）→ TOTP 验证
- 44 位 ModHex 字符（cccccc...）→ YubiKey 验证

ModHex 字母表：cbdefghijklnrtuv

状态文件

验证状态存储在 memory/otp-state.json 中。仅包含时间戳，不包含密钥。

详细文档

请参阅 README.md 获取：
- 安装说明
- 设置指南（TOTP 和 YubiKey）
- 安全注意事项
- 故障排除
- 示例