auth
JWT-based authentication middleware for Buntal applications that validates tokens from cookies or headers. Tokens are verified with HS256 only, and the decoded payload is set on req.context. Missing or invalid tokens get 401; OPTIONS preflight requests pass through. Throws at startup if the secret is empty. Use jwt(secret).sign(payload, { expiresIn }) to issue tokens.
Source
Type Definition
function auth<T = unknown>(options?: AuthOptions<T>): AtomicHandler<Record<string, string>, T>
type AuthOptions<T = unknown> = {
secret: string
strategy?: Strategy | Strategy[]
cookie?: { key: string }
header?: { key: string }
onVerified?: (req: Req<Record<string, string>, T>, res: Res, decoded: T) => void | Response | Promise<void | Response>
}
type Strategy = 'cookie' | 'header' | 'both'Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
options | AuthOptions<T> | ❌ | - | Authentication configuration options |
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
secret | string | ✅ | - | Secret key for JWT verification. Must be non-empty, e.g. process.env.JWT_SECRET |
strategy | Strategy | Strategy[] | ❌ | header | Where to read the token from. An array tries each strategy in order |
cookie | { key: string } | ❌ | { key: "access_token" } | Cookie configuration for token extraction |
header | { key: string } | ❌ | { key: "Authorization" } | Header configuration for token extraction. A Bearer prefix is optional and case-insensitive |
onVerified | function | ❌ | - | Called after successful verification with the decoded payload. Return a Response to reject the request |
Last modified: 2026-10-02