feat(core): add asyncapi-operation-security-defined lint rule

.changeset/stupid-dryers-add.md

@@ -0,0 +1,5 @@
+---
+"@redocly/openapi-core": minor
+---
+
+Added `asyncapi-operation-security-defined` rule for AsyncAPI 2.x that reports when a security scheme referenced from an operation or server `security` array is not defined in `components.securitySchemes`.

docs/@v1/rules/ruleset-templates.md

@@ -438,6 +438,7 @@ rules:
   info-contact: off
   info-license-strict: warn
   operation-operationId: warn
+  asyncapi-operation-security-defined: error
   tag-description: warn
   tags-alphabetical: off
   channels-kebab-case: off

docs/@v2/guides/lint-asyncapi.md

@@ -50,6 +50,7 @@ The currently supported rules are:
 
 - `info-contact`: the `Info` section must contain a valid `Contact` field.
 - `operation-operationId`: every operation must have a valid `operationId`.
+- `security-defined`: every scheme referenced from an operation or server `security` array must be defined in `components.securitySchemes` (AsyncAPI 2.x and 3.0).
 - `channels-kebab-case`: channel address should be `kebab-case` (lowercase with hyphens).
 - `no-channel-trailing-slash`: channel names must not have trailing slashes in their address.
 - `tag-description`: all tags require a description.

docs/@v2/rules/async/security-defined.md

@@ -0,0 +1,120 @@
+# security-defined
+
+Verifies that every security scheme referenced from an operation or server `security` array is defined in `components.securitySchemes`.
+
+| AsyncAPI | Compatibility |
+| -------- | ------------- |
+| 2.6      | ✅            |
+| 3.0      | ✅            |
+
+## API design principles
+
+In AsyncAPI 2.x, `security` entries on operations and servers are bare security scheme names that must match a key under `components.securitySchemes`.
+A typo or rename leaves the reference dangling, and the document remains structurally valid — the mismatch is only visible to clients at runtime.
+
+In AsyncAPI 3.0, `security` entries are `SecurityScheme` objects, typically expressed as `$ref`s into `components.securitySchemes`. The rule reports when a security `$ref` does not point into `components.securitySchemes` or when it points at a name that is not defined there.
+
+This rule catches those name mismatches at lint time.
+
+## Configuration
+
+| Option   | Type   | Description                                                                                |
+| -------- | ------ | ------------------------------------------------------------------------------------------ |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). |
+
+An example configuration:
+
+```yaml
+rules:
+  security-defined: error
+```
+
+## Examples
+
+Given this configuration:
+
+```yaml
+rules:
+  security-defined: error
+```
+
+Example of an **incorrect** security definition due to a mismatch between the referenced name and `components.securitySchemes`:
+
+```yaml
+asyncapi: '2.6.0'
+channels:
+  user/signedup:
+    subscribe:
+      security:
+        - OAuth: [] # no matching scheme in components.securitySchemes
+      message:
+        messageId: UserSignedUp
+components:
+  securitySchemes:
+    JWT:
+      type: http
+      scheme: bearer
+```
+
+Example of a **correct** AsyncAPI 2.x security definition:
+
+```yaml
+asyncapi: '2.6.0'
+channels:
+  user/signedup:
+    subscribe:
+      security:
+        - JWT: []
+      message:
+        messageId: UserSignedUp
+components:
+  securitySchemes:
+    JWT:
+      type: http
+      scheme: bearer
+```
+
+Example of an **incorrect** AsyncAPI 3.0 security definition where the `$ref` points at an undefined scheme:
+
+```yaml
+asyncapi: '3.0.0'
+operations:
+  sendMessage:
+    action: send
+    channel:
+      $ref: '#/channels/userSignedUp'
+    security:
+      - $ref: '#/components/securitySchemes/OAuth'
+components:
+  securitySchemes:
+    JWT:
+      type: http
+      scheme: bearer
+```
+
+Example of a **correct** AsyncAPI 3.0 security definition:
+
+```yaml
+asyncapi: '3.0.0'
+operations:
+  sendMessage:
+    action: send
+    channel:
+      $ref: '#/channels/userSignedUp'
+    security:
+      - $ref: '#/components/securitySchemes/JWT'
+components:
+  securitySchemes:
+    JWT:
+      type: http
+      scheme: bearer
+```
+
+## Related rules
+
+- [security-defined](../oas/security-defined.md) — equivalent rule for OpenAPI.
+
+## Resources
+
+- [AsyncAPI 2.x rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async2/security-defined.ts)
+- [AsyncAPI 3.0 rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async3/security-defined.ts)

