OAuth 2.0 PKCE 与 Token 旋转

步骤 1  浏览器 → 授权服务器:跳转,用户登录+同意
        授权服务器 → 浏览器:回跳 redirect_uri,带 authorization code
步骤 2  客户端后端 → 授权服务器:code + client_secret → 换 access_token

客户端(发起授权前)
  1. 生成 code_verifier:43~128 位的高熵随机字符串
  2. 算 code_challenge = BASE64URL( SHA256( code_verifier ) )   ← method=S256
  3. 跳转授权服务器,带上 code_challenge + code_challenge_method=S256

授权服务器
  4. 记下:这个授权会话绑定了这个 code_challenge

用户登录+同意后,回跳带 code

客户端(换 token 时)
  5. 拿 code + code_verifier(原值) 去换 token

授权服务器
  6. 重新算 BASE64URL(SHA256(code_verifier)),跟步骤 3 记下的 challenge 比对
  7. 匹配 → 发 token;不匹配 → 拒绝

// pkce.js —— 手写 PKCE,理解原理
import { randomBytes, createHash } from 'node:crypto';

// 1. 生成 code_verifier:43~128 字符,base64url 编码的高熵随机串
export function generateCodeVerifier() {
  return randomBytes(32).toString('base64url'); // 43 字符,刚好满足最小长度
}

// 2. 由 verifier 算出 challenge(S256)
export function computeCodeChallenge(verifier) {
  return createHash('sha256').update(verifier).digest('base64url');
}

// 3. 发起授权时,把 verifier 存起来(内存 / sessionStorage,不要 localStorage)
//    challenge 放进授权 URL
export function buildAuthorizeUrl(authEndpoint, params, verifier) {
  const challenge = computeCodeChallenge(verifier);
  const url = new URL(authEndpoint);
  url.searchParams.set('response_type', 'code');
  url.searchParams.set('client_id', params.clientId);
  url.searchParams.set('redirect_uri', params.redirectUri);
  url.searchParams.set('scope', params.scope);
  url.searchParams.set('state', params.state);          // 防 CSRF,必须带
  url.searchParams.set('code_challenge', challenge);
  url.searchParams.set('code_challenge_method', 'S256');
  return url.toString();
}

// 4. 换 token 时,把原 verifier 一起发出去
export async function exchangeCodeForToken(tokenEndpoint, payload) {
  const res = await fetch(tokenEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: payload.code,
      redirect_uri: payload.redirectUri,
      client_id: payload.clientId,
      code_verifier: payload.verifier,  // ← 关键:原值,不是哈希
    }),
  });
  return res.json(); // { access_token, refresh_token?, id_token?, expires_in }
}

隐式流程:
  浏览器 → 授权服务器:response_type=token
  授权服务器 → 浏览器:redirect_uri#access_token=eyJhbG...&expires_in=3600
  前端 JS 从 location.hash 里抠出 token,存起来

无 rotation:
  refresh_token_R1 → 换 access_token
  过一会 refresh_token_R1 → 再换 access_token   ← 同一个 refresh 反复用,泄露即长期失守

有 rotation:
  refresh_token_R1 → 换 access_token + refresh_token_R2(R1 立即失效)
  refresh_token_R2 → 换 access_token + refresh_token_R3(R2 立即失效)
  ...

合法用户:R2 → 换到 access + R3   (R2 现在已失效,但攻击者手里还有 R2 的副本)
攻击者:R2 → 想换 token?         (R2 已失效,服务器拒绝)

合法用户:R2 → 换到 access + R3
攻击者(手慢):R2 → 拿去换       ← R2 已经被用过一次换出了 R3,现在第二次出现

服务器发现:R2 是个"已经被消费过的" refresh token,它居然又被提交了!
         → 这只能说明 refresh token 链条被分叉了 → 有人被偷了
         → 立即作废整条链(R3、R4... 全部失效),强制用户重新登录

// tokenRotation.js —— 服务端 refresh + 旋转 + 重用检测
import { randomBytes } from 'node:crypto';
import { redis } from './redis';

const REFRESH_TTL = 60 * 60 * 24 * 30; // 30 天
const CHAIN_PREFIX = 'refresh_chain:';

export async function rotateRefreshToken(oldRefreshToken, userId) {
  // 1. 查旧 token 的状态
  const tokenKey = `rtok:${oldRefreshToken}`;
  const meta = await redis.hgetall(tokenKey);

  if (!meta || meta.status !== 'active') {
    // 1a. 这个 token 要么不存在,要么已经被旋转过(status=rotated)
    if (meta && meta.status === 'rotated') {
      // ⚠ 重用检测:一个已经被旋转掉的 token 又被提交 → 链条被偷了
      // 立即作废整条链,强制重新登录
      await redis.del(`${CHAIN_PREFIX}${meta.chainId}`);
      throw new TokenTheftError('refresh token reuse detected, chain revoked');
    }
    throw new InvalidTokenError('refresh token not found');
  }

  // 2. 签发新 access token + 新 refresh token
  const newAccessToken = signAccessToken(userId, /* ttl */ 15 * 60);
  const newRefreshToken = randomBytes(32).toString('base64url');

  // 3. 旧的标记为 rotated(保留一段时间用于重用检测,然后过期)
  await redis.hset(tokenKey, 'status', 'rotated');
  await redis.expire(tokenKey, 60 * 60); // 1 小时后清掉

  // 4. 新的写进去,挂到同一条链上
  await redis.hset(`rtok:${newRefreshToken}`, {
    userId,
    chainId: meta.chainId,
    status: 'active',
  });
  await redis.expire(`rtok:${newRefreshToken}`, REFRESH_TTL);

  return { accessToken: newAccessToken, refreshToken: newRefreshToken };
}

