# 纯 Token 模式配置指南

## 功能说明

纯 Token 模式（Token Only Mode）允许短信转发接收端**只验证 token 参数**，跳过 HMAC-SHA256 签名验证。

### 适用场景

- TranspondSms APP 不支持或不需要 HMAC 签名
- 快速测试/开发环境
- 简化配置，降低部署复杂度

### 安全性建议

- **生产环境建议使用标准模式**（Token + HMAC 签名）
- 纯 Token 模式下，请确保网络环境可信（内网、VPN）
- 定期更换 token

---

## 配置方法

### 1. 编辑 `config.json`

```json
{
  "security": {
    "enabled": true,
    "username": "admin",
    "password": "admin123",
    "session_lifetime": 3600,
    "secret_key": "default_secret_key_change_me",
    "sign_verify": true,
    "sign_max_age": 3600000,
    "token_only_mode": true    // 启用纯 Token 模式
  },
  "api_tokens": [
    {
      "name": "测试设备",
      "token": "my_simple_token_123",
      "secret": "",
      "enabled": true
    }
  ]
}
```

### 关键配置项

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `token_only_mode` | Boolean | 是否启用纯 Token 模式（默认 `false`） |
| `token` | String | Token 值（TranspondSms 发送的值） |
| `secret` | String | 在纯 Token 模式下可以为空 |

### 2. 重启服务

```bash
./sms_receiverctl.sh restart
```

或使用 systemd：

```bash
systemctl restart sms_receiver
```

---

## TranspondSms 配置

### 标准 Token + 签名模式（默认）

TranspondSms 配置：

```
Token (URL): http://your-server:9518/api/receive?token=my_token
Secret: my_secret_key
```

### 纯 Token 模式

TranspondSms 配置：

```
Token (URL): http://your-server:9518/api/receive?token=my_simple_token_123
Secret: (留空或随意)
```

**注意**：TranspondSms 仍会发送签名参数，但服务端会忽略签名验证，只验证 token 是否匹配。

---

## API 行为对比

### 标准 Token + 签名模式

1. TranspondSms 发送请求：
   - `from`: 发送方号码
   - `content`: 短信内容
   - `timestamp`: 时间戳
   - `sign`: HMAC-SHA256 签名
   - `token`: 识别设备

2. 服务端验证：
   - 根据 token 查找对应的 secret
   - 验证 HMAC 签名是否匹配
   - 验证时间戳是否过期
   - 保存短信记录

### 纯 Token 模式

1. TranspondSms 发送请求（同样参数，但签名被忽略）：
   - `from`: 发送方号码
   - `content`: 短信内容
   - `token`: 识别设备

2. 服务端验证：
   - **只验证 token 是否存在于配置列表中**
   - **跳过签名验证**
   - **跳过时间戳验证**
   - 保存短信记录（标记为 `sign_verified: true`）

---

## 错误处理

### Token 无效（纯 Token 模式）

```json
{
  "error": "Token 无效"
}
```

返回：HTTP 401

### 缺少 Token（纯 Token 模式）

```json
{
  "error": "缺少 token 参数（纯 Token 模式已启用）"
}
```

返回：HTTP 401

---

## 日志记录

服务会在日志中记录 Token 验证结果：

```
Token 验证成功: my_simple_token_123
收到短信: 10086 -> 【移动】验证码是 123456... (ID: 1)
```

---

## 切换回标准模式

将 `token_only_mode` 设置为 `false` 并重启服务：

```json
{
  "security": {
    "token_only_mode": false
  }
}
```

```bash
./sms_receiverctl.sh restart
```

---

## 常见问题

### Q: 纯 Token 模式安全吗？

A: 相比标准模式，纯 Token 模式安全性较低（没有签名保护）。建议在内网环境或使用 VPN 的场景下使用。

### Q: 纯 Token 模式下还需要配置 secret 吗？

A: 不需要。`secret` 字段可以为空。

### Q: 可以混合使用两种模式吗？

A: 不可以。一个服务实例要么是标准模式，要么是纯 Token 模式。

### Q: TranspondSms 不发送签名会怎样？

A: 即使配置了标准模式，如果 TranspondSms 不发送签名，请求会失败（HTTP 403）。此时请使用纯 Token 模式。

---

## 代码变更

### 配置文件 (`config.py`)

```python
# 新增配置项
TOKEN_ONLY_MODE = False
```

### 接收逻辑 (`app.py`)

```python
if app.config['TOKEN_ONLY_MODE']:
    # 纯 Token 模式：只验证 token
    if not token_param:
        return jsonify({'error': '缺少 token 参数'}), 401

    # 查找 token 并验证
    for token_config in app.config['API_TOKENS']:
        if token_config.get('token') == token_param:
            token_valid = True
            break

    if not token_valid:
        return jsonify({'error': 'Token 无效'}), 401
else:
    # 标准 Token + 签名模式
    # ... 原有逻辑
```

---

## 相关文件

- `config.py` - 配置类定义
- `config.json` - 配置文件
- `app.py` - 主应用逻辑
- `settings.html` - 设置页面
- `TOKEN_ONLY_MODE.md` - 本文档