tempest-fastapi-sdk 0.330.0__tar.gz → 0.331.0__tar.gz

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.331.0] — 2026-10-26
+
+### Added
+
+- `UserAuthService.sse_router(broker)` e `make_sse_router`: stream SSE
+  autenticado pronto. O `EventSource` do browser não manda header, então o
+  stream guardado por `current_user_dependency()` respondia `401` a todo
+  cliente de browser logo depois de um login que deu certo — e a saída
+  documentada, `query_param="access_token"`, punha na URL um token que vale
+  para a API inteira. O router monta `POST <prefix>/ticket` (sessão por
+  header ou cookie, conta ativa) e `GET <prefix>/stream?ticket=`. O ticket é
+  um JWT `typ="stream"` de 60 s com o canal no claim `ch`; nenhuma dependency
+  bearer do SDK aceita esse `typ`. O stream também aceita
+  `Authorization: Bearer` e o cookie do login; `?access_token=` só com
+  `allow_access_token_query=True`, para migrar cliente existente. Novos:
+  `STREAM_TOKEN_TYPE`, `SSETicketResponseSchema`, `DEFAULT_SSE_TICKET_TTL`,
+  `SSE_CHANNEL_CLAIM`, `SSE_TICKET_ERROR`.
+- O stream não segura sessão de banco: guardado por
+  `current_user_dependency(session_dependency=...)`, cada cliente conectado
+  mantinha uma sessão aberta até o disconnect (medido no fastapi 0.141.1),
+  porque a sessão da request só fecha quando a resposta termina. O router
+  carrega o usuário numa sessão própria, fechada antes do stream, e o
+  caminho do ticket não abre sessão.
+- `ServerSettings.SERVER_PUBLIC_SCHEME` (`""`, `"http"`, `"https"`) e
+  `PublicSchemeMiddleware`: atrás de um proxy que termina o TLS, toda URL
+  absoluta saía `http://` — o `action` do formulário de login do admin
+  incluído, e o browser marcava o campo de senha como não seguro. Com
+  `SERVER_PUBLIC_SCHEME=https` o middleware carimba o scheme em toda request
+  (`wss` no websocket). O `tempest new` já registra o middleware.
+- O `GET /admin/login` com `cookie_secure=True` que chega como `http` num host
+  público loga um `WARNING` apontando `SERVER_PUBLIC_SCHEME=https`.
+- `AdminTheme(header_fg=...)` fixa a cor do texto do header e da sidebar
+  quando o palpite pela luminância erra.
+- `AsyncMinIOClient.presigned_post_policy(key, *, max_bytes, content_type=None,
+  min_bytes=0, bucket=None, expires=15min)` devolve um `PresignedPost` (URL +
+  campos do formulário) cuja policy S3 assina a chave, o `Content-Type` e
+  `content-length-range` (#637). Medido em MinIO: 1 byte acima do teto é
+  `400 EntityTooLarge`, abaixo do mínimo `400 EntityTooSmall`, outro tipo ou
+  outra chave `403 AccessDenied`, e nada é gravado na recusa. O
+  `LocalObjectStorageClient` ganhou a mesma chamada, servida pela nova rota
+  `POST` do `make_local_storage_router` (`413 FILE_TOO_LARGE` /
+  `400 FILE_TOO_SMALL` / `403 SIGNED_URL_INVALID`; precisa do extra
+  `[upload]`, checado ao assinar), e o `SubjectObjectStorage` ganhou
+  `presign_post`.
+- `presigned_get_url` (S3 e local) e `SubjectObjectStorage.presign` aceitam
+  `filename`, `media_type` e `as_attachment`, assinados no link — no S3 como
+  os overrides `response-*`, no local amarrados ao propósito da assinatura
+  (`bound_purpose`). Editar um deles na URL dá `403`; sem eles o link é o de
+  antes.
+- `prune_orphan_enum_schemas(app)` tira do OpenAPI os componentes de enum que
+  nenhum `$ref` usa. O FastAPI publica um para todo campo anotado com `Enum`,
+  então um `image_media_type_field` deixava o `ImageMediaType` completo
+  órfão no documento (#637). O `create_app` do `tempest new` já chama.
+- `FileTooSmallException` (`400 FILE_TOO_SMALL`), com mensagem nas duas
+  línguas.
+
+### Changed
+
+- O painel admin ganhou um visual novo (`admin.css` reescrito sobre tokens):
+  header e sidebar claros com a marca à esquerda, cards de métrica com
+  hierarquia, tabela compacta com rolagem horizontal própria, badges para
+  booleanos, form em grid com checkbox em switch, login centralizado com a
+  marca. As classes `tempest-admin-*` existentes continuam; um
+  `custom_css_url` que sobrescrevia cores fixas do header escuro precisa ser
+  revisto.
+- `AdminTheme`: `header_bg` passa de `"#0f172a"` para `"#ffffff"` e `radius`
+  de `"6px"` para `"8px"`. Com um `header_bg`/`sidebar_bg` hex escuro, o
+  texto do chrome passa a claro sozinho (luminância WCAG); cor que não é hex
+  é tratada como escura. `dark_mode=True` agora escurece também os cards e o
+  chrome, enquanto `header_bg` for o padrão.
+- Lista, detalhe e histórico mostram o nome da coluna humanizado
+  (`customer_email` → `Customer email`, `category_id` → `Category`, `id` →
+  `ID`) e formatam o valor: booleano em badge `Yes`/`No`, UUID nos 8 primeiros
+  caracteres com o valor inteiro no `title` (o detalhe mostra inteiro),
+  datetime ao minuto com o offset compacto (`UTC`, `-03:00`) e o instante
+  completo no `title`, `Enum` pelo nome. Export e o `value` do form não mudam.
+- Os rótulos do form seguem a mesma regra (`Price Cents` → `Price cents`,
+  `Category Id` → `Category`).
+- O plural padrão do `verbose_name` segue o inglês regular: `Category` →
+  `Categories`, `Address` → `Addresses` (antes, sempre `+ "s"`).
+- O protocolo `SubjectStorageClient` ganhou `presigned_post_policy` e os
+  parâmetros novos de `presigned_get_url`. `AsyncMinIOClient`,
+  `LocalObjectStorageClient` e `FakeObjectStorageClient` cumprem; um cliente
+  próprio que implemente o protocolo precisa dos dois.
+
+### Fixed
+
+- A busca da lista do admin (`?q=`) e o export comparavam o termo por
+  **igualdade** em cada `search_fields` e exigiam que **todos** fossem iguais
+  ao termo inteiro — `cliente1` não achava `cliente1@mail.com`, e um segundo
+  campo de busca fazia toda busca voltar vazia (#635). Agora cada palavra é
+  um `ILIKE %palavra%` escapado, em OR entre os campos, e toda palavra
+  precisa casar em algum (`like_search_condition`, o mesmo do autocomplete);
+  `%` e `_` são literais.
+- O `admin.css` é servido com `?v=<sha256[:12]>` do arquivo: depois de um
+  upgrade, o browser que tinha a folha antiga em cache desenhava o markup novo
+  com as regras velhas.
+- Cards do dashboard imprimiam `17.0` para contagens vindas de
+  `MetricPartition`/`MetricTrend` em float; inteiro sai sem `.0`.
+- Com `dark_mode=True`, cards, tabelas e dropdowns ficavam brancos
+  (`--tempest-surface` não era sobrescrito).
+
 ## [0.330.0] — 2026-10-25
 
 ### Added

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-fastapi-sdk
-Version: 0.330.0
+Version: 0.331.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -434,7 +434,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `ErrorResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `LogFilesClearedSchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `StorageSettings` (S3-compatible storage; `MinIOSettings` is its deprecated name), `EnvironmentSettings` (`ENV`; `production` refuses development values), `AuthSettings`, `OpenPixSettings` (AppID + ambiente; `openpix_kwargs()`), `HostedGenAISettings` (Anthropic/OpenAI/DeepSeek keys + models; `anthropic_kwargs()` / `openai_kwargs()` / `deepseek_kwargs()`), `reject_conflicting_env_aliases` |
-| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
+| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup), `make_sse_router` / `UserAuthService.sse_router` (authenticated stream for the browser `EventSource`: `POST /sse/ticket` trades the session for a 60 s `typ="stream"` ticket that opens `GET /sse/stream?ticket=` and no other route) |
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX and the `data-confirm` listener locally, no CDN); `htmx()` / `aria()` / `data()` / `confirm()` (typed builders for the `hx-*` / `aria-*` / `data-*` `attrs` map); `FlashMiddleware` + `flash` / `get_flashes` (signed read-once flash cookie), `redirect_back` (Referer validated against host and prefix), `register_html_error_handlers` (error page on GET, flash + 303 on POST, JSON kept for the API); `make_web_app_router` (serve a compiled static/wasm `tempestweb build` as a router, SPA history fallback, `304 Not Modified` on `If-None-Match` / `If-Modified-Since`, `immutable=` globs or an `immutable.json` in the build for year-long `immutable` caching of content-addressed paths), `build_web_app` (host a server-mode build as a WS/SSE sub-app, `theme=` handing a palette to every session's `App`, which the components its `view` builds resolve against), `detect_build_mode` |
 | `tempest_fastapi_sdk.ui` *(extra: `[ssr]`)* | The interface layer, mirroring a service's `src/ui/`: `ui.pages` (`Page` with class-level `stylesheets` / `head` / `title_suffix`, `ErrorPage`), `ui.layout` (`Shell` with `width="full"`, `Grid`), `ui.components` (`Card`, `Alert`, `DataTable`, `TableColumn`, `Pagination`, `EmptyState`, `FlashMessages`, `NavBar`, `component_stylesheet`), `ui.forms` (`form_for`, `form_spec_for`, `render_form`, `parse_form`, `form_dependency`, `FormResult`, `form_stylesheet` — a form generated from a Pydantic schema and read back into it, hidden fields and `UploadFile` uploads included), `ui.css` (`StyleSheet`, `Rule`, `Media`, `ThemeTokens`, `cls`, `make_css_router`, `StyleSheet.url`), `app_stylesheet` |
 | `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`; download through the app with `download_response(key, request=...)`, which honours `Range` and revalidation, `accel_redirect_response` for nginx `X-Accel-Redirect`, and `serve_object`, which picks between them by the constructor's `accel_redirect` — `STORAGE_ACCEL_REDIRECT` / `STORAGE_ACCEL_PREFIX` through `storage_kwargs()`), `ObjectStat`, `PutObjectItem`, batch delete `remove_objects` → `ObjectDeleteError` — async MinIO/S3 facade; `LocalObjectStorageClient` (no extra) answers the same calls from a directory of the server — atomic writes, content type and ETag kept beside each object, `LocalObjectNotFoundError` with `code="NoSuchKey"` — and signs its "presigned" links to the app's own routes, which `make_local_storage_router` serves (`GET` with `Range`, `PUT` capped at `max_upload_bytes`); `StorageSettings.build_storage_client()` picks one by `STORAGE_BACKEND` |
@@ -3109,7 +3109,7 @@ es.addEventListener("counter", (e) => console.log("got", JSON.parse(e.data)));
 
 `heartbeat_seconds` emits a `: keepalive` SSE comment when idle so load-balancers don't close long-lived connections; a frame carrying only `comment`, `id` or `retry` gets no `data:` line, so it never fires `onmessage` (an empty `data:` does — measured in Chromium). `ServerSentEvent.data` accepts strings, bytes or any JSON-serializable Python object — non-strings are JSON-encoded automatically. Pass `retry=` to hint the browser at the reconnect delay (milliseconds).
 
-The queue is **bounded** (`max_queue`, default `1000`): a slow client can't grow memory without limit. `overflow` picks the eviction policy — `"drop_oldest"` (default), `"drop_newest"`, or `"block"` (real backpressure); `EventStream.dropped_events` counts the discards. For broadcast, `SSEBroker.response(channel)` bundles `register` + `sse_response` + `unregister`-on-disconnect in one call. Authenticating an `EventSource` (which can't send an `Authorization` header): prefer a session cookie (`make_jwt_user_dependency(..., cookie_name="access_token")` + `withCredentials`); for cookieless clients pass a short-lived access token in the query string with `query_param="access_token"` (over TLS, scrubbed from logs). See the [SSE recipe](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/sse/) for the full guide.
+The queue is **bounded** (`max_queue`, default `1000`): a slow client can't grow memory without limit. `overflow` picks the eviction policy — `"drop_oldest"` (default), `"drop_newest"`, or `"block"` (real backpressure); `EventStream.dropped_events` counts the discards. For broadcast, `SSEBroker.response(channel)` bundles `register` + `sse_response` + `unregister`-on-disconnect in one call. Authenticating an `EventSource` (which can't send an `Authorization` header): mount `auth_service.sse_router(broker)` — the client trades its session for a ticket on `POST /sse/ticket` and opens `GET /sse/stream?ticket=...`; the ticket is a 60 s `typ="stream"` JWT that every bearer guard refuses, so the URL never carries a session. A header or the login cookie also opens the stream; `allow_access_token_query=True` keeps an existing `?access_token=` client working while it migrates. See the [SSE recipe](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/sse/) for the full guide.
 
 ### Web Push notifications recipe
 

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/README.md

