JWT 插件

¥JWT Plugin

此插件添加了在 Elysia 处理程序中使用 JWT 的支持。

¥This plugin adds support for using JWT in Elysia handlers.

使用以下工具安装：

¥Install with:

bun add @elysiajs/jwt

然后使用它：

¥Then use it:

cookie

import { Elysia } from 'elysia'
import { jwt } from '@elysiajs/jwt'

const app = new Elysia()
    .use(
        jwt({
            name: 'jwt',
            secret: 'Fischl von Luftschloss Narfidort'
        })
    )
    .get('/sign/:name', async ({ jwt, params: { name }, cookie: { auth } }) => {
    	const value = await jwt.sign({ name })

        auth.set({
            value,
            httpOnly: true,
            maxAge: 7 * 86400,
            path: '/profile',
        })

        return `Sign in as ${value}`
    })
    .get('/profile', async ({ jwt, status, cookie: { auth } }) => {
        const profile = await jwt.verify(auth.value)

        if (!profile)
            return status(401, 'Unauthorized')

        return `Hello ${profile.name}`
    })
    .listen(3000)

headers

import { Elysia } from 'elysia'
import { jwt } from '@elysiajs/jwt'

const app = new Elysia()
    .use(
        jwt({
            name: 'jwt',
            secret: 'Fischl von Luftschloss Narfidort'
        })
    )
    .get('/sign/:name', ({ jwt, params: { name } }) => {
    	return jwt.sign({ name })
    })
    .get('/profile', async ({ jwt, error, headers: { authorization } }) => {
        const profile = await jwt.verify(authorization)

        if (!profile)
            return status(401, 'Unauthorized')

        return `Hello ${profile.name}`
    })
    .listen(3000)

配置

¥Config

此插件扩展了 jose 的配置。

¥This plugin extends config from jose.

以下是插件接受的配​​置。

¥Below is a config that is accepted by the plugin.

name

将 jwt 函数注册为的名称。

¥Name to register jwt function as.

例如，jwt 函数将使用自定义名称注册。

¥For example, jwt function will be registered with a custom name.

app
    .use(
        jwt({
            name: 'myJWTNamespace',
            secret: process.env.JWT_SECRETS!
        })
    )
    .get('/sign/:name', ({ myJWTNamespace, params }) => {
        return myJWTNamespace.sign(params)
    })

由于某些开发者可能需要在单个服务器中使用具有不同配置的多个 jwt，因此需要使用不同的名称显式注册 JWT 函数。

¥Because some might need to use multiple jwt with different configs in a single server, explicitly registering the JWT function with a different name is needed.

secret

用于签署 JWT 有效负载的私钥。

¥The private key to sign JWT payload with.

schema

对 JWT 负载进行严格类型验证。

¥Type strict validation for JWT payload.

---

以下是从 cookie 扩展的配置。

¥Below is a config that extends from cookie

alg

@default HS256

用于签名 JWT 有效负载的签名算法。

¥Signing Algorithm to sign JWT payload with.

jose 的可能属性包括：HS256 HS384 HS512 PS256 PS384 PS512 RS256 RS384 RS512 ES256 ES256K ES384 ES512 EdDSA

¥Possible properties for jose are: HS256 HS384 HS512 PS256 PS384 PS512 RS256 RS384 RS512 ES256 ES256K ES384 ES512 EdDSA

iss

颁发者声明根据 RFC7519 标识颁发 JWT 的主体

¥The issuer claim identifies the principal that issued the JWT as per RFC7519

TLDR;通常是签名者的（域名）。

¥TLDR; is usually (the domain) name of the signer.

sub

主体声明标识了 JWT 的主体。

¥The subject claim identifies the principal that is the subject of the JWT.

JWT 中的声明通常是根据 RFC7519 定义的关于主题的陈述。

¥The claims in a JWT are normally statements about the subject as per RFC7519

aud

受众声明标识了 JWT 的目标接收者。

¥The audience claim identifies the recipients that the JWT is intended for.

每个打算处理 JWT 的主体都必须根据 RFC7519 在受众声明中使用一个值来标识自己。

¥Each principal intended to process the JWT MUST identify itself with a value in the audience claim as per RFC7519

jti

JWT ID 声明根据 RFC7519 为 JWT 提供唯一标识符

¥JWT ID claim provides a unique identifier for the JWT as per RFC7519

nbf

"不在此之前" 声明标识根据 RFC7519 规定，在此时间之前不得接受 JWT 进行处理。

¥The "not before" claim identifies the time before which the JWT must not be accepted for processing as per RFC7519

exp

到期时间声明标识了 JWT 的到期时间或之后，根据 RFC7519 规定，JWT 不得被接受处理。

¥The expiration time claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing as per RFC7519

iat

"发布于" 声明标识 JWT 的签发时间。

¥The "issued at" claim identifies the time at which the JWT was issued.

