JWT ライブラリ完全比較：jose, jsonwebtoken, jws, jwa, node-jose の実装と選定

Node.js で認証システムを構築する際、JSON Web Token (JWT) の扱いは避けて通れません。しかし、npm には類似した名前のパッケージが乱立しており、どれを選べばよいのか迷う開発者は少なくありません。

ここでは、jose、jsonwebtoken、jws、jwa、node-jose の 5 つを徹底比較します。単なる機能リストではなく、実際のコードがどう変わるか、セキュリティ面で何が違うかに焦点を当てて解説します。

🏗️ アーキテクチャの根本的な違い：高レベル vs 低レベル

まず理解すべきは、これらのライブラリが「どのレベル」の抽象化を提供しているかです。

jsonwebtoken と jose は「高レベル」ライブラリです。これらは、署名の生成、トークンの検証、有効期限のチェックまでをワンステップで処理します。

一方、jws と jwa は「低レベル」な部品です。jws は署名の作成のみを行い、有効期限のチェックなどは行いません。jwa に至っては、アルゴリズム名の文字列操作などが主な役割です。

node-jose はかつて高レベルな選択肢でしたが、現在は時代遅れとなっています。

🔐 基本的な JWT の署名と検証

最も一般的なユースケースである「トークンの発行」と「検証」を、主要な 2 つの高レベルライブラリで比較します。

jsonwebtoken の実装

長年使われてきたこのライブラリは、API が非常にシンプルです。秘密鍵を渡すだけで署名付きトークンが生成できます。

const jwt = require('jsonwebtoken');

const secret = 'my-secret-key';

// 署名 (Sign)
const token = jwt.sign(
  { userId: 123, role: 'admin' },
  secret,
  { expiresIn: '1h' }
);

// 検証 (Verify)
try {
  const decoded = jwt.verify(token, secret);
  console.log(decoded.userId); // 123
} catch (err) {
  console.error('Invalid token');
}

jose の実装

jose はより明示的で、モダンな Promise ベースの API を採用しています。鍵の扱いも厳格で、セキュリティ上のミスが減りやすい設計です。

import { SignJWT, jwtVerify } from 'jose';
import { textEncoder } from 'jose/util';

const secret = new TextEncoder().encode('my-secret-key');

// 署名 (Sign)
const token = await new SignJWT({ userId: 123, role: 'admin' })
  .setProtectedHeader({ alg: 'HS256' })
  .setExpirationTime('1h')
  .sign(secret);

// 検証 (Verify)
try {
  const { payload } = await jwtVerify(token, secret);
  console.log(payload.userId); // 123
} catch (err) {
  console.error('Invalid token');
}

比較のポイント: jsonwebtoken は同期処理のように見えますが、内部で暗号化処理を行っています。jose は非同期処理であることを明確にし、アルゴリズムをヘッダーで明示的に指定させることで、アルゴリズム混在攻撃（Algorithm Confusion Attack）を防ぐ設計になっています。

🔒 低レベルライブラリの役割：jws と jwa

なぜ jws や jwa といったライブラリが存在するのでしょうか？それは、JWT の仕組みを完全にコントロールしたい場合や、独自のプロトコルを構築する必要がある場合です。

jws の実装

jws は、JWT の「署名部分」のみを作成・検証します。ペイロードの中身や有効期限（exp）のチェックは行いません。

const jws = require('jws');

// 署名の作成
const signature = jws.sign({
  header: { alg: 'HS256' },
  payload: { userId: 123 },
  secret: 'my-secret-key'
});

// 署名の検証（中身のチェックはしない）
const isValid = jws.verify(signature, 'HS256', 'my-secret-key');

if (isValid) {
  const decoded = jws.decode(signature); // ペイロードを取り出すだけ
  console.log(decoded.payload);
}

このように、jws を使うと「有効期限が切れていても署名が合っていれば true を返す」ため、認証ロジックを自分で全て書く必要があります。通常のプロダクションコードでは、このライブラリを直接使用することは稀です。

jwa の実装

jwa は、アルゴリズム名の正規化など、極めて基礎的な処理を行います。例えば、RS256 と rsa-sha2-256 のような表記ゆれを吸収する際などに使われます。