docs/@v2/rules/built-in-rules.md

@@ -122,6 +122,7 @@ Other rules, such as the `struct` and `info.*`, also apply to AsyncAPI.
 
 - [channels-kebab-case](./async/channels-kebab-case.md): Channels must be in `kebab-case` format
 - [no-channel-trailing-slash](./async/no-channel-trailing-slash.md): No trailing slashes on channels
+- [security-defined](./async/security-defined.md): Security scheme names referenced from operations or servers must be defined in `components.securitySchemes`
 
 ## Arazzo rules
 

docs/@v2/rules/ruleset-templates.md

@@ -151,6 +151,7 @@ rules:
   no-required-schema-properties-undefined: warn
   no-schema-type-mismatch: warn
   operation-operationId: warn
+  security-defined: warn
   struct: error
   tag-description: warn
 ```
@@ -163,6 +164,7 @@ rules:
   no-required-schema-properties-undefined: warn
   no-schema-type-mismatch: warn
   operation-operationId: warn
+  security-defined: warn
   struct: error
   tag-description: warn
 ```
@@ -357,6 +359,7 @@ rules:
   no-required-schema-properties-undefined: warn
   no-schema-type-mismatch: error
   operation-operationId: warn
+  security-defined: error
   struct: error
   tag-description: warn
 ```
@@ -372,6 +375,7 @@ rules:
   no-required-schema-properties-undefined: warn
   no-schema-type-mismatch: error
   operation-operationId: warn
+  security-defined: error
   struct: error
   tag-description: warn
 ```

docs/@v2/v2.sidebars.yaml

@@ -153,6 +153,7 @@
             - separator: AsyncAPI
             - page: rules/async/channels-kebab-case.md
             - page: rules/async/no-channel-trailing-slash.md
+            - page: rules/async/security-defined.md
             - separator: Open-RPC
             - page: rules/openrpc/spec-no-duplicated-method-params.md
             - page: rules/openrpc/spec-no-required-params-after-optional.md

packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap

@@ -41,6 +41,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
     "no-required-schema-properties-undefined": "warn",
     "no-schema-type-mismatch": "error",
     "operation-operationId": "warn",
+    "security-defined": "error",
     "tag-description": "warn",
     "tags-alphabetical": "off",
   },
@@ -57,6 +58,7 @@ exports[`resolveConfig > should ignore minimal from the root and read local file
     "no-required-schema-properties-undefined": "warn",
     "no-schema-type-mismatch": "error",
     "operation-operationId": "warn",
+    "security-defined": "error",
     "tag-description": "warn",
     "tags-alphabetical": "off",
   },
@@ -428,6 +430,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
     "no-required-schema-properties-undefined": "warn",
     "no-schema-type-mismatch": "error",
     "operation-operationId": "warn",
+    "security-defined": "error",
     "tag-description": "warn",
     "tags-alphabetical": "off",
   },
@@ -444,6 +447,7 @@ exports[`resolveConfig > should resolve extends with local file config which con
     "no-required-schema-properties-undefined": "warn",
     "no-schema-type-mismatch": "error",
     "operation-operationId": "warn",
+    "security-defined": "error",
     "tag-description": "warn",
     "tags-alphabetical": "off",
   },

