# 安全边界与接口使用

## 报告安全问题

请勿在公开 Issue/PR 中提交漏洞利用细节、Cookie、API Key、Token、账号凭据或个人信息。本项目没有专门安全邮箱，不提供虚构联系方式。

2026-10-07 已确认开启仓库的 private vulnerability reporting。请登录 GitHub，在 [Security 页](https://github.com/zanedonkey/dsh-tool-12306/security) 选择 **Report a vulnerability**，通过该入口提交私密报告。若入口暂时不可用，请只在 Issue 中请求建立私密联系渠道，不提交漏洞细节或附件，等待维护者提供渠道。

报告应包含受影响版本、影响范围、最小脱敏复现及建议修复。敏感问题包括：凭据/行程泄露、非官方地址请求或不安全重定向、执行远端车站脚本、资源限制绕过、依赖漏洞及宿主交互中的隐私问题。普通车次数据错误请使用 Bug Report。

仅维护最新公开发布版本，以 [GitHub Releases](https://github.com/zanedonkey/dsh-tool-12306/releases/latest) 和 npm 的 `latest` 为准。旧版修复通常通过升级提供，不承诺固定响应时间或完整安全保证。

## 凭据泄露与依赖漏洞

发现 API Key、npm/GitHub token 或 Cookie 泄露时，先撤销/轮换对应凭据；对登录 Cookie 撤销相关登录会话。立即停止继续传播，清理日志、fixture、包和会话记录。若进入 Git 提交，仅删除当前文件或添加 .gitignore 无法清理历史；应评估历史重写及 fork、clone、已发布文件中的副本。历史重写需要维护者批准，撤销凭据不能等历史清理完成后才做。

项目不需要 12306 登录凭据；读取浏览器 Cookie、账号 Session 导入和验证码绕过均不属于支持范围。请勿为了复现问题提供真实账号数据。

维护依赖时使用 npm audit，并区分运行依赖和开发依赖；查看安全公告后选择最小修复版本，重跑两套受支持 SDK 的离线检查，不使用 npm audit fix --force 批量升级。npm audit 无告警也不等于不存在漏洞。

## 插件执行与网络边界

本插件在 Harness 宿主进程中执行匿名查询，不是独立沙箱。本插件向模型注册三个查询工具和一个不联网的版本诊断工具；源码中没有账号登录、购票、支付、浏览器 Cookie 导入、第三方代理或遥测上传功能。

HTTP 仅访问 `https://www.12306.cn`、`https://kyfw.12306.cn` 和 `https://search.12306.cn`；禁止携带 URL 用户名/密码，禁止重定向，保留 Node 默认 TLS 校验。车站 JS 只作为文本解析，不执行远端代码。动态查询路径严格限定为已知查询路径格式。

## 请求与资源限制

0.1.6 起一次查询默认最多 60 秒，覆盖初始化、排队、限速、重试、分页与响应体读取。超时取消该调用的剩余工作并返回错误；仍有其他订阅时不取消共享 HTTP 请求。精简模式只改变模型文本，保留完整结构化结果与未知值。诊断不显示 Cookie、凭据或本地路径。

- 默认请求启动间隔 1000ms，同一 Client 串行发送，网络/5xx 最多重试一次；中转默认每个首程乘车日期最多三页。
- 跨午夜出发窗口最多查询乘车日和次日两天，中转默认合计最多六页，保持串行限速；普通窗口只查一天。只指定到达窗口不会额外查询另一个首程日期。
- HTTP 429 不重试，默认进入至少 60 秒的跨调用冷却。支持 Retry-After 秒数/HTTP 日期；异常超长提示最多按一天处理。冷却期间新请求及已排队请求直接失败，冷却结束不自动恢复查询。
- 相同完整 URL 的在途请求共享一次 HTTP。所有订阅者收到响应后移除记录，后续查询重新访问官网；不保存完成后的余票结果。
- 每个订阅者可独立取消，全部订阅者取消或插件卸载时终止底层请求。取消的排队请求不会让后续请求越过仍在执行的请求。
- 默认最多保留 32 个不同在途请求；相同 URL 可共享已有请求。超过限制时明确报错。
- 每个响应默认最多读取 4 MiB。既检查 Content-Length，又累计实际流字节数，因此没有长度或长度不实的响应也受限。超限立即取消读取且不重试；超时覆盖响应体读取阶段。
- 匿名 Cookie 仅保存在内存，最多 128 条，每条不超过 4096 字符；仅接受查询域或其父域声明，按路径匹配和有效期发送，卸载时清空。不实现供浏览器使用的完整 Cookie 协议。

中转每条路线最多枚举 12×12 个有票席别对，默认返回五个组合，可设为 1–20；不发送额外补价请求。缺失或冲突票价保留 `null`，最低已知价格不保证全局最低。

限速、队列和冷却都属于同一 Client/插件实例。多个实例、多个进程或多人共用同一出口 IP 时不会自动汇总限制；代码加固不能保证官方接受请求。

## 数据流与隐私

官网收到日期、起终点/中转站或车次、出口 IP、请求头和匿名查询 Cookie。当前源码不持久化查询参数或 Cookie，也不把这些内容发送给插件作者。

宿主 Harness 可能保存会话和工具记录；使用云端模型时，提示词和工具结果可能发送给模型提供方。这些行为由宿主和提供方管理，不能因插件匿名查询就认为行程完全匿名。请勿在聊天中填写账号密码、身份证或支付信息。

## 官方条款与公开分发

核对日期：2026-10-06。插件使用官网查询端点，未取得或提供 12306 的第三方接口授权。能访问官网接口并不等于获得公开 API 的使用授权。

[12306 服务条款](https://kyfw.12306.cn/otn/regist/rule) 第 6（3）项限制未经认可的机器人、爬虫等访问方式以及不合理重大负荷；第 12 项涉及网站内容及资源的使用。[12306 隐私政策](https://kyfw.12306.cn/otn/gonggao/privacyPolicy_web.html) 说明其信息处理规则。公开分发、再分发数据或商业运营前应确认适用条款及所需授权。MIT 许可覆盖本项目代码，不授予 12306 接口或数据的使用权限。

## 验证范围

新增测试覆盖冷却和排队请求、Retry-After、流大小、读取超时、请求合并、取消隔离、队列容量、Cookie 路径/过期/域限制。仍需持续维护依赖和宿主兼容性；这些测试不等于完整渗透测试、供应链审计或法律合规证明。