sysnet-apikeys 0.2.0__py3-none-any.whl

sysnet_apikeys/__init__.py

@@ -0,0 +1,33 @@
+"""sysnet-apikeys: správa API klíčů FastAPI služeb (ADR 006 v CML)."""
+
+from sysnet_apikeys.errors import (
+    ApiKeyError,
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    NotFoundError,
+    ReadOnlyStoreError,
+)
+from sysnet_apikeys.models import ALL_SCOPES, AuditEvent, IssuedKey, KeyRecord, Principal
+from sysnet_apikeys.service import ApiKeyService
+from sysnet_apikeys.store import InMemoryStore, KeyStore
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ALL_SCOPES",
+    "ApiKeyError",
+    "ApiKeyService",
+    "AuditEvent",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConflictError",
+    "InMemoryStore",
+    "IssuedKey",
+    "KeyRecord",
+    "KeyStore",
+    "NotFoundError",
+    "Principal",
+    "ReadOnlyStoreError",
+    "__version__",
+]

sysnet_apikeys/admin.py

@@ -0,0 +1,140 @@
+"""Admin API pro správu klíčů (volitelné: ``sysnet-apikeys[fastapi]``).
+
+Stejné cesty jako notificator: ``POST/GET /keys``, ``POST /keys/revoke``; navíc ``POST /keys/rotate``
+a ``GET /keys/unused``. Chrání je statický ``X-Admin-Key`` porovnávaný v konstantním čase. Bez nastaveného
+secretu vrací 503, takže je admin API vypnuté, dokud ho někdo vědomě nezapne.
+
+Bez ``from __future__ import annotations``: FastAPI musí anotace vyhodnotit za běhu (viz fastapi.py).
+"""
+
+import secrets
+from datetime import datetime, timedelta
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Security, status
+from fastapi.security import APIKeyHeader
+from pydantic import BaseModel, Field, model_validator
+
+from sysnet_apikeys.errors import AuthenticationError
+from sysnet_apikeys.models import KeyRecord
+from sysnet_apikeys.service import ApiKeyService
+
+ADMIN_KEY_HEADER = "X-Admin-Key"
+ADMIN_ACTOR = "admin"
+_scheme = APIKeyHeader(name=ADMIN_KEY_HEADER, scheme_name="AdminKeyAuth", auto_error=False)
+
+
+class KeyOut(BaseModel):
+    """Popis klíče. Nikdy neobsahuje otevřený klíč ani jeho hash."""
+
+    public_id: str
+    client: str
+    scopes: list[str]
+    agenda: str | None
+    status: str
+    created_at: datetime
+    expires_at: datetime | None
+    last_used_at: datetime | None
+    created_by: str | None
+
+
+class IssuedKeyOut(KeyOut):
+    key: str = Field(description="Předejte klientovi bezpečným kanálem; už se nezobrazí.")
+
+
+class CreateIn(BaseModel):
+    name: str = Field(min_length=1, max_length=200)
+    scopes: list[str] = Field(min_length=1)
+    agenda: str | None = None
+    expires_at: datetime | None = None
+
+
+class RotateIn(BaseModel):
+    name: str = Field(min_length=1)
+    grace_seconds: int = Field(ge=0, le=60 * 60 * 24 * 365)
+    scopes: list[str] | None = Field(default=None, min_length=1)
+    expires_at: datetime | None = None
+
+
+class RevokeIn(BaseModel):
+    name: str | None = None
+    public_id: str | None = None
+
+    @model_validator(mode="after")
+    def _exactly_one(self) -> "RevokeIn":
+        if bool(self.name) == bool(self.public_id):
+            raise ValueError("Zadejte právě jedno z: name, public_id.")
+        return self
+
+
+class RevokedOut(BaseModel):
+    revoked: int
+
+
+def _out(service: ApiKeyService, record: KeyRecord) -> dict[str, Any]:
+    return {
+        "public_id": record.public_id,
+        "client": record.client,
+        "scopes": sorted(record.scopes),
+        "agenda": record.agenda,
+        "status": service.describe(record),
+        "created_at": record.created_at,
+        "expires_at": record.expires_at,
+        "last_used_at": record.last_used_at,
+        "created_by": record.created_by,
+    }
+
+
+def make_admin_router(service: ApiKeyService, *, admin_key: str | None) -> APIRouter:
+    """Vyrobí router; ``admin_key=None`` = admin API vypnuté (503)."""
+
+    def require_admin(raw: Annotated[str | None, Security(_scheme)] = None) -> None:
+        if not admin_key:
+            raise HTTPException(
+                status.HTTP_503_SERVICE_UNAVAILABLE, "Administrace klíčů není nakonfigurovaná."
+            )
+        if not secrets.compare_digest((raw or "").encode(), admin_key.encode()):
+            raise AuthenticationError("Neplatný administrační secret.")
+
+    router = APIRouter(tags=["api-keys"], dependencies=[Depends(require_admin)])
+
+    @router.post("/keys", status_code=status.HTTP_201_CREATED, response_model=IssuedKeyOut)
+    async def create_key(body: CreateIn) -> dict[str, Any]:
+        issued = await service.issue(
+            body.name,
+            scopes=body.scopes,
+            agenda=body.agenda,
+            expires_at=body.expires_at,
+            created_by=ADMIN_ACTOR,
+        )
+        return {**_out(service, issued.record), "key": issued.key}
+
+    @router.get("/keys", response_model=list[KeyOut])
+    async def list_keys(client: str | None = None) -> list[dict[str, Any]]:
+        return [_out(service, r) for r in await service.list_keys(client)]
+
+    @router.get("/keys/unused", response_model=list[KeyOut])
+    async def unused_keys(older_than_days: Annotated[int, Query(ge=0)] = 30) -> list[dict[str, Any]]:
+        records = await service.unused(older_than=timedelta(days=older_than_days))
+        return [_out(service, r) for r in records]
+
+    @router.post("/keys/rotate", status_code=status.HTTP_201_CREATED, response_model=IssuedKeyOut)
+    async def rotate_key(body: RotateIn) -> dict[str, Any]:
+        issued = await service.rotate(
+            body.name,
+            grace=timedelta(seconds=body.grace_seconds),
+            scopes=body.scopes,
+            expires_at=body.expires_at,
+            actor=ADMIN_ACTOR,
+        )
+        return {**_out(service, issued.record), "key": issued.key}
+
+    @router.post("/keys/revoke", response_model=RevokedOut)
+    async def revoke_key(body: RevokeIn) -> dict[str, int]:
+        if body.public_id:
+            await service.revoke_key(body.public_id, actor=ADMIN_ACTOR)
+            return {"revoked": 1}
+        assert body.name is not None
+        return {"revoked": await service.revoke(body.name, actor=ADMIN_ACTOR)}
+
+    return router

