@lpshanley/oidc-start-react 0.0.0-stage → 0.1.0-next.1

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @lpshanley/oidc-start-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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)
+
+## 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.
+
+```sh
+npm install @lpshanley/oidc-start-react@next @lpshanley/oidc-start-core@next
+```
+
+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.
+
+| Provider setting | Local value |
+| --- | --- |
+| 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.
+
+```dotenv
+APP_ORIGIN=http://localhost:5173
+OIDC_ISSUER=https://id.example.com
+OIDC_CLIENT_ID=your-client-id
+OIDC_CLIENT_SECRET=your-client-secret
+# Paste the generated secret here before starting the app.
+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)
+
+## 2. Register the request middleware
+
+In `src/start.ts`, add Start’s CSRF middleware before the OIDC middleware. The first checks the origin of browser calls to server functions, including sign-out. The second resolves the session for the request and writes any refreshed cookies. The `createServerOnlyFn` wrapper keeps your `auth` instance out of the client bundle.
+
+```ts
+import { oidcMiddleware } from '@lpshanley/oidc-start-react'
+import { createCsrfMiddleware, createServerOnlyFn, createStart } from '@tanstack/react-start'
+import { auth } from './auth.server'
+
+const csrf = createCsrfMiddleware({ filter: ctx => ctx.handlerType === 'serverFn' })
+const oidc = oidcMiddleware({ core: createServerOnlyFn(() => auth) })
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [csrf, oidc],
+}))
+```
+
+## 3. Add the callback route
+
+Create `src/routes/callback.ts`. The handler checks the provider response, establishes the session, and redirects to the local path chosen at sign-in.
+
+```ts
+import { handleCallbackRoute } from '@lpshanley/oidc-start-react'
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/callback')({
+  server: { handlers: { GET: handleCallbackRoute() } },
+})
+```
+
+## 4. Connect the buttons
+
+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 { getAuth, getSignInUrl, signOut } from '@lpshanley/oidc-start-react/functions'
+import { createFileRoute } from '@tanstack/react-router'
+import { useServerFn } from '@tanstack/react-start'
+
+export const Route = createFileRoute('/')({
+  loader: () => getAuth(),
+  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>
+  }
+
+  return (
+    <main>
+      <p>Signed in as {displayName(user)}.</p>
+      <button onClick={() => signOutAndRedirect()}>Sign out</button>
+    </main>
+  )
+}
+```
+
+**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' } })`.
+
+## 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.
+
+| Method | Handler | When to use it |
+| --- | --- | --- |
+| GET | `handleSignInRoute()` | Link to sign-in. The optional `returnPathname` query parameter selects a local return path. |
+| 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 | `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.

package/dist/context.d.ts

@@ -0,0 +1,17 @@
+import type { OidcCallContext } from "@lpshanley/oidc-start-core/config";
+import type { OidcAuth, OidcCore } from "@lpshanley/oidc-start-core";
+import type { Session } from "@lpshanley/oidc-start-core";
+/** Request-scoped auth state that oidcMiddleware places in Start's context. */
+export type OidcContext = {
+    core: OidcCore;
+    request: Request;
+    cookies: Map<string, string>;
+    session: Session | null;
+    /** The caller's request context, when one was provided upstream. */
+    call: OidcCallContext | undefined;
+    auth: () => OidcAuth;
+    /** Queue a Set-Cookie line for the final response. */
+    appendSetCookie: (line: string) => void;
+};
+/** The current request's OIDC context; throws outside the middleware. */
+export declare function getOidcContext(): OidcContext;

package/dist/context.js

@@ -0,0 +1,16 @@
+import { getGlobalStartContext } from "@tanstack/react-start";
+const NOT_CONFIGURED = "OIDC middleware is not configured. Add oidcMiddleware() to requestMiddleware in src/start.ts.";
+function isOidcContext(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "core" in value &&
+        "auth" in value &&
+        "appendSetCookie" in value);
+}
+/** The current request's OIDC context; throws outside the middleware. */
+export function getOidcContext() {
+    const context = getGlobalStartContext();
+    if (!isOidcContext(context?.oidc))
+        throw new Error(NOT_CONFIGURED);
+    return context.oidc;
+}

package/dist/functions.d.ts

@@ -0,0 +1,17 @@
+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: {
+        sub: string;
+        email: string;
+        name: string | null;
+        picture?: string | null | undefined;
+        roles?: string[] | undefined;
+    } | 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>>;
+/** 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

@@ -0,0 +1,21 @@
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+// 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. */
+export const getAuth = createServerFn({ method: "GET" }).handler(async () => {
+    const { getAuthBody } = await import("./functions.server.js");
+    return getAuthBody();
+});
+/** An authorization URL; also queues the flow's verifier cookie. */
+export const getSignInUrl = createServerFn({ method: "GET" })
+    .validator(z.object({ returnPathname: z.string().optional() }).optional())
+    .handler(async ({ data }) => {
+    const { getSignInUrlBody } = await import("./functions.server.js");
+    return getSignInUrlBody(data?.returnPathname);
+});
+/** Clears the session and redirects to provider logout. In a component, call via useServerFn. */
+export const signOut = createServerFn({ method: "POST" }).handler(async () => {
+    const { signOutBody } = await import("./functions.server.js");
+    return signOutBody();
+});

package/dist/functions.server.d.ts

@@ -0,0 +1,4 @@
+import type { AuthSession } 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>;

package/dist/functions.server.js

@@ -0,0 +1,21 @@
+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";
+export function getAuthBody() {
+    setResponseHeader("Cache-Control", "no-store");
+    return { user: getOidcContext().auth().user };
+}
+export async function getSignInUrlBody(returnPathname) {
+    const context = getOidcContext();
+    const { url, setCookies } = await context.core.signIn(context.request, context.cookies, returnPathname, context.call);
+    for (const line of setCookies)
+        context.appendSetCookie(line);
+    return url;
+}
+export async function signOutBody() {
+    const result = await endSession();
+    if (result instanceof Response)
+        throw result;
+    throw redirect({ href: result, reloadDocument: true });
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,2 @@
+export { oidcMiddleware } from "./middleware.js";
+export { handleBackchannelLogoutRoute, handleCallbackRoute, handleSignInRoute, handleSignOutRoute, } from "./routes.js";

package/dist/middleware.d.ts

@@ -0,0 +1,19 @@
+import type { OidcMiddlewareOptions } from "@lpshanley/oidc-start-core/config";
+import type { OidcContext } from "./context.js";
+import type { OidcCore } from "@lpshanley/oidc-start-core";
+export type OidcMiddlewareSetup = OidcMiddlewareOptions | {
+    /**
+     * A core the app composed itself, resolved on first request from
+     * the context earlier request middleware provided.
+     */
+    core: (context: unknown) => OidcCore;
+};
+/**
+ * Request middleware after WorkOS's authkitMiddleware: resolves the session
+ * (refreshing or clearing it as needed), exposes it as `context.oidc`, and
+ * appends every queued Set-Cookie line to the final response. Create it once
+ * outside createStart so discovery and refresh state persist across requests.
+ */
+export declare function oidcMiddleware(setup: OidcMiddlewareSetup): import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, {
+    oidc: OidcContext;
+}>;

package/dist/middleware.js

@@ -0,0 +1,50 @@
+import { createMiddleware } from "@tanstack/react-start";
+/** `context.requestContext` from an earlier middleware, when it has the shape. */
+function callContext(context) {
+    const value = context
+        ?.requestContext;
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const { correlationId, deadline, signal } = value;
+    return {
+        ...(signal instanceof AbortSignal ? { signal } : {}),
+        correlationId: typeof correlationId === "string" ? correlationId : undefined,
+        deadline: typeof deadline === "number" ? deadline : undefined,
+    };
+}
+/**
+ * Request middleware after WorkOS's authkitMiddleware: resolves the session
+ * (refreshing or clearing it as needed), exposes it as `context.oidc`, and
+ * appends every queued Set-Cookie line to the final response. Create it once
+ * outside createStart so discovery and refresh state persist across requests.
+ */
+export function oidcMiddleware(setup) {
+    let core;
+    return createMiddleware({ type: "request" }).server(async ({ request, next, context }) => {
+        if ("core" in setup)
+            core ??= setup.core(context);
+        else {
+            const { createOidcCore } = await import("@lpshanley/oidc-start-core");
+            core ??= createOidcCore(setup);
+        }
+        const call = callContext(context);
+        const { cookies, session, setCookies } = await core.resolve(request, call);
+        const pending = [...setCookies];
+        const oidc = {
+            core,
+            request,
+            cookies,
+            session,
+            call,
+            auth: () => ({ user: session?.user ?? null }),
+            appendSetCookie: (line) => pending.push(line),
+        };
+        const result = await next({ context: { oidc } });
+        if (pending.length) {
+            // Start must receive its original response to serialize RPC redirects.
+            const { appendResponseHeader } = await import("@tanstack/react-start/server");
+            appendResponseHeader("Set-Cookie", pending);
+        }
+        return result;
+    });
+}

package/dist/routes.d.ts

@@ -0,0 +1,13 @@
+import type { CallbackRouteOptions } from "./routes.server.js";
+export type { CallbackRouteOptions };
+type RouteHandler = (args: {
+    request: Request;
+}) => Promise<Response>;
+/** GET: redirects to the provider; `?returnPathname=` sets the destination. */
+export declare function handleSignInRoute(options?: CallbackRouteOptions): 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. */
+export declare function handleBackchannelLogoutRoute(): RouteHandler;
+/** POST: clears the session and redirects to the provider logout. */
+export declare function handleSignOutRoute(): RouteHandler;

package/dist/routes.js

@@ -0,0 +1,30 @@
+// 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 }) => {
+        const { signInRoute } = await import("./routes.server.js");
+        return signInRoute(request, options);
+    };
+}
+/** GET: completes sign-in and redirects to the sanitized return path. */
+export function handleCallbackRoute(options = {}) {
+    return async ({ request }) => {
+        const { callbackRoute } = await import("./routes.server.js");
+        return callbackRoute(request, options);
+    };
+}
+/** POST: the provider's back-channel logout; ends the sessions its token names. */
+export function handleBackchannelLogoutRoute() {
+    return async ({ request }) => {
+        const { backchannelLogoutRoute } = await import("./routes.server.js");
+        return backchannelLogoutRoute(request);
+    };
+}
+/** POST: clears the session and redirects to the provider logout. */
+export function handleSignOutRoute() {
+    return async ({ request }) => {
+        const { signOutRoute } = await import("./routes.server.js");
+        return signOutRoute(request);
+    };
+}

package/dist/routes.server.d.ts

@@ -0,0 +1,10 @@
+export type CallbackRouteOptions = {
+    /** 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 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>;

package/dist/routes.server.js

@@ -0,0 +1,73 @@
+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 });
+    if (options.errorRedirectUrl) {
+        return redirectTo(new URL(options.errorRedirectUrl, request.url).toString(), 303);
+    }
+    return new Response("Authentication failed. Restart sign-in.", {
+        status: 400,
+        headers: { "Content-Type": "text/plain", "Cache-Control": "no-store" },
+    });
+}
+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);
+        for (const line of setCookies)
+            context.appendSetCookie(line);
+        return redirectTo(url, 307);
+    }
+    catch (error) {
+        return failure(request, options, "sign-in", error);
+    }
+}
+export async function callbackRoute(request, options) {
+    const context = getOidcContext();
+    const result = await context.core.callback(request, context.cookies, context.call);
+    for (const line of result.setCookies)
+        context.appendSetCookie(line);
+    if (result.ok)
+        return redirectTo(result.location, 307);
+    if (result.error instanceof SessionAccessDeniedError) {
+        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);
+}
+export async function signOutRoute(request) {
+    if (request.method !== "POST") {
+        return new Response("Method Not Allowed", {
+            status: 405,
+            headers: { Allow: "POST" },
+        });
+    }
+    const form = await request.formData().catch(() => undefined);
+    const result = await endSession(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" },
+        });
+    }
+    const context = getOidcContext();
+    const { status } = await context.core.backchannelLogout(request, context.call);
+    return new Response(null, {
+        status,
+        headers: { "Cache-Control": "no-store" },
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export { getOidcContext, type OidcContext } from "./context.js";

package/dist/server.js

@@ -0,0 +1 @@
+export { getOidcContext } from "./context.js";

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

@@ -0,0 +1 @@
+export declare function endSession(everywhere?: boolean): Promise<string | Response>;

package/dist/sign-out.server.js

@@ -0,0 +1,18 @@
+import { getOidcContext } from "./context.js";
+export async function endSession(everywhere = false) {
+    const context = getOidcContext();
+    let result;
+    try {
+        result = await context.core.signOut(context.request, context.cookies, context.session, context.call, everywhere);
+    }
+    catch (error) {
+        context.core.report({ operation: "end-session", error, context: context.call });
+        return new Response("Sign-out could not be recorded. Try again.", {
+            status: 503,
+            headers: { "Content-Type": "text/plain", "Cache-Control": "no-store" },
+        });
+    }
+    for (const line of result.setCookies)
+        context.appendSetCookie(line);
+    return result.location;
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lpshanley/oidc-start-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-next.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lpshanley/oidc-start.git",
+    "directory": "packages/react"
+  },
+  "description": "TanStack Start for React bindings for OpenID Connect",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./functions": {
+      "types": "./dist/functions.d.ts",
+      "import": "./dist/functions.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@lpshanley/oidc-start-core": "0.1.0-next.1",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3",
+    "vitest": "5.0.5",
+    "publint": "^0.3.0",
+    "@types/node": "22.20.2",
+    "@tanstack/react-router": "1.170.46",
+    "@tanstack/react-start": "1.169.4",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": "^1.170.44",
+    "@tanstack/react-start": "^1.169.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check-package": "publint --strict"
+  }
 }