From a2e95444535c09ff0ccb79958cccb2cc9f4257a0 Mon Sep 17 00:00:00 2001
From: Vishu Bhatnagar <vishu.bhatnagar@ibm.com>
Date: Tue, 3 Nov 2026 12:05:56 +0000
Subject: [PATCH] feat: define OAuth connection validation contract

Signed-off-by: Vishu Bhatnagar <vishu.bhatnagar@ibm.com>
---
 README.md                                     |  2 ++
 .../contracts/oauthConnectionValidation.ts    | 25 +++++++++++++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 src/api/contracts/oauthConnectionValidation.ts

diff --git a/README.md b/README.md
index bad7d313..08787ddc 100644
--- a/README.md
+++ b/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
diff --git a/src/api/contracts/oauthConnectionValidation.ts b/src/api/contracts/oauthConnectionValidation.ts
new file mode 100644
index 00000000..e67cf83e
--- /dev/null
+++ b/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;