// blacklist.js —— JWT 黑名单中间件
export async function authGuard(req, res, next) {
  const token = bearerOf(req);
  const payload = verifyJwt(token);             // 验签 + exp
  const blacklisted = await redis.get(`bl:${payload.jti}`);
  if (blacklisted) return res.status(401).end();
  req.user = payload;
  next();
}

export function revokeToken(payload) {
  // 黑名单 TTL = token 剩余寿命,过期后自动清掉,不占空间
  const ttl = payload.exp - Math.floor(Date.now() / 1000);
  if (ttl > 0) redis.set(`bl:${payload.jti}`, '1', 'EX', ttl);
}

// 签发
const jwt = sign({ userId, v: user.tokenVersion });

// 验证
const payload = verify(jwt);
const user = await db.user.findById(payload.userId);
if (payload.v !== user.tokenVersion) return res.status(401).end();

// auth.ts —— NextAuth v5 (Auth.js) 生产级配置
import NextAuth from 'next-auth';
import GitHub from 'next-auth/providers/github';
import Google from 'next-auth/providers/google';
import type { Provider } from 'next-auth/providers';

const providers: Provider[] = [
  GitHub({
    clientId: process.env.AUTH_GITHUB_ID,
    clientSecret: process.env.AUTH_GITHUB_SECRET,
    // NextAuth 对所有 OAuth provider 默认就走 authorization_code + PKCE
    // 如果想显式校验,检查跳转 URL 里有 code_challenge + code_challenge_method=S256
  }),
  Google({
    clientId: process.env.AUTH_GOOGLE_ID,
    clientSecret: process.env.AUTH_GOOGLE_SECRET,
    authorization: {
      params: {
        prompt: 'consent',         // 每次都弹同意,拿到新的 refresh_token
        access_type: 'offline',    // Google 要求 offline 才发 refresh_token
        scope: 'openid email profile',
      },
    },
  }),
];

export const { handlers, auth, signIn, signOut } = NextAuth({
  trustHost: true,                 // 生产必须开,否则 redirect_uri 拼不对
  secret: process.env.AUTH_SECRET, // 加密 cookie/JWT 用,务必是 32+ 字节随机串
  providers,
  session: { strategy: 'jwt' },    // Serverless 友好;有数据库可选 'database'
  cookies: {
    // 服务器组件里直接读 session,不用额外加 provider
    // httpOnly + Secure + SameSite=Lax 是默认,这里显式写出来便于审计
    sessionToken: {
      options: {
        httpOnly: true,
        sameSite: 'lax',
        path: '/',
        secure: process.env.NODE_ENV === 'production',
      },
    },
  },
  callbacks: {
    // 把 refresh token 写进 jwt,回调时续期用
    async jwt({ token, account, user }) {
      // 首次登录:account 里有 OAuth 返回的 tokens
      if (account) {
        token.accessToken = account.access_token;
        token.refreshToken = account.refresh_token;
        token.expiresAt = account.expires_at * 1000; // ms
        token.userId = user.id;
      }
      // 未过期:直接返回
      if (Date.now() < token.expiresAt - 60_000) {
        return token;
      }
      // 过期了:用 refresh token 续期
      if (token.refreshToken) {
        return refreshAccessToken(token);
      }
      return { ...token, error: 'RefreshTokenExpired' };
    },
    async session({ session, token }) {
      session.accessToken = token.accessToken;
      session.error = token.error;
      return session;
    },
  },
});

// auth.ts —— refresh access token
async function refreshAccessToken(token) {
  try {
    // Google 的 token 端点;不同 provider 不同,建议抽一张表
    const res = await fetch('https://oauth2.googleapis.com/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        client_id: process.env.AUTH_GOOGLE_ID,
        client_secret: process.env.AUTH_GOOGLE_SECRET,
        grant_type: 'refresh_token',
        refresh_token: token.refreshToken as string,
      }),
    });
    const refreshed = await res.json();
    if (!res.ok) throw refreshed;

    return {
      ...token,
      accessToken: refreshed.access_token,
      expiresAt: Date.now() + refreshed.expires_in * 1000,
      // 有些 provider 每次 refresh 会换发新 refresh_token,有些不换
      // 换了就用新的,没换就保留旧的(Google 倾向于不换)
      refreshToken: refreshed.refresh_token ?? token.refreshToken,
    };
  } catch (e) {
    console.error('refresh failed', e);
    return { ...token, error: 'RefreshTokenExpired' };
  }
}

// app/dashboard/page.tsx
import { auth, signIn, signOut } from '@/auth';

export default async function DashboardPage() {
  const session = await auth();

  if (!session) {
    return (
      <form action={signIn.bind(null, 'github')}>
        <button type="submit">用 GitHub 登录</button>
      </form>
    );
  }

  // session.error === 'RefreshTokenExpired' → refresh 挂了,引导重新登录
  if (session.error === 'RefreshTokenExpired') {
    return (
      <form action={signIn.bind(null, 'github')}>
        <p>登录态已过期,请重新登录。</p>
        <button type="submit">重新登录</button>
      </form>
    );
  }

  return (
    <div>
      <p>欢迎,access token 还在内存里,无需手动管理。</p>
      <form action={signOut}><button>登出</button></form>
    </div>
  );
}