# HTTP 策略与宿主边界

配置响应头、CSP、origin 和发布策略，并区分它们与运行时权限。

版本、变更与要求见 [Framework 3.2 与 CLI 1.0](/zh-cn/docs/guides/releases/)。


<span id="dos-controles-con-responsabilidades-distintas"></span>

<span class="section-anchor" id="section-1"></span>

## 职责不同的两种控制

`wu.config.json` 中的 `security` 定义 WU 提供并在构建时导出给其他宿主的 HTTP 策略。每个应用的 `grants` 属于宿主授予运行时的权限。CSP 响应头不能替代能力契约，grant 本身也不能让浏览器加载被 CSP 阻止的 origin。

<span id="configuración"></span>

<span class="section-anchor" id="section-2"></span>

## 配置

```json
{
  "security": {
    "enabled": true,
    "csp": "",
    "frame_options": "DENY",
    "referrer_policy": "strict-origin-when-cross-origin",
    "nosniff": true,
    "app_origins": ["https://apps.example.com"],
    "connect_origins": ["https://api.example.com"],
    "wasm": false
  }
}
```

示例中的域名是占位符。策略应描述应用实际使用的 origin。

| 字段 | 作用 |
| --- | --- |
| `enabled` | 启用或禁用整组响应头 |
| `csp` | 自动生成、字面量策略、`report-only` 或 `off` |
| `frame_options` | `X-Frame-Options`；默认 `DENY` |
| `referrer_policy` | 引用来源策略 |
| `permissions_policy` | 通过 Permissions-Policy 管理浏览器能力 |
| `hsts` | Strict-Transport-Security；通过 TLS 提供内容时适用 |
| `nosniff` | `X-Content-Type-Options: nosniff` |
| `corsOrigin` 或 `cors` | CORS origin；`cors` 也支持包含 `origin` 的对象 |
| `app_origins` | bundle 的 origin：脚本和连接 |
| `connect_origins` | API 的 origin：连接 |
| `wasm` | 在生成的 CSP 中允许 WASM 编译 |

解析器还支持多个字段的 camelCase 写法，例如 `appOrigins`、`connectOrigins`、`frameOptions` 和 `wasmUnsafeEval`。CORS 有一个重要例外：`cors_origin` 是结构内部名称，但 JSON 只接受 `corsOrigin` 或 `cors`，不接受该 snake_case 写法。

<span id="convenciones-de-valores"></span>

<span class="section-anchor" id="section-3"></span>

## 值的约定

文本响应头字段中，空字符串交由 WU 决定，`off` 则不输出该响应头。`csp: "report-only"` 在报告响应头中生成等效策略，浏览器仅报告违规，不据此阻止。字面量 CSP 字符串会原样使用。

生成过程分析最终文档的内联脚本并计算哈希，因此必须在插入目录或 import map 之后执行。`onclick` 之类的 HTML 处理属性与具有哈希的脚本处理方式不同，诊断会指出不兼容项。把事件放在模块、样式放在样式表中，可以避免依赖 HTML 例外。

在 1.2.0 中，CSP 哈希按页面计算并规范化 CRLF 换行。`security.upgradeInsecureRequests` 控制是否升级到 HTTPS。构建保留 shell 的 `_headers`，对哈希文件应用不可变缓存，并验证字段以防止响应头注入。使用 `wu doctor --url` 检查托管服务实际发送的策略。

<span class="section-anchor" id="section-4"></span>

## CORS

默认不输出 `Access-Control-Allow-Origin`。同源提供微应用无需启用 `*`。拓扑要求不同 origin 时，请配置具体值，并同时检查 CSP、凭据和目标策略。

代理规则的 `cors` 选项只属于该规则，不等同于控制生产服务器响应的 `security.corsOrigin`。

<span id="archivos-publicables"></span>

<span class="section-anchor" id="section-5"></span>

## 可发布文件

路径安全检查先解码转义，再检查各路径段，并拒绝目录穿越、控制字符、反斜杠和绝对路径。文件过滤器阻止点文件和被视为敏感的扩展名或名称。`.well-known` 是有意保留的例外，因为它包含公开协议文档。

构建和 `doctor` 会检查可发布区域，但凭据仍应存放在后端或其环境中。应用需要私有 token 时，不应将其加入源码或 `public/`，即使具体文件名没有出现在阻止列表中。

开发服务器对 Host、CORS、HMR 和文件访问应用独立策略，涵盖 sourcemap、模块和带查询参数的导入。使用 `dev.allowedHosts` 配置隧道；只有 `.env` 中的 `VITE_*` 和 `WU_*` 会进入浏览器。迁移这些行为请参阅[开发](/zh-cn/docs/cli/development/)。

<span class="section-anchor" id="section-6"></span>

## Sentinel

sentinel 实例在 `wu dev` 中禁用，在 `wu serve` 中按默认值创建。源码包含请求分类和 ACP 协议路由发布功能。这些模块的存在不证明具备全面的自动化防护，也不能替代产品访问控制。

CLI `1.2.0` 允许每个应用使用 `manifest: "define"`，并通过 `security.frameOrigins` 配置远程 iframe。frame 源只进入 `frame-src`，不会允许宿主脚本或连接。目录导航过滤不会阻止 fetch 读取。见 [远程应用](/zh-cn/docs/framework/remote-apps/) 与 [构建](/zh-cn/docs/cli/build/)。

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-7"></span>

## 实现参考

- `wu-cli/src/config/config.zig`
- `wu-cli/src/runtime/security.zig`
- `wu-cli/src/runtime/project_fs.zig`
- `wu-cli/src/runtime/allowed_hosts.zig`
- `wu-cli/src/runtime/dev/env.zig`
- `wu-cli/tests/dev-security.test.cjs`
- `wu-cli/tests/doctor-policy.test.cjs`