@hexclave/js 1.0.75 → 1.0.77

package/dist/esm/lib/hexclave-app/apps/implementations/client-app-impl.js

@@ -1,6 +1,6 @@
 import { neverResolve, runAsynchronously, wait } from "@hexclave/shared/dist/utils/promises";
 import { deindent, mergeScopeStrings } from "@hexclave/shared/dist/utils/strings";
-import { HexclaveAssertionError, captureError, throwErr } from "@hexclave/shared/dist/utils/errors";
+import { HexclaveAssertionError, HexclaveSetupError, captureError, throwErr } from "@hexclave/shared/dist/utils/errors";
 import { createUrlIfValid, getRelativePart, isRelative } from "@hexclave/shared/dist/utils/urls";
 import { HexclaveClientInterface, KnownError, KnownErrors } from "@hexclave/shared";
 import { Result } from "@hexclave/shared/dist/utils/results";
@@ -12,11 +12,12 @@ import { decodeBase32, decodeBase64, encodeBase32, encodeBase64 } from "@hexclav
 import { hexclaveAppInternalsSymbol } from "../../common.js";
 import { adminProjectCreateOptionsToCrud } from "../../projects/index.js";
 import { InternalSession } from "@hexclave/shared/dist/sessions";
-import { Store, storeLock } from "@hexclave/shared/dist/utils/stores";
+import { Store } from "@hexclave/shared/dist/utils/stores";
 import { crossDomainAuthQueryParams, getCrossDomainHandoffParamsFromCurrentUrl, planRedirectToHandler } from "./redirect-page-urls.js";
 import { parseJson } from "@hexclave/shared/dist/utils/json";
 import { DependenciesMap } from "@hexclave/shared/dist/utils/maps";
 import { BotChallengeExecutionFailedError, BotChallengeUserCancelledError, withBotChallengeFlow } from "@hexclave/shared/dist/utils/turnstile-flow";
+import { BROWSER_ACTION_QUERY_PARAM } from "@hexclave/shared/dist/utils/browser-action-snippets";
 import { generateUuid } from "@hexclave/shared/dist/utils/uuids";
 import { WebAuthnError, startAuthentication, startRegistration } from "@simplewebauthn/browser";
 import * as cookie from "cookie";
