> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Bearer Auth

> Bearer token authentication middleware for API protection.

## Overview

The `bearerauth` middleware validates Bearer tokens from the `Authorization` header. It's commonly used for API authentication with JWTs, OAuth tokens, or custom tokens.

Use it when you need:

* API authentication with tokens
* JWT validation
* OAuth 2.0 Bearer token protection
* Custom token authentication

## Installation

```go theme={null}
import "github.com/go-mizu/mizu/middlewares/bearerauth"
```

## Quick Start

```go theme={null}
app := mizu.New()

// Simple token validation
app.Use(bearerauth.New(func(token string) bool {
    return token == "my-secret-token"
}))
```

## Configuration

### Options

| Option                 | Type                           | Default           | Description                  |
| ---------------------- | ------------------------------ | ----------------- | ---------------------------- |
| `Validator`            | `TokenValidator`               | -                 | Validates the token          |
| `ValidatorWithContext` | `TokenValidatorWithContext`    | -                 | Validates and returns claims |
| `Header`               | `string`                       | `"Authorization"` | Header to read token from    |
| `AuthScheme`           | `string`                       | `"Bearer"`        | Expected auth scheme prefix  |
| `ErrorHandler`         | `func(*mizu.Ctx, error) error` | -                 | Custom error handler         |

### Validator Types

```go theme={null}
// Simple validator
type TokenValidator func(token string) bool

// Validator that returns claims
type TokenValidatorWithContext func(token string) (claims any, valid bool)
```

## Examples

### Simple Token Validation

```go theme={null}
validTokens := map[string]bool{
    "token-1": true,
    "token-2": true,
}

app.Use(bearerauth.New(func(token string) bool {
    return validTokens[token]
}))
```

### JWT Validation with Claims

```go theme={null}
type UserClaims struct {
    UserID   string
    Username string
    Role     string
}

app.Use(bearerauth.WithOptions(bearerauth.Options{
    ValidatorWithContext: func(token string) (any, bool) {
        // Parse and validate JWT
        claims, err := parseJWT(token)
        if err != nil {
            return nil, false
        }
        return &UserClaims{
            UserID:   claims["sub"].(string),
            Username: claims["username"].(string),
            Role:     claims["role"].(string),
        }, true
    },
}))

// Access claims in handler
func protectedHandler(c *mizu.Ctx) error {
    claims, ok := bearerauth.Claims[*UserClaims](c)
    if !ok {
        return c.Text(401, "Unauthorized")
    }
    return c.JSON(200, map[string]string{
        "user": claims.Username,
        "role": claims.Role,
    })
}
```

### Custom Header

```go theme={null}
// Use X-API-Token instead of Authorization
app.Use(bearerauth.WithHeader("X-API-Token", func(token string) bool {
    return validateToken(token)
}))
```

### Custom Auth Scheme

```go theme={null}
// Use "Token" instead of "Bearer"
app.Use(bearerauth.WithOptions(bearerauth.Options{
    AuthScheme: "Token",
    Validator: func(token string) bool {
        return validateToken(token)
    },
}))
```

### Custom Error Handler

```go theme={null}
app.Use(bearerauth.WithOptions(bearerauth.Options{
    Validator: validateToken,
    ErrorHandler: func(c *mizu.Ctx, err error) error {
        switch err {
        case bearerauth.ErrTokenMissing:
            return c.JSON(401, map[string]string{
                "error": "Authentication required",
            })
        case bearerauth.ErrTokenInvalid:
            return c.JSON(403, map[string]string{
                "error": "Invalid token",
            })
        default:
            return c.JSON(401, map[string]string{
                "error": err.Error(),
            })
        }
    },
}))
```

### Database Token Lookup

```go theme={null}
app.Use(bearerauth.WithOptions(bearerauth.Options{
    ValidatorWithContext: func(token string) (any, bool) {
        // Look up token in database
        session, err := db.GetSession(token)
        if err != nil || session.IsExpired() {
            return nil, false
        }

        // Return user info as claims
        return &UserInfo{
            ID:    session.UserID,
            Email: session.UserEmail,
        }, true
    },
}))
```

## API Reference

### Functions

```go theme={null}
// New creates middleware with simple validator
func New(validator TokenValidator) mizu.Middleware

// WithHeader creates middleware reading from custom header
func WithHeader(header string, validator TokenValidator) mizu.Middleware

// WithOptions creates middleware with full configuration
func WithOptions(opts Options) mizu.Middleware
```

### Extracting Data

