JWT 身份验证辅助工具

此辅助工具提供 JSON Web Token（JWT）的编码、解码、签名和验证函数。JWT 常用于 Web 应用的身份验证和授权。该工具提供完善的 JWT 功能，支持多种加密算法。

导入

可以按以下方式导入此辅助工具：

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

说明

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, // Token expires in 5 minutes
}
const secret = 'mySecretKey'
const token = await sign(payload, secret)

选项

required payload: unknown

要签名的 JWT 载荷。可以按载荷验证中的说明添加其他声明。

required secret: string

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

optional alg: AlgorithmTypes

用于 JWT 签名或验证的算法。默认值为 HS256。

verify()

此函数检查 JWT 令牌是否真实且仍然有效。它确保令牌未被篡改，并且只有添加了载荷验证相关字段时，才检查相应有效性。

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

示例

import { verify } from 'hono/jwt'

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

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

选项

required token: string

要验证的 JWT 令牌。

required secret: string

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

required alg: AlgorithmTypes

用于 JWT 签名或验证的算法。

optional issuer: string | RegExp

JWT 验证时预期的签发者。

optional aud: string | string[] | RegExp

JWT 验证时预期的受众。设置此选项后，令牌必须包含 aud 声明，并且至少有一个受众值匹配。

decode()

此函数解码 JWT 令牌而不验证签名，提取并返回令牌的头部和载荷。

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

示例

import { decode } from 'hono/jwt'

// Decode the JWT token
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 令牌的头部和载荷。这对于调试或从 JWT 令牌中提取信息很有用。

载荷验证

验证 JWT 令牌时，会执行以下载荷验证：

• exp：确保令牌尚未过期。
• nbf：确保令牌没有在指定时间之前使用。
• iat：确保令牌的签发时间不在未来。
• iss：确保令牌由可信的签发者签发。
• aud：设置 aud 验证参数时，确保令牌面向可接受的受众。

如果希望验证时执行这些检查，请确保 JWT 载荷为对象，且包含这些字段。

自定义错误类型

此模块还定义了用于处理 JWT 相关错误的自定义错误类型。

• JwtAlgorithmNotImplemented：请求的 JWT 算法尚未实现。
• JwtTokenInvalid：JWT 令牌无效。
• JwtTokenNotBefore：令牌在生效时间之前使用。
• JwtTokenExpired：令牌已过期。
• JwtTokenIssuedAt：令牌的 "iat" 声明不正确。
• JwtTokenIssuer：令牌的 "iss" 声明不正确。
• JwtPayloadRequiresAud：配置 aud 验证时，需要提供 aud 声明。
• JwtTokenAudience：令牌的 aud 声明与预期受众不匹配。
• JwtTokenSignatureMismatched：令牌签名不匹配。

支持的 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 及采用 SHA-256 的 MGF1 的 RSASSA-PSS
• PS384：使用 SHA-386 及采用 SHA-386 的 MGF1 的 RSASSA-PSS
• PS512：使用 SHA-512 及采用 SHA-512 的 MGF1 的 RSASSA-PSS
• ES256：使用 P-256 和 SHA-256 的 ECDSA
• ES384：使用 P-384 和 SHA-384 的 ECDSA
• ES512：使用 P-521 和 SHA-512 的 ECDSA
• EdDSA：使用 Ed25519 的 EdDSA