fix(downgrader): leave out 3.2 security requirement names that are not a component name

packages/downgrader/README.md

@@ -87,6 +87,7 @@ Schema Objects inside the document convert as in [Schema](#schema-downgradeschem
 | Example [`dataValue`][3.2-example-data-value] and [`serializedValue`][3.2-example-serialized-value]                                                                                                             | Removed. Without `value` or `externalValue`, `dataValue`, or else `serializedValue`, fills `value`.     |
 | OAuth [`deviceAuthorization`][3.2-oauth-flows-device-authorization] flow                                                                                                                                        | Removed.                                                                                                |
 | Security Scheme [`oauth2MetadataUrl`][3.2-security-scheme-oauth2-metadata-url] and [`deprecated`][3.2-security-scheme-deprecated]                                                                               | Removed.                                                                                                |
+| [Security requirement][3.2-security-requirement] names other than a component name, such as a URI reference to a scheme                                                                                         | Removed, which asks for less.                                                                           |
 
 [3.2-self]: https://spec.openapis.org/oas/v3.2.1.html#oas-self
 [3.2-json-schema-dialect]: https://spec.openapis.org/oas/v3.2.1.html#oas-json-schema-dialect
@@ -113,12 +114,14 @@ Schema Objects inside the document convert as in [Schema](#schema-downgradeschem
 [3.2-oauth-flows-device-authorization]: https://spec.openapis.org/oas/v3.2.1.html#oauth-flows-device-authorization
 [3.2-security-scheme-oauth2-metadata-url]: https://spec.openapis.org/oas/v3.2.1.html#security-scheme-oauth2-metadata-url
 [3.2-security-scheme-deprecated]: https://spec.openapis.org/oas/v3.2.1.html#security-scheme-deprecated
+[3.2-security-requirement]: https://spec.openapis.org/oas/v3.2.1.html#security-requirement-object
 
 #### Limitations
 
 - Other `$ref`s into a removed part, such as a schema `$ref` into `components.mediaTypes`, and Links or discriminator `mapping` values that point at a removed operation, are left as written and dangle.
 - A `content` `$ref` that does not resolve is removed, which can leave a parameter or header without the one entry it needs.
-- Security requirements that name a scheme by URI, and `$self`-relative references, pass through unchanged.
+- A security requirement that names its scheme by URI reference loses it, so 3.1 tools can read the operation as needing no credentials for it.
+- `$self`-relative references pass through unchanged.
 
 ### Schema (`downgradeSchemaV32ToV31`)
 

packages/downgrader/src/v3.2-to-v3.1.ts

@@ -19,6 +19,7 @@ import {
   list,
   map,
   resolve,
+  resolvePointer,
 } from './shared'
 
 const V32_DIALECT_PREFIX = 'https://spec.openapis.org/oas/3.2/dialect/'
@@ -125,6 +126,7 @@ const SECURITY_SCHEME_FIELDS = defineFields({
 
 const OPERATION_FIELDS = defineFields({
   callbacks: map(refOr(convertCallback)),
+  security: convertSecurity,
   parameters: list(convertParameterRef),
   requestBody: refOr(convertRequestBody),
   responses: map(refOr(convertResponse), isNotExtension),
@@ -159,11 +161,32 @@ const DOCUMENT_FIELDS = defineFields({
   jsonSchemaDialect: (item) =>
     typeof item === 'string' && item.startsWith(V32_DIALECT_PREFIX) ? V31_DIALECT : clone(item),
   paths: map(convertPathItem, isPath),
+  security: convertSecurity,
   servers: convertServers,
   tags: list(convertTag),
   webhooks: map(convertPathItem),
 })
 
+// 3.1 names a scheme in a security requirement only by its component name,
+// where 3.2 also takes a URI reference to one. Any other name is left out,
+// which asks for less.
+function convertSecurity(value: unknown, ctx: Context): unknown {
+  if (!Array.isArray(value)) {
+    return clone(value)
+  }
+  const schemes = resolvePointer('#/components/securitySchemes', ctx)
+  const isScheme = (name: string): boolean => isRecord(schemes) && Object.hasOwn(schemes, name)
+  return value.map((requirement) =>
+    isRecord(requirement)
+      ? Object.fromEntries(
+          Object.keys(requirement)
+            .filter((name) => requirement[name] !== undefined && isScheme(name))
+            .map((name) => [name, clone(requirement[name])]),
+        )
+      : clone(requirement),
+  )
+}
+
 /** Reference Objects are the same in 3.1, so they are copied as they are. */
 function refOr(convert: Convert): Convert {
   return (value, ctx) => (getRef(value) === undefined ? convert(value, ctx) : clone(value))

packages/downgrader/tests/v3.2-to-v3.1.test.ts

@@ -415,6 +415,39 @@ describe('downgradeSpecV32ToV31', () => {
     })
   })
 
+  it('leaves out security requirement names that are not a component name', () => {
+    const key = { type: 'apiKey', in: 'header', name: 'X-Key' } as const
+    const out = convert({
+      security: [{ '#/components/securitySchemes/key': [] }],
+      paths: {
+        '/a': {
+          get: {
+            security: [
+              { '#/components/securitySchemes/key': [], 'key': [] },
+              // A component name is read as one, whatever it looks like.
+              { '#/components/securitySchemes/other': ['read'] },
+              { 'https://example.com/openapi.json#/components/securitySchemes/key': [] },
+            ],
+          },
+        },
+      },
+      components: { securitySchemes: { 'key': key, '#/components/securitySchemes/other': key } },
+    })
+    expect(out.security).toEqual([{}])
+    expect(out.paths?.['/a']?.get?.security).toEqual([
+      { key: [] },
+      { '#/components/securitySchemes/other': ['read'] },
+      {},
+    ])
+    // Without any schemes, every name is left out, and malformed values stay.
+    const malformed = convert({
+      security: 'all',
+      paths: { '/a': { get: { security: [null, { key: [] }] } } },
+    } as any)
+    expect(malformed.security).toBe('all')
+    expect(malformed.paths?.['/a']?.get?.security).toEqual([null, {}])
+  })
+
   it('converts schemas everywhere in the document', () => {
     const schema: OpenAPIV3_2.SchemaObject = { type: 'string', xml: { nodeType: 'attribute' } }
     const out = convert({