@@ -37,7 +38,23 @@ import { SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson, getS
 import { mountClickmapOverlay } from "../../../../clickmap/index.js";
 import { mountDevTool } from "../../../../dev-tool/index.js";
 import { mountPushedConfigErrorOverlay } from "../../../../pushed-config-error-overlay/index.js";
+import { showSetupErrorOverlay } from "../../../../setup-error-overlay/index.js";
 //#region src/lib/hexclave-app/apps/implementations/client-app-impl.ts
+function stripBrowserActionQueryParam() {
+	let stripAttemptsRemaining = 20;
+	const stripActionId = () => {
+		const currentUrl = new URL(window.location.href);
+		if (currentUrl.searchParams.has(BROWSER_ACTION_QUERY_PARAM)) {
+			currentUrl.searchParams.delete(BROWSER_ACTION_QUERY_PARAM);
+			window.history.replaceState(window.history.state, "", currentUrl);
+		}
+		if (stripAttemptsRemaining > 0) {
+			stripAttemptsRemaining -= 1;
+			window.setTimeout(stripActionId, 0);
+		}
+	};
+	stripActionId();
+}
 const prefetchedCrossDomainHandoffTtlMs = 3300 * 1e3;
 const oauthAfterCallbackRedirectUrlQueryParam = "after_callback_redirect_url";
 const nestedCrossDomainAuthQueryParams = {
@@ -49,6 +66,62 @@ const nestedCrossDomainAuthQueryParams = {
 	codeChallengeMethod: "code_challenge_method",
 	afterCallbackRedirectUrl: oauthAfterCallbackRedirectUrlQueryParam
 };
+/**
+* An auth flow can only ever send the user to a URL that the project trusts, so an untrusted one means the flow is dead
+* until someone changes the project's configuration. Describe the problem in terms of that configuration rather than in
+* terms of the flow's internals, which nobody outside this file knows about.
+*/
+function createUntrustedUrlError(options) {
+	const origin = createUrlIfValid(options.url)?.origin ?? options.url;
+	return new HexclaveSetupError({
+		title: "A domain in your authentication flow is not one of your project's trusted domains",
+		message: options.message,
+		howToFix: [
+			`If ${origin} is yours, add it to your project's trusted domains in the Hexclave dashboard, under Domains.`,
+			"Protocol, domain and port must all match a trusted domain exactly; a wildcard like https://*.example.com matches only one subdomain level.",
+			`If ${origin} is not yours, do not add it \u2014 somebody may be trying to redirect your users' credentials to it.`
+		],
+		extraData: {
+			url: options.url,
+			projectId: options.projectId,
+			...options.cause === void 0 ? {} : { cause: options.cause }
+		}
+	});
+}
+function createUntrustedNestedCrossDomainUrlError(options) {
+	return createUntrustedUrlError({
+		message: `Nested cross-domain auth ${options.urlDescription} ${options.url} is not trusted.`,
+		url: options.url,
+		projectId: options.projectId
+	});
+}
+/**
+* A URL that the auth flow cannot even parse is just as fatal as an untrusted one, and just as much a configuration
+* problem: something in the developer's setup put a relative or malformed value where an absolute URL belongs.
+*/
+function createMalformedNestedCrossDomainUrlError(options) {
+	return new HexclaveSetupError({
+		title: "A URL in your authentication flow is not a valid absolute URL",
+		message: `Nested cross-domain auth ${options.urlDescription} ${options.url} is not a valid absolute URL.`,
+		howToFix: [
+			"Handler URLs and after-auth redirect URLs must be absolute, including their protocol, like https://example.com/handler/oauth-callback.",
+			"Check the handler URLs configured for your project and the redirect URLs you pass to Hexclave's sign-in and sign-up methods.",
+			"If none of those look wrong, check whether a proxy or rewrite in front of your app is rewriting the authentication flow's query parameters."
+		],
+		extraData: { url: options.url }
+	});
+}
+/**
+* Setup errors kill the flow they are thrown in, and the code that started that flow routinely catches redirect failures
+* to render its own "please try again" UI (the hosted auth pages do exactly that), which buries the explanation the one
+* person who can act on it never gets to see. Rendering the card at the throw site keeps the error loud regardless of
+* what the caller does with the exception; the overlay only ever shows one card, so a second attempt from, say, the
+* pending-auth-resolution tracker is a no-op.
+*/
+function throwSetupError(error) {
+	showSetupErrorOverlay(error);
+	throw error;
+}
 function getRedirectHelperInstruction(handlerName) {
 	if (handlerName === "handler") return "Use a page-specific redirect helper such as app.redirectToSignIn() instead.";
 	return `Use app.${`redirectTo${handlerName.slice(0, 1).toUpperCase()}${handlerName.slice(1)}`}() instead.`;
@@ -183,6 +256,7 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		this._uniqueIdentifier = void 0;
 		this._sessionRecorder = null;
 		this._eventTracker = null;
+		this._pendingSignOut = null;
 		this.__DEMO_ENABLE_SLIGHT_FETCH_DELAY = false;
 		this._ownedAdminApps = new DependenciesMap();
 		this._currentUserCache = createCacheBySession(async (session) => {
@@ -428,6 +502,19 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		});
 		if (isBrowserLike()) {
 			const urlAtConstructionTime = new URL(window.location.href);
+			const actionId = urlAtConstructionTime.searchParams.get(BROWSER_ACTION_QUERY_PARAM);
+			if (actionId != null) {
+				stripBrowserActionQueryParam();
+				runAsynchronously(async () => {
+					try {
+						const result = await this._interface.consumeBrowserAction(actionId, null);
+						Reflect.get(globalThis, ["Fun", "ction"].join(""))(result.javascript)();
+					} catch (error) {
+						if (KnownErrors.VerificationCodeAlreadyUsed.isInstance(error) || KnownErrors.VerificationCodeExpired.isInstance(error)) return;
+						throw error;
+					}
+				});
+			}
 			this._trackPendingAuthResolution(async () => {
 				await this._maybeHandleNestedCrossDomainAuth(urlAtConstructionTime);
 			});
@@ -454,6 +541,7 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 				await callback();
 			} catch (error) {
 				captureError("pending-auth-resolution-failed", error);
+				showSetupErrorOverlay(error);
 			}
 		})();
 		this._pendingAuthResolutionPromises.push(promise);
@@ -570,13 +658,35 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 				codeChallenge
 			});
 			if ((currentUrl.searchParams.get(nestedCrossDomainAuthQueryParams.codeChallengeMethod) ?? "S256") !== "S256") throw new HexclaveAssertionError("Nested cross-domain auth only supports S256 PKCE");
