Fix OAuth2 Security Scheme Codegen

A generated client can expose an OAuth option in its types yet fail to attach the access token to a request. The opposite failure is also possible: it may send a token to a route that does not need one, or send it to the wrong host. Review the complete path from OpenAPI security requirement to client request. The OpenAPI 3.1.1 specification defines OAuth2 schemes, flows, scopes, and operation security requirements.

Spec-to-client trace

Choose one protected operation and one public operation. Record the effective security requirement for each, including operation overrides and alternatives.

Do not assume the generator can obtain or refresh a token. The client may only accept a token supplied by its caller. State that boundary in documentation. Never put a client secret in generated browser code or logs.

Use a minimal OAuth2 fixture

This valid OpenAPI shape names a flow, a scope, and the operation that requires it. The URLs are inert examples, not a service to contact.

openapi: 3.1.1
info:
  title: Fixture API
  version: 1.0.0
paths:
  /records:
    get:
      security:
        - tenantOAuth: ['records:read']
      responses:
        '200':
          description: Synthetic records
components:
  securitySchemes:
    tenantOAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.test/authorize
          tokenUrl: https://auth.example.test/token
          scopes:
            'records:read': Read records

Run fixture tests

Use a local mock server and a synthetic token. Generate the client from a small spec with a protected route, a public route, and an operation that overrides the global requirement. Verify the Authorization header on the protected call. Then remove the token. For this generated client, choose and test a fail-fast contract: it makes no protected network request and gives a clear error. That is a recommended client behavior for this fixture, not a universal SDK requirement. Send a separate raw request without a token to the mock server and require server-side denial with no records or side effects. Test that the public call does not leak the token. Compare generated code and runtime behavior after each generator change.

The OWASP OAuth2 Cheat Sheet gives token-handling context. This trace is the artifact. A generated type or compile success is not proof that auth works. If a scheme cannot be represented safely, mark the operation unsupported rather than silently dropping its security requirement.