feat: define OAuth connection validation contract

README.md

@@ -167,6 +167,8 @@ npm run api:generate   # regenerate src/generated/ from ./openapi.json
 
 To bump the API version, replace `openapi.json` with the new spec, update the version note above, then run `npm run api:generate`.
 
+Post-authorization OAuth connection validation uses a [handwritten compatibility contract](./src/api/contracts/oauthConnectionValidation.ts) for [backend PR #7343](https://github.com/IBM/mcp-context-forge/pull/7343). It extends the existing generated handshake response without modifying `openapi.json`. Remove this compatibility contract once the automated schema refresh includes those fields.
+
 ## Code Quality
 
 ### Linting

src/api/contracts/oauthConnectionValidation.ts

@@ -0,0 +1,25 @@
+import type { GatewayHandshakeResponse } from "@/generated/types";
+
+/** Compatibility contract for backend PR #7343 until the generated schema includes it. */
+export interface OAuthConnectionValidationRequest {
+  baseUrl: string;
+  gatewayId: string;
+  validationMode: "post_authorization";
+}
+
+export type OAuthValidationStage = "token" | "negotiation" | "tools_list";
+export type OAuthValidationOutcome = "ok" | "failed" | "skipped" | "unsupported";
+
+interface OAuthValidationFields {
+  /** Optional so older backends without stage evidence can be rejected by the caller. */
+  stages?: Partial<Record<OAuthValidationStage, OAuthValidationOutcome>> | null;
+  failedStage?: "gateway" | OAuthValidationStage | null;
+  errorCode?: string | null;
+  reauthorizationRequired?: boolean;
+}
+
+/** Reuse existing handshake metadata without depending on a generated schema refresh. */
+export type OAuthConnectionValidationResponse =
+  | (Omit<NonNullable<GatewayHandshakeResponse>, keyof OAuthValidationFields> &
+      OAuthValidationFields)
+  | null;