Auth And Security Reference

This page documents auth hook types, approval hooks, framework errors, and signed cookies.

Prerequisites

Read Security. Auth hooks are your application policy; Quater only defines when they run and what they receive.

from quater import (
    ActionApproval,
    ApprovalRequest,
    AuthContext,
    AuthRequest,
    HTTPError,
    ImproperlyConfigured,
    SignedCookieSigner,
)

AuthRequest

Added in 0.1.0a1.

Input passed to auth hooks.

AuthRequest(
    method: str,
    path: str,
    headers: Mapping[str, str] = <empty read-only mapping>,
    context: RequestContext = RequestContext(),
)

Field	Type	Default	Description
method	str	required	Method being accessed.
path	str	required	Path being accessed.
headers	Mapping[str, str]	empty read-only mapping	Normalized headers. Header names are lowercase.
context	RequestContext	RequestContext()	Source, entrypoint, request id, tool, and action metadata.

MCP and CLI surface auth receive the surface request first. Route auth= receives a second AuthRequest for the actual route when the route declares auth.

AuthContext

Added in 0.1.0a1.

Authenticated identity returned by auth hooks.

AuthContext(subject: str, metadata: Mapping[str, object] = {})

Field	Type	Default	Description
subject	str	required	Stable user, service, or agent id.
metadata	Mapping[str, object]	empty read-only mapping	Small request-scoped values your app wants to carry.

Example:

from quater import AuthContext, AuthRequest


async def authenticate(ctx: AuthRequest) -> AuthContext | None:
    if ctx.headers.get("authorization") != "Bearer demo-token":
        return None
    return AuthContext(subject="user_123")

ApprovalRequest

Added in 0.1.0a1.

Input passed to action_approval for protected MCP tools and CLI actions.

ApprovalRequest(
    action: str,
    arguments_hash: str,
    token: str,
    auth: AuthContext | None = None,
    context: RequestContext = RequestContext(),
)

Field	Type	Default	Description
action	str	required	Tool or CLI action name.
arguments_hash	str	required	SHA-256 hash of action name and canonical JSON arguments.
token	str	required	Submitted approval token.
auth	AuthContext | None	None	Authenticated caller when available.
context	RequestContext	RequestContext()	Source and entrypoint metadata.

ActionApproval

Added in 0.1.0a1.

Callable type for approval hooks.

ActionApproval = Callable[[ApprovalRequest], Awaitable[bool]]

Return True to allow execution. Return False to deny it.

Authenticate

Added in 0.1.0a1.

Callable type for auth hooks.

Authenticate = Callable[[AuthRequest], Awaitable[AuthContext | None]]

Return AuthContext to allow the request. Return None to deny it. Returning any other type is treated as unauthorized.

HTTPError

Added in 0.1.0a1.

Exception converted into an HTTP-style response.

HTTPError(detail: str | None = None, *, status_code: int | None = None)

Parameter	Type	Default	Description
detail	str | None	None	Client-facing error text. Defaults to "Internal Server Error".
status_code	int | None	None	Response status. Defaults to 500.

Example:

from quater import HTTPError


@app.get("/orders/{order_id}")
async def get_order(order_id: str) -> dict[str, str]:
    raise HTTPError("Order not found", status_code=404)

Expected response:

404 Not Found
Order not found

ImproperlyConfigured

Added in 0.1.0a1.

Framework setup error. Catch this when startup should fail loudly.

raise ImproperlyConfigured("bad setup")

ConfigurationError remains in quater.exceptions as a compatibility subclass, but new app code should use ImproperlyConfigured.

SignedCookieSigner

Added in 0.1.0a1.

HMAC signer for small cookie values. It signs values; it does not encrypt them.

SignedCookieSigner(
    secret: str | bytes,
    *,
    fallback_secrets: Iterable[str | bytes] = (),
    salt: str = "quater.cookie",
)

Parameter	Type	Default	Description
secret	str | bytes	required	Current signing secret.
fallback_secrets	Iterable[str | bytes]	()	Old secrets accepted during rotation.
salt	str	"quater.cookie"	Purpose-specific signing salt.

Methods:

Method	Return	Description
sign(value)	str	Returns a signed cookie value.
verify(signed_value)	str | None	Returns original value or None.

Raises ImproperlyConfigured if secrets are empty.

What Can Go Wrong

Unauthorized : An auth hook returned None.

Approval required : A protected tool or action ran without a valid approval token.

Approval denied : action_approval returned False.

Signed cookie secrets must not be empty : Provide non-empty current and fallback secrets.

Also See

• Security: auth ordering across surfaces.
• MCP: tool-call auth sequence.
• Actions and CLI: dry-run and approval flow.