flare.http.auth_extract

The :mod:flare.http.auth module ships BasicAuth and BearerAuth for the client side — they apply credentials to an outbound request's Authorization header.

This module provides the symmetric server-side primitives:

• BearerExtract — pulls the Bearer token out of the inbound request's Authorization header and exposes it to handlers via the Extractor trait (drop-in for Extracted[H]).
• BasicExtract — decodes the inbound Basic credentials (Authorization: Basic <base64-username:password>) into username / password strings.
• parse_bearer_token / parse_basic_credentials — the underlying parsers, exposed for callers who want to assemble their own auth flow without going through Extracted.
• CsrfToken — encode / verify constant-time comparison for double-submit-cookie CSRF protection (OWASP Cheat Sheet §3.1.1, "Double Submit Cookie pattern").

Why server-side parsers, separate from the client-side applicators:

• An HttpServer handler that needs to authenticate the caller has to parse an Authorization header, not write one. The BasicAuth.apply shape doesn't fit (writes vs reads are different operations on the same header name).
• Symmetry with the existing Header[T, name] extractor pattern: callers who put var token: BearerExtract on their Extracted[H] struct get the same auto-injection semantics they get for path / query / header extractors.
• CSRF lives here because every server-side auth pattern needs it (or needs to deliberately opt out of it). Bundling it with the auth extractors keeps the surface tight and the imports obvious.

Spec compliance:

• BearerExtract follows RFC 6750 §2.1: token = b64token per the Augmented BNF, which permits A-Z a-z 0-9 - . _ ~ + / and trailing = padding. We pass the token through verbatim — the resource server is responsible for token introspection / signature verification.
• BasicExtract follows RFC 7617 §2: user-pass = userid ":" password after base64 decode, where userid may not contain : but password may. We split on the first : only.
• CsrfToken follows OWASP guidance: 32-byte random token, base64url-encoded, constant-time compare. Token generation uses urandom-fed bytes (caller responsibility — we accept the bytes; we don't seed a PRNG ourselves so the randomness contract stays explicit).

Error handling:

The parsers (parse_bearer_token, parse_basic_credentials, _b64_decode) raise the typed :class:AuthError so callers can pattern-match on the failure mode:

from flare.http import unauthorized, bad_request
from flare.http.auth_extract import parse_bearer_token, AuthError

try:
    var tok = parse_bearer_token(req.headers.get("authorization"))
except e:
    if e == AuthError.MISSING_HEADER:
        return unauthorized("login required")
    elif e == AuthError.WRONG_SCHEME:
        return bad_request("Bearer required")

When a BearerExtract / BasicExtract is used as an Extracted[H] field, the framework does this mapping for you: a raised :class:AuthError becomes a sanitized 401 Unauthorized with a WWW-Authenticate: Bearer challenge (see flare.http.extract._extractor_error_response).

The BearerExtract / BasicExtract extractors keep the :class:flare.http.extract.Extractor trait's bare-raises shape (the trait is widely implemented across path / query / header extractors and changing it would break every impl), but the :class:AuthError raised inside is preserved by the Mojo runtime — calling String(e) on the caught error still produces the typed AuthError(VARIANT): detail rendering.

struct AuthError

comptime MISSING_HEADER = AuthError(Int(1), String(""))

comptime EMPTY_VALUE = AuthError(Int(2), String(""))

comptime TOO_SHORT = AuthError(Int(3), String(""))

comptime WRONG_SCHEME = AuthError(Int(4), String(""))

comptime EMPTY_TOKEN = AuthError(Int(5), String(""))

comptime B64_BAD_LENGTH = AuthError(Int(6), String(""))

comptime B64_TOO_MUCH_PADDING = AuthError(Int(7), String(""))

comptime B64_INVALID_CHAR = AuthError(Int(8), String(""))

comptime B64_PADDING_BEFORE_TAIL = AuthError(Int(9), String(""))

comptime MISSING_SEPARATOR = AuthError(Int(10), String(""))

def __eq__(self, other: Self) -> Bool

def __ne__(self, other: Self) -> Bool

def variant_name(self) -> String

def write_to[W: Writer](self, mut writer: W)

struct BasicCredentials

struct BearerExtract

def __init__(out self)

def apply(mut self, req: Request)

def extract(req: Request) -> Self

struct BasicExtract

def __init__(out self)

def apply(mut self, req: Request)

def extract(req: Request) -> Self

struct CsrfToken

def verify(self) -> Bool

def parse_bearer_token(authz: String) -> String

def parse_basic_credentials(authz: String) -> BasicCredentials

def csrf_token_b64url(token_bytes: List[UInt8]) -> String

def new_csrf_token() -> String

def csrf_token_compare(a: String, b: String) -> Bool

comptime CSRF_TOKEN_MIN_CHARS = Int(16)