@longzai-intelligence-elysia/helmet

Elysia 安全响应头插件（Helmet 等价），为 Elysia 应用注入 Content-Security-Policy、X-Content-Type-Options、X-Frame-Options、Referrer-Policy 等安全响应头。

概述

本插件提供与 NestJS helmet 中间件等价的安全响应头能力，便于双端服务（NestJS / Elysia）行为对齐。通过 Elysia 的 onRequest 钩子在请求进入阶段统一设置响应头（与 @elysiajs/cors 一致），不侵入请求处理逻辑。

覆盖的安全响应头：

| 响应头 | 默认值 | 说明 | | --- | --- | --- | | Content-Security-Policy | default-src 'self'; ... | 内容安全策略，控制资源加载来源 | | Cross-Origin-Resource-Policy | cross-origin | 跨域资源策略 | | X-DNS-Prefetch-Control | off | DNS 预取控制 | | X-Frame-Options | deny | 点击劫持防护（frameguard） | | X-Powered-By | （移除） | 隐藏服务器技术栈信息 | | X-Download-Options | noopen | IE 下载防执行 | | X-Content-Type-Options | nosniff | 阻止 MIME 嗅探 | | Referrer-Policy | strict-origin-when-cross-origin | Referer 发送策略 | | X-XSS-Protection | 1; mode=block | 旧版 IE XSS 过滤器 |

安装

bun add @longzai-intelligence-elysia/helmet

快速开始

import { Elysia } from 'elysia';
import { helmet } from '@longzai-intelligence-elysia/helmet';

// 使用默认配置（与 NestJS helmet 默认头集一致）
const app = new Elysia().use(helmet()).listen(3000);

配置

每项头可独立开关或覆盖值，未配置时使用与 helmet 一致的安全默认值。

import { helmet } from '@longzai-intelligence-elysia/helmet';

const app = new Elysia().use(
  helmet({
    // 禁用 CSP（如由 CDN / 反代统一设置）
    contentSecurityPolicy: false,

    // 收紧 frameguard 为 sameorigin
    frameguard: { action: 'sameorigin' },

    // 自定义 Referrer-Policy
    referrerPolicy: 'no-referrer',

    // 自定义 CSP 指令
    contentSecurityPolicy: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      objectSrc: ["'none'"],
    },
  }),
);

配置项

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | contentSecurityPolicy | object \| false | 见下方 | CSP 指令配置，false 禁用 | | crossOriginResourcePolicy | 'same-origin' \| 'same-site' \| 'cross-origin' \| false | 'cross-origin' | 跨域资源策略 | | dnsPrefetchControl | { allow: boolean } \| false | { allow: false } | DNS 预取控制 | | frameguard | { action: 'deny' \| 'sameorigin' } \| false | { action: 'deny' } | 点击劫持防护 | | hidePoweredBy | boolean | true | 隐藏 X-Powered-By | | ieNoOpen | boolean | true | IE 下载防执行 | | noSniff | boolean | true | 阻止 MIME 嗅探 | | referrerPolicy | string \| false | 'strict-origin-when-cross-origin' | Referer 策略 | | xssFilter | boolean | true | 旧版 IE XSS 过滤器 |

行为说明

• 时机：在 onRequest 阶段设置响应头（与 @elysiajs/cors 一致），响应阶段这些头会保留下发。
• 追加语义：elysia 的 set.headers 对已存在的头采用逗号拼接追加（非覆盖）。插件预设的安全头会保留在前，handler 设置的同名头追加其后。对 X-Frame-Options 等单值安全头，浏览器只取第一个值，因此插件预设值仍然生效（handler 难以意外放宽安全头）。
• hidePoweredBy：在 onRequest 阶段删除 X-Powered-By 头（elysia 默认不发此头，此配置确保此前设置的同名头被清除）。
• CSP 指令名转换：配置键使用 camelCase（如 defaultSrc），序列化时自动转 kebab-case（default-src）。

相关链接

• 变更记录