# 安全策略

本页说明如何报告 K2F 参考引擎、SDK 和官方工具中的漏洞。规范性格式规则（完整性代码、横幅、禁令）见[格式规范](docs/spec/k2f-v0.3.md)；面向用户的横幅行为概述见[完整性](/integrity)和[验证](/verify)。

## 报告漏洞

请通过 [GitHub Security Advisories](https://github.com/suzheng/k2f/security/advisories/new) 报告安全问题。**请勿**为未披露的漏洞提交公开的 GitHub issue、讨论或 pull request。

请包含清晰的描述、复现步骤以及你所看到的影响（机密性、完整性、可用性，或如相关，[k2f.dev](https://k2f.dev) 上的跨用户风险）。我们的目标是在**五个工作日内**确认收到报告。

## 范围

**范围内**

- Rust 引擎与布局编译器（`engine/`，包括站点和 SDK 使用的 WASM 构建）
- JavaScript / TypeScript SDK（`@openk2f/k2f`，位于 `sdk/js` 的 npm 包）
- MCP stdio 服务器（`engine/k2f_mcp`）
- 桌面阅读器（`desktop/`）
- k2f.dev 上的官方 Web 界面（playground 上传、发布链接、验证页面）

**范围外**

- 已在受支持的发布线中修复的第三方依赖漏洞 —— 请直接向对应项目报告
- 不受支持版本中的问题（见下文）
- 一般产品反馈或格式讨论 —— 请改用公开 issue

## 支持的版本

安全修复针对当前 **0.3.x** SDK 及匹配的引擎发布。格式规范 **v0.3** 是磁盘上的契约（[兼容性策略](COMPATIBILITY.md)）。

| 发布线 | 是否支持安全修复 |
|--------------|------------------------------|
| **0.3.x**    | 是                          |
| 0.2.x 及更早版本 | 否                        |

## `.K2F` 包的安全属性

K2F 将编译后的包视为**可信数据**，而非程序。各实现应保持以下属性：

### 无可执行内容

`.K2F` 归档不得携带 JavaScript、WASM、宏或其他可执行载荷。查看器和 SDK **不得**执行或沙箱运行来自包内容的代码。

### 查看器仅渲染 lock

渲染使用已发布的 `document.K2F.lock`（以及嵌入的字体/资源）。语义编辑需要通过引擎重新编译；查看器不得仅凭 `content/` 静默重新布局。

### 完整性横幅

每次打开都必须呈现完整性状态。代码 `BROKEN_INTEGRITY` 和 `SIGNED_BUT_BROKEN` **绝不能**被呈现为已签名或可信。

哈希校验覆盖语义内容（`content_hash`）与外观绑定（`appearance_hash`，包括 lock 中记录的 `engine_version` 和 `engine_commit_sha`）。当哈希链与 lock 匹配，但读取器由不同的 commit 构建时，校验会报告 `ENGINE_MISMATCH` —— 这属于**来源（provenance）**问题，而非篡改。不要将 `ENGINE_MISMATCH` 映射为 `BROKEN_INTEGRITY` 或 `SIGNED_BUT_BROKEN`。参见[兼容性](COMPATIBILITY.md)。

完整的代码列表与横幅 UI 层级：[完整性](/integrity) 以及规范中的 [完整性校验](docs/spec/k2f-v0.3.md#integrity-verification)。

### 签名

加密签名是由人或组织刻意执行的一步。AI agent 与自动化流水线默认生成 **`UNSIGNED`** 包。**`SIGNED`** 横幅需要有效的哈希链**以及**对规范化 lock JSON（`signatures/v1.json`）的已验证 Ed25519 签名。密钥处理：[密钥参考](docs/reference/keys.md)。

### 导出不是源文件

PDF、PPTX、DOCX 和 IDML 导出是已发布 lock 的单向绘制产物。它们无法作为 K2F 源文件被打开、编辑或重新导入（`PDF_IS_NOT_A_SOURCE` 及同类代码）。请将导出视为只读渲染结果，而非权威的文档状态。

### 其他格式禁令

规范还禁止在语义节点上使用内联 CSS、在 State A 中使用任意矢量路径，以及依赖系统字体（仅允许嵌入字体；缺失字形时按失败关闭处理）。详情：[禁令](docs/spec/k2f-v0.3.md#prohibitions)。

## 相关链接

- [完整性](/integrity) —— 横幅规则与校验哈希代码
- [验证](/verify) —— 浏览器内包检查
- [兼容性](COMPATIBILITY.md) —— 引擎版本匹配
- [格式规范](docs/spec/k2f-v0.3.md) —— 规范性的完整性与签名契约
- [贡献指南](CONTRIBUTING.md) —— 代码贡献（不适用于未披露的安全问题）