@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/Extensions/apikeys/Exemplos.md

@@ -0,0 +1,121 @@
+---
+tags: [seedgrid, extension, apikeys, exemplos]
+fonte: java/seedgrid-quarkus-ext-apikeys
+branch: main
+commit: bfc9c25877
+analisado-em: 2026-10-14
+---
+
+# API Keys (Quarkus) — exemplos
+
+Voltar: [[SeedGrid/Extensions/apikeys/Visao-geral|Visão geral do apikeys]] · [[SeedGrid/Extensions/apikeys/Configuracao|Configuração]]
+
+## 1. Dependência
+
+Fonte: `runtime/pom.xml` e `README.md`.
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-apikeys</artifactId>
+    <version>2026.10.14</version>
+</dependency>
+```
+
+## 2. Proteger um endpoint
+
+Fonte: `ApiKeyIdentityProvider` adiciona cada permissão da role como `StringPermission`, então o `@PermissionsAllowed` nativo do Quarkus funciona; é o que o `README.md` usa.
+
+```java
+import io.quarkus.security.PermissionsAllowed;
+
+@GET
+@Path("/financas/recebiveis")
+@PermissionsAllowed("FINANCAS_LISTAR_RECEBIVEIS")
+public Response listRecebiveis() {
+    ...
+}
+```
+
+## 3. Criar, usar, revogar (HTTP)
+
+Fonte: `ApiKeyManagementController`, `README.md`.
+
+```bash
+# Criar (JWT do usuário, permissão APIKEY_CREATE); a role precisa ser de integração
+curl -X POST "http://localhost:8080/apikeys/role/ROTAS_INTEGRACAO" \
+  -H "Authorization: Bearer <JWT_DO_USUARIO>" -H "Content-Type: application/json" \
+  -d '{"name": "Integracao ERP", "expiresDays": 90}'
+# → 201 { publicId, name, prefix, masked, apiKey: "sgkey_...", expiresAt, createdAt }
+
+# Usar (prefira x-api-key)
+curl "http://localhost:8080/financas/recebiveis" -H "x-api-key: <SEGREDO:api-key>"
+
+# Roles elegíveis para o combo da tela
+curl "http://localhost:8080/apikeys/roles" -H "Authorization: Bearer <JWT_DO_USUARIO>"
+
+# Revogar
+curl -X POST "http://localhost:8080/apikeys/<publicId>/revoke" -H "Authorization: Bearer <JWT_DO_USUARIO>"
+```
+
+`name` é obrigatório (máx. 120); `expiresDays` ≥ 1 ou ausente (sem expiração) — `ApiKeyCreateRequest`.
+
+## 4. Introspecção por serviço externo
+
+Fonte: `ApiKeyIntrospectionController`, `README.md` §1.5.
+
+```bash
+curl "https://<tenant>.<sufixo>/apikeys/me" -H "x-api-key: <SEGREDO:api-key>"
+```
+
+```json
+{
+  "publicId": "apk_123", "name": "chave-do-gateway", "prefix": "A1B2C3D4",
+  "roleName": "ROTAS_INTEGRACAO", "ownerPublicId": "usr_456",
+  "permissions": ["ROTAS_CALCULAR"], "expiresAt": "2026-12-31T23:59:59Z"
+}
+```
+
+`200` = chave válida agora. Quem cacheia deve usar o hash da chave como chave de cache e cachear também negativos (recomendação do README).
+
+## 5. Ler a identidade da API key no código
+
+Fonte: `ApiKeyIdentityProvider` (atributos) e `ApiKeyPrincipal`.
+
+```java
+import br.com.seedgrid.apikeys.utils.ApiKeyPrincipal;
+import io.quarkus.security.identity.SecurityIdentity;
+
+@Inject SecurityIdentity identity;
+
+if (identity.getPrincipal() instanceof ApiKeyPrincipal key) {
+    String keyPublicId = key.getApiKeyPublicId();
+    String ownerPublicId = key.getOwnerPublicId();
+    Long companyId = key.getCompanyId(); // null = chave sem escopo
+}
+String authType = identity.getAttribute("apikey.authType");
+```
+
+## 6. Desligar a gestão de chaves (SPI)
+
+Fonte: `ApiKeyActivationPolicy` / `DefaultApiKeyActivationPolicy` (`@DefaultBean`). Um bean do host substitui o padrão.
+
+```java
+import br.com.seedgrid.apikeys.spis.ApiKeyActivationPolicy;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class MinhaPoliticaApiKey implements ApiKeyActivationPolicy {
+    @Override public boolean isApiKeyAuthEnabled() { return true; }
+    @Override public boolean isApiKeyManagementEnabled() { return false; } // gestão → ApiKeyManagementDisabledException
+}
+```
+
+## 7. Configuração
+
+```properties
+seedgrid.apikeys.prefix-length=8
+seedgrid.apikeys.key-bytes=32
+```
+
+Detalhes em [[SeedGrid/Extensions/apikeys/Configuracao|Configuração]].

package/seedgridKB/SeedGrid/Extensions/apikeys/Rust.md

@@ -0,0 +1,126 @@
+---
+tags: [seedgrid, extension, apikeys, rust]
+fonte: rust/seedgrid-rust-crate-apikeys
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# `seedgrid-rust-crate-apikeys` — porte Rust
+
+Lado Java: [[SeedGrid/Extensions/apikeys/Visao-geral|Visão geral do apikeys (Quarkus)]] · [[SeedGrid/Extensions/apikeys/Configuracao|Configuração Java]]
+Configuração deste crate: [[SeedGrid/Extensions/apikeys/Configuracao-Rust|Configuração Rust do apikeys]]
+
+## Objetivo
+
+Porte da extensão `seedgrid-quarkus-ext-apikeys`: geração, autenticação e gestão de **API keys** `sgkey_...`, com permissões derivadas da role (habilitada para integração). Crate biblioteca: o host constrói um `ApiKeyState`, monta o `router` e instala o middleware `extract::api_key_auth`. A paridade com o Java é essencialmente 1:1.
+
+## Coordenadas
+
+| Item | Valor |
+|---|---|
+| Diretório / pacote / lib | `rust/seedgrid-rust-crate-apikeys` / `seedgrid-rust-crate-apikeys` / `seedgrid_apikeys` |
+| Versão | `version.workspace = true` → `2026.10.14` |
+| Edição / MSRV / licença | 2021 / 1.82 / `LicenseRef-Commercial` |
+| Features | nenhuma |
+| Dependência SeedGrid | `seedgrid-security` (bcrypt `hash_secret`/`verify_secret`, models e schema) |
+
+## Formato da chave (Confirmado em `src/generator.rs` e README)
+
+```
+raw_api_key = "sgkey_" + randomPart
+randomPart  = Base64 URL-safe sem padding de key_bytes bytes (OsRng)
+prefix      = primeiros prefix_length chars de randomPart (sem "sgkey_")
+key_hash    = bcrypt(raw_api_key)   # cobre a chave inteira, inclusive "sgkey_"
+masked      = prefix + "..."
+```
+
+A chave crua só é devolvida na criação. Geração tenta 5 vezes contra colisão de prefixo.
+
+## API pública
+
+| Símbolo | Papel |
+|---|---|
+| `ApiKeysConfig` (+ `from_env`) | ver [[SeedGrid/Extensions/apikeys/Configuracao-Rust\|Configuração Rust]] |
+| `ApiKeyState::builder(pool, config)` → `.policy(...)`, `.security(SecurityState)`, `.build()`; também `from_parts`, `from_parts_with_security` | estado do módulo |
+| `router(ApiKeyState)` | rotas REST |
+| `extract::api_key_auth` | middleware: lê `x-api-key` (trim) ou `Authorization: Bearer sgkey_...`; IP por `X-Forwarded-For` → `X-Real-IP`; injeta `ApiKeyIdentity` e registra uso (best-effort) |
+| `ApiKeyAuthService`, `ApiKeyManagementService`, `ApiKeyIntrospectionService`, `ApiKeyUsageService` | serviços |
+| `ApiKeyGenerator`, `ApiKeyIdentity`/`HumanIdentity`/`ManagementIdentity`/`to_identity` | geração e identidade |
+| `ApiKeyActivationPolicy` / `DefaultApiKeyActivationPolicy` | SPI de ativação (auth/gestão) |
+| `migrate(&PgPool)` / `MIGRATOR` | migrations `0600..0603`, histórico próprio `_sqlx_migrations_apikeys` |
+| `openapi()` | spec utoipa |
+
+Ordem de decisão da autenticação: prefixo inválido / não encontrado / hash errado → silencioso (`Ok(None)`); revogada → 401; expirada → 401; sucesso → principal com permissões da role.
+
+## Endpoints (Confirmado em `src/routes.rs`)
+
+| Método | Path | Permissão |
+|---|---|---|
+| POST | `/apikeys/role/{roleName}` | `APIKEY_CREATE` (201, única resposta com a chave crua) |
+| GET | `/apikeys/role/{roleName}` | `APIKEY_READ` |
+| GET | `/apikeys?page&size` | `APIKEY_READ` (lista simples ou paginada) |
+| POST | `/apikeys/{publicId}/revoke` | `APIKEY_REVOKE` |
+| GET | `/apikeys/me` | só autenticação por API key (introspecção; sem permissão, fora do toggle de gestão, não devolve e-mail do dono) |
+
+## Exemplo (Confirmado em `src/lib.rs` e README)
+
+```rust
+use seedgrid_apikeys::{router, ApiKeysConfig, ApiKeyState};
+use seedgrid_apikeys::extract::api_key_auth;
+
+async fn boot(pool: sqlx::PgPool) -> Result<(), Box<dyn std::error::Error>> {
+    seedgrid_security::migrate(&pool).await?;   // primeiro (dependência de dados)
+    seedgrid_apikeys::migrate(&pool).await?;
+    let state = ApiKeyState::builder(pool, ApiKeysConfig::from_env()).build();
+    let app = axum::Router::new()
+        .merge(router(state.clone()))
+        .layer(axum::middleware::from_fn_with_state(state, api_key_auth));
+    let _ = app;
+    Ok(())
+}
+```
+
+Exemplo executável: `rust/examples/seedgrid-security-apikeys-example`.
+
+## Migrations
+
+`0600_create_apikeys_table.sql`, `0601_add_user_snapshot_fields.sql`, `0602_add_permissions.sql` (semeia `APIKEY_CREATE/READ/REVOKE` e vincula à role `ADMIN`, com `ON CONFLICT` extra em relação ao Java), `0603_add_active_to_api_keys_table.sql`. Rodar **depois** de `seedgrid_security::migrate`.
+
+> O código usa tabela de histórico própria `_sqlx_migrations_apikeys` (`src/migrations.rs`, `HISTORY_TABLE`). A ordem continua necessária pela dependência de dados.
+
+## Testes
+
+`tests/auth_ordering.rs`, `tests/human_auth_management.rs`, `tests/introspection.rs` (sem banco) e `tests/db_flow.rs` (`#[ignore]`, Testcontainers). **Não executados** nesta análise.
+
+## Notas de comportamento
+
+- Datas serializadas como `NaiveDateTime` (sem `Z`), não `Instant` como no Java.
+- O registro de uso da chave é best-effort (não bloqueia a requisição).
+- `@ApiKeyAllowed` e `ApiKeySecurityContext` (JAX-RS) não existem; use `ApiKeyIdentity`.
+
+## Enums
+
+Equivalentes Java em [[SeedGrid/Extensions/apikeys/Enums|Enums (Quarkus)]].
+
+| Enum | Arquivo | Usado em | Equivalente Java |
+|---|---|---|---|
+| `ApiKeyAuthType` | `src/models.rs` | `ApiKeyPrincipal`; atributo `apikey.authType` da identity | [[SeedGrid/Extensions/apikeys/Enums#ApiKeyAuthType\|ApiKeyAuthType]] |
+| `ApiKeyError` | `src/error.rs` | erro de serviços/handlers, resposta RFC 7807 | exceções `ApiKey*Exception` (sem enum) |
+| `ManagementIdentity` | `src/identity.rs` | credencial aceita pelas rotas de gestão | sem equivalente (específico do Rust) |
+
+### ApiKeyAuthType
+
+| Variante | `name()` | Observação |
+|---|---|---|
+| `ApiKey` | `API_KEY` | única variante; é o valor do atributo `apikey.authType` da `ApiKeyIdentity`. Não é persistido nem serializado em JSON |
+
+Java: `API_KEY`, idêntico (também com um único valor).
+
+### ApiKeyError
+
+Mapeamento HTTP (Confirmado em `src/error.rs`): `Unauthorized`, `AuthenticationFailed`, `Expired`, `Revoked` → 401; `NotFound`, `RoleNotFound`, `OwnerNotFound`, `ManagementDisabled` → 404; `RoleNotAllowed`, `Forbidden` → 403; `BadRequest` → 400; `Generation`, `Database`, `Internal` → 500. Mensagens iguais às do Java.
+
+### ManagementIdentity
+
+Enum com dados: `ApiKey(ApiKeyIdentity)` ou `Human(HumanIdentity)`. Permite que as rotas `/apikeys*` aceitem API key **ou** JWT humano; expõe `check_permission` e `principal_name`. No Java o `SecurityContext` abstrai a credencial, então não há enum equivalente.

package/seedgridKB/SeedGrid/Extensions/apikeys/Visao-geral.md

@@ -0,0 +1,111 @@
+---
+tags: [seedgrid, extension, apikeys]
+fonte: java/seedgrid-quarkus-ext-apikeys
+branch: main
+commit: bfc9c25877
+analisado-em: 2026-10-14
+---
+
+# API Keys (Quarkus) — visão geral
+
+Autenticação por **API key** para integrações máquina-a-máquina. A chave é atrelada a uma **role de integração** (`for_integration`) e herda as permissões dela pelo mesmo RBAC do login JWT; o banco guarda só **hash + prefixo**, com expiração e revogação por chave. A extension também emite, lista e revoga chaves e oferece introspecção (`GET /apikeys/me`).
+
+- Configuração: [[SeedGrid/Extensions/apikeys/Configuracao|Configuração do apikeys]]
+- Exemplos: [[SeedGrid/Extensions/apikeys/Exemplos|Exemplos do apikeys]]
+- Enums: [[SeedGrid/Extensions/apikeys/Enums|Enums do apikeys]]
+- Porte Rust (crate `seedgrid-rust-crate-apikeys`): [[SeedGrid/Extensions/apikeys/Rust|Porte Rust]]
+
+## Módulos Maven e coordenadas (Confirmado — `pom.xml`)
+
+| Módulo | groupId | artifactId | Versão |
+|---|---|---|---|
+| parent | `br.com.seedgrid` | `seedgrid-apikeys-parent` | `2026.10.14` |
+| runtime | `br.com.seedgrid` | `seedgrid-apikeys` | `2026.10.14` |
+| deployment | `br.com.seedgrid` | `seedgrid-apikeys-deployment` | `2026.10.14` |
+| integration-tests (não publicado) | `br.com.seedgrid` | `seedgrid-apikeys-integration-tests` | `2026.10.14` |
+
+Parent: `br.com.seedgrid:seedgrid-parent:2026.07.02`. Status: `preview`.
+
+Observações de empacotamento (Confirmado, impacto Não confirmado):
+- O YAML está nomeado `quarkus-extesion.yaml` (grafia incorreta).
+
+## Dependências SeedGrid
+
+| Dependência | Versão (runtime) | Uso |
+|---|---|---|
+| `seedgrid-commons` | `2026.08.16` | `CurrentUserProvider`, paginação (`PageReq`/`PageResult`) |
+| `seedgrid-security` | `2026.10.14` | `PasswordService` (hash), `User`/`Role`/`Permission`, `UserRepository`/`RoleRepository`, `CompanyRequestContext`, `PlatformCompanyService` |
+| `seedgrid-security-deployment` (deployment) | `2026.09.25` | — |
+
+O README declara: "Requer o `seedgrid-security` no host".
+
+## Arquitetura e fluxo (Confirmado)
+
+```mermaid
+flowchart TB
+    REQ["Request com x-api-key<br/>(ou Authorization: Bearer sgkey_...)"] --> MECH[ApiKeyAuthenticationMechanism]
+    MECH -->|"ApiKeyActivationPolicy.isApiKeyAuthEnabled()"| AREQ[ApiKeyAuthenticationRequest]
+    AREQ --> IDP[ApiKeyIdentityProvider]
+    IDP --> AUTH["ApiKeyAuthService.authenticate<br/>prefixo → hash → revogada/expirada → role de integração ativa → membro ativo da empresa"]
+    AUTH --> SI["SecurityIdentity<br/>role da key + StringPermission por permissão"]
+    SI --> F1["ApiKeyUsageFilter (registra uso/IP)"]
+    SI --> F2["ApiKeyCompanyContextFilter (empresa da chave vira a corrente)"]
+    F2 --> EP["Endpoint (@PermissionsAllowed)"]
+```
+
+Pontos relevantes:
+- Formato da chave: `sgkey_` + Base64 URL-safe sem padding de `seedgrid.apikeys.key-bytes` bytes aleatórios. O prefixo armazenado são os primeiros `seedgrid.apikeys.prefix-length` caracteres da parte aleatória; a chave crua é hasheada com `PasswordService.encode` e só aparece na resposta de criação. (`ApiKeyGeneratorService`)
+- Header: `x-api-key` é **fixo** (`ApiKeyConstants.APIKEY_HEADER`), não configurável. `Authorization: Bearer` só é aceito se o token começar com `sgkey_`. O README recomenda `x-api-key`, porque com `smallrye-jwt` na classpath os dois mecanismos disputam o `Authorization`.
+- `OPTIONS` não autentica. IP do cliente vem de `X-Forwarded-For` (primeiro valor) ou `X-Real-IP`.
+- Chave revogada → `ApiKeyRevokedException`; expirada → `ApiKeyExpiredException`; role deixou de ser de integração ou foi desativada, ou dono saiu da empresa da chave → falha de autenticação (fail closed).
+- Escopo por empresa (V607): a chave guarda a empresa corrente de quem a criou; ao autenticar, `ApiKeyCompanyContextFilter` (`Priorities.AUTHORIZATION - 9`) fixa essa empresa como única permitida e corrente. Chave sem escopo não toca o contexto.
+- Fora da empresa-plataforma, roles com qualquer permissão de audience `platform` não são elegíveis (`ApiKeyManagementService#listEligibleRoles`).
+
+## API pública
+
+### Endpoints REST (Confirmado — `ApiKeyManagementController`, `ApiKeyIntrospectionController`)
+
+| Método | Path | Permissão | Descrição |
+|---|---|---|---|
+| `POST` | `/apikeys/role/{roleName}` | `APIKEY_CREATE` | Cria chave (`{name, expiresDays}`) → `201` com a chave crua |
+| `GET` | `/apikeys/roles` | `APIKEY_CREATE` | Roles de integração elegíveis na empresa corrente |
+| `GET` | `/apikeys/role/{roleName}` | `APIKEY_READ` | Lista chaves do usuário para a role |
+| `GET` | `/apikeys?page=&size=` | `APIKEY_READ` | Lista chaves do usuário (paginada se `page` ou `size` vier; `size` padrão 10) |
+| `POST` | `/apikeys/{publicId}/revoke` | `APIKEY_REVOKE` | Revoga (idempotente) |
+| `GET` | `/apikeys/me` | `@Authenticated`, **só API key** (JWT → 401) | Introspecção: dono (`ownerPublicId`), role, permissões, expiração; sem e-mail do dono |
+
+Os endpoints de gestão chamam `ensureManagementEnabled()` (`ApiKeyActivationPolicy#isApiKeyManagementEnabled`); `/apikeys/me` não.
+
+### SPI / beans / anotações
+
+| Símbolo | Tipo | Observação |
+|---|---|---|
+| `br.com.seedgrid.apikeys.spis.ApiKeyActivationPolicy` | SPI | `isApiKeyAuthEnabled()`, `isApiKeyManagementEnabled()`; padrão `DefaultApiKeyActivationPolicy` (`@DefaultBean`, ambos `true`). É a forma de "desligar" a extension — não há propriedade para isso. |
+| `ApiKeyAwareCurrentUserProvider` | `CurrentUserProvider` `@Alternative @Priority(1)` | JWT tem precedência; com API key usa `publicId`/e-mail do dono e `apikey:<prefixo>` como nome; sem identidade, sentinelas do security |
+| `ApiKeyIdentityProvider` | `IdentityProvider` | adiciona atributos `apikey.publicId`, `apikey.prefix`, `apikey.ownerId`, `apikey.ownerPublicId`, `apikey.ownerEmail`, `apikey.authType` |
+| `ApiKeyPrincipal` | `Principal` | obtido em `identity.getPrincipal()` |
+| `ApiKeyPermissionService#hasPermission` | bean | utilitário |
+
+### Permissões (migrations)
+
+`APIKEY_CREATE`, `APIKEY_READ`, `APIKEY_REVOKE` (V602). V605 marcou `audience='client'`; V606 reverteu para audience nula (visível nos dois escopos).
+
+## Migrations (Confirmado)
+
+`runtime/src/main/resources/db/migration/apikeys/V600`–`V607` (tabela `api_keys`, snapshot de usuário, permissões, `active`, timestamps com fuso, audiences, `company_id` com FK condicional para `companies`). Location `classpath:db/migration/apikeys`. Quem roda as migrations é o host ou uma foundation (ex.: [[SeedGrid/Extensions/login-tenancy/Visao-geral|login-tenancy]] usa a tabela de histórico `flyway_schema_history_apikeys`).
+
+## Testes existentes (não executados)
+
+| Teste | Cobertura |
+|---|---|
+| `runtime/src/test/.../ApiKeyCompanyScopeTest` | roles elegíveis por audience; escopo por empresa na criação; dono que saiu da empresa; filtro de contexto |
+| `runtime/src/test/.../ApiKeyIdentityProviderPermissionsTest` | permissões como `StringPermission`, atributo `authType`, chave inválida |
+| `runtime/src/test/.../security/ApiKeyAwareCurrentUserProviderTest` | precedência JWT, dono da chave, sentinelas, whatsapp só do JWT |
+| `integration-tests/.../ApiKeyFlowTest` | cria chave e autentica com permissões da role; chave inexistente |
+| `integration-tests/.../ApiKeyIntrospectionTest` | `/apikeys/me`: conteúdo, não vaza chave/hash/e-mail, 401s, revogada, não empresta permissão de gestão |
+| `integration-tests/.../SeedgridApikeysResourceTest`/`IT` | rota sem credencial é barrada |
+
+## Limitações
+
+- Nenhuma propriedade liga/desliga a autenticação ou a gestão; isso é feito via bean `ApiKeyActivationPolicy` (Confirmado).
+- Cada request autenticada por API key grava uso em transação `REQUIRES_NEW` (`ApiKeyUsageService#registerUsage`) — custo de escrita por request (Inferência).

package/seedgridKB/SeedGrid/Extensions/audit/Configuracao-Rust.md

@@ -0,0 +1,93 @@
+---
+tags: [seedgrid, extension, audit, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-audit
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# audit — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/audit/Rust|Porte Rust do audit]] · Java: [[SeedGrid/Extensions/audit/Configuracao|Configuração do audit (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Struct | `AuditConfig` (+ `MongoConfig`, `JpaConfig`, enum `AuditPersistenceStrategy`) — `rust/seedgrid-rust-crate-audit/src/config.rs` |
+| Mecanismo | `AuditConfig::from_env()` lê `std::env::var`; ou struct construída pelo host (`AuditConfig::default()` / literal) |
+| Prefixo Java equivalente | `seedgrid.audit` (`@ConfigMapping` em `AuditConfig.java`) |
+| Quem chama `from_env` | `AuditPlatform::assemble` (`src/platform.rs`) e o host (ex.: exemplo `seedgrid-audit-example`) |
+| Leitura | uma vez, quando `from_env()` é chamado (no boot do host); sem recarga |
+
+Regras gerais do helper `opt(name)` (`src/config.rs`): valor é `trim()`ado e string vazia vale como ausente. `SEEDGRID_AUDIT_ENABLED` e `AUDIT_STRATEGY` não passam por `opt` (sem trim no `enabled`).
+
+## Variáveis de ambiente
+
+### Ativação e estratégia
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_AUDIT_ENABLED` | bool | `true`/`false` (parse `bool` do Rust, sensível a maiúsculas) | `true` | Não | `false` torna `Auditor::record` no-op e faz `AuditPlatform::assemble` devolver `Ok(None)`. Valor inválido → `true` | liga/desliga auditoria | — | `from_env()` | decl.: `config.rs` → `AuditConfig::from_env`; consumo: `state.rs` (`if !self.config.enabled`), `platform.rs` → `AuditPlatform::assemble` |
+| `AUDIT_STRATEGY` (Java: `seedgrid.audit.persistence.strategy`, via `${AUDIT_STRATEGY:...}`) | enum `AuditPersistenceStrategy` | `JPA`, `POSTGRES`, `POSTGRESQL` → `Jpa`; `MONGODB`, `MONGO` → `Mongodb` (case-insensitive, trim) | derivado da feature: `Jpa` com `postgres` (também quando ambas ou nenhuma); `Mongodb` só com `mongodb` sem `postgres` | Não | valor desconhecido → default da feature. `AuditState::postgres/mongodb` falham (`AuditError::Config`) se a estratégia não casar com o backend | escolhe backend no `AuditPlatform`; valida construtor | `MONGODB` sem a feature `mongodb` → `assemble` loga erro e devolve `Ok(None)` | `from_env()` | `config.rs` → `default_strategy`, `AuditPersistenceStrategy::parse`; `state.rs` → `validate_strategy`; `platform.rs` |
+
+### Relacional (JPA/Postgres)
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_AUDIT_DB_URL` (Java: `seedgrid.audit.jpa.jdbc.url`) | `Option<String>` | `jdbc:postgresql:...`, `postgres://...`, `postgresql://...` | — | Condicional: só se o host usar `pg_connection_url()` | `AuditConfig::pg_connection_url()` remove `jdbc:`; outro formato → `AuditError::Config` | método público; nenhum chamador no workspace | `AuditPlatform` usa o `PgPool` recebido do host | `from_env()` | `config.rs` → `pg_connection_url` |
+
+### MongoDB
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| 🔒 `SEEDGRID_AUDIT_MONGODB_URI` (Java: `seedgrid.audit.mongodb.connection-string`, via `${SEEDGRID_AUDIT_MONGODB_URI:...}`) | `Option<String>` (sempre `Some` após `from_env`) | URI MongoDB | `DEFAULT_MONGODB_URI` = `mongodb://<usuario>:<SEGREDO:mongo-dev>@localhost:27017` (credenciais de dev embutidas, redigidas aqui) | Condicional: estratégia `Mongodb` | URI usada por `effective_mongo_uri()`; falha de conexão → auditoria no-op (`Ok(None)`) | `AuditPlatform::assemble_mongo` | requer feature `mongodb` | `from_env()` | `config.rs` → `DEFAULT_MONGODB_URI`, `effective_mongo_uri`; `platform.rs` |
+| `SEEDGRID_AUDIT_MONGODB_DATABASE` (Java: `seedgrid.audit.mongodb.database`) | `Option<String>` | nome de banco | sem padrão no config; `AuditPlatform` usa `seedgrid_audit` quando ausente | Não | nome do banco Mongo | `AuditPlatform::assemble_mongo` | — | `from_env()` | `config.rs`; `platform.rs` |
+
+Mapeamento Java ↔ env: **Confirmado** para `AUDIT_STRATEGY`, `SEEDGRID_AUDIT_DB_URL` e `SEEDGRID_AUDIT_MONGODB_URI` (expressões `${...}` em `java/seedgrid-quarkus-ext-audit/*/runtime/src/main/resources/META-INF/microprofile-config.properties`). `SEEDGRID_AUDIT_MONGODB_DATABASE` corresponde à conversão padrão MicroProfile de `seedgrid.audit.mongodb.database` (**Confirmado** pela regra, sem hífen ambíguo). `SEEDGRID_AUDIT_ENABLED` é uma opção só do Rust.
+
+## Structs (construção pelo host)
+| Campo | Tipo | `Default` | Notas |
+|---|---|---|---|
+| `AuditConfig.enabled` | `bool` | `true` | |
+| `AuditConfig.strategy` | `AuditPersistenceStrategy` | `default_strategy()` | `#[default]` do enum é `Jpa`, mas `AuditConfig::default()` usa `default_strategy()` |
+| `AuditConfig.mongodb` | `MongoConfig { database, connection_string }` | ambos `None` | com `None`, `effective_mongo_uri()` cai no `DEFAULT_MONGODB_URI` |
+| `AuditConfig.jpa.jdbc_url` | `Option<String>` | `None` | usado só por `pg_connection_url()` |
+
+## Features Cargo
+| Feature | Padrão | Efeito |
+|---|---|---|
+| `postgres` | sim | habilita `sqlx`, `postgres.rs`, `migrate`, `MIGRATOR`, `AuditPlatform`, `AuditState::postgres`; muda `default_strategy()` para `Jpa` |
+| `mongodb` | não | habilita `mongodb`/`bson`, `mongodb.rs`, `AuditState::mongodb`; sem `postgres`, `default_strategy()` vira `Mongodb` |
+
+## Configuração não-env (código)
+- Autorização de leitura: `AuditStateBuilder::read_authorizer(...)` — default `DenyAllAuditReadAuthorizer` (403). Não há variável de ambiente.
+- Escopo de leitura, request context e contribuidores: via builder (`src/state.rs`).
+
+## Somente testes / exemplos
+| Variável | Onde | Finalidade |
+|---|---|---|
+| `AUDIT_IT_PG_URL` | `tests/pg_metadata_it.rs` | Postgres para IT `#[ignore]` |
+| `AUDIT_IT_MONGO_URI` | `tests/mongo_metadata_it.rs` | Mongo para IT `#[ignore]` |
+| `DATABASE_URL` | `examples/seedgrid-audit-example/src/main.rs` | conexão do exemplo (lida pelo exemplo, não pela crate) |
+| `DOCKER_HOST`, `TESTCONTAINERS_RYUK_DISABLED` | `.env.example` do exemplo | Testcontainers/Podman |
+
+## Configuração mínima (`.env`)
+```dotenv
+# Postgres (feature default): a conexão é do host; a crate só precisa disto se quiser desligar
+SEEDGRID_AUDIT_ENABLED=true
+```
+
+## Configuração completa comentada
+```dotenv
+SEEDGRID_AUDIT_ENABLED=true            # false => Auditor no-op
+AUDIT_STRATEGY=JPA                     # JPA|POSTGRES|POSTGRESQL|MONGODB|MONGO
+SEEDGRID_AUDIT_DB_URL=jdbc:postgresql://<host>:5432/<db>   # só via pg_connection_url()
+# Mongo (feature mongodb + AUDIT_STRATEGY=MONGODB)
+SEEDGRID_AUDIT_MONGODB_URI=mongodb://<usuario>:<SEGREDO:audit-mongo>@<host>:27017
+SEEDGRID_AUDIT_MONGODB_DATABASE=seedgrid_audit
+```
+
+## Receitas
+- **Postgres (padrão)**: compile com a feature default, crie o `PgPool`, `seedgrid_audit::migrate(&pool)`, `AuditState::postgres(pool, AuditConfig::from_env())?`, registre um `AuditReadAuthorizer` que valide `LOG_READ`.
+- **MongoDB**: `default-features = false, features = ["mongodb"]`, `AUDIT_STRATEGY=MONGODB` (ou deixe o default da feature), `SEEDGRID_AUDIT_MONGODB_URI` e `SEEDGRID_AUDIT_MONGODB_DATABASE`.
+- **Desligar**: `SEEDGRID_AUDIT_ENABLED=false`.
+
+## Dúvidas e lacunas
+- `SEEDGRID_AUDIT_DB_URL` só tem efeito se o host chamar `pg_connection_url()`; `AuditPlatform` e os construtores usam o `PgPool` do host.

package/seedgridKB/SeedGrid/Extensions/audit/Configuracao.md

@@ -0,0 +1,127 @@
+---
+tags: [seedgrid, extension, audit, configuracao]
+fonte: java/seedgrid-quarkus-ext-audit
+branch: main
+commit: d5bf32e509
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Audit — Configuração
+
+Voltar: [[SeedGrid/Extensions/audit/Visao-geral|Visão geral do audit]] · [[SeedGrid/Extensions/audit/Exemplos|Exemplos]] · [[SeedGrid/Extensions/audit/Rust|Porte Rust]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixo | `seedgrid.audit` |
+| Classe de config | `seedgrid-quarkus-ext-audit-core/runtime/src/main/java/br/com/seedgrid/audit/core/configs/AuditConfig.java` (`@ConfigMapping(prefix = "seedgrid.audit")`) |
+| Mecanismo | SmallRye `@ConfigMapping` (interfaces aninhadas `Persistence`, `MongoDb`, `Jpa`, `Jpa.Jdbc`) |
+| Fase | Runtime (ConfigMapping em módulo runtime; não há `@ConfigRoot`/`*BuildTimeConfig` nos deployments) |
+| Defaults de módulo | `META-INF/microprofile-config.properties` em `seedgrid-quarkus-ext-audit-postgresql/runtime` e `seedgrid-quarkus-ext-audit-mongodb/runtime` (ordinal 100, sobrescrevível pelo `application.properties` do host) |
+| Outras leituras | Nenhum `@ConfigProperty`, `ConfigProvider.getConfig()` ou `@IfBuildProperty` no repositório audit. Fora dele, `seedgrid-login-tenancy` lê `seedgrid.audit.mongodb.database` via `@ConfigProperty`. **Confirmado** por grep. |
+
+Variáveis de ambiente lidas explicitamente pelos `microprofile-config.properties` (expressões `${VAR:default}`): `AUDIT_STRATEGY`, `SEEDGRID_AUDIT_DB_USERNAME`, `SEEDGRID_AUDIT_DB_PASSWORD`, `SEEDGRID_AUDIT_DB_URL`, `SEEDGRID_AUDIT_MONGODB_URI`. Além disso vale a regra MicroProfile padrão (ex.: `SEEDGRID_AUDIT_PERSISTENCE_STRATEGY`), sem ambiguidade para essas chaves.
+
+## 2. Propriedades da extension
+
+### 2.1 Geral e strategy
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.audit.persistence.strategy` | enum [[SeedGrid/Extensions/audit/Enums#AuditPersistenceStrategy\|AuditPersistenceStrategy]] | `JPA`, `MONGODB` (conversão case-insensitive, segundo javadoc) | `JPA` (`@WithDefault`); o módulo postgresql define `${AUDIT_STRATEGY:JPA}` e o módulo mongodb `${AUDIT_STRATEGY:MONGODB}` | Não (mas deve corresponder ao módulo de store presente) | Seleciona o `AuditPersistenceProvider` cuja `strategy()` coincide; sem provider correspondente → `IllegalStateException("No audit persistence provider available for strategy ...")` na primeira injeção dos repositórios | `AuditPersistenceRouter#resolveProvider()`; `AuditConfig#isMongo()/isJpa()` | Determina se `seedgrid.audit.jpa.*` ou `seedgrid.audit.mongodb.*` têm efeito (`effective*`) | Runtime | Decl.: `AuditConfig.Persistence#strategy()`; default de módulo: `META-INF/microprofile-config.properties` (postgresql e mongodb) |
+
+### 2.2 JPA / PostgreSQL (`seedgrid.audit.jpa.*`)
+
+Só têm efeito com `strategy=JPA` **e** quando não há `EntityManager` CDI resolvível no host (datasource standalone do audit). Com `EntityManager` do host, estas chaves são ignoradas. **Confirmado** (`PostgreSqlAuditPersistenceProvider`).
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.audit.jpa.jdbc.url` | `Optional<String>` | URL iniciando com `jdbc:postgresql:` | — (módulo: `${SEEDGRID_AUDIT_DB_URL:}` = vazio) | Condicional: obrigatória com `strategy=JPA` sem `EntityManager` CDI | Vazia → `IllegalStateException("Audit JPA strategy configured but seedgrid.audit.jpa.jdbc.url not set")`; outro esquema → `IllegalArgumentException("Unsupported JDBC URL")`. Usada no `PGSimpleDataSource` do PU standalone `audit-pu` | `PostgreSqlAuditPersistenceProvider#getOrCreateEntityManagerFactory()` via `AuditConfig#effectiveJpaJdbcUrl()` | `username`, `password` | Runtime | Decl.: `AuditConfig.Jpa.Jdbc#url()`; default: `seedgrid-quarkus-ext-audit-postgresql/runtime/.../META-INF/microprofile-config.properties` |
+| `seedgrid.audit.jpa.username` | `Optional<String>` | texto | — (módulo: `${SEEDGRID_AUDIT_DB_USERNAME:}`) | Condicional (conforme o banco) | Usuário do datasource standalone | idem, via `effectiveJpaUsername()` | `jdbc.url` | Runtime | `AuditConfig.Jpa#username()` |
+| 🔒 `seedgrid.audit.jpa.password` | `Optional<String>` | texto | — (módulo: `${SEEDGRID_AUDIT_DB_PASSWORD:}`) | Condicional (conforme o banco) | Senha do datasource standalone | idem, via `effectiveJpaPassword()` | `jdbc.url` | Runtime | `AuditConfig.Jpa#password()` |
+
+### 2.3 MongoDB (`seedgrid.audit.mongodb.*`)
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| 🔒 `seedgrid.audit.mongodb.connection-string` | `Optional<String>` | connection string MongoDB | — no mapping; o módulo mongodb define `${SEEDGRID_AUDIT_MONGODB_URI:<URI local com credenciais de desenvolvimento>}` (valor não reproduzido aqui) | Condicional: necessária em produção com `strategy=MONGODB` (senão cai no default de desenvolvimento do módulo) | Não é lida por Java; o módulo faz a ponte `quarkus.mongodb.connection-string=${seedgrid.audit.mongodb.connection-string}` | Ponte em `microprofile-config.properties` | `quarkus.mongodb.connection-string` | Runtime | Decl.: `AuditConfig.MongoDb#connectionString()`; ponte: `seedgrid-quarkus-ext-audit-mongodb/runtime/.../META-INF/microprofile-config.properties` |
+| `seedgrid.audit.mongodb.database` | `Optional<String>` | nome de database | — (fallback do producer: `<seedgrid.login-tenancy.app.code>_audit_db`, ou `audit_db`) | Não | Não é lida pelo módulo audit. Só tem efeito quando o `MongoDatabase` vem do `LoginTenancyMongoAuditDatabaseProducer` (seedgrid-login-tenancy, banco único): define o nome do banco de auditoria. Ignorada com `seedgrid-subdomain-tenancy` (`TenantAwareMongoProducer` usa `<product-prefix>_<tenant>_audit_db`) ou com producer próprio da app | `java/seedgrid-quarkus-ext-login-tenancy/runtime/src/main/java/br/com/seedgrid/logintenancy/configs/LoginTenancyMongoAuditDatabaseProducer.java` → `#resolveDatabaseName()` (`@ConfigProperty`) | `seedgrid.login-tenancy.app.code` | Runtime | Decl.: `AuditConfig.MongoDb#database()`; consumo: `LoginTenancyMongoAuditDatabaseProducer#auditDatabase` |
+
+Total: **6** propriedades com efeito (`persistence.strategy`, `jpa.jdbc.url`, `jpa.username`, `jpa.password`, `mongodb.connection-string`, `mongodb.database`).
+
+## 3. Propriedades de framework definidas/recomendadas
+
+| Propriedade | Valor definido pela extension | Onde | Observação |
+|---|---|---|---|
+| `quarkus.mongodb.connection-string` | `${seedgrid.audit.mongodb.connection-string}` | módulo mongodb `microprofile-config.properties` | Ponte; o host pode sobrescrever |
+| `quarkus.flyway.locations` | `classpath:db/migration/audit` | módulo postgresql | **Atenção (Inferência):** por ser chave global do Flyway default, pode conflitar com as migrations do host se o host não a sobrescrever/compor |
+| `quarkus.flyway.table` | `flyway_schema_history_audit` | módulo postgresql | idem |
+| `quarkus.flyway.baseline-on-migrate` | `true` | módulo postgresql | — |
+| `quarkus.swagger-ui.path` | `/swagger-ui` | módulo postgresql | — |
+| `quarkus.swagger-ui.always-include` | `true` | módulo postgresql | — |
+| Permissão `LOG_READ` | — | `AuditLogController` | Não é propriedade; o host deve mapear a permissão (ex.: via security) |
+
+## 4. Propriedades de testes
+
+Nenhuma. Os testes (`*IT`, `AuditMaskingTest`) configuram Testcontainers programaticamente; não há `application.properties` de teste. **Confirmado**.
+
+## 5. Aliases, obsoletas, renomeações
+
+- Não há aliases nem renomeações em código.
+- Variáveis de ambiente `AUDIT_STRATEGY` e `SEEDGRID_AUDIT_*` funcionam como "aliases" via expressão nos `microprofile-config.properties`.
+
+## 6. Configuração mínima
+
+PostgreSQL usando o datasource/`EntityManager` do host:
+```properties
+seedgrid.audit.persistence.strategy=JPA
+```
+
+PostgreSQL sem `EntityManager` CDI (standalone):
+```properties
+seedgrid.audit.persistence.strategy=JPA
+seedgrid.audit.jpa.jdbc.url=jdbc:postgresql://<host>:5432/<database>
+seedgrid.audit.jpa.username=<usuario>
+seedgrid.audit.jpa.password=<SEGREDO:audit-db-password>
+```
+
+MongoDB:
+```properties
+seedgrid.audit.persistence.strategy=MONGODB
+seedgrid.audit.mongodb.connection-string=<SEGREDO:audit-mongodb-uri>
+```
+
+## 7. Configuração completa comentada
+
+```properties
+# JPA (padrão) ou MONGODB — deve corresponder ao módulo de store no classpath.
+seedgrid.audit.persistence.strategy=JPA
+
+# --- JPA standalone (só usado quando não há EntityManager CDI no host) ---
+seedgrid.audit.jpa.jdbc.url=jdbc:postgresql://<host>:5432/<database>
+seedgrid.audit.jpa.username=<usuario>
+seedgrid.audit.jpa.password=<SEGREDO:audit-db-password>
+
+# --- MongoDB ---
+# Repassada para quarkus.mongodb.connection-string pelo módulo mongodb.
+#seedgrid.audit.mongodb.connection-string=<SEGREDO:audit-mongodb-uri>
+# Só com seedgrid-login-tenancy (producer de banco único): nome do banco de auditoria.
+#seedgrid.audit.mongodb.database=<database>
+
+# --- Framework (já definidas pelo módulo postgresql; sobrescreva se o host tiver migrations próprias) ---
+#quarkus.flyway.locations=classpath:db/migration/audit
+#quarkus.flyway.table=flyway_schema_history_audit
+#quarkus.flyway.baseline-on-migrate=true
+```
+
+## 8. Receitas
+
+- **Usar o banco do próprio host (JPA):** inclua `seedgrid-audit-postgresql`; mantenha `strategy=JPA`. Com `quarkus-hibernate-orm` ativo o provider usa o `EntityManager` CDI. Garanta que as migrations `db/migration/audit` (V300–V303) sejam aplicadas — revise `quarkus.flyway.locations` para combinar com as do host.
+- **Banco de auditoria separado (JPA standalone):** sem `EntityManager` CDI resolvível, informe `seedgrid.audit.jpa.jdbc.url/username/password` (ou `SEEDGRID_AUDIT_DB_URL/USERNAME/PASSWORD`).
+- **MongoDB:** inclua `seedgrid-audit-mongodb`, defina `SEEDGRID_AUDIT_MONGODB_URI` (ou a propriedade) e garanta um producer de `MongoDatabase`: a extension não o produz; `seedgrid-login-tenancy` (banco único, nome via `seedgrid.audit.mongodb.database`) e `seedgrid-subdomain-tenancy` (banco por tenant) produzem um `@DefaultBean`.
+- **Isolamento de leitura por tenant/company:** não é por propriedade; implemente `AuditReadScopeProvider` (ver [[SeedGrid/Extensions/audit/Exemplos|Exemplos]]).
+
+## 9. Dúvidas e lacunas
+- Comportamento quando os dois módulos de store estão no classpath (dois defaults conflitantes para `strategy`). **Não confirmado**.
+- Os `quarkus.flyway.*` globais definidos pelo módulo postgresql podem interferir com o Flyway do host. **Inferência**.