LeadSoft.Adapter.Google.ReCaptcha 10.1.0

LeadSoft® Google reCAPTCHA Integration Adapter

LeadSoft.Adapter.Google.ReCaptcha

Adapter .NET para integrar com os serviços do Google reCAPTCHA — tanto a versão padrão v3 quanto o reCAPTCHA Enterprise.
Fornece uma camada leve, testável e orientada a interfaces para validação de tokens e criação de avaliações de risco, encapsulando chamadas HTTP, mapeamento de modelos e tratamento de erros de forma consistente para aplicações .NET 10.

Este pacote é um tributo independente e não é afiliado oficialmente ao Google.
Somos gratos pela disponibilização das APIs públicas do Google reCAPTCHA e do reCAPTCHA Enterprise. Ao utilizar este pacote, você concorda automaticamente com os Termos de Serviço do Google.

Nuget.Org: LeadSoft.Adapter.Google.ReCaptcha

GitHub Repo: leadsoft-adapter-google

Principais características

• Compatível com .NET 10.0.
• Suporte ao Google reCAPTCHA v3 (siteverify) e ao reCAPTCHA Enterprise (assessments).
• Chamadas assíncronas com async/await.
• Fácil integração com injeção de dependência (IServiceCollection).
• Interfaces IReCAPTCHA e IReCAPTCHAEnterprise para facilitar testes e mocking.
• Suporte a registro como Scoped ou Singleton.
• Tratamento centralizado de erros e respostas HTTP.
• Preparado para extensão com políticas de resiliência (ex.: Polly).
• Open Source (MIT License).

Métodos disponíveis

reCAPTCHA v3 — IReCAPTCHA

• Task<DTOSiteVerifyResponse> PostSiteVerifyAsync(DTOSiteVerifyRequest aDtoRequest)
  • Valida o token de resposta do usuário junto à API do Google reCAPTCHA v3.
  • Retorna o resultado da verificação com indicador de sucesso e possíveis códigos de erro.

reCAPTCHA Enterprise — IReCAPTCHAEnterprise

• Task<DTOAssessmentResp> CreateAssessmentsAsync(DTOAssessmentReq aDtoRequest, string apiKey)
  • Cria uma avaliação (Assessment) da probabilidade de um evento ser legítimo.
  • Retorna propriedades do token, validade e plataforma de origem (web, Android ou iOS).
  • Lança InvalidOperationException quando a API retorna um status HTTP de erro.

Instalação

Pelo CLI do .NET:

dotnet add package LeadSoft.Adapter.Google.ReCaptcha

Ou via NuGet Package Manager no Visual Studio (pesquise por LeadSoft.Adapter.Google.ReCaptcha).

Uso básico (exemplo)

Abaixo um exemplo genérico de como registrar e usar o adapter em uma aplicação ASP.NET Core / Console com DI.

// Program.cs (exemplo)
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using LeadSoft.Adapter.Google.ReCaptcha;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// reCAPTCHA v3
builder.Services.AddReCAPTCHAApi();        // scoped (padrão)
// builder.Services.AddReCAPTCHAApi(true); // singleton

// reCAPTCHA Enterprise (requer o ID do projeto no Google Cloud)
builder.Services.AddReCAPTCHAEnterpriseApi("meu-projeto-google-cloud");
// builder.Services.AddReCAPTCHAEnterpriseApi("meu-projeto-google-cloud", useSingleton: true);

WebApplication app = builder.Build();
app.Run();

Exemplo de chamada via injeção de dependência — reCAPTCHA v3:

// Em um Controller, Service ou Minimal API endpoint:
public class ValidacaoService(IReCAPTCHA recaptcha)
{
    public async Task<bool> ValidarTokenAsync(string secret, string token, string ip = "")
    {
        DTOSiteVerifyResponse resultado = await recaptcha.PostSiteVerifyAsync(
            new DTOSiteVerifyRequest(secret, token, ip));

        return resultado.Success;
    }
}

Exemplo de chamada via injeção de dependência — reCAPTCHA Enterprise:

// Em um Controller, Service ou Minimal API endpoint:
public class AvaliacaoService(IReCAPTCHAEnterprise recaptchaEnterprise)
{
    public async Task<bool> AvaliarEventoAsync(string token, string siteKey, string apiKey)
    {
        DTOAssessmentResp avaliacao = await recaptchaEnterprise.CreateAssessmentsAsync(
            new DTOAssessmentReq(token, siteKey), apiKey);

        return avaliacao.TokenProperties.Valid;
    }
}