sysnet_apikeys/cli.py

@@ -0,0 +1,213 @@
+"""Příkazová řádka: ``sysnet-apikeys issue|rotate|revoke|list|unused|import-yaml``.
+
+Úložiště se volí proměnnými prostředí (žádné heslo na příkazové řádce):
+
+- ``APIKEYS_STORE=mongo`` + ``APIKEYS_MONGO_URL``, ``APIKEYS_MONGO_DB``,
+  ``APIKEYS_MONGO_COLLECTION`` (výchozí ``api_keys``)
+- ``APIKEYS_STORE=sql`` + ``APIKEYS_SQL_URL`` (např. ``postgresql+asyncpg://...``),
+  ``APIKEYS_SQL_TABLE`` (výchozí ``api_keys``)
+
+Otevřený klíč se tiskne jen při ``issue`` a ``rotate`` a jen na stdout.
+"""
+
+import asyncio
+import json
+import os
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from dataclasses import replace
+from datetime import timedelta
+from pathlib import Path
+from typing import Annotated, Any, TypeVar
+
+import typer
+from sysnet_pyutils.utils import gmt_now
+
+from sysnet_apikeys.errors import ApiKeyError, ConflictError
+from sysnet_apikeys.legacy import LegacyYamlStore
+from sysnet_apikeys.models import KeyRecord
+from sysnet_apikeys.service import ApiKeyService
+from sysnet_apikeys.store import KeyStore
+
+app = typer.Typer(add_completion=False, no_args_is_help=True, help="Správa API klíčů SYSNET.")
+T = TypeVar("T")
+
+
+def _env(name: str, default: str | None = None) -> str:
+    value = os.environ.get(name, default)
+    if not value:
+        typer.echo(f"Chybí proměnná prostředí {name}.", err=True)
+        raise typer.Exit(2)
+    return value
+
+
+@asynccontextmanager
+async def _open_store() -> AsyncIterator[KeyStore]:
+    kind = _env("APIKEYS_STORE")
+    if kind == "mongo":
+        from pymongo import AsyncMongoClient
+
+        from sysnet_apikeys.mongo import MongoStore
+
+        client: AsyncMongoClient[Any] = AsyncMongoClient(_env("APIKEYS_MONGO_URL"))
+        collection = _env("APIKEYS_MONGO_COLLECTION", "api_keys")
+        store = MongoStore(client[_env("APIKEYS_MONGO_DB")], collection=collection)
+        await store.create_schema()
+        try:
+            yield store
+        finally:
+            await client.close()
+    elif kind == "sql":
+        from sqlalchemy.ext.asyncio import create_async_engine
+
+        from sysnet_apikeys.sql import SqlStore
+
+        engine = create_async_engine(_env("APIKEYS_SQL_URL"))
+        sql_store = SqlStore(engine, table=_env("APIKEYS_SQL_TABLE", "api_keys"))
+        await sql_store.create_schema()
+        try:
+            yield sql_store
+        finally:
+            await engine.dispose()
+    else:
+        typer.echo(f"APIKEYS_STORE musí být 'mongo' nebo 'sql', ne '{kind}'.", err=True)
+        raise typer.Exit(2)
+
+
+def _run(action: Callable[[ApiKeyService, KeyStore], Awaitable[T]]) -> T:
+    async def main() -> T:
+        async with _open_store() as store:
+            return await action(ApiKeyService(store), store)
+
+    try:
+        return asyncio.run(main())
+    except ApiKeyError as error:
+        typer.echo(f"Chyba: {error}", err=True)
+        raise typer.Exit(1) from error
+
+
+def _row(service: ApiKeyService, record: KeyRecord) -> dict[str, Any]:
+    return {
+        "public_id": record.public_id,
+        "client": record.client,
+        "scopes": sorted(record.scopes),
+        "agenda": record.agenda,
+        "status": service.describe(record),
+        "created_at": record.created_at.isoformat(),
+        "expires_at": record.expires_at.isoformat() if record.expires_at else None,
+        "last_used_at": record.last_used_at.isoformat() if record.last_used_at else None,
+    }
+
+
+def _print_rows(service: ApiKeyService, records: list[KeyRecord], as_json: bool) -> None:
+    rows = [_row(service, r) for r in records]
+    if as_json:
+        typer.echo(json.dumps(rows, ensure_ascii=False))
+        return
+    for r in rows:
+        typer.echo(f"{r['public_id']}  {r['client']:<28} {r['status']:<8} agenda={r['agenda'] or '-'} "
+                   f"scopes={','.join(r['scopes'])} last_used={r['last_used_at'] or '-'}")
+
+
+@app.command()
+def issue(
+    client: str,
+    scope: Annotated[list[str], typer.Option("--scope", help="Oprávnění (lze opakovat).")],
+    agenda: Annotated[str | None, typer.Option()] = None,
+) -> None:
+    """Vydá první klíč klienta. Klíč se zobrazí jen teď."""
+
+    async def action(service: ApiKeyService, _: KeyStore) -> str:
+        return (await service.issue(client, scopes=scope, agenda=agenda, created_by="cli")).key
+
+    typer.echo(_run(action))
+
+
+@app.command()
+def rotate(
+    client: str,
+    grace_hours: Annotated[float, typer.Option("--grace-hours", min=0)] = 24,
+) -> None:
+    """Vydá nový klíč; starý platí ještě ``--grace-hours``."""
+
+    async def action(service: ApiKeyService, _: KeyStore) -> str:
+        issued = await service.rotate(client, grace=timedelta(hours=grace_hours), actor="cli")
+        return issued.key
+
+    typer.echo(_run(action))
+
+
+@app.command()
+def revoke(client: str) -> None:
+    """Zruší všechny aktivní klíče klienta."""
+
+    async def action(service: ApiKeyService, _: KeyStore) -> int:
+        return await service.revoke(client, actor="cli")
+
+    typer.echo(f"Zrušeno klíčů: {_run(action)}")
+
+
+@app.command("list")
+def list_(
+    client: Annotated[str | None, typer.Option()] = None,
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Vypíše klíče (nikdy ne otevřený klíč ani hash)."""
+
+    async def action(service: ApiKeyService, _: KeyStore) -> tuple[ApiKeyService, list[KeyRecord]]:
+        return service, await service.list_keys(client)
+
+    service, records = _run(action)
+    _print_rows(service, records, as_json)
+
+
+@app.command()
+def unused(
+    older_than_days: Annotated[int, typer.Option("--older-than-days", min=0)] = 30,
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Aktivní klíče, které nikdo nepoužil déle než zadaný počet dní (nebo nikdy)."""
+
+    async def action(service: ApiKeyService, _: KeyStore) -> tuple[ApiKeyService, list[KeyRecord]]:
+        return service, await service.unused(older_than=timedelta(days=older_than_days))
+
+    service, records = _run(action)
+    _print_rows(service, records, as_json)
+
+
+@app.command("import-yaml")
+def import_yaml(
+    path: Path,
+    apply: Annotated[bool, typer.Option("--apply", help="Bez tohoto přepínače jen dry-run.")] = False,
+) -> None:
+    """Převede ``api_keys`` ze starého YAML na hashe v úložišti. Klienti zůstanou beze změny."""
+    legacy = LegacyYamlStore.from_file(path)
+
+    async def action(service: ApiKeyService, store: KeyStore) -> tuple[int, int, int]:
+        added = skipped = 0
+        records = await legacy.list_all()
+        for old in records:
+            if await store.get(old.key_hash) is not None:
+                skipped += 1
+                continue
+            if apply:
+                try:
+                    imported = replace(old, created_at=gmt_now(), legacy=False, created_by="import-yaml")
+                    await store.add(imported)
+                except ConflictError:
+                    skipped += 1
+                    continue
+            added += 1
+        return len(records), added, skipped
+
+    total, added, skipped = _run(action)
+    mode = "" if apply else " (dry-run, nic se nezapsalo; použijte --apply)"
+    typer.echo(f"Nalezeno: {total}, přidáno: {added}, přeskočeno: {skipped}{mode}")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

sysnet_apikeys/errors.py

@@ -0,0 +1,29 @@
+"""Výjimky knihovny. Služba je překládá na HTTP odpovědi, knihovna sama HTTP nezná."""
+
+
+class ApiKeyError(Exception):
+    """Základ všech chyb knihovny."""
+
+
+class AuthenticationError(ApiKeyError):
+    """Klíč chybí, je neznámý, zrušený nebo propadlý. Příčina se záměrně nerozlišuje."""
+
+
+class AuthorizationError(ApiKeyError):
+    """Klíč je platný, ale nemá požadované oprávnění."""
+
+    def __init__(self, missing: frozenset[str]) -> None:
+        super().__init__("Chybí oprávnění: " + ", ".join(sorted(missing)))
+        self.missing = missing
+
+
+class ConflictError(ApiKeyError):
+    """Klient nebo klíč už existuje."""
+
+
+class NotFoundError(ApiKeyError):
+    """Klient nebo klíč neexistuje (nebo už není aktivní)."""
+
+
+class ReadOnlyStoreError(ApiKeyError):
+    """Úložiště je jen pro čtení (např. starý YAML)."""

sysnet_apikeys/fastapi.py

@@ -0,0 +1,71 @@
+"""FastAPI vazba (volitelná: ``pip install sysnet-apikeys[fastapi]``).
+
+Bez ``from __future__ import annotations``: FastAPI musí anotace vnořených dependency
+(``Depends(self)``) vyhodnotit za běhu, což se zpožděnými anotacemi nepodaří (vrací 422).
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Annotated
+
+from fastapi import Depends, FastAPI, Request, Security
+from fastapi.responses import JSONResponse
+from fastapi.security import APIKeyHeader
+
+from sysnet_apikeys.errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    NotFoundError,
+    ReadOnlyStoreError,
+)
+from sysnet_apikeys.models import Principal
+from sysnet_apikeys.service import ApiKeyService
+
+API_KEY_HEADER = "X-API-KEY"
+_scheme = APIKeyHeader(name=API_KEY_HEADER, scheme_name="ApiKeyAuth", auto_error=False)
+
+
+class ApiKeyAuth:
+    """Dependency: ``Depends(auth)`` vrátí :class:`Principal`; ``auth.scopes(...)`` přidá oprávnění.
+
+    ``auto_error=False``: chybějící hlavička končí stejnou 401 jako neplatný klíč
+    (FastAPI by jinak vrátilo 403 v jiném tvaru a prozradilo, že hlavička chyběla).
+    """
+
+    def __init__(self, service: ApiKeyService) -> None:
+        self.service = service
+
+    async def __call__(self, raw_key: Annotated[str | None, Security(_scheme)] = None) -> Principal:
+        return await self.service.authenticate(raw_key)
+
+    def scopes(self, *required: str) -> Callable[[Principal], Awaitable[Principal]]:
+        async def dependency(principal: Annotated[Principal, Depends(self)]) -> Principal:
+            principal.require_scopes(*required)
+            return principal
+
+        return dependency
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    """Překlad výjimek knihovny na 401/403 se stručným tvarem ``{"detail": ...}``."""
+
+    @app.exception_handler(AuthenticationError)
+    async def _unauthenticated(_: Request, exc: AuthenticationError) -> JSONResponse:
+        return JSONResponse({"detail": str(exc)}, status_code=401)
+
+    @app.exception_handler(AuthorizationError)
+    async def _forbidden(_: Request, exc: AuthorizationError) -> JSONResponse:
+        # Které oprávnění chybí, se klientovi neříká; zůstává v logu služby.
+        return JSONResponse({"detail": "Nedostatečné oprávnění."}, status_code=403)
+
+    @app.exception_handler(ConflictError)
+    async def _conflict(_: Request, exc: ConflictError) -> JSONResponse:
+        return JSONResponse({"detail": str(exc)}, status_code=409)
+
+    @app.exception_handler(NotFoundError)
+    async def _not_found(_: Request, exc: NotFoundError) -> JSONResponse:
+        return JSONResponse({"detail": str(exc)}, status_code=404)
+
+    @app.exception_handler(ReadOnlyStoreError)
+    async def _read_only(_: Request, exc: ReadOnlyStoreError) -> JSONResponse:
+        return JSONResponse({"detail": str(exc)}, status_code=409)

sysnet_apikeys/legacy.py

@@ -0,0 +1,93 @@
+"""Čtení starého YAML ``api_keys: [{klíč: jméno}]`` bez změny klientů.
+
+Výsledek je stejný jako dnešní ``Context.check_api_key`` v sysnet-pyutils (agenda,
+jméno uživatele), ale bez sdíleného stavu: identita se vrací hodnotou.
+Úložiště je jen pro čtení; zápisy (vydání, rotace, rušení) vrací ``ReadOnlyStoreError``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from sysnet_apikeys.errors import ReadOnlyStoreError
+from sysnet_apikeys.models import ALL_SCOPES, KeyRecord
+from sysnet_apikeys.security import hash_key
+
+CONFIG_API_KEYS = "api_keys"
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+
+
+@dataclass(frozen=True, slots=True)
+class LegacyItem:
+    """Jedna položka starého YAML po zahashování; otevřený klíč zde už není."""
+
+    key_hash: str
+    agenda: str
+    client: str
+
+
+def hash_legacy_config(config: Mapping[str, Any]) -> list[LegacyItem]:
+    """Projde konfiguraci jako ``check_api_key`` (sekce s ``api_keys``) a vrátí hashe."""
+    items: list[LegacyItem] = []
+    for agenda, section in config.items():
+        if not isinstance(section, Mapping) or CONFIG_API_KEYS not in section:
+            continue
+        for entry in section[CONFIG_API_KEYS] or []:
+            if not isinstance(entry, Mapping):
+                continue
+            for raw, user in entry.items():
+                items.append(LegacyItem(hash_key(str(raw)), str(agenda), str(user)))
+    return items
+
+
+class LegacyYamlStore:
+    """KeyStore nad starým YAML. Klíče z YAML mají oprávnění ``*`` (staré klíče scopes neznaly)."""
+
+    def __init__(self, config: Mapping[str, Any]) -> None:
+        self._rows: dict[str, KeyRecord] = {}
+        for item in hash_legacy_config(config):
+            self._rows.setdefault(
+                item.key_hash,
+                KeyRecord(
+                    key_hash=item.key_hash,
+                    public_id=item.key_hash[:8],
+                    client=item.client,
+                    scopes=frozenset({ALL_SCOPES}),
+                    created_at=_EPOCH,
+                    agenda=item.agenda,
+                    legacy=True,
+                ),
+            )
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> LegacyYamlStore:
+        with open(path, encoding="utf-8") as handle:
+            return cls(yaml.safe_load(handle) or {})
+
+    async def get(self, key_hash: str) -> KeyRecord | None:
+        return self._rows.get(key_hash)
+
+    async def list_by_client(self, client: str) -> list[KeyRecord]:
+        return [r for r in self._rows.values() if r.client == client]
+
+    async def list_all(self) -> list[KeyRecord]:
+        return sorted(self._rows.values(), key=lambda r: (r.agenda or "", r.client))
+
+    async def touch(self, key_hash: str, when: datetime) -> None:
+        """Poslední použití se do souboru nezapisuje; je to záměrný no-op, ne chyba."""
+        return None
+
+    async def add(self, record: KeyRecord) -> None:
+        raise ReadOnlyStoreError("Starý YAML je jen pro čtení; použijte databázové úložiště.")
+
+    async def set_expires(self, key_hash: str, expires_at: datetime | None) -> None:
+        raise ReadOnlyStoreError("Starý YAML je jen pro čtení.")
+
+    async def set_revoked(self, key_hash: str, revoked_at: datetime) -> None:
+        raise ReadOnlyStoreError("Starý YAML je jen pro čtení.")

sysnet_apikeys/models.py

@@ -0,0 +1,78 @@
+"""Datové modely. Vše neměnné: identita požadavku se předává hodnotou, nikdy sdíleným stavem."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime
+
+from sysnet_apikeys.errors import AuthorizationError
+
+#: Oprávnění „vše“. Dostávají ho klíče převzaté ze starého YAML, které scopes nemají.
+ALL_SCOPES = "*"
+
+
+@dataclass(frozen=True, slots=True)
+class KeyRecord:
+    """Jeden klíč. Otevřený klíč se neukládá nikdy, jen jeho SHA-256."""
+
+    key_hash: str
+    public_id: str
+    client: str
+    scopes: frozenset[str]
+    created_at: datetime
+    agenda: str | None = None
+    expires_at: datetime | None = None
+    revoked_at: datetime | None = None
+    last_used_at: datetime | None = None
+    created_by: str | None = None
+    legacy: bool = False
+
+    def status(self, now: datetime) -> str:
+        if self.revoked_at is not None:
+            return "revoked"
+        if self.expires_at is not None and self.expires_at <= now:
+            return "expired"
+        return "active"
+
+    def is_active(self, now: datetime) -> bool:
+        return self.status(now) == "active"
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """Kdo volá. Vzniká při každém ověření znovu a nikde se nesdílí."""
+
+    client: str
+    scopes: frozenset[str]
+    public_id: str
+    agenda: str | None = None
+    legacy: bool = False
+
+    def has_scopes(self, required: Iterable[str]) -> bool:
+        needed = frozenset(required)
+        return ALL_SCOPES in self.scopes or needed <= self.scopes
+
+    def require_scopes(self, *required: str) -> None:
+        needed = frozenset(required)
+        if not self.has_scopes(needed):
+            raise AuthorizationError(needed - self.scopes)
+
+
+@dataclass(frozen=True, slots=True)
+class IssuedKey:
+    """Výsledek vydání. ``key`` se vrací jednou a knihovna ho už nikde neuchová."""
+
+    record: KeyRecord
+    key: str
+
+
+@dataclass(frozen=True, slots=True)
+class AuditEvent:
+    """Událost pro auditní hook. Nikdy neobsahuje klíč ani jeho hash."""
+
+    action: str
+    client: str
+    actor: str | None
+    public_id: str | None = None
+    detail: tuple[tuple[str, str], ...] = ()