feat(auth)!: stop persisting ID token; persist decoded profile instead

[bmanquen]

• Decode ID token once at sign-in to derive userInfo, then discard it

  • Persist the decoded profile (Zod-validated on read) so it survives reloads
  • Clear stored profile on sign-out and on unrecoverable session expiry
  • core: drop idToken from saveAuthData; add saveUserInfo/storedUserInfo and getStoredUserInfo()
  • hooks: remove AuthenticationState.idToken; provider rehydrates from stored profile
  • ui: update authenticated-user test helper

  BREAKING CHANGE: the ID token is no longer exposed or persisted.

  • Removed AuthenticationState.idToken (use userInfo for profile data)
  • Removed the YouVersionPlatformConfiguration.idToken getter
  • saveAuthData(accessToken, refreshToken, expiryDate) no longer accepts an idToken arg

Greptile Summary

This PR removes the raw ID token from the auth persistence layer: the token is now decoded once at sign-in to produce a Zod-validated user profile, which is persisted in place of the token itself. Token refresh no longer requires a stored ID token, sign-out clears the profile alongside the OAuth tokens, and a new host-controlled mode lets native Expo wrappers pass an externally-obtained profile directly into the provider.

• YouVersionPlatformConfiguration: saveAuthData drops the idToken parameter; new saveUserInfo/storedUserInfo handle the decoded profile; clearAuthTokens now wipes the profile as well as the OAuth tokens.
• YouVersionAPIUsers: handleAuthCallback persists the decoded profile after exchange and clears everything (tokens + profile) if an error is thrown; getStoredUserInfo() reads the validated profile from storage; refreshTokens no longer needs or preserves a stored ID token.
• YouVersionAuthProvider: rehydrates userInfo via getStoredUserInfo() instead of re-decoding the token; adds a userInfo prop for host-controlled (native) auth flows.

Confidence Score: 4/5

Safe to merge after addressing the legacy idToken cleanup gap; all new auth paths are well-tested and logically sound.

The clearAuthTokens method no longer removes the idToken localStorage key. Existing users who signed in with the previous SDK version carry a raw ID token in storage; after upgrading and signing out, that key persists indefinitely because nothing in the new code touches it. The stated security goal of never keeping the signed token in storage is not met for this population until they uninstall or manually clear storage.

packages/core/src/YouVersionPlatformConfiguration.ts — the clearAuthTokens method needs a one-line migration to remove the legacy idToken key.

Important Files Changed

Filename	Overview
packages/core/src/YouVersionPlatformConfiguration.ts	Replaces idToken getter/storage with saveUserInfo/storedUserInfo (Zod-validated); clearAuthTokens no longer removes the legacy idToken localStorage key, leaving it in storage for existing users after upgrade
packages/core/src/Users.ts	handleAuthCallback now persists decoded profile instead of idToken; catch block correctly calls clearAuthTokens() before re-throwing; getStoredUserInfo() guards on id presence; refreshTokens() leaves the stored profile untouched
packages/core/src/schemas/user-info.ts	New Zod schema for the persisted profile; all fields optional (empty object passes), but getStoredUserInfo() adds an id-presence guard to prevent empty stubs from counting as authenticated
packages/hooks/src/context/YouVersionAuthProvider.tsx	Provider now rehydrates userInfo via getStoredUserInfo() instead of re-decoding idToken; adds host-controlled mode (userInfo prop) for Expo native sign-in bridging; two useEffects cleanly separated by isHostControlled guard
packages/hooks/src/useYVAuth.ts	Removes idToken from authTokens memo and AuthenticationState; isAuthenticated still derives from userInfo presence; no functional regressions
packages/ui/src/components/bible-reader.tsx	Adds onSignInPress/onSignOutPress props to BibleReader.Root, bridged to native handlers in UserMenu; falls back to web SDK auth when callbacks are absent
packages/ui/src/test/utils.ts	Updated setupAuthenticatedUser to use saveUserInfo + getStoredUserInfo mock instead of idToken; refreshTokenIfNeeded now returns true (matching the new refreshed=true to getStoredUserInfo path)

Comments Outside Diff (2)

