@lpshanley/oidc-start-react 0.2.0 → 0.4.0

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,51 +64,158 @@ 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>
   )
 }
 ```
 
+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.
+
+### 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 that page, import `authErrorMessage` from `@lpshanley/oidc-start-react`. Read `auth_error` from the route's search parameters and render `<p role="alert">{authErrorMessage(auth_error)}</p>` when the parameter is present. The helper selects fixed messages and gives unknown values a generic retry message. Host access denials keep their 403 response.
+
+### 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

@@ -0,0 +1,48 @@
+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 AuthProvider({ auth, children }: {
+    auth: AuthSession;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<{
+    user: {
+        sub: string;
+        email: string;
+        name: string | null;
+        picture?: string | null | undefined;
+        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;
+        email: string;
+        name: string | null;
+        picture?: string | null | undefined;
+        roles?: string[] | undefined;
+    } | null;
+    hasRole: (role: string) => boolean;
+    signIn(options?: SignInOptions): Promise<void>;
+    signOut: {
+        (): Promise<never>;
+        (options?: {
+            everywhere?: boolean;
+        }): Promise<never>;
+    };
+};

package/dist/client.js

@@ -0,0 +1,39 @@
+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 AuthProvider({ auth, children }) {
+    return createElement(AuthContext.Provider, { value: auth }, children);
+}
+/** The user supplied by the current root loader, or null when signed out. */
+export function useUser() {
+    const auth = useContext(AuthContext);
+    if (!auth)
+        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,
+        hasRole: (role) => user !== null && hasRole(user, role),
+        async signIn(options) {
+            window.location.assign(await getSignInUrl({ data: options }));
+        },
+        signOut: signOutUser,
+    };
+}

package/dist/context.d.ts

@@ -15,3 +15,9 @@ export type OidcContext = {
 };
 /** The current request's OIDC context; throws outside the middleware. */
 export declare function getOidcContext(): OidcContext;
+/** Check the resolved session inside the server handler that performs a sensitive action. */
+export declare function checkRecentAuth({ maxAge }: {
+    maxAge: number;
+}): {
+    isStale: boolean;
+};

package/dist/context.js

@@ -14,3 +14,14 @@ export function getOidcContext() {
         throw new Error(NOT_CONFIGURED);
     return context.oidc;
 }
+/** Check the resolved session inside the server handler that performs a sensitive action. */
+export function checkRecentAuth({ maxAge }) {
+    if (!Number.isSafeInteger(maxAge) || maxAge < 0) {
+        throw new RangeError("maxAge must be a nonnegative integer in seconds");
+    }
+    const authTime = getOidcContext().session?.authTime;
+    if (authTime === undefined)
+        return { isStale: true };
+    const age = Math.floor(Date.now() / 1000) - authTime;
+    return { isStale: !(age >= 0 && age <= maxAge) };
+}

package/dist/functions.d.ts

@@ -9,9 +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, 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";
+    }>>;
 }, 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 { 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,15 +9,44 @@ 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(z.object({ returnPathname: z.string().optional() }).optional())
+    .validator(signInOptionsSchema.optional())
     .handler(async ({ data }) => {
     const { getSignInUrlBody } = await import("./functions.server.js");
-    return getSignInUrlBody(data?.returnPathname);
+    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 } from "@lpshanley/oidc-start-core/models";
+import type { AuthSession, SignInOptions } from "@lpshanley/oidc-start-core/models";
 export declare function getAuthBody(): AuthSession;
-export declare function getSignInUrlBody(returnPathname?: string): Promise<string>;
-export declare function signOutBody(): Promise<never>;
+export declare function getRecentAuthBody(maxAge: number): AuthSession;
+export declare function getSignInUrlBody(options?: SignInOptions): Promise<string>;
+export declare function signOutBody(everywhere?: boolean): Promise<never>;

package/dist/functions.server.js

@@ -1,20 +1,24 @@
 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 async function getSignInUrlBody(returnPathname) {
+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, returnPathname, context.call);
+    const { url, setCookies } = await context.core.signIn(context.request, context.cookies, options, context.call);
     for (const line of setCookies)
         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

@@ -1,4 +1,6 @@
 export * from "@lpshanley/oidc-start-core/models";
 export type { OidcCallContext, OidcErrorEvent, OidcMiddlewareOptions, } from "@lpshanley/oidc-start-core/config";
 export { type OidcMiddlewareSetup, oidcMiddleware } from "./middleware.js";
-export { type CallbackRouteOptions, handleBackchannelLogoutRoute, handleCallbackRoute, handleSignInRoute, handleSignOutRoute, } from "./routes.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.d.ts

@@ -1,10 +1,10 @@
-import type { CallbackRouteOptions } from "./routes.server.js";
-export type { CallbackRouteOptions };
+import type { CallbackRouteOptions, SignInRouteOptions } from "./routes.server.js";
+export type { CallbackRouteOptions, SignInRouteOptions };
 type RouteHandler = (args: {
     request: Request;
 }) => Promise<Response>;
 /** GET: redirects to the provider; `?returnPathname=` sets the destination. */
-export declare function handleSignInRoute(options?: CallbackRouteOptions): RouteHandler;
+export declare function handleSignInRoute(options?: SignInRouteOptions): RouteHandler;
 /** GET: completes sign-in and redirects to the sanitized return path. */
 export declare function handleCallbackRoute(options?: CallbackRouteOptions): RouteHandler;
 /** POST: the provider's back-channel logout; ends the sessions its token names. */

package/dist/routes.server.d.ts

@@ -1,10 +1,21 @@
-export type CallbackRouteOptions = {
+import type { CallbackErrorReason } from "@lpshanley/oidc-start-core";
+import type { SignInOptions } from "@lpshanley/oidc-start-core/models";
+type FailureOptions = {
     /** Where to send the browser when sign-in fails. Defaults to a 400. */
     errorRedirectUrl?: string;
     /** Shown when the host denies a session to an authenticated user. */
     accessDeniedMessage?: string;
 };
-export declare function signInRoute(request: Request, options: CallbackRouteOptions): Promise<Response>;
+export type SignInRouteOptions = FailureOptions & SignInOptions;
+export type CallbackRouteOptions = FailureOptions & {
+    /** Customize callback failures after the verifier cookie has been queued for cleanup. */
+    onError?: (failure: {
+        reason: CallbackErrorReason;
+        request: Request;
+    }) => Response | Promise<Response>;
+};
+export declare function signInRoute(request: Request, options: SignInRouteOptions): Promise<Response>;
 export declare function callbackRoute(request: Request, options: CallbackRouteOptions): Promise<Response>;
 export declare function signOutRoute(request: Request): Promise<Response>;
 export declare function backchannelLogoutRoute(request: Request): Promise<Response>;
+export {};

package/dist/routes.server.js

@@ -1,16 +1,12 @@
 import { endSession } from "./sign-out.server.js";
 import { getOidcContext } from "./context.js";
-import { SessionAccessDeniedError } from "@lpshanley/oidc-start-core";
 function redirectTo(location, status) {
     return new Response(null, {
         status,
         headers: { Location: location, "Cache-Control": "no-store" },
     });
 }
-function failure(request, options, operation, error) {
-    // Provider error details go to onError, never into the response.
-    const context = getOidcContext();
-    context.core.report({ operation, error, context: context.call });
+function failure(request, options) {
     if (options.errorRedirectUrl) {
         return redirectTo(new URL(options.errorRedirectUrl, request.url).toString(), 303);
     }
@@ -22,13 +18,29 @@ function failure(request, options, operation, error) {
 export async function signInRoute(request, options) {
     const context = getOidcContext();
     try {
-        const { url, setCookies } = await context.core.signIn(request, context.cookies, new URL(request.url).searchParams.get("returnPathname"), context.call);
+        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: query.get("returnPathname") ?? options.returnPathname,
+            loginHint: options.loginHint,
+            maxAge,
+            prompt: options.prompt,
+        }, context.call);
         for (const line of setCookies)
             context.appendSetCookie(line);
         return redirectTo(url, 307);
     }
     catch (error) {
-        return failure(request, options, "sign-in", error);
+        context.core.report({ operation: "sign-in", error, context: context.call });
+        return failure(request, options);
     }
 }
 export async function callbackRoute(request, options) {
@@ -38,13 +50,16 @@ export async function callbackRoute(request, options) {
         context.appendSetCookie(line);
     if (result.ok)
         return redirectTo(result.location, 307);
-    if (result.error instanceof SessionAccessDeniedError) {
+    if (result.reason === "session_access_denied") {
         return new Response(options.accessDeniedMessage ?? "Your account does not have access.", {
             status: 403,
             headers: { "Content-Type": "text/plain", "Cache-Control": "no-store" },
         });
     }
-    return failure(request, options, "callback", result.error);
+    context.core.report({ operation: "callback", error: result.error, context: context.call });
+    if (options.onError)
+        return options.onError({ reason: result.reason, request });
+    return failure(request, options);
 }
 export async function signOutRoute(request) {
     if (request.method !== "POST") {

package/dist/server.d.ts

@@ -1,2 +1,2 @@
 export * from "@lpshanley/oidc-start-core";
-export { getOidcContext, type OidcContext } from "./context.js";
+export { checkRecentAuth, getOidcContext, type OidcContext } from "./context.js";

package/dist/server.js

@@ -1,2 +1,2 @@
 export * from "@lpshanley/oidc-start-core";
-export { getOidcContext } from "./context.js";
+export { checkRecentAuth, getOidcContext } from "./context.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpshanley/oidc-start-react",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,6 +16,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./functions": {
       "types": "./dist/functions.d.ts",
       "import": "./dist/functions.js"
@@ -36,7 +40,7 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@lpshanley/oidc-start-core": "0.2.0",
+    "@lpshanley/oidc-start-core": "0.4.0",
     "zod": "4.6.7"
   },
   "devDependencies": {
@@ -53,7 +57,13 @@
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.44",
-    "@tanstack/react-start": "^1.169.2"
+    "@tanstack/react-start": "^1.169.2",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",