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 クレームが必要で、少なくとも 1 つの対象者の値が一致しなければなりません。

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