bearerAuth - Hono

Import

import { bearerAuth } from 'hono/bearer-auth'

Usage

const app = new Hono()

const token = 'honoishot'

app.use('/api/*', bearerAuth({ token }))

app.get('/api/page', (c) => {
  return c.json({ message: 'You are authorized' })
})

Options

The bearerAuth middleware accepts a BearerAuthOptions object:

string | string[]

The token or array of tokens to validate against. Required if verifyToken is not provided.

(token: string, c: Context) => boolean | Promise<boolean>

Custom function to verify the token. Alternative to providing static token values.

string

default:""

The domain name of the realm, as part of the returned WWW-Authenticate challenge header.

string

default:"Bearer"

The prefix (or schema) for the Authorization header value. If set to empty string, no prefix is expected.

string

default:"Authorization"

The header name to look for the token.

Function

A function to handle hashing for safe comparison of authentication tokens.

string | object | MessageFunction

default:"Unauthorized"

The message returned when no authentication header is provided.

string | object | MessageFunction

default:"Bearer realm=\"\""

The WWW-Authenticate header value when no authentication header is provided.

string | object | MessageFunction

default:"Bad Request"

The message returned when authentication header format is invalid.

string | object | MessageFunction

default:"Bearer error=\"invalid_request\""

The WWW-Authenticate header value when authentication header is invalid.

string | object | MessageFunction

default:"Unauthorized"

The message returned when token is invalid.

string | object | MessageFunction

default:"Bearer error=\"invalid_token\""

The WWW-Authenticate header value when token is invalid.

Signature

bearerAuth(options: BearerAuthOptions): MiddlewareHandler

Examples

Multiple tokens

app.use('/api/*', bearerAuth({ 
  token: ['token1', 'token2', 'token3'] 
}))

Custom token verification

app.use('/api/*', bearerAuth({
  verifyToken: async (token, c) => {
    // Verify against database or external service
    const valid = await validateTokenInDatabase(token)
    return valid
  },
}))

Custom prefix

// Use "Token" instead of "Bearer"
app.use('/api/*', bearerAuth({ 
  token: 'secret',
  prefix: 'Token'
}))

// Request header: Authorization: Token secret

No prefix

app.use('/api/*', bearerAuth({ 
  token: 'secret',
  prefix: ''
}))

// Request header: Authorization: secret

Custom error messages

app.use('/api/*', bearerAuth({
  token: 'secret',
  noAuthenticationHeader: {
    message: 'Please provide authentication',
    wwwAuthenticateHeader: 'Bearer realm="api"'
  },
  invalidToken: {
    message: { error: 'Invalid token provided' }
  }
}))

Behavior

Returns 401 Unauthorized if token is missing or invalid
Returns 400 Bad Request if Authorization header format is invalid
Sets WWW-Authenticate header with appropriate error information
Uses timing-safe comparison to prevent timing attacks
Supports custom hash functions for secure token comparison

⌘I