@lpshanley/oidc-start-react 0.4.2 → 0.5.0

package/README.md

@@ -21,7 +21,7 @@ Register a confidential web client with your OIDC provider. If your app runs at
 | Sign-in redirect URI | `http://localhost:5173/callback` |
 | Post-logout redirect URI | `http://localhost:5173/` |
 
-Set these values in your **server environment**. Generate `SESSION_SECRET` once with `openssl rand -hex 32` and reuse it across server instances. Your provider must supply the account’s email in the ID token or through UserInfo.
+Set these values in your **server environment**. Generate `SESSION_SECRET` once with `openssl rand -hex 32` and reuse it across server instances. Email is optional. Use `displayName(user)` for a name, email, or neutral account label.
 
 ```dotenv
 APP_ORIGIN=http://localhost:5173
@@ -32,7 +32,7 @@ OIDC_CLIENT_SECRET=your-client-secret
 SESSION_SECRET=
 ```
 
-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)
+Import `createOidcCore` and the `SessionRegistry` 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 active sessions in memory. For deployment, set `allowSession` to your access policy and use a durable session registry 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
 
@@ -114,7 +114,7 @@ function Home() {
 }
 ```
 
-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.
+Call `signOut()` for the current session or `signOut({ everywhere: true })` for all of this user's sessions in this app. Use `signOut({ providerLogout: false })` to end only the application session. These options use the same CSRF-protected POST server function. If the session registry 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.
 
@@ -255,3 +255,7 @@ A guest or stale session is sent to the local sign-in endpoint with the same `ma
 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.
