Commit Message:
oauth2: add cookie expiration margin

Additional Description:
Adds cookie_expiration_margin to the OAuth2 HTTP filter. When configured, the filter subtracts this margin from the lifetime of OAuth2 auth-related cookies whose expiration is derived from token/session expiry, including the bearer token, ID token, refresh token, OAuth expiry, and HMAC cookies.

This lets Envoy proactively refresh or re-authenticate before forwarding a request with a token that is close to expiration, matching the motivation in #45749.

The default is unchanged when cookie_expiration_margin is unset or zero.

This PR was prepared with assistance from OpenAI Codex. I reviewed and understand the submitted code and tests, and take responsibility for the change.

Risk Level:
Low. The new field is optional and the default behavior is unchanged.

Testing:
Added OAuth2 filter unit coverage for:

• configured cookie expiration margin subtraction
• margin equal to token lifetime, clamping affected cookie Max-Age values to 0 rather than underflowing

Also ran:

• git diff --check
• scoped Envoy format check: PASS
• npx -y @bazel/bazelisk test //test/extensions/filters/http/oauth2:filter_test --test_filter=OAuth2Test.OAuthAccessTokenSucessWithCookieExpirationMargin:OAuth2Test.OAuthAccessTokenSucessWithCookieExpirationMarginEqualToTokenLifetime --config=macos --macos_minimum_os=10.15 --jobs=4 --test_output=errors: PASS

Docs Changes:
Added inline API documentation for cookie_expiration_margin and updated the OAuth2 filter documentation with a short description and example configuration.

Release Notes:
Added changelog fragment under changelogs/current/new_features.

Platform Specific Features:
N/A

[Optional Runtime guard:]
N/A

[Optional Fixes #Issue]
Fixes #45749

[Optional Fixes commit #PR or SHA]
N/A

[Optional Deprecated:]
N/A

[Optional API Considerations:]
Adds a new optional field to the existing v3 OAuth2 filter config. The default is unset/0, preserving existing behavior.

Request variables

Key	Value
ref	f2a50bc
sha	3b1e877
pr	45810
base-sha	467ee8f
actor	@ftaboadac
message	oauth2: add cookie expiration margin...
started	1782500742.677459
target-branch	main
trusted	false

Container image/s (as used in this CI run)

Envoy version (as used in this CI run)