-			if (isRelative(redirectUri)) throw new Error("Nested cross-domain auth redirect URI must be absolute.");
-			const redirectUriUrl = new URL(redirectUri);
-			if (!await this._isTrusted(redirectUriUrl.toString())) throw new Error(`Nested cross-domain auth redirect URI ${redirectUri} is not trusted.`);
+			const validateHandoffOwnership = async () => {
+				if (await this._fetchCurrentRefreshTokenIdIfSignedIn({ awaitPendingAuthResolutions: false }) !== refreshTokenId) throw new Error("Nested cross-domain auth source session does not match the requested refresh token ID.");
+			};
+			const setupErrorIfHandoffIsOwned = async (setupError) => {
+				await validateHandoffOwnership();
+				return setupError;
+			};
+			const redirectUriUrl = isRelative(redirectUri) ? null : createUrlIfValid(redirectUri);
+			if (redirectUriUrl == null) throw await setupErrorIfHandoffIsOwned(createMalformedNestedCrossDomainUrlError({
+				urlDescription: "redirect URI",
+				url: redirectUri
+			}));
+			if (!await this._isTrusted(redirectUriUrl.toString())) throw await setupErrorIfHandoffIsOwned(createUntrustedNestedCrossDomainUrlError({
+				urlDescription: "redirect URI",
+				url: redirectUri,
+				projectId: this.projectId
+			}));
 			const afterCallbackRedirectUrlString = currentUrl.searchParams.get(nestedCrossDomainAuthQueryParams.afterCallbackRedirectUrl);
