@lpshanley/oidc-start-react 0.3.0 → 0.4.1

package/README.md

@@ -1,8 +1,8 @@
 # @lpshanley/oidc-start-react
 
-Add OpenID Connect sign-in to a TanStack Start app. Loaders can read the current user, components can start sign-in or sign-out, and Start’s middleware handles the session cookies. The code exchange and provider tokens stay on the server.
+Add OpenID Connect sign-in to a TanStack Start app. Loaders can read the current user, components can start sign-in or sign-out, and Start’s middleware handles the session cookies. The server exchanges the authorization code. Loaders and React components receive the user profile.
 
-This guide adds two routes to an existing app. The home page at `/` shows who is signed in. The callback at `/callback` receives the browser when the provider sends it back. [Complete example app](https://github.com/lpshanley/oidc-start/tree/main/examples/tanstack-start)
+The quickstart connects a root loader, a home page at `/` and a callback at `/callback`. The example also includes `/sign-in`, a guarded `/account` page and a `/settings` page that requires a recent login. [Complete example app](https://github.com/lpshanley/oidc-start/tree/main/examples/tanstack-start)
 
 For multi-replica deployment, see the [production guide](https://github.com/lpshanley/oidc-start/blob/main/docs/production.md) and [tested PostgreSQL example](https://github.com/lpshanley/oidc-start/tree/main/examples/postgres).
 
@@ -64,65 +64,194 @@ export const Route = createFileRoute('/callback')({
 })
 ```
 
-## 4. Connect the buttons
+## 4. Load the user in the root route
 
-In `src/routes/index.tsx`, call `getAuth()` from the loader. It returns `{ user }`, with `user: null` for a signed-out visitor. Bind `signOut` with `useServerFn` so TanStack follows the redirect to the provider when the user clicks the button.
+In `src/routes/__root.tsx`, call `getAuth()` from the loader. It returns `{ user }`, with `user: null` for a guest. Pass the result to `AuthProvider` so descendants share the user on the first render and after navigation. [Example root route](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/routes/__root.tsx)
+
+```tsx
+import { AuthProvider } from '@lpshanley/oidc-start-react/client'
+import { getAuth } from '@lpshanley/oidc-start-react/functions'
+import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router'
+
+export const Route = createRootRoute({ loader: () => getAuth(), component: Root })
+
+function Root() {
+  const auth = Route.useLoaderData()
+  return (
+    <html lang="en">
+      <head><HeadContent /></head>
+      <body>
+        <AuthProvider auth={auth}><Outlet /></AuthProvider>
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+Upgrading from 0.3.x? Rename the `OidcAuthProvider` import and JSX tags to `AuthProvider`. It takes the same `auth` and `children` props.
+
+## 5. Connect the buttons
+
+In `src/routes/index.tsx`, read the user and actions from `useAuth()`. The hook handles navigation to the provider for both sign-in and sign-out. [Example home page](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/routes/index.tsx)
 
 ```tsx
 import { displayName } from '@lpshanley/oidc-start-react'
-import { getAuth, getSignInUrl, signOut } from '@lpshanley/oidc-start-react/functions'
+import { useAuth } from '@lpshanley/oidc-start-react/client'
 import { createFileRoute } from '@tanstack/react-router'
-import { useServerFn } from '@tanstack/react-start'
 
-export const Route = createFileRoute('/')({
-  loader: () => getAuth(),
-  component: Home,
-})
+export const Route = createFileRoute('/')({ component: Home })
 
 function Home() {
-  const { user } = Route.useLoaderData()
-  const signOutAndRedirect = useServerFn(signOut)
-
-  if (!user) {
-    return <button onClick={async () => location.assign(await getSignInUrl())}>Sign in</button>
-  }
-
+  const { user, signIn, signOut } = useAuth()
+  if (!user) return <button onClick={() => signIn()}>Sign in</button>
   return (
     <main>
       <p>Signed in as {displayName(user)}.</p>
-      <button onClick={() => signOutAndRedirect()}>Sign out</button>
+      <button onClick={signOut}>Sign out</button>
     </main>
   )
 }
 ```
 
-For shared UI such as an account menu, load `getAuth()` in the root route and wrap `<Outlet />` in `<OidcAuthProvider auth={Route.useLoaderData()}>`. Import the provider and `useAuth` from `@lpshanley/oidc-start-react/client`. Components can then call `const { user, signIn, signOut } = useAuth()` and bind buttons with `onClick={() => signIn()}` or `onClick={() => signOut()}`. The first render uses the loader's user, and subsequent loader updates flow through the provider. [Example root route](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/routes/__root.tsx)
+Call `signOut()` for the current session or `signOut({ everywhere: true })` for all of this user's sessions in this app. Both use the same CSRF-protected POST server function. If the revocation store is unavailable, the server returns 503 so the user can retry.
+
+Use `useAuth().hasRole('admin')` to show role-specific UI. It returns false for signed-out users and sessions without a roles claim. Check authorization again in the server handler that reads private data or performs the action.
+
+Import `useUser` from `@lpshanley/oidc-start-react/client` when a component only needs the loader's `AuthUser | null`.
+
+For navigation links, import `SignedIn` and `SignedOut` from that same entry. Inside the provider, `<SignedIn><AccountMenu /></SignedIn>` shows the menu to a signed-in user and `<SignedOut><SignInButton /></SignedOut>` shows a button to a guest. Both use the loader's user during SSR and client navigation.
 
 **Try it.** Open `/` in a fresh browser session and choose **Sign in**. After the provider redirects you back, your name should appear and survive a reload. Choose **Sign out**, finish logout at the provider if prompted, and reload. You should see **Sign in** again.
 
-To return someone to a specific page, pass a local path when starting sign-in, for example `getSignInUrl({ data: { returnPathname: '/account' } })`.
+### Recheck the session when a tab regains focus
+
+To pick up a sign-out from another tab, add this effect to the root component that reads the auth loader. Invalidating the root match reruns `getAuth()` and supplies the new user to the provider. The server function returns only `{ user }` and sets `Cache-Control: no-store`.
+
+```tsx
+import { rootRouteId, useRouter } from '@tanstack/react-router'
+import { useEffect } from 'react'
+
+function useRecheckAuthOnFocus() {
+  const router = useRouter()
+  useEffect(() => {
+    const recheck = () => {
+      void router.invalidate({ filter: match => match.routeId === rootRouteId })
+    }
+    window.addEventListener('focus', recheck)
+    return () => window.removeEventListener('focus', recheck)
+  }, [router])
+}
+```
+
+Call `useRecheckAuthOnFocus()` once in the root component to opt in. A session check can update the idle timestamp, so a periodic timer in an unattended tab can extend its session.
+
+### Sign in and return here
+
+From a page with a sign-in button, pass its local pathname when the user clicks. The server sanitizes the path and binds it to this sign-in flow. Omitting the option keeps the default destination of `/`.
+
+```tsx
+function SignInHere() {
+  const { signIn } = useAuth()
+  return <button onClick={() => signIn({ returnPathname: window.location.pathname })}>Sign in</button>
+}
+```
+
+If the page needs its current filters or anchor after sign-in, append `window.location.search` or `window.location.hash` to the pathname. From a dedicated login page, pass the intended destination instead. The server function accepts the same option, for example `getSignInUrl({ data: { returnPathname: '/account' } })`.
 
 To prefill an account, pass `loginHint`. For an account picker, call `signIn({ prompt: 'select_account' })`. The hook, `getSignInUrl({ data: options })`, and `handleSignInRoute(options)` accept the same sign-in options. Supported prompts are `login`, `consent`, `select_account`, and `none`. Omitting `prompt` leaves the provider's usual SSO behavior in place.
 
 ## HTTP routes and server access
 
-The buttons above use server functions. If you prefer ordinary links and forms, mount these handlers from `@lpshanley/oidc-start-react` behind the same OIDC middleware. Choose the paths in your app.
+The buttons above call server functions through `useAuth()`. To call those functions directly, import `getSignInUrl` and `signOut` from `@lpshanley/oidc-start-react/functions`. Bind the latter with `useServerFn(signOut)` in a component so the router follows the sign-out redirect. For ordinary links and forms, mount these handlers from `@lpshanley/oidc-start-react` behind the same OIDC middleware. Choose the paths in your app.
 
 | Method | Handler | When to use it |
 | --- | --- | --- |
-| GET | `handleSignInRoute()` | Link to sign-in. The optional `returnPathname` query parameter selects a local return path. |
+| GET | `handleSignInRoute()` | Link to sign-in. Use `returnPathname` for the local return path and `maxAge` to request a recent provider login. |
 | GET | `handleCallbackRoute()` | Mount at the exact callback path registered with your provider. |
-| POST | `handleSignOutRoute()` | Submit a same-origin form. Add `server.middleware: [createCsrfMiddleware()]` to this route because the global filter above only covers server functions. |
+| POST | `handleSignOutRoute()` | Submit a same-origin form. Include the field `everywhere=1` to revoke all of the user's app sessions. Add `server.middleware: [createCsrfMiddleware()]` to this route because the global filter above only covers server functions. |
 | POST | `handleBackchannelLogoutRoute()` | Register this URL with your provider for back-channel logout. The provider sends a signed logout token without a browser Origin header. Keep the browser CSRF check scoped to the browser routes. |
 
 In a server handler, import `getOidcContext` from `@lpshanley/oidc-start-react/server` to access the resolved session and core for the current request. Use `getAuth()` from `/functions` when a loader or component only needs the user.
 
+### Protect route navigation
+
+Mount `GET: handleSignInRoute()` at a local path such as `/sign-in`. A protected route can then use the following option with `requireAuth` from `@lpshanley/oidc-start-react/functions`.
+
+```ts
+beforeLoad: ({ location }) => requireAuth({ signInPath: '/sign-in', returnPathname: location.href })
+```
+
+The helper reads the session on the server. A guest follows a document redirect to the sign-in route. A signed-in user is available as `Route.useRouteContext().user`. Enforce authorization in every server function or endpoint that serves private data, including those called by the guarded route.
+
+### Restrict an admin route by role
+
+Import `requireAuth` from `@lpshanley/oidc-start-react/functions`, `hasRole` from the package root, and `redirect` from `@tanstack/react-router`. Compose them in the admin route's `beforeLoad`.
+
+```ts
+beforeLoad: async ({ location }) => {
+  const { user } = await requireAuth({ signInPath: '/sign-in', returnPathname: location.href })
+  if (!hasRole(user, 'admin')) throw redirect({ href: '/forbidden', reloadDocument: true })
+  return { user }
+}
+```
+
+Guests sign in and return to the requested URL. An admin sees the dashboard. A signed-in user without the role goes to the app's `/forbidden` endpoint, which returns HTTP 403. Use role names from your provider's configured roles claim. [Admin route](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/routes/admin.tsx) · [Forbidden response](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/routes/forbidden.ts)
+
+Private endpoints must also check the current request before reading admin data or performing a mutation. In a server route handler, import `getOidcContext` from `@lpshanley/oidc-start-react/server` and check the resolved user.
+
+```ts
+const { user } = getOidcContext().auth()
+if (!user) return new Response(null, { status: 401 })
+if (!hasRole(user, 'admin')) return new Response(null, { status: 403 })
+// Perform the authorized operation here.
+```
+
 ### Customize callback failures
 
 Pass `onError({ reason, request })` to `handleCallbackRoute` to return a custom response. It takes precedence over `errorRedirectUrl`. A provider cancellation is `access_denied`, and a missing verifier (for example after its cookie expires) is `sign_in_expired`. Other reasons are `invalid_callback`, `invalid_state`, `provider_error`, `token_exchange_failed`, and `session_failed`. The middleware still clears the failed flow's verifier. A rejection by your own `allowSession` policy takes its separate 403 path.
 
+To show a message on your own login page, redirect the classified reason to a fixed local route.
+
+```ts
+GET: handleCallbackRoute({
+  onError: ({ reason }) => new Response(null, {
+    status: 303,
+    headers: {
+      Location: '/login?' + new URLSearchParams({ auth_error: reason }),
+      'Cache-Control': 'no-store',
+    },
+  }),
+})
+```
+
+On the login page, read `auth_error` with `Route.useSearch()`. When the parameter is present, render `<p role="alert">{authErrorMessage(auth_error)}</p>` using `authErrorMessage` from `@lpshanley/oidc-start-react`. Unknown values receive a generic retry message. Host access denials keep their 403 response.
+
+Keep the message visible until the user chooses **Dismiss**. Inside the login component, bind `const navigate = Route.useNavigate()` and use this click handler. It removes only the error parameter, preserves the fragment and replaces the current history entry so Back returns to the preceding page.
+
+```tsx
+<button onClick={() => navigate({
+  search: previous => ({ ...previous, auth_error: undefined }),
+  hash: true,
+  replace: true,
+  resetScroll: false,
+})}>Dismiss</button>
+```
+
+The working example wires the callback to the login page and includes the route's search validation. [Callback](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/routes/callback.ts) · [Dismissible login error](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/routes/login.tsx)
+
 ### Require a recent login
 
+Use `requireRecentAuth` from `@lpshanley/oidc-start-react/functions` in `beforeLoad` for a page that requires a recent provider login.
+
+```ts
+beforeLoad: ({ location }) => requireRecentAuth({
+  maxAge: 300, signInPath: '/sign-in', returnPathname: location.href,
+})
+```
+
+A guest or stale session is sent to the local sign-in endpoint with the same `maxAge` in seconds. A `maxAge` configured on `handleSignInRoute` caps the value the URL can request. Choose a positive window that gives the user time to return from the provider.
+
 Inside the server handler for a sensitive action, call `checkRecentAuth({ maxAge: 300 })` from `@lpshanley/oidc-start-react/server` before performing the action. If `isStale` is true, stop the mutation and offer `signIn({ maxAge: 300, returnPathname: '/settings' })`. Check again when the user submits the action after returning. Pick the maximum age in the server's policy.
 
 The age is in seconds and comes from the provider's ID-token `auth_time`. Signed-out users, existing sessions without that claim, and expired authentication all require sign-in. Token refresh preserves the original authentication time. A sign-in with `maxAge: 0` requests fresh authentication.

package/dist/auth-error.d.ts

@@ -0,0 +1,2 @@
+/** Safe display text for a callback reason or an untrusted auth_error query value. */
+export declare function authErrorMessage(reason: unknown): string;

package/dist/auth-error.js

@@ -0,0 +1,17 @@
+const retry = "Sign-in could not be completed. Please try again.";
+const messages = {
+    access_denied: "Sign-in was declined. You can try again.",
+    sign_in_expired: "Your sign-in request expired. Please start again.",
+    invalid_callback: retry,
+    invalid_state: retry,
+    provider_error: "Your identity provider could not complete sign-in. Please try again.",
+    token_exchange_failed: retry,
+    session_failed: retry,
+};
+/** Safe display text for a callback reason or an untrusted auth_error query value. */
+export function authErrorMessage(reason) {
+    if (typeof reason === "string" && Object.hasOwn(messages, reason)) {
+        return messages[reason];
+    }
+    return retry;
+}

package/dist/client.d.ts

@@ -1,7 +1,7 @@
-import { type ReactNode } from "react";
-import type { AuthSession, SignInOptions } from "@lpshanley/oidc-start-core/models";
+import { type ReactElement, type ReactNode } from "react";
+import { type AuthSession, type SignInOptions } from "@lpshanley/oidc-start-core/models";
 /** Supply the root loader's getAuth() result for SSR and client navigation. */
-export declare function OidcAuthProvider({ auth, children }: {
+export declare function AuthProvider({ auth, children }: {
     auth: AuthSession;
     children: ReactNode;
 }): import("react").FunctionComponentElement<import("react").ProviderProps<{
@@ -13,6 +13,22 @@ export declare function OidcAuthProvider({ auth, children }: {
         roles?: string[] | undefined;
     } | null;
 } | undefined>>;
+/** The user supplied by the current root loader, or null when signed out. */
+export declare function useUser(): {
+    sub: string;
+    email: string;
+    name: string | null;
+    picture?: string | null | undefined;
+    roles?: string[] | undefined;
+} | null;
+/** Render children when the loader has a signed-in user. */
+export declare function SignedIn({ children }: {
+    children: ReactNode;
+}): ReactElement | null;
+/** Render children when the loader has no signed-in user. */
+export declare function SignedOut({ children }: {
+    children: ReactNode;
+}): ReactElement | null;
 export declare function useAuth(): {
     user: {
         sub: string;
@@ -21,6 +37,12 @@ export declare function useAuth(): {
         picture?: string | null | undefined;
         roles?: string[] | undefined;
     } | null;
+    hasRole: (role: string) => boolean;
     signIn(options?: SignInOptions): Promise<void>;
-    signOut: () => Promise<never>;
+    signOut: {
+        (): Promise<never>;
+        (options?: {
+            everywhere?: boolean;
+        }): Promise<never>;
+    };
 };

package/dist/client.js

@@ -1,21 +1,39 @@
-import { createContext, createElement, useContext } from "react";
+import { createContext, createElement, Fragment, useContext } from "react";
 import { useServerFn } from "@tanstack/react-start";
+import { hasRole } from "@lpshanley/oidc-start-core/models";
 import { getSignInUrl, signOut } from "./functions.js";
 const AuthContext = createContext(undefined);
 /** Supply the root loader's getAuth() result for SSR and client navigation. */
-export function OidcAuthProvider({ auth, children }) {
+export function AuthProvider({ auth, children }) {
     return createElement(AuthContext.Provider, { value: auth }, children);
 }
-export function useAuth() {
+/** The user supplied by the current root loader, or null when signed out. */
+export function useUser() {
     const auth = useContext(AuthContext);
-    const signOutAndRedirect = useServerFn(signOut);
     if (!auth)
-        throw new Error("useAuth() requires an OidcAuthProvider.");
+        throw new Error("Wrap components that use auth hooks in <AuthProvider>.");
+    return auth.user;
+}
+/** Render children when the loader has a signed-in user. */
+export function SignedIn({ children }) {
+    return useUser() ? createElement(Fragment, null, children) : null;
+}
+/** Render children when the loader has no signed-in user. */
+export function SignedOut({ children }) {
+    return useUser() ? null : createElement(Fragment, null, children);
+}
+export function useAuth() {
+    const user = useUser();
+    const signOutAndRedirect = useServerFn(signOut);
+    function signOutUser(options) {
+        return signOutAndRedirect({ data: { everywhere: options?.everywhere } });
+    }
     return {
-        user: auth.user,
+        user,
+        hasRole: (role) => user !== null && hasRole(user, role),
         async signIn(options) {
             window.location.assign(await getSignInUrl({ data: options }));
         },
-        signOut: () => signOutAndRedirect(),
+        signOut: signOutUser,
     };
 }

package/dist/functions.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /** The signed-in user, or null. Never returns tokens. */
 export declare const getAuth: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, Promise<{
     user: {
@@ -8,17 +9,48 @@ export declare const getAuth: import("@tanstack/react-start").OptionalFetcher<un
         roles?: string[] | undefined;
     } | null;
 }>>;
+type GuardOptions = {
+    /** App-local GET endpoint mounted with handleSignInRoute(). */
+    signInPath: string;
+    /** App-local destination to resume after the callback. */
+    returnPathname: string;
+};
+/** Guard route navigation and supply a signed-in user to descendant routes. */
+export declare function requireAuth(options: GuardOptions): Promise<{
+    user: {
+        sub: string;
+        email: string;
+        name: string | null;
+        picture?: string | null | undefined;
+        roles?: string[] | undefined;
+    };
+}>;
+/** Guard navigation using the provider login time. Recheck inside sensitive actions. */
+export declare function requireRecentAuth(options: GuardOptions & {
+    maxAge: number;
+}): Promise<{
+    user: {
+        sub: string;
+        email: string;
+        name: string | null;
+        picture?: string | null | undefined;
+        roles?: string[] | undefined;
+    };
+}>;
 /** An authorization URL; also queues the flow's verifier cookie. */
-export declare const getSignInUrl: import("@tanstack/react-start").OptionalFetcher<undefined, import("zod").ZodOptional<import("zod").ZodObject<{
-    returnPathname: import("zod").ZodOptional<import("zod").ZodString>;
-    maxAge: import("zod").ZodOptional<import("zod").ZodNumber>;
-    loginHint: import("zod").ZodOptional<import("zod").ZodString>;
-    prompt: import("zod").ZodOptional<import("zod").ZodEnum<{
+export declare const getSignInUrl: import("@tanstack/react-start").OptionalFetcher<undefined, z.ZodOptional<z.ZodObject<{
+    returnPathname: z.ZodOptional<z.ZodString>;
+    maxAge: z.ZodOptional<z.ZodNumber>;
+    loginHint: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodEnum<{
         none: "none";
         login: "login";
         consent: "consent";
         select_account: "select_account";
     }>>;
-}, import("zod/v4/core").$strip>>, Promise<string>>;
+}, z.core.$strip>>, Promise<string>>;
 /** Clears the session and redirects to provider logout. In a component, call via useServerFn. */
-export declare const signOut: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, Promise<never>>;
+export declare const signOut: import("@tanstack/react-start").OptionalFetcher<undefined, z.ZodOptional<z.ZodObject<{
+    everywhere: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>, Promise<never>>;
+export {};

package/dist/functions.js

@@ -1,5 +1,7 @@
 import { createServerFn } from "@tanstack/react-start";
-import { signInOptionsSchema } from "@lpshanley/oidc-start-core/models";
+import { redirect } from "@tanstack/react-router";
+import { z } from "zod";
+import { sanitizeReturnPath, signInOptionsSchema } from "@lpshanley/oidc-start-core/models";
 // Server functions after WorkOS's server-functions.ts; bodies load lazily so
 // server code stays out of the client bundle.
 /** The signed-in user, or null. Never returns tokens. */
@@ -7,6 +9,33 @@ export const getAuth = createServerFn({ method: "GET" }).handler(async () => {
     const { getAuthBody } = await import("./functions.server.js");
     return getAuthBody();
 });
+function redirectToSignIn({ signInPath, returnPathname }, maxAge) {
+    const url = new URL(sanitizeReturnPath(signInPath), "https://sign-in.invalid");
+    url.searchParams.set("returnPathname", sanitizeReturnPath(returnPathname));
+    if (maxAge !== undefined)
+        url.searchParams.set("maxAge", String(maxAge));
+    throw redirect({ href: url.pathname + url.search + url.hash, reloadDocument: true });
+}
+/** Guard route navigation and supply a signed-in user to descendant routes. */
+export async function requireAuth(options) {
+    const { user } = await getAuth();
+    if (!user)
+        redirectToSignIn(options);
+    return { user };
+}
+const getRecentAuth = createServerFn({ method: "GET" })
+    .validator(z.object({ maxAge: z.int().nonnegative() }))
+    .handler(async ({ data }) => {
+    const { getRecentAuthBody } = await import("./functions.server.js");
+    return getRecentAuthBody(data.maxAge);
+});
+/** Guard navigation using the provider login time. Recheck inside sensitive actions. */
+export async function requireRecentAuth(options) {
+    const { user } = await getRecentAuth({ data: { maxAge: options.maxAge } });
+    if (!user)
+        redirectToSignIn(options, options.maxAge);
+    return { user };
+}
 /** An authorization URL; also queues the flow's verifier cookie. */
 export const getSignInUrl = createServerFn({ method: "GET" })
     .validator(signInOptionsSchema.optional())
@@ -15,7 +44,9 @@ export const getSignInUrl = createServerFn({ method: "GET" })
     return getSignInUrlBody(data);
 });
 /** Clears the session and redirects to provider logout. In a component, call via useServerFn. */
-export const signOut = createServerFn({ method: "POST" }).handler(async () => {
+export const signOut = createServerFn({ method: "POST" })
+    .validator(z.object({ everywhere: z.boolean().optional() }).optional())
+    .handler(async ({ data }) => {
     const { signOutBody } = await import("./functions.server.js");
-    return signOutBody();
+    return signOutBody(data?.everywhere);
 });

package/dist/functions.server.d.ts

@@ -1,4 +1,5 @@
 import type { AuthSession, SignInOptions } from "@lpshanley/oidc-start-core/models";
 export declare function getAuthBody(): AuthSession;
+export declare function getRecentAuthBody(maxAge: number): AuthSession;
 export declare function getSignInUrlBody(options?: SignInOptions): Promise<string>;
-export declare function signOutBody(): Promise<never>;
+export declare function signOutBody(everywhere?: boolean): Promise<never>;

package/dist/functions.server.js

@@ -1,11 +1,15 @@
 import { redirect } from "@tanstack/react-router";
 import { setResponseHeader } from "@tanstack/react-start/server";
 import { endSession } from "./sign-out.server.js";
-import { getOidcContext } from "./context.js";
+import { checkRecentAuth, getOidcContext } from "./context.js";
 export function getAuthBody() {
     setResponseHeader("Cache-Control", "no-store");
     return { user: getOidcContext().auth().user };
 }
+export function getRecentAuthBody(maxAge) {
+    const auth = getAuthBody();
+    return checkRecentAuth({ maxAge }).isStale ? { user: null } : auth;
+}
 export async function getSignInUrlBody(options) {
     const context = getOidcContext();
     const { url, setCookies } = await context.core.signIn(context.request, context.cookies, options, context.call);
@@ -13,8 +17,8 @@ export async function getSignInUrlBody(options) {
         context.appendSetCookie(line);
     return url;
 }
-export async function signOutBody() {
-    const result = await endSession();
+export async function signOutBody(everywhere = false) {
+    const result = await endSession(everywhere);
     if (result instanceof Response)
         throw result;
     throw redirect({ href: result, reloadDocument: true });

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export type { OidcCallContext, OidcErrorEvent, OidcMiddlewareOptions, } from "@l
 export { type OidcMiddlewareSetup, oidcMiddleware } from "./middleware.js";
 export { type CallbackRouteOptions, type SignInRouteOptions, handleBackchannelLogoutRoute, handleCallbackRoute, handleSignInRoute, handleSignOutRoute, } from "./routes.js";
 export type { CallbackErrorReason } from "@lpshanley/oidc-start-core";
+export { authErrorMessage } from "./auth-error.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "@lpshanley/oidc-start-core/models";
 export { oidcMiddleware } from "./middleware.js";
 export { handleBackchannelLogoutRoute, handleCallbackRoute, handleSignInRoute, handleSignOutRoute, } from "./routes.js";
+export { authErrorMessage } from "./auth-error.js";

package/dist/routes.server.js

@@ -18,10 +18,20 @@ function failure(request, options) {
 export async function signInRoute(request, options) {
     const context = getOidcContext();
     try {
+        const query = new URL(request.url).searchParams;
+        const requestedAge = query.get("maxAge");
+        let maxAge = options.maxAge;
+        if (requestedAge !== null) {
+            const age = Number(requestedAge);
+            if (!/^\d+$/.test(requestedAge) || !Number.isSafeInteger(age)) {
+                return new Response("Invalid maxAge.", { status: 400, headers: { "Cache-Control": "no-store" } });
+            }
+            maxAge = Math.min(maxAge ?? age, age);
+        }
         const { url, setCookies } = await context.core.signIn(request, context.cookies, {
-            returnPathname: new URL(request.url).searchParams.get("returnPathname") ?? options.returnPathname,
+            returnPathname: query.get("returnPathname") ?? options.returnPathname,
             loginHint: options.loginHint,
-            maxAge: options.maxAge,
+            maxAge,
             prompt: options.prompt,
         }, context.call);
         for (const line of setCookies)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpshanley/oidc-start-react",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@lpshanley/oidc-start-core": "0.3.0",
+    "@lpshanley/oidc-start-core": "0.4.1",
     "zod": "4.6.7"
   },
   "devDependencies": {