```go theme={null}
// FromContext extracts token or claims
func FromContext(c *mizu.Ctx) any

// Token extracts the token string
func Token(c *mizu.Ctx) string

// Claims extracts typed claims (generic)
func Claims[T any](c *mizu.Ctx) (T, bool)
```

### Error Types

```go theme={null}
var (
    ErrTokenMissing  // Token not found in request
    ErrTokenInvalid  // Token validation failed
    ErrInvalidScheme // Auth scheme doesn't match
)
```

## Technical Details

### Implementation Overview

The bearerauth middleware implements Bearer token authentication following RFC 6750 standards. It extracts and validates tokens from HTTP headers, storing the token or associated claims in the request context for downstream handlers.

### Core Components

1. **Token Extraction**: The middleware reads the configured header (default: "Authorization") and extracts the token after the auth scheme prefix (default: "Bearer ").

2. **Validation Flow**:
   * Checks if the authorization header exists
   * Verifies the auth scheme matches the configured scheme
   * Extracts the token after removing the scheme prefix
   * Invokes either `Validator` or `ValidatorWithContext` to validate the token
   * Stores the token or claims in the request context using a private context key

3. **Context Storage**: The middleware uses a private `contextKey` struct to store authentication data in the request context. This prevents key collisions with other middleware or application code.

4. **Error Handling**: Three error types are defined:
   * `ErrTokenMissing`: Returned when no token is found (401 Unauthorized)
   * `ErrInvalidScheme`: Returned when auth scheme doesn't match (403 Forbidden)
   * `ErrTokenInvalid`: Returned when validation fails (403 Forbidden)

### Validator Types

* **TokenValidator**: Simple boolean validation for basic token checking
* **TokenValidatorWithContext**: Returns claims along with validation result, enabling stateful authentication with user data

### Data Retrieval

Three helper functions extract authentication data from context:

* `FromContext(c)`: Returns raw token or claims (type `any`)
* `Token(c)`: Returns token string (only when using `Validator`)
* `Claims[T](c)`: Type-safe claims extraction (when using `ValidatorWithContext`)

## Security Considerations

1. **Token Security** - Use cryptographically secure tokens
2. **HTTPS Required** - Always use HTTPS to protect tokens in transit
3. **Token Expiration** - Implement token expiration
4. **Secure Storage** - Store tokens securely on the client
5. **Revocation** - Implement token revocation for logout/security

## Best Practices

* Use short-lived tokens with refresh tokens for better security
* Validate token claims (expiration, issuer, audience)
* Log authentication failures for security monitoring
* Consider rate limiting failed attempts

## Testing

The bearerauth middleware includes comprehensive test coverage for all authentication scenarios:

| Test Case                                            | Description                                          | Expected Behavior                                           |
| ---------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------- |
| `TestNew/allows_valid_token`                         | Valid Bearer token in Authorization header           | Returns 200 OK and allows access to protected resource      |
| `TestNew/rejects_invalid_token`                      | Invalid Bearer token provided                        | Returns 403 Forbidden                                       |
| `TestNew/rejects_missing_token`                      | No Authorization header present                      | Returns 401 Unauthorized                                    |
| `TestNew/rejects_wrong_scheme`                       | Authorization header with wrong scheme (e.g., Basic) | Returns 403 Forbidden                                       |
| `TestWithHeader`                                     | Custom header name (X-Api-Token) with valid token    | Returns 200 OK when token is valid                          |
| `TestWithOptions_ValidatorWithContext`               | ValidatorWithContext returns user claims             | Claims are stored in context and accessible via FromContext |
| `TestWithOptions_ErrorHandler`                       | Custom error handler for authentication failures     | Custom error handler is invoked with proper error           |
| `TestWithOptions_CustomScheme/accepts_custom_scheme` | Custom auth scheme "Token" instead of "Bearer"       | Returns 200 OK for matching scheme                          |
| `TestWithOptions_CustomScheme/rejects_bearer_scheme` | Bearer scheme when Token scheme is configured        | Returns 403 Forbidden for mismatched scheme                 |
| `TestToken`                                          | Token extraction using Token() helper                | Token string is correctly extracted from context            |
| `TestWithOptions_Panics`                             | Creating middleware without validator                | Panics with appropriate message                             |
| `TestClaims`                                         | Type-safe claims extraction using Claims[T]()        | Claims are properly typed and accessible                    |
| `TestErrors`                                         | Error message formatting                             | Error constants return correct messages                     |

## Related Middlewares

* [basicauth](/middlewares/basicauth) - Username/password authentication
* [keyauth](/middlewares/keyauth) - API key authentication
* [csrf](/middlewares/csrf) - CSRF protection