Security and extensions

These types describe security requirements and vendor metadata. They do not authenticate requests or enforce access policies. For runtime CoSec integration see CoSec configuration.

Security objects

Type	Contract
SecurityScheme	Required type: apiKey/http/mutualTLS (3.1)/oauth2/openIdConnect; optional description, name, in (query/header/cookie), scheme, bearerFormat, flows, openIdConnectUrl
OAuthFlow	Required scopes map (scope → description); optional authorizationUrl, tokenUrl, refreshUrl
OAuthFlows	Optional implicit, password, clientCredentials, authorizationCode flow objects
SecurityRequirement	Scheme-name keys mapped to string[] scope names; not Extensible, since every key is a scheme name

The declaration does not make fields conditionally required for each scheme or flow. For example, TypeScript does not reject an apiKey scheme missing name/in. Arrays and scope maps are passed through as data; there are no defaults, return values, network effects, or cleanup methods.

Extensions

Extensible permits only the template-key family x-${string}, with any values. Most document objects extend it; Reference and SecurityRequirement do not. CommonExtensions separately names x-internal, x-deprecated (message/since/removedIn/replacement), x-tags, x-examples, x-order, and x-group. It is not automatically merged into every Extensible object and does not implement generator behavior. Generator-specific Wow extensions are documented in discovery.

Complete example

import type { OpenAPI, CommonExtensions } from '@ahoo-wang/fetcher-openapi';
const extensions: CommonExtensions = { 'x-internal': true, 'x-order': 1 };
const document: OpenAPI = {
  openapi: '3.0.3',
  info: { title: 'Secure API', version: '1' },
  paths: {},
  components: {
    securitySchemes: {
      bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
    },
  },
  security: [{ bearer: [] }],
  ...extensions,
};
console.log(document.security);

OAuthFlow

packages/openapi/src/security.ts:29

export interface OAuthFlow extends Extensible {
  authorizationUrl?: string;
  tokenUrl?: string;
  refreshUrl?: string;
  scopes: Record<string, string>;
}

OAuthFlows

packages/openapi/src/security.ts:44

export interface OAuthFlows extends Extensible {
  implicit?: OAuthFlow;
  password?: OAuthFlow;
  clientCredentials?: OAuthFlow;
  authorizationCode?: OAuthFlow;
}

SecurityScheme

packages/openapi/src/security.ts:63

export interface SecurityScheme extends Extensible {
  type: 'apiKey' | 'http' | 'mutualTLS' | 'oauth2' | 'openIdConnect';
  description?: string;
  name?: string;
  in?: Exclude<ParameterLocation, 'path'>;
  scheme?: string;
  bearerFormat?: string;
  flows?: OAuthFlows;
  openIdConnectUrl?: string;
}

SecurityRequirement

packages/openapi/src/security.ts:80

export interface SecurityRequirement {
  [name: string]: string[];
}

Extensible

packages/openapi/src/extensions.ts:22

export interface Extensible {
  [extension: `x-${string}`]: any;
}

CommonExtensions

packages/openapi/src/extensions.ts:33

export interface CommonExtensions {
  'x-internal'?: boolean;

  'x-deprecated'?: {
    message?: string;
    since?: string;
    removedIn?: string;
    replacement?: string;
  };

  'x-tags'?: string[];

  'x-examples'?: any[];

  'x-order'?: number;

  'x-group'?: string;
}