Security Requirements Validator

Build a validator that analyzes OpenAPI documents to determine which security schemes are required for specific operations.

Problem Description

Create a TypeScript module that examines OpenAPI 3.0 documents and extracts security requirements information. The validator should identify:

1. Document-level security requirements that apply to all operations by default
2. Operation-specific security requirements that override document-level settings
3. Whether multiple security schemes are required together (AND logic)
4. Whether any of several security schemes can be used (OR logic)

The validator should help developers understand the authentication requirements for each API operation.

Requirements

Your implementation should provide a function that:

• Accepts an OpenAPI 3.0 document and a path + HTTP method
• Returns information about the security requirements for that specific operation
• Handles both document-level and operation-level security configurations
• Correctly interprets AND/OR logic in security requirements

Input

• An OpenAPI 3.0 document object
• A path string (e.g., "/users")
• An HTTP method (e.g., "get")

Output

Return an object with:

• hasRequirements: boolean indicating if any security is required
• requirements: array of requirement groups (each group represents an OR option)
• Each requirement group contains scheme names and their required scopes

Security Logic Rules

1. OR Logic: Multiple items in the security array mean any one can satisfy the requirement
2. AND Logic: Multiple key-value pairs in a single security object mean all schemes must be satisfied
3. Operation Override: If an operation specifies security, it completely replaces document-level security
4. Empty Array: An empty security array means the operation requires no authentication

Test Cases

• Given a document with document-level security requiring "oauth2" with ["read"] scope, when requesting an operation without operation-level security, it returns the document-level requirements @test

• Given a document where an operation defines security requiring "api_key", when requesting that operation, it returns the operation-level requirements and ignores document-level security @test

• Given an operation with security array containing two objects (OR logic), when analyzed, it returns two requirement groups showing either scheme satisfies the requirement @test

• Given an operation with a security object containing two schemes (AND logic), when analyzed, it returns one requirement group containing both schemes @test

Implementation

@generates

API

/**
 * Analyzes security requirements for a specific operation in an OpenAPI document
 */
export function analyzeSecurityRequirements(
  document: OpenAPIV3.Document,
  path: string,
  method: string
): SecurityAnalysis;

/**
 * Result of security requirements analysis
 */
export interface SecurityAnalysis {
  hasRequirements: boolean;
  requirements: SecurityRequirementGroup[];
}

/**
 * A group of security schemes that must all be satisfied (AND logic)
 * Multiple groups in the requirements array represent OR logic
 */
export interface SecurityRequirementGroup {
  schemes: Array<{
    name: string;
    scopes: string[];
  }>;
}

Dependencies { .dependencies }

openapi-types { .dependency }

Provides TypeScript type definitions for OpenAPI 3.0 documents including security types.

@satisfied-by