Files
jobboard/auth/schemas.py
T

139 lines
4.7 KiB
Python

"""The seven bodies this package accepts, and the five small answers it gives.
Small on purpose.
A ceremony's `credential` is passed through as an opaque dict — it is the
browser's `PublicKeyCredential` serialised by `toJSON()`, and its shape is the
WebAuthn spec's business rather than ours. Restating it as a model here would
be a second, staler copy of a structure the library already parses and
validates properly.
The answers are models rather than dicts so that the app's OpenAPI document,
which a client generates its types from, names every one of them. The JSON is
what the dicts were.
"""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, Field
class LoginBody(BaseModel):
"""The whole login form. No username field, because there is no username —
asking for one would be theatre, and a wrong guess at it would be an error
message about something that does not exist."""
#: Bounded, because it is the one field an unauthenticated stranger can
#: send: scrypt is memory-hard by design and a megabyte of "password" is a
#: megabyte this process hashes before saying no.
password: str = Field(max_length=1000)
#: Where the middleware was sending them before it asked. Sanitised on the
#: way back out — see `_safe_next` in `auth/router.py`.
next: str = "/"
class PasswordBody(BaseModel):
"""Changing it. `current` is required even though the caller is signed in;
`auth/router.py` says why."""
current: str = Field(max_length=1000)
new: str = Field(max_length=1000)
#: Also delete every API token and passkey. Off by default, because a
#: token's cron job is not what a routine change is against; on when the
#: password may have been someone else's, since what they minted with it
#: outlives the change. None is off, and is the default rather than False
#: so the generated client type leaves the field optional, as it does
#: `TokenBody.days`: openapi-typescript makes a field with a non-null
#: default required, and a client that never asks should not have to say so.
revoke_all: bool | None = None
class PasskeyOptionsBody(BaseModel):
"""Starting to register a passkey. `current` is the password, required for
the same reason as in `PasswordBody`: a passkey is a permanent way in, and
a borrowed session must not be able to mint one."""
current: str = Field(max_length=1000)
class PasskeyBody(BaseModel):
"""A finished registration ceremony, on its way to be checked."""
credential: dict[str, Any]
#: What to call it in the list. Suggested by the browser, editable after.
label: str = ""
class PasskeyLoginBody(BaseModel):
"""A finished authentication ceremony. Same reasoning as above."""
credential: dict[str, Any]
class LabelBody(BaseModel):
"""Renaming a passkey or a token."""
label: str = Field(max_length=100)
class TokenBody(BaseModel):
"""Minting an API token. `current` is the password, required for the same
reason as in `PasskeyOptionsBody`: a token is a standing way in, and a
borrowed session must not be able to mint one."""
current: str = Field(max_length=1000)
#: What to call it: the machine or the job that will hold it.
label: str = Field("", max_length=100)
#: How long it lives, in days. None is a token that does not expire, which
#: is what a cron job wants; bounded above so a typo cannot ask for a
#: thousand years and still be called dated.
days: int | None = Field(None, ge=1, le=3650)
class Ok(BaseModel):
"""A change that has nothing to report beyond having happened."""
ok: bool = True
class SignedOut(BaseModel):
"""How many other sessions "sign out everywhere else" closed."""
signed_out: int
class PasswordChanged(BaseModel):
"""What a password change closed and what it left, for the screen to say.
`signed_out` is the other sessions, always closed. The tokens and
passkeys are deleted only when `revoke_all` was asked for, and the
`_left` counts are what is still registered afterwards, expired tokens
included, so an owner who did not ask knows what to review."""
signed_out: int
tokens_revoked: int
passkeys_revoked: int
tokens_left: int
passkeys_left: int
class PasskeyAdded(BaseModel):
"""The row a registered passkey was given, which rename and revoke take."""
id: int
class TokenCreated(BaseModel):
"""A minted token: the one answer in this package that carries a credential.
`token` is shown once and stored nowhere but as a hash, so a caller that
loses it mints another. The rest is the row as `ApiToken` lists it.
"""
id: int
token: str
hint: str
label: str
expires_at: str