139 lines
4.7 KiB
Python
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
|