pavilion 0.1.0__py3-none-any.whl

pavilion/__init__.py

@@ -0,0 +1,5 @@
+from pavilion.cli import app
+
+
+def main() -> None:
+    app()

pavilion/auth/__init__.py

@@ -0,0 +1 @@
+"""Auth package scaffolding (`pavilion add auth`)."""

pavilion/auth/cli.py

@@ -0,0 +1,173 @@
+"""`pavilion add auth`"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from pavilion import ui
+from pavilion.auth.config import AuthConfig, Hashing, RefreshKeys, Strategy, Transport
+from pavilion.auth.scaffold import AuthFilesExistError, key_pairs, scaffold_auth
+from pavilion.auth.ttl import DEFAULT_ACCESS_TTL, DEFAULT_REFRESH_TTL, TTL, validate_ttls
+from pavilion.keys.cli import RsaBitsOption, check_rsa_bits, choose_algorithm, choose_rsa_bits
+from pavilion.keys.generate import (
+    DEFAULT_SECRETS_DIR,
+    Algorithm,
+    KeyMismatchError,
+    KeyPair,
+)
+
+REFRESH_KEY_LABELS = {
+    Strategy.ASYMMETRIC: "Separate key pair  (a leaked access key can't forge refresh tokens)",
+    Strategy.SYMMETRIC: "Separate secret    (a leaked access secret can't forge refresh tokens)",
+}
+
+
+
+def _parse_ttl(text: str) -> TTL:
+    try:
+        return TTL.parse(text)
+    except ValueError as e:
+        raise typer.BadParameter(str(e)) from None
+
+
+def _ttl_option(flag: str, default: TTL, token: str) -> typer.models.OptionInfo:
+    return typer.Option(
+        flag,
+        parser=_parse_ttl,
+        metavar="DURATION",
+        help=f"{token} token lifetime, e.g. 30m, 3h, 7d (default {default}). Prompts if omitted.",
+        show_default=False,
+    )
+
+
+def _choose_ttl(message: str, default: TTL, longer_than: TTL | None = None) -> TTL:
+    def validate(answer: str) -> bool | str:
+        try:
+            ttl = TTL.parse(answer)
+            if longer_than is not None:
+                validate_ttls(longer_than, ttl)
+        except ValueError as e:
+            return str(e)
+        return True
+
+    return TTL.parse(ui.text(message, str(default), validate))
+
+
+def add_auth(
+    transport: Annotated[
+        Transport | None,
+        typer.Option(help="How tokens travel: Authorization header or cookies.", show_default=False),
+    ] = None,
+    strategy: Annotated[
+        Strategy | None, typer.Option(help="Token signing strategy.", show_default=False)
+    ] = None,
+    algorithm: Annotated[
+        Algorithm | None,
+        typer.Option(
+            case_sensitive=False, help="Asymmetric JWT algorithm.", show_default=False
+        ),
+    ] = None,
+    rsa_bits: RsaBitsOption = None,
+    refresh_keys: Annotated[
+        RefreshKeys | None,
+        typer.Option(help="Sign refresh tokens with their own keys.", show_default=False),
+    ] = None,
+    access_ttl: Annotated[
+        TTL | None, _ttl_option("--access-ttl", DEFAULT_ACCESS_TTL, "Access")
+    ] = None,
+    refresh_ttl: Annotated[
+        TTL | None, _ttl_option("--refresh-ttl", DEFAULT_REFRESH_TTL, "Refresh")
+    ] = None,
+    hashing: Annotated[
+        Hashing | None, typer.Option(help="Password hashing.", show_default=False)
+    ] = None,
+    directory: Annotated[
+        Path, typer.Option("--dir", "-d", help="Directory for the generated package.")
+    ] = Path("auth"),
+    force: Annotated[
+        bool, typer.Option("--force", help="Overwrite existing auth files.")
+    ] = False,
+) -> None:
+    """Generate an auth package: JWT access/refresh tokens, password hashing, login/refresh/logout.
+
+    Prompts for any choice not given as an option.
+    """
+    transport = transport or ui.select(
+        "Authentication transport:",
+        {
+            Transport.HEADER: "JWT in Authorization header  (Bearer token)",
+            Transport.COOKIE: "JWT in cookies               (HttpOnly)",
+        },
+    )
+    strategy = strategy or ui.select(
+        "Token/signing strategy:",
+        {
+            Strategy.ASYMMETRIC: "Asymmetric  (private key signs, public key verifies)",
+            Strategy.SYMMETRIC: "Symmetric   (HS256, one shared secret)",
+        },
+    )
+    if strategy is Strategy.SYMMETRIC and algorithm:
+        raise typer.BadParameter("only applies to --strategy asymmetric", param_hint="--algorithm")
+    if strategy is Strategy.ASYMMETRIC:
+        algorithm = algorithm or choose_algorithm("Algorithm:", default=Algorithm.EdDSA)
+    check_rsa_bits(rsa_bits, algorithm)
+    refresh_keys = refresh_keys or ui.select(
+        "Refresh token keys:",
+        {
+            RefreshKeys.SHARED: "Same as access tokens",
+            RefreshKeys.SEPARATE: REFRESH_KEY_LABELS[strategy],
+        },
+    )
+    if algorithm is Algorithm.RS256 and rsa_bits is None:
+        # Existing keys get reused, so only ask for a size when new ones will be made.
+        separate = refresh_keys is RefreshKeys.SEPARATE
+        if any(not keys.private.exists() for keys in key_pairs(DEFAULT_SECRETS_DIR, separate)):
+            rsa_bits = choose_rsa_bits()
+    access_ttl = access_ttl or _choose_ttl("Access token TTL:", DEFAULT_ACCESS_TTL)
+    refresh_ttl = refresh_ttl or _choose_ttl(
+        "Refresh token TTL:", DEFAULT_REFRESH_TTL, longer_than=access_ttl
+    )
+    try:
+        validate_ttls(access_ttl, refresh_ttl)
+    except ValueError as e:
+        raise typer.BadParameter(str(e), param_hint="--access-ttl/--refresh-ttl") from None
+    hashing = hashing or ui.select(
+        "Password hashing:", {Hashing.ARGON2: "Argon2", Hashing.BCRYPT: "bcrypt"}
+    )
+
+    config = AuthConfig(
+        transport=transport,
+        hashing=hashing,
+        strategy=strategy,
+        algorithm=algorithm,
+        refresh_keys=refresh_keys,
+        access_ttl=access_ttl,
+        refresh_ttl=refresh_ttl,
+    )
+    try:
+        result = scaffold_auth(
+            config, directory, DEFAULT_SECRETS_DIR, rsa_key_size=rsa_bits, force=force
+        )
+    except AuthFilesExistError as e:
+        raise ui.fail(
+            f"Auth files already exist: {', '.join(map(str, e.paths))}. Use --force to overwrite."
+        )
+    except KeyMismatchError as e:
+        size = f" --rsa-bits {rsa_bits}" if rsa_bits else ""
+        target = " --refresh" if e.keys == KeyPair.in_dir(DEFAULT_SECRETS_DIR, refresh=True) else ""
+        raise ui.fail(
+            f"{e}.\nPick a matching option, or replace the keys with "
+            f"`pavilion add keys {algorithm}{size}{target} --force`.",
+            color=typer.colors.RED,
+        )
+
+    typer.secho(f"Generated {directory}/ ({config.describe()}):", fg=typer.colors.GREEN)
+    for path in result.files:
+        typer.echo(f"  {path}")
+    for path in result.removed:
+        typer.echo(f"  {path} (removed, not used by this configuration)")
+    for note in result.secrets_notes:
+        typer.echo(note)
+    deps = " ".join(f"'{d}'" if "[" in d else d for d in config.dependencies)
+    typer.echo(f"\nNext: uv add {deps}")

pavilion/auth/config.py

@@ -0,0 +1,77 @@
+"""The choices behind a generated auth package."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pavilion.auth.ttl import DEFAULT_ACCESS_TTL, DEFAULT_REFRESH_TTL, TTL
+from pavilion.keys.generate import Algorithm
+
+SYMMETRIC_ALGORITHM = "HS256"
+
+
+class Transport(StrEnum):
+    """How the access/refresh tokens travel between client and server."""
+
+    HEADER = "header"
+    COOKIE = "cookie"
+
+class Strategy(StrEnum):
+    ASYMMETRIC = "asymmetric"
+    SYMMETRIC = "symmetric"
+
+class Hashing(StrEnum):
+    ARGON2 = "argon2"
+    BCRYPT = "bcrypt"
+
+class RefreshKeys(StrEnum):
+    SHARED = "shared"
+    SEPARATE = "separate"
+
+# Output file name -> template path (relative to auth/templates), for every transport.
+COMMON_TEMPLATES = {
+    "__init__.py": "__init__.py.jinja",
+    "passwords.py": "passwords.py.jinja",
+    "tokens.py": "tokens.py.jinja",
+    "service.py": "service.py.jinja",
+}
+COOKIE_TEMPLATES = {"cookies.py": "cookies.py.jinja"}
+# Every file pavilion may generate, so `--force` can remove ones a new config doesn't use.
+ALL_OUTPUT_FILES = frozenset(COMMON_TEMPLATES) | frozenset(COOKIE_TEMPLATES)
+
+@dataclass(frozen=True)
+class AuthConfig:
+    transport: Transport
+    strategy: Strategy
+    hashing: Hashing
+    algorithm: Algorithm | None = None  # asymmetric only
+    refresh_keys: RefreshKeys = RefreshKeys.SHARED
+    access_ttl: TTL = DEFAULT_ACCESS_TTL
+    refresh_ttl: TTL = DEFAULT_REFRESH_TTL
+
+    @property
+    def separate_refresh_keys(self) -> bool:
+        return self.refresh_keys is RefreshKeys.SEPARATE
+
+    @property
+    def jwt_algorithm(self) -> str:
+        return str(self.algorithm) if self.strategy is Strategy.ASYMMETRIC else SYMMETRIC_ALGORITHM
+
+    @property
+    def templates(self) -> dict[str, str]:
+        """Output file name -> template path (relative to auth/templates)."""
+        if self.transport is Transport.COOKIE:
+            return COMMON_TEMPLATES | COOKIE_TEMPLATES
+        return COMMON_TEMPLATES
+
+    @property
+    def dependencies(self) -> list[str]:
+        # Asymmetric algorithms need PyJWT's `cryptography` extra.
+        jwt = "pyjwt[crypto]" if self.strategy is Strategy.ASYMMETRIC else "pyjwt"
+        return [jwt, "argon2-cffi" if self.hashing is Hashing.ARGON2 else "bcrypt"]
+
+    def describe(self) -> str:
+        hashing = "Argon2" if self.hashing is Hashing.ARGON2 else "bcrypt"
+        via = "cookies" if self.transport is Transport.COOKIE else "header"
+        refresh = ", separate refresh keys" if self.separate_refresh_keys else ""
+        ttls = f"access {self.access_ttl} / refresh {self.refresh_ttl}"
+        return f"JWT {self.jwt_algorithm} via {via} ({self.strategy}{refresh}), {ttls}, {hashing}"

