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 ¶
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 ¶
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)
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.
hinoki.crypto.random_token ¶
random_token(size: int = 32) -> str
size random bytes (1 to 1024) as URL-safe text, from the OS CSPRNG.