JWT 身份验证助手

¥JWT Authentication Helper

此辅助程序提供用于编码、解码、签名和验证 JSON Web Tokens (JWT) 的函数。JWT 通常用于 Web 应用中的身份验证和授权目的。此辅助程序提供强大的 JWT 功能，支持各种加密算法。

¥This helper provides functions for encoding, decoding, signing, and verifying JSON Web Tokens (JWTs). JWTs are commonly used for authentication and authorization purposes in web applications. This helper offers robust JWT functionality with support for various cryptographic algorithms.

导入

¥Import

要使用此辅助程序，你可以按如下方式导入它：

¥To use this helper, you can import it as follows:

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

信息

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

¥JWT Middleware also import the jwt function from the hono/jwt.

sign()

此函数通过编码有效负载并使用指定的算法和密钥对其进行签名来生成 JWT 令牌。

¥This function generates a JWT token by encoding a payload and signing it using the specified algorithm and secret.

sign(
  payload: unknown,
  secret: string,
  alg?: 'HS256';

): Promise<string>;

示例

¥Example

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)

选项

¥Options

required payload:unknown

要签名的 JWT 有效负载。你可以像在 有效负载验证 中一样包含其他声明。

¥The JWT payload to be signed. You can include other claims like in Payload Validation.

<徽章类型="danger" 文本="required" /> 秘密：string

¥required secret: string

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

¥The secret key used for JWT verification or signing.

optional alg：AlgorithmTypes

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

¥The algorithm used for JWT signing or verification. The default is HS256.

verify()

此函数检查 JWT 令牌是否真实且仍然有效。它确保令牌未被更改，并且仅在你添加 有效负载验证 时才检查有效性。

¥This function checks if a JWT token is genuine and still valid. It ensures the token hasn't been altered and checks validity only if you added Payload Validation.

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

示例

¥Example

import { verify } from 'hono/jwt'

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

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

选项

¥Options

<徽章类型="danger" 文本="required" /> 令牌：string

¥required token: string

要验证的 JWT 令牌。

¥The JWT token to be verified.

<徽章类型="danger" 文本="required" /> 秘密：string

¥required secret: string

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

¥The secret key used for JWT verification or signing.

optional alg：AlgorithmTypes

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

¥The algorithm used for JWT signing or verification. The default is HS256.

decode()

此函数解码 JWT 令牌而不执行签名验证。它从令牌中提取并返回标头和有效负载。

¥This function decodes a JWT token without performing signature verification. It extracts and returns the header and payload from the token.

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

示例

¥Example

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)

选项

¥Options

<徽章类型="danger" 文本="required" /> 令牌：string

¥required token: string

要解码的 JWT 令牌。

¥The JWT token to be decoded.

decode 函数允许你检查 JWT 令牌的标头和有效负载而无需执行验证。这对于调试或从 JWT 令牌中提取信息很有用。

¥The decode function allows you to inspect the header and payload of a JWT token without performing verification. This can be useful for debugging or extracting information from JWT tokens.

有效负载验证

¥Payload Validation

验证 JWT 令牌时，将执行以下有效负载验证：

¥When verifying a JWT token, the following payload validations are performed:

• exp：检查令牌以确保其未过期。

  ¥exp: The token is checked to ensure it has not expired.

• nbf：检查令牌以确保其未在指定时间之前被使用。

  ¥nbf: The token is checked to ensure it is not being used before a specified time.

• iat：检查令牌以确保其不会在将来发出。

  ¥iat: The token is checked to ensure it is not issued in the future.

如果你打算在验证期间执行这些检查，请确保你的 JWT 有效负载包含这些字段作为对象。

¥Please ensure that your JWT payload includes these fields, as an object, if you intend to perform these checks during verification.

自定义错误类型

¥Custom Error Types

该模块还定义了自定义错误类型来处理与 JWT 相关的错误。

¥The module also defines custom error types to handle JWT-related errors.

• JwtAlgorithmNotImplemented：表示请求的 JWT 算法未实现。

  ¥JwtAlgorithmNotImplemented: Indicates that the requested JWT algorithm is not implemented.

• JwtTokenInvalid：表示 JWT 令牌无效。

  ¥JwtTokenInvalid: Indicates that the JWT token is invalid.

• JwtTokenNotBefore：表示令牌在有效期之前使用。

  ¥JwtTokenNotBefore: Indicates that the token is being used before its valid date.

• JwtTokenExpired：表示令牌已过期。

  ¥JwtTokenExpired: Indicates that the token has expired.

• JwtTokenIssuedAt：表示令牌中的 "iat" 声明不正确。

  ¥JwtTokenIssuedAt: Indicates that the "iat" claim in the token is incorrect.

• JwtTokenSignatureMismatched：表示令牌中的签名不匹配。

  ¥JwtTokenSignatureMismatched: Indicates a signature mismatch in the token.

支持的算法类型

¥Supported AlgorithmTypes

该模块支持以下 JWT 加密算法：

¥The module supports the following JWT cryptographic algorithms:

• HS256：使用 SHA-256 的 HMAC

  ¥HS256: HMAC using SHA-256

• HS384：使用 SHA-384 的 HMAC

  ¥HS384: HMAC using SHA-384

• HS512：使用 SHA-512 的 HMAC

  ¥HS512: HMAC using SHA-512

• RS256：使用 SHA-256 的 RSASSA-PKCS1-v1_5

  ¥RS256: RSASSA-PKCS1-v1_5 using SHA-256

• RS384：使用 SHA-384 的 RSASSA-PKCS1-v1_5

  ¥RS384: RSASSA-PKCS1-v1_5 using SHA-384

• RS512：使用 SHA-512 的 RSASSA-PKCS1-v1_5

  ¥RS512: RSASSA-PKCS1-v1_5 using SHA-512

• PS256：RSASSA-PSS 使用 SHA-256 和 MGF1 使用 SHA-256

  ¥PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256

• PS384：RSASSA-PSS 使用 SHA-386 和 MGF1 使用 SHA-386

  ¥PS384: RSASSA-PSS using SHA-386 and MGF1 with SHA-386

• PS512：RSASSA-PSS 使用 SHA-512 和 MGF1 使用 SHA-512

  ¥PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512

• ES256：使用 P-256 和 SHA-256 的 ECDSA

  ¥ES256: ECDSA using P-256 and SHA-256

• ES384：使用 P-384 和 SHA-384 的 ECDSA

  ¥ES384: ECDSA using P-384 and SHA-384

• ES512：使用 P-521 和 SHA-512 的 ECDSA

  ¥ES512: ECDSA using P-521 and SHA-512

• EdDSA：使用 Ed25519 的 EdDSA

  ¥EdDSA: EdDSA using Ed25519