@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,113 @@
+---
+tags: [seedgrid, extension, notification]
+fonte: java/seedgrid-quarkus-ext-notification
+branch: main
+commit: b989a6248a
+analisado-em: 2026-10-14
+---
+
+# Notification (Quarkus) — visão geral
+
+Notificações administrativas da plataforma por **e-mail, WhatsApp ou ambos**, escolhidos por evento. Extensões produtoras declaram eventos (catálogo dinâmico) e os publicam por evento CDI síncrono; o motor grava uma **outbox transacional** e um worker agendado entrega com retry, lease e deduplicação. Não há crate Rust equivalente.
+
+- Configuração: [[SeedGrid/Extensions/notification/Configuracao|Configuração do notification]]
+- Exemplos: [[SeedGrid/Extensions/notification/Exemplos|Exemplos do notification]]
+- Enums: [[SeedGrid/Extensions/notification/Enums|Enums do notification]]
+
+## Módulos Maven e coordenadas (Confirmado — `pom.xml`)
+
+| Módulo | groupId | artifactId | Versão | Papel |
+|---|---|---|---|---|
+| parent | `br.com.seedgrid` | `seedgrid-notification-parent` | `2026.10.15` | — |
+| `api` | `br.com.seedgrid` | `seedgrid-notification-api` | `2026.10.15` | Contrato leve para extensões **produtoras**: `EventDefinition`, `NotificationEvent`, `NotificationCatalogContributor`, `NotificationEventEnricher`, `RoutingAttribute`, `NotificationPublisher`. Só depende de `quarkus-arc`; tem `beans.xml`. |
+| `runtime` | `br.com.seedgrid` | `seedgrid-notification` | `2026.10.15` | Motor (subscriber): catálogo, regras, outbox, scheduler, transportes, REST, migrations |
+| `deployment` | `br.com.seedgrid` | `seedgrid-notification-deployment` | `2026.10.15` | Feature `seedgrid-notification`, beans unremovable, registro das entidades JPA na PU |
+| `integration-tests` | `br.com.seedgrid` | `seedgrid-notification-integration-tests` | `2026.10.15` | Testcontainers (PostgreSQL 16, MailHog) — perfil `-Pit` |
+
+Parent: `br.com.seedgrid:seedgrid-parent:2026.07.02`. Status: `stable` (`quarkus-extension.yaml`). O pom da notification sobrescreve `quarkus.platform.version` para `3.30.6` (o parent declara 3.30.8).
+
+## Dependências
+
+| Dependência | Versão | Uso |
+|---|---|---|
+| `seedgrid-notification-api` | `${project.version}` | contratos |
+| `br.com.seedgrid:seedgrid-whatsapp-core` (+ `-deployment`) | `2026.07.27` | `WhatsAppApi#sendTextMessage` — o provider (Evolution/Cloud) é escolhido pela extensão WhatsApp; ver [[SeedGrid/Extensions/whatsapp/Visao-geral|whatsapp]] |
+| `seedgrid-commons` | `2026.10.08` (dependencyManagement) | — |
+| `quarkus-mailer` | BOM | `@MailerName("security") Mailer` — o mesmo mailer nomeado do `seedgrid-security` |
+| `quarkus-hibernate-orm`, `quarkus-agroal`, `quarkus-flyway`, `quarkus-scheduler`, `quarkus-security`, `quarkus-hibernate-validator`, `quarkus-rest-jackson` | BOM | — |
+
+Integra como produtores (segundo o README): ai-pricing, billing e exchange — cada um depende só do `seedgrid-notification-api`. O `security` também só depende da `notification-api` (publica a falha de entrega de e-mail). Já `login-tenancy` e `subdomain-tenancy` dependem da extension completa (`seedgrid-notification` + `-deployment`): quem usa um tenancy recebe catálogo, regras, outbox e API administrativa sem declarar nada além do tenancy.
+
+## Arquitetura e fluxo
+
+```mermaid
+flowchart LR
+    C[NotificationCatalogContributor<br/>beans das produtoras] --> K[NotificationCatalog]
+    P["NotificationPublisher.publish()<br/>(evento CDI síncrono)"] --> S[NotificationSubscriber @Transactional]
+    K --> S
+    R[NotificationRules<br/>regra por evento e scope] --> S
+    E[NotificationEventEnricher<br/>atributos de roteamento] -.-> S
+    S --> O[(sg_notification_event<br/>+ entregas PENDING)]
+    D["NotificationDispatcher<br/>@Scheduled every poll-interval"] --> Q["NotificationQueue.claim()<br/>FOR UPDATE SKIP LOCKED + lease"]
+    O --> Q
+    Q --> T[NotificationTransport]
+    T --> M[Mailer 'security']
+    T --> W[WhatsAppApi]
+    T --> X["NotificationQueue.complete()<br/>SENT / PENDING com backoff / FAILED"]
+```
+
+Garantias e comportamento (Confirmado no código e em `docs/ARCHITECTURE.md`):
+- Publicação síncrona dentro da transação de negócio; rollback desfaz marcador e entregas. Deduplicação por `(scope, event_code, event_id)`.
+- Snapshot por canal/destinatário (texto, instância e destinatários congelados).
+- Estados: `PENDING → SENDING → SENT`, ou volta a `PENDING` com backoff `retry-delay × 2^min(tentativas-1, 10)`, terminando em `FAILED` ao atingir `max-attempts`. Entrega **ao menos uma vez**.
+- Templates em texto puro com `{variavel}` (substituição literal); assunto ≤ 300 caracteres sem CR/LF; corpo ≤ 16 000.
+- WhatsApp sem `messageId` na resposta é falha (o provider no-op nunca conta como sucesso).
+- Startup (`NotificationStartup`, `@Priority(APPLICATION + 1)`): valida a config, escolhe datasource (`datasource-name` → `master` → default) e roda Flyway próprio (`classpath:db/migration/notification`, tabela `flyway_schema_history_notification`, `baselineOnMigrate=true`). O dispatcher só trabalha depois disso (`isReady()`).
+- Persistence unit escolhida **no build** (`NotificationProcessor#registerEntities`): `master` se existir datasource com esse nome, senão a PU default (`<default>`).
+- Evento embutido: `platform.email-delivery-failed` (`OperationalNotificationCatalog`).
+
+## API pública
+
+### REST (Confirmado — `NotificationResource`, base `/admin/notifications`, `@Authenticated`)
+
+| Método | Path | Permissão | Resultado |
+|---|---|---|---|
+| `GET` | `/admin/notifications/events` | `NOTIFICATION_READ` | `channels`, eventos instalados com a configuração atual, `routingAttributes` |
+| `PUT` | `/admin/notifications/events/{code}` | `NOTIFICATION_UPDATE` | Substitui a regra (`NotificationRule`); `400` em regra inválida |
+| `GET` | `/admin/notifications/deliveries?page=0&size=30` | `NOTIFICATION_READ` | Histórico paginado sem corpo/destinatário (`size` 1–200, `page` 0–100000) |
+
+### Contratos Java (módulo `api`)
+
+| Símbolo | Papel |
+|---|---|
+| `EventDefinition(code, group, label, description, variables, subjectTemplate, bodyTemplate)` | Código `[a-z][a-z0-9-]*[.][a-z][a-z0-9.-]*` (≤ 120); variáveis `[a-zA-Z][a-zA-Z0-9_]*` |
+| `NotificationCatalogContributor#events()` | Bean CDI da produtora; códigos duplicados ou variáveis não declaradas impedem o startup |
+| `NotificationEvent(id, code, variables)` | `id` estável (≤ 160) para deduplicar |
+| `NotificationPublisher#publish(NotificationEvent)` | Dispara evento CDI síncrono; sem o runtime instalado, nada acontece |
+| `NotificationEventEnricher#attributes(event)` / `#describe()` | Host fornece atributos de roteamento para destinatários condicionais |
+| `RoutingAttribute(key, label, options)` / `RoutingAttribute.Option(value, label)` | Descrição para a tela |
+
+Modelo de regra (runtime): `NotificationRule(enabled, channels, emails, phones, whatsappChannelId, conditionalRecipients)` com `Channel {EMAIL, WHATSAPP}` e `ConditionalRecipient(channel, address, attribute, value)`.
+
+## Migrations
+
+`runtime/src/main/resources/db/migration/notification/V1000__notification.sql` e `V1001__notification_permissions.sql`. Faixa reservada **1000–1099** (README). V1001 insere `NOTIFICATION_READ`/`NOTIFICATION_UPDATE` com `audience='platform'` (se a tabela `permissions` existir) e as vincula à role `ADMIN` (se `roles`/`role_permissions` existirem).
+
+## Testes existentes (não executados)
+
+| Teste | Cobertura |
+|---|---|
+| `api/src/test/.../NotificationPublisherTest` | publicação síncrona por `Event` |
+| `runtime/src/test/.../NotificationRulesTest` | catálogo, duplicidade, variáveis, templates, normalização de e-mail/telefone E.164, instância WhatsApp, condicionais, limite de 50, JSON legado |
+| `runtime/src/test/.../NotificationRoutingTest` | condicionais, `value=null`, enricher não sobrescreve variáveis, enricher com exceção ignorado, `describe` |
+| `runtime/src/test/.../NotificationTransportTest` | WhatsApp no-op não marca `SENT` |
+| `runtime/src/test/.../NotificationEntityManagerTest` | seleção da PU default/nomeada |
+| `integration-tests/.../NotificationIT` | fluxo completo com PostgreSQL, MailHog e Evolution simulada (perfil `-Pit`) |
+
+## Limitações
+
+- `scope` **não** é resolução de company/tenant; a primeira versão atende alertas da plataforma.
+- Sem UI, sem templates HTML, sem webhook de entrega, sem expurgo, sem reenvio manual, sem transação distribuída.
+- Dados (destinatários e texto) ficam em claro no banco.
+- `seedgrid.notification.datasource-name` afeta só o datasource das migrations; a PU das entidades é decidida no build (`master`/default). Configurar um datasource diferente pode separar schema e acesso JPA (Inferência — ver [[SeedGrid/Extensions/notification/Configuracao|Configuração]]).
+- E-mail usa obrigatoriamente o mailer nomeado `security`; um host que substituiu o `EmailServiceInterface` do security por outro transporte precisa avaliar.

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