+
+## Upgrading to 0.5
+
+See the [migration guide](https://github.com/lpshanley/oidc-start/blob/main/docs/migration-0.5.md). `getAuth` and guards distinguish absent sessions from denied admission (403) and temporary authentication outages (503); only an absent session starts automatic sign-in. User email is optional and issuer identity is explicit.

package/dist/client.d.ts

@@ -1,23 +1,25 @@
 import { type ReactElement, type ReactNode } from "react";
-import { type AuthSession, type SignInOptions } from "@lpshanley/oidc-start-core/models";
+import { type AuthSession, type SignInOptions, type SignOutOptions } 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: {
+        issuer: string;
         sub: string;
-        email: string;
         name: string | null;
+        email?: string | undefined;
         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(): {
+    issuer: string;
     sub: string;
-    email: string;
     name: string | null;
+    email?: string | undefined;
     picture?: string | null | undefined;
     roles?: string[] | undefined;
 } | null;
@@ -31,9 +33,10 @@ export declare function SignedOut({ children }: {
 }): ReactElement | null;
 export declare function useAuth(): {
     user: {
+        issuer: string;
         sub: string;
-        email: string;
         name: string | null;
+        email?: string | undefined;
         picture?: string | null | undefined;
         roles?: string[] | undefined;
     } | null;
@@ -41,8 +44,6 @@ export declare function useAuth(): {
     signIn(options?: SignInOptions): Promise<void>;
     signOut: {
         (): Promise<never>;
-        (options?: {
-            everywhere?: boolean;
-        }): Promise<never>;
+        (options?: SignOutOptions): Promise<never>;
     };
 };

package/dist/client.js

@@ -26,7 +26,10 @@ export function useAuth() {
     const user = useUser();
     const signOutAndRedirect = useServerFn(signOut);
     function signOutUser(options) {
-        return signOutAndRedirect({ data: { everywhere: options?.everywhere } });
+        return signOutAndRedirect({ data: options ? {
+                everywhere: options.everywhere === true,
+                providerLogout: options.providerLogout,
+            } : undefined });
     }
     return {
         user,

package/dist/context.d.ts

@@ -12,6 +12,8 @@ export type OidcContext = {
     auth: () => OidcAuth;
     /** Queue a Set-Cookie line for the final response. */
     appendSetCookie: (line: string) => void;
+    /** Drop cookie writes from resolving the incoming session when a handler supersedes it. */
+    discardSessionUpdates?: () => void;
 };
 /** The current request's OIDC context; throws outside the middleware. */
 export declare function getOidcContext(): OidcContext;

package/dist/functions.d.ts

@@ -2,9 +2,10 @@ 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: {
+        issuer: string;
         sub: string;
-        email: string;
         name: string | null;
+        email?: string | undefined;
         picture?: string | null | undefined;
         roles?: string[] | undefined;
     } | null;
@@ -18,9 +19,10 @@ type GuardOptions = {
 /** Guard route navigation and supply a signed-in user to descendant routes. */
 export declare function requireAuth(options: GuardOptions): Promise<{
     user: {
+        issuer: string;
         sub: string;
-        email: string;
         name: string | null;
+        email?: string | undefined;
         picture?: string | null | undefined;
         roles?: string[] | undefined;
     };
@@ -30,9 +32,10 @@ export declare function requireRecentAuth(options: GuardOptions & {
     maxAge: number;
 }): Promise<{
     user: {
+        issuer: string;
         sub: string;
-        email: string;
         name: string | null;
+        email?: string | undefined;
         picture?: string | null | undefined;
         roles?: string[] | undefined;
     };
@@ -42,15 +45,11 @@ export declare const getSignInUrl: import("@tanstack/react-start").OptionalFetch
     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";
-    }>>;
+    prompt: z.ZodOptional<z.ZodString>;
 }, 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, z.ZodOptional<z.ZodObject<{
     everywhere: z.ZodOptional<z.ZodBoolean>;
+    providerLogout: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>>, Promise<never>>;
 export {};

package/dist/functions.js

@@ -1,7 +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";
+import { sanitizeReturnPath, signInOptionsSchema, signOutOptionsSchema } 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. */
@@ -45,8 +45,8 @@ export const getSignInUrl = createServerFn({ method: "GET" })
 });
 /** Clears the session and redirects to provider logout. In a component, call via useServerFn. */
 export const signOut = createServerFn({ method: "POST" })
-    .validator(z.object({ everywhere: z.boolean().optional() }).optional())
+    .validator(signOutOptionsSchema.optional())
     .handler(async ({ data }) => {
     const { signOutBody } = await import("./functions.server.js");
-    return signOutBody(data?.everywhere);
+    return signOutBody(data);
 });

package/dist/functions.server.d.ts

@@ -1,5 +1,5 @@
-import type { AuthSession, SignInOptions } from "@lpshanley/oidc-start-core/models";
+import type { AuthSession, SignInOptions, SignOutOptions } 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(everywhere?: boolean): Promise<never>;
+export declare function signOutBody(options?: SignOutOptions): Promise<never>;

package/dist/functions.server.js

@@ -1,10 +1,19 @@
 import { redirect } from "@tanstack/react-router";
-import { setResponseHeader } from "@tanstack/react-start/server";
+import { setResponseHeader, setResponseStatus } from "@tanstack/react-start/server";
 import { endSession } from "./sign-out.server.js";
 import { checkRecentAuth, getOidcContext } from "./context.js";
 export function getAuthBody() {
     setResponseHeader("Cache-Control", "no-store");
-    return { user: getOidcContext().auth().user };
+    const auth = getOidcContext().auth();
+    if (auth.status === "denied" || auth.status === "unavailable") {
+        const status = auth.status === "denied" ? 403 : 503;
+        setResponseStatus(status);
+        // Loader errors must serialize during SSR. A thrown Response cannot.
+        throw Object.assign(new Error(auth.status === "denied"
+            ? "Your account does not have access."
+            : "Authentication is temporarily unavailable. Try again."), { status });
+    }
+    return { user: auth.user };
 }
 export function getRecentAuthBody(maxAge) {
     const auth = getAuthBody();
@@ -17,8 +26,8 @@ export async function getSignInUrlBody(options) {
         context.appendSetCookie(line);
     return url;
 }
-export async function signOutBody(everywhere = false) {
-    const result = await endSession(everywhere);
+export async function signOutBody(options = {}) {
+    const result = await endSession(options);
     if (result instanceof Response)
         throw result;
     throw redirect({ href: result, reloadDocument: true });

package/dist/middleware.js

@@ -28,18 +28,21 @@ export function oidcMiddleware(setup) {
             core ??= createOidcCore(setup);
         }
         const call = callContext(context);
-        const { cookies, session, setCookies } = await core.resolve(request, call);
-        const pending = [...setCookies];
+        const { cookies, session, setCookies, status, reason } = await core.resolve(request, call);
+        let sessionUpdates = setCookies;
+        const appended = [];
         const oidc = {
             core,
             request,
             cookies,
             session,
             call,
-            auth: () => ({ user: session?.user ?? null }),
-            appendSetCookie: (line) => pending.push(line),
+            auth: () => ({ user: session?.user ?? null, status, reason }),
+            appendSetCookie: (line) => appended.push(line),
+            discardSessionUpdates: () => { sessionUpdates = []; },
         };
         const result = await next({ context: { oidc } });
+        const pending = [...sessionUpdates, ...appended];
         if (pending.length) {
             // Start must receive its original response to serialize RPC redirects.
             const { appendResponseHeader } = await import("@tanstack/react-start/server");

package/dist/routes.d.ts

@@ -1,3 +1,4 @@
+import type { SignOutOptions } from "@lpshanley/oidc-start-core/models";
 import type { CallbackRouteOptions, SignInRouteOptions } from "./routes.server.js";
 export type { CallbackRouteOptions, SignInRouteOptions };
 type RouteHandler = (args: {
@@ -10,4 +11,4 @@ export declare function handleCallbackRoute(options?: CallbackRouteOptions): Rou
 /** POST: the provider's back-channel logout; ends the sessions its token names. */
 export declare function handleBackchannelLogoutRoute(): RouteHandler;
 /** POST: clears the session and redirects to the provider logout. */
-export declare function handleSignOutRoute(): RouteHandler;
+export declare function handleSignOutRoute(options?: SignOutOptions): RouteHandler;

package/dist/routes.js

@@ -1,5 +1,3 @@
-// Server route handler factories, after WorkOS's handleCallbackRoute. They run
-// behind oidcMiddleware, which applies the cookies they queue.
 /** GET: redirects to the provider; `?returnPathname=` sets the destination. */
 export function handleSignInRoute(options = {}) {
     return async ({ request }) => {
@@ -22,9 +20,9 @@ export function handleBackchannelLogoutRoute() {
     };
 }
 /** POST: clears the session and redirects to the provider logout. */
-export function handleSignOutRoute() {
+export function handleSignOutRoute(options = {}) {
     return async ({ request }) => {
         const { signOutRoute } = await import("./routes.server.js");
-        return signOutRoute(request);
+        return signOutRoute(request, options);
     };
 }

package/dist/routes.server.d.ts

@@ -1,5 +1,5 @@
 import type { CallbackErrorReason } from "@lpshanley/oidc-start-core";
-import type { SignInOptions } from "@lpshanley/oidc-start-core/models";
+import type { SignInOptions, SignOutOptions } from "@lpshanley/oidc-start-core/models";
 type FailureOptions = {
     /** Where to send the browser when sign-in fails. Defaults to a 400. */
     errorRedirectUrl?: string;
@@ -16,6 +16,6 @@ export type CallbackRouteOptions = FailureOptions & {
 };
 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 signOutRoute(request: Request, options?: SignOutOptions): Promise<Response>;
 export declare function backchannelLogoutRoute(request: Request): Promise<Response>;
 export {};

package/dist/routes.server.js

@@ -46,6 +46,8 @@ export async function signInRoute(request, options) {
 export async function callbackRoute(request, options) {
     const context = getOidcContext();
     const result = await context.core.callback(request, context.cookies, context.call);
+    if (result.ok)
+        context.discardSessionUpdates?.();
     for (const line of result.setCookies)
         context.appendSetCookie(line);
     if (result.ok)
@@ -56,27 +58,27 @@ export async function callbackRoute(request, options) {
             headers: { "Content-Type": "text/plain", "Cache-Control": "no-store" },
         });
     }
-    context.core.report({ operation: "callback", error: result.error, context: context.call });
+    context.core.report({ operation: "callback", reason: result.reason, 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) {
+export async function signOutRoute(request, options = {}) {
     if (request.method !== "POST") {
         return new Response("Method Not Allowed", {
             status: 405,
-            headers: { Allow: "POST" },
+            headers: { Allow: "POST", "Cache-Control": "no-store" },
         });
     }
     const form = await request.formData().catch(() => undefined);
-    const result = await endSession(form?.get("everywhere") === "1");
+    const result = await endSession({ ...options, everywhere: options.everywhere || form?.get("everywhere") === "1" });
     return result instanceof Response ? result : redirectTo(result, 303);
 }
 export async function backchannelLogoutRoute(request) {
     if (request.method !== "POST") {
         return new Response("Method Not Allowed", {
             status: 405,
-            headers: { Allow: "POST" },
+            headers: { Allow: "POST", "Cache-Control": "no-store" },
         });
     }
     const context = getOidcContext();

package/dist/sign-out.server.d.ts

@@ -1 +1,2 @@
-export declare function endSession(everywhere?: boolean): Promise<string | Response>;
+import type { SignOutOptions } from "@lpshanley/oidc-start-core/models";
+export declare function endSession(options?: SignOutOptions): Promise<string | Response>;

package/dist/sign-out.server.js

@@ -1,9 +1,12 @@
 import { getOidcContext } from "./context.js";
-export async function endSession(everywhere = false) {
+export async function endSession(options = {}) {
     const context = getOidcContext();
+    // A failed revocation must leave the incoming cookie available for retry.
+    // A successful sign-out supplies all deletions for that same incoming jar.
+    context.discardSessionUpdates?.();
     let result;
     try {
-        result = await context.core.signOut(context.request, context.cookies, context.session, context.call, everywhere);
+        result = await context.core.signOut(context.request, context.cookies, context.session, context.call, options);
     }
     catch (error) {
         context.core.report({ operation: "end-session", error, context: context.call });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpshanley/oidc-start-react",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@lpshanley/oidc-start-core": "0.4.2",
+    "@lpshanley/oidc-start-core": "0.5.0",
     "zod": "4.6.7"
   },
   "devDependencies": {
@@ -66,7 +66,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "check-package": "publint --strict"