Remix 认证、会话与安全体系实战指南从签名 Cookie 到路由保护与跨源防护【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix在 RemixThe fully-stacked web framework中一个签名 Cookie、一个 session、一个已认证的 identity 是三个不同层次的概念。本篇指南按照“先建底层、再加上层”的顺序完整讲解 Remix 如何管理每浏览器的状态remix/cookie、remix/session、如何在登录流程中写入可信的身份记录remix/auth、如何在每个请求上解析身份并保护路由remix/middleware/auth以及如何在会改变状态的路由外围叠加 CSRF 同步器令牌csrf()与无令牌跨源防护cop()。读完本篇你可以直接在当前仓库的包实现与demos/示例上复刻一套从 Cookie 到 OAuth 登录、再到路由守卫与浏览器来源校验的完整安全栈。三层模型Cookie、Session 与身份Remix 的安全体系建议按以下顺序构建签名 Cookieremix/cookie提供的类型安全 Cookie 解析/序列化支持 HMAC-SHA256 签名与密钥轮换Sessionremix/session提供的服务端管理生命周期flash 值、ID 轮换、防篡改存储通过remix/middleware/session挂到请求上下文上认证身份remix/auth负责登录协议凭据校验、OAuth/OIDC 跳转与回调把“app-owned”的认证记录写入 session之后每个请求再由remix/middleware/auth的auth()把 session 记录解析回context.auth最后用requireAuth()保护路由。在这三层之上才叠加授权检查authorization、CSRF 同步器令牌、跨源防护COP等针对浏览器请求边界防御的中间件。这个顺序的意义在于后一层依赖前一层的安全属性——session 依赖签名 Cookie 防篡改身份解析依赖 session 里可信任的认证记录。纯 Cookie 与 Session 的选型用remix/cookie处理浏览器可控的偏好或一个小的签名值例如主题偏好、记住的 token 标记用remix/session处理需要服务端管理生命周期的状态flash 值、ID 轮换、防篡改存储——典型如登录态和购物车。remix/cookie基于 Web Crypto API 构建运行时无依赖Node.js、Bun、Deno、Cloudflare Workers 均可。核心 API 在 cookie 包 README 中import { createCookie } from remix/cookie let sessionCookie createCookie(session, { httpOnly: true, secrets: [s3cret1], secure: true, }) // 从请求的 Cookie header 解析该 cookie 的值 let value await sessionCookie.parse(request.headers.get(Cookie)) // 通过响应 Set-Cookie header 写回 let response new Response(Hello, world!, { headers: { Set-Cookie: await sessionCookie.serialize(value) }, })Cookie 配置与密钥轮换属性要有意识地设置httpOnly、sameSite、secure、path与过期时间应当刻意配置而不是依赖默认值。Remix 的 session cookie 典型配置见 auth 包 README 与 session-middleware 包 READMElet sessionCookie createCookie(__session, { secrets: [env.SESSION_SECRET], httpOnly: true, // 禁止 JS 读取防御 XSS 窃取 secure: true, // 仅 HTTPS 传输 sameSite: lax, // 降低 CSRF 面 path: /, })注意两条硬性约定session-middleware 文档明确说明session cookie 必须签名防止客户端篡改 session 数据且 session cookie 默认是 HTTP-only 的。签名实现HMAC-SHA256签名防止篡改但不隐藏 cookie 内容——值本身仍是可读取的默认经 percent-encoding base64 包装。从源码看cookie-signing.ts 中sign()用crypto.subtle以 HMAC/SHA-256 对值签名输出value.hash格式unsign()按最后一个.拆分值与哈希并验证任何 base64 非法字符都会被当作无效签名处理export async function sign(value: string, secret: string): Promisestring { let data encoder.encode(value) let key await createKey(secret, [sign]) let signature await crypto.subtle.sign(HMAC, key, data) let hash btoa(String.fromCharCode(...new Uint8Array(signature))).replace(/$/, ) return value . hash }密钥轮换新密钥放最前生产环境要求密钥来自环境配置而非测试常量。轮换时把新的签名密钥放在数组最前面旧 cookie 仍然可以被解析// 最初 let sessionCookie createCookie(session, { secrets: [secret1] }) // 轮换后新密钥在头部新序列化的 cookie 用 secret2 签名 let rotated createCookie(session, { secrets: [secret2, secret1] }) // 两种密钥签发的 cookie 都能 parse let value await rotated.parse(request.headers.get(Cookie))此外还可以自定义encode/decode作为完整的 cookie 值编解码器自定义编码会跳过默认 base64 包装直接签名后序列化适合希望在开发者工具中看到人类可读值的场景但必须自行保证输出只包含合法的 cookie 值字符。Session 中间件与存储策略session 中间件读进上下文、写回响应session(cookie, storage)会把签名 cookie 对应的 session 读入请求上下文context.session或context.get(Session)并在请求结束时把变更持久化到存储、把新值序列化进Set-Cookie响应头。基础用法见 session-middleware READMEimport { createRouter } from remix/router import { createCookie } from remix/cookie import { createCookieSessionStorage } from remix/session-storage/cookie import { session } from remix/middleware/session let sessionCookie createCookie(__session, { secrets: [s3cr3t], // session cookies must be signed! secure: true, sameSite: lax, }) let sessionStorage createCookieSessionStorage() let router createRouter({ middleware: [session(sessionCookie, sessionStorage)] }) router.get(/, (context) { context.session.set(count, Number(context.session.get(count) ?? 0) 1) return new Response(Count: ${context.session.get(count)}) })五种存储策略的对比维度仓库提供了多种存储后端选择时按数据量上限、持久性、运行时环境、多进程是否共享状态四个维度权衡存储创建函数适用场景关键限制CookiecreateCookieSessionStorage()remix/session-storage/cookie生产可用、无额外依赖全部数据塞进 cookie受浏览器上限通常 4096 字节约束文件系统createFsSessionStorage(/tmp/sessions)remix/session-storage/fs生产、需要持久文件系统能承载大 session 数据需要可写文件系统内存createMemorySessionStorage()测试与开发进程重启即丢失Redisremix/session-storage/redis多应用进程需要共享 session依赖 Redis 服务Memcacheremix/session-storage/memcache多进程共享、可过期依赖 Memcache 服务实现入口分别位于 cookie.ts、fs.ts、memory.tsRedis/Memcache 则独立成包 session-storage-redis 与 session-storage-memcache。判断标准如果多个应用进程集群部署必须看到同一份 sessionCookie 存储与内存/文件系统存储都不满足要求应选 Redis 或 Memcache。Session 值、Flash、ID 轮换与销毁Session类session.ts是这部分的实现核心类型参数分别约束 value 与 flash 两个命名空间get(key)优先读 value 表回落到 flash 表set(key, value)写入 value 表传null会删除该键unset(key)删除 value 表中的键flash(key, value)只写入nextMap——当前请求内get读不到下一个请求可见再下一个请求消失regenerateId(deleteOldSession?)生成新的 session IDcrypto.randomUUID()保留数据destroy()标记销毁之后任何修改都会抛出Session has been destroyed。Flash 的三段式行为在 session 包 README 的示例中被验证session.flash(message, success!) // 设置当次请求 get(message) 为 undefined // 该响应通常是重定向到展示页的路由 // 下一个请求 get(message) success! // 再下一个请求又恢复 undefinedID 轮换防会话固定登录等权限变化之后应调用regenerateId()在响应中签发新的 session ID。源码上session.tsregenerateId(true)会把deleteId记为原始session ID保存时删除旧数据传false默认则保留旧数据——README 提示后者适用于弱网移动端可能凭旧 ID 恢复会话的场景。登出销毁而不是删一个字段用户登出时应调用session.destroy()下次保存时清空存储中的全部数据并在下一个响应中清掉客户端的 session ID使下一个请求从全新 session 开始。不要只unset(userId)——残留的其他字段仍可能被复用这是会话固定攻击的常见入口。凭据登录与登出provider 管校验路由管跳转remix/auth暴露五个原语verifyCredentials()、startExternalAuth()、finishExternalAuth()、refreshExternalAuth()、completeAuth()。分工原则是路由拥有重定向与面向用户的失败反馈provider 拥有协议校验。createCredentialsAuthProvider()接受两个钩子parse(context)从请求上下文取出凭据verify(credentials)返回用户或null。Remix 的 auth 包 README 给出了完整流程let passwordProvider createCredentialsAuthProvider({ parse(context) { let formData context.get(FormData) if (formData null) { throw new Error(Expected formData() middleware before verifyCredentials()) } return { email: String(formData.get(email) ?? ), password: String(formData.get(password) ?? ), } }, async verify({ email, password }) { return users.verifyPassword(email, password) }, }) router.post(routes.auth.session.login.action, async (context) { let user await verifyCredentials(passwordProvider, context) if (user null) { return redirect(routes.auth.session.login.index.href()) } let session completeAuth(context) // 轮换 session id session.set(auth, { userId: user.id }) // 写入 app-owned 认证记录 return redirect(routes.app.dashboard.href()) }) router.post(routes.auth.session.logout, ({ get }) { let session get(Session) session.unset(auth) session.regenerateId(true) // 登出时销毁/轮换而非只删一个字段 return redirect(routes.auth.session.login.index.href()) })关键点completeAuth()在写认证记录之前轮换当前 session id实现见 complete-auth.ts这正是前面regenerateId安全要求在登录成功时刻的落地。仓库中的 social-auth 演示 展示了更贴近实战的parse实现先用remix/data-schema的表单 schema 解析并规范化 email再查库、比对密码哈希const loginSchema f.object({ email: f.field(s.defaulted(s.string(), )), password: f.field(s.defaulted(s.string(), )), }) export const passwordProvider createCredentialsAuthProvider({ parse(context) { let formData context.get(FormData) let { email, password } s.parse(loginSchema, formData) return { email: normalizeEmail(email), password } }, async verify({ email, password }, context) { let db context.get(databaseContext) let user await db.findOne(users, { where: { email } }) if (user null) return null if (typeof user.password_hash string user.password_hash ! ) { return (await verifyPassword(password, user.password_hash)) ? user : null } return null }, })OAuth 与 OIDC 登录外部登录的标准七步来自 auth 包 README在模块作用域创建 provider启动时校验配置、回调 URL 稳定登录路由调用startExternalAuth(provider, context, options?)——它把进行中的 OAuth 事务存入 session 并返回跳转响应回调路由调用finishExternalAuth(provider, context)——校验回调、清除存储的事务返回{ result, returnTo? }provider token 位于result.tokens持久化你希望复用的 provider token调用completeAuth(context)并把认证记录写进返回的 session后续请求中读取存储的 token 包需要时再用refreshExternalAuth()刷新并回存返回你自己的重定向。Google 登录的完整路由示例let googleProvider createGoogleAuthProvider({ clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET, redirectUri: new URL(routes.auth.google.callback.href(), env.APP_ORIGIN), authorizationParams: { access_type: offline, prompt: consent }, }) router.get(routes.auth.google.login, (context) startExternalAuth(googleProvider, context, { returnTo: context.url.searchParams.get(returnTo), }), ) router.get(routes.auth.google.callback, async (context) { let { result, returnTo } await finishExternalAuth(googleProvider, context) let user await users.upsertFromGoogle(result.profile) await persistProviderTokens(user.id, result.tokens) let session completeAuth(context) session.set(auth, { userId: user.id }) return redirect(returnTo ?? routes.app.dashboard.href()) })内置 provider 与关键约定内置 provider 覆盖两类运行时Google、Microsoft、Okta、Auth0 使用共享的OIDC 运行时GitHub、Facebook、X 使用内置的自定义 OAuth 流程实现位于 providers 目录。要点OIDC provider 默认在/.well-known/openid-configuration做 discovery想跳过 discovery 可传metadatametadata 在别处则传discoveryUrl默认 OIDC scope 为openid profile email非 OIDC 的默认 scopeGitHubread:user user:email、Facebookpublic_profile email、Xtweet.read users.readrefreshExternalAuth()支持内置 OIDC provider 与 X前提是存储的 token 包含 refresh token而 provider 只在配置了离线访问时才返回 refresh token如 Google 的authorizationParams: { access_type: offline }、X 的offline.accessscopecreateMicrosoftAuthProvider()增加tenant选项并据此构造 issuercreateOktaAuthProvider()需要完整 issuer URL如https://example.okta.com/oauth2/defaultcreateAuth0AuthProvider()接受 domain 并自行推导 issuer。自定义 OIDC 与自定义 OAuth自定义 SSO 直接用createOIDCAuthProvider()通过mapProfile({ claims })把 claims 映射为应用内部类型let companyProvider createOIDCAuthProvider({ name: company, issuer: https://sso.acme.com, clientId: acme-web, clientSecret: acme-web-secret, redirectUri: new URL(/auth/company/callback, https://app.acme.com), mapProfile({ claims }) { return { id: claims.sub, email: claims.email ?? null, name: claims.name ?? claims.preferred_username ?? Unknown user, } }, })若 provider 根本不支持 OIDC则用createOAuthProvider()实现createAuthorizationURL/handleCallback/refreshTokens钩子。其中transaction.providerState是 provider 拥有的不透明数据运行时会在createAuthorizationURL()时写入序列化值随 OAuth 事务持久化后原样交还handleCallback()由于 session 存储不保证机密性敏感值必须自行加密。用 auth 中间件解析请求身份登录协议工作在remix/auth而请求期的身份解析在remix/middleware/auth见 auth-middleware README。auth({ schemes })按顺序尝试各 scheme把成功或失败结果存入context.authrouter createRouter({ middleware: [ session(sessionCookie, sessionStorage), auth({ schemes: [ createSessionAuthSchemeUser, { userId: string }({ read(session) { return session.get(auth) as { userId: string } | null }, verify(value) { return users.getById(value.userId) }, invalidate(session) { session.unset(auth) }, }), ], }), ], })auth()写入的形态是{ ok: true, identity, method }或{ ok: false, error? }。内置三个 schemecreateSessionAuthScheme()——从session()加载的 session 读取createBearerTokenAuthScheme()——Authorization: Bearer token头createAPIAuthScheme()——自定义请求头中的 API key。schemes数组按顺序回退一个 scheme 返回 success 或 failure 即停止全部无结果则请求视为匿名。自定义 scheme 就是一个{ name, authenticate(context) }对象authenticate返回null/undefined表示跳过、{ status: success, identity }表示认证成功、{ status: failure, code?, message?, challenge? }表示认证失败scheme 的name会成为成功后的auth.methodfailure 里带challenge时会被自动转发到WWW-Authenticate响应头。social-auth 演示 展示了 session scheme 的进阶形态verify里不仅查用户还联查authAccounts表把登录方式密码/GitHub/Google/X与 provider profile 一并解析进 identity供后续路由按登录方式做差异化处理。用 requireAuth 保护路由auth()与requireAuth()的分离是刻意的同一份身份解析结果要同时支撑公共路由、API 路由和浏览器路由而失败行为各不相同。requireAuth()必须在auth()之后使用否则直接抛错默认失败返回401 Unauthorized可以用onFailure(context, auth)替换为任意响应——HTML 重定向、frame HTML、API JSON 都可以类型上上下文契约包含auth()和requireAuthIdentity()的 handler 可以直接读context.auth.identity无需手动context.get(Auth)。按文档建议onFailure应区分响应形态见 auth-middleware README 的示例let requireAuthCookie requireAuthdemo-user({ onFailure(context) { let isFrameRequest context.request.headers.get(X-Remix-Frame) true if (isFrameRequest) { return new Response(pNot authorized/p, { status: 401, headers: { Content-Type: text/html; charsetutf-8 }, }) } return redirect(/login) }, })social-auth 的 requireAuth 则是更简单的形态——失败一律重定向回首页export function requireAuth() { return requireAuthenticatedAuthIdentity({ onFailure() { return redirect(routes.home.href()) }, }) }一个必须记住的边界一个 controller 上的路由保护不会流入为嵌套 route map 映射的 controller。requireAuth()是 controller/action 级中间件给每个含敏感操作的 controller 显式挂上保护不要假设父级映射“继承”了守卫。授权对每个资源操作单独检查认证回答“请求是谁发的”授权决定“这个身份能不能读写这条记录”。即使requireAuth()已经放行仍须在 action 或数据写入路径内检查所有权记录的 owner 是否等于当前 identity角色/租户角色是否足够、是否属于同一租户状态迁移操作在当前资源状态下是否合法。这类检查属于应用业务逻辑Remix 不提供内建策略引擎——从仓库结构看social-auth 的数据层 与 action controller 各自承担此类断言这正是“认证由框架中间件完成、授权由路由/动作代码完成”的分工体现。CSRF 同步器令牌csrf()csrf-middleware是“保守派”方案session 存储的同步器令牌 来源校验。两条中间件顺序硬性要求来自章节文档并被包 README 印证session()必须在csrf()之前运行——令牌要持久化在请求 session 里表单解析必须在从_csrf提取令牌之前完成——即需要formData()中间件把请求体解析出来。import { csrf, getCsrfToken } from remix/middleware/csrf let router createRouter({ middleware: [session(sessionCookie, sessionStorage), csrf()], }) router.get(/form, (context) { let token getCsrfToken(context) return new Response( form methodpost action/submit input typehidden name_csrf value${token} / button typesubmitSubmit/button /form ) })令牌来源与传输方式csrf()默认按以下顺序提取令牌请求头X-Csrf-Token、X-Xsrf-Token、Csrf-Token表单字段_csrf依赖formData()中间件查询参数_csrf兼容性兜底最弱——令牌易泄漏到日志、历史与复制链接中。也可以用value(context)完全自定义提取逻辑。受控客户端场景下优先用请求头或隐藏表单字段。来源校验与 missing-origin 策略对不安全方法POST/PUT/PATCH/DELETE中间件还会校验请求来源默认策略Origin或Referer存在时执行同源校验自定义origin可传字符串、正则、数组或函数missing origin 行为由allowMissingOrigin控制默认true——即两个来源头都缺失时持有合法令牌的请求仍会通过。如果你的部署希望不安全请求必须携带来源头应显式设allowMissingOrigin: false。为什么 Cookie 认证的浏览器请求需要这套刻意防御现代浏览器已提供Sec-Fetch-SiteSameSiteLax也拦截了大量 CSRF但 Remix 无法假设每个部署都能满足无令牌模型的全部前提因此csrf()作为“同步器令牌 来源校验”的保守选项保留给 session 表单流程与混合部署环境。无令牌跨源防护cop()当部署可以依赖Sec-Fetch-Site与Origin时cop()cop-middleware是更轻的替代——它对不安全方法做浏览器来源检查全程不需要令牌或会话存储。判定顺序Sec-Fetch-Site: same-origin或none→ 放行其他Sec-Fetch-Site值 → 拒绝除非命中 trusted origin 或 insecure bypass无Sec-Fetch-Site→ 比较Origin与请求 host两者都缺失 →放行有意为之让老客户端与非浏览器调用者不会默认被 fail-closed 拒掉。两项配置属于“窄安全例外”范围必须收小cop({ // 精确 originscheme://host[:port] trustedOrigins: [https://admin.example.com], // 方法前缀 / 精确路径 / 尾斜杠子树 / {name} / {name...} 通配 insecureBypassPatterns: [POST /webhooks/{provider}, /healthz], })也可以把cop()叠在csrf()前面先用来源头做早期拦截剩余流量再走令牌校验let router createRouter({ middleware: [cop(), session(sessionCookie, sessionStorage), csrf()], })CORS 既不是认证也不是 CSRF 防护cors()cors-middleware只用于“浏览器必须跨源调用”的端点。配置要点精确的 origin、credentials、请求头与 preflight 策略都要显式给出。两个常见误解要纠正CORS 响应头不授权调用方——它们只影响浏览器如何呈现跨源响应攻击者发起跨源 POST 并不会被 CORS 阻止CORS挡不住非浏览器客户端curl、脚本、服务器直接访问端点。因此 CORS 配置不能替代auth()/requireAuth()也不能替代csrf()/cop()它是面向“跨源前端消费者”的独立关注点。中间件顺序与整体装配把上述部件装配进一个真实路由时顺序即语义。social-auth 演示的 中间件链 是一个可直接参考的装配范本function createSocialAuthMiddleware(cookie: Cookie, storage: SessionStorage) { return createMiddleware( staticFiles(./public, { cacheControl: no-store, must-revalidate, etag: false, lastModified: false }), formData(), session(cookie, storage), // 先于依赖 session 的一切 loadDatabase(), loadAuth(), // auth({ schemes }) —— 身份解析 render(), ) }对照本篇各节的顺序约束一份完整的安全栈大致是cop() → session(cookie, storage) → formData() → csrf() → auth({ schemes }) → 路由requireAuth() 资源级授权session在csrf之前令牌需要会话存储formData在csrf之前_csrf表单字段需要已解析的请求体auth在session之后session scheme 依赖context.sessionrequireAuth()作为 controller/action 中间件逐处挂载失败行为按端点形态定制登录成功后completeAuth()轮换 session id 再写认证记录登出时destroy()/regenerateId(true)整体失效。这套组合让每层各司其职remix/cookie保证传输层不可篡改remix/session管理状态生命周期remix/auth完成登录协议并交出 app-owned 认证记录remix/middleware/auth在请求期解析身份requireAuth()守住路由入口而csrf()与cop()在浏览器请求边界补上最后一道来源校验。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Remix 认证、会话与安全体系实战指南：从签名 Cookie 到路由保护与跨源防护
Remix 认证、会话与安全体系实战指南从签名 Cookie 到路由保护与跨源防护【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix在 RemixThe fully-stacked web framework中一个签名 Cookie、一个 session、一个已认证的 identity 是三个不同层次的概念。本篇指南按照“先建底层、再加上层”的顺序完整讲解 Remix 如何管理每浏览器的状态remix/cookie、remix/session、如何在登录流程中写入可信的身份记录remix/auth、如何在每个请求上解析身份并保护路由remix/middleware/auth以及如何在会改变状态的路由外围叠加 CSRF 同步器令牌csrf()与无令牌跨源防护cop()。读完本篇你可以直接在当前仓库的包实现与demos/示例上复刻一套从 Cookie 到 OAuth 登录、再到路由守卫与浏览器来源校验的完整安全栈。三层模型Cookie、Session 与身份Remix 的安全体系建议按以下顺序构建签名 Cookieremix/cookie提供的类型安全 Cookie 解析/序列化支持 HMAC-SHA256 签名与密钥轮换Sessionremix/session提供的服务端管理生命周期flash 值、ID 轮换、防篡改存储通过remix/middleware/session挂到请求上下文上认证身份remix/auth负责登录协议凭据校验、OAuth/OIDC 跳转与回调把“app-owned”的认证记录写入 session之后每个请求再由remix/middleware/auth的auth()把 session 记录解析回context.auth最后用requireAuth()保护路由。在这三层之上才叠加授权检查authorization、CSRF 同步器令牌、跨源防护COP等针对浏览器请求边界防御的中间件。这个顺序的意义在于后一层依赖前一层的安全属性——session 依赖签名 Cookie 防篡改身份解析依赖 session 里可信任的认证记录。纯 Cookie 与 Session 的选型用remix/cookie处理浏览器可控的偏好或一个小的签名值例如主题偏好、记住的 token 标记用remix/session处理需要服务端管理生命周期的状态flash 值、ID 轮换、防篡改存储——典型如登录态和购物车。remix/cookie基于 Web Crypto API 构建运行时无依赖Node.js、Bun、Deno、Cloudflare Workers 均可。核心 API 在 cookie 包 README 中import { createCookie } from remix/cookie let sessionCookie createCookie(session, { httpOnly: true, secrets: [s3cret1], secure: true, }) // 从请求的 Cookie header 解析该 cookie 的值 let value await sessionCookie.parse(request.headers.get(Cookie)) // 通过响应 Set-Cookie header 写回 let response new Response(Hello, world!, { headers: { Set-Cookie: await sessionCookie.serialize(value) }, })Cookie 配置与密钥轮换属性要有意识地设置httpOnly、sameSite、secure、path与过期时间应当刻意配置而不是依赖默认值。Remix 的 session cookie 典型配置见 auth 包 README 与 session-middleware 包 READMElet sessionCookie createCookie(__session, { secrets: [env.SESSION_SECRET], httpOnly: true, // 禁止 JS 读取防御 XSS 窃取 secure: true, // 仅 HTTPS 传输 sameSite: lax, // 降低 CSRF 面 path: /, })注意两条硬性约定session-middleware 文档明确说明session cookie 必须签名防止客户端篡改 session 数据且 session cookie 默认是 HTTP-only 的。签名实现HMAC-SHA256签名防止篡改但不隐藏 cookie 内容——值本身仍是可读取的默认经 percent-encoding base64 包装。从源码看cookie-signing.ts 中sign()用crypto.subtle以 HMAC/SHA-256 对值签名输出value.hash格式unsign()按最后一个.拆分值与哈希并验证任何 base64 非法字符都会被当作无效签名处理export async function sign(value: string, secret: string): Promisestring { let data encoder.encode(value) let key await createKey(secret, [sign]) let signature await crypto.subtle.sign(HMAC, key, data) let hash btoa(String.fromCharCode(...new Uint8Array(signature))).replace(/$/, ) return value . hash }密钥轮换新密钥放最前生产环境要求密钥来自环境配置而非测试常量。轮换时把新的签名密钥放在数组最前面旧 cookie 仍然可以被解析// 最初 let sessionCookie createCookie(session, { secrets: [secret1] }) // 轮换后新密钥在头部新序列化的 cookie 用 secret2 签名 let rotated createCookie(session, { secrets: [secret2, secret1] }) // 两种密钥签发的 cookie 都能 parse let value await rotated.parse(request.headers.get(Cookie))此外还可以自定义encode/decode作为完整的 cookie 值编解码器自定义编码会跳过默认 base64 包装直接签名后序列化适合希望在开发者工具中看到人类可读值的场景但必须自行保证输出只包含合法的 cookie 值字符。Session 中间件与存储策略session 中间件读进上下文、写回响应session(cookie, storage)会把签名 cookie 对应的 session 读入请求上下文context.session或context.get(Session)并在请求结束时把变更持久化到存储、把新值序列化进Set-Cookie响应头。基础用法见 session-middleware READMEimport { createRouter } from remix/router import { createCookie } from remix/cookie import { createCookieSessionStorage } from remix/session-storage/cookie import { session } from remix/middleware/session let sessionCookie createCookie(__session, { secrets: [s3cr3t], // session cookies must be signed! secure: true, sameSite: lax, }) let sessionStorage createCookieSessionStorage() let router createRouter({ middleware: [session(sessionCookie, sessionStorage)] }) router.get(/, (context) { context.session.set(count, Number(context.session.get(count) ?? 0) 1) return new Response(Count: ${context.session.get(count)}) })五种存储策略的对比维度仓库提供了多种存储后端选择时按数据量上限、持久性、运行时环境、多进程是否共享状态四个维度权衡存储创建函数适用场景关键限制CookiecreateCookieSessionStorage()remix/session-storage/cookie生产可用、无额外依赖全部数据塞进 cookie受浏览器上限通常 4096 字节约束文件系统createFsSessionStorage(/tmp/sessions)remix/session-storage/fs生产、需要持久文件系统能承载大 session 数据需要可写文件系统内存createMemorySessionStorage()测试与开发进程重启即丢失Redisremix/session-storage/redis多应用进程需要共享 session依赖 Redis 服务Memcacheremix/session-storage/memcache多进程共享、可过期依赖 Memcache 服务实现入口分别位于 cookie.ts、fs.ts、memory.tsRedis/Memcache 则独立成包 session-storage-redis 与 session-storage-memcache。判断标准如果多个应用进程集群部署必须看到同一份 sessionCookie 存储与内存/文件系统存储都不满足要求应选 Redis 或 Memcache。Session 值、Flash、ID 轮换与销毁Session类session.ts是这部分的实现核心类型参数分别约束 value 与 flash 两个命名空间get(key)优先读 value 表回落到 flash 表set(key, value)写入 value 表传null会删除该键unset(key)删除 value 表中的键flash(key, value)只写入nextMap——当前请求内get读不到下一个请求可见再下一个请求消失regenerateId(deleteOldSession?)生成新的 session IDcrypto.randomUUID()保留数据destroy()标记销毁之后任何修改都会抛出Session has been destroyed。Flash 的三段式行为在 session 包 README 的示例中被验证session.flash(message, success!) // 设置当次请求 get(message) 为 undefined // 该响应通常是重定向到展示页的路由 // 下一个请求 get(message) success! // 再下一个请求又恢复 undefinedID 轮换防会话固定登录等权限变化之后应调用regenerateId()在响应中签发新的 session ID。源码上session.tsregenerateId(true)会把deleteId记为原始session ID保存时删除旧数据传false默认则保留旧数据——README 提示后者适用于弱网移动端可能凭旧 ID 恢复会话的场景。登出销毁而不是删一个字段用户登出时应调用session.destroy()下次保存时清空存储中的全部数据并在下一个响应中清掉客户端的 session ID使下一个请求从全新 session 开始。不要只unset(userId)——残留的其他字段仍可能被复用这是会话固定攻击的常见入口。凭据登录与登出provider 管校验路由管跳转remix/auth暴露五个原语verifyCredentials()、startExternalAuth()、finishExternalAuth()、refreshExternalAuth()、completeAuth()。分工原则是路由拥有重定向与面向用户的失败反馈provider 拥有协议校验。createCredentialsAuthProvider()接受两个钩子parse(context)从请求上下文取出凭据verify(credentials)返回用户或null。Remix 的 auth 包 README 给出了完整流程let passwordProvider createCredentialsAuthProvider({ parse(context) { let formData context.get(FormData) if (formData null) { throw new Error(Expected formData() middleware before verifyCredentials()) } return { email: String(formData.get(email) ?? ), password: String(formData.get(password) ?? ), } }, async verify({ email, password }) { return users.verifyPassword(email, password) }, }) router.post(routes.auth.session.login.action, async (context) { let user await verifyCredentials(passwordProvider, context) if (user null) { return redirect(routes.auth.session.login.index.href()) } let session completeAuth(context) // 轮换 session id session.set(auth, { userId: user.id }) // 写入 app-owned 认证记录 return redirect(routes.app.dashboard.href()) }) router.post(routes.auth.session.logout, ({ get }) { let session get(Session) session.unset(auth) session.regenerateId(true) // 登出时销毁/轮换而非只删一个字段 return redirect(routes.auth.session.login.index.href()) })关键点completeAuth()在写认证记录之前轮换当前 session id实现见 complete-auth.ts这正是前面regenerateId安全要求在登录成功时刻的落地。仓库中的 social-auth 演示 展示了更贴近实战的parse实现先用remix/data-schema的表单 schema 解析并规范化 email再查库、比对密码哈希const loginSchema f.object({ email: f.field(s.defaulted(s.string(), )), password: f.field(s.defaulted(s.string(), )), }) export const passwordProvider createCredentialsAuthProvider({ parse(context) { let formData context.get(FormData) let { email, password } s.parse(loginSchema, formData) return { email: normalizeEmail(email), password } }, async verify({ email, password }, context) { let db context.get(databaseContext) let user await db.findOne(users, { where: { email } }) if (user null) return null if (typeof user.password_hash string user.password_hash ! ) { return (await verifyPassword(password, user.password_hash)) ? user : null } return null }, })OAuth 与 OIDC 登录外部登录的标准七步来自 auth 包 README在模块作用域创建 provider启动时校验配置、回调 URL 稳定登录路由调用startExternalAuth(provider, context, options?)——它把进行中的 OAuth 事务存入 session 并返回跳转响应回调路由调用finishExternalAuth(provider, context)——校验回调、清除存储的事务返回{ result, returnTo? }provider token 位于result.tokens持久化你希望复用的 provider token调用completeAuth(context)并把认证记录写进返回的 session后续请求中读取存储的 token 包需要时再用refreshExternalAuth()刷新并回存返回你自己的重定向。Google 登录的完整路由示例let googleProvider createGoogleAuthProvider({ clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET, redirectUri: new URL(routes.auth.google.callback.href(), env.APP_ORIGIN), authorizationParams: { access_type: offline, prompt: consent }, }) router.get(routes.auth.google.login, (context) startExternalAuth(googleProvider, context, { returnTo: context.url.searchParams.get(returnTo), }), ) router.get(routes.auth.google.callback, async (context) { let { result, returnTo } await finishExternalAuth(googleProvider, context) let user await users.upsertFromGoogle(result.profile) await persistProviderTokens(user.id, result.tokens) let session completeAuth(context) session.set(auth, { userId: user.id }) return redirect(returnTo ?? routes.app.dashboard.href()) })内置 provider 与关键约定内置 provider 覆盖两类运行时Google、Microsoft、Okta、Auth0 使用共享的OIDC 运行时GitHub、Facebook、X 使用内置的自定义 OAuth 流程实现位于 providers 目录。要点OIDC provider 默认在/.well-known/openid-configuration做 discovery想跳过 discovery 可传metadatametadata 在别处则传discoveryUrl默认 OIDC scope 为openid profile email非 OIDC 的默认 scopeGitHubread:user user:email、Facebookpublic_profile email、Xtweet.read users.readrefreshExternalAuth()支持内置 OIDC provider 与 X前提是存储的 token 包含 refresh token而 provider 只在配置了离线访问时才返回 refresh token如 Google 的authorizationParams: { access_type: offline }、X 的offline.accessscopecreateMicrosoftAuthProvider()增加tenant选项并据此构造 issuercreateOktaAuthProvider()需要完整 issuer URL如https://example.okta.com/oauth2/defaultcreateAuth0AuthProvider()接受 domain 并自行推导 issuer。自定义 OIDC 与自定义 OAuth自定义 SSO 直接用createOIDCAuthProvider()通过mapProfile({ claims })把 claims 映射为应用内部类型let companyProvider createOIDCAuthProvider({ name: company, issuer: https://sso.acme.com, clientId: acme-web, clientSecret: acme-web-secret, redirectUri: new URL(/auth/company/callback, https://app.acme.com), mapProfile({ claims }) { return { id: claims.sub, email: claims.email ?? null, name: claims.name ?? claims.preferred_username ?? Unknown user, } }, })若 provider 根本不支持 OIDC则用createOAuthProvider()实现createAuthorizationURL/handleCallback/refreshTokens钩子。其中transaction.providerState是 provider 拥有的不透明数据运行时会在createAuthorizationURL()时写入序列化值随 OAuth 事务持久化后原样交还handleCallback()由于 session 存储不保证机密性敏感值必须自行加密。用 auth 中间件解析请求身份登录协议工作在remix/auth而请求期的身份解析在remix/middleware/auth见 auth-middleware README。auth({ schemes })按顺序尝试各 scheme把成功或失败结果存入context.authrouter createRouter({ middleware: [ session(sessionCookie, sessionStorage), auth({ schemes: [ createSessionAuthSchemeUser, { userId: string }({ read(session) { return session.get(auth) as { userId: string } | null }, verify(value) { return users.getById(value.userId) }, invalidate(session) { session.unset(auth) }, }), ], }), ], })auth()写入的形态是{ ok: true, identity, method }或{ ok: false, error? }。内置三个 schemecreateSessionAuthScheme()——从session()加载的 session 读取createBearerTokenAuthScheme()——Authorization: Bearer token头createAPIAuthScheme()——自定义请求头中的 API key。schemes数组按顺序回退一个 scheme 返回 success 或 failure 即停止全部无结果则请求视为匿名。自定义 scheme 就是一个{ name, authenticate(context) }对象authenticate返回null/undefined表示跳过、{ status: success, identity }表示认证成功、{ status: failure, code?, message?, challenge? }表示认证失败scheme 的name会成为成功后的auth.methodfailure 里带challenge时会被自动转发到WWW-Authenticate响应头。social-auth 演示 展示了 session scheme 的进阶形态verify里不仅查用户还联查authAccounts表把登录方式密码/GitHub/Google/X与 provider profile 一并解析进 identity供后续路由按登录方式做差异化处理。用 requireAuth 保护路由auth()与requireAuth()的分离是刻意的同一份身份解析结果要同时支撑公共路由、API 路由和浏览器路由而失败行为各不相同。requireAuth()必须在auth()之后使用否则直接抛错默认失败返回401 Unauthorized可以用onFailure(context, auth)替换为任意响应——HTML 重定向、frame HTML、API JSON 都可以类型上上下文契约包含auth()和requireAuthIdentity()的 handler 可以直接读context.auth.identity无需手动context.get(Auth)。按文档建议onFailure应区分响应形态见 auth-middleware README 的示例let requireAuthCookie requireAuthdemo-user({ onFailure(context) { let isFrameRequest context.request.headers.get(X-Remix-Frame) true if (isFrameRequest) { return new Response(pNot authorized/p, { status: 401, headers: { Content-Type: text/html; charsetutf-8 }, }) } return redirect(/login) }, })social-auth 的 requireAuth 则是更简单的形态——失败一律重定向回首页export function requireAuth() { return requireAuthenticatedAuthIdentity({ onFailure() { return redirect(routes.home.href()) }, }) }一个必须记住的边界一个 controller 上的路由保护不会流入为嵌套 route map 映射的 controller。requireAuth()是 controller/action 级中间件给每个含敏感操作的 controller 显式挂上保护不要假设父级映射“继承”了守卫。授权对每个资源操作单独检查认证回答“请求是谁发的”授权决定“这个身份能不能读写这条记录”。即使requireAuth()已经放行仍须在 action 或数据写入路径内检查所有权记录的 owner 是否等于当前 identity角色/租户角色是否足够、是否属于同一租户状态迁移操作在当前资源状态下是否合法。这类检查属于应用业务逻辑Remix 不提供内建策略引擎——从仓库结构看social-auth 的数据层 与 action controller 各自承担此类断言这正是“认证由框架中间件完成、授权由路由/动作代码完成”的分工体现。CSRF 同步器令牌csrf()csrf-middleware是“保守派”方案session 存储的同步器令牌 来源校验。两条中间件顺序硬性要求来自章节文档并被包 README 印证session()必须在csrf()之前运行——令牌要持久化在请求 session 里表单解析必须在从_csrf提取令牌之前完成——即需要formData()中间件把请求体解析出来。import { csrf, getCsrfToken } from remix/middleware/csrf let router createRouter({ middleware: [session(sessionCookie, sessionStorage), csrf()], }) router.get(/form, (context) { let token getCsrfToken(context) return new Response( form methodpost action/submit input typehidden name_csrf value${token} / button typesubmitSubmit/button /form ) })令牌来源与传输方式csrf()默认按以下顺序提取令牌请求头X-Csrf-Token、X-Xsrf-Token、Csrf-Token表单字段_csrf依赖formData()中间件查询参数_csrf兼容性兜底最弱——令牌易泄漏到日志、历史与复制链接中。也可以用value(context)完全自定义提取逻辑。受控客户端场景下优先用请求头或隐藏表单字段。来源校验与 missing-origin 策略对不安全方法POST/PUT/PATCH/DELETE中间件还会校验请求来源默认策略Origin或Referer存在时执行同源校验自定义origin可传字符串、正则、数组或函数missing origin 行为由allowMissingOrigin控制默认true——即两个来源头都缺失时持有合法令牌的请求仍会通过。如果你的部署希望不安全请求必须携带来源头应显式设allowMissingOrigin: false。为什么 Cookie 认证的浏览器请求需要这套刻意防御现代浏览器已提供Sec-Fetch-SiteSameSiteLax也拦截了大量 CSRF但 Remix 无法假设每个部署都能满足无令牌模型的全部前提因此csrf()作为“同步器令牌 来源校验”的保守选项保留给 session 表单流程与混合部署环境。无令牌跨源防护cop()当部署可以依赖Sec-Fetch-Site与Origin时cop()cop-middleware是更轻的替代——它对不安全方法做浏览器来源检查全程不需要令牌或会话存储。判定顺序Sec-Fetch-Site: same-origin或none→ 放行其他Sec-Fetch-Site值 → 拒绝除非命中 trusted origin 或 insecure bypass无Sec-Fetch-Site→ 比较Origin与请求 host两者都缺失 →放行有意为之让老客户端与非浏览器调用者不会默认被 fail-closed 拒掉。两项配置属于“窄安全例外”范围必须收小cop({ // 精确 originscheme://host[:port] trustedOrigins: [https://admin.example.com], // 方法前缀 / 精确路径 / 尾斜杠子树 / {name} / {name...} 通配 insecureBypassPatterns: [POST /webhooks/{provider}, /healthz], })也可以把cop()叠在csrf()前面先用来源头做早期拦截剩余流量再走令牌校验let router createRouter({ middleware: [cop(), session(sessionCookie, sessionStorage), csrf()], })CORS 既不是认证也不是 CSRF 防护cors()cors-middleware只用于“浏览器必须跨源调用”的端点。配置要点精确的 origin、credentials、请求头与 preflight 策略都要显式给出。两个常见误解要纠正CORS 响应头不授权调用方——它们只影响浏览器如何呈现跨源响应攻击者发起跨源 POST 并不会被 CORS 阻止CORS挡不住非浏览器客户端curl、脚本、服务器直接访问端点。因此 CORS 配置不能替代auth()/requireAuth()也不能替代csrf()/cop()它是面向“跨源前端消费者”的独立关注点。中间件顺序与整体装配把上述部件装配进一个真实路由时顺序即语义。social-auth 演示的 中间件链 是一个可直接参考的装配范本function createSocialAuthMiddleware(cookie: Cookie, storage: SessionStorage) { return createMiddleware( staticFiles(./public, { cacheControl: no-store, must-revalidate, etag: false, lastModified: false }), formData(), session(cookie, storage), // 先于依赖 session 的一切 loadDatabase(), loadAuth(), // auth({ schemes }) —— 身份解析 render(), ) }对照本篇各节的顺序约束一份完整的安全栈大致是cop() → session(cookie, storage) → formData() → csrf() → auth({ schemes }) → 路由requireAuth() 资源级授权session在csrf之前令牌需要会话存储formData在csrf之前_csrf表单字段需要已解析的请求体auth在session之后session scheme 依赖context.sessionrequireAuth()作为 controller/action 中间件逐处挂载失败行为按端点形态定制登录成功后completeAuth()轮换 session id 再写认证记录登出时destroy()/regenerateId(true)整体失效。这套组合让每层各司其职remix/cookie保证传输层不可篡改remix/session管理状态生命周期remix/auth完成登录协议并交出 app-owned 认证记录remix/middleware/auth在请求期解析身份requireAuth()守住路由入口而csrf()与cop()在浏览器请求边界补上最后一道来源校验。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考