@@ -0,0 +1,67 @@
+---
+tags: [seedgrid, extension, privacy, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-privacy
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# privacy — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/privacy/Rust|Porte Rust do privacy]] · Java: [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Mecanismo | estado global `CryptoProvider` (`rust/seedgrid-rust-crate-privacy/src/field.rs`); propriedades lidas do ambiente por `config_env(property)` |
+| Conversão de nome | `env_of`: maiúsculas e `.`/`-` → `_` (`seedgrid.privacy.crypto.key` → `SEEDGRID_PRIVACY_CRYPTO_KEY`) |
+| Prefixo Java | `seedgrid.privacy` (constantes em `CryptoProvider.java`) |
+| Precedência | configuração programática (`CryptoProvider::configure*`, `set_encryption_enabled_for_tests`) > variável de ambiente > padrão |
+| Leitura | `ENCRYPTION_ENABLED` a **cada** chamada de `is_encryption_enabled()` (sem cache); chaves na primeira chamada de `get_*_service()` e depois em cache |
+| Struct de config | não há |
+
+`config_env` trata valor vazio/brancos como ausente (não faz `trim` no valor retornado).
+
+## Variáveis de ambiente
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_PRIVACY_ENCRYPTION_ENABLED` (Java `seedgrid.privacy.encryption.enabled`) | bool | `true`, `1`, `yes`, `on` (case-insensitive) = ligado; qualquer outro = desligado | `false` | Não | ligado: `EncryptedFieldConverter::from_provider` cifra na escrita e o listener gera hash; desligado: grava cru e não gera hash | `CryptoProvider::is_encryption_enabled` → `EncryptedFieldConverter::resolve_for_write`, `apply_search_hashes_via_provider` | exige as duas chaves quando ligado | a cada chamada | `field.rs` → `ENCRYPTION_ENABLED_PROPERTY`, `parse_bool` |
+| 🔒 `SEEDGRID_PRIVACY_CRYPTO_KEY` (Java `seedgrid.privacy.crypto.key`) | String | Base64 (com ou sem prefixo `base64:`) que decodifica para **exatamente 32 bytes** | — | Condicional: com cripto ligada e para **ler** valores `v1:...` | cria `AesGcmCryptoService`; ausente/inválida → serviço `None` (ver nota) | `CryptoProvider::get_crypto_service` | ignorada se `configure`/`configure_with_key` foi chamado | 1ª chamada, depois cache | `field.rs`; `crypto.rs` → `from_key_spec`, `decode_key`, `from_raw_key` |
+| 🔒 `SEEDGRID_PRIVACY_SEARCH_KEY` (Java `seedgrid.privacy.search.key`) | String | Base64 (com ou sem `base64:`) com **≥ 32 bytes** | — | Condicional: para gerar/consultar hash de busca | cria `HmacSha256SearchHashService` | `get_search_hash_service`, `get_secure_search`, listener | ignorada se `configure_search_*` foi chamado | 1ª chamada, depois cache | `field.rs`; `search.rs` → `from_key_spec` |
+
+Nota sobre chave ausente/inválida: com cripto ligada e sem serviço de cifra válido, `EncryptedFieldConverter::convert_to_database_column` devolve `Err(CryptoError::InvalidKey("seedgrid.privacy.crypto.key"))` (fail-closed, como o Java): o valor **não** é gravado em claro. Com cripto desligada o valor é gravado cru e nenhuma chave é exigida. Da mesma forma, `apply_search_hashes_via_provider` devolve erro (`seedgrid.privacy.search.key`) quando a cifra está ligada, a entidade tem campo com hash de busca e não há chave de busca. A leitura de um valor `v1:...` sem chave falha com `CryptoError::InvalidKey`. (**Confirmado** em `field.rs`: `resolve_for_write`, `apply_search_hashes_via_provider`, testes `cifra_ligada_sem_chave_falha_em_vez_de_gravar_em_claro` e `cifra_desligada_sem_chave_grava_cru`.)
+
+Mapeamento Java ↔ env: **Confirmado** — mesmos nomes de propriedade em `java/seedgrid-quarkus-lib-privacy/src/main/java/br/com/seedgrid/privacy/CryptoProvider.java`; a conversão é a regra MicroProfile sem ambiguidade.
+
+## Configuração programática (sem env)
+| API | Efeito |
+|---|---|
+| `CryptoProvider::configure(Arc<dyn CryptoService>)` / `configure_with_key(&str)` | define o serviço de cifra (vence a env) |
+| `CryptoProvider::configure_search_hash_service(..)` / `configure_search_with_key(&str)` | define o serviço de hash (vence a env) |
+| `CryptoProvider::configure_normalizer(..)` | troca o normalizador (padrão `DefaultValueNormalizer`) |
+| `CryptoProvider::set_encryption_enabled_for_tests(bool)` | override do flag (vence a env) |
+| `CryptoProvider::reset_for_tests()` | limpa tudo |
+| `#[personal_data(search = "...", normalize = "none\|canonical\|email")]` | por campo, via derive; `normalize` padrão `canonical` (comentário do teste) |
+
+## Features Cargo
+Nenhuma.
+
+## Somente testes
+Nenhuma variável de ambiente lida em `tests/`.
+
+## Aliases / obsoletos
+
+## Configuração mínima (cripto ligada)
+```dotenv
+SEEDGRID_PRIVACY_ENCRYPTION_ENABLED=true
+SEEDGRID_PRIVACY_CRYPTO_KEY=base64:<SEGREDO:privacy-aes-256-key-32-bytes>
+SEEDGRID_PRIVACY_SEARCH_KEY=base64:<SEGREDO:privacy-hmac-key-32-bytes>
+```
+
+## Receitas
+- **Só mascaramento**: nenhuma configuração.
+- **Cifra at-rest**: as três variáveis acima, ou `CryptoProvider::configure_with_key(...)` + `configure_search_with_key(...)` no boot.
+- **Dados legados em claro**: podem coexistir; a leitura segue o dado (`v1:` decifra, cru volta cru).
+
+## Dúvidas e lacunas
+- **Chave ausente ou inválida com a cifra ligada**: a gravação falha com erro (fail-closed), igual ao Java; nada é gravado em claro. A chave só é lida no primeiro uso — para falhar mais cedo, chame `CryptoProvider::configure_with_key` no boot do host e trate o erro.

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

@@ -0,0 +1,94 @@
+---
+tags: [seedgrid, library, privacy, configuracao]
+fonte: java/seedgrid-quarkus-lib-privacy
+branch: main
+commit: 79f8b03eeb
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Privacy — Configuração
+
+Voltar: [[SeedGrid/Extensions/privacy/Visao-geral|Visão geral do privacy]] · [[SeedGrid/Extensions/privacy/Exemplos|Exemplos do privacy]] · [[SeedGrid/Extensions/privacy/Rust|Porte Rust]]
+
+## 1. Cabeçalho
+
+| Item                      | Valor                                                                                                                                                                                                                                                                                              |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Prefixo                   | `seedgrid.privacy.*`                                                                                                                                                                                                                                                                               |
+| Classes de config         | Nenhuma `@ConfigMapping`/`@ConfigRoot`/`@ConfigProperty`. Nomes como constantes em `CryptoProvider` (`ENCRYPTION_ENABLED_PROPERTY`, `CRYPTO_KEY_PROPERTY`, `SEARCH_KEY_PROPERTY`); leitura via `ConfigProvider.getConfig().getOptionalValue(...)`; POJO `CryptoProperties` só transporta as chaves |
+| Arquivos de config da lib | Nenhum (`src/main/resources` inexistente)                                                                                                                                                                                                                                                          |
+| Fase                      | Runtime. `encryption.enabled` é relido **a cada** escrita/hash (`isEncryptionEnabled()` sem cache). As chaves são lidas no startup (`CryptoBootstrap`, `@Singleton @Startup`) e/ou lazy no primeiro uso; depois ficam em campos estáticos (mudança posterior não tem efeito sem restart)           |
+| Masking                   | Não tem configuração (não usa chave)                                                                                                                                                                                                                                                               |
+
+Investigado: `@ConfigMapping`, `@ConfigRoot`, `@ConfigProperty`, `ConfigProvider`, `System.getenv`, resources, testes. Fora de contexto MicroProfile (`IllegalStateException` do `ConfigProvider`), `isEncryptionEnabled()` → `false` e `loadConfiguredProperties()` → vazio.
+
+## 2. Propriedades próprias
+
+### 2.1 Secure Fields
+
+| Propriedade                           | Tipo                                          | Valores aceitos                                                                                     | Padrão  | Obrigatória                                                                                                                                                                              | Comportamento                                                                                                                                                                             | Uso                                                                                                                                                                       | Relações                                                                                                                                                                                  | Fase                                                                                                | Origem                                                                                                                                                             |
+| ------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `seedgrid.privacy.encryption.enabled` | `Boolean`                                     | `true`/`false`                                                                                      | `false` | Não                                                                                                                                                                                      | `false`: `@EncryptedField` grava valor cru e o campo de hash fica sem preencher; `true`: cifra na escrita e preenche o hash                                                               | `EncryptedFieldAttributeConverter#resolveForWrite`, `EncryptedFieldListener#applyEncryptedField`; exposto em `CryptoProvider.isEncryptionEnabled()` para queries bimodais | Ligado exige `crypto.key` e `search.key`. A **leitura** não depende do flag (valor `v1:` sempre exige `crypto.key`). Override programático: `CryptoProvider.setEncryptionEnabledForTests` | Runtime (relido a cada chamada)                                                                     | Declaração: `java/seedgrid-quarkus-lib-privacy/src/main/java/br/com/seedgrid/privacy/CryptoProvider.java` → `ENCRYPTION_ENABLED_PROPERTY`, `isEncryptionEnabled()` |
+| `seedgrid.privacy.crypto.key` 🔒      | `String` (Base64, prefixo `base64:` opcional) | Base64 válido que decodifique para **32 bytes** (mínimo validado: 32; AES aceita 16/24/32 — use 32) | —       | Condicional: obrigatória com `encryption.enabled=true` **e** para ler qualquer valor já cifrado (`v1:...`) mesmo com o flag desligado                                                    | Ausente quando necessária → `IllegalStateException("Propriedade obrigatoria ausente para secure fields: ...")` no 1º uso; inválida → `IllegalArgumentException` (no startup, se presente) | `AesGcmCryptoService` (AES/GCM/NoPadding, IV 12 bytes, tag 128 bits)                                                                                                      | Deve ser diferente de `search.key` (README)                                                                                                                                               | Runtime: startup (`CryptoBootstrap`) se presente; senão lazy em `CryptoProvider#getCryptoService()` | `CryptoProvider` → `CRYPTO_KEY_PROPERTY`, `loadConfiguredProperties()`, `getRequiredConfig()`; `KeyDecoder#decode(..., 32, ...)`; `AesGcmCryptoService(String)`    |
+| `seedgrid.privacy.search.key` 🔒      | `String` (Base64, prefixo `base64:` opcional) | Base64 válido com **≥ 32 bytes**                                                                    | —       | Condicional: obrigatória com `encryption.enabled=true` (listener com `searchField`) e sempre que se usar `EncryptedFieldSearch()`/`CryptoProvider.getSecureSearch()` (independe do flag) | Ausente quando necessária → `IllegalStateException`; inválida → `IllegalArgumentException` (no startup, se presente)                                                                      | `HmacSha256SearchHashService` (hash hex lowercase)                                                                                                                        | Trocar a chave invalida todos os hashes já gravados (**Inferência**)                                                                                                                      | Runtime: startup se presente; senão lazy em `getSearchHashService()`                                | `CryptoProvider` → `SEARCH_KEY_PROPERTY`; `HmacSha256SearchHashService(String)`                                                                                    |
+
+Variáveis de ambiente pela regra MP (**Inferência**, leitura por nome exato): `SEEDGRID_PRIVACY_ENCRYPTION_ENABLED`, `SEEDGRID_PRIVACY_CRYPTO_KEY`, `SEEDGRID_PRIVACY_SEARCH_KEY`. O exemplo e o README usam **outras** env vars via expansão no `application.properties` (`SEEDGRID_CRYPTO_KEY`, `SEEDGRID_SEARCH_KEY`, `SEEDGRID_PRIVACY_ENCRYPTION_ENABLED`) — convenção do host, não lida pela lib.
+
+## 3. Propriedades de frameworks recomendadas
+
+| Propriedade | Situação | Origem |
+|---|---|---|
+| `quarkus.hibernate-orm.packages` incluindo `br.com.seedgrid.privacy` | Usada no exemplo, com o comentário de que o pacote da lib contém o converter e o listener referenciados por `@Convert`/`@EntityListeners`. Necessidade só quando o host restringe `packages` — **Inferência** | `java/examples/seedgrid-privacy-example/src/main/resources/application.properties` |
+| `quarkus.datasource.*`, `quarkus.flyway.*` | Do host (a lib não traz migrations; colunas cifradas precisam comportar `v1:iv:ciphertext`, o exemplo usa `length = 512`; hash `length = 64`) | exemplo `Customer` + `V1000__create_customers.sql` |
+
+## 4. Propriedades só de testes/exemplos
+
+| Propriedade | Onde | Observação |
+|---|---|---|
+| `seedgrid.privacy.encryption.enabled=true`, `seedgrid.privacy.crypto.key`, `seedgrid.privacy.search.key` | `java/examples/seedgrid-privacy-example/src/{main,test}/resources/application.properties` | O exemplo define as três propriedades (com valores default fictícios na expansão `${SEEDGRID_CRYPTO_KEY:...}`) |
+| (nenhuma) | testes da própria lib | usam `CryptoProvider.setEncryptionEnabledForTests`/`resetForTests` e construtores package-private com serviços injetados |
+
+## 5. Aliases, obsoletas, renomeações
+
+Nenhuma propriedade renomeada. Renomeações de API (não de config): `@PersonalData` ← antiga `@AuditSensitive`; `@MaskRule` ← `@AuditFieldRule`; `PersonalDataSanitizer` ← `AuditSanitizerService`; `PersonalDataResolver` ← `AuditSensitiveRuleResolverService` (Javadocs).
+
+## 6. Configuração mínima
+
+Modo agnóstico (padrão): **nenhuma** propriedade. Para cifrar:
+
+```properties
+seedgrid.privacy.encryption.enabled=true
+seedgrid.privacy.crypto.key=${SEEDGRID_PRIVACY_CRYPTO_KEY}
+seedgrid.privacy.search.key=${SEEDGRID_PRIVACY_SEARCH_KEY}
+```
+
+## 7. Configuração completa comentada
+
+```properties
+# Liga a cifra at-rest dos @EncryptedField (padrão false = grava cru, sem exigir chave)
+seedgrid.privacy.encryption.enabled=true
+
+# AES-256-GCM: Base64 (ou "base64:<...>") de exatamente 32 bytes. Guardar em secret.
+seedgrid.privacy.crypto.key=<SEGREDO:privacy-crypto-key>
+
+# HMAC-SHA256 do hash de busca: Base64 de >= 32 bytes, DIFERENTE da crypto.key.
+seedgrid.privacy.search.key=<SEGREDO:privacy-search-key>
+
+# Se o host restringe os pacotes do Hibernate, inclua o da lib (converter/listener):
+quarkus.hibernate-orm.packages=<pacote.das.suas.entidades>,br.com.seedgrid.privacy
+```
+
+Gerar uma chave de 32 bytes (ex.): `openssl rand -base64 32`.
+
+## 8. Receitas
+
+- **App sem gestão de chaves**: não configure nada; `@EncryptedField` grava cru e a busca usa o campo normal (`if (CryptoProvider.isEncryptionEnabled()) ... else ...`). O masking continua ativo.
+- **App com cifra e busca por CPF/e-mail**: ligue o flag + as duas chaves; anote `@EncryptedField(searchField="cpfHash", normalize=CANONICAL)` e `@EncryptedField(searchField="emailHash", normalize=EMAIL)`; busque com `hashForSearch(valor, mesmaNormalização)`.
+- **Banco legado em claro → cifrado**: ligar o flag não recifra registros antigos (sem backfill automático); planeje migração.
+- **Desligar com dados cifrados**: mantenha `crypto.key` configurada, senão a leitura de valores `v1:` falha.
+
+## 9. Dúvidas e lacunas
+
+- A falha "fail-closed" com flag ligado e chave ausente ocorre no **primeiro uso**, não no boot.
+- Não há rotação de chave nem versionamento de chave além do prefixo `v1`.
+- Mapeamento com o crate Rust: [[SeedGrid/Extensions/privacy/Configuracao-Rust|Configuração Rust do privacy]].

package/seedgridKB/SeedGrid/Extensions/privacy/Enums.md

@@ -0,0 +1,79 @@
+---
+tags: [seedgrid, library, privacy, enum]
+fonte: java/seedgrid-quarkus-lib-privacy
+branch: main
+commit: 79f8b03eeb
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Privacy — Enums
+
+Voltar: [[SeedGrid/Extensions/privacy/Visao-geral|Visão geral do privacy]] · [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy]] · [[SeedGrid/Extensions/privacy/Rust|Porte Rust]]
+
+Nenhum destes enums é tipo de propriedade de configuração nem é persistido: são atributos de anotações públicas e parâmetros de API.
+
+| Enum | Pacote/arquivo | Usado em | Público? |
+|---|---|---|---|
+| `MaskingStrategy` | `br.com.seedgrid.privacy.masking.MaskingStrategy` | `@PersonalData.type`, `@MaskRule.type`, `PersonalDataMasker.mask`, `PersonalDataSanitizer` | Sim |
+| `SearchNormalization` | `br.com.seedgrid.privacy.SearchNormalization` | `@EncryptedField.normalize`, `EncryptedFieldSearch.hashForSearch` | Sim |
+| `CryptoAlgorithm` | `br.com.seedgrid.privacy.CryptoAlgorithm` | `@EncryptedField.cryptoAlgorithm` | Sim |
+| `SearchAlgorithm` | `br.com.seedgrid.privacy.SearchAlgorithm` | `@EncryptedField.searchAlgorithm` | Sim |
+
+## MaskingStrategy
+
+Arquivo: `java/seedgrid-quarkus-lib-privacy/src/main/java/br/com/seedgrid/privacy/masking/MaskingStrategy.java`.
+
+Cada constante implementa `String maskValue(String value, String param)`; `param` vem de `@PersonalData.maskWith` / `@MaskRule.maskWith` (padrão da anotação: `"***"`).
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `FULL` | Substitui todo o valor por um texto fixo | `param` não vazio → `param`; senão `"***"` | Padrão de `@PersonalData.type` e `@MaskRule.type`. **Confirmado.** |
+| `FORMAT` | Máscara pronta que preserva o formato | `param` não vazio → `param`; senão `"***"` | Comportamento idêntico a `FULL`; a diferença é só semântica (`param` é a máscara completa). O valor original é ignorado. |
+| `PARTIAL` | Revela só os últimos N caracteres | `param` = N (inteiro; ausente ou inválido → 2). Valor mais curto ou igual a N volta inteiro, sem máscara; valor `null` → `null` | Ex.: `"12345678900"`, N=3 → `"********900"`. |
+| `HASH` | SHA-256 hexadecimal minúsculo | `Sha256.hex(value)`; `null` é tratado como string vazia | Irreversível; `param` ignorado. |
+| `TEMPLATE` | Gabarito posicional | `#` revela o caractere da mesma posição (espaço se o valor for menor), `*` mascara, outro caractere é literal; valor ou `param` `null` → `"***"` | O tamanho do resultado é o do gabarito, não o do valor. |
+| `REMOVE` | Remove o campo | `maskValue` devolve `null`; `isRemoval()` é `true`. `PersonalDataSanitizer` remove a chave do JSON; `PersonalDataMasker.mask` devolve `null` | Também usado quando `@MaskRule.remove=true`, que sobrepõe o `type`. |
+
+**Atributos/métodos:** sem campos; `abstract maskValue(String, String)`, `isRemoval()`.
+
+**Serialização:** não é serializado nem persistido; só aparece em anotações (valor da constante em tempo de compilação). Um `strategy` `null` em `PersonalDataMasker.mask` devolve o valor inalterado.
+
+**Onde é usado:** `@PersonalData` / `@MaskRule` (resolvidos por `PersonalDataResolver`, aplicados por `PersonalDataSanitizer`, com precedência override › payload › modelo); `PersonalDataMasker.mask`; embeddables `Address` e `Contact` do commons — ver [[SeedGrid/Extensions/commons/Visao-geral|Visão geral do commons]]. O masking não tem propriedades de configuração.
+
+## SearchNormalization
+
+Arquivo: `java/seedgrid-quarkus-lib-privacy/src/main/java/br/com/seedgrid/privacy/SearchNormalization.java`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `NONE` | Sem normalização: hash do valor exato | `apply` devolve o valor como está | Padrão de `@EncryptedField.normalize`. Case-sensitive. |
+| `CANONICAL` | Forma canônica: `trim`, remove acentos (NFD), minúsculas, mantém só `[a-z0-9]` | `apply` delega ao `ValueNormalizer` (`DefaultValueNormalizer`, substituível via `CryptoProvider.configureNormalizer`) | Para CPF, CNPJ, telefone e CEP. `hashForSearch(valor)` sem 2º argumento usa este modo. |
+| `EMAIL` | `trim` + minúsculas, preservando `@ . - _` | `apply` faz `value.trim().toLowerCase(Locale.ROOT)` | Para e-mail; `CANONICAL` faria e-mails diferentes colidirem. |
+
+**Métodos:** `String apply(String value, ValueNormalizer canonicalNormalizer)` — `null` → `null`; o normalizador só é usado por `CANONICAL`.
+
+**Regra importante:** a mesma normalização deve ser usada na gravação (`EncryptedFieldListener`, a partir de `@EncryptedField.normalize`) e na consulta (`EncryptedFieldSearch.hashForSearch(valor, normalização)`); senão a busca não encontra o registro. A normalização só afeta o hash de busca, nunca o valor cifrado.
+
+**Serialização/persistência:** nenhuma (só atributo de anotação e parâmetro de método).
+
+**Onde é usado:** `@EncryptedField.normalize`; `EncryptedFieldListener`; `EncryptedFieldSearch`; embeddables `Address` (telefone) e `Contact` (cpf, telefone, whatsapp: `CANONICAL`; email: `EMAIL`). Só tem efeito com `seedgrid.privacy.encryption.enabled=true` — ver [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy]].
+
+## CryptoAlgorithm
+
+Arquivo: `java/seedgrid-quarkus-lib-privacy/src/main/java/br/com/seedgrid/privacy/CryptoAlgorithm.java`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `AES_256_GCM` | Cifra AES-256 em modo GCM | **Nenhum código lê** `@EncryptedField.cryptoAlgorithm()`; a cifra é sempre `AesGcmCryptoService` (AES/GCM/NoPadding) | Único valor e padrão do atributo. Escolher outro algoritmo não é possível. |
+
+## SearchAlgorithm
+
+Arquivo: `java/seedgrid-quarkus-lib-privacy/src/main/java/br/com/seedgrid/privacy/SearchAlgorithm.java`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `HMAC_SHA256` | HMAC-SHA256 para o hash de busca | **Nenhum código lê** `@EncryptedField.searchAlgorithm()`; o hash é sempre `HmacSha256SearchHashService` | Único valor e padrão do atributo. |
+
+## Internos
+
+Nenhum.

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