@@ -212,7 +212,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `ErrorResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `LogFilesClearedSchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `StorageSettings` (S3-compatible storage; `MinIOSettings` is its deprecated name), `EnvironmentSettings` (`ENV`; `production` refuses development values), `AuthSettings`, `OpenPixSettings` (AppID + ambiente; `openpix_kwargs()`), `HostedGenAISettings` (Anthropic/OpenAI/DeepSeek keys + models; `anthropic_kwargs()` / `openai_kwargs()` / `deepseek_kwargs()`), `reject_conflicting_env_aliases` |
-| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
+| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup), `make_sse_router` / `UserAuthService.sse_router` (authenticated stream for the browser `EventSource`: `POST /sse/ticket` trades the session for a 60 s `typ="stream"` ticket that opens `GET /sse/stream?ticket=` and no other route) |
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX and the `data-confirm` listener locally, no CDN); `htmx()` / `aria()` / `data()` / `confirm()` (typed builders for the `hx-*` / `aria-*` / `data-*` `attrs` map); `FlashMiddleware` + `flash` / `get_flashes` (signed read-once flash cookie), `redirect_back` (Referer validated against host and prefix), `register_html_error_handlers` (error page on GET, flash + 303 on POST, JSON kept for the API); `make_web_app_router` (serve a compiled static/wasm `tempestweb build` as a router, SPA history fallback, `304 Not Modified` on `If-None-Match` / `If-Modified-Since`, `immutable=` globs or an `immutable.json` in the build for year-long `immutable` caching of content-addressed paths), `build_web_app` (host a server-mode build as a WS/SSE sub-app, `theme=` handing a palette to every session's `App`, which the components its `view` builds resolve against), `detect_build_mode` |
 | `tempest_fastapi_sdk.ui` *(extra: `[ssr]`)* | The interface layer, mirroring a service's `src/ui/`: `ui.pages` (`Page` with class-level `stylesheets` / `head` / `title_suffix`, `ErrorPage`), `ui.layout` (`Shell` with `width="full"`, `Grid`), `ui.components` (`Card`, `Alert`, `DataTable`, `TableColumn`, `Pagination`, `EmptyState`, `FlashMessages`, `NavBar`, `component_stylesheet`), `ui.forms` (`form_for`, `form_spec_for`, `render_form`, `parse_form`, `form_dependency`, `FormResult`, `form_stylesheet` — a form generated from a Pydantic schema and read back into it, hidden fields and `UploadFile` uploads included), `ui.css` (`StyleSheet`, `Rule`, `Media`, `ThemeTokens`, `cls`, `make_css_router`, `StyleSheet.url`), `app_stylesheet` |
 | `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`; download through the app with `download_response(key, request=...)`, which honours `Range` and revalidation, `accel_redirect_response` for nginx `X-Accel-Redirect`, and `serve_object`, which picks between them by the constructor's `accel_redirect` — `STORAGE_ACCEL_REDIRECT` / `STORAGE_ACCEL_PREFIX` through `storage_kwargs()`), `ObjectStat`, `PutObjectItem`, batch delete `remove_objects` → `ObjectDeleteError` — async MinIO/S3 facade; `LocalObjectStorageClient` (no extra) answers the same calls from a directory of the server — atomic writes, content type and ETag kept beside each object, `LocalObjectNotFoundError` with `code="NoSuchKey"` — and signs its "presigned" links to the app's own routes, which `make_local_storage_router` serves (`GET` with `Range`, `PUT` capped at `max_upload_bytes`); `StorageSettings.build_storage_client()` picks one by `STORAGE_BACKEND` |
@@ -2887,7 +2887,7 @@ es.addEventListener("counter", (e) => console.log("got", JSON.parse(e.data)));
 
 `heartbeat_seconds` emits a `: keepalive` SSE comment when idle so load-balancers don't close long-lived connections; a frame carrying only `comment`, `id` or `retry` gets no `data:` line, so it never fires `onmessage` (an empty `data:` does — measured in Chromium). `ServerSentEvent.data` accepts strings, bytes or any JSON-serializable Python object — non-strings are JSON-encoded automatically. Pass `retry=` to hint the browser at the reconnect delay (milliseconds).
 
-The queue is **bounded** (`max_queue`, default `1000`): a slow client can't grow memory without limit. `overflow` picks the eviction policy — `"drop_oldest"` (default), `"drop_newest"`, or `"block"` (real backpressure); `EventStream.dropped_events` counts the discards. For broadcast, `SSEBroker.response(channel)` bundles `register` + `sse_response` + `unregister`-on-disconnect in one call. Authenticating an `EventSource` (which can't send an `Authorization` header): prefer a session cookie (`make_jwt_user_dependency(..., cookie_name="access_token")` + `withCredentials`); for cookieless clients pass a short-lived access token in the query string with `query_param="access_token"` (over TLS, scrubbed from logs). See the [SSE recipe](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/sse/) for the full guide.
+The queue is **bounded** (`max_queue`, default `1000`): a slow client can't grow memory without limit. `overflow` picks the eviction policy — `"drop_oldest"` (default), `"drop_newest"`, or `"block"` (real backpressure); `EventStream.dropped_events` counts the discards. For broadcast, `SSEBroker.response(channel)` bundles `register` + `sse_response` + `unregister`-on-disconnect in one call. Authenticating an `EventSource` (which can't send an `Authorization` header): mount `auth_service.sse_router(broker)` — the client trades its session for a ticket on `POST /sse/ticket` and opens `GET /sse/stream?ticket=...`; the ticket is a 60 s `typ="stream"` JWT that every bearer guard refuses, so the URL never carries a session. A header or the login cookie also opens the stream; `allow_access_token_query=True` keeps an existing `?access_token=` client working while it migrates. See the [SSE recipe](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/sse/) for the full guide.
 
 ### Web Push notifications recipe
 

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/SHIPPED.md

