4.0.0

v4.0.0 (2026-04-29)

Fail-secure by default (upstream), agent-stats surface, version reporting (v4.0.0)

• Breaking (upstream) — SecurityConfig.fail_secure now defaults to True (inherited from guard-core >= 3.0.0). When any security check raises an unhandled exception, the request is now blocked with HTTP 500 instead of logging and falling through. Bugs in checks that previously slipped past as silent fail-open responses now surface immediately. Restore the old behavior on deployments that depend on it via SecurityConfig(fail_secure=False). Recommended migration: keep the new default, surface any check exceptions in your monitoring, and fix them — the previous default could mask serious bugs. The flaskapi-guard major bump tracks this upstream change so deployments see a clear signal.
• Added — FlaskAPIGuard.agent_stats read-only @property returning the agent's telemetry buffer state. Returns {"enabled": False} when no agent is wired; otherwise returns {"enabled": True, **agent_handler.get_stats()} exposing events_dropped, metrics_dropped, circuit_breaker_state, and other agent counters. No caching — fresh on each call. Access the property on the extension instance returned by FlaskAPIGuard(app, config=...) or via app.extensions["flaskapi_guard"]["guard"].agent_stats. Lets app teams build Flask health endpoints that surface agent-side drops and circuit-breaker trips without scraping the agent directly.
• Added — from flaskapi_guard import __version__ — package version is now exported via importlib.metadata.version("flaskapi_guard") with a "0.0.0+unknown" fallback if the package is not installed (development from source). Pairs with guard-core >= 3.0.0's SecurityConfig.agent_guard_version so application code can wire the flaskapi-guard version through to the agent for SaaS-side telemetry attribution: SecurityConfig(agent_guard_version=__version__).
• Fixed (latent) — FlaskAPIGuard.refresh_cloud_ip_ranges was calling cloud_handler.refresh(...) directly. When Redis was enabled, that method raises RuntimeError("Use refresh_async() when Redis is enabled") — the cloud-IP refresh check would surface as an exception inside the security pipeline. Under the old fail_secure=False default the exception was logged and the request fell through, so the bug stayed invisible. Under the new fail_secure=True default it would block every request with HTTP 500 in any deployment that combines enable_redis=True with block_cloud_providers. Switched to cloud_handler.refresh_async(...) which dispatches Redis-aware vs non-Redis paths internally (matches djangoapi-guard's v3.0.0 fix and tornadoapi-guard's existing dispatch). Same fix shape; pre-existing bug.
• Compatibility — FlaskAPIGuard.agent_stats is purely additive; no existing API was changed. __version__ was previously absent; reading it before this release returned None via missing-attribute fallback in some integrations.

What's Changed

• Fail secure default + agent version persistance by @rennf93 in #12

Full Changelog: 3.0.0...4.0.0