refactor(oauth): consolidate authorization flow primitives

[wenxi-onyx]

Description

OAuth connection flows now share one authorization-attempt lifecycle, but callers still repeated security-sensitive setup: tenant-aware cache lookup, the ten-minute TTL, payload field constraints, stable configuration fingerprints, protected authorization parameters, and internal return-path validation. Small differences in these rules can make callbacks accept stale configuration or allow provider options to replace fields owned by the OAuth flow.

This base change gives those rules one implementation. AuthorizationAttemptStore can now be declared once with a namespace and payload type; it resolves the current tenant cache for each operation, uses the standard TTL by default, and still accepts an injected cache for isolated tests. Canonical configuration fingerprints live with the attempt store, while shared OAuth models define fingerprint, PKCE-verifier, and safe return-path constraints. Protected authorization parameters remain beside authorization URL construction.

The scope remains intentionally narrow. Domain payload fields, configuration inputs, provider behavior, persistence, and callback side effects stay in their owning features. The next PRs can therefore declare one store and supply their own payload without rebuilding the common lifecycle or introducing a universal OAuth framework.

How Has This Been Tested?

Additional Options

• [Optional] Please cherry-pick this PR to the latest release version.
• [Optional] Override Linear Check

[greptile-apps]

Greptile Summary

The PR consolidates reusable OAuth authorization primitives while preserving the connector and MCP authorization flows.

• Introduces shared validation for safe internal OAuth return paths.
• Centralizes reserved authorization-parameter conflict detection.
• Reuses canonical JSON fingerprinting for MCP OAuth configuration snapshots.
• Adds unit coverage for order-independent, value-sensitive fingerprints.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking issues identified.

The consolidated validators and fingerprint helpers preserve reachable behavior for current OAuth callers, and the changed imports do not introduce a circular dependency or external initialization at import time.

Important Files Changed

Filename	Overview
backend/onyx/oauth/models.py	Adds a bounded shared type that validates OAuth callbacks redirect only to unchanged, printable internal paths.
backend/onyx/oauth/authorization_attempt.py	Adds deterministic JSON fingerprinting for authorization-attempt configuration snapshots.
backend/onyx/auth/oauth_token_manager.py	Centralizes detection of additional authorization parameters that conflict with protocol-owned values.
backend/onyx/server/features/mcp/models.py	Replaces duplicated MCP validation and reserved-parameter definitions with shared OAuth primitives.
backend/onyx/server/features/mcp/credentials.py	Reuses canonical fingerprinting without changing digests for realistic string-typed header and client-information values.
backend/onyx/server/features/mcp/oauth_flow.py	Uses centralized protocol-parameter conflict detection in known-provider authorization flows.
backend/onyx/server/documents/standard_oauth.py	Replaces the connector-specific return-path validator with behaviorally equivalent shared validation.
backend/tests/unit/onyx/oauth/test_authorization_attempt.py	Verifies that canonical fingerprints ignore mapping order while remaining sensitive to changed values.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Request[OAuth connect request] --> Validate[Validate SafeOAuthReturnPath]
  Validate --> Params[Reject conflicting protocol parameters]
  Params --> Snapshot[Fingerprint OAuth configuration]
  Snapshot --> Store[Store tenant-scoped authorization attempt]
  Store --> Provider[Redirect to OAuth provider]
  Provider --> Callback[OAuth callback]
  Callback --> Consume[Consume and validate attempt]
  Consume --> Return[Redirect to validated internal return path]

Loading

_{Reviews (1): Last reviewed commit: "refactor(oauth): consolidate authorizati..." | Re-trigger Greptile}

[github-actions]

Full-stack Preview (frontend + backend)

Status	Preview	Commit	Updated
✅	https://c033d98-onyx.preview.onyxcorp.dev/	c033d98	2026-08-22 00:24:34 UTC

Sign in with GitHub as an onyx-dot-app member to view it.

[cubic-dev-ai]

1 issue found across 8 files

Confidence score: 3/5

• backend/onyx/oauth/authorization_attempt.py passes list[tuple[str, str]] to mcp_oauth_connection_headers_fingerprint, which is outside Pydantic’s JsonValue type and causes strict ty check to fail; convert the header pairs to a JsonValue-compatible structure or adjust the typing.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/onyx/oauth/authorization_attempt.py">

<violation number="1" location="backend/onyx/oauth/authorization_attempt.py:24">
P2: `mcp_oauth_connection_headers_fingerprint` passes `list[tuple[str, str]]`, which is not included in Pydantic's `JsonValue` type, so the strict `ty check` fails on this call. Either convert the header pairs to JSON arrays before calling this helper or include that explicitly typed tuple-list shape in the helper's accepted input type.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: mcp_oauth_connection_headers_fingerprint passes list[tuple[str, str]], which is not included in Pydantic's JsonValue type, so the strict ty check fails on this call. Either convert the header pairs to JSON arrays before calling this helper or include that explicitly typed tuple-list shape in the helper's accepted input type.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At backend/onyx/oauth/authorization_attempt.py, line 24:

<comment>`mcp_oauth_connection_headers_fingerprint` passes `list[tuple[str, str]]`, which is not included in Pydantic's `JsonValue` type, so the strict `ty check` fails on this call. Either convert the header pairs to JSON arrays before calling this helper or include that explicitly typed tuple-list shape in the helper's accepted input type.</comment>

<file context>
@@ -20,6 +21,18 @@
 MAX_AUTHORIZATION_ATTEMPT_TTL_SECONDS = 10 * 60
 
 
+def canonical_json_fingerprint(value: JsonValue) -> str:
+    """Fingerprint configuration captured by a pending authorization attempt."""
+    serialized = json.dumps(
</file context>

Suggested change

	def canonical_json_fingerprint(value: JsonValue) -> str:
	def canonical_json_fingerprint(
	value: JsonValue | list[tuple[str, str]],
	) -> str:

[github-actions]

🖼️ Visual Regression Report

Project	Changed	Added	Removed	Unchanged	Report
admin	10	0	0	177	View Report
exclusive	0	0	0	10	✅ No changes