GkCaptcha.AspNetCore 0.1.0

gkCAPTCHA .NET SDK

Official .NET client for gkCAPTCHA — an AI-resistant CAPTCHA built for PDPL compliance.

Packages

Requirements

• .NET 8.0 or later

Quick Start — Standalone .NET

using GkCaptcha;

var client = new GkCaptchaClient(new GkCaptchaOptions
{
    SecretKey = "your_secret_key",   // or set GKCAPTCHA_SECRET_KEY env var
    SiteKey   = "your_site_key",     // or set GKCAPTCHA_SITE_KEY env var
});

var result = await client.VerifyTokenAsync(token);

if (result.FailOpen)
{
    // API was unreachable — fail-open: request allowed through (safe default)
    Console.WriteLine("Fail-open: allowing request");
}
else if (result.Success)
{
    Console.WriteLine($"Human verified (score: {result.Score})");
}
else
{
    Console.WriteLine($"Bot detected: {result.Error} ({result.ReasonCode})");
}

Fail-Open Behavior

By default, if the gkCAPTCHA API is unreachable after 1 retry, the client returns VerifyTokenResponse { Success = true, FailOpen = true } — your application continues rather than blocking legitimate users during an outage.

To fail closed (reject on API error):

var client = new GkCaptchaClient(new GkCaptchaOptions
{
    SecretKey  = "...",
    SiteKey    = "...",
    FailClosed = true,  // throw GkCaptchaException on network error
});

ASP.NET Core Quick Start

1. Register in Program.cs

using GkCaptcha.AspNetCore;

builder.Services.AddGkCaptcha(opts =>
{
    opts.SecretKey = builder.Configuration["GkCaptcha:SecretKey"];
    opts.SiteKey   = builder.Configuration["GkCaptcha:SiteKey"];
});

2. appsettings.json

{
  "GkCaptcha": {
    "SecretKey": "your_secret_key",
    "SiteKey":   "your_site_key"
  }
}

Middleware

Protect entire path prefixes. All requests to those paths require a valid CAPTCHA token.

app.UseGkCaptcha(opts =>
{
    opts.Paths.Add("/login");
    opts.Paths.Add("/register");
});

When no paths are configured, all requests are protected.

[RequireCaptcha] Attribute

Apply to MVC controllers or actions:

using GkCaptcha.AspNetCore;

[HttpPost]
[RequireCaptcha]
public IActionResult Login([FromForm] LoginModel model)
{
    // CAPTCHA already verified — proceed with login
    return Ok();
}

Returns HTTP 400 if the token is missing, HTTP 403 if verification fails.

Minimal API — .RequireGkCaptcha()

app.MapPost("/api/contact", (ContactRequest req) => Results.Ok())
   .RequireGkCaptcha();

Razor Tag Helper

Register in _ViewImports.cshtml:

@addTagHelper *, GkCaptcha.AspNetCore

Use in Razor views:

<form method="post">
    <gk-captcha site-key="@Model.SiteKey" theme="dark" />
    <button type="submit">Submit</button>
</form>

Renders:

<gk-captcha sitekey="pk_live_..." theme="dark"></gk-captcha>
<script src="https://cdn.gatekeeper.sa/gk-captcha.js" async defer></script>

Attributes: site-key (required), theme (light/dark, default light), widget-url (override CDN URL).

Token Sources

The SDK reads the CAPTCHA token from (in order):

1. Form field: gk-captcha-token (only for application/x-www-form-urlencoded or multipart/form-data requests)
2. HTTP header: X-Gk-Captcha-Token

Your frontend widget automatically submits the token. For API clients, pass the token in the header.

Configuration Reference

Testing

Inject IGkCaptchaClient in your tests without any mocking library:

private sealed class MockCaptcha(bool success) : IGkCaptchaClient
{
    public Task<VerifyTokenResponse> VerifyTokenAsync(
        string token, VerifyOptions? opts = null, CancellationToken ct = default)
        => Task.FromResult(new VerifyTokenResponse { Success = success });
}

// Register in test DI:
services.AddSingleton<IGkCaptchaClient>(new MockCaptcha(success: true));

License

MIT — see LICENSE.