Token 身份认证教程

这套教程面向正在学习 Node.js 与 TypeScript 的初学者，目标是理解并实现一套包含注册、登录、接口鉴权、刷新 Token 和退出登录的认证流程。

教程使用以下两个核心库：

jsonwebtoken：签发、验证和读取 JWT。
argon2：安全地哈希和验证密码。

本教程根据 2026-08-12 可见的官方文档编写。库版本变化时，应优先核对官方 README 和发布说明。

先记住两个职责

注册：密码 --argon2.hash()--> 密码哈希 --保存--> 数据库

登录：输入密码 + 数据库密码哈希 --argon2.verify()--> 是否匹配
                                            |
                                            v
                                      匹配后签发 Token

后续请求：Access Token --jwt.verify()--> 当前用户身份

argon2 解决“密码如何安全保存和验证”，jsonwebtoken 解决“登录成功后如何携带和验证身份凭证”。二者不是替代关系。

章节目录

完整业务流程

注册
  -> 校验输入
  -> Argon2 哈希密码
  -> 保存用户和 passwordHash

登录
  -> 根据账号查找用户
  -> Argon2 验证密码
  -> 创建登录会话
  -> 签发短期 Access Token
  -> 生成长期 Refresh Token

访问受保护接口
  -> 客户端发送 Authorization: Bearer <accessToken>
  -> 服务端验证签名、算法、签发方、接收方和过期时间
  -> 读取当前用户 ID
  -> 执行业务权限判断

刷新
  -> 校验 Refresh Token
  -> 检查服务端会话是否有效
  -> 轮换 Refresh Token
  -> 签发新的 Access Token

退出登录
  -> 撤销服务端会话
  -> 客户端删除本地凭证

与当前项目配置的关系

当前项目在源码中使用 import，由 TypeScript 按 CommonJS 模式转换，并通过 ts-node server.ts 运行：

{
  "compilerOptions": {
    "module": "commonjs",
    "esModuleInterop": true
  }
}

因此教程采用：

import jwt from "jsonwebtoken";
import * as argon2 from "argon2";

安装命令：

npm install jsonwebtoken argon2
npm install --save-dev @types/jsonwebtoken

argon2 自带 TypeScript 类型声明；jsonwebtoken 通常搭配 @types/jsonwebtoken。

目前项目尚未安装这两个依赖。教程只新增 Markdown 文档，不修改 package.json，也不改变 CommonJS 运行方式。

案例范围

案例使用“内存数组模拟数据库”，目的是集中学习认证流程。现实项目应替换为 MySQL 等持久化存储，并为用户名、会话 ID 等字段增加唯一约束和索引。

教学示例采用：

Access Token：JWT，有效期 15 分钟。
Refresh Token：密码学安全随机字符串，有效期 7 天。
数据库存储 Refresh Token 的 SHA-256 摘要，而不是原文。
刷新时执行 Refresh Token Rotation（轮换）。