authia 0.3.1

# authia


[English](./README.md) | [日本語](./README.ja.md)

High-performance JWT verification library for Ed25519 using WebAssembly.

## Features


- 🚀 Fast Ed25519 JWT verification using Rust + WebAssembly
- ⚡ **v0.3.0 Optimization**: Single-pass JSON parsing for maximum performance
- 🔒 Secure by design - algorithm fixed to Ed25519
- 🌐 Universal runtime support (Node.js, Browser, Cloudflare Workers)
- 📦 Zero runtime dependencies
- 🎯 TypeScript type definitions included
- ⚡ Automatic Wasm initialization

## 📊 Benchmarks


In environments like Cloudflare Workers or Edge runtimes, **authia** provides highly efficient execution by leveraging Rust's performance and minimal memory footprint.

| Library           | Avg (ms)   | p50 (ms)   | p95 (ms)   |
| :---------------- | :--------- | :--------- | :--------- |
| **authia (WASM)** | **0.20ms** | **0.17ms** | **0.36ms** |
| jose (WebCrypto)  | 0.30ms     | 0.28ms     | 0.50ms     |

_Tested with authia v0.3.0. Node.js native `crypto` may be faster due to C++ bindings, but authia is optimized for high-throughput WASM environments._

## Installation


```bash
npm install authia
```

## Usage


The library automatically detects the environment (Node.js or Bundler/Workers) and handles WebAssembly loading.

### Access Token Verification


```typescript
import { verifyAccessToken } from "authia";

try {
  // ⚡ RECOMMENDED: Use publicKeyJwkRaw for better performance (v0.2.0+)
  const payload = await verifyAccessToken(token, {
    publicKeyJwkRaw: process.env.JWT_PUBLIC_KEY, // Raw JWK JSON string
    audience: "kapock-app",
    issuer: "https://auth.kapock.com",
  });

  console.log(`User ID: ${payload.sub}, Email: ${payload.email}`);
} catch (error) {
  console.error("Token verification failed:", error);
}
```

**Legacy (still supported, but slower):**

```typescript
// Base64-encoded JWK (backward compatible)
const payload = await verifyAccessToken(token, {
  publicKeyJwk: btoa(process.env.JWT_PUBLIC_KEY), // Requires base64 encoding
  audience: "kapock-app",
  issuer: "https://auth.kapock.com",
});
```

### Refresh Token Verification


```typescript
import { verifyRefreshToken } from "authia";

const payload = await verifyRefreshToken(token, {
  publicKeyJwkRaw: process.env.JWT_PUBLIC_KEY, // Use raw JWK for better performance
  audience: "kapock-app",
  issuer: "https://auth.kapock.com",
});

console.log(`JTI: ${payload.jti}`);
```

### Performance Tips


1. **Use `publicKeyJwkRaw`** instead of `publicKeyJwk` (2-5x faster in high-throughput scenarios)
2. **Cache your verification options** at the worker/process level
3. The library automatically caches the decoded public key internally

```typescript
// Worker-level caching example (Cloudflare Workers)
let cachedPublicKey: string | null = null;

export async function verifyToken(token: string, env: Env) {
  if (!cachedPublicKey) {
    cachedPublicKey = env.JWT_PUBLIC_KEY.trim();
  }

  return verifyAccessToken(token, {
    publicKeyJwkRaw: cachedPublicKey, // Avoid repeated trim() calls
    audience: "kapock-app",
    issuer: "https://auth.kapock.com",
  });
}
```

## Runtime Behavior


### Node.js


Verification is **synchronous**. The WebAssembly module is loaded and instantiated at startup using the optimized Node.js target.

### Cloudflare Workers / Bundlers


Verification is also **synchronous**. The library automatically handles WebAssembly instantiation during module load. The `await` in examples is supported but not strictly required for the verification itself (it returns the payload directly).

## API


See [API Documentation](./docs/api.md) for detailed information.

## License


MIT