tanstack-start-security

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

TanStack Start Security

TanStack Start 安全指南

Purpose

目的

Harden TanStack Start applications without turning every change into a full security rewrite.

Use this skill when the job is specifically about security posture in a TanStack Start app:

auth and session protection
cookies, CSRF, trusted origins, and browser request safety
request middleware in
```
src/start.ts
```
server function and server route hardening
secret and env boundary protection
SSR, hydration, and client/server execution leaks
security headers, CSP, webhook verification, and rate limiting

Do not use this skill for generic React work or non-security copy edits.

If the task is mainly TanStack Start architecture compliance rather than security hardening, use

skills/tanstack-start-architecture/

instead of stretching this skill.

If the request is a generic non-TanStack security review, route away to the normal security-review path instead of forcing TanStack Start rules.

在不将每一处改动都变成全面安全重写的前提下，强化TanStack Start应用的安全性。

当工作内容专门针对TanStack Start应用的安全态势时使用本技能：

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

请勿将本技能用于通用React开发或非安全相关的文案编辑。

如果任务主要是TanStack Start架构合规性而非安全加固，请使用

skills/tanstack-start-architecture/

，而非强行使用本技能。

如果请求是通用的非TanStack安全审查，请转至常规安全审查流程，而非强制套用TanStack Start规则。

Trigger Examples

触发示例

Positive

适用场景

Review TanStack Start login and session handling security.

Prevent secrets from leaking through a TanStack Start server function.

Review auth, cookies, CSRF, and webhook security in this TanStack Start app.

审查TanStack Start登录与会话处理的安全性。

防止密钥通过TanStack Start服务器函数泄露。

审查此TanStack Start应用中的认证、Cookie、CSRF及Webhook安全。

Negative

不适用场景

Make a small style-only change to a plain React page.

Security review an Express API server that is not a TanStack Start app.

对普通React页面进行仅样式的小改动。

对非TanStack Start应用的Express API服务器进行安全审查。

Boundary

边界场景

```
Change only the copy on a TanStack Start page.
```
If there is no change to security boundaries, auth, env handling, server routes, or headers, this skill may be too heavy.

```
仅修改TanStack Start页面上的文案。
```
如果未涉及安全边界、认证、环境变量处理、服务器路由或请求头的改动，使用本技能可能过于冗余。

Step 1: Project Validation

步骤1：项目验证

Apply this skill only when the repository is actually using TanStack Start signals such as:

```
app.config.ts
```
```
@tanstack/react-start
```
in
```
package.json
```
```
@tanstack/react-router
```
in
```
package.json
```
```
src/routes/__root.tsx
```

If those signals are absent, stop and fall back to the normal implementation or security-review path.

仅当仓库实际使用TanStack Start的特征时应用本技能，例如：

```
app.config.ts
```
文件
```
package.json
```
中包含
```
@tanstack/react-start
```
```
package.json
```
中包含
```
@tanstack/react-router
```
```
src/routes/__root.tsx
```
文件

如果上述特征不存在，请停止并转至常规实现或安全审查流程。

Step 2: Read The Right Rules

步骤2：阅读对应规则

Read these files before editing security-sensitive code:

```
rules/auth-and-session.md
```
for authentication, authorization, cookies, and request-origin rules

rules/server-boundaries.md

for

createServerFn

createServerOnlyFn

, env/secrets, and import boundaries

```
rules/http-and-headers.md
```
for server routes, CSP, headers, CORS, rate limiting, and webhook handling
```
rules/validation.md
```
for review gates and verification steps

Read

references/official-security-notes.md

when auth stack details, TanStack execution rules, or Better Auth specifics matter.

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

