Orientation Arc
Routing Algorithms
Rendering and JSX
Runtime Adapters
Middleware Ecosystem
Developer Helpers
System Utilities
The following files were used as context for generating this wiki page:
Authentication middleware in Hono serves as the primary security layer for guarding routes, ensuring that incoming HTTP requests carry valid credentials before reaching the business logic. By leveraging standard Web Crypto APIs and JWT specifications, these components provide a robust, non-blocking flow that integrates seamlessly into the Hono middleware pipeline.
The architecture is designed to handle multiple common authentication patterns, including standard Bearer tokens, JSON Web Key (JWK) rotation through remote URI fetching, and static token validation. Because Hono is built on Web Standards, the middleware is platform-agnostic, running effectively across Cloudflare Workers, Node.js, Bun, and Deno, relying solely on the standard crypto.subtle API for cryptographic operations.
These components operate by inspecting headers or cookies, verifying claims against provided secrets or public keys, and either passing the request forward via or terminating execution early with an . This ensures that downstream handlers only process requests that have satisfied the authentication invariant.
next()HTTPExceptionThe core of Hono's token-based authentication lies in the Jwt utility and its corresponding middleware. It provides high-level abstractions for signing and verifying tokens, adhering to RFC 7519.
The verify function is the primary mechanism for token validation. It performs an ordered check:
.).alg matches the expected algorithm, preventing "alg: none" or algorithm confusion attacks.nbf (Not Before), exp (Expiration), and iat (Issued At) against the current time.verifying function to ensure the signature matches the signed header and payload.Caution
When using verifyWithJwks, the implementation enforces an explicit exclusion of symmetric algorithms (HS256/384/512) to prevent algorithm confusion attacks where a client might attempt to use a public key as a HMAC secret.
Sources: src/utils/jwt/jwt.ts:96-188
The jwk middleware extends the JWT functionality by supporting dynamic public key rotation, commonly required in OIDC-compliant identity providers.
When jwks_uri is provided, the middleware dynamically fetches the keyset. The mechanism involves:
kid (Key ID) from the JWT header.jwks_uri is present, performing a fetch to retrieve the JSON Web Key Set.kid from the token against the retrieved keys array.// Example: Using JWK middleware with a dynamic URI
app.use("/auth/*", jwk({
jwks_uri: (c) => `https://${c.env.authServer}/.well-known/jwks.json`,
alg: ['RS256']
}))Sources: src/middleware/jwk/jwk.ts:48-168
The bearerAuth middleware provides a simplified, non-JWT-specific token validation mechanism. It is ideal for API key-based authentication where the token itself does not need a structured payload.
It supports two validation strategies:
verifyToken function for custom logic (e.g., database lookup).The security-critical component is the timingSafeEqual function, which prevents timing attacks by performing constant-time string comparison.
// Example: Using bearer authentication with a static token
app.use('/api/*', bearerAuth({ token: 'my-secret-token' }))The ipRestriction middleware provides infrastructure-level access control by inspecting the remote IP address of incoming requests.
Mechanism:
10.0.0.0/8).buildMatcher function compiles rules into Set structures for constant-time lookup and binary masks for CIDR ranges.denyList rule matches, access is rejected. If an allowList is provided, the request must match at least one rule to proceed.Note
When allowList is provided, the middleware behaves as a whitelist-only filter. If the list is empty, it falls back to permissive behavior unless denyList rules trigger a block.
This diagram traces the standard authentication middleware sequence.