1. packages/core/src/Users.ts, line 192-201 (link)

   extractSignInResult still attaches idToken to the result — partial removal of the exposure path

   handleAuthCallback no longer persists the ID token, but it still returns a SignInWithYouVersionResult whose idToken field is set (via extractSignInResult). processCallback() in useYVAuth returns this object directly, so any consumer calling result.idToken can still read the raw token from memory. If the intent is to fully remove the exposure vector, idToken should be omitted from the result constructed inside extractSignInResult.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/core/src/Users.ts
   Line: 192-201
   
   Comment:
   **`extractSignInResult` still attaches `idToken` to the result — partial removal of the exposure path**
   
   `handleAuthCallback` no longer persists the ID token, but it still returns a `SignInWithYouVersionResult` whose `idToken` field is set (via `extractSignInResult`). `processCallback()` in `useYVAuth` returns this object directly, so any consumer calling `result.idToken` can still read the raw token from memory. If the intent is to fully remove the exposure vector, `idToken` should be omitted from the result constructed inside `extractSignInResult`.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

2. packages/core/src/Users.ts, line 148-154 (link)

   Catch block doesn't clean up saveAuthData / saveUserInfo on error

   If an exception is raised after saveAuthData and saveUserInfo have already written to localStorage (e.g. window.history.replaceState throwing in a restrictive browser environment), the catch block removes the PKCE/OAuth temporary keys but leaves the persisted tokens and user profile intact. On the next page load the user would be treated as authenticated, while the provider also exposes the error that was thrown. Adding YouVersionPlatformConfiguration.clearAuthTokens() at the top of the catch block would make the failure path consistent with sign-out semantics.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/core/src/Users.ts
   Line: 148-154
   
   Comment:
   **Catch block doesn't clean up `saveAuthData` / `saveUserInfo` on error**
   
   If an exception is raised after `saveAuthData` and `saveUserInfo` have already written to localStorage (e.g. `window.history.replaceState` throwing in a restrictive browser environment), the catch block removes the PKCE/OAuth temporary keys but leaves the persisted tokens and user profile intact. On the next page load the user would be treated as authenticated, while the provider also exposes the error that was thrown. Adding `YouVersionPlatformConfiguration.clearAuthTokens()` at the top of the catch block would make the failure path consistent with sign-out semantics.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
packages/core/src/YouVersionPlatformConfiguration.ts:73-76
Legacy `idToken` localStorage key is never removed after upgrading. The old `saveAuthData` always removed `idToken` (passing null set `removeItem`), but the new signature dropped that branch entirely. Users who signed in with the previous version have a raw ID token sitting in `localStorage`; after upgrading they sign out, `clearAuthTokens` removes `accessToken`, `refreshToken`, `expiryDate`, and `userInfo` — but the `idToken` key is silently left behind. That directly contradicts this PR's stated goal of never keeping the signed token in storage.

```suggestion
  public static clearAuthTokens(): void {
    this.saveAuthData(null, null, null);
    this.saveUserInfo(null);
    // Migration: remove the legacy idToken key written by older versions of this SDK.
    // saveAuthData no longer touches this key, so it must be cleaned up explicitly.
    localStorage.removeItem('idToken');
  }
```

### Issue 2 of 2
packages/ui/src/components/bible-reader.tsx:423-436
Unnecessary `else` blocks after a return-like branch. Per the project style guide, prefer early returns to reduce nesting. Both handlers can be flattened by calling the host callback and returning early.

```suggestion
  const handleSignIn = () => {
    if (onSignInPress) {
      onSignInPress();
      return;
    }
    void signIn({ scopes: ['profile'] });
  };
  const handleSignOut = () => {
    if (onSignOutPress) {
      onSignOutPress();
      return;
    }
    void signOut();
  };
```

_{Reviews (3): Last reviewed commit: "fix(auth): harden sign-in result and cal..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[changeset-bot]

🦋 Changeset detected

Latest commit: d2e7621

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-core	Major
@youversion/platform-react-hooks	Major
@youversion/platform-react-ui	Major
vite-react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cameronapak]

Devin Review found 2 potential issues.

View 4 additional findings in Devin Review.

[cameronapak]

Please consider the feedback from DeepWiki and from Greptile. This is approved, but please, please, please do not merge the changeset PR after this yet. If we're making a breaking major change bump, I have some things I need to prep in another PR that would merge alongside it