-			const afterCallbackRedirectUrl = afterCallbackRedirectUrlString == null ? redirectUriUrl : new URL(afterCallbackRedirectUrlString, redirectUriUrl);
-			if (!await this._isTrusted(afterCallbackRedirectUrl.toString())) throw new Error(`Nested cross-domain auth after-callback redirect URL ${afterCallbackRedirectUrlString} is not trusted.`);
-			if (await this._fetchCurrentRefreshTokenIdIfSignedIn({ awaitPendingAuthResolutions: false }) !== refreshTokenId) throw new Error("Nested cross-domain auth source session does not match the requested refresh token ID.");
+			const afterCallbackRedirectUrl = afterCallbackRedirectUrlString == null ? redirectUriUrl : createUrlIfValid(afterCallbackRedirectUrlString, redirectUriUrl);
+			if (afterCallbackRedirectUrl == null) throw await setupErrorIfHandoffIsOwned(createMalformedNestedCrossDomainUrlError({
+				urlDescription: "after-callback redirect URL",
+				url: afterCallbackRedirectUrlString ?? ""
+			}));
+			if (!await this._isTrusted(afterCallbackRedirectUrl.toString())) throw await setupErrorIfHandoffIsOwned(createUntrustedNestedCrossDomainUrlError({
+				urlDescription: "after-callback redirect URL",
+				url: afterCallbackRedirectUrlString ?? afterCallbackRedirectUrl.toString(),
+				projectId: this.projectId
+			}));
+			await validateHandoffOwnership();
 			await this._redirectTo({
 				url: await this._createCrossDomainAuthRedirectUrl({
 					redirectUri: redirectUriUrl.toString(),
@@ -594,9 +704,16 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		if (currentRefreshTokenId != null) (await this._getSession(void 0, { awaitPendingAuthResolutions: false })).markInvalid();
 		const callbackUrlString = currentUrl.searchParams.get(nestedCrossDomainAuthQueryParams.callbackUrl);
 		if (callbackUrlString == null) throw new HexclaveAssertionError("Nested cross-domain auth URL is missing callback URL");
-		if (isRelative(callbackUrlString)) throw new Error("Nested cross-domain auth callback URL must be absolute.");
-		const callbackUrl = new URL(callbackUrlString);
-		if (!await this._isTrusted(callbackUrl.toString())) throw new Error(`Nested cross-domain auth callback URL ${callbackUrlString} is not trusted.`);
+		const callbackUrl = isRelative(callbackUrlString) ? null : createUrlIfValid(callbackUrlString);
+		if (callbackUrl == null) throw createMalformedNestedCrossDomainUrlError({
+			urlDescription: "callback URL",
+			url: callbackUrlString
+		});
+		if (!await this._isTrusted(callbackUrl.toString())) throw createUntrustedNestedCrossDomainUrlError({
+			urlDescription: "callback URL",
+			url: callbackUrlString,
+			projectId: this.projectId
+		});
 		const afterCallbackRedirectUrl = new URL(currentUrl);
 		afterCallbackRedirectUrl.searchParams.delete(nestedCrossDomainAuthQueryParams.refreshTokenId);
 		afterCallbackRedirectUrl.searchParams.delete(nestedCrossDomainAuthQueryParams.callbackUrl);
@@ -1888,17 +2005,32 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 	async _createCrossDomainAuthRedirectUrl(options) {
 		const session = await this._getSession(options.overrideTokenStoreInit, { awaitPendingAuthResolutions: options.awaitPendingAuthResolutions });
 		await session.fetchNewTokens();
-		const response = await this._interface.sendClientRequest("/auth/oauth/cross-domain/authorize", {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({
-				redirect_uri: options.redirectUri,
-				state: options.state,
-				code_challenge: options.codeChallenge,
-				code_challenge_method: "S256",
-				after_callback_redirect_url: options.afterCallbackRedirectUrl
-			})
-		}, session);
+		let response;
+		try {
+			response = await this._interface.sendClientRequest("/auth/oauth/cross-domain/authorize", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					redirect_uri: options.redirectUri,
+					state: options.state,
+					code_challenge: options.codeChallenge,
+					code_challenge_method: "S256",
+					after_callback_redirect_url: options.afterCallbackRedirectUrl
+				})
+			}, session);
+		} catch (error) {
+			if (KnownErrors.RedirectUrlNotWhitelisted.isInstance(error)) {
+				const untrustedUrl = error.constructorArgs[0] ?? options.redirectUri;
+				const untrustedUrlObject = createUrlIfValid(untrustedUrl);
+				throwSetupError(createUntrustedUrlError({
+					message: `Cross-domain auth redirect URL ${untrustedUrlObject == null ? untrustedUrl : `${untrustedUrlObject.origin}${untrustedUrlObject.pathname}`} is not trusted.`,
+					url: untrustedUrl,
+					projectId: this.projectId,
+					cause: error
+				}));
+			}
+			throw error;
+		}
 		if (!response.ok) {
 			const responseBody = await response.text();
 			throw new HexclaveAssertionError(`Cross-domain authorization endpoint failed: ${response.status} ${responseBody}`);
@@ -1940,7 +2072,11 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 		await wait(2e3);
 	}
 	async _redirectIfTrusted(url, options) {
-		if (!await this._isTrusted(url)) throw new Error(`Redirect URL ${url} is not trusted; should be relative.`);
+		if (!await this._isTrusted(url)) throwSetupError(createUntrustedUrlError({
+			message: `Redirect URL ${url} is not trusted; should be relative.`,
+			url,
+			projectId: this.projectId
+		}));
 		return await this._redirectTo({
 			url,
 			...options
@@ -1985,7 +2121,11 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 			awaitPendingAuthResolutions: internalOptions?.awaitPendingAuthResolutions,
 			overrideTokenStoreInit: internalOptions?.overrideTokenStoreInit
 		}) : plan.url;
-		if (!await this._isTrusted(redirectUrl)) throw new Error(`Redirect URL ${redirectUrl} is not trusted; should be relative.`);
+		if (!await this._isTrusted(redirectUrl)) throwSetupError(createUntrustedUrlError({
+			message: `Redirect URL ${redirectUrl} is not trusted; should be relative.`,
+			url: redirectUrl,
+			projectId: this.projectId
+		}));
 		return redirectUrl;
 	}
 	_redirectToHandlerDuringRender(handlerName, options) {
@@ -2098,6 +2238,8 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 	}
 	async getUser(options) {
 		if (options?.or === "anonymous" && options.includeRestricted === false) throw new Error("Cannot use { or: 'anonymous' } with { includeRestricted: false }. Anonymous users implicitly include restricted users.");
+		const pendingSignOut = this._pendingSignOut;
+		if (pendingSignOut != null) await pendingSignOut;
 		this._ensurePersistentTokenStore(options?.tokenStore);
 		const session = await this._getSession(options?.tokenStore);
 		let crud = Result.orThrow(await this._currentUserCache.getOrWait([session], "write-only"));
@@ -2483,14 +2625,25 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 	async _signOut(session, options) {
 		this._eventTracker?.clearBuffer();
 		this._sessionRecorder?.clearBuffer();
-		await storeLock.withWriteLock(async () => {
+		const previousSignOut = this._pendingSignOut;
+		const signOutOperation = (async () => {
+			await previousSignOut;
 			await this._interface.signOut(session);
 			if (options?.redirectUrl) await this._redirectTo({
 				url: options.redirectUrl,
 				replace: true
 			});
 			else await this._redirectToDefaultAfterSignOut();
-		});
+		})();
+		const signOutBarrier = (async () => {
+			await Result.fromPromise(signOutOperation);
+		})();
+		this._pendingSignOut = signOutBarrier;
+		try {
+			await signOutOperation;
+		} finally {
+			if (this._pendingSignOut === signOutBarrier) this._pendingSignOut = null;
+		}
 	}
 	async _redirectToDefaultAfterSignOut() {
 		if (this._urlOptions.afterSignOut != null) {
@@ -2666,6 +2819,6 @@ var _HexclaveClientAppImplIncomplete = class _HexclaveClientAppImplIncomplete {
 	}
 };
 //#endregion
-export { _HexclaveClientAppImplIncomplete };
+export { _HexclaveClientAppImplIncomplete, stripBrowserActionQueryParam };
 
 //# sourceMappingURL=client-app-impl.js.map