const jwa = require('jwa');

// アルゴリズムエイリアスの解決
const algo = jwa('RS256');
console.log(algo.algorithm); // 'RS256'

// 通常、開発者が直接呼び出す機会はほとんどありません
// 他のライブラリ内部で使用されることが多いです

📦 暗号化トークン (JWE) の扱い

JWT には、署名だけでなく「暗号化」されたタイプ（JWE）があります。機密情報をトークン自体に含めたい場合に必要です。

node-jose の現状と限界

かつて node-jose は、Node.js で JWE を扱うための数少ない選択肢でした。

// 【非推奨】node-jose の例
const jose = require('node-jose');

// 鍵の準備と暗号化
jose.JWK.createKeyStore().then((keystore) => {
  return keystore.generate('oct', 256).then((key) => {
    return jose.JWE.createEncrypt({ format: 'compact' }, key)
      .update(JSON.stringify({ data: 'secret' }))
      .final();
  });
});

しかし、このライブラリは更新が止まっており、セキュリティのパッチも適用されていません。新しいプロジェクトで node-jose を選ぶべきではありません。

jose による JWE 実装

現代の正解は jose です。JWE の作成も JWT と同様にモダンな API で処理できます。

import { CompactEncrypt } from 'jose';
import { generateSecret } from 'jose/util';

// 対称鍵の生成
const secret = await generateSecret('A256GCM');

// 暗号化 (Encrypt)
const encryptedToken = await new CompactEncrypt(
  new TextEncoder().encode(JSON.stringify({ data: 'secret' }))
)
  .setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })
  .encrypt(secret);

console.log(encryptedToken);
// 結果は JWE 形式の文字列になります

jose は JWE だけでなく、JWK（JSON Web Key）のインポート・エクスポートも容易に扱えるため、鍵管理システムとの連携もスムーズです。

🌐 環境対応：Node.js とブラウザ

アーキテクチャを決定する際、どこでコードを動かすかは重要です。

jsonwebtoken は Node.js 固有の機能を使っているため、ブラウザ（React や Vue のフロントエンドコード内など）で動かすことはできません。一方、jose は Web Crypto API を活用しているため、サーバーとクライアントで同じライブラリを共有できます。

⚠️ セキュリティとメンテナンス状況

選択を誤ると、セキュリティリスクに直結します。

1. node-jose: メンテナンス終了。既知の脆弱性が放置されている可能性があります。即刻移行を検討してください。
2. jsonwebtoken: 広く使われていますが、機能追加はほぼ停止しており、バグフィックス中心のメンテナンスモードです。アルゴリズムの指定を怠るとセキュリティホールになる過去の実装方針でした。
3. jose: 現在最もアクティブに開発されており、最新の仕様を追従しています。デフォルトで安全な設定が多く、誤用を防ぐ設計になっています。

💡 実戦的な選定ガイド

実際のプロジェクトでは、以下のように判断するのが賢明です。

シナリオ A: 新規の認証システム構築

→ jose 一択です。 ブラウザとサーバーでコードを共有でき、JWE への拡張も容易です。将来のセキュリティ要件の変化にも柔軟に対応できます。

シナリオ B: 既存システムの保守

→ jsonwebtoken のまま維持するか、段階的に jose へ移行。 すぐに書き換える必要はありませんが、新規機能追加時には jose を導入し、徐々に置き換えるのが現実的です。

シナリオ C: 独自のトークンフォーマット開発

→ jws を検討。 標準的な JWT のルールに縛られず、ヘッダーやペイロードの構造を完全にカスタマイズする場合のみ使用します。

📊 機能比較サマリー

🎯 結論

迷ったら jose を使ってください。それは単に「新しいから」ではなく、セキュリティ設計が現代的であり、ブラウザ環境も含めた幅広いユースケースをカバーしているからです。

jsonwebtoken は過去の資産として尊重しつつ、node-jose は過去のものとしてアーカイブに送る。これが、2024 年以降の Node.js エコシステムにおける正しい立ち位置です。低レベルな jws や jwa は、本当に必要な時が来るまで、その存在を頭の片隅に置いておくだけで十分でしょう。