@@ -601,7 +601,12 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   (per-channel fan-out; `SSEBroker.response(channel)` bundles
   register + response + unregister-on-disconnect; in-memory
   single-process, or multi-worker via an injected Redis pub/sub bridge
-  — same call site).
+  — same call site). Authenticated stream for the browser `EventSource`:
+  `UserAuthService.sse_router(broker)` / `make_sse_router` mount
+  `POST <prefix>/ticket` + `GET <prefix>/stream?ticket=` — a 60 s
+  `typ="stream"` JWT carrying the channel, refused by every bearer guard;
+  header and login cookie also open the stream, `?access_token=` only behind
+  `allow_access_token_query=True`; no DB session held while streaming.
 - **Throttle** — `AttemptThrottle` (any `ThrottleBackend`, e.g.
   `redis.asyncio.Redis`) and, since v0.306.0, the bundled
   `InMemoryThrottleBackend` (process-local, `clock=` injectable for
@@ -3785,16 +3790,16 @@ cadastro pendente comum. Com `AUTH_AUTO_ACTIVATE=true` o cadastro não consulta
   Receita: `docs/recipes/auth-pages.md`. Testes:
   `tests/auth/test_auth_pages.py`.
 - **Helpers de login do admin aceitam `httpx2`/`TestClient` no strict,
-  Unreleased (#610)** — `admin_login` / `admin_login_sync` tipados por
+  v0.329.0 (#610)** — `admin_login` / `admin_login_sync` tipados por
   `AsyncFormClient` / `SyncFormClient` / `FormResponse` (`Protocol`s públicos
   em `tempest_fastapi_sdk.testing`), genéricos na resposta. Teste:
   `tests/testing/test_admin_login_typing.py` (mypy `--strict` sobre o uso de
   cada cliente).
-- **Import preguiçoso da raiz, Unreleased (#611)** — `__init__` da raiz e de
+- **Import preguiçoso da raiz, v0.329.0 (#611)** — `__init__` da raiz e de
   `utils` em PEP 562 (`_LAZY_ATTRIBUTES` + `__getattr__` escondido do checker
   + imports em `TYPE_CHECKING`); `tempest --help` 0,94 s → 0,14 s. Guard:
   `tests/test_lazy_init_guard.py`.
-- **Storage em disco local, Unreleased** — `LocalObjectStorageClient`
+- **Storage em disco local, v0.328.0** — `LocalObjectStorageClient`
   (`storage/local_client.py`, sem extra) implementa o `SubjectStorageClient`
   inteiro sobre um diretório: `objects/<bucket>/<key>`, metadado (content type,
   metadata, ETag MD5) em `meta/<bucket>/<key>.meta.json`, escrita em `tmp/` +
@@ -3812,3 +3817,49 @@ cadastro pendente comum. Com `AUTH_AUTO_ACTIVATE=true` o cadastro não consulta
   `docs/recipes/local-storage.md`. Testes:
   `tests/storage/test_local_client.py`, `tests/storage/test_local_router.py`,
   `tests/settings/test_storage_settings.py::TestLocalBackend`.
+- **Visual novo do admin, v0.331.0 (2026-10-26)** — `admin.css` reescrito sobre tokens
+  (`--tempest-surface`, `--tempest-border`, `--tempest-*-soft` derivados por
+  `color-mix()`): chrome claro com a marca à esquerda, sidebar com item ativo
+  suave, cards de métrica, tabela com rolagem horizontal própria, form em
+  grid de duas colunas com checkbox em switch, login centralizado. O
+  `AdminTheme` passa a `header_bg="#ffffff"` e `radius="8px"`, ganha
+  `header_fg` e escolhe o texto do header/sidebar pela luminância do fundo; o
+  `dark_mode` cobre os cards e escurece o chrome padrão. `admin/display.py`
+  formata célula e rótulo (`humanize_field`, `cell_view`: booleano em badge,
+  UUID curto com o valor inteiro no `title`, datetime ao minuto com offset
+  compacto, inteiro sem `.0`), e o plural do `verbose_name` segue o inglês
+  regular (`Categories`). O link do CSS leva `?v=<sha256[:12]>` do arquivo,
+  para o browser não servir a folha antiga depois de um upgrade. Validado em
+  browser real (1440 e 390, burger, criação, busca, lens, dark mode). Testes:
+  `tests/admin/test_display.py`.
+- **Scheme público atrás de proxy, v0.331.0 (2026-10-26)** — `ServerSettings` ganha
+  `SERVER_PUBLIC_SCHEME` e `api/middlewares/public_scheme.py` o
+  `PublicSchemeMiddleware`, que carimba `scope["scheme"]` (`ws`/`wss` no
+  websocket, `lifespan` intocado). Declarado em vez de lido de
+  `X-Forwarded-Proto` porque porta publicada deixa forjar header encaminhado.
+  Veio do `alofans-api` (commit `a3f4cb9e`), onde cada serviço tinha a sua
+  cópia; o `transport-backend` não tinha e o login do admin aparecia como não
+  seguro em produção. O `make_admin_router` loga `WARNING` no login servido
+  como `http` em host público com `cookie_secure=True`, e o template do
+  `tempest new` registra o middleware. Receita: `docs/recipes/security.md`.
+  Testes: `tests/api/test_public_scheme_middleware.py`,
+  `tests/admin/test_login_scheme_warning.py`,
+  `tests/settings/test_public_scheme.py`.
+- **Upload com teto e download com tipo assinado no storage, v0.331.0 (2026-10-26)
+  (#637)** — `presigned_post_policy` no `AsyncMinIOClient` (policy S3 com
+  `eq key`, `eq Content-Type` e `content-length-range`; assinatura local, sem
+  rede, com o `DeprecationWarning` do `datetime.utcnow()` do minio 7.2.20
+  silenciado no ponto da chamada) e no `LocalObjectStorageClient` (rota
+  `POST` multipart no `make_local_storage_router`, limites amarrados à
+  assinatura por `bound_purpose`); `SubjectObjectStorage.presign_post`;
+  `filename`/`media_type`/`as_attachment` assinados no `presigned_get_url` dos
+  dois backends e no `presign`. `prune_orphan_enum_schemas` remove do OpenAPI
+  o enum que o FastAPI publica sem `$ref` (o `ImageMediaType` do
+  `image_media_type_field`); o scaffold chama. Testes:
+  `tests/storage/test_presign.py`, `tests/storage/test_local_presign.py`,
+  `tests/storage/test_presign_live.py` (docker), `tests/api/test_openapi_pruning.py`.
+- **Busca do admin por trecho, v0.331.0 (2026-10-26) (#635)** — `?q=` da lista e do
+  export passa por `like_search_condition` (ILIKE escapado por palavra, OR
+  entre `search_fields`, todas as palavras) via `where=` do `paginate`, em vez
+  de `filters[field] = q` (igualdade com AND). Teste:
+  `tests/admin/test_search.py` (8 dos 10 casos falham no código antigo).

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/docs/migration.en.md

@@ -2,6 +2,38 @@
 
 Breaking-change walkthroughs grouped by minor release. Stick to the version that matches what you're upgrading **from**. The release sections are listed newest-first, so on a multi-version jump read and apply them bottom-up.
 
+## 0.331.0 — new admin look, capped storage uploads
+
+`admin.css` was rewritten on tokens and `AdminTheme` changed two defaults:
+`header_bg` goes from `"#0f172a"` to `"#ffffff"` and `radius` from `"6px"`
+to `"8px"`. The `tempest-admin-*` classes stay.
+
+The `SubjectStorageClient` protocol gained `presigned_post_policy`, and
+`presigned_get_url` gained `filename`, `media_type` and `as_attachment`.
+
+The admin list search (`?q=`) now matches a substring in any of the
+`search_fields`; it used to compare by equality in all of them.
+
+### What to do
+
+1. If you pass `custom_css_url` overriding fixed colors of the dark header:
+   review the sheet against the light header.
+2. To keep a dark header, pass `AdminTheme(header_bg="#0f172a")`: the chrome
+   text turns light on its own from the luminance. If the guess is wrong,
+   pin it with `header_fg=`.
+3. Behind a proxy that terminates TLS, use the upgrade to declare
+   `SERVER_PUBLIC_SCHEME=https` and register the `PublicSchemeMiddleware`
+   ([Security](recipes/security.md#public-scheme-behind-a-proxy-server_public_scheme)):
+   without it the admin login shows as not secure.
+4. A storage client of yours implementing `SubjectStorageClient` needs
+   `presigned_post_policy` and the three new `presigned_get_url` parameters
+   to keep passing the type-checker. `AsyncMinIOClient`,
+   `LocalObjectStorageClient` and `FakeObjectStorageClient` already comply.
+5. A service that generates a client from the OpenAPI and uses
+   `image_media_type_field`: call `prune_orphan_enum_schemas(app)` in
+   `create_app` to drop the orphan `ImageMediaType`
+   ([Uploads](recipes/uploads.md)).
+
 ## 0.330.0 — a push subscription no longer changes owner
 
 `POST /subscribe` (Web Push) and `POST /register` (mobile push) no longer

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/docs/migration.md

@@ -2,6 +2,39 @@
 
 Passo a passo das mudanças que quebram compatibilidade, agrupadas por release minor. Siga a versão que casa com aquela **de onde** você está atualizando. As seções estão listadas da mais nova para a mais antiga, então num salto de várias versões leia e aplique-as de baixo para cima.
 
+## 0.331.0 — visual novo do admin, upload com teto no storage
+
+O `admin.css` foi reescrito sobre tokens e o `AdminTheme` mudou dois
+defaults: `header_bg` passa de `"#0f172a"` para `"#ffffff"` e `radius` de
+`"6px"` para `"8px"`. As classes `tempest-admin-*` continuam.
+
+O protocolo `SubjectStorageClient` ganhou `presigned_post_policy`, e
+`presigned_get_url` ganhou `filename`, `media_type` e `as_attachment`.
+
+A busca da lista do admin (`?q=`) passa a procurar por trecho em qualquer
+`search_fields`; antes comparava por igualdade em todos.
+
+### O que fazer
+
+1. Quem passa `custom_css_url` sobrescrevendo cores fixas do header escuro:
+   revise a folha contra o header claro.
+2. Para manter o header escuro, passe `AdminTheme(header_bg="#0f172a")`: o
+   texto do chrome passa a claro sozinho pela luminância. Se o palpite errar,
+   fixe com `header_fg=`.
+3. Atrás de um proxy que termina o TLS, aproveite o upgrade para declarar
+   `SERVER_PUBLIC_SCHEME=https` e registrar o `PublicSchemeMiddleware`
+   ([Segurança](recipes/security.md#scheme-publico-atras-de-proxy-server_public_scheme)):
+   sem isso o login do admin aparece como não seguro.
+4. Um cliente de storage seu que implemente `SubjectStorageClient` precisa
+   de `presigned_post_policy` e dos três parâmetros novos de
+   `presigned_get_url` para continuar passando no type-checker.
+   `AsyncMinIOClient`, `LocalObjectStorageClient` e `FakeObjectStorageClient`
+   já cumprem.
+5. Serviço que gera cliente a partir do OpenAPI e usa
+   `image_media_type_field`: chame `prune_orphan_enum_schemas(app)` no
+   `create_app` para tirar o `ImageMediaType` órfão
+   ([Uploads](recipes/uploads.md)).
+
 ## 0.330.0 — inscrição de push não muda mais de dono
 
 `POST /subscribe` (Web Push) e `POST /register` (push mobile) não

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/docs/recipes/admin.en.md

@@ -204,7 +204,7 @@ app.include_router(
 - `GET  /admin/` — dashboard: a card per model with its **live row count** + Browse/New, plus a **metrics panel** (CPU/RAM/disk via `MetricsUtils`). On by default, omitted without the `[metrics]` extra, disable with `make_admin_router(show_metrics=False)`.
 - `GET  /admin/logs` — **application logs** (when `show_logs=True`): reads the structured JSON files written by `configure_logging(log_dir=…)`, with source filter (`?source=`), free-text search (`?q=`) and pagination. Color-coded level badges. Renders an empty state when no log files exist yet.
 - `GET  /admin/logs/export` — **log export** (`?format=md|json`): downloads the filtered selection as markdown (traceback in a fenced block, ready to paste into an issue) or verbatim JSON.
-- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`) + per-field filters (`?filter_<field>=value`) + clickable **column sorting** (`?sort=<column>&dir=asc|desc`).
+- `GET  /admin/m/{slug}/` — list view with pagination + free-text search (`?q=`: each word matched as a case-insensitive substring in any of the `search_fields`, and every word must appear; `%` and `_` are literal) + per-field filters (`?filter_<field>=value`) + clickable **column sorting** (`?sort=<column>&dir=asc|desc`).
 - `GET  /admin/m/{slug}/export.csv` / `export.json` — **export** the current result set (honoring search/filters/sort) as CSV or JSON. Row cap via `make_admin_router(export_max_rows=…)` (default 5000).
 - `POST /admin/m/{slug}/bulk` — **bulk actions** (delete / activate / deactivate + your **custom actions**) on the selected rows.
 - `GET/POST /admin/m/{slug}/new` — **create** a record (when `can_create`).
@@ -934,8 +934,8 @@ site.register(
 What changes, and nothing else:
 
 - **List and detail** convert every `datetime` to the zone and print the
-  offset with it (`2026-06-15 20:00:00-03:00`), so the screen is never
-  ambiguous.
+  offset with it (`2026-06-15 20:00 -03:00`; the full instant is in the
+  tooltip), so the screen is never ambiguous.
 - **The form** pre-fills the box with the local hour
   (`2026-06-15T20:00`) and writes `Timezone: America/Sao_Paulo — stored
   as UTC.` underneath, because `datetime-local` has nowhere to say it.
@@ -1046,6 +1046,14 @@ and export; "All" clears it.
     this flag to `DEBUG` — turning debug on in production is worse than the
     original problem.
 
+!!! warning "Browser says the login form is not secure? It's the scheme behind the proxy"
+    With HTTPS in front and the proxy speaking HTTP to the app, the form's
+    `action` comes out as `http://...` and the browser flags the password
+    field as not secure. Set `SERVER_PUBLIC_SCHEME=https` and add
+    `PublicSchemeMiddleware` — recipe in
+    [Security](security.md#public-scheme-behind-a-proxy-server_public_scheme).
+    Until then, `GET /admin/login` logs a `WARNING` saying so.
+
 ##### Signing in from a test
 
 Since `POST /admin/login` requires the form's token, a test that posts the credentials alone gets `403`. `tempest_fastapi_sdk.testing` does what a browser does — loads the form, reads the hidden field (the cookie lands in the client's jar) and submits it:
@@ -1408,13 +1416,13 @@ from tempest_fastapi_sdk import AdminSite, AdminTheme
 theme: AdminTheme = AdminTheme(
     accent="#7c3aed",                       # primary color (links, buttons, active item)
     accent_hover="#6d28d9",                 # hover shade of the accent
-    header_bg="#1e1b4b",                    # header/sidebar background
+    header_bg="#1e1b4b",                    # header/sidebar background (text turns light on its own)
     radius="10px",                          # radius of buttons, inputs, cards, tables
     font_family="'Inter', system-ui, sans-serif",
     logo_url="/admin/static/logo.svg",      # header image (instead of the text brand)
     favicon_url="/admin/static/favicon.ico",
     footer_text="Servus | 2026",
-    dark_mode=False,                         # dark content surfaces
+    dark_mode=False,                         # dark surfaces
 )
 
 site: AdminSite = AdminSite(title="Servus Admin", brand="Servus", theme=theme)
@@ -1433,23 +1441,33 @@ site: AdminSite = AdminSite(title="Servus Admin", brand="Servus", theme=theme)
 | `accent` | `str` | `"#2563eb"` | Primary color: links, buttons, active sidebar item |
 | `accent_hover` | `str` | `"#1d4ed8"` | Hover/active shade of `accent` |
 | `danger` | `str` | `"#b91c1c"` | Destructive actions and error messages |
-| `header_bg` | `str` | `"#0f172a"` | Header background |
+| `header_bg` | `str` | `"#ffffff"` | Header background |
 | `sidebar_bg` | ``str | None`` | `None` | Sidebar background (falls back to `header_bg`) |
+| `header_fg` | ``str | None`` | `None` | Header and sidebar text color (`None` picks it from the background contrast) |
 | `page_bg` | ``str | None`` | `None` | Content background (mode default) |
-| `radius` | `str` | `"6px"` | Radius of buttons, inputs, cards, tables |
+| `radius` | `str` | `"8px"` | Radius of buttons, inputs, cards, tables |
 | `font_family` | ``str | None`` | `None` | `font-family` for the whole panel |
 | `logo_url` | ``str | None`` | `None` | Header image instead of the text brand |
 | `logo_alt` | `str` | `"Logo"` | `alt` text for the logo image |
 | `favicon_url` | ``str | None`` | `None` | Browser-tab favicon |
 | `footer_text` | `str` | `"Powered by tempest-fastapi-sdk"` | Footer text |
-| `dark_mode` | `bool` | `False` | Dark content surfaces |
+| `dark_mode` | `bool` | `False` | Dark surfaces (and the chrome, while `header_bg` is the default) |
 | `custom_css_url` | ``str | None`` | `None` | Extra stylesheet, linked last |
 
 !!! info "Dark mode"
     `dark_mode=True` switches the **content surfaces** (page background,
-    text, table rows, inputs, borders) to a dark palette. The
-    header/sidebar are already dark, so they are unaffected; `accent` and
-    the other colors still apply. An explicit `page_bg` wins over dark mode.
+    cards, text, table rows, inputs, borders) to a dark palette. The header
+    and sidebar go dark with them while `header_bg` is the light default;
+    a `header_bg` of yours is kept. `accent` and the other colors still
+    apply. An explicit `page_bg` wins over the content's dark mode (the
+    surfaces stay light), but the default chrome still goes dark.
+
+!!! info "Header text picked from the background"
+    The header and sidebar are light by default. Give them a dark hex
+    `header_bg` (or `sidebar_bg`) and their text turns light on its own —
+    the SDK computes the background's luminance. A color that is not hex
+    (`"rebeccapurple"`, `rgb(...)`) is treated as dark; when that guess is
+    wrong, pin the color with `header_fg`.
 
 !!! warning "Escape hatch for the rest"
     For anything the fields do not cover, point `custom_css_url` at your own

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/docs/recipes/admin.md

@@ -187,7 +187,7 @@ app.include_router(
 - `GET  /admin/` — dashboard: card por modelo com **contagem de linhas** + Browse/New, e um **painel de métricas** (CPU/RAM/disco via `MetricsUtils`). Painel ligado por default, omitido sem o extra `[metrics]`, desligável com `make_admin_router(show_metrics=False)`.
 - `GET  /admin/logs` — **logs da aplicação** (quando `show_logs=True`): lê os arquivos JSON estruturados escritos pelo `configure_logging(log_dir=…)`, com filtro por fonte (`?source=`), busca em texto (`?q=`) e paginação. Badges coloridos por nível. Quando ainda não há arquivos de log, mostra um estado vazio.
 - `GET  /admin/logs/export` — **export dos logs** (`?format=md|json`): baixa a seleção filtrada como markdown (traceback em bloco cercado, pronto para colar em issue) ou JSON verbatim.
-- `GET  /admin/m/{slug}/` — list view com paginação + busca em texto livre (`?q=`) + filtros por campo (`?filter_<field>=value`) + **ordenação por coluna** clicável (`?sort=<coluna>&dir=asc|desc`).
+- `GET  /admin/m/{slug}/` — list view com paginação + busca em texto livre (`?q=`: cada palavra procurada por trecho, sem diferenciar maiúscula, em qualquer um dos `search_fields`, e toda palavra precisa aparecer; `%` e `_` são literais) + filtros por campo (`?filter_<field>=value`) + **ordenação por coluna** clicável (`?sort=<coluna>&dir=asc|desc`).
 - `GET  /admin/m/{slug}/export.csv` / `export.json` — **exporta** o resultado atual (respeitando busca/filtros/ordenação) como CSV ou JSON. Limite de linhas via `make_admin_router(export_max_rows=…)` (default 5000).
 - `POST /admin/m/{slug}/bulk` — **ações em massa** (delete / activate / deactivate + suas **ações customizadas**) nas linhas selecionadas.
 - `GET/POST /admin/m/{slug}/new` — **criar** registro (quando `can_create`).
@@ -914,8 +914,8 @@ site.register(
 O que muda, e só isso:
 
 - **Listagem e detail** convertem cada `datetime` para o fuso e mostram
-  o offset junto (`2026-06-15 20:00:00-03:00`), então a tela nunca é
-  ambígua.
+  o offset junto (`2026-06-15 20:00 -03:00`; o instante completo fica no
+  tooltip), então a tela nunca é ambígua.
 - **Form** pré-preenche a caixa com a hora local (`2026-06-15T20:00`) e
   escreve `Timezone: America/Sao_Paulo — stored as UTC.` embaixo, porque
   o `datetime-local` não tem onde dizer isso sozinho.
@@ -1025,6 +1025,14 @@ volta ao padrão.
     `cookie_secure=False`, ciente de que a sessão vai sem `Secure`. Não amarre
     esse flag ao `DEBUG` — ligar debug em produção é pior que o problema original.
 
+!!! warning "O browser diz que o formulário de login não é seguro? É o scheme atrás do proxy"
+    Com HTTPS na frente e o proxy falando HTTP com a app, o `action` do
+    formulário sai `http://...` e o browser marca o campo de senha como não
+    seguro. Declare `SERVER_PUBLIC_SCHEME=https` e adicione o
+    `PublicSchemeMiddleware` — receita em
+    [Segurança](security.md#scheme-publico-atras-de-proxy-server_public_scheme).
+    Enquanto falta, o `GET /admin/login` loga um `WARNING` dizendo isso.
+
 ##### Logar em teste
 
 Como o `POST /admin/login` exige o token do formulário, teste que posta só as credenciais leva `403`. `tempest_fastapi_sdk.testing` faz o que o navegador faz — abre o formulário, lê o hidden (o cookie fica no jar do cliente) e envia:
@@ -1387,13 +1395,13 @@ from tempest_fastapi_sdk import AdminSite, AdminTheme
 theme: AdminTheme = AdminTheme(
     accent="#7c3aed",                       # cor primária (links, botões, item ativo)
     accent_hover="#6d28d9",                 # tom de hover do accent
-    header_bg="#1e1b4b",                    # fundo do header/sidebar
+    header_bg="#1e1b4b",                    # fundo do header/sidebar (texto fica claro sozinho)
     radius="10px",                          # raio de botões, inputs, cards, tabelas
     font_family="'Inter', system-ui, sans-serif",
     logo_url="/admin/static/logo.svg",      # imagem no header (no lugar do texto)
     favicon_url="/admin/static/favicon.ico",
     footer_text="Servus | 2026",
-    dark_mode=False,                         # superfícies de conteúdo escuras
+    dark_mode=False,                         # superfícies escuras
 )
 
 site: AdminSite = AdminSite(title="Servus Admin", brand="Servus", theme=theme)
@@ -1412,23 +1420,34 @@ site: AdminSite = AdminSite(title="Servus Admin", brand="Servus", theme=theme)
 | `accent` | `str` | `"#2563eb"` | Cor primária: links, botões, item ativo da sidebar |
 | `accent_hover` | `str` | `"#1d4ed8"` | Tom de hover/ativo do `accent` |
 | `danger` | `str` | `"#b91c1c"` | Ações destrutivas e mensagens de erro |
-| `header_bg` | `str` | `"#0f172a"` | Fundo do header |
+| `header_bg` | `str` | `"#ffffff"` | Fundo do header |
 | `sidebar_bg` | ``str | None`` | `None` | Fundo da sidebar (cai pra `header_bg`) |
+| `header_fg` | ``str | None`` | `None` | Cor do texto do header e da sidebar (`None` escolhe pelo contraste do fundo) |
 | `page_bg` | ``str | None`` | `None` | Fundo do conteúdo (padrão do modo) |
-| `radius` | `str` | `"6px"` | Raio de botões, inputs, cards, tabelas |
+| `radius` | `str` | `"8px"` | Raio de botões, inputs, cards, tabelas |
 | `font_family` | ``str | None`` | `None` | `font-family` do painel inteiro |
 | `logo_url` | ``str | None`` | `None` | Imagem no header em vez do texto |
 | `logo_alt` | `str` | `"Logo"` | `alt` da imagem do logo |
 | `favicon_url` | ``str | None`` | `None` | Favicon da aba |
 | `footer_text` | `str` | `"Powered by tempest-fastapi-sdk"` | Texto do rodapé |
-| `dark_mode` | `bool` | `False` | Superfícies de conteúdo escuras |
+| `dark_mode` | `bool` | `False` | Superfícies escuras (e o chrome, se `header_bg` for o padrão) |
 | `custom_css_url` | ``str | None`` | `None` | Folha de estilo extra, linkada por último |
 
 !!! info "Modo escuro"
     `dark_mode=True` troca as **superfícies de conteúdo** (fundo da página,
-    texto, linhas da tabela, inputs, bordas) para uma paleta escura. O
-    header/sidebar já são escuros, então não mudam; `accent` e as outras
-    cores continuam valendo. Um `page_bg` explícito vence o modo escuro.
+    cards, texto, linhas da tabela, inputs, bordas) para uma paleta escura.
+    O header e a sidebar escurecem junto enquanto `header_bg` for o padrão
+    claro; um `header_bg` seu é mantido. `accent` e as outras cores
+    continuam valendo. Um `page_bg` explícito vence o modo escuro do
+    conteúdo (as superfícies ficam claras), mas o chrome padrão escurece
+    mesmo assim.
+
+!!! info "Texto do header escolhido pelo fundo"
+    O header e a sidebar são claros por padrão. Com um `header_bg` (ou
+    `sidebar_bg`) em hex escuro, o texto deles passa para claro sozinho —
+    a SDK calcula a luminância do fundo. Cor que não é hex
+    (`"rebeccapurple"`, `rgb(...)`) é tratada como escura; se o palpite
+    errar, fixe a cor com `header_fg`.
 
 !!! warning "Escape hatch para o resto"
     Para o que os campos não cobrem, aponte `custom_css_url` para a sua

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/docs/recipes/auth-flow.en.md

@@ -2736,7 +2736,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
     The dependency tries **header → cookie → query string** and stops at the first hit, so the single line above serves both bearer clients and cookie clients.
 
     - **Cookie — automatic.** With `AUTH_TOKEN_DELIVERY` set to `"cookie"` or `"both"`, `cookie_name` is **auto-derived** from `AUTH_ACCESS_COOKIE_NAME` — the same cookie the bundled `/auth/login` set. Zero extra wiring: a route guarded by this dependency already accepts that cookie. A bearer-only delivery mode leaves it `None` (header only). Pass `cookie_name="..."` to force a name.
-    - **Query string — opt-in.** Never auto-derived. It exists for clients that can send neither a header **nor** a cookie — the classic case being the browser `EventSource` (SSE) cross-origin:
+    - **Query string — opt-in.** Never auto-derived. It exists for clients that can send neither a header **nor** a cookie. For **SSE**, don't turn this on by hand: `auth_service.sse_router(broker)` trades the session for a stream ticket that is valid on no other route. Raw `query_param` is for the rest:
 
     ```python
     # src/api/dependencies/auth.py
@@ -2748,7 +2748,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
     )
     ```
 
-    Full SSE walkthrough in the [SSE recipe »](sse.md#authentication-cookie-or-query-string).
+    Full SSE walkthrough in the [SSE recipe »](sse.md#authentication).
 
 !!! warning "A token in the URL leaks"
     Query strings land in access logs, browser history and the `Referer` header. Enable `query_param` only over TLS, only with a **short-lived access token** (never a refresh token), and scrub the value from your log format. When the client shares the API's origin, prefer a session cookie (`withCredentials`).

{tempest_fastapi_sdk-0.330.0 → tempest_fastapi_sdk-0.331.0}/docs/recipes/auth-flow.md

@@ -2708,7 +2708,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
     A dependency tenta **header → cookie → query string** e para no primeiro hit, então a mesma linha acima serve cliente bearer e cliente cookie.
 
     - **Cookie — automático.** Com `AUTH_TOKEN_DELIVERY` em `"cookie"` ou `"both"`, o `cookie_name` é **auto-derivado** de `AUTH_ACCESS_COOKIE_NAME`, o mesmo cookie que o `/auth/login` bundled setou. Zero wiring extra: rota guardada por essa dependency já aceita o cookie. Em delivery bearer-only fica `None` (só header). Passe `cookie_name="..."` pra forçar um nome.
-    - **Query string — opt-in.** Nunca é auto-derivada. Serve pra cliente que não consegue mandar header **nem** cookie — caso clássico é o `EventSource` do browser (SSE) cross-origin:
+    - **Query string — opt-in.** Nunca é auto-derivada. Serve pra cliente que não consegue mandar header **nem** cookie. Para **SSE**, não ligue isto na mão: o `auth_service.sse_router(broker)` troca a sessão por um ticket de stream que não vale em nenhuma outra rota. O `query_param` cru fica para o resto:
 
     ```python
     # src/api/dependencies/auth.py
@@ -2720,7 +2720,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
     )
     ```
 
-    Detalhe do fluxo SSE na [receita SSE »](sse.md#autenticacao-cookie-ou-query-string).
+    Detalhe do fluxo SSE na [receita SSE »](sse.md#autenticacao).
 
 !!! warning "Token na URL vaza"
     Query string entra em log de acesso, histórico do browser e header `Referer`. Habilite `query_param` só sobre TLS, só com **access token de vida curta** (nunca refresh token), e limpe o valor do formato de log. Se o cliente compartilha a origem da API, prefira cookie de sessão (`withCredentials`).