Java Integration

// Gradle (Kotlin DSL)
dependencies {
    implementation("sa.gatekeeper:gkcaptcha-java:0.1.0")
}

<!-- Maven -->
<dependency>
    <groupId>sa.gatekeeper</groupId>
    <artifactId>gkcaptcha-java</artifactId>
    <version>0.1.0</version>
</dependency>

// Spring Boot starter — Gradle (Kotlin DSL)
dependencies {
    implementation("sa.gatekeeper:gkcaptcha-spring-boot-starter:0.1.0")
}

import sa.gatekeeper.*;

// Build the client once and reuse it (thread-safe)
GkCaptchaConfig config = GkCaptchaConfig.builder()
    .secretKey(System.getenv("GKCAPTCHA_SECRET_KEY"))
    .siteKey(System.getenv("GKCAPTCHA_SITE_KEY"))
    .build();

GkCaptchaClient client = new GkCaptchaClient(config);

// Synchronous verification
VerifyTokenResponse result = client.verifyToken(captchaToken);
if (!result.success()) {
    throw new ForbiddenException("CAPTCHA verification failed: " + result.error());
}

// Asynchronous verification
client.verifyTokenAsync(captchaToken)
    .thenAccept(r -> {
        if (!r.success()) throw new CompletionException(new ForbiddenException("CAPTCHA failed"));
    });

# application.yml
gkcaptcha:
  secret-key: ${GKCAPTCHA_SECRET_KEY}
  site-key: ${GKCAPTCHA_SITE_KEY}
  api-url: https://gkcaptcha.gatekeeper.sa  # optional, default
  timeout: 5s                     # optional, default
  max-retries: 1                  # optional, default
  fail-closed: false              # optional, default (fail-open)

import org.springframework.web.bind.annotation.*;
import sa.gatekeeper.spring.RequireCaptcha;

@RestController
public class AuthController {

    @PostMapping("/login")
    @RequireCaptcha
    public ResponseEntity<?> login(@RequestBody LoginRequest req) {
        // CAPTCHA has already been verified by the aspect
        return ResponseEntity.ok().build();
    }
}

# application.yml — route-level filter
gkcaptcha:
  secret-key: ${GKCAPTCHA_SECRET_KEY}
  site-key: ${GKCAPTCHA_SITE_KEY}
  filter:
    enabled: true
    url-patterns:
      - /api/submit
      - /login
      - /register

VerifyTokenResponse result = client.verifyToken(token);
if (result.failOpen()) {
    log.warn("gkCAPTCHA API unreachable - request allowed through (fail-open)");
}

// To enforce fail-closed:
GkCaptchaConfig config = GkCaptchaConfig.builder()
    .secretKey("...")
    .siteKey("...")
    .failClosed(true)  // throws GkCaptchaException("NETWORK_ERROR") on API failure
    .build();