```
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

。

Start Here By Prompt Type

根据请求类型选择起始文件

auth, session, cookie, CSRF,
```
beforeLoad
```
, and authorization issues: start with
```
rules/auth-and-session.md
```
secret leaks, env exposure,
```
loader
```
, SSR context, hydration leaks, and import-boundary issues: start with
```
rules/server-boundaries.md
```
```
src/start.ts
```
middleware, CSP, CORS, headers, webhooks, rate limiting, and server routes: start with
```
rules/http-and-headers.md
```
if the prompt is a copy-only edit or a non-TanStack security request, stop at the core boundary decision and route away instead of reading deeper files

认证、会话、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安全请求，请在核心边界判断阶段停止并转至对应流程，无需深入阅读更多文件

Step 3: Security Mapping

步骤3：安全面映射

Before changing code, map which security surface you are touching:

Auth/session
Secrets/env
Request middleware in
```
src/start.ts
```
Server functions
Server routes / HTTP endpoints
Browser-delivered headers and CSP
SSR / hydration / import boundary leaks

If more than one surface is affected, validate all linked rule files before editing.

在修改代码前，确定你将涉及的安全面：

认证/会话
密钥/环境变量
```
src/start.ts
```
中的请求中间件
服务器函数
服务器路由 / HTTP端点
浏览器交付的请求头与CSP
SSR / 水合作用 / 导入边界泄露

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

Step 4: Preferred Fix Order

步骤4：优先修复顺序

Use the lightest fix that closes the actual risk:

Stop secret or boundary leaks first
Add session/authz enforcement next
Tighten cookies, origins, and mutation safety
Add explicit headers, CSP, webhook checks, and rate limits
Only then consider larger auth-stack or route-structure migrations

使用最轻量化的修复方案来解决实际风险：

首先阻止密钥或边界泄露
其次添加会话/授权强制校验
收紧Cookie、源及变更操作的安全性
添加明确的请求头、CSP、Webhook校验及速率限制
仅在必要时考虑更大规模的认证栈或路由结构迁移

Step 5: Auto-Remediation Policy

步骤5：自动修复策略

Auto-fix directly when the change is local, reversible, and clearly safer:

move privileged logic behind
```
createServerFn
```
or
```
createServerOnlyFn
```
add route/session guard checks
replace client-exposed secret access with server-only access
add missing input validation or origin/signature checks
tighten cookie or header defaults when the current stack is clear

Do not auto-apply broad, risky migrations without explicit justification:

replacing the auth library
sweeping session model changes
site-wide CSP rewrites without checking asset/script requirements
broad CORS or cookie-domain changes across environments

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

将特权逻辑移至
```
createServerFn
```
或
```
createServerOnlyFn
```
之后
添加路由/会话守卫校验
将客户端可访问的密钥替换为仅服务器端访问
添加缺失的输入验证或源/签名校验
当当前栈清晰时，收紧Cookie或请求头的默认配置

未经明确论证，请勿自动应用宽泛、高风险的迁移：

替换认证库
全面修改会话模型
未检查资源/脚本需求的情况下进行全站CSP重写
跨环境进行宽泛的CORS或Cookie域改动

Core Security Gates

核心安全关卡

Block the change until fixed if any of these are true:

client-reachable code can import or derive a secret
protected data mutation trusts client-provided identity or role claims
a TanStack Start
```
loader
```
or shared utility performs privileged work without an explicit server boundary
a route relies on
```
beforeLoad
```
only, without equivalent server-side protection for protected actions
loader output, SSR context, or hydrated state serializes secrets or internal-only auth data
a server route is accepting browser state-changing input without auth/origin/CSRF strategy
webhook handlers trust payloads before signature verification
auth/session cookies are configured loosely without deliberate environment rules

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

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

Verification

验证

Before claiming completion:

verify the relevant rule-file checklist
run the project checks that prove the change did not break the app
summarize what was hardened and what remains stack-dependent

For detailed review and command guidance, use

rules/validation.md

在确认完成前：

验证相关规则文件中的检查清单
运行项目检查，确保改动未破坏应用
总结已加固的内容及仍依赖于栈的部分

如需详细审查及命令指导，请使用

rules/validation.md

。