hubvault.server.auth

Token parsing and authorization helpers for hubvault.server.

This module keeps bearer-token parsing and access-level checks independent from the FastAPI app factory so the authorization policy can be tested without API extras installed.

The module contains:

AuthContext - Resolved token identity for one request
TokenAuthorizer - Read/write token resolver
parse_request_token() - Header parser for supported token inputs

AuthContext

class hubvault.server.auth.AuthContext(access: str, token: str)[source]

Resolved token identity for one request.

Parameters:

access (str) – Access level string, currently "ro" or "rw"
token (str) – Original bearer token text

property can_write: bool

Whether the token grants write access.

Returns:: True when the token carries read-write permissions
Return type:: bool

TokenAuthorizer

class hubvault.server.auth.TokenAuthorizer(token_ro, token_rw)[source]

Resolve read-only and read-write API tokens.

Parameters:

token_ro (Iterable[str]) – Read-only token values
token_rw (Iterable[str]) – Read-write token values

__init__(token_ro, token_rw) → None[source]

Build one token authorizer from normalized token collections.

Parameters:

token_ro (Iterable[str]) – Read-only token values
token_rw (Iterable[str]) – Read-write token values

Returns:

None.

Return type:

None

require_write(context: AuthContext) → AuthContext[source]

Ensure the current token grants write access.

Parameters:: context (AuthContext) – Previously resolved authorization context
Returns:: The same authorization context when write access is allowed
Return type:: AuthContext
Raises:: PermissionError – Raised when the token is read-only.

resolve(token: str | None) → AuthContext[source]

Resolve one raw token into an AuthContext.

Parameters:: token (Optional[str]) – Raw token string extracted from the request
Returns:: Resolved authorization context
Return type:: AuthContext
Raises:: PermissionError – Raised when the token is missing or invalid.

parse_request_token

hubvault.server.auth.parse_request_token(authorization: str | None = None, x_hubvault_token: str | None = None, query_token: str | None = None) → str | None[source]

Extract a token from supported request inputs.

X-HubVault-Token takes precedence over Authorization, and the optional query-string token acts as a final read-only fallback for browser resource URLs that cannot attach authorization headers.

Parameters:

authorization (Optional[str]) – Raw Authorization header value
x_hubvault_token (Optional[str]) – Raw X-HubVault-Token header value
query_token (Optional[str]) – Raw token query-string value

Returns:

Normalized token string or None when no supported token is present

Return type:

Optional[str]

build_read_auth_dependency

hubvault.server.auth.build_read_auth_dependency(authorizer: TokenAuthorizer)[source]

Create a FastAPI dependency that enforces read access.

Parameters:: authorizer (TokenAuthorizer) – Token authorizer shared by the server app
Returns:: FastAPI dependency callable that returns AuthContext
Return type:: Callable[…, Awaitable[AuthContext]]
Raises:: hubvault.optional.MissingOptionalDependencyError – Raised when the API extra is not installed.

build_write_auth_dependency

hubvault.server.auth.build_write_auth_dependency(authorizer: TokenAuthorizer)[source]

Create a FastAPI dependency that enforces write access.

Parameters:: authorizer (TokenAuthorizer) – Token authorizer shared by the server app
Returns:: FastAPI dependency callable that returns AuthContext
Return type:: Callable[…, Awaitable[AuthContext]]
Raises:: hubvault.optional.MissingOptionalDependencyError – Raised when the API extra is not installed.