@hexclave/js 1.0.125 → 1.0.126

package/src/lib/hexclave-app/apps/implementations/client-app-impl.init-analytics.test.ts

@@ -0,0 +1,79 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { KnownErrors } from "@hexclave/shared";
+import { Result } from "@hexclave/shared/dist/utils/results";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { HexclaveClientApp, HexclaveClientAppConstructorOptions } from "../interfaces/client-app";
+
+const baseOptions = {
+  baseUrl: "http://localhost:12345",
+  projectId: "00000000-0000-4000-8000-000000000000",
+  publishableClientKey: "stack-pk-test",
+  tokenStore: "memory",
+  redirectMethod: "none",
+  noAutomaticPrefetch: true,
+} satisfies HexclaveClientAppConstructorOptions<true, string>;
+
+const analyticsAppDisabledMessage = "initAnalytics() was called, but the Analytics app is not enabled on this Hexclave project";
+
+// The backend's AnalyticsNotEnabled rejection only reaches the client through the event tracker's and session
+// recorder's upload callbacks, which only exist in a browser; this simulates such a rejection arriving.
+function simulateAnalyticsUploadResult(app: HexclaveClientApp, result: Result<Response, Error>) {
+  const handler: unknown = Reflect.get(app, "_handleAnalyticsUploadResult");
+  if (typeof handler !== "function") {
+    throw new Error("Expected HexclaveClientApp to have a _handleAnalyticsUploadResult method");
+  }
+  handler.call(app, result);
+}
+
+describe("HexclaveClientApp.initAnalytics", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not throw when analytics are configured", () => {
+    const app = new HexclaveClientApp(baseOptions);
+    expect(() => app.initAnalytics()).not.toThrow();
+  });
+
+  it("throws when analytics are disabled with the analytics option", () => {
+    const app = new HexclaveClientApp({ ...baseOptions, analytics: { enabled: false } });
+    expect(() => app.initAnalytics()).toThrow("`analytics.enabled` constructor option is set to false");
+  });
+
+  it("does not throw when only session replays are disabled", () => {
+    const app = new HexclaveClientApp({ ...baseOptions, analytics: { replays: { enabled: false } } });
+    expect(() => app.initAnalytics()).not.toThrow();
+  });
+
+  it("reports an error when the backend rejects uploads after initAnalytics() was called", () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const app = new HexclaveClientApp(baseOptions);
+    app.initAnalytics();
+
+    simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));
+    // Repeated rejections must not report the error again.
+    simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));
+
+    const reports = consoleError.mock.calls.filter((args) => args.some((arg) => String(arg).includes(analyticsAppDisabledMessage)));
+    expect(reports).toHaveLength(1);
+  });
+
+  it("throws from initAnalytics() when the backend already rejected uploads before it was called", () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const app = new HexclaveClientApp(baseOptions);
+
+    simulateAnalyticsUploadResult(app, Result.error(new KnownErrors.AnalyticsNotEnabled()));
+    expect(consoleError.mock.calls.some((args) => args.some((arg) => String(arg).includes(analyticsAppDisabledMessage)))).toBe(false);
+
+    expect(() => app.initAnalytics()).toThrow(analyticsAppDisabledMessage);
+  });
+
+  it("ignores upload failures unrelated to the Analytics app being disabled", () => {
+    const app = new HexclaveClientApp(baseOptions);
+    simulateAnalyticsUploadResult(app, Result.error(new Error("network error")));
+    expect(() => app.initAnalytics()).not.toThrow();
+  });
+});

package/src/lib/hexclave-app/apps/implementations/client-app-impl.ts

@@ -64,12 +64,13 @@ import { StackClientApp, StackClientAppConstructorOptions, StackClientAppJson }
 import { _HexclaveAdminAppImplIncomplete } from "./admin-app-impl";
 import { TokenObject, clientVersion, createCache, createCacheBySession, createEmptyTokenStore, getAnalyticsBaseUrl, getDefaultExtraRequestHeaders, getDefaultProjectId, getDefaultPublishableClientKey, getUrls, resolveApiUrls, resolveConstructorOptions } from "./common";
 import { EventTracker } from "./event-tracker";
