sysnet-apikeys

Sdílená knihovna pro správu API klíčů FastAPI služeb SYSNET. Rozhodnutí a zdůvodnění: ADR 006 v CML (docs/adr/006-sdilena-knihovna-sysnet-apikeys.md).

Stav: 0.3.0. Jádro, úložiště (paměť, SQL, Mongo, starý YAML jen pro čtení), vazba na FastAPI, admin router a CLI. Pilot: taxonomy 2.7.1 běží na dev (Hermes VM) s APIKEYS_STORE=mongo; produkce zatím ne.

Co řeší

• Klíč se ukládá jako SHA-256, otevřený klíč se vrací jednou při vydání.
• Klient má víc klíčů; rotace vydá nový klíč a starému zkrátí platnost na nyní + grace. Oba platí souběžně.
• Chybějící, neznámý, zrušený i propadlý klíč dává stejnou chybu (nic se nenapovídá útočníkovi).
• Identita se vrací hodnotou (Principal). Nesdílí se stav mezi požadavky, na rozdíl od Context.check_api_key v sysnet-pyutils, který ho v souběhu zaměňuje.
• Nové klíče mají tvar snk_<public_id>_<tajemství>; public_id je bezpečné uvádět v logu a v tiketu.

Instalace

pip install "sysnet-apikeys[fastapi,mongo]"    # nebo [fastapi,sql]; CLI: přidejte cli

Příklad (ověřený spuštěním)

import asyncio
from datetime import timedelta
from typing import Annotated

import httpx
from fastapi import Depends, FastAPI

from sysnet_apikeys import ApiKeyService, InMemoryStore, Principal
from sysnet_apikeys.fastapi import ApiKeyAuth, install_error_handlers

service = ApiKeyService(InMemoryStore())
auth = ApiKeyAuth(service)
app = FastAPI()
install_error_handlers(app)


@app.get("/dokumenty")
async def dokumenty(principal: Annotated[Principal, Depends(auth)]) -> dict[str, str]:
    return {"volá": principal.client}


async def main() -> None:
    old = await service.issue("ippc-docs", scopes=["read"])
    new = await service.rotate("ippc-docs", grace=timedelta(days=1))
    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://t") as c:
        for key in (old.key, new.key):
            print((await c.get("/dokumenty", headers={"X-API-KEY": key})).status_code)


asyncio.run(main())

Výstup: 200 a 200. Starý i nový klíč platí do konce překryvu.

Úložiště

Admin API a CLI

app.include_router(make_admin_router(service, admin_key=os.environ.get("ADMIN_API_KEY")), prefix="/admin")

Proměnná se jmenuje ADMIN_API_KEY stejně jako v notificator a geocode. Bez admin_key vrací admin API 503.

Vygenerování při nasazení (jednou, hodnotu nikdy nevypíše, existující nepřepíše, nový soubor má práva 600):

sysnet-apikeys admin-key /opt/docker/<služba>/.env --ensure   # bez --ensure jen ověří (kód 1 = chybí)

Heslo čtěte ze serveru (grep ^ADMIN_API_KEY= .env), nikam ho neukládejte jinam než do .env. CLI čte úložiště z proměnných APIKEYS_STORE (mongo|sql) a APIKEYS_MONGO_URL/APIKEYS_MONGO_DB nebo APIKEYS_SQL_URL; otevřený klíč tiskne jen issue a rotate. sysnet-apikeys import-yaml conf/x.yml je dry-run, --apply zapíše hashe (klienti se nemění).

Audit (sysnet-audit)

from audit_lib import AuditLogger, MongoAuditBackend
from sysnet_apikeys.audit import audit_hook

service = ApiKeyService(store, audit=audit_hook(AuditLogger(backend=MongoAuditBackend(), service_name="moje-sluzba")))

Vydání, rotace a rušení klíče se zapíše jako api_key.issued|rotated|revoked. Selhání zápisu auditu operaci nezruší. Vyžaduje pip install "sysnet-apikeys[audit]" a inicializovanou Beanie (init_audit).

Migrace ze starého YAML

LegacyYamlStore.from_file("conf/xyz.yml") čte stávající api_keys: [{klíč: jméno}]. Klíče dostanou oprávnění * a Principal.agenda a Principal.client odpovídají dnešnímu agenda a user_name. Úložiště je jen pro čtení.

Vývoj

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest && .venv/bin/ruff check . && .venv/bin/mypy

Testy úložišť potřebují PostgreSQL a MongoDB (APIKEYS_TEST_PG, APIKEYS_TEST_MONGO); bez nich padají, nepřeskakují se.

Verzování: pyproject.toml a sysnet_apikeys/__init__.py musí mít stejnou verzi, tag vX.Y.Z spustí release. Licence: AGPL-3.0 (stejně jako ostatní sdílené knihovny SYSNET).