tanstack-start-security

@rules/auth-and-session.md @rules/server-boundaries.md @rules/http-and-headers.md @rules/validation.md @references/official-security-notes.md

TanStack Start 安全

<output_language>

默认将所有面向用户的交付内容、保存的产物、报告、计划、生成的文档、摘要、交接备注、提交/消息草稿和验证备注设为韩语，即使此规范技能文件是用英语编写的。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、软件包名称、专有名称和引用的源文本片段，使用其规定的语言或原始语言。

只有在用户明确提出要求、现有目标产物必须为保持一致性而继续使用其他语言，或机器可读契约要求使用精确的英文词项时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），请优先将其用于面向用户的产物。

</output_language>

用途

在不把每次更改都变成全面安全重写的前提下，强化 TanStack Start 应用的安全性。

当任务明确涉及 TanStack Start 应用的安全态势时，使用此技能：

• 身份验证和会话保护
• Cookie、CSRF、可信来源和浏览器请求安全
• src/start.ts 中的请求中间件
• 服务端函数和服务端路由加固
• 密钥和环境变量边界保护
• SSR、水合以及客户端／服务端执行泄露
• 安全标头、CSP、Webhook 验证和速率限制

不要将此技能用于通用 React 工作或与安全无关的文案修改。

此技能的输出形式是一组安全决策：映射出的安全范围、负责约束该范围的规则文件、能够消除风险的最小更改，以及证明风险已消除的验证结果。如果交付内容是架构计划，而不是已消除的安全风险（例如文件夹布局、路由约定、数据加载模型、缓存行为），就不符合这种输出形式；不要勉强用此技能覆盖这些内容：仅加固并报告实际在范围内的安全事项，并将其余架构事项列为不属于此技能的输出范围。

如果请求是通用的、与 TanStack 无关的安全审查，应转到常规安全审查流程，而不是强行套用 TanStack Start 规则。

<instruction_contract>

字段	约定
意图	降低 TanStack Start 应用中的实际安全风险，同时避免将每次更改都变成全面安全重写。
范围	TanStack Start 项目中的身份验证和会话、Cookie／CSRF／可信来源、密钥和环境变量暴露、请求中间件、服务端函数、服务端路由、标头／CSP／CORS、Webhook、速率限制，以及 SSR／水合／导入边界泄露。
权威性	用户和项目指令优先于此技能。当前官方 TanStack Start 和身份验证库文档在与此技能说明冲突时优先适用。无论其他偏好如何，核心安全门槛都必须满足。
证据	仓库信号（app.config.ts、@tanstack/react-start、@tanstack/react-router、src/routes/__root.tsx）、所修改的源文件路径、负责约束这些路径的规则文件，以及项目检查结果。
工具	本地搜索、读取和编辑命令，以及项目自身的 lint、类型检查、测试和构建命令。网络访问、使用凭据以及可能影响生产环境或造成破坏的命令都需要用户明确批准。
循环	不设循环：对受影响的范围进行一次映射和修复，然后依据规则文件清单检查；只有触及新范围或检查失败时才重复。
输出	韩语安全报告或变更集：映射出的安全范围、每项修复所依据的规则文件、修改的文件、带结果的验证命令，以及依赖技术栈的剩余风险。
验证	对每个修改的范围运行 rules/validation.md 中的检查门槛，以及项目自身的检查，然后记录准确的命令及其结果。
停止条件	每个映射出的范围都已加固或明确延期，相关规则文件中的检查门槛均已通过，验证结果已记录，并且已指出依赖技术栈的剩余风险。

</instruction_contract>

触发示例

正向示例：

• 审查 TanStack Start 登录和会话处理的安全性。
• 防止密钥通过 TanStack Start 服务端函数泄露。
• 审查此 TanStack Start 应用中的身份验证、Cookie、CSRF 和 Webhook 安全性。

反向示例：

• 仅对普通 React 页面进行小幅样式修改。
• 对一个并非 TanStack Start 应用的 Express API 服务器进行安全审查。

边界示例：

• 只修改 TanStack Start 页面上的文案。 如果不涉及安全边界、身份验证、环境变量处理、服务端路由或标头的更改，此技能可能过于繁重。

