link-based-auth

用途

link-based-auth 是一种参考模式（reference pattern），用于解决「需要个性化体验但不想引入登录界面摩擦」的问题。典型场景包括作品集网站、演示应用、仅限邀请访问等。文档明确说明：这是一个参考模式，应学习其思路并适配自身场景，不要逐字复制。

主要能力

该模式通过将认证令牌嵌入个性化 URL 来实现认证，主要组件包括：

链接生成器（Link Generator）：创建带嵌入令牌的 URL，并将每个链接与访客元数据关联。
身份后端（Identity Backend）：将令牌映射到虚拟用户身份（例如创建无密码的 Cognito 用户）。
边缘认证函数（Edge Auth Function）：在 CDN 边缘校验令牌并设置会话 Cookie。
认证上下文（Auth Context）：前端上下文，从 Cookie 中提取令牌并向组件提供认证状态。

使用方式

流程如下：

管理员生成带嵌入令牌的个性化链接
访客点击链接
CDN 边缘函数拦截请求
边缘函数校验令牌并设置认证 Cookie
前端加载时认证已建立
API 请求使用 Cookie/令牌进行授权

架构示意：

Personalized Link (contains token)
    ↓
CDN Edge Function
    ├── Valid token → Set cookie, redirect to app
    └── No/invalid token → Serve public view
    ↓
Static Frontend (reads cookie for auth state)
    ↓
API (validates token from Authorization header)

文档提供了边缘认证函数示例（Lambda@Edge、CloudFlare Worker 等），逻辑为：从查询字符串读取 token，校验有效则返回 302 重定向并设置 auth=${token}; Secure; HttpOnly; SameSite=Strict 的 Cookie；否则检查已有会话 Cookie，已认证则继续，未认证则提供公开视图。

前端认证上下文示例（lib/auth/auth-context.tsx）提供 useAuth，根据环境与路由类型返回不同的认证头：本地环境或公开路由使用 x-api-key，受保护路由且存在 accessToken 时使用 Authorization: Bearer。

数据获取示例（lib/profile/use-profile.ts）通过 useProfile 结合 useAuth，在未认证时跳过查询，认证时携带受保护路由的认证头。

本地开发可使用环境感知的拦截器（useLocalInterceptor），当环境为 local 且存在 visitor 查询参数时返回模拟数据，组件优先检查拦截器，再回退到真实数据。

适用场景

作品集网站中面向招聘者的专属视图
仅限邀请访问的演示应用
带门控个性化内容的营销网站
含客户专属章节的文档

优势

零摩擦：无登录界面、无密码、无注册
个性化：每个链接映射到特定访客身份
安全：令牌在服务端校验，Cookie 为 HttpOnly/Secure
防篡改：URL 操纵无效，认证与后端身份绑定

安全考量

Cookie 标志：Secure、HttpOnly、SameSite=Strict，防止 XSS 与 CSRF
令牌过期：短生命周期令牌限制暴露窗口
内容隔离：每个令牌映射到特定身份，访客只能看到自己的内容
无客户端密钥：令牌在服务端校验，前端只读取结果
直接 URL 访问：无有效令牌/Cookie 时仅可见公开内容（设计如此）

限制（何时不应使用）

敏感数据：该模式用于个性化，不用于保护高度敏感信息
长期会话：基于令牌的链接适合短时交互，不适合持久账户
复杂认证流程：若需要 MFA、密码重置或角色管理，应使用完整的认证提供商

渐进改进

如果开发者纠正了本技能本应防止的行为，建议对本技能提出具体修订，以防未来出现同样的纠正。

技能介绍

用途