+import { ExternalTokenStoreSessionAdapter, isExternalTokenStore } from "./external-token-store-session-adapter";
 import { augmentUrlWithPersistedRedirectBackState, getRawAfterAuthReturnTo, saveRedirectBackStateFromUrl } from "./redirect-back-state";
 import { recordRedirectAndThrowIfLoopDetected } from "./redirect-loop-breaker";
 import type { CrossDomainHandoffParams } from "./redirect-page-urls";
 import { crossDomainAuthQueryParams, getCrossDomainHandoffParamsFromCurrentUrl, planRedirectToHandler } from "./redirect-page-urls";
 import { subscribeSessionRefresh } from "./session-refresh-subscription";
-import { AnalyticsOptions, SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions } from "./session-replay";
+import { AnalyticsOptions, SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions, isAnalyticsNotEnabledError } from "./session-replay";
 
 export function stripBrowserActionQueryParam() {
   let stripAttemptsRemaining = 20;
@@ -202,6 +203,10 @@ function throwSetupError(error: HexclaveSetupError): never {
   throw error;
 }
 
+function createAnalyticsAppDisabledOnProjectError(): Error {
+  return new Error("initAnalytics() was called, but the Analytics app is not enabled on this Hexclave project, so the backend rejects all analytics uploads. Enable the Analytics app in the Hexclave dashboard (or in hexclave.config.ts), or remove the initAnalytics() call if this is intentional.");
+}
+
 function getRedirectHelperInstruction(handlerName: string): string {
   if (handlerName === "handler") {
     return "Use a page-specific redirect helper such as app.redirectToSignIn() instead.";
@@ -360,7 +365,10 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
   private readonly _analyticsOptions: AnalyticsOptions | undefined;
   private _sessionRecorder: SessionRecorder | null = null;
   private _eventTracker: EventTracker | null = null;
+  private _initAnalyticsCalled = false;
+  private _analyticsAppDisabledOnProject = false;
   private _pendingSignOut: Promise<void> | null = null;
+  private readonly _externalTokenStoreSessionAdapter: ExternalTokenStoreSessionAdapter;
 
   private __DEMO_ENABLE_SLIGHT_FETCH_DELAY = false;
   private readonly _ownedAdminApps = new DependenciesMap<[InternalSession, string], _HexclaveAdminAppImplIncomplete<false, string>>();
@@ -765,6 +773,13 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
         }
       });
     }
+    this._externalTokenStoreSessionAdapter = new ExternalTokenStoreSessionAdapter(
+      (sessionOptions) => this._interface.createSession(sessionOptions),
+      async (providerId, token) => {
+        const exchange = await this._interface.exchangeExternalAuthToken(providerId, token);
+        return Result.orThrow(exchange).accessToken;
+      },
+    );
 
     this._tokenStoreInit = resolvedOptions.tokenStore;
     this._redirectMethod = resolvedOptions.redirectMethod || (isBrowserLike() ? "window" : "none");
@@ -806,24 +821,28 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       return anonUser._internalSession;
     };
 
-    const analyticsEnabled = this._analyticsOptions?.enabled !== false;
+    const recordsAnalytics = this._getAnalyticsDisabledReason() == null && isBrowserLike();
 
     const sessionReplayOptions = getSessionReplayOptions(this._analyticsOptions);
