SofiDevO/sofi-csrf
GitHub: SofiDevO/sofi-csrf
一个框架无关的 Node.js CSRF 防护库，提供 TypeScript 类型安全和 Token 轮换机制，已适配 Express 和 Hono。
Stars: 0 | Forks: 0
# Sofi CSRF
一个快速、完全类型化且框架无关的 CSRF (跨站请求伪造) 保护库，专为 Node.js 量身定制。它包含一个独立的核心逻辑引擎，并提供了一个专为 Express.js 设计的开箱即用适配器。
## 功能特性
- **框架无关的核心**：从路由逻辑中提取的安全 payload 生成器和时间安全的验证机制。适用于任何 HTTP node 服务器。
- **TypeScript First**：端到端类型化的类和函数，并使用 `TSDoc` 进行了完善的文档编写。
- **Express 适配器**：预包装的中间件，适当封装了 `req`、`res` 和 cookies，可轻松处理注入和错误抛出。
- **Token 轮换**：利用开箱即用的重新生成中间件，避免 token 重放攻击。
## 支持的框架与贡献
目前，`sofi-csrf` 为以下框架提供官方的“开箱即用”适配器：
- **Express.js**
- **Hono**
得益于其框架无关的核心引擎，我们欢迎社区的 PR！请随意通过创建新的适配器（Fastify, Koa, NestJS 等）来扩展生态系统。同样，我也会在时间允许的情况下逐步添加更多官方适配器。
## 安装
```
npm install sofi-csrf
```
*(Express 适配器注意：你应该在 Express 应用中使用 `cookie-parser`)*。
## 使用指南 (Express)
```
import express from 'express';
// Note: [cookie-parser](https://www.npmjs.com/package/cookie-parser) is required to extract cookies smoothly before this middleware
import cookieParser from 'cookie-parser';
import { expressCsrf } from 'sofi-csrf';
const app = express();
app.use(express.json());
app.use(cookieParser());
// 1. Initialize the middleware adapter (Accepts partial options)
const { csrfMiddleware, verifyCsrfToken, regenerateCsrfToken } = expressCsrf({
cookieName: 'xsrf-token', // Defaults to 'csrfToken'
cookieOptions: {
secure: process.env.NODE_ENV === 'production',
httpOnly: true,
maxAge: 3600000
}
});
// 2. Inject tokens globally (assigns token to local cookies, req and res.locals)
app.use(csrfMiddleware);
// 3. Retrieve token for frontend binding or views
app.get('/form', (req, res) => {
// Can be easily retrieved from req.csrfToken, or res.locals.csrfToken inside EJS/Pug templates!
res.json({ csrfToken: req.csrfToken });
});
// 4. Secure your data mutations routes
// Client must send the token either in req.body._csrf OR headers['x-csrf-token']
app.post('/submit', verifyCsrfToken, (req, res) => {
res.json({ message: "Successfully executed operation with valid token" });
});
// 5. Rotate the token
// Often necessary when performing high privilege or session-upgrade tasks
app.post('/sensitive-update', regenerateCsrfToken, (req, res) => {
res.json({ message: "Task completed securely. A new token has rolled.", newToken: req.csrfToken });
});
```
## 使用指南 (Hono)
```
import { Hono } from 'hono';
import { honoCsrf } from 'sofi-csrf';
const app = new Hono();
// 1. Initialize the adapter
const { csrfMiddleware, verifyCsrfToken, regenerateCsrfToken } = honoCsrf({
cookieName: 'xsrf-token',
});
// 2. Inject token in cookies and set it in context variables (c.get('csrfToken'))
app.use('*', csrfMiddleware);
// 3. Simple retrieval
app.get('/form', (c) => {
return c.json({ token: c.get('csrfToken') });
});
// 4. Secure data mutations, accepts 'x-csrf-token' header or '_csrf' in body
app.post('/submit', verifyCsrfToken, (c) => {
return c.text('Processed securely');
});
// 5. Native Token Rotation
app.post('/rotate', regenerateCsrfToken, (c) => {
return c.json({ message: "Rotated successfully", newToken: c.get('csrfToken') });
});
```
## API 文档
利用 IDE 的智能提示探索代码，享受详细的 `TSDocs` 片段和丰富的上下文信息。
### 内置接口
- `CsrfCore`：精选的算法验证逻辑。
- `CsrfOptions` 和 `defaultOptions`：处理可自定义的规则。
- `CsrfForbiddenError`：默认抛出的异常，包含 `403` 状态。
### 选项配置
在初始化适配器（例如 `expressCsrf()` 或 `honoCsrf()`）时，你可以传递一个可选的配置对象来覆盖 `defaultOptions`。
以下是你可以配置的完整选项列表：
| 选项 | 类型 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- |
| `cookieName` | `string` | `'csrfToken'` | 存储生成 token 的 cookie 名称。 |
| `tokenLength` | `number` | `24` | 用于生成的加密字节长度（生成一个 48 位的十六进制字符串）。 |
| `cookieOptions.httpOnly` | `boolean` | `true` | 防止客户端脚本通过 `document.cookie` 访问 cookie。 |
| `cookieOptions.secure` | `boolean` | `false` | 是否确保 cookie 仅通过 HTTPS 发送（强烈建议在生产环境中设置为 `true`）。 |
| `cookieOptions.maxAge` | `number` | `3600000` (1 小时) | cookie 的过期时间，以毫秒为单位。 |
## 支持
如果你觉得这个库有帮助，请考虑支持我的工作！
[](https://ko-fi.com/sofidev)
标签：CSRF防护, Express, Fastify, GNU通用公共许可证, Hono, HTTP安全, Koa, MITM代理, NestJS, Node.js, NPM包, OSV-Scalibr, Token验证, TypeScript, Web安全, 中间件, 全类型, 前后端安全, 安全插件, 无框架依赖, 网络安全, 自动化攻击, 蓝队分析, 跨站请求伪造, 隐私保护