Authentication & Security
Relevant source files
The following files were used as context for generating this wiki page:
OneBots provides a multi-layered security architecture that protects management interfaces and protocol gateways. The system secures internal administration through device pairing and revokable sessions while enforcing protocol-specific authentication for external downstream clients. Core security logic resides in @onebots/core via specialized middleware and validation systems.
Sources: AGENTS.md:148-152, README.en.md:112-115
Core Security Architecture
The framework centralizes security enforcement in the packages/core middleware. This layer processes all incoming traffic before it reaches protocol implementations or management routes.
Security Middleware Components
- Token Manager: Manages the lifecycle of authentication credentials.
- Token Validator: Enforces credential checks against configured protocol requirements.
- Rate Limit: Prevents brute-force attacks and resource exhaustion.
- Security Audit: Records security-sensitive operations for administrative review.
Sources: AGENTS.md:149-152, packages/core/ARCHITECTURE.md:5-10
The diagram shows the sequence of security checks applied to every incoming request before dispatching to the target service.
Protocol Authentication Standards
Each supported protocol follows its official specification for authentication. The gateway enforces these standards for HTTP API calls, WebSocket upgrades, and Webhook deliveries.
OneBot 11 & 12
OneBot implementations use access_token verification. OneBot 12 specifically requires checking the Authorization header before falling back to URL query parameters.
| Requirement | OneBot 11 | OneBot 12 |
|---|---|---|
| Header | Authorization: Bearer <token> | Authorization: Bearer <token> |
| Query Param | ?access_token=<token> | ?access_token=<token> |
| Priority | Query takes precedence | Header takes precedence |
| Error Code | 401 Unauthorized | 401 Unauthorized |
| Webhook Signature | HMAC-SHA1 (X-Signature) | N/A |
Sources: tests/PROTOCOL_AUTH_HEARTBEAT.md:16-51, tests/onebot/v12/webhook/headers.spec.js:144-165
Satori and Milky
Satori and Milky rely primarily on Bearer Tokens. Satori implementations also utilize identity headers to distinguish platform namespaces.
This sequence illustrates the token verification process within the Satori V1 protocol implementation.
Sources: protocols/satori-v1/protocol/src/index.ts:241-267, tests/PROTOCOL_AUTH_HEARTBEAT.md:61-81
Sensitive Data Management
OneBots implements strict boundaries for sensitive configuration data. The management console protects fields such as platform tokens, secrets, and adapter credentials.
Configuration Protection
- Field Masking: The Web UI uses
secret-statesto track and mask sensitive fields in theControlConfigurationPanel. - Server-Side Protection: The server protects specific configuration paths. The system retains original values for unknown or protected paths to prevent accidental empty-value overwrites.
- Environment Safety: The project strictly prohibits committing
config.yamlor environment-specific tokens to the repository.
Sources: packages/web/src/components/ControlConfigurationPanel.vue:152-156, CONTRIBUTING.md:126-128, AGENTS.md:144-147
Implementation of Satori Token Verification
The Satori protocol implementation manually validates the token from the Authorization header during HTTP requests and the IDENTIFY opcode during WebSocket handshakes.
// protocols/satori-v1/protocol/src/index.ts:245-257
const authHeader = ctx.headers["authorization"];
const token =
typeof authHeader === "string"
? authHeader.replace(/^Bearer\s+/i, "").trim()
: undefined;
if (!this.verifyToken(token)) {
ctx.status = 401;
ctx.body = { message: "Unauthorized" };
return;
}
Sources: protocols/satori-v1/protocol/src/index.ts:245-257
Management Interface Security
Security for the administrative management console differs from protocol gateway security to prevent cross-contamination of credentials.
- Device Pairing: Initial access requires a one-time bootstrap device code.
- Revokable Sessions: The management console uses sessions that administrators can revoke independently of gateway operations.
- Separation of Concerns: Management authentication remains isolated from the
access_tokenused by downstream bots.
Sources: AGENTS.md:144-152, README.en.md:80-85
Summary of Security Best Practices
| Category | Enforced Policy |
|---|---|
| Error Handling | Catch blocks must record error level logs; never swallow exceptions silently. |
| External Data | Use unknown types and Type Guards for all external SDK data. |
| Log Integrity | Prohibit console.log in production; use structure logger.xxx() with operation tracking. |
| Transport | Use HTTPS/WSS for remote connections; enforce access_token for all gateway ports. |
Sources: CONTRIBUTING.md:68-85, AGENTS.md:144-152