dgknbtl/jaga

# 🛡️ Jaga [](https://www.npmjs.com/package/jagajs) [](https://bundlephobia.com/result?p=jagajs) [](https://github.com/dgknbtl/jaga/blob/main/LICENSE) [](https://www.typescriptlang.org/) **Jaga** 是一个用于 HTML 模板的超轻量级、零依赖安全层，在用户输入和 DOM 之间提供上下文感知的 XSS 保护。 阅读 [Jaga 宣言](MANIFESTO.md) ## 功能 - **智能上下文感知**：自动识别多部分属性、连续属性和闭合标签中的注入上下文 —— 针对 `text`、`attr`、`url` 和 `css` 上下文应用正确的转义规则。 - **HTML Sanitizer**：SSR 原生白名单 sanitizer (`jagajs/sanitize`) —— 零依赖，适用于 Node.js、Bun、Deno。开箱即用地包含对 `data-*` 属性的支持。 - **CSS 上下文保护**：通过词法分析和严格转义，防止 `style` 属性中的 CSS Injection。 - **内置 URL Sanitization**：主动拦截 `javascript:` 及其他危险协议，包括编码绕过尝试。 - **原生 Trusted Types 支持**：自动与浏览器的 Trusted Types API 集成，实现超安全的 DOM 赋值。 - **安全的 JSON 注入**：`j.json(data)` 可将状态安全地嵌入 `` 越狱问题。 ``` const state = { user: "Admin", bio: "", }; const html = j` `; ``` ### 3. 列表渲染 **Jaga** 能够无缝且安全地处理数组： ``` const items = ["Safe", "Bold", "Italic"]; const list = j`

${items.map((i) => j`
• ${i}
`)}

`; ``` ### 4. 智能 Minifier **Jaga** 的 `j` 标签会通过移除不必要的空白来自动压缩你的 HTML，并且它足够智能，能够忽略 `

` 和 `` 标签。


```
const html = j`

  <div>

    <span>Compact but...</span>

    <pre>  This space is preserved!  </pre>

  </div>

`;
```


### 5. CSP 安全 Nonce

轻松为内联脚本注入 CSP nonce：


```
import { j, nonce } from "jagajs";



const myNonce = nonce();

const script = j`<script nonce="${myNonce}">console.log('Safe script');</script>`;
```


### 6. 词法 CSS 保护

**Jaga** 具备一个生产级别的 **极简词法 CSS sanitizer**。

与基于正则表达式的转义器不同，它使用字符级状态机和类型化的 AST 来强制实施严格的安全保证：

- **严格白名单**：仅允许明确通过的安全属性（例如 `color`、`font-size`）。
- **现代 CSS 支持**：包含逻辑属性，如 `margin-inline-start`、`padding-block-end` 等。
- **协议 Sanitization**：`url()` 值被限制为安全协议（例如 `https:`、`data:image/`）。
- **边界强制执行**：通过禁止属性越狱或新声明来防止注入。


```
const maliciousStyle = 'color: red; background: url("javascript:alert(1)");';

const html = j`<div style="${maliciousStyle}">Safe Content</div>`;



// Result: <div style="color:red;">
```




## 兼容 Trusted Types

**Jaga** 的 `JagaHTML` 包装器旨在与浏览器的 [Trusted Types API](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) 原生集成。当你的 CSP 强制执行 `require-trusted-types-for 'script'` 时，**Jaga** 会自动创建一个策略，并通过 `.toTrusted()` 方法返回一个 `TrustedHTML` 对象（或者在预期为字符串但需要 Trusted Types 的情况下，使用 **Jaga** 的输出时自动执行）。


```
// Jaga handles the policy creation and wrapping for you:

const html = j`<div>${userInput}</div>`;



// Assign directly to innerHTML (Compatible with Trusted Types CSP)

element.innerHTML = html.toTrusted();
```






## 框架集成（处理不安全的 HTML）

框架默认安全地处理了大多数情况。**Jaga** 专为它们留给开发者的边缘情况而设计。

在框架环境中，**Jaga** 通常通过 `sanitize(...).toString()` 使用，然后再将结果传递给特定框架的 API。



### React / Next.js (App Router)

当你需要在 React 中安全地渲染由用户控制的 HTML 时，尤其是在使用 `dangerouslySetInnerHTML` 的情况下，**Jaga** 非常有用。

它在 Server Components 中表现得尤为出色，此时 Jaga 完全在服务端运行，对客户端零开销。


```
// app/page.js (Server Component)

import { sanitize } from "jagajs/sanitize";



export default function Page({ searchParams }) {

  const clean = sanitize(searchParams.bio).toString();

  return <div dangerouslySetInnerHTML={{ __html: clean }} />;

}
```




### Vue 3 / Nuxt 3

在使用 `v-html` 绑定之前，使用 **Jaga** 安全地处理用户 HTML。


```
<!-- components/UserBio.vue -->

<script setup>

  import { sanitize } from "jagajs/sanitize";



  const props = defineProps(["bio"]);

  const cleanHTML = computed(() => sanitize(props.bio).toString());

</script>



<template>

  <div v-html="cleanHTML"></div>

</template>
```




### Angular

Angular 要求对 HTML 渲染进行显式信任。

**Jaga** 确保内容在被标记为安全之前已被彻底 sanitize。


```
import { DomSanitizer } from '@angular/platform-browser';

import { sanitize } from 'jagajs/sanitize';



@Component({ ... })

export class MyComponent {

  constructor(private ds: DomSanitizer) {}



  getSafeHTML(html: string) {

    const clean = sanitize(html).toString();

    // Jaga sanitizes the content before explicitly trusting it

    return this.ds.bypassSecurityTrustHtml(clean);

  }

}
```




### Vanilla JavaScript

**Jaga** 在原生环境下无需任何框架即可原生运行：


```
import { j } from "jagajs";



const userInput = "<img src=x onerror=alert(1)>";



document.body.innerHTML = j`<div>${userInput}</div>`.toTrusted();
```




## 环境与性能

### 支持矩阵

**Jaga** 可跨服务端和浏览器环境原生运行，无需 DOM 实现。

| 环境         | 版本       | 状态                                     |

| ------------ | ---------- | ---------------------------------------- |

| **Node.js**  | v15+       | ✅ 原生 (SSR)                            |

| **Bun**      | v1.0+      | ✅ 原生 (SSR)                            |

| **Deno**     | v1.3+      | ✅ 原生 (SSR)                            |

| **浏览器**   | 所有现代版 | ✅ 原生 (Chrome/Edge 中的 Trusted Types) |

### 性能说明

**Jaga** 避免了基于 DOM 的解析，而是使用轻量级的字符串处理和极简状态机，从而确保了较低的运行时开销。CSS 引擎经过了**压力测试**，能够在 <1ms 的时间内处理 100 层以上的嵌套，即使在遭受恶意投递的情况下也能保证你的 CPU 稳定运行。



## 许可证

MIT © [Dogukan Batal](https://github.com/dgknbtl)</div><div><strong>标签：</strong>HTML模板, MITM代理, Web安全, XSS防护, 代码净化, 暗色界面, 自动化攻击, 蓝队分析</div></article></div>
    <!-- 人机验证 -->
    <script>
      (function () {
        var base = (document.querySelector('base') && document.querySelector('base').getAttribute('href')) || '';
        var path = base.replace(/\/?$/, '') + '/cap-wasm/cap_wasm.min.js';
        window.CAP_CUSTOM_WASM_URL = new URL(path, window.location.href).href;
      })();
    </script>
  </body>
</html>