totp

针对敏感操作（环境变量、网关重启、备份删除、关键配置更改）的基于 TOTP 的 OTP 验证。使用 otplib 和 window:2（1 分钟容差）。

# TOTP Verification Skill

Secure OTP verification using TOTP (Time-based One-Time Password) for sensitive operations.

## Purpose

Protect access to:
- `.env` variables
- `openclaw.json` configuration
- Gateway restarts
- Backup deletions
- Critical configuration changes
- External API key operations

## Setup

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Generate secret and QR:**
   ```bash
   npm run generate
   ```
   Optionally pass service and account name:
   ```bash
   node scripts/generate-secret.js MyService myuser
   ```

3. **Send the QR image** (`qr.png`) to the user, then delete it immediately:
   ```bash
   rm qr.png
   ```

4. **Set TOTP_SECRET in `.env`:**
   ```env
   TOTP_SECRET=YOUR_BASE32_SECRET_HERE
   ```

5. **Configure Google Authenticator/Authy** with the generated secret or QR.

## Usage

When a sensitive operation is requested:

1. **Agent:** "Please provide your OTP"
2. **User:** Provides 6-digit code from authenticator app
3. **Agent:** Runs verification:
   ```bash
   TOTP_SECRET=$TOTP_SECRET node scripts/verify.js 123456
   ```
4. **If valid (exit 0):** Proceed with operation
5. **If invalid (exit 1):** Deny access

## Files

- `scripts/generate-secret.js` - Generate new TOTP secret and QR
- `scripts/verify.js` - Verify OTP tokens (window:2 = 1 minute tolerance)
- `SKILL.md` - This documentation

## Security Notes

- **Window:** 2 (1 minute tolerance) for time drift
- **Algorithm:** SHA1
- **Digits:** 6
- **Period:** 30 seconds
- **Secret:** Base32 encoded, stored in `.env` as `TOTP_SECRET`

## Integration

This skill should be integrated into the agent's decision flow when:
1. User requests `.env` variables
2. User requests `openclaw.json` contents
3. User requests gateway restart
4. User requests backup deletion
5. Any operation marked as "critical"

---

## 中文说明

# TOTP Verification Skill

针对敏感操作，使用 TOTP（基于时间的一次性密码）进行安全的 OTP 验证。

## 用途

保护对以下内容的访问：
- `.env` 变量
- `openclaw.json` 配置
- 网关重启
- 备份删除
- 关键配置更改
- 外部 API 密钥操作

## 设置

1. **安装依赖：**
   ```bash
   npm install
   ```

2. **生成密钥与二维码：**
   ```bash
   npm run generate
   ```
   可选地传入服务名和账户名：
   ```bash
   node scripts/generate-secret.js MyService myuser
   ```

3. **将二维码图片**（`qr.png`）发送给用户，然后立即删除：
   ```bash
   rm qr.png
   ```

4. **在 `.env` 中设置 TOTP_SECRET：**
   ```env
   TOTP_SECRET=YOUR_BASE32_SECRET_HERE
   ```

5. **配置 Google Authenticator/Authy**，使用生成的密钥或二维码。

## 用法

当请求敏感操作时：

1. **Agent：** "Please provide your OTP"
2. **User：** 提供身份验证器应用中的 6 位数字代码
3. **Agent：** 运行验证：
   ```bash
   TOTP_SECRET=$TOTP_SECRET node scripts/verify.js 123456
   ```
4. **如果有效（exit 0）：** 继续执行操作
5. **如果无效（exit 1）：** 拒绝访问

## 文件

- `scripts/generate-secret.js` - 生成新的 TOTP 密钥与二维码
- `scripts/verify.js` - 验证 OTP 令牌（window:2 = 1 分钟容差）
- `SKILL.md` - 本文档

## 安全说明

- **Window：** 2（1 分钟容差），用于时间漂移
- **Algorithm：** SHA1
- **Digits：** 6
- **Period：** 30 秒
- **Secret：** Base32 编码，作为 `TOTP_SECRET` 存储在 `.env` 中

## 集成

在以下情况下，本 skill 应被纳入代理的决策流程：
1. 用户请求 `.env` 变量
2. 用户请求 `openclaw.json` 内容
3. 用户请求网关重启
4. 用户请求备份删除
5. 任何被标记为 "critical" 的操作