feat(respect): enhance OAS3 security scheme types and add getSecurityParameters utility function (#2077)

yarokon · DmitryAnansky · commit 9087fc19d506 · 2025-05-12T12:16:31.000+03:00
diff --git a/packages/core/src/rules/respect/no-x-security-scheme-name-without-openapi.ts b/packages/core/src/rules/respect/no-x-security-scheme-name-without-openapi.ts
@@ -18,7 +18,7 @@ export const NoXSecuritySchemeNameWithoutOpenAPI: Arazzo1Rule = () => {
         }
 
         for (const security of extendedSecurity) {
-          if (security?.schemeName) {
+          if ('schemeName' in security) {
             report({
               message:
                 'The `schemeName` can be only used in Step with OpenAPI operation, please use `scheme` instead.',
diff --git a/packages/core/src/typings/arazzo.ts b/packages/core/src/typings/arazzo.ts
@@ -1,4 +1,4 @@
-import type { Oas3SecurityScheme } from './openapi.js';
+import type { Oas3SecurityScheme, ApiKeyAuth, BasicAuth, BearerAuth } from './openapi.js';
 
 export interface InfoObject {
   title: string;
@@ -29,11 +29,42 @@ export interface Parameter {
   reference?: string;
 }
 
-export interface ExtendedSecurity {
-  schemeName?: string;
-  values: Record<string, string>;
-  schema?: Oas3SecurityScheme;
-}
+export type ExtendedSecurity =
+  | {
+      schemeName: string;
+      values: Record<string, string>;
+    }
+  | {
+      scheme: Oas3SecurityScheme;
+      values: Record<string, string>;
+    };
+
+export type ResolvedSecurity =
+  | {
+      scheme: ApiKeyAuth;
+      values: {
+        value: string;
+      };
+    }
+  | {
+      scheme: BasicAuth;
+      values: {
+        username: string;
+        password: string;
+      };
+    }
+  | {
+      scheme: BearerAuth;
+      values: {
+        token: string;
+      };
+    }
+  | {
+      scheme: Exclude<Oas3SecurityScheme, ApiKeyAuth | BasicAuth | BearerAuth>;
+      values: {
+        accessToken: string;
+      };
+    };
 
 export interface ExtendedOperation {
   url: string;
diff --git a/packages/core/src/typings/openapi.ts b/packages/core/src/typings/openapi.ts
@@ -291,37 +291,83 @@ export interface Oas3SecurityRequirement {
   [name: string]: string[];
 }
 
-export interface Oas3SecurityScheme {
-  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect' | 'mutualTLS';
+type SecuritySchemeBase = {
   description?: string;
-  name?: string;
-  in?: 'query' | 'header' | 'cookie';
-  scheme?: string;
+  [key: `x-${string}`]: unknown;
+};
+
+export type ApiKeyAuth = {
+  type: 'apiKey';
+  in: 'query' | 'header' | 'cookie';
+  name: string;
+} & SecuritySchemeBase;
+
+export type HttpAuth = {
+  type: 'http';
+  scheme: string;
+} & SecuritySchemeBase;
+
+export type BasicAuth = {
+  type: 'http';
+  scheme: 'basic';
+} & SecuritySchemeBase;
+
+export type BearerAuth = {
+  type: 'http';
+  scheme: 'bearer';
   bearerFormat?: string;
+} & SecuritySchemeBase;
+
+export type DigestAuth = {
+  type: 'http';
+  scheme: 'digest';
+} & SecuritySchemeBase;
+
+export type MutualTLSAuth = {
+  type: 'mutualTLS';
+} & SecuritySchemeBase;
+
+export type OAuth2Auth = {
+  type: 'oauth2';
   flows: {
     implicit?: {
-      refreshUrl?: string;
-      scopes: Record<string, string>;
       authorizationUrl: string;
+      scopes: Record<string, string>;
+      refreshUrl?: string;
     };
     password?: {
-      refreshUrl?: string;
-      scopes: Record<string, string>;
       tokenUrl: string;
+      scopes: Record<string, string>;
+      refreshUrl?: string;
     };
     clientCredentials?: {
-      refreshUrl?: string;
-      scopes: Record<string, string>;
       tokenUrl: string;
+      scopes: Record<string, string>;
+      refreshUrl?: string;
     };
     authorizationCode?: {
-      refreshUrl?: string;
-      scopes: Record<string, string>;
+      authorizationUrl: string;
       tokenUrl: string;
+      scopes: Record<string, string>;
+      refreshUrl?: string;
     };
   };
-  openIdConnectUrl?: string;
-}
+} & SecuritySchemeBase;
+
+export type OpenIDAuth = {
+  type: 'openIdConnect';
+  openIdConnectUrl: string;
+} & SecuritySchemeBase;
+
+export type Oas3SecurityScheme =
+  | ApiKeyAuth
+  | HttpAuth
+  | BasicAuth
+  | BearerAuth
+  | DigestAuth
+  | MutualTLSAuth
+  | OAuth2Auth
+  | OpenIDAuth;
 
 export interface Oas3Tag {
   name: string;
diff --git a/packages/core/src/visitors.ts b/packages/core/src/visitors.ts
@@ -27,6 +27,7 @@ import type {
   Oas3RequestBody,
   Oas3Tag,
   OasRef,
+  OAuth2Auth,
   Oas3SecurityScheme,
   Oas3SecurityRequirement,
   Oas3Encoding,
@@ -197,11 +198,12 @@ type Oas3FlatVisitor = {
   NamedSecuritySchemes?: VisitFunctionOrObject<Record<string, Oas3SecurityScheme>>;
   NamedLinks?: VisitFunctionOrObject<Record<string, Oas3Link>>;
   NamedCallbacks?: VisitFunctionOrObject<Record<string, Oas3Callback<Oas3Schema | Oas3_1Schema>>>;
-  ImplicitFlow?: VisitFunctionOrObject<Oas3SecurityScheme['flows']['implicit']>;
-  PasswordFlow?: VisitFunctionOrObject<Oas3SecurityScheme['flows']['password']>;
-  ClientCredentials?: VisitFunctionOrObject<Oas3SecurityScheme['flows']['clientCredentials']>;
-  AuthorizationCode?: VisitFunctionOrObject<Oas3SecurityScheme['flows']['authorizationCode']>;
-  OAuth2Flows?: VisitFunctionOrObject<Oas3SecurityScheme['flows']>;
+
+  ImplicitFlow?: VisitFunctionOrObject<NonNullable<OAuth2Auth['flows']['implicit']>>;
+  PasswordFlow?: VisitFunctionOrObject<NonNullable<OAuth2Auth['flows']['password']>>;
+  ClientCredentials?: VisitFunctionOrObject<NonNullable<OAuth2Auth['flows']['clientCredentials']>>;
+  AuthorizationCode?: VisitFunctionOrObject<NonNullable<OAuth2Auth['flows']['authorizationCode']>>;
+  OAuth2Flows?: VisitFunctionOrObject<OAuth2Auth['flows']>;
   SecurityScheme?: VisitFunctionOrObject<Oas3SecurityScheme>;
   SpecExtension?: VisitFunctionOrObject<unknown>;
 };
diff --git a/packages/respect-core/src/arazzo-schema.ts b/packages/respect-core/src/arazzo-schema.ts
@@ -114,7 +114,7 @@ export const extendedSecurity = {
     },
   },
   required: ['values'],
-  requiredOneOf: ['schemeName', 'schema'],
+  requiredOneOf: ['schemeName', 'scheme'],
 } as const;
 export const extendedSecurityList = {
   type: 'array',
diff --git a/packages/respect-core/src/modules/__tests__/config-parser/get-security-parameters.test.ts b/packages/respect-core/src/modules/__tests__/config-parser/get-security-parameters.test.ts
@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { getSecurityParameters } from '../../config-parser/get-security-parameters';
+
+describe('getSecurityParameters', () => {
+  it('should return security parameters for API Key Auth', () => {
+    const result = getSecurityParameters({
+      scheme: {
+        type: 'apiKey',
+        in: 'query',
+        name: 'api_key',
+      },
+      values: {
+        value: '12345678-ABCD-90EF-GHIJ-1234567890KL',
+      },
+    });
+
+    expect(result).toEqual({
+      in: 'query',
+      name: 'api_key',
+      value: '12345678-ABCD-90EF-GHIJ-1234567890KL',
+    });
+  });
+
+  it('should return security parameters for Basic Auth', () => {
+    const result = getSecurityParameters({
+      scheme: {
+        type: 'http',
+        scheme: 'basic',
+      },
+      values: {
+        username: 'username',
+        password: 'password',
+      },
+    });
+
+    expect(result).toEqual({
+      in: 'header',
+      name: 'Authorization',
+      value: `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`,
+    });
+  });
+
+  it('should return security parameters for Bearer Auth', () => {
+    const result = getSecurityParameters({
+      scheme: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+      },
+      values: {
+        token:
+          'eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.LlTGHPZRXbci-y349jXXN0byQniQQqwKGybzQCFIgY0',
+      },
+    });
+
+    expect(result).toEqual({
+      in: 'header',
+      name: 'Authorization',
+      value:
+        'Bearer eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.LlTGHPZRXbci-y349jXXN0byQniQQqwKGybzQCFIgY0',
+    });
+  });
+
+  it('should return security parameters for OpenID Auth', () => {
+    const result = getSecurityParameters({
+      scheme: {
+        type: 'openIdConnect',
+        openIdConnectUrl: 'https://example.com',
+      },
+      values: {
+        accessToken: 'openid-token',
+      },
+    });
+
+    expect(result).toEqual({
+      in: 'header',
+      name: 'Authorization',
+      value: 'Bearer openid-token',
+    });
+  });
+
+  it('should return security parameters for OAuth2 Auth', () => {
+    const result = getSecurityParameters({
+      scheme: {
+        type: 'oauth2',
+        flows: {
+          authorizationCode: {
+            authorizationUrl: 'https://example.com/authorize',
+            tokenUrl: 'https://example.com/token',
+            scopes: {
+              read: 'Read access',
+              write: 'Write access',
+            },
+          },
+        },
+      },
+      values: {
+        accessToken: 'oauth2-token',
+      },
+    });
+
+    expect(result).toEqual({
+      in: 'header',
+      name: 'Authorization',
+      value: 'Bearer oauth2-token',
+    });
+  });
+});
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/generate-inputs-arazzo-components.ts b/packages/respect-core/src/modules/arazzo-description-generator/generate-inputs-arazzo-components.ts
@@ -10,7 +10,7 @@ export function generateSecurityInputsArazzoComponents(
       continue;
     }
 
-    if (securityScheme?.scheme?.toLowerCase() === 'basic') {
+    if (securityScheme.type === 'http' && securityScheme.scheme?.toLowerCase() === 'basic') {
       inputs[name] = {
         type: 'object',
         properties: {
@@ -21,7 +21,10 @@ export function generateSecurityInputsArazzoComponents(
           },
         },
       };
-    } else if (securityScheme?.scheme?.toLowerCase() === 'bearer') {
+    } else if (
+      securityScheme.type === 'http' &&
+      securityScheme.scheme?.toLowerCase() === 'bearer'
+    ) {
       inputs[name] = {
         type: 'object',
         properties: {
diff --git a/packages/respect-core/src/modules/arazzo-description-generator/generate-workflow-security-parameters.ts b/packages/respect-core/src/modules/arazzo-description-generator/generate-workflow-security-parameters.ts
@@ -32,17 +32,17 @@ export function generateWorkflowSecurityParameters(
           value: `$inputs.${securityName}`,
           in: securityScheme?.in || 'header',
         });
-      } else if (securityScheme?.scheme === 'bearer') {
+      } else if (securityScheme?.type === 'http' && securityScheme?.scheme === 'bearer') {
         parameters.push({
           name: 'Authorization',
           value: `Bearer {$inputs.${securityName}}`,
-          in: securityScheme?.in || 'header',
+          in: 'header',
         });
-      } else if (securityScheme?.scheme === 'basic') {
+      } else if (securityScheme?.type === 'http' && securityScheme?.scheme === 'basic') {
         parameters.push({
           name: 'Authorization',
           value: `Basic {$inputs.${securityName}}`,
-          in: securityScheme?.in || 'header',
+          in: 'header',
         });
       }
     }
diff --git a/packages/respect-core/src/modules/config-parser/get-security-parameters.ts b/packages/respect-core/src/modules/config-parser/get-security-parameters.ts

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ export const NoXSecuritySchemeNameWithoutOpenAPI: Arazzo1Rule = () => {`
`18`	`18`	`}`
`19`	`19`
`20`	`20`	`for (const security of extendedSecurity) {`
`21`		`- if (security?.schemeName) {`
	`21`	`+ if ('schemeName' in security) {`
`22`	`22`	`report({`
`23`	`23`	`message:`
`24`	`24`	'The `schemeName` can be only used in Step with OpenAPI operation, please use `scheme` instead.',