此声明可用于根据 RFC7519 确定 JWT 的生存期。

¥This claim can be used to determine the age of the JWT as per RFC7519

b64

此 JWS 扩展标头参数根据 RFC7797 修改了 JWS 有效负载表示和 JWS 签名输入计算。

¥This JWS Extension Header Parameter modifies the JWS Payload representation and the JWS Signing input computation as per RFC7797.

kid

指示用于保护 JWS 的密钥的提示。

¥A hint indicating which key was used to secure the JWS.

此参数允许发起者根据 RFC7515 明确向接收者发出密钥更改信号。

¥This parameter allows originators to explicitly signal a change of key to recipients as per RFC7515

x5t

(X.509 证书 SHA-1 指纹) 标头参数是一个 base64url 编码的 SHA-1 摘要，该摘要是对 X.509 证书 RFC5280 的 DER 编码进行编码，该证书或证书链与用于按照 RFC7515 对 JWS 进行数字签名的密钥相对应

¥(X.509 certificate SHA-1 thumbprint) header parameter is a base64url-encoded SHA-1 digest of the DER encoding of the X.509 certificate RFC5280 corresponding to the key used to digitally sign the JWS as per RFC7515

x5c

(X.509 证书链) 标头参数包含用于按照 RFC7515 对 JWS 进行数字签名的密钥对应的 X.509 公钥证书或证书链 RFC5280

¥(X.509 certificate chain) header parameter contains the X.509 public key certificate or certificate chain RFC5280 corresponding to the key used to digitally sign the JWS as per RFC7515

x5u

(X.509 URL) 标头参数是一个 URI RFC3986，它指向一个 X.509 公钥证书或证书链 [RFC5280] 资源，该证书或证书链与用于按照 RFC7515 对 JWS 进行数字签名的密钥相对应

¥(X.509 URL) header parameter is a URI RFC3986 that refers to a resource for the X.509 public key certificate or certificate chain [RFC5280] corresponding to the key used to digitally sign the JWS as per RFC7515

jwk

"jku"（JWK 设置 URL）标头参数是一个 URI [RFC3986]，它指向一组 JSON 编码公钥的资源，其中一个公钥对应于用于对 JWS 进行数字签名的密钥。

¥The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that refers to a resource for a set of JSON-encoded public keys, one of which corresponds to the key used to digitally sign the JWS.

密钥必须根据 RFC7515 编码为 JWK 集 [JWK]

¥The keys MUST be encoded as a JWK Set [JWK] as per RFC7515

typ

JWS 应用使用 typ（类型）标头参数来声明此完整 JWS 的媒体类型 [IANA.MediaTypes]。

¥The typ (type) Header Parameter is used by JWS applications to declare the media type [IANA.MediaTypes] of this complete JWS.

这旨在供应用使用，当根据 RFC7515 可以包含 JWS 的应用数据结构中可能存在多种类型的对象时。

¥This is intended for use by the application when more than one kind of object could be present in an application data structure that can contain a JWS as per RFC7515

ctr

JWS 应用使用 Content-Type 参数来声明受保护内容（有效负载）的媒体类型 [IANA.MediaTypes]。

¥Content-Type parameter is used by JWS applications to declare the media type [IANA.MediaTypes] of the secured content (the payload).

这旨在供应用使用，当根据 RFC7515 可以包含 JWS 有效负载中可能存在多种类型的对象时。

¥This is intended for use by the application when more than one kind of object could be present in the JWS Payload as per RFC7515

处理程序

¥Handler

以下是添加到处理程序的值。

¥Below are the value added to the handler.

jwt.sign

JWT 插件注册的与 JWT 一起使用的动态集合对象。

¥A dynamic object of collection related to use with JWT registered by the JWT plugin.

类型：

¥Type:

sign: (payload: JWTPayloadSpec): Promise<string>

JWTPayloadSpec 接受与 JWT 配置 相同的值

¥JWTPayloadSpec accepts the same value as JWT config

jwt.verify

使用提供的 JWT 配置验证有效负载

¥Verify payload with the provided JWT config

类型：

¥Type:

verify(payload: string) => Promise<JWTPayloadSpec | false>

JWTPayloadSpec 接受与 JWT 配置 相同的值

¥JWTPayloadSpec accepts the same value as JWT config

模式

¥Pattern

以下是使用该插件的常见模式。

¥Below you can find the common patterns to use the plugin.

设置 JWT 过期日期

¥Set JWT expiration date

默认情况下，配置将传递给 setCookie 并继承其值。

¥By default, the config is passed to setCookie and inherits its value.

const app = new Elysia()
    .use(
        jwt({
            name: 'jwt',
            secret: 'kunikuzushi',
            exp: '7d'
        })
    )
    .get('/sign/:name', async ({ jwt, params }) => jwt.sign(params))

这将对 JWT 进行签名，其有效期为未来 7 天。

¥This will sign JWT with an expiration date of the next 7 days.