Add SASL OAUTHBEARER support with application-supplied tokens

[proddata]

This adds support for PostgreSQL's SASL OAUTHBEARER authentication mechanism when the application supplies a bearer token directly or through a callback.

The implementation intentionally keeps OAuth provider interaction outside of pg. OAuth bearer token acquisition depends heavily on the IdP, grant type, scopes, refresh behavior, caching policy, and user interaction model. Instead of embedding that logic in the driver, this change gives applications a focused hook for supplying a valid token while pg handles the PostgreSQL SASL protocol exchange.

Changes

• Add an oauthBearerToken client option that accepts either:
  • a token string
  • a sync or async callback returning a token string
• Prefer OAUTHBEARER when the server advertises it and oauthBearerToken is configured.
• Implement the OAUTHBEARER initial response and server challenge response handling.
• Add a generic sendSASLResponseMessage protocol serializer while keeping sendSCRAMClientFinalMessage as an alias for SCRAM compatibility.
• Keep oauthBearerToken non-enumerable on client, connection parameters, and pool options so token values do not appear in common inspection/serialization output.
• Document the new option and clarify that applications are responsible for fetching and caching OAuth bearer tokens.
• Add unit coverage for OAUTHBEARER mechanism selection, token callbacks, error paths, and response packets.

Rationale

PostgreSQL 18 adds native OAuth authentication using the SASL OAUTHBEARER mechanism. Returning a bearer token from the existing password callback is not sufficient because the server expects OAUTHBEARER SASL messages, not a SCRAM exchange.

This change implements the PostgreSQL protocol support needed for callers that already have, or can fetch, a bearer token. Keeping token acquisition in user code keeps the driver small and avoids baking IdP-specific OAuth behavior into pg.

Scope

This does not implement a full OAuth authorization flow, device authorization grant, token discovery, or token refresh logic inside pg.

Applications can build those flows externally and provide the resulting token through oauthBearerToken.

This support applies to the pure JavaScript client. pg.native delegates authentication to libpq and does not currently use oauthBearerToken; native OAuth support would require libpq OAuth configuration or new node-libpq auth hook bindings.

Partially resolves #3687

I am not conviced that fully following libpq (oauth_issuer and oauth_client_id) is proper for a low level driver like node-pg. However open for suggestions.

co-authored with codex

[brianc]

This looks good to me. It would be nice if there was a way to configure a postgres instance w/ OAUTH authentication in CI so we could do an end-to-end integration test, but I realize configuring postgres in docker is somewhat non-trivial. Maybe ask an LLM to give that a shot? Otherwise this looks p straight forward and mergeable...ty!

[proddata]

This looks good to me. It would be nice if there was a way to configure a postgres instance w/ OAUTH authentication in CI so we could do an end-to-end integration test, but I realize configuring postgres in docker is somewhat non-trivial. Maybe ask an LLM to give that a shot? Otherwise this looks p straight forward and mergeable...ty!

I don't think there is a Postgres image with a bundled OAUTH validator module (yet). While Postgres does have some validators in the repo for tests https://github.com/postgres/postgres/tree/master/src/test/modules/oauth_validator, I think builidng Postgres for a test might be a bit much. So an approach would be to have some dummy validator and build it during testing and still use the same base Postgres docker image. However that likely means it should not be added to the CI, therefore added as separate workflow. Let me know what you think about it.