auth-guard git:20260824.ed54ae6A

Immutable. This exact content is served forever at /api/v1/blob/5ef892b5c6ceb36b.

---
name: auth-guard
description: 公网访问鉴权与安全防护插件，提供 HTTP Bearer/API-Key 访问拦截、Token 密码学生成与公网就绪度状态评估
---

# auth-guard 插件

本插件为 rchat-assistant 服务提供**零外部依赖的 HTTP 访问鉴权**支持，方便将服务安全地暴露在局域网、公网（如 VPS、Docker 容器）或反向代理后。

## 核心特性

1. **零外部软件依赖**：无需安装第三方 VPN 或代理工具，Node.js 原生校验。
2. **多方式兼容**：
   - Authorization: Bearer <TOKEN>（标准 REST Header）
   - X-API-Key: <TOKEN>（API Key Header）
   - ?token=<TOKEN>（URL 查询参数，兼容不支持自定义 Header 的客户端与 SSE 接口）
3. **时序安全比对**：采用 crypto.timingSafeEqual 防范侧信道攻击。
4. **向后完全兼容**：若未设置 VRC_MONITOR_AUTH_TOKEN，服务默认对本地开放，不影响本地使用体验。

## 环境变量配置

在项目根目录 .env 文件中配置：

`env
# 1. 开启公网网卡监听（默认 127.0.0.1 仅本地可连，设为 0.0.0.0 允许外部连接）
VRC_MONITOR_HOST=0.0.0.0

# 2. 自定义端口（可选，默认 8799）
VRC_MONITOR_PORT=8799

# 3. 访问认证令牌（配置后强制开启全接口 401 拦截防护）
VRC_MONITOR_AUTH_TOKEN=your_secure_random_token_here
`

## MCP 工具

| 工具名 | 说明 |
| :--- | :--- |
| uth_get_status | 查看当前服务的监听 IP、端口、Token 启用情况与公网安全就绪度 |
| uth_generate_token | 生成 32 字节高强度随机 Token，并输出可直接写入 .env 的配置片段 |
| uth_verify_token | 校验指定 Token 是否与当前生效配置相匹配 |