zopia 0.3.0

package/src/conversions/openapi-to-api-docs.ts

@@ -0,0 +1,203 @@
+import { ZopiaError } from '../errors';
+import { normalizeOpenApiDocument, type OpenApiDocument } from './openapi';
+import { resolveOpenApiLocalRef } from './openapi-ref';
+
+/** Canonical km-api/OpenAPI operation method order. */
+export const OPENAPI_METHODS = ['get', 'post', 'put', 'delete', 'head', 'options', 'patch', 'trace'] as const;
+
+/** Supported lowercase OpenAPI operation method. */
+export type OpenApiMethod = (typeof OPENAPI_METHODS)[number];
+
+/** Collected source operation with merged parameters and a stable identifier. */
+export interface OpenApiOperation {
+  /** Original OpenAPI path template. */
+  path: string;
+  /** Lowercase HTTP method. */
+  method: OpenApiMethod;
+  /** Original operation object. */
+  operation: Record<string, any>;
+  /** Explicit or deterministically derived operation identifier. */
+  operationId: string;
+  /** Path-level and operation-level parameters after override merging. */
+  parameters: any[];
+}
+
+function pascalPath(path: string): string {
+  return path.split('/').filter(Boolean).map((segment) => segment.replace(/[{}]/g, '').split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join('')).join('') || 'Root';
+}
+/**
+ * Derive a stable operation identifier from a path and method.
+ *
+ * @param path OpenAPI path template beginning with `/`.
+ * @param method Supported lowercase HTTP method.
+ * @returns Method-prefixed camel-case operation identifier.
+ * @throws {@link ZopiaError} when the path or method is invalid.
+ */
+export function deriveOperationId(path: string, method: OpenApiMethod): string {
+  if (typeof path !== 'string' || !path.startsWith('/')) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid API path: ${String(path)}`, { at: 'path' });
+  if (!OPENAPI_METHODS.includes(method)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Unsupported HTTP method: ${String(method)}`, { at: 'method' });
+  return `${method}${pascalPath(path)}`;
+}
+
+function parameterIdentity(parameter: Record<string, any>, document: OpenApiDocument): string {
+  let current = parameter; const seen = new Set<string>();
+  while ('$ref' in current) {
+    if (typeof current.$ref !== 'string' || !current.$ref) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', 'Invalid parameter $ref');
+    if (seen.has(current.$ref)) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Circular parameter $ref: ${current.$ref}`);
+    seen.add(current.$ref);
+    const target = resolveOpenApiLocalRef(document, current.$ref);
+    if (!target || typeof target !== 'object' || Array.isArray(target)) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Invalid parameter $ref target: ${current.$ref}`);
+    current = { ...(target as Record<string, any>), ...Object.fromEntries(Object.entries(current).filter(([key]) => key !== '$ref')) };
+  }
+  return `${String(current.in)}:${String(current.name)}`;
+}
+
+/**
+ * Collect path operations in the canonical km-api method order.
+ *
+ * @param input Valid Swagger/OpenAPI object or JSON text.
+ * @returns Operations with merged parameters and unique stable identifiers.
+ * @throws {@link ZopiaError} when the source, references, or operations are invalid.
+ */
+export function collectOpenApiOperations(input: OpenApiDocument | string): OpenApiOperation[] {
+  const { document } = normalizeOpenApiDocument(input); const operations: OpenApiOperation[] = []; const ids = new Set<string>(); const owners = new Map<string, OpenApiOperation>();
+  for (const path of Object.keys(document.paths)) {
+    if (path.startsWith('x-')) continue;
+    const item = document.paths[path];
+    let resolvedItem: any = item;
+    const seenPathRefs = new Set<string>();
+    while ('$ref' in resolvedItem) {
+      if (typeof resolvedItem.$ref !== 'string' || !resolvedItem.$ref) throw new ZopiaError('ZOPIA_SPEC_PATH_REF', `Invalid path-item $ref: ${path}`);
+      if (seenPathRefs.has(resolvedItem.$ref)) throw new ZopiaError('ZOPIA_SPEC_PATH_REF', `Circular path-item $ref: ${resolvedItem.$ref}`);
+      seenPathRefs.add(resolvedItem.$ref);
+      const target = resolveOpenApiLocalRef(document, resolvedItem.$ref);
+      if (!target || typeof target !== 'object' || Array.isArray(target)) throw new ZopiaError('ZOPIA_SPEC_PATH_REF', `Invalid path-item $ref: ${resolvedItem.$ref}`);
+      resolvedItem = { ...target, ...Object.fromEntries(Object.entries(resolvedItem).filter(([key]) => key !== '$ref')) };
+    }
+    for (const method of OPENAPI_METHODS) {
+      const operation = resolvedItem[method];
+      if (operation === undefined) continue;
+      if (!operation || typeof operation !== 'object' || Array.isArray(operation)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI operation: ${method.toUpperCase()} ${path}`);
+      if (operation.operationId !== undefined && (typeof operation.operationId !== 'string' || !operation.operationId.trim())) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid operationId: ${method.toUpperCase()} ${path}`);
+      const pathParameters = resolvedItem.parameters === undefined ? [] : resolvedItem.parameters;
+      if (!Array.isArray(pathParameters) || !pathParameters.every((parameter: any) => parameter && typeof parameter === 'object' && !Array.isArray(parameter))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid path parameters: ${path}`);
+      const operationParameters = operation.parameters === undefined ? [] : operation.parameters;
+      if (!Array.isArray(operationParameters) || !operationParameters.every((parameter: any) => parameter && typeof parameter === 'object' && !Array.isArray(parameter))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid operation parameters: ${method.toUpperCase()} ${path}`);
+      const identities = (parameters: any[], label: string): string[] => {
+        const keys = parameters.map((parameter) => parameterIdentity(parameter, document));
+        const seen = new Set<string>();
+        for (const key of keys) {
+          if (seen.has(key)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Duplicate ${label} parameter: ${key}`);
+          seen.add(key);
+        }
+        return keys;
+      };
+      const pathIdentities = identities(pathParameters, 'path-level');
+      const operationIdentities = identities(operationParameters, 'operation-level');
+      const mergedParameters = [...pathParameters]; const mergedIdentities = [...pathIdentities];
+      for (let parameterIndex = 0; parameterIndex < operationParameters.length; parameterIndex += 1) {
+        const parameter = operationParameters[parameterIndex]; const identity = operationIdentities[parameterIndex];
+        const index = mergedIdentities.indexOf(identity);
+        if (index >= 0) mergedParameters[index] = parameter;
+        else { mergedParameters.push(parameter); mergedIdentities.push(identity); }
+      }
+      let operationId: string;
+      if (operation.operationId !== undefined) {
+        operationId = operation.operationId;
+        const previous = owners.get(operationId);
+        if (previous) {
+          if (previous.operation.operationId !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Duplicate operationId: ${operationId}`);
+          let replacement = previous.operationId; let suffix = 1;
+          while (ids.has(replacement)) replacement = `${operationId}${++suffix}`;
+          ids.delete(previous.operationId); owners.delete(previous.operationId);
+          previous.operationId = replacement; ids.add(replacement); owners.set(replacement, previous);
+        }
+      } else {
+        const base = deriveOperationId(path, method);
+        operationId = base; let suffix = 1;
+        while (ids.has(operationId)) operationId = `${base}${++suffix}`;
+      }
+      const collected = { path, method, operation, operationId, parameters: mergedParameters };
+      ids.add(operationId); owners.set(operationId, collected); operations.push(collected);
+    }
+  }
+  return operations;
+}
+
+/**
+ * Collect every `webhooks` operation (OpenAPI 3.1) using the same operation rules as path operations.
+ *
+ * Webhook names are arbitrary identifiers rather than URL path templates, so no path-parameter
+ * template validation applies. `x-` names are preserved through the manifest overlays instead.
+ *
+ * @param document Normalized OpenAPI document.
+ * @returns Deterministically ordered webhook operations keyed by their webhook name.
+ * @throws {@link ZopiaError} when a webhook item, webhook-item `$ref` chain, or webhook operation is invalid.
+ */
+export function collectOpenApiWebhookOperations(document: OpenApiDocument): OpenApiOperation[] {
+  const operations: OpenApiOperation[] = []; const ids = new Set<string>(); const owners = new Map<string, OpenApiOperation>();
+  const webhooks = (document as { webhooks?: unknown }).webhooks;
+  if (webhooks === undefined) return operations;
+  if (!webhooks || typeof webhooks !== 'object' || Array.isArray(webhooks)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid OpenAPI webhooks', { at: '#/webhooks' });
+  for (const name of Object.keys(webhooks as Record<string, unknown>)) {
+    if (name.startsWith('x-')) continue;
+    let resolvedItem: any = (webhooks as Record<string, any>)[name];
+    if (!resolvedItem || typeof resolvedItem !== 'object' || Array.isArray(resolvedItem)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI webhook item: ${name}`);
+    const seenRefs = new Set<string>();
+    while ('$ref' in resolvedItem) {
+      if (typeof resolvedItem.$ref !== 'string' || !resolvedItem.$ref) throw new ZopiaError('ZOPIA_SPEC_PATH_REF', `Invalid webhook-item $ref: ${name}`);
+      if (seenRefs.has(resolvedItem.$ref)) throw new ZopiaError('ZOPIA_SPEC_PATH_REF', `Circular webhook-item $ref: ${resolvedItem.$ref}`);
+      seenRefs.add(resolvedItem.$ref);
+      const target = resolveOpenApiLocalRef(document, resolvedItem.$ref);
+      if (!target || typeof target !== 'object' || Array.isArray(target)) throw new ZopiaError('ZOPIA_SPEC_PATH_REF', `Invalid webhook-item $ref: ${resolvedItem.$ref}`);
+      resolvedItem = { ...target, ...Object.fromEntries(Object.entries(resolvedItem as Record<string, unknown>).filter(([key]) => key !== '$ref')) };
+    }
+    for (const method of OPENAPI_METHODS) {
+      const operation = resolvedItem[method];
+      if (operation === undefined) continue;
+      if (!operation || typeof operation !== 'object' || Array.isArray(operation)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI webhook operation: ${method.toUpperCase()} ${name}`);
+      if (operation.operationId !== undefined && (typeof operation.operationId !== 'string' || !operation.operationId.trim())) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid operationId: ${method.toUpperCase()} ${name}`);
+      const pathParameters = resolvedItem.parameters === undefined ? [] : resolvedItem.parameters;
+      if (!Array.isArray(pathParameters) || !pathParameters.every((parameter: any) => parameter && typeof parameter === 'object' && !Array.isArray(parameter))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid webhook-item parameters: ${name}`);
+      const operationParameters = operation.parameters === undefined ? [] : operation.parameters;
+      if (!Array.isArray(operationParameters) || !operationParameters.every((parameter: any) => parameter && typeof parameter === 'object' && !Array.isArray(parameter))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid webhook operation parameters: ${method.toUpperCase()} ${name}`);
+      const identities = (parameters: any[], label: string): string[] => {
+        const keys = parameters.map((parameter) => parameterIdentity(parameter, document));
+        const seen = new Set<string>();
+        for (const key of keys) {
+          if (seen.has(key)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Duplicate ${label} parameter: ${key}`);
+          seen.add(key);
+        }
+        return keys;
+      };
+      const pathIdentities = identities(pathParameters, 'webhook-item');
+      const operationIdentities = identities(operationParameters, 'operation-level');
+      const mergedParameters = [...pathParameters]; const mergedIdentities = [...pathIdentities];
+      for (let parameterIndex = 0; parameterIndex < operationParameters.length; parameterIndex += 1) {
+        const parameter = operationParameters[parameterIndex]; const identity = operationIdentities[parameterIndex];
+        const index = mergedIdentities.indexOf(identity);
+        if (index >= 0) mergedParameters[index] = parameter;
+        else { mergedParameters.push(parameter); mergedIdentities.push(identity); }
+      }
+      let operationId: string;
+      if (operation.operationId !== undefined) {
+        operationId = operation.operationId;
+        const previous = owners.get(operationId);
+        if (previous) {
+          if (previous.operation.operationId !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Duplicate operationId: ${operationId}`);
+          let replacement = previous.operationId; let suffix = 1;
+          while (ids.has(replacement)) replacement = `${operationId}${++suffix}`;
+          ids.delete(previous.operationId); owners.delete(previous.operationId);
+          previous.operationId = replacement; ids.add(replacement); owners.set(replacement, previous);
+        }
+      } else {
+        const base = `${method}${pascalPath(name)}`;
+        operationId = base; let suffix = 1;
+        while (ids.has(operationId)) operationId = `${base}${++suffix}`;
+      }
+      const collected = { path: name, method, operation, operationId, parameters: mergedParameters };
+      ids.add(operationId); owners.set(operationId, collected); operations.push(collected);
+    }
+  }
+  return operations;
+}

package/src/conversions/openapi.ts

@@ -0,0 +1,80 @@
+import { asZopiaError, ZopiaError } from '../errors';
+
+/** Mutable JSON-like Swagger/OpenAPI document accepted by normalization helpers. */
+export type OpenApiDocument = Record<string, any>;
+
+/** Supported normalized source dialect family. */
+export type OpenApiVersion = '2.0' | '3.0' | '3.1';
+
+/** Validated source envelope and its normalized dialect metadata. */
+export interface NormalizedOpenApiDocument {
+  /** Validated source document. */
+  document: OpenApiDocument;
+  /** Detected Swagger/OpenAPI dialect family. */
+  version: OpenApiVersion;
+  /** Source `info.title`, when available after validation. */
+  title?: string;
+  /** Source `info.version`, when available after validation. */
+  versionString?: string;
+}
+
+const pointerToken = (value: string): string => value.replace(/~/g, '~0').replace(/\//g, '~1');
+const PATH_ITEM_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+
+/**
+ * Parse and validate the supported OpenAPI/Swagger document envelope.
+ *
+ * @param input Swagger/OpenAPI object or JSON text.
+ * @returns Validated document with detected dialect and info metadata.
+ * @throws {@link ZopiaError} when parsing or envelope validation fails.
+ */
+export function normalizeOpenApiDocument(input: OpenApiDocument | string): NormalizedOpenApiDocument {
+  let document: OpenApiDocument;
+  try { document = (typeof input === 'string' ? JSON.parse(input) : input) as OpenApiDocument; }
+  catch (error) { throw asZopiaError(error, 'ZOPIA_SPEC_INVALID_JSON', 'Invalid OpenAPI document', { at: '#', hint: 'fix the JSON syntax' }); }
+  if (!document || typeof document !== 'object' || Array.isArray(document)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid OpenAPI document: expected an object', { at: '#' });
+  const hasSwaggerVersion = Object.prototype.hasOwnProperty.call(document, 'swagger');
+  const hasOpenApiVersion = Object.prototype.hasOwnProperty.call(document, 'openapi');
+  if (hasSwaggerVersion && hasOpenApiVersion) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid OpenAPI document: swagger and openapi version fields are mutually exclusive', { at: '#', hint: 'keep exactly one dialect version field' });
+  let version: OpenApiVersion;
+  if (document.swagger === '2.0') version = '2.0';
+  else if (typeof document.openapi === 'string' && /^3\.0(?:\.\d+)?$/.test(document.openapi)) version = '3.0';
+  else if (typeof document.openapi === 'string' && /^3\.1(?:\.\d+)?$/.test(document.openapi)) version = '3.1';
+  else throw new ZopiaError('ZOPIA_SPEC_UNSUPPORTED_VERSION', 'Unsupported OpenAPI document version; expected Swagger 2.0 or OpenAPI 3.0/3.1', { at: '#', hint: 'use Swagger 2.0, OpenAPI 3.0, or OpenAPI 3.1' });
+  const allowedRootFields = new Set(version === '2.0'
+    ? ['swagger', 'info', 'host', 'basePath', 'schemes', 'consumes', 'produces', 'paths', 'definitions', 'parameters', 'responses', 'securityDefinitions', 'security', 'tags', 'externalDocs']
+    : ['openapi', 'info', 'servers', 'paths', 'components', 'security', 'tags', 'externalDocs', ...(version === '3.1' ? ['jsonSchemaDialect', 'webhooks'] : [])]);
+  const unsupportedRootField = Object.keys(document).find((key) => !allowedRootFields.has(key) && !key.startsWith('x-'));
+  if (unsupportedRootField) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI document: unsupported root field: ${unsupportedRootField}`, { at: `#/${pointerToken(unsupportedRootField)}`, hint: 'use a field supported by the selected dialect or an x- extension' });
+  if (version === '2.0') for (const field of ['consumes', 'produces'] as const) {
+    const value = document[field];
+    if (value !== undefined && (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.length > 0))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger ${field}: #`, { at: `#/${field}`, hint: `provide ${field} as an array of non-empty media-type strings` });
+  }
+  let schemas: unknown;
+  let schemasAt: string;
+  if (version === '2.0') {
+    schemas = document.definitions;
+    schemasAt = '#/definitions';
+  } else {
+    if (document.components !== undefined && (!document.components || typeof document.components !== 'object' || Array.isArray(document.components))) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid OpenAPI document: components must be an object', { at: '#/components', hint: 'provide an OpenAPI Components Object' });
+    schemas = document.components?.schemas;
+    schemasAt = '#/components/schemas';
+  }
+  if (schemas !== undefined) {
+    if (!schemas || typeof schemas !== 'object' || Array.isArray(schemas)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid OpenAPI document: schema components must be an object', { at: schemasAt, hint: 'provide a map of named schemas' });
+    for (const [name, schema] of Object.entries(schemas)) if (!name || typeof schema !== 'boolean' && (!schema || typeof schema !== 'object' || Array.isArray(schema))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid schema component: ${name || '(empty name)'}`, { at: `${schemasAt}/${pointerToken(name)}`, hint: 'provide a non-empty component name and an object or boolean schema' });
+  }
+  if (!document.info || typeof document.info !== 'object' || typeof document.info.title !== 'string' || document.info.title.trim() === '' || typeof document.info.version !== 'string' || document.info.version.trim() === '') throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid OpenAPI document: info.title and info.version are required', { at: '#/info', hint: 'provide non-empty info.title and info.version strings' });
+  if (!document.paths || typeof document.paths !== 'object' || Array.isArray(document.paths)) throw new ZopiaError('ZOPIA_SPEC_MISSING_PATHS', 'invalid OpenAPI document: paths must be an object', { at: '#/paths', hint: 'add a paths object to the API document' });
+  for (const [path, item] of Object.entries(document.paths)) {
+    if (!path.startsWith('/') && !path.startsWith('x-')) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI document: path key must start with /: ${path}`, { at: `#/paths/${pointerToken(path)}`, hint: "start API path keys with '/'" });
+    if (path.startsWith('x-')) continue;
+    if (path.includes('?') || path.includes('#')) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI document: path must not contain a query or fragment: ${path}`, { at: `#/paths/${pointerToken(path)}`, hint: 'move query values into parameter objects and remove URL fragments' });
+    if (/[{}]/.test(path) && !/^\/([^{}]|\{[A-Za-z0-9._-]+\})*$/.test(path)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI document: malformed path template: ${path}`, { at: `#/paths/${pointerToken(path)}`, hint: 'use balanced {parameter} path segments' });
+    if (!item || typeof item !== 'object' || Array.isArray(item)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI document: path item must be an object: ${path}`, { at: `#/paths/${pointerToken(path)}`, hint: 'provide a Path Item object' });
+    const allowedPathItemFields = new Set(['$ref', 'parameters', ...PATH_ITEM_METHODS, ...(version === '2.0' ? [] : ['summary', 'description', 'servers'])]);
+    const unsupportedField = Object.keys(item).find((key) => !allowedPathItemFields.has(key) && !key.startsWith('x-'));
+    if (unsupportedField) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid OpenAPI document: unsupported path-item field: ${unsupportedField}`, { at: `#/paths/${pointerToken(path)}/${pointerToken(unsupportedField)}`, hint: 'use a supported HTTP method or an x- extension' });
+  }
+  return { document, version, title: document.info.title, versionString: document.info.version };
+}

package/src/conversions/reverse-security.ts

@@ -0,0 +1,68 @@
+import { ZopiaError } from '../errors';
+/** One OpenAPI security-requirement alternative. */
+export type OpenApiSecurityRequirement = Record<string, string[]>;
+
+/** Result of selecting or creating zopia's deterministic fallback scheme. */
+export interface ZopiaFallbackSecurityScheme {
+  /** Scheme name used by the synthesized operation requirement. */
+  name: string;
+  /** Security-scheme map including the fallback definition. */
+  schemes: Record<string, unknown>;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Validate and detach an OpenAPI security requirement list.
+ *
+ * @param value Candidate security-requirement array.
+ * @param context Human-readable field name used in failure messages.
+ * @returns Detached security-requirement alternatives in source order.
+ * @throws {@link ZopiaError} when the requirement shape is invalid.
+ */
+export function normalizeSecurityRequirements(value: unknown, context: string): OpenApiSecurityRequirement[] {
+  if (!Array.isArray(value)) throw new ZopiaError('ZOPIA_MANIFEST_INVALID', `Invalid ${context}: expected an array`);
+  return value.map((alternative, index) => {
+    if (!isRecord(alternative)) throw new ZopiaError('ZOPIA_MANIFEST_INVALID', `Invalid ${context} alternative ${index}: expected an object`);
+    const requirement: OpenApiSecurityRequirement = {};
+    for (const [name, scopes] of Object.entries(alternative)) {
+      if (!name || !Array.isArray(scopes) || !scopes.every((scope) => typeof scope === 'string')) throw new ZopiaError('ZOPIA_MANIFEST_INVALID', `Invalid ${context} alternative ${index}: expected scheme names with string scope arrays`);
+      Object.defineProperty(requirement, name, { value: [...scopes], enumerable: true, configurable: true, writable: true });
+    }
+    return requirement;
+  });
+}
+
+function isCompatibleFallback(value: unknown, swagger: boolean): boolean {
+  if (!isRecord(value)) return false;
+  if (swagger) return value.type === 'apiKey' && value.in === 'header' && typeof value.name === 'string' && value.name.toLowerCase() === 'authorization';
+  return value.type === 'http' && typeof value.scheme === 'string' && value.scheme.toLowerCase() === 'bearer';
+}
+
+/**
+ * Add or reuse a collision-safe bearer fallback without replacing existing schemes.
+ *
+ * @param input Existing security-scheme map to copy and extend.
+ * @param swagger Whether to emit a Swagger 2.0 API-key-compatible fallback.
+ * @returns Selected fallback name and a detached security-scheme map.
+ */
+export function ensureFallbackSecurityScheme(input: Record<string, unknown>, swagger: boolean): ZopiaFallbackSecurityScheme {
+  const schemes = { ...input };
+  let suffix = 1;
+  while (true) {
+    const name = suffix === 1 ? 'bearerAuth' : `bearerAuth${suffix}`;
+    if (!Object.prototype.hasOwnProperty.call(schemes, name)) {
+      Object.defineProperty(schemes, name, {
+        value: swagger
+          ? { type: 'apiKey', name: 'Authorization', in: 'header' }
+          : { type: 'http', scheme: 'bearer' },
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+      return { name, schemes };
+    }
+    if (isCompatibleFallback(schemes[name], swagger)) return { name, schemes };
+    suffix += 1;
+  }
+}