# authia
WebAssemblyを使用した高性能なEd25519 JWT検証ライブラリ
## 特徴
- 🚀 Rust + WebAssemblyによる高速なEd25519 JWT検証
- ⚡ **v0.3.0 最適化**: 同期的なシングルパスJSONパースによる最高速のパフォーマンス
- 🔒 セキュアな設計 - アルゴリズムはEd25519に固定
- 🌐 ユニバーサルランタイム対応（Node.js、ブラウザ、Cloudflare Workers）
- 📦 ランタイム依存なし
- 🎯 TypeScript型定義を同梱
- ⚡ 自動的なWasm初期化
## 📊 ベンチマーク
パフォーマンスは実行環境によって大きく異なります：
**Cloudflare Workers / エッジランタイム:**
| **authia (WASM)** | **0.20ms** | **0.17ms** | **0.36ms** |
| jose (WebCrypto) | 0.30ms | 0.28ms | 0.50ms |
**Node.js (ネイティブcrypto):**
| jose (native) | **0.01-0.03ms** ⚡ |
| authia (WASM) | 0.17-0.20ms |
_Node.jsでは、joseはネイティブC++暗号バインディングを使用するため大幅に高速です。authiaは両方のライブラリが同様のAPIを使用するエッジランタイムに最適化されています。_
## インストール
```bash
npm install authia
```
## 使い方
ライブラリは環境（Node.jsまたはBundler/Workers）を自動検出し、WebAssemblyの読み込みを処理します。
### アクセストークンの検証
```typescript
import { verifyAccessToken } from "authia";
try {
// ⚡ 推奨: publicKeyJwkRawでパフォーマンス向上 (v0.2.0+)
const payload = await verifyAccessToken(token, {
publicKeyJwkRaw: process.env.JWT_PUBLIC_KEY, // 生のJWK JSON文字列
audience: "kapock-app",
issuer: "https://auth.kapock.com",
});
console.log(`ユーザーID: ${payload.sub}, メール: ${payload.email}`);
} catch (error) {
console.error("トークン検証失敗:", error);
}
```
**レガシー（サポート継続、ただし低速）:**
```typescript
// Base64エンコードされたJWK（後方互換性）
const payload = await verifyAccessToken(token, {
publicKeyJwk: btoa(process.env.JWT_PUBLIC_KEY), // Base64エンコードが必要
audience: "kapock-app",
issuer: "https://auth.kapock.com",
});
```
### リフレッシュトークンの検証
```typescript
import { verifyRefreshToken } from "authia";
const payload = await verifyRefreshToken(token, {
publicKeyJwkRaw: process.env.JWT_PUBLIC_KEY, // 生JWKでパフォーマンス向上
audience: "kapock-app",
issuer: "https://auth.kapock.com",
});
console.log(`JTI: ${payload.jti}`);
```
### パフォーマンスのコツ
1. **`publicKeyJwkRaw`を使用**：`publicKeyJwk`より2〜5倍高速（高スループットシナリオ）
2. **検証オプションをWorker/プロセスレベルでキャッシュ**
3. ライブラリ内部で自動的に公開鍵をキャッシュ
```typescript
// Worker-levelキャッシングの例（Cloudflare Workers）
export async function verifyToken(token: string, env: Env) {
if (!cachedPublicKey) {
cachedPublicKey = env.JWT_PUBLIC_KEY.trim();
}
return verifyAccessToken(token, {
publicKeyJwkRaw: cachedPublicKey, // 繰り返しのtrim()呼び出しを回避
audience: "kapock-app",
issuer: "https://auth.kapock.com",
});
}
```
## ランタイムの動作
### Node.js
検証は**同期的**です。WebAssemblyモジュールは、起動時に最適化されたNode.jsターゲットとして読み込まれ、インスタンス化されます。
### Cloudflare Workers / バンドラー
検証も**同期的**です。ライブラリは、モジュールのロード時にWebAssemblyのインスタンス化を自動的に処理します。例にある `await` は互換性のために維持されていますが、検証自体はペイロードを直接返します。
## API
詳細は[APIドキュメント](./docs/api.md)を参照してください。
## 既知の問題と制限事項
⚠️ **本番環境での使用に関する重要な注意事項**
### パフォーマンスに関する考慮事項
**Node.js環境:**
- authiaには **JS ↔ WASM境界のオーバーヘッド** が1回あたり約0.1-0.15ms発生します
- 人気の`jose`ライブラリはネイティブC++暗号バインディングを使用し、通常**Node.jsではより高速**です（0.01-0.03ms）
- **推奨**: Node.jsバックエンドでは、authiaの代わりに`jose`の使用を検討してください
**Cloudflare Workers / エッジランタイム:**
- authiaはこれらの環境で**競争力のあるパフォーマンス**を発揮します（`jose`もWebCrypto APIを使用するため）
- WASMアプローチは異なるエッジプラットフォーム間で**一貫したパフォーマンス**を提供します
- **推奨**: authiaはEd25519トークンを使用するCloudflare Workersに適しています
### スキーマ検証（v0.3.x）
- **厳格なスキーマ検証**: v0.3.1-v0.3.3はJWTクレームに対して厳格な型チェックを使用します
- オプションフィールド（`email`など）が欠けていると検証が失敗する可能性があります
- **回避策**: すべてのトークンに期待されるフィールドが含まれていることを確認するか、より寛容なパースのためにv0.2.xを使用してください
- **今後の改善**: `Option<T>`型を使用した柔軟なスキーマへの移行を計画中です
### 環境変数のパース
- 公開鍵形式の検出: ライブラリはJSONとBase64エンコードされたJWKを自動検出しようとします
- **ベストプラクティス**: `publicKeyJwkRaw`オプションには生のJSON形式を使用してください（推奨）
- Base64を使用する場合は、PEMヘッダーなしで適切にエンコードされていることを確認してください
### 推奨される使用ケース
✅ **適している場合:**
- Ed25519 JWTトークンを使用するCloudflare Workers
- 一貫したクロスプラットフォーム動作が必要なエッジランタイム
- Rust + WebAssembly開発の学習
❌ **代替案を検討すべき場合:**
- 高スループット要件のあるNode.jsバックエンド → `jose`を使用
- クレーム構造が変動するトークン → v0.2.xまたは`jose`を使用
- 最大限の安定性が必要な本番システム → `jose`を使用
## ライセンス
MIT