feat(oas/extensions): oauth configuration options

[kanadgupta]

🚥 Partially resolves RM-10641, RM-10720, RM-10730

🧰 Changes

Adds an OAS extension so folks can configure OAuth flows handling. These options are inspired by Swagger UI's configuration options: https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/

In my testing, I've found these ones are necessary for a v1 release of OAuth flows support, but I'm down to add more options further down the line.

Also, a super tiny type-fix with our CODE_SAMPLES extension.

🧬 QA & Testing

Tests appear to pass, but I would love targeted feedback on the following million dollar question: do you feel good about the naming conventions and defaults? This will be impossible to change in the future so I'd love to make sure we develop a consensus first!

I opted to stick with the Swagger naming conventions (despite by own personal reservations), with a couple small exceptions:

• The name diverges slightly for useBasicAuthenticationWithAuthorizationCodeGrant (known as useBasicAuthenticationWithAccessCodeGrant in Swagger UI) — accessCode was a Swagger 2.0 convention and it's authorizationCode in OpenAPI 3.x, hence the update
• I also diverged from Swagger UI in that the default value for useBasicAuthenticationWithAuthorizationCodeGrant is true. This is because it's the more secure/recommended approach per the following RFCs¹²:
  • https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
  • https://datatracker.ietf.org/doc/html/rfc6819#section-5.4.1

Footnotes

1. First discovered through this: https://security.stackexchange.com/a/143560 ↩

2. I'm also cool with a name that ensures folks understand the risks, (e.g., useInsecureAuthorizationCodeGrantDefinition with a default of false, etc.) ↩

[kanadgupta]

smol type fix

[kanadgupta]

all of the changes i made in this file are related to that smol type fix