pavilion/auth/scaffold.py

@@ -0,0 +1,121 @@
+"""Rendering an auth package (tokens, cookies, password hashing, login/refresh/logout)."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, StrictUndefined
+
+from pavilion.auth.config import ALL_OUTPUT_FILES, AuthConfig, Strategy, Transport
+from pavilion.keys.generate import (
+    Algorithm,
+    KeyPair,
+    check_keys,
+    ensure_keys,
+    ensure_secret,
+    read_rsa_key_size,
+    secret_path,
+)
+
+
+class AuthFilesExistError(Exception):
+    def __init__(self, paths: list[Path]):
+        super().__init__(", ".join(map(str, paths)))
+        self.paths = paths
+
+
+@dataclass(frozen=True)
+class AuthResult:
+    files: list[Path]
+    # Files from a previous run that this config doesn't use (deleted with --force).
+    removed: list[Path]
+    # Human-readable notes about the keys/secrets used: access first, then refresh.
+    secrets_notes: list[str]
+
+
+_env = Environment(
+    loader=PackageLoader("pavilion.auth", "templates"),
+    undefined=StrictUndefined,
+    trim_blocks=True,
+    lstrip_blocks=True,
+    keep_trailing_newline=True,
+)
+
+
+def key_pairs(secrets_dir: Path, separate_refresh_keys: bool) -> list[KeyPair]:
+    """Asymmetric key pairs used: access tokens first, then refresh tokens if separate."""
+    access = KeyPair.in_dir(secrets_dir)
+    if separate_refresh_keys:
+        return [access, KeyPair.in_dir(secrets_dir, refresh=True)]
+    return [access]
+
+
+def _prepare_secrets(
+    config: AuthConfig, secrets_dir: Path, rsa_key_size: int | None
+) -> list[str]:
+    def verb(created: bool) -> str:
+        return "Generated" if created else "Using existing"
+
+    if config.strategy is Strategy.SYMMETRIC:
+        paths = [secret_path(secrets_dir)]
+        if config.separate_refresh_keys:
+            paths.append(secret_path(secrets_dir, refresh=True))
+        return [f"{verb(ensure_secret(path))} HS256 secret: {path}" for path in paths]
+
+    assert config.algorithm is not None
+    pairs = key_pairs(secrets_dir, config.separate_refresh_keys)
+    # Validate every pair first so a mismatch in one doesn't leave new keys behind.
+    for keys in pairs:
+        check_keys(keys, config.algorithm, rsa_key_size)
+    notes = []
+    for keys in pairs:
+        created = ensure_keys(keys, config.algorithm, rsa_key_size)
+        label = str(config.algorithm)
+        if config.algorithm is Algorithm.RS256:
+            label += f" ({read_rsa_key_size(keys.private)}-bit)"
+        notes.append(f"{verb(created)} {label} key pair: {keys.private}, {keys.public}")
+    return notes
+
+
+def scaffold_auth(
+    config: AuthConfig,
+    directory: Path,
+    secrets_dir: Path,
+    *,
+    rsa_key_size: int | None = None,
+    force: bool = False,
+) -> AuthResult:
+    """Render the auth package into `directory` and make sure signing material exists.
+
+    `rsa_key_size` applies to newly generated RS256 keys (default 2048); when given,
+    existing RS256 keys must match it.
+
+    Raises AuthFilesExistError or KeyMismatchError before writing anything.
+    """
+    targets = {directory / name: template for name, template in config.templates.items()}
+    existing = sorted(p for name in ALL_OUTPUT_FILES if (p := directory / name).exists())
+    if existing and not force:
+        raise AuthFilesExistError(existing)
+    stale = [path for path in existing if path not in targets]
+
+    secrets_notes = _prepare_secrets(config, secrets_dir, rsa_key_size)
+
+    context = {
+        "cookie": config.transport is Transport.COOKIE,
+        "hashing": str(config.hashing),
+        "asymmetric": config.strategy is Strategy.ASYMMETRIC,
+        "algorithm": config.jwt_algorithm,
+        "separate_refresh_keys": config.separate_refresh_keys,
+        "access_ttl": config.access_ttl.python(),
+        "refresh_ttl": config.refresh_ttl.python(),
+        "access_keys": KeyPair.in_dir(secrets_dir),
+        "refresh_keys": KeyPair.in_dir(secrets_dir, refresh=True),
+        "access_secret": secret_path(secrets_dir).as_posix(),
+        "refresh_secret": secret_path(secrets_dir, refresh=True).as_posix(),
+        "package": directory.name,
+    }
+    directory.mkdir(parents=True, exist_ok=True)
+    for path, template in targets.items():
+        path.write_text(_env.get_template(template).render(context))
+    for path in stale:
+        path.unlink()
+    return AuthResult(files=list(targets), removed=stale, secrets_notes=secrets_notes)

pavilion/auth/templates/__init__.py.jinja

@@ -0,0 +1,87 @@
+"""Authentication: JWT ({{ algorithm }}) via {{ "HttpOnly cookies" if cookie else "the Authorization header" }}, {{ "Argon2" if hashing == "argon2" else "bcrypt" }} password hashing.
+
+Generated by `pavilion add auth`. Implement `UserRepository` for your user model, then:
+
+{% if cookie %}
+    from {{ package }} import (
+        ACCESS_COOKIE,
+        REFRESH_COOKIE,
+        AuthService,
+        InMemoryRevokedTokenStore,
+        cleared_cookies,
+        token_cookies,
+    )
+
+    auth = AuthService(users=MyUserRepository(), revoked_tokens=InMemoryRevokedTokenStore())
+
+    # login (and refresh): set both cookies on the response
+    pair = auth.login("alice", "password")
+    for cookie in token_cookies(pair):
+        response.set_cookie(**cookie.kwargs)
+
+    user_id = auth.authenticate(request.cookies[ACCESS_COOKIE])
+    pair = auth.refresh(request.cookies[REFRESH_COOKIE])
+
+    # logout: revoke, then clear both cookies
+    auth.logout(request.cookies[REFRESH_COOKIE])
+    for cookie in cleared_cookies():
+        response.set_cookie(**cookie.kwargs)
+{% else %}
+    from {{ package }} import AuthService, InMemoryRevokedTokenStore
+
+    auth = AuthService(users=MyUserRepository(), revoked_tokens=InMemoryRevokedTokenStore())
+    pair = auth.login("alice", "password")      # return to the client as JSON
+    user_id = auth.authenticate(access_token)   # from "Authorization: Bearer <token>"
+    pair = auth.refresh(refresh_token)
+    auth.logout(refresh_token)
+{% endif %}
+
+Store new passwords with `hash_password()`.
+"""
+
+{% if cookie %}
+from .cookies import (
+    ACCESS_COOKIE,
+    REFRESH_COOKIE,
+    REFRESH_COOKIE_PATH,
+    Cookie,
+    cleared_cookies,
+    token_cookies,
+)
+{% endif %}
+from .passwords import hash_password, verify_password
+from .service import (
+    AuthError,
+    AuthService,
+    InMemoryRevokedTokenStore,
+    RevokedTokenStore,
+    TokenPair,
+    User,
+    UserRepository,
+)
+
+__all__ = [
+{% if cookie %}
+    "ACCESS_COOKIE",
+    "REFRESH_COOKIE",
+    "REFRESH_COOKIE_PATH",
+{% endif %}
+    "AuthError",
+    "AuthService",
+{% if cookie %}
+    "Cookie",
+{% endif %}
+    "InMemoryRevokedTokenStore",
+    "RevokedTokenStore",
+    "TokenPair",
+    "User",
+    "UserRepository",
+{% if cookie %}
+    "cleared_cookies",
+{% endif %}
+    "hash_password",
+{% if cookie %}
+    "token_cookies",
+{% endif %}
+    "verify_password",
+]

pavilion/auth/templates/cookies.py.jinja

@@ -0,0 +1,59 @@
+"""Sending access and refresh tokens to the browser as HttpOnly cookies.
+
+Pass `cookie.kwargs` to your framework's `response.set_cookie(**cookie.kwargs)`
+(Starlette/FastAPI, Flask and Django all accept these names), and read tokens back
+from the request's cookies by ACCESS_COOKIE / REFRESH_COOKIE.
+
+HttpOnly keeps tokens out of reach of JavaScript (and so of XSS). Browsers attach
+cookies automatically, so SameSite is what stops cross-site requests from using them.
+"""
+
+from dataclasses import asdict, dataclass
+from typing import Any, Literal
+
+from .service import TokenPair
+from .tokens import ACCESS_TOKEN_TTL, REFRESH_TOKEN_TTL
+
+ACCESS_COOKIE = "access_token"
+REFRESH_COOKIE = "refresh_token"
+# The refresh cookie is only sent to paths under this one: point it at the
+# routes that call AuthService.refresh() and .logout().
+REFRESH_COOKIE_PATH = "/auth"
+
+
+@dataclass(frozen=True)
+class Cookie:
+    key: str
+    value: str
+    max_age: int
+    path: str = "/"
+    httponly: bool = True
+    # Most browsers accept Secure cookies on http://localhost, so this also works locally.
+    secure: bool = True
+    samesite: Literal["lax", "strict"] = "lax"
+
+    @property
+    def kwargs(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _access_cookie(value: str, max_age: int) -> Cookie:
+    return Cookie(ACCESS_COOKIE, value, max_age)
+
+
+def _refresh_cookie(value: str, max_age: int) -> Cookie:
+    # Strict: never sent with cross-site requests, even top-level navigations.
+    return Cookie(REFRESH_COOKIE, value, max_age, path=REFRESH_COOKIE_PATH, samesite="strict")
+
+
+def token_cookies(pair: TokenPair) -> list[Cookie]:
+    """Cookies to set after login() or refresh(); they expire along with their tokens."""
+    return [
+        _access_cookie(pair.access_token, int(ACCESS_TOKEN_TTL.total_seconds())),
+        _refresh_cookie(pair.refresh_token, int(REFRESH_TOKEN_TTL.total_seconds())),
+    ]
+
+
+def cleared_cookies() -> list[Cookie]:
+    """Cookies to set after logout(): same names and paths, expired immediately."""
+    return [_access_cookie("", 0), _refresh_cookie("", 0)]

pavilion/auth/templates/passwords.py.jinja

@@ -0,0 +1,34 @@
+"""Password hashing with {{ "Argon2" if hashing == "argon2" else "bcrypt" }}."""
+
+{% if hashing == "argon2" %}
+from argon2 import PasswordHasher
+from argon2.exceptions import InvalidHashError, VerificationError
+
+# Defaults to RFC 9106's recommended (low-memory) parameters.
+_hasher = PasswordHasher()
+
+
+def hash_password(password: str) -> str:
+    return _hasher.hash(password)
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    try:
+        return _hasher.verify(password_hash, password)
+    except (VerificationError, InvalidHashError):
+        return False
+{% else %}
+import bcrypt
+
+
+def hash_password(password: str) -> str:
+    # bcrypt rejects passwords over 72 bytes (ValueError); cap length at signup.
+    return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    try:
+        return bcrypt.checkpw(password.encode(), password_hash.encode())
+    except ValueError:  # malformed hash or over-long password
+        return False
+{% endif %}

pavilion/auth/templates/service.py.jinja

@@ -0,0 +1,123 @@
+"""Login, refresh and logout with JWT access/refresh tokens."""
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from functools import cache
+from typing import Any, Protocol
+
+from . import tokens
+from .passwords import hash_password, verify_password
+
+
+class AuthError(Exception):
+    """Invalid credentials, or an invalid, expired or revoked token."""
+
+
+class User(Protocol):
+    @property
+    def id(self) -> Any: ...
+
+    @property
+    def password_hash(self) -> str: ...
+
+
+class UserRepository(Protocol):
+    def get_by_username(self, username: str) -> User | None: ...
+
+
+class RevokedTokenStore(Protocol):
+    """Remembers revoked refresh tokens (by `jti`) until they would have expired."""
+
+    def revoke(self, jti: str, expires_at: datetime) -> None: ...
+
+    def is_revoked(self, jti: str) -> bool: ...
+
+
+class InMemoryRevokedTokenStore:
+    """Single-process store for development; use Redis or a database in production."""
+
+    def __init__(self) -> None:
+        self._revoked: dict[str, datetime] = {}
+
+    def revoke(self, jti: str, expires_at: datetime) -> None:
+        now = datetime.now(UTC)
+        # Expired tokens are rejected anyway, so there's no need to remember them.
+        self._revoked = {j: exp for j, exp in self._revoked.items() if exp > now}
+        self._revoked[jti] = expires_at
+
+    def is_revoked(self, jti: str) -> bool:
+        return jti in self._revoked
+
+
+@dataclass(frozen=True)
+class TokenPair:
+    access_token: str
+    refresh_token: str
+{% if not cookie %}
+    token_type: str = "bearer"
+{% endif %}
+
+
+class AuthService:
+    def __init__(self, users: UserRepository, revoked_tokens: RevokedTokenStore) -> None:
+        self.users = users
+        self.revoked_tokens = revoked_tokens
+
+    def login(self, username: str, password: str) -> TokenPair:
+        user = self.users.get_by_username(username)
+        if user is None:
+            # Hash anyway so response time doesn't reveal which usernames exist.
+            verify_password(password, _dummy_hash())
+            raise AuthError("Invalid username or password")
+        if not verify_password(password, user.password_hash):
+            raise AuthError("Invalid username or password")
+        return _issue_tokens(str(user.id))
+
+    def refresh(self, refresh_token: str) -> TokenPair:
+        """Exchange a refresh token for a new pair; the old refresh token stops working."""
+        claims = self._decode_refresh_token(refresh_token)
+        self._revoke(claims)
+        return _issue_tokens(claims["sub"])
+
+    def logout(self, refresh_token: str) -> None:
+        """Revoke the refresh token.
+
+        Access tokens are stateless and stay valid until they expire
+        (tokens.ACCESS_TOKEN_TTL), so keep that TTL short.
+        """
+        try:
+            claims = self._decode_refresh_token(refresh_token)
+        except AuthError:
+            return  # already unusable
+        self._revoke(claims)
+
+    def authenticate(self, access_token: str) -> str:
+        """Return the id of the user an access token was issued to."""
+        try:
+            return tokens.decode_token(access_token, "access")["sub"]
+        except tokens.InvalidTokenError as e:
+            raise AuthError(str(e)) from e
+
+    def _decode_refresh_token(self, refresh_token: str) -> dict[str, Any]:
+        try:
+            claims = tokens.decode_token(refresh_token, "refresh")
+        except tokens.InvalidTokenError as e:
+            raise AuthError(str(e)) from e
+        if self.revoked_tokens.is_revoked(claims["jti"]):
+            raise AuthError("Refresh token has been revoked")
+        return claims
+
+    def _revoke(self, claims: dict[str, Any]) -> None:
+        self.revoked_tokens.revoke(claims["jti"], datetime.fromtimestamp(claims["exp"], UTC))
+
+
+def _issue_tokens(user_id: str) -> TokenPair:
+    return TokenPair(
+        access_token=tokens.create_access_token(user_id),
+        refresh_token=tokens.create_refresh_token(user_id),
+    )
+
+
+@cache
+def _dummy_hash() -> str:
+    return hash_password("dummy password for constant-time login failures")