@lpshanley/oidc-start-core 0.1.0-next.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Shanley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,12 +4,14 @@ OpenID Connect sign-in for Node.js servers. Give the core a standard `Request` a
 
 Building a TanStack Start app? The React adapter connects the core to Start’s request middleware, routes, and server functions. [TanStack Start quickstart](https://www.npmjs.com/package/@lpshanley/oidc-start-react)
 
+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).
+
 ## Install and register your app
 
-Use Node.js 22.12 or newer with ES modules. Install the current prerelease from npm.
+Use Node.js 22.12 or newer with ES modules. Install the package from npm.
 
 ```sh
-npm install @lpshanley/oidc-start-core@next
+npm install @lpshanley/oidc-start-core
 ```
 
 Register a **confidential web client** with your OIDC provider. For the example below, register `http://localhost:5173/callback` as the sign-in redirect URI and `http://localhost:5173/` as the post-logout redirect URI. In production, use your app’s public HTTPS origin for both.
@@ -21,7 +23,7 @@ Register a **confidential web client** with your OIDC provider. For the example
 | `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | The credentials issued to your web client. |
 | `SESSION_SECRET` | Generate once with `openssl rand -hex 32`. Keep the same secret across restarts and server instances. |
 | `OIDC_SCOPES` | Optional. Defaults to `openid profile email offline_access`. The provider must supply an email in the ID token or through UserInfo. |
-| `OIDC_ROLES_CLAIM` | Optional. Defaults to `roles`. Set this to the claim your provider uses if your policy checks roles. |
+| `OIDC_ROLES_CLAIM` | Optional. Defaults to `roles`. If the ID token omits this claim, the core checks UserInfo when the provider advertises it. Without either source, your policy receives an empty role list. |
 
 ## Create the core
 
@@ -52,6 +54,7 @@ Mount these handlers at `GET /sign-in` and `GET /callback` in your server. The f
 
 ```ts
 import { SessionAccessDeniedError } from '@lpshanley/oidc-start-core'
