@lpshanley/oidc-start-react 0.1.0 → 0.3.0

package/README.md

@@ -8,10 +8,10 @@ For multi-replica deployment, see the [production guide](https://github.com/lpsh
 
 ## 1. Install and configure the server
 
-Use Node.js 22.12 or newer. Your app supplies `@tanstack/react-start@^1.169.2` and `@tanstack/react-router@^1.170.44`. Install both OIDC packages because your app imports the core directly.
+Use Node.js 22.12 or newer. Your app supplies `@tanstack/react-start@^1.169.2` and `@tanstack/react-router@^1.170.44`. Install the React adapter. It brings in the OIDC core as a dependency.
 
 ```sh
-npm install @lpshanley/oidc-start-react @lpshanley/oidc-start-core
+npm install @lpshanley/oidc-start-react
 ```
 
 Register a confidential web client with your OIDC provider. If your app runs at `http://localhost:5173`, register these exact URLs. Use your public HTTPS origin in production.
@@ -32,7 +32,7 @@ OIDC_CLIENT_SECRET=your-client-secret
 SESSION_SECRET=
 ```
 
-For local development, copy the example’s `auth.server.ts` into `src/auth.server.ts`. It exports an `auth` instance configured with `callbackPath: '/callback'` and `postLogoutPath: '/'`. The example admits any authenticated user and keeps revocations in memory. For deployment, set `allowSession` to your access policy and use a durable revocation store shared by all instances. [Copy auth.server.ts](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/auth.server.ts) · [Core configuration and storage](https://www.npmjs.com/package/@lpshanley/oidc-start-core)
+Import `createOidcCore` and the `SessionRevocations` type from `@lpshanley/oidc-start-react/server` in your server module. For local development, copy the example’s `auth.server.ts` into `src/auth.server.ts`. It exports an `auth` instance configured with `callbackPath: '/callback'` and `postLogoutPath: '/'`. The example admits any authenticated user and keeps revocations in memory. For deployment, set `allowSession` to your access policy and use a durable revocation store shared by all instances. [Copy auth.server.ts](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/auth.server.ts) · [Core configuration and storage](https://www.npmjs.com/package/@lpshanley/oidc-start-core)
 
 ## 2. Register the request middleware
 
@@ -69,7 +69,7 @@ export const Route = createFileRoute('/callback')({
 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.
 
 ```tsx
-import { displayName } from '@lpshanley/oidc-start-core/models'
+import { displayName } from '@lpshanley/oidc-start-react'
 import { getAuth, getSignInUrl, signOut } from '@lpshanley/oidc-start-react/functions'
 import { createFileRoute } from '@tanstack/react-router'
 import { useServerFn } from '@tanstack/react-start'
@@ -96,10 +96,14 @@ function Home() {
 }
 ```
 
+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)
+
 **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' } })`.
 
+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.
@@ -112,3 +116,13 @@ The buttons above use server functions. If you prefer ordinary links and forms,
 | 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.
+
+### 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.
+
+### Require a recent login
+
+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/client.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import type { AuthSession, 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 }: {
+    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>>;
+export declare function useAuth(): {
+    user: {
+        sub: string;
+        email: string;
+        name: string | null;
+        picture?: string | null | undefined;
+        roles?: string[] | undefined;
+    } | null;
+    signIn(options?: SignInOptions): Promise<void>;
+    signOut: () => Promise<never>;
+};

package/dist/client.js

@@ -0,0 +1,21 @@
+import { createContext, createElement, useContext } from "react";
+import { useServerFn } from "@tanstack/react-start";
+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 }) {
+    return createElement(AuthContext.Provider, { value: auth }, children);
+}
+export function useAuth() {
+    const auth = useContext(AuthContext);
+    const signOutAndRedirect = useServerFn(signOut);
+    if (!auth)
+        throw new Error("useAuth() requires an OidcAuthProvider.");
+    return {
+        user: auth.user,
+        async signIn(options) {
+            window.location.assign(await getSignInUrl({ data: options }));
+        },
+        signOut: () => signOutAndRedirect(),
+    };
+}

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

@@ -1,4 +1,3 @@
-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: {
@@ -10,8 +9,16 @@ export declare const getAuth: import("@tanstack/react-start").OptionalFetcher<un
     } | null;
 }>>;
 /** 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>;
-}, z.core.$strip>>, Promise<string>>;
+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<{
+        none: "none";
+        login: "login";
+        consent: "consent";
+        select_account: "select_account";
+    }>>;
+}, import("zod/v4/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>>;

package/dist/functions.js

@@ -1,5 +1,5 @@
 import { createServerFn } from "@tanstack/react-start";
-import { z } from "zod";
+import { 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. */
@@ -9,10 +9,10 @@ export const getAuth = createServerFn({ method: "GET" }).handler(async () => {
 });
 /** 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 () => {

package/dist/functions.server.d.ts

@@ -1,4 +1,4 @@
-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 getSignInUrlBody(options?: SignInOptions): Promise<string>;
 export declare function signOutBody(): Promise<never>;

package/dist/functions.server.js

@@ -6,9 +6,9 @@ export function getAuthBody() {
     setResponseHeader("Cache-Control", "no-store");
     return { user: getOidcContext().auth().user };
 }
-export async function getSignInUrlBody(returnPathname) {
+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;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+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";

package/dist/index.js

@@ -1,2 +1,3 @@
+export * from "@lpshanley/oidc-start-core/models";
 export { oidcMiddleware } from "./middleware.js";
 export { handleBackchannelLogoutRoute, handleCallbackRoute, handleSignInRoute, handleSignOutRoute, } from "./routes.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,19 @@ 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 { url, setCookies } = await context.core.signIn(request, context.cookies, {
+            returnPathname: new URL(request.url).searchParams.get("returnPathname") ?? options.returnPathname,
+            loginHint: options.loginHint,
+            maxAge: options.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 +40,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 +1,2 @@
-export { getOidcContext, type OidcContext } from "./context.js";
+export * from "@lpshanley/oidc-start-core";
+export { checkRecentAuth, getOidcContext, type OidcContext } from "./context.js";

package/dist/server.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpshanley/oidc-start-react",
-  "version": "0.1.0",
+  "version": "0.3.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.1.0",
+    "@lpshanley/oidc-start-core": "0.3.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",