0018: app: Register OAuth callback providers

[illume]

Summary

• add a validated registry for desktop OAuth callback providers
• route startup, second-instance, and macOS protocol callbacks to registered providers
• keep unmatched product protocol URLs on the existing deep-link path
• cover registration, ownership, dispatch, and failure behavior with focused unit and Electron process tests

Stack

This PR is stacked on prerequisite patch 0009:

• 0009: app: electron: Read protocol scheme from product metadata #7252

The first three commits belong to that prerequisite; the final three commits are patch 0018. This PR will be rebased onto main after #7252 merges.

Provenance

• Direct source: Azure/aks-desktop#823, patch 0018-headlamp-upstream-oauth-provider-registry.patch
• Retained patch commit: 2e4c7e7d95a8a0fcba47961e9a4e79616739b38c, authored by Thomas Gamble on 2026-07-31
• Original OAuth callback flow: Azure/aks-desktop#260, commit 5b78e600bbb2666969c649043bd89610f407bebf
• Related branded protocol correction: Azure/aks-desktop#457, commit d9b4def25efc00ad66f4f2af23d2d89f9c6c0f86

The implementation commit preserves Thomas Gamble as author and the original author date, with Rene Dudfield as co-author.

Improvements over the existing changes

• Put focused unit and Electron process tests before the implementation commit so reviewers can see the intended behavior and regression boundaries independently of the production change.
• Raise focused registry branch coverage from the retained tests to 100%, with an enforced 80% threshold, so validation, cleanup, dispatch, and error paths cannot regress without failing the focused check.
• Document exported interfaces, fields, callbacks, parameters, and return values with TSDoc so downstream provider implementations have an explicit contract instead of relying on implementation details.
• Reject callback paths containing traversal segments so registrations cannot claim ambiguous or path-normalized routes that differ from the exact callback URL being dispatched.
• Verify case-normalized callback ownership, stale cleanup safety, and synchronous and asynchronous provider failures so route ownership remains deterministic and one failing provider cannot disrupt protocol handling.
• Exercise provider registration and callback dispatch in a real Electron main process without requiring Kubernetes so the process boundary is tested quickly and reliably in CI.
• Buffer macOS launch callbacks until providers and the application window are ready because Electron can emit open-url before ready; without buffering, a cold-start OAuth callback can be lost.
• Keep protocol listeners, startup arguments, window focus, validation, dialog errors, and renderer fallback out of main.ts so the Electron entry point remains wiring-focused and the protocol lifecycle can be tested as one encapsulated unit.

Testing

• make app-i18n-check
• npm --prefix app test -- electron/protocol.test.ts electron/oauthProvider.test.ts electron/protocolHandler.test.ts (55 tests)
• focused Istanbul coverage for app/electron/oauthProvider.ts and app/electron/protocolHandler.ts: 100% branches (80% threshold enforced)
• npm --prefix app/e2e-tests run test-app -- tests/protocolScheme.spec.ts tests/oauthProvider.spec.ts --workers=1 (2 tests)
• npm --prefix app run tsc
• npm --prefix app run compile-electron -- --dev
• git diff --check 8464d801..HEAD

Screenshots

Not applicable. This change adds main-process callback infrastructure with no visual difference.

Assisted by copilot.

[kubernetes-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: illume

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [illume]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Copilot]

Pull request overview

Adds desktop OAuth callback provider registration and routes product protocol URLs through registered providers.

Changes:

• Adds validated OAuth provider registration and dispatch.
• Integrates startup, second-instance, and macOS callback handling.
• Adds unit, coverage, and Electron process tests.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
app/package.json	Adds Istanbul coverage support.
app/package-lock.json	Locks coverage dependencies.
app/electron/protocol.ts	Reads and validates protocol schemes.
app/electron/protocol.test.ts	Tests protocol utilities.
app/electron/oauth-provider.ts	Implements the provider registry.
app/electron/oauth-provider.test.ts	Tests registry behavior.
app/electron/main.ts	Routes protocol callbacks.
app/e2e-tests/tests/protocolScheme.spec.ts	Tests custom deep-link routing.
app/e2e-tests/tests/oauthProvider.spec.ts	Tests Electron callback dispatch.
app/e2e-tests/fixtures/oauth-provider-main.ts	Provides the Electron test fixture.

Files not reviewed (1)

• app/package-lock.json: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• app/package-lock.json: Generated file

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• app/package-lock.json: Generated file

Suppressed comments (2)

app/electron/protocolHandler.ts:143

• This drains callbacks queued by open-url/second-instance before processing the original startup callback, reversing the ordering promised by setReady and the callbacks' arrival order. For example, callback B from a fast second launch is delivered before startup callback A. Process the non-macOS argv callback first, then drain pendingUrls.

      for (const value of pendingUrls.splice(0)) {
        processUrl(value);
      }
      if (platform !== 'darwin') {
        handleFirstProtocolUrl(argv);

app/electron/oauthProvider.ts:115

• A stale cleanup still removes a replacement when the caller re-registers the same registration object: after firstUnregister(); registerOAuthProvider(registration); firstUnregister(), this identity check succeeds again and deletes the new registration. That contradicts the documented replacement-safety guarantee. Associate each registration call with a unique stored entry/token and compare that token during cleanup rather than the caller-owned object.

  return () => {
    if (providersByCallback.get(key) === registration) {
      providersByCallback.delete(key);
    }