JWT 인증 헬퍼

이 헬퍼는 JSON Web Token(JWT)을 인코딩, 디코딩, 서명, 검증하는 기능을 제공한다. JWT는 웹 애플리케이션에서 인증과 권한 부여를 위해 널리 사용된다. 이 헬퍼는 다양한 암호화 알고리즘을 지원하며 강력한 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 페이로드. 페이로드 검증에서처럼 추가 클레임을 포함할 수 있다.

required secret: string

JWT 검증 또는 서명에 사용되는 비밀 키.

optional alg: AlgorithmTypes

JWT 서명 또는 검증에 사용할 알고리즘. 기본값은 HS256이다.

verify()

이 함수는 JWT 토큰이 진짜인지, 아직 유효한지 확인한다. 토큰이 변경되지 않았음을 보장하며, 페이로드 검증을 추가한 경우에만 유효성을 검사한다.

verify(
  token: string,
  secret: string,
  alg?: 'HS256';
): 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이다.

decode()

이 함수는 JWT 토큰의 서명 검증 없이 디코딩을 수행한다. 토큰에서 헤더와 페이로드를 추출하여 반환한다.

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('디코딩된 헤더:', header)
console.log('디코딩된 페이로드:', payload)

옵션

required token: string

디코딩할 JWT 토큰을 지정한다.

decode 함수는 JWT 토큰의 검증 없이 헤더와 페이로드를 확인할 수 있다. 이 기능은 디버깅이나 JWT 토큰에서 정보를 추출할 때 유용하다.

페이로드 검증

JWT 토큰을 검증할 때, 다음과 같은 페이로드 검증을 수행한다:

• exp: 토큰이 만료되지 않았는지 확인한다.
• nbf: 토큰이 지정된 시간 이전에 사용되지 않았는지 확인한다.
• iat: 토큰이 미래 시점에 발급되지 않았는지 확인한다.

이 검증을 수행하려면 JWT 페이로드에 이 필드들을 객체 형태로 포함해야 한다.

커스텀 에러 타입

이 모듈은 JWT 관련 에러를 처리하기 위한 커스텀 에러 타입도 정의한다.

• JwtAlgorithmNotImplemented: 요청한 JWT 알고리즘이 구현되지 않았음을 나타낸다.
• JwtTokenInvalid: JWT 토큰이 유효하지 않음을 나타낸다.
• JwtTokenNotBefore: 토큰이 유효한 날짜 이전에 사용되었음을 나타낸다.
• JwtTokenExpired: 토큰이 만료되었음을 나타낸다.
• JwtTokenIssuedAt: 토큰의 "iat" 클레임이 잘못되었음을 나타낸다.
• JwtTokenSignatureMismatched: 토큰의 서명이 일치하지 않음을 나타낸다.

지원하는 알고리즘 타입

이 모듈은 다음과 같은 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을 사용한 RSASSA-PSS
• PS384: SHA-386과 MGF1을 사용한 RSASSA-PSS
• PS512: 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