-    if (analyticsEnabled && isBrowserLike() && this._hasPersistentTokenStore() && sessionReplayOptions.enabled) {
+    if (recordsAnalytics && sessionReplayOptions.enabled) {
       this._sessionRecorder = new SessionRecorder({
         projectId: this.projectId,
         sendBatch: async (body, opts) => {
-          return await this._interface.sendSessionReplayBatch(body, await getAnalyticsSession(), opts);
+          return this._handleAnalyticsUploadResult(
+            await this._interface.sendSessionReplayBatch(body, await getAnalyticsSession(), opts),
+          );
         },
       }, sessionReplayOptions);
       this._sessionRecorder.start();
     }
 
-    if (analyticsEnabled && isBrowserLike() && this._hasPersistentTokenStore()) {
+    if (recordsAnalytics) {
       this._eventTracker = new EventTracker({
         projectId: this.projectId,
         sendBatch: async (body, opts) => {
-          return await this._interface.sendAnalyticsEventBatch(body, await getAnalyticsSession(), opts);
+          return this._handleAnalyticsUploadResult(
+            await this._interface.sendAnalyticsEventBatch(body, await getAnalyticsSession(), opts),
+          );
         },
       });
       this._eventTracker.start();
@@ -1684,6 +1703,13 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       default: {
         if (tokenStoreInit === null) {
           return createEmptyTokenStore();
+        } else if (typeof tokenStoreInit === "object" && isExternalTokenStore(tokenStoreInit)) {
+          return this._externalTokenStoreSessionAdapter.getOrCreateTokenStore(tokenStoreInit, (store, previousSessionKey) => {
+            this._sessionsByTokenStoreAndSessionKey
+              .get(store)
+              ?.get(previousSessionKey)
+              ?.suggestAccessTokenExpired();
+          });
         } else if (typeof tokenStoreInit === "object" && "headers" in tokenStoreInit) {
           if (this._requestTokenStores.has(tokenStoreInit)) return this._requestTokenStores.get(tokenStoreInit)!;
 
@@ -1746,28 +1772,29 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
    * - So different token stores are separated and don't leak information between each other, eg. if the same user sends two requests to the same server they should get a different session object
    */
   private _sessionsByTokenStoreAndSessionKey = new WeakMap<Store<TokenObject>, Map<string, InternalSession>>();
+
+  private _getSessionKeyForTokenStore(tokenStore: Store<TokenObject>, tokenObj: TokenObject): string {
+    return this._externalTokenStoreSessionAdapter.getSessionKey(tokenStore, tokenObj);
+  }
   /**
    * @param overrideTokenObj The tokens to build the session for, if they haven't been written to the token store yet
    *                         (so we can warm a sign-in's session before the token store publishes it).
    */
   protected _getSessionFromTokenStore(tokenStore: Store<TokenObject>, overrideTokenObj?: TokenObject): InternalSession {
     const tokenObj = overrideTokenObj ?? tokenStore.get();
-    const sessionKey = InternalSession.calculateSessionKey(tokenObj);
+    const sessionKey = this._getSessionKeyForTokenStore(tokenStore, tokenObj);
     const existing = sessionKey ? this._sessionsByTokenStoreAndSessionKey.get(tokenStore)?.get(sessionKey) : null;
     if (existing) return existing;
 
-    const session = this._interface.createSession({
-      refreshToken: tokenObj.refreshToken,
-      accessToken: tokenObj.accessToken,
-    });
+    const session = this._externalTokenStoreSessionAdapter.createSessionForTokenStore(tokenStore, tokenObj, sessionKey);
     session.onAccessTokenChange((newAccessToken) => {
-      tokenStore.update((old) => InternalSession.calculateSessionKey(old) === sessionKey ? {
+      tokenStore.update((old) => this._getSessionKeyForTokenStore(tokenStore, old) === sessionKey ? {
         ...old,
         accessToken: newAccessToken?.token ?? null
       } : old);
     });
     session.onInvalidate(() => {
-      tokenStore.update((old) => InternalSession.calculateSessionKey(old) === sessionKey ? {
+      tokenStore.update((old) => this._getSessionKeyForTokenStore(tokenStore, old) === sessionKey ? {
         ...old,
         accessToken: null,
         refreshToken: null,
@@ -1796,6 +1823,11 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     if (!("accessToken" in tokens) || !("refreshToken" in tokens)) {
       throw new HexclaveAssertionError("Invalid tokens object; can't sign in with this", { tokens });
     }
+    // An external token store keys its session by the provider's session, so Hexclave refresh tokens from a
+    // first-party sign-in would be written into (and then silently replaced by) the provider's session.
+    if (this.isExternalAuthApp()) {
+      throw new Error("This app authenticates through an external provider and cannot sign in with Hexclave tokens. Sign in through the provider instead.");
+    }
     const attemptId = ++this._signInAttemptCounter;
     const tokenStore = this._getOrCreateTokenStore(await this._createCookieHelper());
 
@@ -2251,6 +2283,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       emailAuthEnabled: crud.auth_with_email,
       otpAuthEnabled: crud.otp_auth_enabled,
       oauthProviders: crud.oauth_providers,
+      externalAuthProviders: crud.external_auth_providers,
       passkeyAuthEnabled: crud.passkey_auth_enabled,
       isMultiFactorRequired: crud.requires_totp_mfa,
       isAnonymous: crud.is_anonymous,
@@ -3254,6 +3287,69 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     return crud && this._currentUserFromCrud(crud, session);
   }
 
+  isExternalAuthApp(): boolean {
+    return typeof this._tokenStoreInit === "object"
+      && this._tokenStoreInit != null
+      && isExternalTokenStore(this._tokenStoreInit);
+  }
+
+  initAnalytics(): void {
+    // This doesn't start anything: the constructor already starts analytics capture (see
+    // _initializeAutomaticSideEffects). Pages that never import the module constructing the client app record no
+    // analytics, which is easy to miss when the app is only imported where auth is used. Having a dedicated function
+    // to call on every tracked page makes that import explicit, and gives setup docs and AI prompts a concrete step
+    // to point at. Since the caller has thereby declared that they expect analytics, we fail loudly whenever we know
+    // analytics won't be recorded.
+    this._initAnalyticsCalled = true;
+
+    const disabledReason = this._getAnalyticsDisabledReason();
+    if (disabledReason != null) {
+      throw new Error(`initAnalytics() was called, but this Hexclave app will not record analytics because ${disabledReason}. Remove the initAnalytics() call if this is intentional.`);
+    }
+    if (this._analyticsAppDisabledOnProject) {
+      throw createAnalyticsAppDisabledOnProjectError();
+    }
+
+    // Outside the browser (eg. during SSR of a client component), analytics are never recorded, but the same module
+    // runs again in the browser where they are, so this isn't an error.
+    if (isBrowserLike() && this._eventTracker == null) {
+      throw new HexclaveAssertionError("initAnalytics() was called in the browser and _getAnalyticsDisabledReason() returned null, but the constructor did not start the event tracker. The two must agree on when analytics are recorded.");
+    }
+  }
+
+  /**
+   * Returns why this app will never record analytics, or null if it records them whenever it runs in a browser. The
+   * constructor and initAnalytics() both use this, so that the conditions under which analytics start and the
+   * conditions under which initAnalytics() throws can't drift apart.
+   *
+   * Whether the Analytics app is enabled on the project is not part of this, as the client only learns that once the
+   * backend rejects an upload; see _handleAnalyticsUploadResult.
+   */
+  private _getAnalyticsDisabledReason(): string | null {
+    if (this._analyticsOptions?.enabled === false) {
+      return "the `analytics.enabled` constructor option is set to false";
+    }
+    if (this._options.automaticSideEffects === false) {
+      return "the `automaticSideEffects` constructor option is set to false, which also disables analytics";
+    }
+    if (!this._hasPersistentTokenStore()) {
+      return "the `tokenStore` constructor option is null; analytics require a persistent token store such as \"cookie\" (or \"nextjs-cookie\" in Next.js)";
+    }
+    return null;
+  }
+
+  private _handleAnalyticsUploadResult(result: Result<Response, Error>): Result<Response, Error> {
+    if (result.status === "error" && isAnalyticsNotEnabledError(result.error) && !this._analyticsAppDisabledOnProject) {
+      this._analyticsAppDisabledOnProject = true;
+      // initAnalytics() usually runs at module load, long before the first upload, so it can't throw this itself. If
+      // it gets called after this point instead, it throws synchronously (see initAnalytics()).
+      if (this._initAnalyticsCalled) {
+        captureError("initAnalytics", createAnalyticsAppDisabledOnProjectError());
+      }
+    }
+    return result;
+  }
+
 
   _getTokenPartialUserFromSession(session: InternalSession, options: GetCurrentPartialUserOptions<HasTokenStore>): TokenPartialUser | null {
     const accessToken = session.getAccessTokenIfNotExpiredYet(0, null);
@@ -3269,6 +3365,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       primaryEmail: accessToken.payload.email,
       displayName: accessToken.payload.name,
       primaryEmailVerified: accessToken.payload.email_verified,
+      selectedTeamId: accessToken.payload.selected_team_id,
       isAnonymous,
       isMultiFactorRequired: accessToken.payload.requires_totp_mfa,
       isRestricted: accessToken.payload.is_restricted,
@@ -3281,11 +3378,16 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     if (!auth) {
       return null;
     }
+    const selectedTeamId = auth.selected_team_id ?? null;
+    if (selectedTeamId !== null && typeof selectedTeamId !== "string") {
+      throw new HexclaveAssertionError("Expected the Convex selected_team_id claim to be a string or null.");
+    }
     return {
       id: auth.subject,
       displayName: auth.name ?? null,
       primaryEmail: auth.email ?? null,
       primaryEmailVerified: auth.email_verified as boolean,
+      selectedTeamId,
       isAnonymous: auth.is_anonymous as boolean,
       isMultiFactorRequired: auth.requires_totp_mfa as boolean,
       isRestricted: auth.is_restricted as boolean,
@@ -3841,6 +3943,12 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     const signOutOperation = (async () => {
       // Preserve the old behavior of serializing concurrent sign-outs without coupling them to unrelated stores.
       await previousSignOut;
+      const externalTokenStore = this._externalTokenStoreSessionAdapter.getExternalTokenStoreForSession(session);
+      if (externalTokenStore != null) {
+        throw new HexclaveAssertionError(
+          `Cannot sign out an externally authenticated session through Hexclave. Sign out through the ${externalTokenStore.providerId} provider instead.`,
+        );
+      }
       await this._interface.signOut(session);
       if (options?.redirectUrl) {
         await this._redirectTo({ url: options.redirectUrl, replace: true });
@@ -4018,6 +4126,9 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
         if (typeof this._redirectMethod !== "string") {
           throw new HexclaveAssertionError("Cannot serialize to JSON from an application with a non-string redirect method");
         }
+        if (typeof this._tokenStoreInit === "object" && this._tokenStoreInit != null && isExternalTokenStore(this._tokenStoreInit)) {
+          throw new HexclaveAssertionError("Cannot serialize an app with an external token store because its callbacks are not serializable. Construct this app in the client runtime instead.");
+        }
 
         const publishableClientKey = "publishableClientKey" in this._interface.options
           ? this._interface.options.publishableClientKey

package/src/lib/hexclave-app/apps/implementations/external-token-store-session-adapter.ts

@@ -0,0 +1,190 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { KnownErrors } from "@hexclave/shared";
+import type { ExternalAuthProviderId } from "@hexclave/shared/dist/interface/external-auth";
+import { AccessToken, InternalSession } from "@hexclave/shared/dist/sessions";
+import { throwErr } from "@hexclave/shared/dist/utils/errors";
+import { Store } from "@hexclave/shared/dist/utils/stores";
+import type { ExternalTokenStore } from "../../common";
+import { createEmptyTokenStore, type TokenObject } from "./common";
+
+type ExternalTokenStoreState = {
+  generation: number,
+  providerSessionId: string | null | undefined,
+};
+
+type SessionOptions = {
+  refreshToken: string | null,
+  accessToken?: string | null,
+  sessionKey?: string,
+  refreshAccessTokenWithoutRefreshTokenCallback?: () => Promise<AccessToken | null>,
+};
+
+export function isExternalTokenStore(value: object): value is ExternalTokenStore {
+  return "type" in value && value.type === "external";
+}
+
+export class ExternalTokenStoreSessionAdapter {
+  private readonly storesByExternalTokenStore = new WeakMap<ExternalTokenStore, Store<TokenObject>>();
+  private readonly externalTokenStoresByStore = new WeakMap<Store<TokenObject>, ExternalTokenStore>();
+  private readonly externalTokenStoresBySession = new WeakMap<InternalSession, ExternalTokenStore>();
+  private readonly states = new WeakMap<ExternalTokenStore, ExternalTokenStoreState>();
+
+  constructor(
+    private readonly createSession: (options: SessionOptions) => InternalSession,
+    private readonly exchangeToken: (providerId: ExternalAuthProviderId, token: string) => Promise<string>,
+  ) {}
+
+  getOrCreateTokenStore(
+    externalTokenStore: ExternalTokenStore,
+    onProviderChange: (store: Store<TokenObject>, previousSessionKey: string) => void,
+  ): Store<TokenObject> {
+    const existing = this.storesByExternalTokenStore.get(externalTokenStore);
+    if (existing != null) {
+      return existing;
+    }
+
+    const store = createEmptyTokenStore();
+    this.storesByExternalTokenStore.set(externalTokenStore, store);
+    this.externalTokenStoresByStore.set(store, externalTokenStore);
+    this.states.set(externalTokenStore, {
+      generation: 0,
+      providerSessionId: externalTokenStore.getSessionId?.(),
+    });
+    externalTokenStore.subscribe?.(() => {
+      const state = this.states.get(externalTokenStore) ?? throwErr("External token store state was not initialized");
+      // Derive the previous session's key from the recorded state, not from a live getSessionId()
+      // read: by the time this notification fires, the provider has already switched sessions, so a
+      // live read would compute the *new* key and the expiry hint would target the wrong session.
+      const previousSessionKey = this.buildSessionKey(externalTokenStore, state);
+      const providerSessionId = externalTokenStore.getSessionId?.();
+      if (externalTokenStore.getSessionId == null || providerSessionId !== state.providerSessionId) {
+        state.generation += 1;
+        state.providerSessionId = providerSessionId;
+      }
+      onProviderChange(store, previousSessionKey);
+      store.set({ accessToken: null, refreshToken: null });
+    });
+    return store;
+  }
+
+  getSessionKey(tokenStore: Store<TokenObject>, tokenObject: TokenObject): string {
+    const externalTokenStore = this.externalTokenStoresByStore.get(tokenStore);
+    if (externalTokenStore == null) {
+      return InternalSession.calculateSessionKey(tokenObject);
+    }
+
+    const state = this.states.get(externalTokenStore) ?? throwErr("External token store state was not initialized");
+    // Read the provider session id live (instead of from state) so a session switch is reflected
+    // immediately, even before the store's subscribe notification has fired.
+    return this.buildSessionKey(externalTokenStore, {
+      generation: state.generation,
+      providerSessionId: externalTokenStore.getSessionId?.(),
+    });
+  }
+
+  private buildSessionKey(externalTokenStore: ExternalTokenStore, state: ExternalTokenStoreState): string {
+    if (externalTokenStore.getSessionId == null) {
+      return `external-${externalTokenStore.providerId}-${state.generation}`;
+    }
+    return state.providerSessionId == null
+      ? "not-logged-in"
+      : `external-${externalTokenStore.providerId}-${state.providerSessionId}`;
+  }
+
+  createSessionForTokenStore(
+    tokenStore: Store<TokenObject>,
+    tokenObject: TokenObject,
+    sessionKey: string,
+  ): InternalSession {
+    const externalTokenStore = this.externalTokenStoresByStore.get(tokenStore);
+    let session: InternalSession;
+    if (externalTokenStore == null) {
+      session = this.createSession({
+        refreshToken: tokenObject.refreshToken,
+        accessToken: tokenObject.accessToken,
+      });
+    } else if (sessionKey === "not-logged-in") {
+      // A provider can clear its session before its token store notification arrives; never let
+      // that transiently expose the previous provider session's cached Hexclave token.
+      session = this.createSession({
+        refreshToken: null,
+        accessToken: null,
+        sessionKey,
+      });
+    } else {
+      session = this.createSession({
+        refreshToken: null,
+        accessToken: tokenObject.accessToken,
+        sessionKey,
+        refreshAccessTokenWithoutRefreshTokenCallback: async () => {
+          const state = this.states.get(externalTokenStore) ?? throwErr("External token store state was not initialized");
+          const expectedGeneration = state.generation;
+          const assertSessionIdentityUnchanged = () => {
+            const liveSessionKey = this.buildSessionKey(externalTokenStore, {
+              generation: state.generation,
+              providerSessionId: externalTokenStore.getSessionId?.(),
+            });
+            if (state.generation !== expectedGeneration || liveSessionKey !== sessionKey) {
+              throw new Error("The external provider session changed while exchanging a token; retrying with the current provider session.");
+            }
+          };
+          // Returning null from this callback permanently invalidates the cached InternalSession, so
+          // we must only do it when the provider session is definitively gone — for transient states
+          // we throw instead, which surfaces the failure to the current caller but lets the next
+          // request retry the exchange.
+          const attemptExchange = async (isRetry: boolean): Promise<AccessToken | null> => {
+            assertSessionIdentityUnchanged();
+            const externalToken = await externalTokenStore.getToken();
+            assertSessionIdentityUnchanged();
+            if (externalToken == null) {
+              if (externalTokenStore.getSessionId?.() != null) {
+                // The provider reports an active session but handed out no token; this is usually a
+                // transient state (eg. its SDK is still initializing), so don't treat it as signed out.
+                throw new Error("The external token store returned no token even though it reports an active provider session. This is usually transient (eg. the provider SDK is still initializing) and the exchange will be retried on the next request.");
+              }
+              return null;
+            }
+            try {
+              const accessToken = await this.exchangeToken(externalTokenStore.providerId, externalToken);
+              const validatedAccessToken = AccessToken.createIfValid(accessToken)
+                ?? throwErr("External authentication exchange returned an invalid Hexclave access token");
+              // An explicit session key bypasses InternalSession's identity check. Refuse to install
+              // a token if the provider switched accounts while the exchange was in flight instead
+              // of returning null, which would permanently invalidate the reusable session.
+              assertSessionIdentityUnchanged();
+              return validatedAccessToken;
+            } catch (error) {
+              if (!KnownErrors.InvalidExternalAuthToken.isInstance(error)) {
+                throw error;
+              }
+              // The server rejects provider tokens that expired in flight with the same error as
+              // genuinely bad ones, so retry once with a freshly fetched provider token: the provider
+              // SDK replaces an expired token. If the fresh token is rejected too, the cause is not
+              // transient (eg. an issuer or client-ID misconfiguration), and it does not mean the
+              // provider session ended either: the backend re-establishes a Hexclave session for any
+              // valid provider token, so a rejection never signals revocation. Propagate the error
+              // instead of returning null, which would permanently invalidate this session and make
+              // a misconfiguration look like a silent sign-out.
+              if (isRetry) {
+                throw error;
+              }
+              return await attemptExchange(true);
+            }
+          };
+          return await attemptExchange(false);
+        },
+      });
+    }
+    if (externalTokenStore != null) {
+      this.externalTokenStoresBySession.set(session, externalTokenStore);
+    }
+    return session;
+  }
+
+  getExternalTokenStoreForSession(session: InternalSession): ExternalTokenStore | undefined {
+    return this.externalTokenStoresBySession.get(session);
+  }
+}

package/src/lib/hexclave-app/apps/interfaces/client-app.ts

@@ -83,6 +83,23 @@ export type StackClientApp<HasTokenStore extends boolean = boolean, ProjectId ex
      * `redirectToSignIn()`, `redirectToSignUp()`, `redirectToSignOut()`, or `redirectToAccountSettings()`.
      */
     readonly urls: Readonly<ResolvedHandlerUrls>,
+    /** Whether this app delegates authentication to an external provider token store. */
+    isExternalAuthApp(): boolean,
+
+    /**
+     * Marks the current page as one that should record analytics (page views, clicks, session replays, and clickmaps).
+     *
+     * Analytics capture starts automatically when the client app is constructed in the browser, so this function doesn't
+     * start anything itself. Call it at the top level of a client-side module that is loaded on every page you want to
+     * track (for example, your app's root layout or entry file); the call guarantees that the module creating the client
+     * app is actually imported, and therefore constructed, on that page.
+     *
+     * Throws if this app will never record analytics because of its constructor options (`analytics.enabled: false`,
+     * `automaticSideEffects: false`, or a `null` token store). If the Analytics app turns out to be disabled on the
+     * project, an error is reported as soon as the backend rejects the first upload. Outside the browser (eg. during
+     * server-side rendering), it doesn't throw for that reason alone.
+     */
+    initAnalytics(): void,
 
     signInWithOAuth(provider: string, options?: { returnTo?: string }): Promise<void>,
     signInWithCredential(options: { email: string, password: string, noRedirect?: boolean }): Promise<Result<undefined, KnownErrors["EmailPasswordMismatch"] | KnownErrors["InvalidTotpCode"]>>,

package/src/lib/hexclave-app/common.ts

@@ -3,6 +3,7 @@
 // THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
 //===========================================
 import { ProviderType } from "@hexclave/shared/dist/utils/oauth";
+import type { ExternalAuthProviderId } from "@hexclave/shared/dist/interface/external-auth";
 import type { GenericQueryCtx, UserIdentity } from "convex/server";
 export type {
   DefaultHandlerUrlTarget,
@@ -87,6 +88,37 @@ export type RequestLike = {
     | Record<string, string | null>,
 };
 
+export type ExternalTokenStore = {
+  readonly type: "external",
+  readonly providerId: ExternalAuthProviderId,
+  getSessionId?(): string | null,
+  getToken(): Promise<string | null>,
+  /** The adapter retains this subscription for its own lifetime and does not unsubscribe it. */
+  subscribe?(callback: () => void): () => void,
+};
+
+type ExternalTokenStoreOptions = Omit<ExternalTokenStore, "type" | "providerId">;
+
+function createExternalTokenStore(providerId: ExternalAuthProviderId, options: ExternalTokenStoreOptions): ExternalTokenStore {
+  return {
+    ...options,
+    type: "external",
+    providerId,
+  };
+}
+
+export function clerkTokenStore(options: ExternalTokenStoreOptions): ExternalTokenStore {
+  return createExternalTokenStore("clerk-integration", options);
+}
+
+export function betterAuthTokenStore(options: ExternalTokenStoreOptions): ExternalTokenStore {
+  return createExternalTokenStore("better-auth-integration", options);
+}
+
+export function workosTokenStore(options: ExternalTokenStoreOptions): ExternalTokenStore {
+  return createExternalTokenStore("workos-integration", options);
+}
+
 export type TokenStoreInit<HasTokenStore extends boolean = boolean> =
   HasTokenStore extends true ? (
     | "cookie"
@@ -94,6 +126,7 @@ export type TokenStoreInit<HasTokenStore extends boolean = boolean> =
     | "memory"
     | RequestLike
     | { accessToken: string, refreshToken: string }
+    | ExternalTokenStore
   )
   : HasTokenStore extends false ? null
   : TokenStoreInit<true> | TokenStoreInit<false>;

package/src/lib/hexclave-app/index.ts

@@ -83,13 +83,17 @@ export type {
 } from "./internal-api-keys";
 
 export {
+  betterAuthTokenStore,
+  clerkTokenStore,
   hexclaveAppInternalsSymbol,
+  workosTokenStore,
 } from "./common";
 export {
   getPagePrompt,
 } from "./url-targets";
 export type {
   GetCurrentUserOptions,
+  ExternalTokenStore,
   /** @deprecated Use GetCurrentUserOptions instead */
   GetCurrentUserOptions as GetUserOptions,
   HandlerUrlOptions,