packages/core/src/config/__tests__/load.test.ts

@@ -163,6 +163,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -179,6 +180,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -487,6 +489,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "error",
               "operation-operationId": "warn",
+              "security-defined": "error",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -503,6 +506,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "error",
               "operation-operationId": "warn",
+              "security-defined": "error",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -816,6 +820,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -832,6 +837,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -1229,6 +1235,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -1245,6 +1252,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -1553,6 +1561,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "error",
               "operation-operationId": "warn",
+              "security-defined": "error",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -1569,6 +1578,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "error",
               "operation-operationId": "warn",
+              "security-defined": "error",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -1882,6 +1892,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },
@@ -1898,6 +1909,7 @@ describe('loadConfig', () => {
               "no-required-schema-properties-undefined": "warn",
               "no-schema-type-mismatch": "warn",
               "operation-operationId": "warn",
+              "security-defined": "warn",
               "tag-description": "warn",
               "tags-alphabetical": "off",
             },

packages/core/src/config/all.ts

@@ -256,6 +256,7 @@ const all: RawGovernanceConfig<'built-in'> = {
     'info-license-strict': 'error',
     'no-channel-trailing-slash': 'error',
     'operation-operationId': 'error',
+    'security-defined': 'error',
     'tag-description': 'error',
     'tags-alphabetical': 'error',
     'no-duplicated-tag-names': 'error',
@@ -270,6 +271,7 @@ const all: RawGovernanceConfig<'built-in'> = {
     'info-license-strict': 'error',
     'no-channel-trailing-slash': 'error',
     'operation-operationId': 'error',
+    'security-defined': 'error',
     'tag-description': 'error',
     'tags-alphabetical': 'error',
     'no-duplicated-tag-names': 'error',

packages/core/src/config/minimal.ts

@@ -240,6 +240,7 @@ const minimal: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'warn',
     'no-schema-type-mismatch': 'warn',
     'operation-operationId': 'warn',
+    'security-defined': 'warn',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
   },
@@ -254,6 +255,7 @@ const minimal: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'warn',
     'no-schema-type-mismatch': 'warn',
     'operation-operationId': 'warn',
+    'security-defined': 'warn',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
   },

packages/core/src/config/recommended-strict.ts

@@ -240,6 +240,7 @@ const recommendedStrict: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'error',
     'no-schema-type-mismatch': 'error',
     'operation-operationId': 'error',
+    'security-defined': 'error',
     'tag-description': 'error',
     'tags-alphabetical': 'off',
   },
@@ -254,6 +255,7 @@ const recommendedStrict: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'error',
     'no-schema-type-mismatch': 'error',
     'operation-operationId': 'error',
+    'security-defined': 'error',
     'tag-description': 'error',
     'tags-alphabetical': 'off',
   },

packages/core/src/config/recommended.ts

@@ -240,6 +240,7 @@ const recommended: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'warn',
     'no-schema-type-mismatch': 'error',
     'operation-operationId': 'warn',
+    'security-defined': 'error',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
   },
@@ -254,6 +255,7 @@ const recommended: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'warn',
     'no-schema-type-mismatch': 'error',
     'operation-operationId': 'warn',
+    'security-defined': 'error',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
   },

packages/core/src/config/spec.ts

@@ -240,6 +240,7 @@ const spec: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'off',
     'no-schema-type-mismatch': 'off',
     'operation-operationId': 'off',
+    'security-defined': 'off',
     'tag-description': 'off',
     'tags-alphabetical': 'off',
   },
@@ -254,6 +255,7 @@ const spec: RawGovernanceConfig<'built-in'> = {
     'no-required-schema-properties-undefined': 'off',
     'no-schema-type-mismatch': 'off',
     'operation-operationId': 'off',
+    'security-defined': 'off',
     'tag-description': 'off',
     'tags-alphabetical': 'off',
   },