pre-alpha

5.7 · Reference

Auth and crypto

JWTAuth delegates signature and registered-claim verification to the Rust core. Its current key and policy values are captured for each token verification, while the application-defined resolve_claims hook remains Python and runs for every verified token.

hinoki.auth.Caller dataclass

Who is making the request, as decided by authentication.

id is a stable string, user is your own object (the user row, a service account) and permissions is what the caller may do::

Caller(id="u1", user=user, permissions=frozenset({"posts:write"}))

hinoki.auth.Permission

Bases: StrEnum

Base for an application's typed permission names.

Subclass it with the permissions your application uses::

class BlogPermission(Permission):
    WRITE = "posts:write"

Members compare and serialize as their string values.

hinoki.auth.Credentials dataclass

The parts of a request a provider may inspect.

hinoki.auth.BaseAuth

Bases: ABC

Base class of providers.

authenticate returns a principal, None when the request carries no credentials, and raises Unauthorized when credentials are present but invalid. Providers hold no per-request state.

openapi_scheme

openapi_scheme() -> dict[str, object] | None

OpenAPI security scheme describing this provider, if it has one.

authenticate abstractmethod

authenticate(
    credentials: Credentials,
) -> Caller[T] | Awaitable[Caller[T] | None] | None

async def or plain def (a plain one runs on the sync executor).

hinoki.auth.HeaderAuth

Bases: BaseAuth[T]

Credential carried in a named header; subclasses implement resolve.

resolve abstractmethod

resolve(
    value: str,
) -> Caller[T] | Awaitable[Caller[T] | None] | None

The principal for a header value or None if invalid; async def or plain def.

hinoki.auth.BearerAuth

Bases: HeaderAuth[T]

Authorization: Bearer <token>; subclasses implement resolve_token.

resolve_token abstractmethod

resolve_token(
    token: str,
) -> Caller[T] | Awaitable[Caller[T] | None] | None

async def or plain def, as resolve.

hinoki.auth.APIKeyAuth

Bases: HeaderAuth[T]

API key in x-api-key (override header to change it).

hinoki.crypto.JWTKey dataclass

One verification (and optionally signing) key.

HMAC secrets must be at least as long as the hash (32/48/64 bytes). For EdDSA the key is the 32-byte private seed, or with public=True the 32-byte public key of a verify-only deployment. kid is required when several keys are configured. The key is excluded from repr.

verify_only classmethod

verify_only(kid: str | None, public_key: bytes) -> JWTKey

An Ed25519 public key (32 bytes) that can verify but never sign. Use this, not the plain constructor, wherever you hold only the public key: a public key passed as a seed would let anyone who knows it forge tokens.

hinoki.crypto.JWTAuth

Bases: BearerAuth[T]

Bearer-token provider for JWTs. Subclass, set keys (and usually issuer and audience) and implement resolve_claims::

class Tokens(JWTAuth[User]):
    keys = [JWTKey("2026-11", "HS256", settings.jwt_secret)]
    issuer = "https://api.example.com"
    audience = "blog"

    async def resolve_claims(self, claims):
        subject, raw = claims.get("sub"), claims.get("scopes", [])
        if not isinstance(subject, str) or not isinstance(raw, list):
            return None  # claims are signed, but still untyped JSON
        try:
            user = await User.aget_or_none(id=UUID(subject))
        except ValueError:  # a signed token can still carry any text
            return None
        if user is None:
            return None
        scopes = frozenset(s for s in raw if isinstance(s, str))
        return Caller(subject, user, scopes)

now

now() -> int

The clock (override in tests).

resolve_claims abstractmethod

resolve_claims(
    claims: dict[str, Any],
) -> Caller[T] | Awaitable[Caller[T] | None] | None

The principal for verified claims, or None to refuse; async def or plain def.

issue

issue(claims: dict[str, Any], ttl: int = 900) -> str

A signed token for claims valid for ttl seconds, signed with the first non-public key. iat and exp are always set by the server (a value in claims is replaced); iss and aud are added when configured, unless claims already has them.

hinoki.crypto.ClaimsJWTAuth

Bases: JWTAuth[None]

A JWT provider whose caller comes from the signed claims alone.

Subclass it and set keys (and usually issuer and audience)::

class Tokens(ClaimsJWTAuth):
    keys = [JWTKey("2026-11", "HS256", settings.jwt_secret)]

Caller.id is the non-empty string claim sub, Caller.user is None and Caller.permissions are the strings in the list claim named by scope_claim (none when it is absent). A token without a usable sub, or whose scope claim is not a list, is refused. Nothing is loaded from a database, so a token stays valid until it expires; use JWTAuth when a revoked or deleted account must be refused immediately.

Because it runs no application code, the Rust server can authenticate generated CRUD routes that use it without entering Python. Overriding any method keeps the routes on the Python request pipeline.

hinoki.crypto.PasswordHasher

Argon2id hashes in PHC format, computed off the event loop.

Parameters below the OWASP floor are refused unless allow_weak=True (tests only). workers bounds concurrent hashing, max_pending the queue; beyond that hash/verify raise HashingBusy (503). A task cancelled while its hash runs frees its slot but the thread finishes, so at most workers extra hashes can be in flight; hash_sync/verify_sync are not bounded. Only argon2id hashes are verified. For unknown users, verify against a fixed dummy hash so timing does not reveal who exists.

hash_sync

hash_sync(password: str) -> str

Blocking hash (for scripts and sync handlers).

verify_sync

verify_sync(password: str, stored: str) -> bool

False for a wrong password; ValueError for a malformed hash.

needs_rehash

needs_rehash(stored: str) -> bool

True when stored was made with other parameters than these.

hinoki.crypto.random_token

random_token(size: int = 32) -> str

size random bytes (1 to 1024) as URL-safe text, from the OS CSPRNG.