@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,95 @@
+---
+tags: [seedgrid, extension, security, enum]
+fonte: java/seedgrid-quarkus-ext-security
+branch: main
+commit: 450735386e
+analisado-em: 2026-10-14
+---
+
+# security — Enums (Quarkus)
+
+Voltar para [[SeedGrid/Extensions/security/Visao-geral|Visão geral do security]] · [[SeedGrid/Extensions/security/Configuracao|Configuração]] · [[SeedGrid/Extensions/security/Rust|Porte Rust]]
+
+Caminho-base: `java/seedgrid-quarkus-ext-security/runtime/src/main/java/br/com/seedgrid/security/`. Os módulos `deployment` e testes não declaram enums de contrato.
+
+## Índice
+
+| Enum | Pacote/arquivo | Usado em | Público? |
+|---|---|---|---|
+| [[SeedGrid/Extensions/security/Enums#TwoFactorMethodType\|TwoFactorMethodType]] | `twofactors/TwoFactorMethodType.java` | Corpo de `POST /2f/enable` e `POST /2f/setup/confirm`, resposta de enable, estratégias 2FA, config `2f.allowed-methods` (por código textual) | Sim |
+| [[SeedGrid/Extensions/security/Enums#EntryRequestStatus\|EntryRequestStatus]] | `entities/EntryRequestStatus.java` | Coluna `entry_requests.status`, self-enter, job de limpeza | Sim (persistido) |
+| [[SeedGrid/Extensions/security/Enums#EntryRequestOrigin\|EntryRequestOrigin]] | `entities/EntryRequestOrigin.java` | Coluna `entry_requests.origin`, self-enter | Sim (persistido) |
+| [[SeedGrid/Extensions/security/Enums#UserCreateOptions.Delivery\|UserCreateOptions.Delivery]] | `services/UserCreateOptions.java` (enum aninhado) | API Java para quem cria usuário por fluxo próprio (`UserService#createUser`) | Sim (API de bean) |
+
+## TwoFactorMethodType
+
+Arquivo: `…/security/twofactors/TwoFactorMethodType.java` — FQN `br.com.seedgrid.security.twofactors.TwoFactorMethodType`. Javadoc: helper de tipo para os métodos 2FA padrão; o código do método é guardado como **String** no banco para permitir implementações custom.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `EMAIL` | Código de uso único por e-mail | `EmailTwoFactorStrategy#getMethodCode`; `TwoFactorController` exige e-mail confirmado para ativar | Confirmado |
+| `WHATSAPP` | Código de uso único por WhatsApp | `WhatsappTwoFactorStrategy#getMethodCode`; ativação exige WhatsApp do usuário e `2f.whatsapp.channel-id`; `MeProfileController` compara com o método primário | Confirmado |
+| `TOTP` | Código de app autenticador | `TotpTwoFactorStrategy#getMethodCode`; `TwoFactorController` (setup/confirm e disable); `TwoFactorService` grava como método primário ao confirmar | Confirmado |
+| `BACKUP_CODE` | Código de backup | Existe no enum, mas **nenhum código o referencia** (não há estratégia com esse código; o fallback por backup code em `TwoFactorService` usa `BackupCodeService` direto). Enviá-lo em `method` passa na desserialização, mas não há estratégia registrada para ele | Confirmado (busca por referências) |
+
+- **Campos/métodos:** `getCode()` (igual ao nome da constante) e `static fromCode(String)` — comparação `equalsIgnoreCase`, retorna `null` se não achar. `fromCode` não é chamado em lugar nenhum do módulo.
+- **JSON:** sem `@JsonValue`/`@JsonCreator`; o Jackson usa o **nome exato** (maiúsculas, case-sensitive) em `Enable2FADTO.method`, `SetupConfirmDTO.method` e `Enable2FAResponseDTO.method`. Valor desconhecido → erro de desserialização (400).
+- **Persistência:** o enum **não** é persistido; `users.two_factor_primary_method` é `VARCHAR(32)` com o código textual (`User#enableTwoFactor(String)`). Não há CHECK constraint (V202), então estratégias custom (ex.: `SMS`) podem ser gravadas.
+- **Config:** `seedgrid.security.2f.allowed-methods` é `List<String>` (não usa o enum); os valores são normalizados com `trim().toUpperCase()` e cruzados com as estratégias registradas. Ver [[SeedGrid/Extensions/security/Configuracao|Configuração §2.5]].
+- **Observação:** como o DTO usa o enum, um método custom (`SMS`) não pode ser ativado por `POST /2f/enable` (o corpo é rejeitado) mesmo estando em `allowed-methods`. *Inferência* a partir do tipo do campo `method`.
+
+## EntryRequestStatus
+
+Arquivo: `…/security/entities/EntryRequestStatus.java` — FQN `br.com.seedgrid.security.entities.EntryRequestStatus`. Sem Javadoc; significados deduzidos do tratamento.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `PENDING_EMAIL` | Aguardando confirmação do e-mail (OTP no signup público; aceite do convite) | Estado inicial de `requestAccess` e do convite (`SelfEnterService`); `confirmEmail`/`resendEmail` exigem este estado; o job expira registros neste estado | Confirmado |
+| `PENDING_APPROVAL` | Aguardando aprovação administrativa | `EntryRequest#markEmailConfirmed` e `#markInvitationAccepted` levam a este estado; `approve`/`reject` só aceitam este estado; listagem "to-approve" | Confirmado |
+| `APPROVED` | Aprovada; usuário criado | `EntryRequest#approve`; elegível a purga | Confirmado |
+| `REJECTED` | Rejeitada por um administrador | `EntryRequest#reject`; elegível a purga | Confirmado |
+| `EXPIRED` | Expirada | `EntryRequest#expire` (ao aprovar/confirmar uma solicitação vencida) e `EntryRequestRepository#expireOldRequests` (PENDING_EMAIL/PENDING_APPROVAL com `expiresAt` vencido); elegível a purga | Confirmado |
+
+- **Persistência:** `@Enumerated(EnumType.STRING)` em `entry_requests.status` (`VARCHAR(30)`). **CHECK** `chk_entry_request_status` (V201) aceita exatamente `PENDING_EMAIL, PENDING_APPROVAL, APPROVED, REJECTED, EXPIRED` — igual às constantes.
+- **JSON:** `EntryRequestDTORes.status` é do tipo `EntryRequestStatus`, serializado pelo nome da constante (sem `@JsonValue`).
+- **Purga:** `EntryRequestCleanupJob` apaga `APPROVED/REJECTED/EXPIRED` mais antigos que `self-enter.cleanup.purge-after` ([[SeedGrid/Extensions/security/Configuracao|Configuração]]).
+
+```mermaid
+stateDiagram-v2
+  [*] --> PENDING_EMAIL: requestAccess / convite
+  PENDING_EMAIL --> PENDING_APPROVAL: confirmEmail / aceite do convite
+  PENDING_APPROVAL --> APPROVED: approve
+  PENDING_APPROVAL --> REJECTED: reject
+  PENDING_EMAIL --> EXPIRED: expira
+  PENDING_APPROVAL --> EXPIRED: expira
+```
+
+Convite com `invite-needs-approval=false` chama `approve` logo após o aceite (vai direto a `APPROVED`).
+
+## EntryRequestOrigin
+
+Arquivo: `…/security/entities/EntryRequestOrigin.java` — FQN `br.com.seedgrid.security.entities.EntryRequestOrigin`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `PUBLIC` | Pedido criado pelo signup público | `SelfEnterService#requestAccess`; confirmação/reenvio de e-mail exigem esta origem; também é o default em `@PrePersist` quando nulo e o `DEFAULT 'PUBLIC'` da coluna | Confirmado |
+| `INVITE` | Pedido criado por convite administrativo | `SelfEnterService` (convite); aceite/complete/reenvio de convite exigem esta origem; repositório consulta convites pendentes | Confirmado |
+
+- **Persistência:** `@Enumerated(EnumType.STRING)`, coluna `origin VARCHAR(20) NOT NULL DEFAULT 'PUBLIC'` (V217). **Não há CHECK constraint** para `origin` (diferente de `status`).
+- Relações: `public-enabled` rege `PUBLIC`; `invite-enabled` rege `INVITE` — [[SeedGrid/Extensions/security/Configuracao|Configuração §2.6]].
+
+## UserCreateOptions.Delivery
+
+Arquivo: `…/security/services/UserCreateOptions.java` — FQN `br.com.seedgrid.security.services.UserCreateOptions.Delivery` (enum aninhado no record `UserCreateOptions`). Define como as credenciais iniciais chegam ao usuário criado por `UserService#createUser(dto, options)`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `SECURITY_WELCOME_EMAIL` | E-mail de boas-vindas do security | `UserService#deliverInitialCredentials` chama `EmailServiceInterface#sendWelcomeEmail`; é o default (`UserCreateOptions.defaults()` e quando `delivery` é nulo) | Confirmado |
+| `NONE` | Nenhum envio | Sem ação; `createUser` lança `BadRequestException("Senha obrigatoria…")` se a senha teria de ser gerada | Confirmado |
+| `CALLBACK` | Envio feito pelo host via `ActivationMailer` | Exige `activationMailer` não nulo (senão `IllegalArgumentException`); falha do envio só é logada com `mailerBestEffort=true` | Confirmado |
+
+- Não é persistido nem serializado em JSON; é parâmetro Java. Construtores de conveniência no record criam as variantes `NONE` e `CALLBACK`.
+
+## Internos
+
+Nenhum enum interno encontrado no `runtime` além dos listados.

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

@@ -0,0 +1,218 @@
+---
+tags: [seedgrid, extension, security, exemplos]
+fonte: java/seedgrid-quarkus-ext-security; java/examples/seedgrid-security-example
+branch: main
+commit: 450735386e
+analisado-em: 2026-10-14
+---
+
+# security — Exemplos (Quarkus)
+
+Ver também: [[SeedGrid/Extensions/security/Visao-geral|Visão geral do security]] · [[SeedGrid/Extensions/security/Configuracao|Configuração do security]] · [[SeedGrid/Extensions/security/Rust|Porte Rust]]
+
+Fontes: assinaturas lidas em `java/seedgrid-quarkus-ext-security/runtime/src/main/java/br/com/seedgrid/security/spi/*.java`; testes em `runtime/src/test/java/br/com/seedgrid/security/`; `README.md` da extension; exemplo `java/examples/seedgrid-security-example` (repo próprio, commit `86cfc37`, depende de `seedgrid-security:2026.09.25`). Exemplos marcados *ilustrativo* combinam a API real com lógica de negócio fictícia.
+
+## 1. Dependência
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-security</artifactId>
+    <version>2026.10.14</version>
+</dependency>
+```
+
+Chaves RSA (README):
+
+```bash
+openssl genrsa -out src/main/resources/keys/private.pem 2048
+openssl rsa -in src/main/resources/keys/private.pem -pubout -out src/main/resources/keys/public.pem
+```
+
+> A chave privada lida por `RsaKeyProvider` precisa estar em PKCS#8 (`-----BEGIN PRIVATE KEY-----`). OpenSSL 3 gera PKCS#8 por padrão; com OpenSSL 1.x use `openssl pkcs8 -topk8 -nocrypt` (*Inferência* a partir do `PKCS8EncodedKeySpec` usado no código).
+
+Configuração mínima: [[SeedGrid/Extensions/security/Configuracao|Configuração §6]].
+
+## 2. Proteger endpoints do host
+
+Anotações Quarkus + RBAC do security (README "Proteger endpoints"). As permissões vêm das roles do token via `RbacSecurityIdentityAugmentor`.
+
+```java
+import br.com.seedgrid.security.annotations.MonoCompany;
+import io.quarkus.security.Authenticated;
+import io.quarkus.security.PermissionsAllowed;
+import jakarta.annotation.security.RolesAllowed;
+import jakarta.ws.rs.*;
+
+@Path("/relatorios")            // path sem "/public/" => exige Bearer JWT
+public class RelatorioResource {   // ilustrativo
+
+    @GET
+    @PermissionsAllowed("USER_READ")          // permissão derivada das roles
+    public String listar() { return "ok"; }
+
+    @GET @Path("/admin")
+    @RolesAllowed("ADMIN")
+    public String admin() { return "ok"; }
+
+    @GET @Path("/sem-empresa")
+    @Authenticated
+    @MonoCompany                              // CompanyContextFilter ignora
+    public String semEmpresa() { return "ok"; }
+}
+```
+
+Rotas públicas precisam ter `/public/` no path (`JwtAuthenticationFilter#isPublicPath`).
+
+## 3. Fluxo HTTP do cliente
+
+```http
+POST /public/auth/login
+{ "login": "admin@exemplo.com", "password": "<senha>" }
+-> 200 { "token": "<JWT>", "tokenType": "Bearer", "refreshToken": "<opaco>" }
+   ou desafio 2FA com tempToken (quando 2f.enabled=true e o usuário ativou 2FA)
+
+POST /public/2f/verify
+{ "tempToken": "<tempToken>", "code": "123456" }
+
+POST /me/select-company            (Authorization: Bearer <JWT>)
+{ "companyPublicId": "<uuid>" }    -> novo par escopado | 403
+
+POST /public/auth/refresh
+{ "refreshToken": "<opaco>" }      -> preserva a empresa do token
+```
+
+(README §"Exemplos de rotas".)
+
+## 4. SPIs
+
+Todas as implementações padrão são `@DefaultBean`; um bean `@ApplicationScoped` do host com o mesmo tipo substitui.
+
+### 4.1 `UserAdditionalFieldsValidator` — regras de `additionalAttributes`
+
+Assinatura: `void validate(User user, Map<String, JsonNode> additionalAttributes)`. Exemplo real do teste `RejectingUserAdditionalFieldsValidator`:
+
+```java
+import br.com.seedgrid.security.entities.User;
+import br.com.seedgrid.security.exceptions.InvalidUserAdditionalAttributesException;
+import br.com.seedgrid.security.spi.UserAdditionalFieldsValidator;
+import com.fasterxml.jackson.databind.JsonNode;
+import jakarta.enterprise.context.ApplicationScoped;
+import java.util.Map;
+
+@ApplicationScoped
+public class RejectingUserAdditionalFieldsValidator implements UserAdditionalFieldsValidator {
+
+    public static final String REJECT_KEY = "__reject";
+
+    @Override
+    public void validate(User user, Map<String, JsonNode> additionalAttributes) {
+        if (additionalAttributes != null && additionalAttributes.containsKey(REJECT_KEY)) {
+            throw new InvalidUserAdditionalAttributesException(
+                    "Atributo " + REJECT_KEY + " rejeitado pela aplicacao");
+        }
+    }
+}
+```
+
+A exceção vira HTTP 400. Os limites de tamanho/profundidade/chaves são aplicados antes, por `seedgrid.security.user.additional-attributes.*`.
+
+### 4.2 `AllowedCompaniesResolver` — visão "todas as empresas"
+
+Assinatura: `AllowedCompanies resolve(User user, List<String> roles)`; `AllowedCompanies.of(List<Long>)` e `AllowedCompanies.seeingAll(List<Long>)`. *Ilustrativo* (adaptado do README — o README usa `getMemberships()`; a entidade expõe `getActiveCompanies()`):
+
+```java
+@ApplicationScoped
+public class MyAllowedCompaniesResolver implements AllowedCompaniesResolver {
+    @Override
+    public AllowedCompanies resolve(User user, List<String> roles) {
+        List<Long> ids = user.getActiveCompanies().stream().map(Company::getId).toList();
+        return roles.contains("PLATFORM_ADMIN") ? AllowedCompanies.seeingAll(ids) : AllowedCompanies.of(ids);
+    }
+}
+```
+
+### 4.3 `JwtTokenCustomizer` — claims extras (ex.: `audience`)
+
+Assinatura **atual**: `Map<String, Object> customizeClaims(User user, List<String> roles, String hostHeader, Long scopedCompanyId)` (o README mostra uma versão antiga com 3 parâmetros). O claim `audience` é o que o `RbacSecurityIdentityAugmentor` usa para filtrar permissões por audience. *Ilustrativo*:
+
+```java
+@ApplicationScoped
+public class AudienceTokenCustomizer implements JwtTokenCustomizer {
+    @Override
+    public Map<String, Object> customizeClaims(User user, List<String> roles, String hostHeader, Long scopedCompanyId) {
+        return scopedCompanyId == null ? Map.of() : Map.of("audience", "client");
+    }
+}
+```
+
+Combine com `seedgrid.security.account.assignable-permission-audiences=client` para que admins de conta possam atribuir permissões `client`.
+
+### 4.4 `JwtTokenValidator`
+
+`void validateCustomClaims(JWTClaimsSet claims, String hostHeader)` (Nimbus `JWTClaimsSet`) — chamado por `TokenVerifier` depois de assinatura, issuer e expiração. Use para validar claims próprios (ex.: subdomínio).
+
+### 4.5 `TwoFactorStrategy` — novo método 2FA
+
+```java
+public interface TwoFactorStrategy {
+    String getMethodCode();
+    boolean canInitiate(User user);
+    default boolean canEnroll(User user) { return canInitiate(user); }
+    TwoFactorInitResult initiate(User user, TwoFactorContext context);
+    TwoFactorVerifyResult verify(User user, String code, TwoFactorContext context);
+}
+```
+
+O código retornado por `getMethodCode()` precisa constar em `seedgrid.security.2f.allowed-methods` para aparecer ao usuário (`TwoFactorController#getAllowedMethods`).
+
+### 4.6 E-mail e templates
+
+- `EmailServiceInterface`: `sendEmailConfirmation`, `sendPasswordReset`, `generateToken`, `sendHtmlEmail(to, subject, htmlBody, textBody)`, `sendWelcomeEmail(user, temporaryPassword, confirmationToken)`. Os testes trocam a implementação com `@Alternative @Priority(1)` (`TestEmailService`), usando `TemplateSecurityProvider` + `SecurityLinkBuilder`.
+- `TemplateSecurityProvider`: `emailConfirmation`, `passwordReset`, `entryRequestConfirmation`, `entryRequestApproved`, `welcomeEmail`, `twoFactorCode` (abstratos) e `entryRequestConfirmationCode`, `entryRequestInvitation`, `twoFactorWhatsappText` (default). `entryRequestApproved` precisa ser implementado, mas hoje não é chamado (o e-mail de aprovação do self-enter não é enviado). Templates padrão: `runtime/src/main/resources/templates/security-default/html/*.html` e `txt/two-factor-code-whatsapp.txt`.
+- `TwoFactorEmailTemplateProvider#buildCodeEmail(User, String code, int expiresInMinutes)` → `EmailTemplate(subject, htmlBody, textBody)`.
+
+### 4.7 Outras SPIs
+
+| SPI | Método |
+|---|---|
+| `LoginScopeResolver` | `Long resolveLoginScope(User user, String requestedScope)` |
+| `SecurityScopeResolverProvider` | `String currentScope()` |
+| `UserQuotaValidator` | `void assertCanAddUser(Company company)` |
+| `AccountUserActivationMailer` | `void deliver(User user, ActivationCredentials credentials)` |
+
+## 5. Configuração por cenário (testes)
+
+Profiles reais de teste mostram combinações válidas:
+
+```java
+// SelfEnterInviteOnlyProfile
+Map.of(
+    "seedgrid.security.self-enter.enabled", "true",
+    "seedgrid.security.self-enter.public-enabled", "false",
+    "seedgrid.security.self-enter.invite-enabled", "true");
+```
+
+Outros: `SelfEnterInviteAutoApproveProfile` (`invite-needs-approval=false`), `SelfEnterNoDefaultRoleProfile` (`default-role` inexistente → aprovação falha), `BootstrapDisabledProfile` (`bootstrap.enabled=false`), `RefreshTokenGraceWindowProfile` (`refresh-token.reuse-grace-window`).
+
+## 6. Trecho de `application.properties` do exemplo
+
+De `java/examples/seedgrid-security-example/src/main/resources/application.properties` (segredos substituídos por placeholders):
+
+```properties
+seedgrid.security.2f.enabled=true
+seedgrid.security.2f.allowed-methods=EMAIL,TOTP,WHATSAPP
+seedgrid.security.2f.totp.issuer=SeedGrid.CRM
+seedgrid.security.2f.otp-qrcode.branding.enabled=true
+seedgrid.security.2f.otp-qrcode.logo=classpath:/images/logo-qrcode-otp.png
+seedgrid.security.2f.otp-qrcode.size=350
+seedgrid.security.rbac.cache-ttl=${SECURITY_RBAC_CACHE_TTL:PT5M}
+seedgrid.security.encryption.key=<SEGREDO:security-encryption-key-base64-32-bytes>
+seedgrid.security.self-enter.enabled=true
+seedgrid.security.self-enter.request-ttl=PT2M
+seedgrid.security.self-enter.email-token-ttl=PT10M
+seedgrid.security.self-enter.cleanup.purge-after=PT10M
+seedgrid.security.self-enter.cleanup.cron=0 */5 * * * ?
+```
+
+Observação: o exemplo não define `seedgrid.security.frontend.self-enter-path` (cai no default do mp-config) e usa TTLs curtos de demonstração.

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

@@ -0,0 +1,203 @@
+---
+tags: [seedgrid, extension, security, rust]
+fonte: rust/seedgrid-rust-crate-security
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# `seedgrid-security` — porte Rust
+
+Lado Java: [[SeedGrid/Extensions/security/Visao-geral|Visão geral do security (Quarkus)]] · [[SeedGrid/Extensions/security/Configuracao|Configuração Java]]
+Configuração deste crate: [[SeedGrid/Extensions/security/Configuracao-Rust|Configuração Rust do security]]
+
+## Objetivo
+
+Porte em Rust da extensão `seedgrid-quarkus-ext-security`, distribuído como **crate biblioteca** (Axum 0.8 + sqlx/Postgres). O host constrói um `SecurityState` e monta o `router` no servidor Axum dele. Funcionalidades (Confirmado em `src/lib.rs`, `README.md`, `src/routes.rs`):
+
+- Autenticação **JWT RS256** (claims `sub/upn/userName/whatsapp/groups/allowedCompanies/companyId/companyRoot/allCompanies` + claims via SPI).
+- **Refresh tokens** rotativos com *family*, detecção de reuso e janela de graça para rotação concorrente.
+- Senha **BCrypt** sobre `publicId + senha` (emite `$2a$10$`, compatível com o jBCrypt do Java).
+- **RBAC** (roles + permissões com `audience`/`is_default`), empresas, memberships por conta (`is_root`, roles por conta, desativação por conta), gestão pela plataforma e pela própria conta (`/me/security/*`).
+- **2FA** TOTP / e-mail / WhatsApp + backup codes; segredo TOTP cifrado (AES-256-GCM).
+- **Self-enter** (auto-registro com OTP + aprovação, convites).
+- **Avatar** via crate `seedgrid-filemanagement`; **auditoria** via `seedgrid-audit`; **rate limit** via `seedgrid-resilience` + `seedgrid-cache`; **PII at-rest** via `seedgrid-privacy`; SMTP real via `lettre`.
+- Erros RFC 7807 (`application/problem+json`); OpenAPI própria via `utoipa` (`seedgrid_security::openapi()`).
+
+## Coordenadas
+
+| Item | Valor |
+|---|---|
+| Diretório | `rust/seedgrid-rust-crate-security` |
+| Pacote Cargo / lib | `seedgrid-security` / `seedgrid_security` |
+| Versão | `version.workspace = true` → `2026.10.14` (`rust/Cargo.toml`, `[workspace.package]`). |
+| Edição / MSRV | `edition = "2021"`, `rust-version = "1.82"` |
+| Licença declarada | `LicenseRef-Commercial` |
+| Features Cargo | nenhuma |
+| Dependências SeedGrid | `seedgrid-rust-crate-filemanagent` (como `seedgrid-filemanagement`), `-audit`, `-resilience`, `-cache`, `-whatsapp`, `-privacy` (path deps). Reexporta `seedgrid_audit`, `seedgrid_cache`, `seedgrid_resilience`, `seedgrid_whatsapp`. |
+
+## API pública (principais símbolos)
+
+| Símbolo | Papel |
+|---|---|
+| `SecurityConfig` (+ `from_env`, `new`) | configuração agregada — ver [[SeedGrid/Extensions/security/Configuracao-Rust\|Configuração Rust]] |
+| `migrate(&PgPool)` / `MIGRATOR` | aplica `migrations/0199..0230` em tabela de histórico própria `_sqlx_migrations_security` (`src/migrations.rs`) |
+| `SecurityState::builder(pool, config)` → `SecurityStateBuilder` | seams: `.email`, `.whatsapp`, `.storage`, `.scope_resolver`, `.jwt_customizer`, `.jwt_validator`, `.login_scope_resolver`, `.allowed_companies`, `.user_quota_validator`, `.user_additional_fields_validator`, `.auditor`, `.cache`, `.template_provider`, `.two_factor_template_provider`, `.pool_resolver`, `.account_user_activation_mailer`; `.build()` |
+| `router(SecurityState)` | `axum::Router` com todas as rotas abaixo |
+| `bootstrap(&SecurityState)` | garante a empresa-plataforma e o primeiro admin |
+| `cleanup_entry_requests` / `spawn_entry_request_cleanup(state, interval)` | limpeza de pedidos de self-enter (job tokio) |
+| `SecurityPlatform::assemble(Option<&PgPool>, SecurityOverrides)` | "autostart" estilo Quarkus: habilita só com Postgres **e** chaves RSA; roda `migrate`, `build` e (opcional) `bootstrap`; retorna `Ok(None)` se desabilitado |
+| `SmtpEmailService`, `DefaultTemplateSecurityProvider`, `DefaultTwoFactorEmailTemplateProvider`, `TemplateSecurityProvider`, `TwoFactorEmailTemplateProvider` | e-mail e templates |
+| `spi::*` | `PoolResolver`, `AllowedCompaniesResolver`, `LoginScopeResolver`, `UserQuotaValidator`, `UserAdditionalFieldsValidator`, `JwtTokenCustomizer`, `JwtTokenValidator`, `ScopeResolver`, `EmailService`, `WhatsappSender`, `AvatarStorage` (todos com default embutido) |
+| `services::users`, `services::rbac`, `services::company_users`, `services::company_roles`... | serviços reutilizados pelos crates de tenancy/apikeys (ex.: `users::create_user_with_options`, `rbac::resolve_for_company`, `rbac::require_platform_scope`) |
+
+## Endpoints (Confirmado em `src/routes.rs`)
+
+| Grupo | Método + path |
+|---|---|
+| Auth pública | `POST /public/auth/login`, `POST /public/auth/refresh`, `GET /public/auth/confirm-email`, `POST /public/auth/forgot-password`, `GET /public/auth/reset-password` |
+| 2FA pública | `POST /public/2f/verify`, `POST /public/2f/resend` |
+| Self-enter público | `POST /public/self-enter/requests`, `POST /public/self-enter/requests/{id}/confirm-email`, `POST /public/self-enter/requests/{id}/resend-email`, `GET /public/self-enter/invitations/{token}`, `POST /public/self-enter/invitations/{token}/complete` |
+| Outras públicas | `GET /public/companies` |
+| Usuário logado | `GET /me/permissions`, `GET /me/companies`, `POST /me/select-company`, `GET\|PUT /me/profile`, `PUT /me/profile/password`, `POST\|GET\|DELETE /me/profile/avatar` |
+| Gestão pela conta | `GET\|POST /me/security/roles`, `GET /me/security/roles/permissions`, `GET\|PUT\|DELETE /me/security/roles/{id}`, `GET\|POST /me/security/users`, `GET\|PUT\|DELETE /me/security/users/{id}`, `POST /me/security/users/{id}/resend-activation` |
+| Usuários (plataforma) | `GET\|POST /users`, `GET\|PATCH\|DELETE /users/{public_id}`, `POST /users/avatars/defaults`, `POST\|GET\|DELETE /users/{public_id}/avatar`, `PUT /users/change-password`, `PUT /users/{public_id}/memberships`, `PUT\|DELETE /users/{public_id}/memberships/{company_public_id}` |
+| Roles / permissões | `GET\|POST /roles`, `GET /roles/integration`, `GET\|PATCH\|DELETE /roles/{public_id}`, `GET /permissions`, `GET /permissions/{public_id}` |
+| Empresas | `GET\|POST /companies`, `GET\|PATCH\|DELETE /companies/{public_id}` |
+| 2FA autenticado | `POST /2f/setup`, `/2f/confirm`, `/2f/disable`, `/2f/backup-codes`, `/2f/enable`, `/2f/setup/confirm`, `/2f/totp/confirm`; `GET /2f/status` |
+| Self-enter admin | `GET /self-enter/requests/to-approve`, `GET\|POST /self-enter/invitations`, `POST /self-enter/invitations/{id}/resend`, `POST /self-enter/requests/{id}/approve`, `POST /self-enter/requests/{id}/reject` |
+
+Rotas de plataforma (`/users`, `/roles`, `/permissions`, `/companies`) exigem, além da permissão, root global ou membro ativo da empresa-plataforma (`rbac::require_platform_scope`). Rotas `/self-enter*` respondem 404 antes da autenticação quando o self-enter está desligado. Rotas públicas têm rate limit por IP (`src/ratelimit.rs`).
+
+## Exemplos
+
+Uso básico (Confirmado em `src/lib.rs` doc-test e `README.md`):
+
+```rust
+use seedgrid_security::{router, SecurityConfig, SecurityState};
+
+async fn boot(pool: sqlx::PgPool) -> Result<(), Box<dyn std::error::Error>> {
+    let config = SecurityConfig::from_env()?;
+    seedgrid_security::migrate(&pool).await?;
+    let state = SecurityState::builder(pool, config).build()?;
+    let app = axum::Router::new().merge(router(state));
+    let _ = app;
+    Ok(())
+}
+```
+
+Montagem "estilo Quarkus" (Confirmado em `src/platform.rs`):
+
+```rust
+use seedgrid_security::{SecurityOverrides, SecurityPlatform};
+
+async fn boot(pool: Option<sqlx::PgPool>) -> Result<(), String> {
+    if let Some(state) = SecurityPlatform::assemble(pool.as_ref(), SecurityOverrides::enabled()).await? {
+        let app = axum::Router::new().merge(seedgrid_security::router(state));
+        let _ = app;
+    }
+    Ok(())
+}
+```
+
+> `SecurityOverrides::default()` deixa `run_bootstrap = false` (derive `Default`); `SecurityOverrides::enabled()` liga o bootstrap.
+
+Validador de `additionalAttributes` e override de templates: ver `README.md` do crate (`UserAdditionalFieldsValidator`, `DefaultTemplateSecurityProvider::with_host_dir`).
+
+Exemplo executável: `rust/examples/seedgrid-security-apikeys-example/src/main.rs` (security + apikeys; migra security antes de apikeys, `from_env`, `bootstrap`, merge dos routers e middleware `api_key_auth`).
+
+## Migrations
+
+`migrations/0199_enable_extensions.sql` a `0230_user_company_active.sql` (32 arquivos), porte das V200..V233 do Flyway Java. Tabela de histórico isolada `_sqlx_migrations_security`. Precisam rodar **antes** das de apikeys/login-tenancy/backup (dependência de dados: `users`, `roles`, `permissions`, `companies`).
+
+## Testes
+
+- Unitários em `src/**` (`cargo test --lib`), ex.: `config::tests` (durações, base64 DER→PEM, bool).
+- Integração em `tests/` com Postgres real via Testcontainers: `integration.rs`, `rate_limit.rs`, `email_templates.rs` e ~30 arquivos `java_parity_*.rs` (port dos testes Java: auth, refresh grace window, 2FA, self-enter, RBAC, memberships, cripto de campos, bootstrap do primeiro admin, gestão de conta/plataforma etc.).
+- **Não executados** nesta análise.
+
+## Limitações conhecidas
+
+- Sem cache RBAC (resolução direta no banco).
+- Status HTTP 422 do módulo Java viram 400 em várias regras.
+- Política de senha com defaults mais rígidos que o módulo Java.
+- Backend de storage do avatar é seam do host (não lido de config).
+- Tolerância TOTP fixa em ±1 janela (sem config); nomes JWT `SEEDGRID_SECURITY_JWT_ISSUER/KID/TTL` não lidos — ver [[SeedGrid/Extensions/security/Configuracao-Rust|Configuração Rust]] §9.
+- `is_effective_root` segue modelo de união (Java: override).
+- Self-enter: `default_role` é obrigatória com self-enter ligado (`from_env` falha sem ela); se a role não existe, a aprovação é recusada antes de criar o usuário, como no Java — ver [[SeedGrid/Extensions/security/Configuracao-Rust|Configuração Rust]] §2.7.
+
+## Enums
+
+Enums públicos do crate (`rust/seedgrid-rust-crate-security/src`). Equivalentes Java em [[SeedGrid/Extensions/security/Enums|Enums (Quarkus)]].
+
+| Enum | Arquivo | Usado em | Equivalente Java |
+|---|---|---|---|
+| `EntryRequestStatus` | `models/entry_request.rs` | coluna `entry_requests.status`; fluxo de self-enter | [[SeedGrid/Extensions/security/Enums#EntryRequestStatus\|EntryRequestStatus]] |
+| `EntryRequestOrigin` | `models/entry_request.rs` | coluna `entry_requests.origin` | [[SeedGrid/Extensions/security/Enums#EntryRequestOrigin\|EntryRequestOrigin]] |
+| `CredentialDelivery` | `services/users.rs` | `UserCreateOptions.delivery` (API de serviço para o host) | [[SeedGrid/Extensions/security/Enums#Delivery\|Delivery]] |
+| `SecurityError` | `error.rs` | erro de serviços/handlers; corpo RFC 7807 | exceções do Java (sem enum equivalente) |
+| `TemplateError` | `templates.rs` | retorno de `TemplateSecurityProvider` | `TemplateNotFoundException` / `TemplateCantLoadException` |
+
+### EntryRequestStatus
+
+Estado do pedido de self-enter. Coluna `status VARCHAR(30)` com `CHECK chk_entry_request_status` (`migrations/0201_create_entry_requests_table.sql`) que aceita exatamente os 5 valores abaixo.
+
+| Variante | Valor | Onde é tratado |
+|---|---|---|
+| `PendingEmail` | `PENDING_EMAIL` | estado inicial do pedido público e do convite (`services/selfenter.rs`); expira por `expires_at` |
+| `PendingApproval` | `PENDING_APPROVAL` | depois de confirmar o OTP de e-mail; só nesse estado a aprovação é aceita (senão erro `INVALID_STATUS`) |
+| `Approved` | `APPROVED` | a aprovação cria o usuário e grava `approved_at`/`approved_by` |
+| `Rejected` | `REJECTED` | a rejeição grava `rejected_at`/`rejected_by` |
+| `Expired` | `EXPIRED` | o job de limpeza marca pendentes vencidos; depois de `purge_after` o registro é purgado junto com APPROVED/REJECTED |
+
+- Serde: `rename_all = "SCREAMING_SNAKE_CASE"` (apenas `Serialize`). Conversões: `as_str()` e `parse(&str) -> Option<Self>` (sensível a caixa). A struct `EntryRequest` guarda `status` como `String` e as queries comparam literais SQL.
+- Java: mesmos 5 valores na mesma ordem. Igual (Confirmado).
+
+### EntryRequestOrigin
+
+| Variante | Valor | Onde é tratado |
+|---|---|---|
+| `Public` | `PUBLIC` | pedido do link público; default da coluna `origin` |
+| `Invite` | `INVITE` | convite criado por admin; as consultas de convites filtram `origin = 'INVITE'` |
+
+- Coluna `origin VARCHAR(20) NOT NULL DEFAULT 'PUBLIC'` (migration `0217`), sem CHECK. Serde `rename_all = "UPPERCASE"`; `as_str()` / `parse()`.
+- Java: `PUBLIC`, `INVITE`: idêntico.
+
+### CredentialDelivery
+
+Enum com dados, não serializável: `SecurityWelcomeEmail` (e-mail de boas-vindas do security), `None` (nada é enviado; exige senha informada) e `Callback { mailer: Arc<dyn ActivationMailer>, best_effort: bool }` (envio do host; `best_effort` faz a falha só logar). No Java, `Delivery` tem `SECURITY_WELCOME_EMAIL`, `NONE`, `CALLBACK`, e o mailer e o best-effort são campos separados do record `UserCreateOptions`. Mesmos 3 casos; muda só o formato.
+
+### SecurityError
+
+Cada variante tem status HTTP e `code` estável no corpo `application/problem+json` (`error.rs`).
+
+| Variante | HTTP | `code` |
+|---|---|---|
+| `InvalidCredentials` | 401 | `INVALID_CREDENTIALS` |
+| `Unauthorized` | 401 | `UNAUTHORIZED` |
+| `TokenValidation` | 401 | `TOKEN_VALIDATION` |
+| `Forbidden` | 403 | `FORBIDDEN` |
+| `NotFound` | 404 | o `code` informado |
+| `Conflict` | 409 | o `code` informado |
+| `Validation` | 400 | `VALIDATION_ERROR` (com `violations`) |
+| `BadRequest` | 400 | o `code` informado (ex.: `INVALID_USER_ADDITIONAL_ATTRIBUTES`) |
+| `TwoFactorRequired` | 202 | `TWO_FACTOR_REQUIRED` (com `session_token` e `primary_method`) |
+| `Database` | 500 | `DATABASE_ERROR` |
+| `Internal` | 500 | `INTERNAL_ERROR` |
+
+Convenção do crate: regras que o Java responde 422 viram 400.
+
+### TemplateError
+
+`NotFound(String)` e `CantLoad(String)`. O provider default só os usa internamente (cai para o template embutido); ficam expostos para providers do host.
+
+### Métodos de 2FA (sem enum)
+
+O Java tem `TwoFactorMethodType` (`EMAIL`, `WHATSAPP`, `TOTP`, `BACKUP_CODE`, com `fromCode` sem diferenciar caixa). O Rust **não tem enum**: o método é `String` em `users.two_factor_primary_method` e em `two_factor.allowed_methods` / `default_method`. Valores executáveis: `SUPPORTED_METHODS = ["TOTP","EMAIL","WHATSAPP"]` (`services/twofactor.rs`); os itens de `allowed_methods` são aparados e passados para maiúsculas, mas o que estiver fora dessa lista nunca é oferecido. `BACKUP_CODE` não é um método no Rust: o código de backup é um campo à parte (`backupCode`) verificado por `consume_backup_code`. Ver [[SeedGrid/Extensions/security/Enums#TwoFactorMethodType|TwoFactorMethodType]].
+
+### Internos
+
+| Enum | Arquivo |
+|---|---|
+| `UsersListResponse`, `RolesListResponse`, `EntryListResponse` (respostas lista simples ou página) | `routes.rs` |
+| `PlatformRolesTarget` | `services/users.rs` |