feat(sdk): expose securitySchemes key on Auth when schemes collide

[matthewjamesadam]

Summary

Fixes #3817.

When an OpenAPI spec defines two or more components.securitySchemes entries whose generated Auth shape would otherwise be identical (e.g. two http/bearer schemes used by different operations), the SDK now emits the components.securitySchemes key as Auth.key so the runtime auth callback can disambiguate which token to return. Schemes with unique signatures are unchanged — preserving the "no redundant info" property we discussed in the issue thread (#3817 (comment)).

How collision detection works

A new helper in @hey-api/shared (packages/shared/src/openApi/shared/utils/security.ts) computes a canonical signature for each scheme (e.g. http:bearer, apiKey:header:X-Token) that mirrors what the SDK plugin emits onto Auth. computeAmbiguousSecurityKeys buckets every components.securitySchemes entry by that signature and returns the set of keys whose bucket has size ≥ 2. The parser threads that set through parsePathOperation / parseWebhookOperation for all three OpenAPI versions (2.0, 3.0, 3.1) and attaches key to the IR security object only for ambiguous schemes. The SDK plugin (auth.ts) is a pass-through.

Generated SDK before/after

For the new test fixture specs/3.1.x/security-http-bearer-duplicate.json (two http/bearer schemes bearerAuth + refreshAuth plus a unique http/basic basicAuth):

// /data — `bearerAuth` collides with `refreshAuth`
security: [{ key: 'bearerAuth', scheme: 'bearer', type: 'http' }]

// /refresh — `refreshAuth` collides with `bearerAuth`
security: [{ key: 'refreshAuth', scheme: 'bearer', type: 'http' }]

// /unique — `basicAuth` has a unique signature → no `key`
security: [{ scheme: 'basic', type: 'http' }]

All existing security-* snapshots have unchanged sdk.gen.ts output; only the Auth interface JSDoc in auth.gen.ts changed.

Test plan

• pnpm exec vitest run --project @hey-api/shared --project @test/openapi-ts — 818 passed (added scenarios for 3.0.x + 3.1.x in openapi-ts-tests, plus unit tests for the new helper and the 3.1.x parser)
• pnpm ty @hey-api/shared --filter @hey-api/openapi-ts --filter @test/openapi-ts — clean
• pnpm lint — 0 errors

🤖 Generated with Claude Code

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@matthewjamesadam is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 23d908a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hey-api/shared	Patch
@hey-api/openapi-ts	Patch
@hey-api/openapi-python	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pullfrog]

Important

securitySchemeSignature produces false collisions for oauth2 schemes with only authorizationCode flow, causing unnecessary key fields on otherwise unique schemes.

Reviewed changes — collision detection for security schemes that would emit identical Auth shapes, exposing the scheme key only when disambiguation is needed.

• Add computeAmbiguousSecurityKeys utility — canonical signature-based collision detection in @hey-api/shared
• Thread ambiguousSecurityKeys through all three OpenAPI version parsers — attaches key to IR security objects only for colliding schemes
• Forward key in SDK auth plugin — passes the scheme name through to generated Auth objects
• Update Auth interface JSDoc — documents the new key field in client-core bundle
• Add test fixtures and snapshots — security-http-bearer-duplicate specs for 3.0.x and 3.1.x

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 ｜ 𝕏}

[codecov]

Codecov Report

❌ Patch coverage is 84.21053% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.40%. Comparing base (1d76793) to head (23d908a).

Files with missing lines	Patch %	Lines
...ckages/shared/src/openApi/shared/utils/security.ts	90.32%	3 Missing ⚠️
...openapi-ts/src/plugins/@hey-api/sdk/shared/auth.ts	0.00%	0 Missing and 1 partial ⚠️
packages/shared/src/openApi/2.0.x/parser/index.ts	0.00%	1 Missing ⚠️
...kages/shared/src/openApi/2.0.x/parser/operation.ts	83.33%	1 Missing ⚠️
...kages/shared/src/openApi/3.0.x/parser/operation.ts	83.33%	1 Missing ⚠️
packages/shared/src/openApi/3.1.x/parser/index.ts	50.00%	1 Missing ⚠️
...kages/shared/src/openApi/3.1.x/parser/operation.ts	87.50%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3935      +/-   ##
==========================================
+ Coverage   37.36%   37.40%   +0.04%     
==========================================
  Files         653      654       +1     
  Lines       22430    22456      +26     
  Branches     6520     6531      +11     
==========================================
+ Hits         8381     8400      +19     
- Misses      11391    11397       +6     
- Partials     2658     2659       +1     

Flag	Coverage Δ
unittests	37.40% <84.21%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3935

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3935

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3935

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3935

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3935

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3935

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3935

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3935

commit: 23d908a

[mrlubos]

@matthewjamesadam this one also looks good, thank you!