|
| 1 | +/* |
| 2 | + * Copyright 2025 The Kubernetes Authors |
| 3 | + * |
| 4 | + * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | + * you may not use this file except in compliance with the License. |
| 6 | + * You may obtain a copy of the License at |
| 7 | + * |
| 8 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | + * |
| 10 | + * Unless required by applicable law or agreed to in writing, software |
| 11 | + * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | + * See the License for the specific language governing permissions and |
| 14 | + * limitations under the License. |
| 15 | + */ |
| 16 | + |
| 17 | +const VALID_PROVIDER_ID = /^[a-z0-9][a-z0-9._-]*$/i; |
| 18 | +const VALID_HOSTNAME = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i; |
| 19 | +const VALID_PATHNAME = /^\/[a-z0-9/._~-]*$/i; |
| 20 | +const MAX_PROVIDER_ID_LENGTH = 128; |
| 21 | + |
| 22 | +/** Identifies the protocol route owned by an OAuth provider. */ |
| 23 | +export interface OAuthProviderCallback { |
| 24 | + /** Hostname expected in the provider callback URL. */ |
| 25 | + hostname: string; |
| 26 | + /** Absolute path expected in the provider callback URL. */ |
| 27 | + pathname: string; |
| 28 | +} |
| 29 | + |
| 30 | +/** Describes an OAuth provider that can receive desktop protocol callbacks. */ |
| 31 | +export interface OAuthProviderRegistration { |
| 32 | + /** Stable identifier used to attribute callback failures. */ |
| 33 | + id: string; |
| 34 | + /** Protocol route owned by the provider. */ |
| 35 | + callback: OAuthProviderCallback; |
| 36 | + /** |
| 37 | + * Handles a callback claimed by this provider. |
| 38 | + * |
| 39 | + * @param url Validated callback URL, including provider query parameters. |
| 40 | + * @returns Nothing, or a promise that settles after callback handling completes. |
| 41 | + */ |
| 42 | + handleCallback(url: URL): void | Promise<void>; |
| 43 | +} |
| 44 | + |
| 45 | +const providersByCallback = new Map<string, OAuthProviderRegistration>(); |
| 46 | + |
| 47 | +/** |
| 48 | + * Creates a case-insensitive lookup key for a callback route. |
| 49 | + * |
| 50 | + * @param hostname Callback URL hostname. |
| 51 | + * @param pathname Callback URL pathname. |
| 52 | + * @returns A registry key for the callback route. |
| 53 | + */ |
| 54 | +function callbackKey(hostname: string, pathname: string): string { |
| 55 | + return `${hostname.toLowerCase()}\n${pathname}`; |
| 56 | +} |
| 57 | + |
| 58 | +/** |
| 59 | + * Checks whether a callback pathname is absolute and contains no traversal segments. |
| 60 | + * |
| 61 | + * @param pathname Callback pathname to validate. |
| 62 | + * @returns Whether the pathname is safe for exact route matching. |
| 63 | + */ |
| 64 | +function isValidPathname(pathname: string): boolean { |
| 65 | + return ( |
| 66 | + VALID_PATHNAME.test(pathname) && |
| 67 | + pathname.split('/').every(segment => segment !== '.' && segment !== '..') |
| 68 | + ); |
| 69 | +} |
| 70 | + |
| 71 | +/** |
| 72 | + * Validates an OAuth provider registration before storing it. |
| 73 | + * |
| 74 | + * @param registration Candidate provider registration to validate. |
| 75 | + * @returns Whether every registration field is valid. |
| 76 | + */ |
| 77 | +function isValidRegistration(registration: unknown): registration is OAuthProviderRegistration { |
| 78 | + if (typeof registration !== 'object' || registration === null) { |
| 79 | + return false; |
| 80 | + } |
| 81 | + |
| 82 | + const candidate = registration as Partial<OAuthProviderRegistration>; |
| 83 | + return ( |
| 84 | + typeof candidate.id === 'string' && |
| 85 | + candidate.id.length <= MAX_PROVIDER_ID_LENGTH && |
| 86 | + VALID_PROVIDER_ID.test(candidate.id) && |
| 87 | + typeof candidate.callback?.hostname === 'string' && |
| 88 | + VALID_HOSTNAME.test(candidate.callback.hostname) && |
| 89 | + typeof candidate.callback?.pathname === 'string' && |
| 90 | + isValidPathname(candidate.callback.pathname) && |
| 91 | + typeof candidate.handleCallback === 'function' |
| 92 | + ); |
| 93 | +} |
| 94 | + |
| 95 | +/** |
| 96 | + * Registers an OAuth provider as the exclusive owner of a callback route. |
| 97 | + * |
| 98 | + * @param registration Provider callback registration. |
| 99 | + * @returns A function that unregisters this provider without affecting replacements. |
| 100 | + * @throws When the registration is invalid or its callback route is already owned. |
| 101 | + */ |
| 102 | +export function registerOAuthProvider(registration: OAuthProviderRegistration): () => void { |
| 103 | + if (!isValidRegistration(registration)) { |
| 104 | + throw new Error('Invalid OAuth provider registration'); |
| 105 | + } |
| 106 | + const key = callbackKey(registration.callback.hostname, registration.callback.pathname); |
| 107 | + if (providersByCallback.has(key)) { |
| 108 | + throw new Error('OAuth callback is already registered'); |
| 109 | + } |
| 110 | + providersByCallback.set(key, registration); |
| 111 | + |
| 112 | + return () => { |
| 113 | + if (providersByCallback.get(key) === registration) { |
| 114 | + providersByCallback.delete(key); |
| 115 | + } |
| 116 | + }; |
| 117 | +} |
| 118 | + |
| 119 | +/** |
| 120 | + * Dispatches a product protocol URL to its registered OAuth provider. |
| 121 | + * |
| 122 | + * Provider failures are reported asynchronously and do not release ownership of |
| 123 | + * the callback URL to other protocol handlers. |
| 124 | + * |
| 125 | + * @param url Candidate OAuth callback URL. |
| 126 | + * @param protocolScheme Product protocol scheme accepted by this application. |
| 127 | + * @returns Whether a provider claimed the callback URL. |
| 128 | + */ |
| 129 | +export function dispatchOAuthCallback(url: URL, protocolScheme: string): boolean { |
| 130 | + if (url.protocol !== `${protocolScheme}:`) { |
| 131 | + return false; |
| 132 | + } |
| 133 | + const provider = providersByCallback.get(callbackKey(url.hostname, url.pathname)); |
| 134 | + if (!provider) { |
| 135 | + return false; |
| 136 | + } |
| 137 | + |
| 138 | + try { |
| 139 | + Promise.resolve(provider.handleCallback(url)).catch(error => { |
| 140 | + console.error(`OAuth callback failed for provider ${provider.id}:`, error); |
| 141 | + }); |
| 142 | + } catch (error) { |
| 143 | + console.error(`OAuth callback failed for provider ${provider.id}:`, error); |
| 144 | + } |
| 145 | + return true; |
| 146 | +} |
0 commit comments