Configuration Reference

Full configuration shape

{
  "CWaptcha": {
    "SecretKey":         "",        // required — set via user-secrets or env var
    "NonceTtlSeconds":   300,       // optional, default 300 (5 min)
    "HoneypotFieldName": "cw_hp_email",  // optional
    "ProtectedPaths":    [],        // optional — routes intercepted by middleware
    "RequireHttps":      false      // optional, enable true in production
  }
}

Option	Type	Default	Description
`SecretKey`	string	required	Master HMAC key. Set via user-secrets or environment variable. Throws OptionsValidationException at startup if empty.
`NonceTtlSeconds`	int	300	How long (in seconds) a nonce is valid. After expiry the token is rejected with "expired".
`HoneypotFieldName`	string	"cw_hp_email"	Name of the hidden honeypot field injected by the JS. Must match the data-honeypot attribute on the script tag.
`ProtectedPaths`	string[]	[]	Routes the middleware intercepts. Matched with OrdinalIgnoreCase prefix matching. Only the POST verb is validated.
`RequireHttps`	bool	false	When true, rejects non-HTTPS requests. Checks IsHttps or X-Forwarded-Proto: https for reverse-proxy setups.

Setting the SecretKey

⚠️ Never commit the SecretKey to source control. Use the appropriate method for your environment.

DEVELOPMENT — dotnet user-secrets

dotnet user-secrets set "CWaptcha:SecretKey" "your-secret-here"

PRODUCTION — environment variable (IIS / Windows)

# System environment variable (double underscore = section separator)
CWaptcha__SecretKey=your-secret-here

PRODUCTION — web.config environment variable

<environmentVariables>
    <environmentVariable name="CWaptcha__SecretKey" value="your-secret-here" />
</environmentVariables>

Multi-node: distributed nonce store

ℹ️ The default MemoryNonceStore is in-process only. For load-balanced deployments, use a distributed cache.

// Program.cs
builder.Services.AddStackExchangeRedisCache(o =>
    o.Configuration = builder.Configuration["Redis:ConnectionString"]);

builder.Services.AddCWaptcha(builder.Configuration.GetSection("CWaptcha"))
                .UseDistributedNonceStore();

Dos & Don'ts → Integration wizard →