JWT 身份验证助手

该助手提供一组函数用于编码、解码、签名与验证 JSON Web Token（JWT）。JWT 常用于 Web 应用中的身份验证与授权，本助手支持多种密码算法，提供完备的 JWT 能力。

导入

使用示例：

import { decode, sign, verify } from 'hono/jwt'

INFO

JWT 中间件 同样从 hono/jwt 中导入 jwt 函数。

sign()

该函数会对载荷进行编码，并使用指定算法与密钥生成 JWT。

sign(
  payload: unknown,
  secret: string,
  alg?: 'HS256'
): Promise<string>

示例

import { sign } from 'hono/jwt'

const payload = {
  sub: 'user123',
  role: 'admin',
  exp: Math.floor(Date.now() / 1000) + 60 * 5, // 5 分钟后过期
}
const secret = 'mySecretKey'
const token = await sign(payload, secret)

配置项

required payload: unknown

要签名的 JWT 载荷。你可以参考 Payload 校验 添加更多声明。

required secret: string

用于签名或验证 JWT 的密钥。

optional alg: AlgorithmTypes

JWT 的签名/验证算法，默认为 HS256。

verify()

该函数会校验 JWT 的真实性与有效性，确保 Token 未被篡改；若你提供了 Payload 校验 所需字段，也会同步检查这些约束。

verify(
  token: string,
  secret: string,
  alg?: 'HS256'
  issuer?: string | RegExp
): Promise<any>

示例

import { verify } from 'hono/jwt'

const tokenToVerify = 'token'
const secretKey = 'mySecretKey'

const decodedPayload = await verify(tokenToVerify, secretKey)
console.log(decodedPayload)

配置项

required token: string

待验证的 JWT。

required secret: string

用于签名或验证 JWT 的密钥。

optional alg: AlgorithmTypes

JWT 的签名/验证算法，默认为 HS256。

optional issuer: string | RegExp

期望的签发者，用于验证。

decode()

该函数会在 不 验证签名的情况下解析 JWT，并返回其中的 header 与 payload。

decode(token: string): { header: any; payload: any }

示例

import { decode } from 'hono/jwt'

// 解码 JWT
const tokenToDecode =
  'eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcjEyMyIsICJyb2xlIjogImFkbWluIn0.JxUwx6Ua1B0D1B0FtCrj72ok5cm1Pkmr_hL82sd7ELA'

const { header, payload } = decode(tokenToDecode)

console.log('Decoded Header:', header)
console.log('Decoded Payload:', payload)

配置项

required token: string

需要解析的 JWT。

decode 函数可以在 不 验证签名的情况下查看 JWT 的 header 与 payload，适合调试或提取信息。

Payload 校验

在验证 JWT 时，会针对以下载荷字段执行检查：

• exp：确认 Token 是否已过期。
• nbf：确认 Token 是否在允许使用的时间之前被调用。
• iat：确认 Token 的签发时间不是未来。
• iss：确认 Token 是否由可信的签发者生成。

如果你希望在验证过程中启用这些检查，请确保 JWT 载荷中包含相应的字段。

自定义错误类型

模块定义了若干自定义错误，便于处理与 JWT 相关的问题。

• JwtAlgorithmNotImplemented：请求的 JWT 算法尚未实现。
• JwtTokenInvalid：JWT 无效。
• JwtTokenNotBefore：Token 在允许时间之前被使用。
• JwtTokenExpired：Token 已过期。
• JwtTokenIssuedAt：Token 的 iat 声明不正确。
• JwtTokenIssuer：Token 的 iss 声明不正确。
• JwtTokenSignatureMismatched：Token 签名不匹配。

支持的 AlgorithmTypes

当前支持以下 JWT 加密算法：

• HS256：基于 SHA-256 的 HMAC
• HS384：基于 SHA-384 的 HMAC
• HS512：基于 SHA-512 的 HMAC
• RS256：基于 SHA-256 的 RSASSA-PKCS1-v1_5
• RS384：基于 SHA-384 的 RSASSA-PKCS1-v1_5
• RS512：基于 SHA-512 的 RSASSA-PKCS1-v1_5
• PS256：基于 SHA-256 与 MGF1(SHA-256) 的 RSASSA-PSS
• PS384：基于 SHA-384 与 MGF1(SHA-384) 的 RSASSA-PSS
• PS512：基于 SHA-512 与 MGF1(SHA-512) 的 RSASSA-PSS
• ES256：P-256 + SHA-256 的 ECDSA
• ES384：P-384 + SHA-384 的 ECDSA
• ES512：P-521 + SHA-512 的 ECDSA
• EdDSA：使用 Ed25519 的 EdDSA