@@ -0,0 +1,172 @@
+---
+tags: [seedgrid, library, privacy, exemplos]
+fonte: java/seedgrid-quarkus-lib-privacy, java/examples/seedgrid-privacy-example
+branch: main
+commit: 79f8b03eeb
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Privacy — Exemplos
+
+Voltar: [[SeedGrid/Extensions/privacy/Visao-geral|Visão geral do privacy]] · [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy]]
+
+## Dependência
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-privacy</artifactId>
+    <version>2026.07.27</version>
+</dependency>
+```
+
+## Entidade com campos cifrados e pesquisáveis (exemplo real)
+
+Fonte: `java/examples/seedgrid-privacy-example/src/main/java/br/com/seedgrid/privacyexample/entity/Customer.java` (Lombok `@Getter/@Setter/@NoArgsConstructor` omitidos).
+
+```java
+@Entity
+@Table(name = "customers")
+@EntityListeners(EncryptedFieldListener.class)
+public class Customer {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    // cifrado, NÃO pesquisável (sem searchField)
+    @Convert(converter = EncryptedFieldAttributeConverter.class)
+    @EncryptedField
+    @Column(nullable = false, length = 512)
+    private String name;
+
+    @Convert(converter = EncryptedFieldAttributeConverter.class)
+    @EncryptedField(searchField = "emailHash", normalize = SearchNormalization.EMAIL)
+    @Column(nullable = false, length = 512)
+    private String email;
+
+    @Column(name = "email_hash", length = 64)
+    private String emailHash;
+
+    @Convert(converter = EncryptedFieldAttributeConverter.class)
+    @EncryptedField(searchField = "cpfHash", normalize = SearchNormalization.CANONICAL)
+    @Column(nullable = false, length = 512)
+    private String cpf;
+
+    @Column(name = "cpf_hash", length = 64)
+    private String cpfHash;
+
+    @Convert(converter = EncryptedFieldAttributeConverter.class)
+    @EncryptedField
+    @Column(length = 512)
+    private String phone;
+}
+```
+
+## Busca por hash e mascaramento (exemplo real)
+
+Fonte: `.../privacyexample/service/CustomerService.java` (trecho).
+
+```java
+public Optional<Customer> findByEmail(String email) {
+    EncryptedFieldSearch search = CryptoProvider.getSecureSearch();
+    String hash = search.hashForSearch(email, SearchNormalization.EMAIL);
+    return repository.findByEmailHash(hash);      // find("emailHash", hash).firstResultOptional()
+}
+
+public Optional<Customer> findByCpf(String cpf) {
+    EncryptedFieldSearch search = CryptoProvider.getSecureSearch();
+    String hash = search.hashForSearch(cpf, SearchNormalization.CANONICAL);
+    return repository.findByCpfHash(hash);
+}
+
+public CustomerResponse mask(CustomerResponse response) {
+    return sanitizer.sanitize(response, CustomerResponse.class);  // PersonalDataSanitizer injetado
+}
+```
+
+DTO de saída com regras de masking (fonte: `.../dto/CustomerResponse.java`):
+
+```java
+public class CustomerResponse {
+    public Long id;
+
+    @PersonalData(type = MaskingStrategy.PARTIAL, maskWith = "4")
+    public String name;
+
+    @PersonalData(type = MaskingStrategy.FULL)
+    public String email;
+
+    @PersonalData(type = MaskingStrategy.FORMAT, maskWith = "***.***.***-**")
+    public String cpf;
+
+    @PersonalData(type = MaskingStrategy.PARTIAL, maskWith = "4")
+    public String phone;
+}
+```
+
+## Busca bimodal (cifra opcional)
+
+Fonte: `README.md`.
+
+```java
+if (CryptoProvider.isEncryptionEnabled()) {
+    String hash = new EncryptedFieldSearch().hashForSearch(cpf);   // CANONICAL por padrão
+    return repository.find("cpfHash", hash).firstResult();
+}
+return repository.find("cpf", cpf).firstResult();
+```
+
+> `new EncryptedFieldSearch()` exige `seedgrid.privacy.search.key` — por isso fica dentro do `if`.
+
+## Campo cifrado dentro de `@Embeddable`
+
+Fonte: `README.md` (comportamento confirmado em `EncryptedFieldListener#applyTo`).
+
+```java
+@Embeddable
+public class Contato {
+    @EncryptedField(searchField = "cpfHash", normalize = SearchNormalization.CANONICAL)
+    @Convert(converter = EncryptedFieldAttributeConverter.class)
+    private String cpf;
+
+    private String cpfHash;          // irmão, no MESMO embeddable
+}
+
+@Entity
+@EntityListeners(EncryptedFieldListener.class)
+public class Empresa {
+    @Embedded
+    private Contato representante;
+}
+```
+
+Os embeddables `Address`/`Contact` do commons seguem esse padrão — ver [[SeedGrid/Extensions/commons/Visao-geral|Visão geral do commons]].
+
+## Masking de valores soltos
+
+Fonte: `README.md` + assinaturas de `PersonalDataMasker`.
+
+```java
+String cpf  = PersonalDataMasker.cpf("12345678900");     // ***.***.***-00
+String cnpj = PersonalDataMasker.cnpj("12345678000190");
+String cep  = PersonalDataMasker.cep("01310100");        // 01310-***
+String x    = PersonalDataMasker.mask("12345678900", MaskingStrategy.PARTIAL, "3"); // ********900
+
+@Override
+public String toString() {
+    return "Contact [cpf=" + PersonalDataMasker.cpf(cpf)
+            + ", email=" + PersonalDataMasker.mask(email, MaskingStrategy.FULL, null) + "]";
+}
+```
+
+## Configuração
+
+```properties
+seedgrid.privacy.encryption.enabled=true
+seedgrid.privacy.crypto.key=<SEGREDO:privacy-crypto-key>
+seedgrid.privacy.search.key=<SEGREDO:privacy-search-key>
+quarkus.hibernate-orm.packages=<pacote.das.entidades>,br.com.seedgrid.privacy
+```
+
+Detalhes: [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy]].