DTOs de requisição

DTOSiteVerifyRequest — reCAPTCHA v3

DTOAssessmentReq — reCAPTCHA Enterprise

DTOAssessmentEventReq — reCAPTCHA Enterprise

DTOs de retorno

DTOSiteVerifyResponse — reCAPTCHA v3

Códigos de erro possíveis:

DTOAssessmentResp — reCAPTCHA Enterprise

DTOAssessmentTokenPropertiesResp — reCAPTCHA Enterprise

Configuração recomendada

• Use IServiceCollection com AddReCAPTCHAApi() ou AddReCAPTCHAEnterpriseApi() — evita problemas com ciclo de vida do HttpClient.
• Configure Timeout e cabeçalhos necessários conforme os limites das APIs do Google.
• Adicione políticas de resiliência com Polly (Retry, Circuit Breaker) para chamadas de rede.
• Propague CancellationToken em todas as chamadas assíncronas.
• Armazene chaves secretas e API Keys em variáveis de ambiente ou em cofre seguro (ex.: Azure Key Vault, AWS Secrets Manager) — nunca em código-fonte.

Boas práticas de integração

• Valide o token no servidor imediatamente após o envio do formulário — nunca confie apenas na validação client-side.
• Para o reCAPTCHA v3, defina um limiar de pontuação (score) adequado ao risco da operação (ex.: >= 0.5 para login, >= 0.7 para transações).
• Para o reCAPTCHA Enterprise, inspecione TokenProperties.Valid e TokenProperties.Action para garantir que o token corresponde à ação esperada.
• Não exponha diretamente os DTOs HTTP ao seu domínio — mapeie para modelos de domínio quando necessário.
• Capture e logue erros com ILogger<T> para diagnóstico: inclua status code e corpo quando aplicável.

Gerador de Token para Testes

O repositório inclui o arquivo LeadSoft.Google.Tests/GoogleReCAPTCHA.html — uma página HTML standalone que pode ser aberta diretamente no navegador para gerar tokens de resposta do reCAPTCHA v3 sem necessidade de servidor.

Como usar:

1. Abra o arquivo GoogleReCAPTCHA.html no navegador (duplo clique ou Ctrl+O).
2. Informe a Site Key pública do seu projeto reCAPTCHA.
3. Clique em Gerar Token — o token aparece no campo de saída.
4. Copie o token e use-o como valor de Response no DTOSiteVerifyRequest, combinando com sua Secret Key para testar o método PostSiteVerifyAsync.

O token gerado é válido por aproximadamente 2 minutos. Gere um novo token para cada teste.

Testes

• Injete um HttpMessageHandler falso no HttpClient para simular respostas da API do Google sem realizar chamadas reais.
• As interfaces IReCAPTCHA e IReCAPTCHAEnterprise permitem criar mocks facilmente com bibliotecas como Moq ou NSubstitute.
• Cubra cenários: token válido, token inválido, token expirado, token duplicado, erros de rede e respostas HTTP de erro.
• Use fixtures com exemplos de payloads JSON conhecidos para manter os testes determinísticos.

Versionamento e Compatibilidade

• Destinado a .NET 10.0. Verifique a compatibilidade do pacote com seu projeto.
• Siga versionamento semântico: breaking changes → major, novas features → minor, correções → patch.

Documentação de referência

Licença

Consulte o arquivo de licença no repositório para detalhes sobre uso e redistribuição.

LeadSoft.Adapter.Google.ReCaptcha — adapter simples e testável para integração com o Google reCAPTCHA v3 e reCAPTCHA Enterprise em aplicações .NET 10.

Development

Desenvolvido pelo time da LeadSoft® Soluções Web.

• Lucas Resende Tavares
• Frederico Ferreira Bitencourt
• Pedro Foresti Leão

Nossa empresa

LeadSoft Soluções Web Ltda
CNPJ 38.043.762/0001-48

Como nos encontrar:

• Nosso Site
• GitHub
• LinkedIn
• Behance
• YouTube
• Instagram
• Facebook

INFORMAÇÕES DE CONTATO Se você tiver alguma dúvida sobre estes Termos ou Serviços, entre em contato conosco em

developers@leadsoft.inf.br.