@missionmind/auth-front 0.0.0-stage → 0.1.0

package/src/session.ts

@@ -0,0 +1,1006 @@
+import { observable } from "@legendapp/state";
+import { GoogleSignin } from "@react-native-google-signin/google-signin";
+import { randomUUID } from "expo-crypto";
+// biome-ignore lint/performance/noNamespaceImport: needed for expo-secure-store
+import * as SecureStore from "expo-secure-store";
+import { getAppleIdToken } from "./apple-id-token";
+import type { ExpoAuthClient } from "./client";
+
+const MAX_ATTEMPTS = 5;
+/** Creating the account at the end of onboarding: the user is waiting on it. */
+const ACCOUNT_ATTEMPTS = 3;
+const INITIAL_RETRY_DELAY_MS = 2000;
+const HTTP_UNAUTHORIZED = 401;
+const REGISTERED_ACCOUNT_KIND = "registered";
+const ANONYMOUS_ACCOUNT_KIND = "anonymous";
+
+export type AuthProvider = "email" | "apple" | "google";
+export type AuthAction = "sign_in" | "link_account";
+/** Where a sign-in started (`sign_in` by default), or `settings` for a link. */
+export interface AuthActionProps<EntryPoint extends string = string> {
+  entry_point: EntryPoint | "sign_in" | "settings";
+  provider: AuthProvider;
+}
+
+export interface AuthSessionOptions<EntryPoint extends string = string> {
+  apple: {
+    /**
+     * Apple's web sign-in on Android: the API's `createAppleWebSignInRouter`
+     * `/start` (`<api>/auth/apple/start`).
+     */
+    webSignInUrl: string;
+  };
+  google: {
+    /** The iOS OAuth client. */
+    iosClientId?: string;
+    /** The web OAuth client, whose id tokens the API verifies. */
+    webClientId?: string;
+  };
+  /**
+   * Keychain items an earlier version of the app wrote and nothing reads any
+   * more, deleted at launch.
+   */
+  legacyStorageKeys?: readonly string[];
+  /**
+   * The user's data on this device belongs to another account, or to none:
+   * a sign-in into another account (`isSameAccount` false) or back into the
+   * same one, or a device left without an account (`onStartOver`).
+   */
+  onAccountSignedIn?: (change: {
+    isSameAccount: boolean;
+    userId: string | undefined;
+  }) => Promise<void> | void;
+  /**
+   * An anonymous account was replaced by the account the user signed into,
+   * which the server deletes: hand over what is kept outside the API
+   * (purchases). Must not throw.
+   */
+  onAnonymousAccountReplaced?: (userId: string) => Promise<void> | void;
+  /** A password reset was requested or submitted (analytics). */
+  onPasswordReset?: () => void;
+  /** The user signs out (analytics). Called first. */
+  onSignOut?: () => void;
+  /**
+   * The device has no account any more (signed out, or its anonymous account
+   * is gone): empty what it kept of the old one.
+   */
+  onStartOver?: () => Promise<void> | void;
+  /**
+   * Where the password reset email's link leads: the API's
+   * `createResetPasswordRouter`.
+   */
+  passwordResetUrl: string;
+  /** Errors worth hearing about, beside the console (Sentry). */
+  reportError?: (error: unknown) => void;
+  /**
+   * The origin id-token sign-ins (Apple, Google) send as `expo-origin`: one of
+   * the API's trusted origins, such as `myapp://`.
+   */
+  signInOrigin: string;
+  /**
+   * Wraps each sign-in and link (analytics). `run` resolves false when the user
+   * backed out. Must return what `run` returned, and rethrow what it threw.
+   */
+  trackAction?: (
+    action: AuthAction,
+    props: AuthActionProps<EntryPoint>,
+    run: () => Promise<boolean>
+  ) => Promise<boolean>;
+}
+
+export class AuthenticationError extends Error {
+  code: string;
+
+  constructor(status: number, code: string) {
+    super(status.toString());
+    this.name = "AuthenticationError";
+    this.code = code;
+  }
+}
+
+class TransientAuthError extends Error {}
+
+function wait(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function throwOnAuthError(
+  error: { status: number; code?: string | undefined } | null
+) {
+  if (error) {
+    console.error(error);
+    throw new AuthenticationError(error.status, error.code ?? "UNKNOWN_ERROR");
+  }
+}
+
+/**
+ * Read synchronously: the asynchronous keychain calls queue behind the others
+ * at launch and can take seconds. A keychain that cannot be read counts as
+ * empty.
+ */
+function readKeychain(key: string) {
+  try {
+    return SecureStore.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The signed-in user, when the provider answered with one.
+ *
+ * A social sign-in resolves either to a session — the id token flow every
+ * platform here uses — or to a URL the user still has to visit, which carries
+ * no user yet.
+ */
+function getSignedInUserId(data: unknown): string | undefined {
+  if (data && typeof data === "object" && "user" in data) {
+    return (data as { user: { id: string } }).user.id;
+  }
+
+  return;
+}
+
+/**
+ * The account a device holds, and everything that signs it in and out.
+ *
+ * A device gets an anonymous account once (`ensureAccount`), and a long-lived
+ * device token in the keychain that brings that account back whenever its
+ * session dies (`ensureSession`, `recoverSession`). Signing in with an email,
+ * Apple or Google replaces an anonymous account (the server hands its data
+ * over), linking Apple or Google keeps it. A registered account that cannot be
+ * recovered asks the user to sign in (`isSignInRequired$`); an anonymous one
+ * starts over.
+ */
+export function createAuthSession<EntryPoint extends string = string>(
+  client: ExpoAuthClient,
+  options: AuthSessionOptions<EntryPoint>
+) {
+  const { authClient, readStoredCookie, storagePrefix } = client;
+  const DEVICE_TOKEN_STORAGE_KEY = `${storagePrefix}.device-token`;
+  const DEVICE_ID_STORAGE_KEY = `${storagePrefix}.device-id`;
+  const LAST_ACCOUNT_KIND_STORAGE_KEY = `${storagePrefix}.last-account-kind`;
+  const LAST_USER_ID_STORAGE_KEY = `${storagePrefix}.last-user-id`;
+
+  function reportError(error: unknown) {
+    options.reportError?.(error);
+  }
+
+  function track(
+    action: AuthAction,
+    props: AuthActionProps<EntryPoint>,
+    run: () => Promise<boolean>
+  ) {
+    return options.trackAction
+      ? options.trackAction(action, props, run)
+      : run();
+  }
+
+  /**
+   * Set when the device can no longer prove who it is and the account it lost
+   * is one the user can prove they own.
+   *
+   * A device whose anonymous account is lost starts over with onboarding, which
+   * is right for a visitor who never signed up and quietly destructive for
+   * everyone else: the account is still there on the server, and the only thing
+   * missing is a credential the user can supply themselves.
+   */
+  const isSignInRequired$ = observable(false);
+
+  /**
+   * Who the app is acting as.
+   *
+   * Straight from better-auth: the Expo client caches each `/get-session` reply
+   * in the keychain and seeds the session with it as the first one goes out, so
+   * the user is known before any reply comes back and stays known when one
+   * fails — the cached session is only dropped on a 401, which is the server
+   * actually saying the session is gone. Nothing here needs a store of its own.
+   */
+  function useAuthSession() {
+    const { data: session, isPending } = authClient.useSession();
+
+    return {
+      isAnonymous: Boolean(session?.user.isAnonymous),
+      isPending,
+      session,
+    };
+  }
+
+  /**
+   * Whether a sign-in actually left us signed in.
+   *
+   * Every sign-in response carries the session cookie, and the Expo client has
+   * written it to the keychain by the time the call resolves — better-auth's
+   * fetch layer awaits that hook before returning. Reading the cookie back is
+   * therefore a stronger check than a second `/get-session` and costs no round
+   * trip: the cookie is the thing every later request depends on.
+   */
+  async function hasSessionCookie(): Promise<boolean> {
+    return Boolean(await authClient.getCookie());
+  }
+
+  /**
+   * Tells better-auth to read the session again.
+   *
+   * A sign-in gets this for free — the Expo client raises the signal when the
+   * session cookie changes — but linking a provider leaves the cookie alone
+   * while changing what the account is, and every screen showing "anonymous"
+   * needs to hear about it.
+   */
+  function notifySessionChanged() {
+    authClient.$store.notify("$sessionSignal");
+  }
+
+  /**
+   * This install's name for itself, kept for as long as the keychain survives.
+   *
+   * The server files each device token under it, so two installs of the same
+   * account each keep their own; issuing one used to revoke every other, which
+   * only surfaced weeks later on whichever device was unlucky enough to need
+   * its token first.
+   *
+   * @returns isNew - true when the id was created just now, which also means
+   * the token stored beside it, if any, predates the scheme and is still
+   * untagged server-side.
+   */
+  async function getDeviceId(): Promise<{ deviceId: string; isNew: boolean }> {
+    const stored = await SecureStore.getItemAsync(DEVICE_ID_STORAGE_KEY);
+
+    if (stored) {
+      return { deviceId: stored, isNew: false };
+    }
+
+    const deviceId = randomUUID();
+    await SecureStore.setItemAsync(DEVICE_ID_STORAGE_KEY, deviceId);
+
+    return { deviceId, isNew: true };
+  }
+
+  /**
+   * The device token is a long-lived credential held in the keychain. It lets
+   * us re-authenticate as the same user after the server session expires, so
+   * session loss never orphans the workouts of someone who never created an
+   * account.
+   */
+  async function issueAndStoreDeviceToken(deviceId: string) {
+    const result = await authClient.$fetch<{ token: string }>(
+      "/device-token/issue",
+      { method: "POST", body: { deviceId } }
+    );
+
+    if (result.error || !result.data?.token) {
+      throw new TransientAuthError(
+        `Device token issuance failed (${result.error?.status ?? "no token returned"})`
+      );
+    }
+
+    await SecureStore.setItemAsync(DEVICE_TOKEN_STORAGE_KEY, result.data.token);
+  }
+
+  /**
+   * A token issued before this device had an id is untagged on the server,
+   * which leaves it revocable by any other install of the same account — so it
+   * is traded for one bound to this device the first time we come through here.
+   */
+  async function ensureDeviceToken() {
+    const { deviceId, isNew } = await getDeviceId();
+    const stored = await SecureStore.getItemAsync(DEVICE_TOKEN_STORAGE_KEY);
+
+    if (stored && !isNew) {
+      return;
+    }
+
+    await issueAndStoreDeviceToken(deviceId).catch((error) => {
+      // Best effort: the next ensureSession call retries issuance.
+      console.error("[auth] could not issue device token", error);
+      reportError(error);
+    });
+  }
+
+  /** Forgets the device token, so the next launch starts from a clean slate. */
+  async function clearDeviceToken() {
+    await SecureStore.deleteItemAsync(DEVICE_TOKEN_STORAGE_KEY);
+  }
+
+  /**
+   * Remembers whether the account the device holds is one the user could sign
+   * back into, so a refused device token can be told apart from a visitor who
+   * never had anything to lose. By the time it is read there is no session left
+   * to ask.
+   */
+  async function rememberAccountKind(isAnonymous: boolean) {
+    await SecureStore.setItemAsync(
+      LAST_ACCOUNT_KIND_STORAGE_KEY,
+      isAnonymous ? ANONYMOUS_ACCOUNT_KIND : REGISTERED_ACCOUNT_KIND
+    ).catch((error) => {
+      // Losing this only costs us the sign-in prompt on a failed recovery.
+      console.error("[auth] could not record account kind", error);
+    });
+  }
+
+  /**
+   * Remembers which user the local data belongs to, so a sign-in can tell
+   * signing back into the same account (keep the data, sync it) from switching
+   * to another one (clear it).
+   */
+  async function rememberAccountUser(userId: string) {
+    await SecureStore.setItemAsync(LAST_USER_ID_STORAGE_KEY, userId).catch(
+      (error) => {
+        console.error("[auth] could not record account user", error);
+      }
+    );
+  }
+
+  function hadRegisteredAccount() {
+    return (
+      readKeychain(LAST_ACCOUNT_KIND_STORAGE_KEY) === REGISTERED_ACCOUNT_KIND
+    );
+  }
+
+  /**
+   * Leaves the device without an account: no credential, and no record of an
+   * account to sign back into. The next launch starts like a new install.
+   */
+  async function forgetAccount() {
+    await Promise.allSettled([
+      clearDeviceToken(),
+      SecureStore.deleteItemAsync(LAST_ACCOUNT_KIND_STORAGE_KEY),
+      SecureStore.deleteItemAsync(LAST_USER_ID_STORAGE_KEY),
+    ]);
+  }
+
+  /** Empties what the device kept of an account it no longer holds. */
+  async function startOverLocally() {
+    await options.onStartOver?.();
+  }
+
+  /**
+   * Rebinds the device to the user who is signed in right now.
+   *
+   * The stored token belongs to whoever held the session before — the anonymous
+   * user that has just been replaced by a real account, most of the time — and
+   * that user is usually deleted moments later, so keeping it would leave the
+   * device unable to recover any session at all.
+   */
+  async function refreshDeviceToken() {
+    const { deviceId } = await getDeviceId();
+
+    await clearDeviceToken();
+    await issueAndStoreDeviceToken(deviceId).catch((error) => {
+      // The device is now without a recovery credential: it will be issued one
+      // on the next launch, but until then a dead session cannot be recovered,
+      // which is worth hearing about rather than only reading in a console.
+      console.error("[auth] could not refresh device token", error);
+      reportError(error);
+    });
+  }
+
+  /** Resolves null when the token has been revoked, so the caller starts fresh. */
+  async function signInWithDeviceToken(
+    deviceToken: string
+  ): Promise<{ isAnonymous: boolean } | null> {
+    const result = await authClient.$fetch<{ user: { isAnonymous?: boolean } }>(
+      "/sign-in/device-token",
+      {
+        method: "POST",
+        body: { token: deviceToken },
+      }
+    );
+
+    if (!result.error) {
+      if (await hasSessionCookie()) {
+        return { isAnonymous: Boolean(result.data?.user.isAnonymous) };
+      }
+
+      throw new TransientAuthError(
+        "Session cookie missing after device token sign-in"
+      );
+    }
+
+    if (result.error.status === HTTP_UNAUTHORIZED) {
+      // The token was revoked server-side; forget it and start fresh.
+      await clearDeviceToken();
+      return null;
+    }
+
+    throw new TransientAuthError("Device token sign-in failed");
+  }
+
+  /**
+   * Whether the cookie in the keychain is still worth believing.
+   *
+   * Deliberately not an argument: a rejection arriving on one request says the
+   * credential is dead for every caller, the run already in flight included —
+   * and that run is the one about to answer them all. Passing the doubt in per
+   * call let it be dropped the moment two callers shared a run, which is
+   * exactly when it matters. Raised by whoever was refused, lowered by whatever
+   * establishes the next session.
+   */
+  let isStoredCookieDistrusted = false;
+
+  /**
+   * Says the credential this device holds has just been refused.
+   *
+   * The caller knows something nobody else does yet, including a session run
+   * already under way: the cookie it may be about to accept on sight is the one
+   * that was turned down.
+   */
+  function distrustStoredCookie() {
+    isStoredCookieDistrusted = true;
+  }
+
+  /**
+   * Brings back the session of the account this device holds, and creates an
+   * anonymous one only when `create` is set — at the end of onboarding, the one
+   * moment a device gets an account. A launch, a sync or a rejected request
+   * only ever recovers: a device that never finished onboarding has no
+   * account, and nothing on the server to sync with.
+   *
+   * At launch an unexpired session cookie is enough to consider the device
+   * signed in: better-auth is already fetching the session behind it, and a
+   * cookie the server no longer honours comes back as a rejected request, which
+   * lands in {@link recoverSession}. That reasoning collapses once recovery has
+   * spoken — the credential it is called about is this very one — so the
+   * shortcut is off both when the doubt was raised before we arrived and when
+   * it is raised while we are still inside it. Falling through costs a
+   * `/get-session` and answers the question for real.
+   */
+  async function establishSession(create: boolean): Promise<boolean> {
+    if (!isStoredCookieDistrusted && (await hasSessionCookie())) {
+      await ensureDeviceToken();
+
+      if (!isStoredCookieDistrusted) {
+        return true;
+      }
+    }
+
+    // Without a cookie there is no session for the server to find.
+    if (await hasSessionCookie()) {
+      const session = await authClient
+        .getSession()
+        .catch(() => ({ data: null, error: { status: 0 } }));
+
+      if (session.data) {
+        await rememberAccountKind(Boolean(session.data.user.isAnonymous));
+        await ensureDeviceToken();
+        return true;
+      }
+
+      if (session.error) {
+        // Network or server failure: the session may still exist, so giving up
+        // on it here would leave the account behind. Retry instead.
+        throw new TransientAuthError("Could not reach the auth server");
+      }
+    }
+
+    // Signed out. Recover the account this device holds via its device token.
+    const deviceToken = readKeychain(DEVICE_TOKEN_STORAGE_KEY);
+    if (deviceToken) {
+      const recovered = await signInWithDeviceToken(deviceToken);
+
+      if (recovered) {
+        await rememberAccountKind(recovered.isAnonymous);
+        await ensureDeviceToken();
+        notifySessionChanged();
+        return true;
+      }
+
+      if (!hadRegisteredAccount()) {
+        // The anonymous account is gone and nothing else could bring it back:
+        // the device starts over, with onboarding. Signing out drops the dead
+        // session from the keychain before the request even goes out.
+        await forgetAccount();
+        await authClient.signOut().catch(() => undefined);
+        await startOverLocally();
+      }
+    }
+
+    // Nothing left to prove who this device is. Someone who owns an account can
+    // prove it themselves, which beats starting them over with nothing.
+    if (hadRegisteredAccount()) {
+      isSignInRequired$.set(true);
+      return false;
+    }
+
+    if (!create) {
+      return false;
+    }
+
+    const created = await authClient.signIn.anonymous();
+    if (created.error || !created.data) {
+      throw new TransientAuthError("Anonymous sign-in failed");
+    }
+
+    await rememberAccountKind(true);
+    await ensureDeviceToken();
+
+    if (!(await hasSessionCookie())) {
+      throw new TransientAuthError(
+        "Session cookie missing after anonymous sign-in"
+      );
+    }
+
+    notifySessionChanged();
+
+    return true;
+  }
+
+  async function establishWithRetries(create: boolean, attempts: number) {
+    for (let attempt = 0; attempt < attempts; attempt++) {
+      if (attempt > 0) {
+        await wait(INITIAL_RETRY_DELAY_MS * 2 ** (attempt - 1));
+      }
+
+      try {
+        return await establishSession(create);
+      } catch {
+        // Transient failure, retry with backoff.
+      }
+    }
+
+    return false;
+  }
+
+  let inFlightSession: { create: boolean; run: Promise<boolean> } | null = null;
+  let hasEstablishedSession = false;
+
+  /**
+   * There is only ever one run: a second caller — a remount, a sync that found
+   * itself signed out — joins the one in flight rather than opening its own,
+   * which is what keeps two callers from each creating their own anonymous user
+   * and leaving one of them orphaned. A run that may create answers callers
+   * that only recover, and one that only recovers is waited for before
+   * creating. A successful run is remembered, so later callers cost nothing.
+   */
+  function runSession(create: boolean, attempts: number): Promise<boolean> {
+    if (hasEstablishedSession) {
+      return Promise.resolve(true);
+    }
+
+    // Waiting on the user rather than on the network: every caller would
+    // otherwise re-run a recovery that already knows how it ends.
+    if (isSignInRequired$.get()) {
+      return Promise.resolve(false);
+    }
+
+    if (inFlightSession) {
+      if (inFlightSession.create || !create) {
+        return inFlightSession.run;
+      }
+      return inFlightSession.run.then(
+        (established) => established || runSession(true, attempts)
+      );
+    }
+
+    const run = establishWithRetries(create, attempts).then((established) => {
+      hasEstablishedSession = established;
+
+      if (established) {
+        // Whatever it took to get here, the keychain now holds a cookie nobody
+        // has been refused on.
+        isStoredCookieDistrusted = false;
+      }
+
+      inFlightSession = null;
+
+      return established;
+    });
+    inFlightSession = { create, run };
+
+    return run;
+  }
+
+  /**
+   * Brings back the session of the account this device holds. Resolves false
+   * when there is none — a device that has not finished onboarding — or when
+   * the server cannot be reached.
+   */
+  function ensureSession(): Promise<boolean> {
+    return runSession(false, MAX_ATTEMPTS);
+  }
+
+  /**
+   * Gives the device its account, at the end of onboarding: the one it already
+   * holds, or a new anonymous one. Resolves false when the server cannot be
+   * reached, for the caller to offer a retry.
+   */
+  function ensureAccount(): Promise<boolean> {
+    return runSession(true, ACCOUNT_ATTEMPTS);
+  }
+
+  /**
+   * Re-establishes the session after the API has rejected our credentials.
+   *
+   * Distinct from {@link ensureSession} because that one remembers its success
+   * for the life of the process — right at launch, useless once the session it
+   * established has died. Forgetting that result is the whole difference; the
+   * run itself is still shared, since a dead session shows up as a rejection on
+   * several requests at once and they must not each start their own sign-in.
+   *
+   * The doubt is recorded before joining, so a run already in flight hears it
+   * too rather than answering from the cookie the caller was just refused on.
+   */
+  function recoverSession(): Promise<boolean> {
+    hasEstablishedSession = false;
+    distrustStoredCookie();
+
+    return ensureSession();
+  }
+
+  let isInitialized = false;
+
+  /**
+   * Brings back the session of the account this device holds, once per launch.
+   *
+   * A device that already holds a session costs nothing here — better-auth
+   * reads it on its own — and only one with an expired session goes on to
+   * trade its device token. A device without an account stays without one
+   * until onboarding ends ({@link ensureAccount}). The app is rendered before
+   * any of this finishes: what the user writes in the meantime is stored
+   * locally and synced when the session lands.
+   */
+  async function initializeAuth() {
+    if (isInitialized) {
+      return;
+    }
+
+    isInitialized = true;
+
+    // Nothing reads them any more.
+    for (const key of options.legacyStorageKeys ?? []) {
+      void SecureStore.deleteItemAsync(key).catch(() => {
+        // Never written on this device.
+      });
+    }
+
+    await ensureSession();
+  }
+
+  /**
+   * Whether this device holds no account: no session, no device token and no
+   * record of an account it could sign back into — a new install, or a device
+   * signed out. Such a user has nothing on the server to download, and gets an
+   * account when onboarding ends. Keychain items survive a reinstall on iOS, so
+   * a returning user still waits for their data.
+   *
+   * Synchronous on purpose, so the root layout can ask before the first render.
+   */
+  function holdsNoAccount() {
+    return !(
+      readStoredCookie() ||
+      readKeychain(DEVICE_TOKEN_STORAGE_KEY) ||
+      readKeychain(LAST_ACCOUNT_KIND_STORAGE_KEY)
+    );
+  }
+
+  let isGoogleConfigured = false;
+
+  function configureGoogleSignIn() {
+    if (isGoogleConfigured) {
+      return;
+    }
+
+    GoogleSignin.configure({
+      webClientId: options.google.webClientId,
+      iosClientId: options.google.iosClientId,
+    });
+
+    isGoogleConfigured = true;
+  }
+
+  /** Resolves null when the user backs out of the native sheet. */
+  async function getGoogleIdToken(): Promise<string | null> {
+    configureGoogleSignIn();
+
+    const signInResponse = await GoogleSignin.signIn();
+
+    if (signInResponse.type !== "success" || !signInResponse.data.idToken) {
+      return null;
+    }
+
+    return signInResponse.data.idToken;
+  }
+
+  function getAppleToken() {
+    return getAppleIdToken({ webSignInUrl: options.apple.webSignInUrl });
+  }
+
+  /**
+   * The current session cookie, as a header a sign-in request can carry.
+   *
+   * better-auth's Expo client strips cookies from id-token sign-ins — only
+   * `/link-social` keeps them — so Apple and Google reach the server looking
+   * like requests from nobody, and the anonymous plugin finds no anonymous
+   * account to delete. The email path, which does send its cookie, gets that
+   * cleanup for free. The sign-in handler itself never reads the cookie, so
+   * passing it only restores the symmetry.
+   */
+  async function previousSessionHeader(): Promise<Record<string, string>> {
+    const cookie = await authClient.getCookie();
+
+    return cookie ? { cookie } : {};
+  }
+
+  /**
+   * The account the device held, read before signing in: the session changes
+   * under us as soon as the sign-in answers. `userId` is the user the local
+   * data belongs to; a device that predates this record and held a registered
+   * account is assumed to sign back into it.
+   */
+  function previousAccount() {
+    return {
+      userId: readKeychain(LAST_USER_ID_STORAGE_KEY),
+      wasRegistered: hadRegisteredAccount(),
+      wasAnonymous:
+        readKeychain(LAST_ACCOUNT_KIND_STORAGE_KEY) === ANONYMOUS_ACCOUNT_KIND,
+    };
+  }
+
+  /**
+   * Signing in replaces the user this device carries: the anonymous one is
+   * dropped server-side, so the token that used to bring it back has to be
+   * traded for one bound to the account the user just proved they own.
+   */
+  async function onSignedIn(
+    userId: string | undefined,
+    previous: ReturnType<typeof previousAccount>
+  ) {
+    // The user just proved they own this account, which is exactly what a
+    // failed recovery was waiting for, and the sign-in wrote a cookie to go
+    // with it.
+    hasEstablishedSession = true;
+    isStoredCookieDistrusted = false;
+    isSignInRequired$.set(false);
+
+    // Rows carry no user id: what the device holds belongs to the account it
+    // had, and would otherwise be filed under this one. Signing back into the
+    // same account keeps it and syncs; any other account starts from its own.
+    const isSameAccount = previous.userId
+      ? previous.userId === userId
+      : previous.wasRegistered;
+    await options.onAccountSignedIn?.({ isSameAccount, userId });
+
+    await rememberAccountKind(false);
+    if (userId) {
+      await rememberAccountUser(userId);
+    }
+
+    const { onAnonymousAccountReplaced } = options;
+
+    // Independent of each other, and each a round trip or more: the sign-in
+    // screen waits for both, so they run side by side.
+    await Promise.all([
+      refreshDeviceToken(),
+      userId && previous.wasAnonymous && onAnonymousAccountReplaced
+        ? // What an anonymous account paid for would be lost with it: the
+          // server deletes it on this sign-in. Any other sign-in leaves
+          // subscriptions where they are, or signing out of a Pro account and
+          // into another would hand the subscription over. A failure here
+          // must not take the sign-in down with it.
+          Promise.resolve(onAnonymousAccountReplaced(userId)).catch((error) => {
+            console.error(
+              "[auth] could not hand the anonymous account over",
+              error
+            );
+            reportError(error);
+          })
+        : undefined,
+    ]);
+
+    notifySessionChanged();
+  }
+
+  async function signInWithEmail(
+    email: string,
+    password: string,
+    entryPoint: EntryPoint | "sign_in" = "sign_in"
+  ) {
+    return await track(
+      "sign_in",
+      { provider: "email", entry_point: entryPoint },
+      async () => {
+        const previous = previousAccount();
+        const { data, error } = await authClient.signIn.email({
+          email,
+          password,
+        });
+
+        throwOnAuthError(error);
+
+        await onSignedIn(data?.user.id, previous);
+        return true;
+      }
+    );
+  }
+
+  async function signInWithApple(
+    entryPoint: EntryPoint | "sign_in" = "sign_in"
+  ) {
+    return await track(
+      "sign_in",
+      { provider: "apple", entry_point: entryPoint },
+      async () => {
+        const previous = previousAccount();
+        const idToken = await getAppleToken();
+
+        if (!idToken) {
+          return false;
+        }
+
+        const { data, error } = await authClient.signIn.social({
+          provider: "apple",
+          idToken,
+          fetchOptions: {
+            headers: {
+              ...(await previousSessionHeader()),
+              "expo-origin": options.signInOrigin,
+            },
+          },
+        });
+
+        throwOnAuthError(error);
+
+        await onSignedIn(getSignedInUserId(data), previous);
+        return true;
+      }
+    );
+  }
+
+  async function signInWithGoogle(
+    entryPoint: EntryPoint | "sign_in" = "sign_in"
+  ) {
+    return await track(
+      "sign_in",
+      { provider: "google", entry_point: entryPoint },
+      async () => {
+        const previous = previousAccount();
+        const idToken = await getGoogleIdToken();
+
+        if (!idToken) {
+          return false;
+        }
+
+        const { data, error } = await authClient.signIn.social({
+          provider: "google",
+          idToken: { token: idToken },
+          fetchOptions: {
+            headers: {
+              ...(await previousSessionHeader()),
+              "expo-origin": options.signInOrigin,
+            },
+          },
+        });
+
+        throwOnAuthError(error);
+
+        await onSignedIn(getSignedInUserId(data), previous);
+        return true;
+      }
+    );
+  }
+
+  /**
+   * Attaches a provider to the account already in hand instead of signing into
+   * another one: the user keeps their id, and with it every workout they logged
+   * before they had a way to sign back in.
+   */
+  async function linkWithApple() {
+    return await track(
+      "link_account",
+      { provider: "apple", entry_point: "settings" },
+      async () => {
+        const idToken = await getAppleToken();
+
+        if (!idToken) {
+          return false;
+        }
+
+        const { error } = await authClient.linkSocial({
+          provider: "apple",
+          idToken,
+        });
+
+        throwOnAuthError(error);
+
+        // The account keeps its id but stops being anonymous, so a device token
+        // refused later is now worth a sign-in prompt rather than a fresh
+        // identity.
+        await rememberAccountKind(false);
+        await refreshDeviceToken();
+        notifySessionChanged();
+        return true;
+      }
+    );
+  }
+
+  async function linkWithGoogle() {
+    return await track(
+      "link_account",
+      { provider: "google", entry_point: "settings" },
+      async () => {
+        const idToken = await getGoogleIdToken();
+
+        if (!idToken) {
+          return false;
+        }
+
+        const { error } = await authClient.linkSocial({
+          provider: "google",
+          idToken: { token: idToken },
+        });
+
+        throwOnAuthError(error);
+
+        // The account keeps its id but stops being anonymous, so a device token
+        // refused later is now worth a sign-in prompt rather than a fresh
+        // identity.
+        await rememberAccountKind(false);
+        await refreshDeviceToken();
+        notifySessionChanged();
+        return true;
+      }
+    );
+  }
+
+  async function requestPasswordReset(email: string) {
+    options.onPasswordReset?.();
+
+    const { error } = await authClient.requestPasswordReset({
+      email,
+      redirectTo: options.passwordResetUrl,
+    });
+
+    throwOnAuthError(error);
+  }
+
+  async function resetPassword(newPassword: string, token: string) {
+    options.onPasswordReset?.();
+
+    const { error } = await authClient.resetPassword({ newPassword, token });
+
+    throwOnAuthError(error);
+  }
+
+  /**
+   * Leaves the account behind: the device holds no account any more, as on a
+   * new install, and onboarding gives it one again.
+   *
+   * The local data is emptied here rather than by the screen that asked for
+   * it: the app stays mounted across a sign-out, so nothing else would separate
+   * the data of the account being left from the next one.
+   */
+  async function signOut() {
+    options.onSignOut?.();
+
+    await forgetAccount();
+    isSignInRequired$.set(false);
+    // Signing out empties better-auth's cached session as well as the cookie,
+    // the latter before the request goes out, so even offline.
+    await Promise.allSettled([authClient.signOut(), GoogleSignin.signOut()]);
+    hasEstablishedSession = false;
+    await startOverLocally();
+  }
+
+  return {
+    ensureAccount,
+    ensureSession,
+    hasSessionCookie,
+    holdsNoAccount,
+    initializeAuth,
+    isSignInRequired$,
+    linkWithApple,
+    linkWithGoogle,
+    recoverSession,
+    rememberAccountKind,
+    rememberAccountUser,
+    requestPasswordReset,
+    resetPassword,
+    signInWithApple,
+    signInWithEmail,
+    signInWithGoogle,
+    signOut,
+    useAuthSession,
+  };
+}
+
+export type AuthSession = ReturnType<typeof createAuthSession>;