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

package/README.md

@@ -1,3 +1,18 @@
-# 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.
+TanStack Start for React bindings for `@lpshanley/oidc-start-core`. Install alongside the application's React Start and React Router packages.
+
+In a custom `src/start.ts`, register `createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === 'serverFn' })` from `@tanstack/react-start` before `oidcMiddleware({ core: () => auth })` in `requestMiddleware`. This restores Start's same-origin check for browser RPCs. Here `auth` is the server-side core configured by the host. You can also read a core from the context supplied by earlier server middleware. In a file shared with the browser, load server-only composition inside the server boundary.
+
+```ts
+import { createFileRoute } from '@tanstack/react-router'
+import { handleCallbackRoute } from '@lpshanley/oidc-start-react'
+
+export const Route = createFileRoute('/auth/callback')({
+  server: { handlers: { GET: handleCallbackRoute() } },
+})
+```
+
+Register `handleSignInRoute()` on GET and `handleSignOutRoute()` and `handleBackchannelLogoutRoute()` on POST. Add `server.middleware: [createCsrfMiddleware()]` to the browser sign-out route as well. The provider posts signed tokens to the separate back-channel route without a browser Origin header, so leave that route outside the browser CSRF check.
+
+Import `getAuth`, `getSignInUrl` and `signOut` from `@lpshanley/oidc-start-react/functions`. In a React component, bind `const signOutAndRedirect = useServerFn(signOut)` from TanStack Start and call it in the click handler so the router follows the logout redirect. Use `getOidcContext` from `@lpshanley/oidc-start-react/server` inside server handlers. The adapter ships ESM with its server-function declarations intact for the consuming app's Start compiler.

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.0",
+  "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.0",
+    "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"
+  }
 }