+import { isAuthorizationDenied } from '@lpshanley/oidc-start-core/provider'
 import { auth } from './auth.server.js'
 
 function authHeaders(cookies: string[]) {
@@ -73,6 +76,9 @@ export async function callback(request: Request) {
   const result = await auth.callback(request, cookies)
   const headers = authHeaders([...setCookies, ...result.setCookies])
   if (!result.ok) {
+    if (isAuthorizationDenied(result.error)) {
+      return new Response('Authorization was declined.', { status: 403, headers })
+    }
     const denied = result.error instanceof SessionAccessDeniedError
     return new Response(denied ? 'Access denied.' : 'Please sign in again.', {
       status: denied ? 403 : 400, headers,
@@ -85,6 +91,8 @@ export async function callback(request: Request) {
 
 On an ordinary request, `const { session, setCookies } = await auth.resolve(request)` gives you `session?.user`. Forward **each** returned `Set-Cookie` header separately, even on a signed-out response. A read can refresh a session or clear an expired cookie. Keep the full session on the server because it contains provider tokens. Browser code can use `AuthUser`, `displayName`, and `hasRole` from `@lpshanley/oidc-start-core/models`.
 
+If you use `provider.exchangeCode()` directly, import `isAuthorizationDenied` from `@lpshanley/oidc-start-core/provider` and pass it the caught error. It recognizes the provider’s `access_denied` response across bundles. Other responses, such as `login_required`, and network failures return `false`.
+
 ## End a session
 
 For browser sign-out, use a same-origin, CSRF-protected POST handler. Resolve the request, pass its `cookies` and `session` to `auth.signOut(request, cookies, session)`, append both sets of cookies as above, and redirect with **303** to the returned `location`. If recording the revocation throws, return a retryable error. The default session lasts up to 14 days and expires after 12 hours of inactivity.

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { AuthUser } from "./models.js";
+import type { SessionRefreshCoordinator } from "./refresh.js";
 import type { SessionRevocations } from "./revocation.js";
 export type AuthEnvironment = Readonly<Record<string, string | undefined>>;
 export type AuthEnvironmentProvider = () => AuthEnvironment;
@@ -41,7 +42,7 @@ export type OidcCallContext = {
 };
 /** A failure the library recovered from or reported to the browser. */
 export type OidcErrorEvent = {
-    operation: "sign-in" | "callback" | "refresh" | "end-session" | "token-revocation" | "backchannel-logout";
+    operation: "sign-in" | "callback" | "refresh" | "end-session" | "revocation-read" | "token-revocation" | "backchannel-logout";
     error: unknown;
     context?: OidcCallContext;
 };
@@ -50,6 +51,8 @@ export type OidcMiddlewareOptions = AuthServiceOptions & {
     allowSession: (user: AuthUser) => boolean;
     /** Server-side record of ended sessions. */
     revocations: SessionRevocations;
+    /** Share rotating session refreshes between app instances. */
+    refreshCoordinator?: SessionRefreshCoordinator;
     /** Read configuration inside each request. Defaults to process.env. */
     environment?: AuthEnvironmentProvider;
     /**

package/dist/core.d.ts

@@ -64,6 +64,7 @@ export declare function createOidcCore(options: OidcMiddlewareOptions): {
             issuedAt: number;
             lastSeenAt: number;
             refreshToken?: string | undefined;
+            refreshGeneration?: number | undefined;
             idToken?: string | undefined;
             idpSid?: string | undefined;
         } | null;

package/dist/core.js

@@ -137,7 +137,7 @@ export function createOidcCore(options) {
             ? [expire(verifierCookieName(prefix(), state))]
             : [];
         try {
-            if (!state || !url.searchParams.get("code")) {
+            if (!state || !(url.searchParams.get("code") || url.searchParams.get("error"))) {
                 throw new OidcStateError("missing");
             }
             const flow = await verifyCallbackState({
@@ -169,13 +169,14 @@ export function createOidcCore(options) {
         password,
         provider,
         revocations: options.revocations,
+        refreshCoordinator: options.refreshCoordinator,
         allowSession: options.allowSession,
     });
     return {
         /** Reads, and when needed refreshes or clears, the request's session. */
         async resolve(request, context) {
             const cookies = parseCookies(request.headers.get("cookie"));
-            const { session, setCookies } = await sessions.resolve(cookies, (error) => onError({ operation: "refresh", error, context }), (work) => withinDeadline(work, context), context);
+            const { session, setCookies } = await sessions.resolve(cookies, (error, operation) => onError({ operation, error, context }), (work) => withinDeadline(work, context), context);
             return { cookies, session, setCookies };
         },
         /** An authorization URL plus the flow's verifier cookie. */

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createOidcCore, SessionAccessDeniedError, type OidcCore, type OidcAuth, type GrantRefresh, type GrantResult, } from "./core.js";
+export type { SessionRefreshCoordinator } from "./refresh.js";
 export type { Session, SessionRevocations } from "./session.js";
 export type { OidcMiddlewareOptions, OidcCallContext } from "./config.js";
 export type { TokenSet } from "./provider.js";

package/dist/provider.d.ts

@@ -17,6 +17,8 @@ export declare const PROVIDER_TIMEOUT_MS = 5000;
 /** The provider has not received a token refresh request. */
 export declare class RefreshNotDispatched extends Error {
 }
+/** Whether the provider returned access_denied in its authorization response. */
+export declare function isAuthorizationDenied(error: unknown): boolean;
 export declare function createProvider(settings: OidcConfiguration, timeoutMs?: number): {
     authorizationUrl: (input: Parameters<({ redirectUri, state, nonce, codeVerifier, }: {
         redirectUri: string;

package/dist/provider.js

@@ -58,6 +58,12 @@ export const PROVIDER_TIMEOUT_MS = 5_000;
 /** The provider has not received a token refresh request. */
 export class RefreshNotDispatched extends Error {
 }
+/** Whether the provider returned access_denied in its authorization response. */
+export function isAuthorizationDenied(error) {
+    return typeof error === "object" && error !== null
+        && "code" in error && error.code === "OAUTH_AUTHORIZATION_RESPONSE_ERROR"
+        && "error" in error && error.error === "access_denied";
+}
 export function createProvider(settings, timeoutMs = PROVIDER_TIMEOUT_MS) {
     // The SDK caches discovery and JWKS clients and accepts a single transport hook.
     // Only this transport adapter uses async-local state; domain callers pass context explicitly.
@@ -154,7 +160,7 @@ export function createProvider(settings, timeoutMs = PROVIDER_TIMEOUT_MS) {
             let email = firstString(claims.email);
             const tokenRoles = roleList(claims[settings.OIDC_ROLES_CLAIM]);
             let info;
-            if (!email || tokenRoles === undefined) {
+            if ((!email || tokenRoles === undefined) && config.serverMetadata().userinfo_endpoint) {
                 info = await client.fetchUserInfo(config, response.access_token, claims.sub);
                 email = email ?? firstString(info.email);
             }
@@ -182,11 +188,11 @@ export function createProvider(settings, timeoutMs = PROVIDER_TIMEOUT_MS) {
                     error: "invalid_grant",
                 });
             let roles = roleList(claims?.[settings.OIDC_ROLES_CLAIM]);
-            if (roles === undefined) {
+            if (roles === undefined && config.serverMetadata().userinfo_endpoint) {
                 const info = await client.fetchUserInfo(config, response.access_token, sub);
-                roles = roleList(info[settings.OIDC_ROLES_CLAIM]) ?? [];
+                roles = roleList(info[settings.OIDC_ROLES_CLAIM]);
             }
-            return { ...tokenSet(response, refreshToken), roles };
+            return { ...tokenSet(response, refreshToken), roles: roles ?? [] };
         },
         /**
          * Verifies a back-channel logout token's signature against the provider's

package/dist/refresh.d.ts

@@ -0,0 +1,30 @@
+import type { RefreshedTokens } from "./provider.js";
+import type { Session } from "./session.js";
+/** Reuse a recent refresh when a concurrent request still has the old cookie. */
+export declare const RECENT_REFRESH_MS = 10000;
+/** Coordinate a session refresh across replicas of one app. Times named "until" are epoch seconds. */
+export interface SessionRefreshCoordinator {
+    /**
+     * Atomically reserve the key before calling produce. Keep the reservation through
+     * until, even if the outcome is unknown. Concurrent callers may reuse the sealed
+     * result for reuseMs after completion. Return null for a spent key or wait timeout.
+     */
+    run(request: {
+        key: string;
+        until: number;
+        reuseMs: number;
+    }, produce: () => Promise<string>): Promise<string | null>;
+}
+export declare function sharedRefresh(coordinator: SessionRefreshCoordinator, { session, until, password, refresh }: {
+    session: Session;
+    until: number;
+    password: string;
+    refresh: () => Promise<RefreshedTokens>;
+}): Promise<{
+    accessToken: string;
+    expiresAt: number;
+    roles: string[];
+    refreshToken?: string | undefined;
+    idToken?: string | undefined;
+    refreshExpiresAt?: number | undefined;
+} | null>;

package/dist/refresh.js

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { sealValue, unsealValue } from "./seal.js";
+/** Reuse a recent refresh when a concurrent request still has the old cookie. */
+export const RECENT_REFRESH_MS = 10_000;
+const refreshResult = z.object({
+    key: z.string(),
+    useBefore: z.number(),
+    tokens: z.object({
+        accessToken: z.string().min(1),
+        refreshToken: z.string().min(1).optional(),
+        idToken: z.string().min(1).optional(),
+        expiresAt: z.number(),
+        refreshExpiresAt: z.number().optional(),
+        roles: z.array(z.string()),
+    }),
+});
+export async function sharedRefresh(coordinator, { session, until, password, refresh }) {
+    // Some providers return the same refresh token on successive renewals.
+    // Each generation gets its own reservation within this sign-in.
+    const key = createHash("sha256").update(JSON.stringify([
+        session.sid, session.user.sub, session.refreshGeneration ?? 0, session.refreshToken,
+    ])).digest("hex");
+    const ttl = RECENT_REFRESH_MS / 1000;
+    const sealed = await coordinator.run({ key, until, reuseMs: RECENT_REFRESH_MS }, async () => {
+        const tokens = await refresh();
+        return sealValue({ key, tokens, useBefore: Date.now() + RECENT_REFRESH_MS }, password, ttl);
+    });
+    if (sealed === null)
+        return null;
+    const result = refreshResult.parse(await unsealValue(sealed, password, ttl));
+    if (result.key !== key)
+        throw new Error("Mismatched session refresh result");
+    return Date.now() < result.useBefore ? result.tokens : null;
+}

package/dist/session.d.ts

@@ -2,16 +2,11 @@ import type { OidcCallContext } from "./config.js";
 import { z } from "zod";
 import { type CookieOptions } from "./cookies.js";
 import type { OidcProvider } from "./provider.js";
+import { type SessionRefreshCoordinator } from "./refresh.js";
 import type { SessionRevocations } from "./revocation.js";
 export type { SessionRevocations };
 /** Refresh this many seconds before the access token expires. */
 export declare const REFRESH_LEEWAY_SECONDS = 30;
-/**
- * How long a completed refresh is reused for requests still carrying the old
- * refresh token, so a provider that rotates refresh tokens doesn't reject the
- * stale one from a parallel request or another tab.
- */
-export declare const RECENT_REFRESH_MS = 10000;
 declare const sessionSchema: z.ZodObject<{
     user: z.ZodObject<{
         sub: z.ZodString;
@@ -22,6 +17,7 @@ declare const sessionSchema: z.ZodObject<{
     }, z.core.$strip>;
     accessToken: z.ZodString;
     refreshToken: z.ZodOptional<z.ZodString>;
+    refreshGeneration: z.ZodOptional<z.ZodNumber>;
     idToken: z.ZodOptional<z.ZodString>;
     expiresAt: z.ZodNumber;
     sid: z.ZodString;
@@ -37,7 +33,7 @@ export type SessionResolution = {
     /** Set-Cookie lines to apply: a refreshed session, or a cleared one. */
     setCookies: string[];
 };
-export declare function createSessionManager({ cookieName: name, cookieOptions, maxAgeSeconds, idleSeconds, password, provider, revocations, allowSession, }: {
+export declare function createSessionManager({ cookieName: name, cookieOptions, maxAgeSeconds, idleSeconds, password, provider, revocations, refreshCoordinator, allowSession, }: {
     cookieName: () => string;
     cookieOptions: () => CookieOptions;
     /** Absolute lifetime from sign-in. */
@@ -47,11 +43,12 @@ export declare function createSessionManager({ cookieName: name, cookieOptions,
     password: () => string;
     provider: () => OidcProvider;
     revocations: SessionRevocations;
+    refreshCoordinator?: SessionRefreshCoordinator;
     /** Whether the (possibly refreshed) user may keep a session. */
     allowSession: (user: Session["user"]) => boolean;
 }): {
     readActive: (cookies: Map<string, string>, onStoreError?: (error: unknown) => void) => Promise<SessionResolution>;
-    resolve: (cookies: Map<string, string>, onRefreshError?: (error: unknown) => void, bound?: <T>(work: Promise<T>) => Promise<T>, context?: OidcCallContext) => Promise<SessionResolution>;
+    resolve: (cookies: Map<string, string>, onError?: (error: unknown, operation: "refresh" | "revocation-read") => void, bound?: <T>(work: Promise<T>) => Promise<T>, context?: OidcCallContext) => Promise<SessionResolution>;
     write: (cookies: Map<string, string>, session: Session) => Promise<string[]>;
     clear: (cookies: Map<string, string>) => string[];
 };

package/dist/session.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { clearChunked, readChunked, writeChunked, } from "./cookies.js";
 import { authUserSchema } from "./models.js";
+import { RECENT_REFRESH_MS, sharedRefresh } from "./refresh.js";
 import { sealValue, unsealValue } from "./seal.js";
 // Session resolution after WorkOS authkit-session's AuthKitCore and
 // AuthService: the sealed cookie holds the user and tokens, and an expiring
@@ -8,16 +9,12 @@ import { sealValue, unsealValue } from "./seal.js";
 // refreshes shortly before expiry and clears the cookie when refresh fails.
 /** Refresh this many seconds before the access token expires. */
 export const REFRESH_LEEWAY_SECONDS = 30;
-/**
- * How long a completed refresh is reused for requests still carrying the old
- * refresh token, so a provider that rotates refresh tokens doesn't reject the
- * stale one from a parallel request or another tab.
- */
-export const RECENT_REFRESH_MS = 10_000;
 const sessionSchema = z.object({
     user: authUserSchema,
     accessToken: z.string().min(1),
     refreshToken: z.string().min(1).optional(),
+    /** Sequence number of this session’s last coordinated token refresh. */
+    refreshGeneration: z.number().int().nonnegative().optional(),
     idToken: z.string().min(1).optional(),
     expiresAt: z.number(),
     /** Random id naming this sign-in, so it can be revoked server-side. */
@@ -31,7 +28,7 @@ const sessionSchema = z.object({
 });
 /** Re-seal the cookie once the last-seen time is this stale, to keep idle tracking current. */
 export const TOUCH_AFTER_SECONDS = 300;
-export function createSessionManager({ cookieName: name, cookieOptions, maxAgeSeconds, idleSeconds, password, provider, revocations, allowSession, }) {
+export function createSessionManager({ cookieName: name, cookieOptions, maxAgeSeconds, idleSeconds, password, provider, revocations, refreshCoordinator, allowSession, }) {
     const refreshes = new Map();
     function refreshOnce(refreshToken, sub, context) {
         const now = Date.now();
@@ -87,7 +84,13 @@ export function createSessionManager({ cookieName: name, cookieOptions, maxAgeSe
             return { session: null, setCookies: clear(cookies) };
         }
         try {
-            if (await revocations.isRevoked({ ...session, sub: session.user.sub })) {
+            const revoked = await revocations.isRevoked({
+                sid: session.sid,
+                sub: session.user.sub,
+                issuedAt: session.issuedAt,
+                ...(session.idpSid !== undefined && { idpSid: session.idpSid }),
+            });
+            if (revoked) {
                 return { session: null, setCookies: clear(cookies) };
             }
         }
@@ -99,8 +102,8 @@ export function createSessionManager({ cookieName: name, cookieOptions, maxAgeSe
         }
         return { session, setCookies: [] };
     }
-    async function resolve(cookies, onRefreshError = () => { }, bound = (work) => work, context) {
-        const checked = await readActive(cookies, onRefreshError);
+    async function resolve(cookies, onError = () => { }, bound = (work) => work, context) {
+        const checked = await readActive(cookies, (error) => onError(error, "revocation-read"));
         const { session } = checked;
         if (!session)
             return checked;
@@ -116,10 +119,23 @@ export function createSessionManager({ cookieName: name, cookieOptions, maxAgeSe
             return { session: null, setCookies: clear(cookies) };
         }
         try {
-            const { roles, ...tokens } = await bound(refreshOnce(session.refreshToken, session.user.sub, context));
+            const refreshToken = session.refreshToken;
+            const work = refreshCoordinator
+                ? sharedRefresh(refreshCoordinator, {
+                    session,
+                    until: session.issuedAt + maxAgeSeconds,
+                    password: password(),
+                    refresh: () => provider().refresh(refreshToken, session.user.sub, context),
+                })
+                : refreshOnce(refreshToken, session.user.sub, context);
+            const refreshedTokens = await bound(work);
+            if (!refreshedTokens)
+                return { session: null, setCookies: [] };
+            const { roles, ...tokens } = refreshedTokens;
             const refreshed = {
                 ...session,
                 ...tokens,
+                ...(refreshCoordinator && { refreshGeneration: (session.refreshGeneration ?? 0) + 1 }),
                 idToken: tokens.idToken ?? session.idToken,
                 user: { ...session.user, roles },
                 lastSeenAt: now,
@@ -133,8 +149,10 @@ export function createSessionManager({ cookieName: name, cookieOptions, maxAgeSe
             };
         }
         catch (error) {
-            onRefreshError(error);
-            return { session: null, setCookies: clear(cookies) };
+            onError(error, "refresh");
+            // A peer may already have written the renewed cookie, even if this
+            // caller timed out. A failed coordinated refresh must never erase it.
+            return { session: null, setCookies: refreshCoordinator ? [] : clear(cookies) };
         }
     }
     return { readActive, resolve, write, clear };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@lpshanley/oidc-start-core",
-  "version": "0.1.0-next.1",
+  "version": "0.2.0",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lpshanley/oidc-start.git",