feat: protecao CSRF (double-submit cookie) e paginacao da lista de clientes

CSRF: novo app/csrf.py + middleware em app/main.py garantem um cookie
csrf_token por navegador; todo formulario que muda estado (criar/editar/
excluir cliente, adicionar/editar/excluir contato) embute esse valor
como campo oculto, e Depends(exigir_csrf) confere no POST que o valor
enviado bate com o cookie antes de deixar a rota executar. Verificado
ponta a ponta com o app real rodando (curl): token errado -> 403,
token correto -> 303.

Paginacao: db_clientes.listar_clientes ganha offset, nova
contar_clientes(); GET /clientes aceita ?pagina=N (100 clientes por
pagina), template mostra Anterior/Proxima e o total.

53/53 testes passando (8 novos).

app/main.py

@@ -2,11 +2,12 @@
 Painel de Clientes — monta os routers de CLIENTE, CLIENTE_CONTATO e o
 gerador de chave manual. Ver docs/superpowers/specs/2026-08-13-painel-clientes-web-design.md.
 """
-from fastapi import Depends, FastAPI
+from fastapi import Depends, FastAPI, Request
 from fastapi.responses import RedirectResponse
 from fastapi.staticfiles import StaticFiles
 
 from .auth import exigir_login
+from .csrf import CSRF_COOKIE_NAME, gerar_token
 from .routers import chave_manual, clientes, contatos
 
 app = FastAPI(title="Painel de Clientes", docs_url=None, redoc_url=None, openapi_url=None)
@@ -16,6 +17,27 @@ app.include_router(contatos.router)
 app.include_router(chave_manual.router)
 
 
+@app.middleware("http")
+async def csrf_cookie_middleware(request: Request, call_next):
+    """
+    Garante que todo navegador que acessa o painel tenha um cookie
+    csrf_token (gerado uma vez, HttpOnly). Disponibiliza o valor em
+    request.state.csrf_token para os templates embutirem em formulários —
+    ver app/csrf.py para a validação do lado do POST.
+    """
+    token_existente = request.cookies.get(CSRF_COOKIE_NAME)
+    precisa_definir_cookie = token_existente is None
+    request.state.csrf_token = token_existente or gerar_token()
+
+    response = await call_next(request)
+
+    if precisa_definir_cookie:
+        response.set_cookie(
+            CSRF_COOKIE_NAME, request.state.csrf_token, httponly=True, samesite="strict"
+        )
+    return response
+
+
 @app.get("/")
 def raiz(usuario: str = Depends(exigir_login)):
     return RedirectResponse(url="/clientes")