第 1 步：项目验证

仅当仓库确实使用 TanStack Start 的标志时，才应用此技能，例如：

• app.config.ts
• package.json 中的 @tanstack/react-start
• package.json 中的 @tanstack/react-router
• src/routes/__root.tsx

如果缺少这些标志，请停止，并改用常规实现或安全审查流程。

第 2 步：阅读正确的规则

编辑安全敏感代码前，请阅读以下文件：

• rules/auth-and-session.md：了解身份验证、授权、Cookie 和请求来源规则
• rules/server-boundaries.md：了解 createServerFn、createServerOnlyFn、环境变量/密钥和导入边界
• rules/http-and-headers.md：了解服务端路由、CSP、标头、CORS、速率限制和 Webhook 处理
• rules/validation.md：了解审查关卡和验证步骤

当身份验证技术栈详情、TanStack 执行规则或 Better Auth 具体事项很重要时，请阅读 references/official-security-notes.md。

根据提示类型从这里开始

• 身份验证、会话、Cookie、CSRF、beforeLoad 和授权问题：从 rules/auth-and-session.md 开始
• 密钥泄露、环境变量暴露、loader、SSR 上下文、水合泄露和导入边界问题：从 rules/server-boundaries.md 开始
• src/start.ts 中间件、CSP、CORS、标头、Webhook、速率限制和服务端路由：从 rules/http-and-headers.md 开始
• 如果提示是仅修改副本或与 TanStack 无关的安全请求，请在核心边界判断处停止，并转交处理，不要继续深入阅读其他文件

第 3 步：安全映射

修改代码前，请梳理你涉及的安全面：

1. 身份验证/会话
2. 密钥/环境变量
3. src/start.ts 中的请求中间件
4. 服务端函数
5. 服务端路由/HTTP 端点
6. 浏览器端提供的标头和 CSP
7. SSR/水合/导入边界泄露

如果涉及多个安全面，请在修改前验证所有相关规则文件。

第 4 步：优先修复顺序

采用能消除实际风险的最轻量修复：

1. 首先阻止密钥或边界泄露
2. 接着添加会话/授权强制检查
3. 收紧 Cookie、来源和变更安全措施
4. 添加明确的标头、CSP、Webhook 检查和速率限制
5. 最后才考虑更大范围的身份验证技术栈或路由结构迁移

第 5 步：自动修复策略

当更改范围局部、可逆且明显更安全时，直接自动修复：

• 将特权逻辑移至 createServerFn 或 createServerOnlyFn 后
• 添加路由/会话保护检查
• 将客户端可访问的密钥访问方式替换为仅服务端访问
• 添加缺失的输入验证或来源/签名检查
• 当前技术栈明确时，收紧 Cookie 或标头的默认设置

没有明确理由时，不要自动应用范围广、风险高的迁移：

• 替换身份验证库
• 大范围更改会话模型
• 未检查资源/脚本要求就重写全站 CSP
• 跨环境大范围更改 CORS 或 Cookie 域

核心安全关卡

如果存在以下任一情况，请先阻止更改，直至问题修复：

• 客户端可访问的代码能够导入或推导出密钥
• 受保护的数据变更信任客户端提供的身份或角色声明
• TanStack Start 的 loader 或共享工具在没有明确服务端边界的情况下执行特权操作
• 路由仅依赖 beforeLoad，而受保护操作没有等效的服务端保护
• loader 输出、SSR 上下文或水合状态序列化了密钥或仅供内部使用的身份验证数据
• 服务端路由接受来自浏览器的状态变更输入，却没有身份验证/来源/CSRF 策略
• Webhook 处理程序在验证签名前就信任负载
• 身份验证/会话 Cookie 的配置过于宽松，且没有明确的环境规则

<validation_checklist>

验证

在声称已完成之前：

• 核对相关规则文件中的检查清单
• 运行项目检查，确认更改没有导致应用出错
• 总结已加固的内容以及仍取决于技术栈的部分

如需详细的审核和命令指南，请使用 rules/validation.md。

</validation_checklist>