[improve][broker] PIP-488: Pluggable authentication audit-event hook

[PavelZeger]

Motivation

Pulsar exposes only aggregate AuthenticationMetrics (success/failure counters by provider and error code). There is no per-login structured record - nothing that says "principal P authenticated via method M from address A at time T," or "a failed attempt with reason R came from A."

Security teams need that audit trail: SIEM ingestion, anomaly detection (failure spikes from one source, a principal appearing from an unexpected location), incident forensics, and compliance. Counters cannot answer "who, from where, when, and why did this fail." Today operators must scrape provider-internal logs (unstructured, mostly absent) or fork the broker.

BrokerInterceptor is the closest existing extension point, but it does not cover this: it fires only on successful binary connections (onConnectionCreated), runs inline on the event-loop thread (can block auth), is not authentication-scoped, and cannot be reached from pulsar-broker-common where HTTP/admin auth happens. This proposal closes the gap.

Modifications

Adds the design document pip/pip-488.md. It proposes a pluggable authentication audit-event hook that emits a structured, secret-free AuthenticationEvent on login success, failure, and refresh, on both the binary and HTTP/HTTPS paths, delivered through a bounded background queue so a slow or throwing listener can never stall or fail authentication.

The proposal presents two delivery options side by side for the community to choose on the DISCUSS thread:

• Option A: add a default onAuthenticationEvent(...) method to the existing BrokerInterceptor and reuse its loading/lifecycle.
• Option B: a dedicated AuthenticationEventListener SPI in pulsar-broker-common.

This PR contains only the proposal document - no production code or configuration changes.

Verifying this change

• Make sure that the change passes the CI checks.

This change is a trivial rework / documentation-only change (a PIP design document) without any test coverage.

Does this pull request potentially affect one of the following parts:

• Dependencies (add or upgrade a dependency)
• The public API
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment