[monarcode]

This branch is the 0.1.0-alpha.4 release, based on 0.1.0-alpha.3. It has three themes:

• Storage and users. Storage becomes an adapter, and users can come from the access token.
• Router support. Routers get their own entry points, and the /react hooks no longer depend on TanStack Router.
• Correctness. A security fix for return paths, plus several race-condition fixes.

It includes breaking changes (listed below), and the [CHANGELOG](CHANGELOG.md) has the full notes.

Security

• safeReturnTo no longer returns paths whose dot segments resolve to another origin. Inputs like /.//evil.com and /%2e//evil.com used to become //evil.com, which browsers follow to evil.com. Apps on alpha.3 or earlier that redirect to safeReturnTo's result should upgrade.

What's new

Storage

• Add a storage option and AuthStorage type, with webStorage() (localStorage, or sessionStorage per tab) and memoryStorage().
• Apply storage operations one at a time in issue order, and re-check the session after every read. Late or out-of-order async storage can no longer erase a newer sign-in.
• Make webStorage() explain when browser storage is missing, as on a server, instead of throwing a bare TypeError.

Users and sessions

• Add fromAccessToken(claims, map?), which reads the user from a JWT access token.
• Add auth.refresh() to force a refresh, and an optional revoke callback with the new REVOKE_FAILED code.
• Make AuthState a discriminated union, so checking status narrows user.
• Restore the saved session at mount when storage and the user source are synchronous, and mount AuthProvider in a layout effect so initializing never paints.
• Drop the crypto.randomUUID and structuredClone requirements, for React Native.

React and routers

• Add /tanstack-router with connectAuth, requireSession, SessionOutlet, redirectIfSignedIn and useRouterAuth.
• Add /react-router for React Router 7 and 8 in declarative, data and framework (ssr: false) modes, with useAuthRevalidation and a basename option on requireSession.
• Support TanStack Start in SPA mode: connectAuth is a no-op while the Router renders on a server.
• Support React 18.

Docs and examples

• Rewrite the README around a runnable DummyJSON quick start.
• Add five example apps under examples/, built in CI. The repo is now a pnpm workspace.

Fixes

• Unmounting no longer cancels a restore or refresh in progress. StrictMode used to flash unavailable, reject waiting loaders and send the same refresh token twice, which signed users out when the backend rotates tokens.
• A failed signIn no longer cancels a restore or aborts a refresh. Only a newer signIn or signOut() cancels one still validating.
• Mounting again applies what another tab saved meanwhile, such as a sign-out.
• A React Router data-mode SessionOutlet no longer renders child routes with the previous account's loader data.
• Guards read the session again when getSession() rejects with SESSION_CHANGED.

Breaking changes

• createAuth takes user instead of userSchema, and storage is now required. Pass storage: webStorage() to keep the old behaviour.
• getSession() and retry() return { sessionId, user } with no tokens.
  • Tokens move to auth.credentials.get().
  • refresh(session) becomes credentials.renew(credentials).
  • rejectSession(session) becomes credentials.reject(credentials).
  • auth.refresh() still exists but now takes no argument and forces a refresh.
• createRefreshFn is removed. AuthClient is now AuthClient<User, Input> and needs both type arguments.
• /react exports only createAuthHooks. connectAuth moves to /tanstack-router, and safeReturnTo moves to the package root.
• The peer dependencies are optional and react-dom is no longer one. @tanstack/react-router now needs ^1.132.0.
• Sign-in, updateUser and refresh reject with USER_VALIDATION_FAILED when the user schema does not accept its own output unchanged.
• Sessions are saved in a new format, so users sign in once after upgrading.

Test plan

• pnpm run check passes (lint, format, build, tests, type tests, README examples)
• pnpm test passes in both the sync and test:async storage runs
• pnpm run build:examples builds the package and all five example apps
• CI's oldest-peers job passes (React 18.0.0, @tanstack/react-router 1.132.0, react-router 7.0.0)