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

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @lpshanley/oidc-start-core
 
-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.
+OpenID Connect sign-in for Node.js servers. Give the core a standard `Request` and it handles provider discovery, the authorization code exchange with PKCE, and sealed session cookies. Your app decides who can sign in and where to record revoked sessions.
+
+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)
+
+## Install and register your app
+
+Use Node.js 22.12 or newer with ES modules. Install the current prerelease from npm.
+
+```sh
+npm install @lpshanley/oidc-start-core@next
+```
+
+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.
+
+| Server setting | What to supply |
+| --- | --- |
+| `APP_ORIGIN` | The public origin of your app, such as `http://localhost:5173` in development. |
+| `OIDC_ISSUER` | The provider’s issuer URL, including its tenant path if it has one. |
+| `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. |
+
+## Create the core
+
+Create one instance in a server module. This example requires the `members` role, so give your test user that role at the provider. The core checks the policy at sign-in, when reading a session, and after refreshing it.
+
+```ts
+// auth.server.ts
+import { createOidcCore } from '@lpshanley/oidc-start-core'
+import { hasRole } from '@lpshanley/oidc-start-core/models'
+import { revocations } from './revocations.js'
+
+export const auth = createOidcCore({
+  cookiePrefix: 'myapp',
+  callbackPath: '/callback',
+  postLogoutPath: '/',
+  allowSession: user => hasRole(user, 'members'),
+  revocations,
+})
+
+auth.assertConfigured()
+```
+
+`./revocations.js` is an app module you supply. For a local trial, copy the three maps and the `revocations` object from the example into `revocations.ts` and export the object. A deployed app needs durable storage shared by every instance. [Local revocation store](https://github.com/lpshanley/oidc-start/blob/main/examples/tanstack-start/src/auth.server.ts)
+
+## Wire sign-in and callback
+
+Mount these handlers at `GET /sign-in` and `GET /callback` in your server. The first sends the browser to the provider. The second checks the code and browser verifier, sets the session cookie, and returns the user to `/`.
+
+```ts
+import { SessionAccessDeniedError } from '@lpshanley/oidc-start-core'
+import { auth } from './auth.server.js'
+
+function authHeaders(cookies: string[]) {
+  const headers = new Headers({ 'Cache-Control': 'no-store' })
+  for (const cookie of cookies) headers.append('Set-Cookie', cookie)
+  return headers
+}
+
+export async function signIn(request: Request) {
+  const { cookies, setCookies } = await auth.resolve(request)
+  const flow = await auth.signIn(request, cookies, '/')
+  const headers = authHeaders([...setCookies, ...flow.setCookies])
+  headers.set('Location', flow.url)
+  return new Response(null, { status: 302, headers })
+}
+
+export async function callback(request: Request) {
+  const { cookies, setCookies } = await auth.resolve(request)
+  const result = await auth.callback(request, cookies)
+  const headers = authHeaders([...setCookies, ...result.setCookies])
+  if (!result.ok) {
+    const denied = result.error instanceof SessionAccessDeniedError
+    return new Response(denied ? 'Access denied.' : 'Please sign in again.', {
+      status: denied ? 403 : 400, headers,
+    })
+  }
+  headers.set('Location', result.location)
+  return new Response(null, { status: 302, headers })
+}
+```
+
+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`.
+
+## 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.
+
+Implement these four methods on your `SessionRevocations` store. All times are in epoch seconds. Let storage errors propagate so the core can distinguish an outage from an active session.
+
+| Method | Storage rule |
+| --- | --- |
+| `revoke(sid, until)` | Mark this app session as revoked through its expiry. |
+| `revokeIdpSession(idpSid, until)` | Mark the provider session as revoked. Atomically keep the later expiry. |
+| `revokeAllFor(sub, cutoff)` | Atomically keep the greatest cutoff for the subject. |
+| `isRevoked({ sid, idpSid, sub, issuedAt })` | Return true for a live revocation of either session ID, or when `issuedAt <= cutoff` for this subject. |
+
+For provider-initiated logout, register a POST endpoint and pass its request to `auth.backchannelLogout(request)`. Return the resulting HTTP status to the provider. The core verifies the signed logout token, including its expiry and nonempty token ID. A redelivered event uses the original issue time. [Revocation interface](https://github.com/lpshanley/oidc-start/blob/main/packages/core/src/revocation.ts)
+
+## Obtain a separate provider grant
+
+Use this flow when your app needs credentials for provider API calls independently of the browser session. Register a second redirect URI with the provider. The default path is `/api/auth/grant-callback`, configurable with `grantCallbackPath`.
+
+1. Call `auth.startGrant(request, cookies, returnPathname)`, send its cookies, and redirect to its `url`.
+2. In the grant callback, call `auth.finishGrant(request, cookies)` and forward its cookies on success or failure. On success, check the returned user and permissions before storing the tokens on the server.
+3. Call `auth.refreshGrant(refreshToken)` to renew the grant. A `refused` result means the provider rejected it. Other errors propagate. `RefreshNotDispatched` from `@lpshanley/oidc-start-core/provider` means the refresh request was never sent.

package/dist/config.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import type { AuthUser } from "./models.js";
+import type { SessionRevocations } from "./revocation.js";
+export type AuthEnvironment = Readonly<Record<string, string | undefined>>;
+export type AuthEnvironmentProvider = () => AuthEnvironment;
+export declare const authServiceOptionsSchema: z.ZodObject<{
+    cookiePrefix: z.ZodDefault<z.ZodString>;
+    sessionMaxAgeSeconds: z.ZodDefault<z.ZodNumber>;
+    sessionIdleSeconds: z.ZodDefault<z.ZodNumber>;
+    callbackPath: z.ZodDefault<z.ZodString>;
+    grantCallbackPath: z.ZodDefault<z.ZodString>;
+    postLogoutPath: z.ZodDefault<z.ZodString>;
+    providerTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type AuthServiceOptions = z.input<typeof authServiceOptionsSchema>;
+export declare const sessionConfigurationSchema: z.ZodObject<{
+    SESSION_SECRET: z.ZodString;
+}, z.core.$strip>;
+export declare const oidcConfigurationSchema: z.ZodObject<{
+    OIDC_ISSUER: z.ZodPipe<z.ZodString, z.ZodURL>;
+    OIDC_CLIENT_ID: z.ZodString;
+    OIDC_CLIENT_SECRET: z.ZodString;
+    OIDC_SCOPES: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
+    OIDC_ROLES_CLAIM: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
+}, z.core.$strip>;
+export type OidcConfiguration = z.output<typeof oidcConfigurationSchema>;
+export declare const authOriginConfigurationSchema: z.ZodObject<{
+    APP_ORIGIN: z.ZodPreprocess<z.ZodOptional<z.ZodURL>, unknown>;
+    OIDC_REDIRECT_URI: z.ZodCatch<z.ZodOptional<z.ZodURL>>;
+    NODE_ENV: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function assertOidcConfigured(env: AuthEnvironment): void;
+/**
+ * The caller's request context, read from `context.requestContext` when an
+ * earlier request middleware provides one.
+ */
+export type OidcCallContext = {
+    correlationId?: string;
+    deadline?: number;
+    signal?: AbortSignal;
+};
+/** 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";
+    error: unknown;
+    context?: OidcCallContext;
+};
+export type OidcMiddlewareOptions = AuthServiceOptions & {
+    /** The host decides who may start or keep a session. */
+    allowSession: (user: AuthUser) => boolean;
+    /** Server-side record of ended sessions. */
+    revocations: SessionRevocations;
+    /** Read configuration inside each request. Defaults to process.env. */
+    environment?: AuthEnvironmentProvider;
+    /**
+     * Receives provider and flow failures. The error may carry provider
+     * responses, so redact it before logging. Defaults to logging the
+     * operation and request ID only.
+     */
+    onError?: (event: OidcErrorEvent) => void;
+};

package/dist/config.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+export const authServiceOptionsSchema = z.object({
+    /** Cookie names start with this prefix. Defaults to `oidc`. */
+    cookiePrefix: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]+$/, "cookiePrefix must contain only letters, numbers, underscores or hyphens")
+        .default("oidc"),
+    /** Application session lifetime in seconds. Defaults to 14 days. */
+    sessionMaxAgeSeconds: z
+        .number()
+        .int("sessionMaxAgeSeconds must be a positive integer")
+        .positive("sessionMaxAgeSeconds must be a positive integer")
+        .default(60 * 60 * 24 * 14),
+    /** Session lifetime without requests, in seconds. Defaults to 12 hours. */
+    sessionIdleSeconds: z
+        .number()
+        .int()
+        .positive()
+        .default(60 * 60 * 12),
+    /** Callback path when OIDC_REDIRECT_URI is unset. */
+    callbackPath: z.string().default("/api/auth/callback"),
+    /** Separate return address for app-managed grants. */
+    grantCallbackPath: z.string().default("/api/auth/grant-callback"),
+    /** Application path after provider logout. Defaults to `/login`. */
+    postLogoutPath: z.string().default("/login"),
+    /** Timeout for each provider request. Defaults to 5 seconds. */
+    providerTimeoutMs: z.number().int().positive().default(5_000),
+});
+export const sessionConfigurationSchema = z.object({
+    SESSION_SECRET: z
+        .string({ error: "Missing required environment variable: SESSION_SECRET" })
+        .min(1, "Missing required environment variable: SESSION_SECRET")
+        .min(32, "SESSION_SECRET must be at least 32 characters"),
+});
+export const oidcConfigurationSchema = z.object({
+    OIDC_ISSUER: z
+        .string({
+        error: "Missing required environment variable: OIDC_ISSUER",
+    })
+        .min(1, "Missing required environment variable: OIDC_ISSUER")
+        .pipe(z.url({ error: "OIDC_ISSUER must be a valid URL" })),
+    OIDC_CLIENT_ID: z
+        .string({
+        error: "Missing required environment variable: OIDC_CLIENT_ID",
+    })
+        .min(1, "Missing required environment variable: OIDC_CLIENT_ID"),
+    OIDC_CLIENT_SECRET: z
+        .string({
+        error: "Missing required environment variable: OIDC_CLIENT_SECRET",
+    })
+        .min(1, "Missing required environment variable: OIDC_CLIENT_SECRET"),
+    /** Space-separated scopes; offline_access requests a refresh token. */
+    OIDC_SCOPES: z.preprocess((value) => (value === "" ? undefined : value), z.string().default("openid profile email offline_access")),
+    /** The claim holding the user's roles, read into `AuthUser.roles`. */
+    OIDC_ROLES_CLAIM: z.preprocess((value) => (value === "" ? undefined : value), z.string().default("roles")),
+});
+export const authOriginConfigurationSchema = z.object({
+    APP_ORIGIN: z.preprocess((value) => (value === "" ? undefined : value), z.url({ error: "APP_ORIGIN must be a valid URL" }).optional()),
+    OIDC_REDIRECT_URI: z.url().optional().catch(undefined),
+    NODE_ENV: z.string().optional(),
+});
+export function assertOidcConfigured(env) {
+    const issues = [
+        oidcConfigurationSchema,
+        sessionConfigurationSchema,
+        authOriginConfigurationSchema,
+    ].flatMap((schema) => schema.safeParse(env).error?.issues ?? []);
+    if (issues.length) {
+        throw new Error(`Invalid OIDC configuration: ${issues.map((issue) => issue.message).join("; ")}`);
+    }
+}

package/dist/cookies.d.ts

@@ -0,0 +1,21 @@
+export type CookieOptions = {
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+    maxAge?: number;
+};
+/** Browsers cap a cookie near 4096 bytes; leave room for name and attributes. */
+export declare const CHUNK_SIZE = 3800;
+export declare function parseCookies(header: string | null | undefined): Map<string, string>;
+export declare function serializeCookie(name: string, value: string, options: CookieOptions): string;
+/** Reads `name`, or its contiguous `name.0`, `name.1`, … chunks. */
+export declare function readChunked(cookies: Map<string, string>, name: string): string | undefined;
+/** Set-Cookie lines that delete `name` and every chunk of it. */
+export declare function clearChunked(cookies: Map<string, string>, name: string, options: CookieOptions): string[];
+/**
+ * Set-Cookie lines that store `value` under `name`, splitting it into
+ * `name.0..n` chunks when it is too large for one cookie, and deleting any
+ * stale cookie or chunk left from a previous size.
+ */
+export declare function writeChunked(cookies: Map<string, string>, name: string, value: string, options: CookieOptions): string[];

package/dist/cookies.js

@@ -0,0 +1,93 @@
+/** Browsers cap a cookie near 4096 bytes; leave room for name and attributes. */
+export const CHUNK_SIZE = 3800;
+export function parseCookies(header) {
+    const cookies = new Map();
+    for (const part of header?.split(";") ?? []) {
+        const index = part.indexOf("=");
+        if (index < 1)
+            continue;
+        const name = part.slice(0, index).trim();
+        const raw = part.slice(index + 1).trim();
+        try {
+            cookies.set(name, decodeURIComponent(raw));
+        }
+        catch {
+            cookies.set(name, raw);
+        }
+    }
+    return cookies;
+}
+export function serializeCookie(name, value, options) {
+    const parts = [`${name}=${encodeURIComponent(value)}`];
+    if (options.maxAge !== undefined)
+        parts.push(`Max-Age=${options.maxAge}`);
+    parts.push(`Path=${options.path ?? "/"}`);
+    if (options.httpOnly)
+        parts.push("HttpOnly");
+    if (options.secure)
+        parts.push("Secure");
+    if (options.sameSite) {
+        parts.push(`SameSite=${options.sameSite[0]?.toUpperCase()}${options.sameSite.slice(1)}`);
+    }
+    return parts.join("; ");
+}
+function chunkNames(cookies, name) {
+    const pattern = new RegExp(`^${name.replace(/[.-]/g, "\\$&")}\\.(\\d+)$`);
+    return [...cookies.keys()]
+        .map((key) => ({ key, index: Number(pattern.exec(key)?.[1]) }))
+        .filter(({ index }) => Number.isInteger(index))
+        .sort((a, b) => a.index - b.index);
+}
+/** Reads `name`, or its contiguous `name.0`, `name.1`, … chunks. */
+export function readChunked(cookies, name) {
+    const whole = cookies.get(name);
+    if (whole !== undefined)
+        return whole;
+    const chunks = chunkNames(cookies, name);
+    if (chunks.length === 0 || chunks.some(({ index }, i) => index !== i)) {
+        return undefined;
+    }
+    return chunks.map(({ key }) => cookies.get(key)).join("");
+}
+/** Set-Cookie lines that delete `name` and every chunk of it. */
+export function clearChunked(cookies, name, options) {
+    const expired = { ...options, maxAge: 0 };
+    const keys = [
+        ...(cookies.has(name) ? [name] : []),
+        ...chunkNames(cookies, name).map(({ key }) => key),
+    ];
+    return keys.map((key) => serializeCookie(key, "", expired));
+}
+/**
+ * Set-Cookie lines that store `value` under `name`, splitting it into
+ * `name.0..n` chunks when it is too large for one cookie, and deleting any
+ * stale cookie or chunk left from a previous size.
+ */
+export function writeChunked(cookies, name, value, options) {
+    const encoded = encodeURIComponent(value);
+    if (encoded.length <= CHUNK_SIZE) {
+        return [
+            serializeCookie(name, value, options),
+            ...clearChunked(new Map(chunkNames(cookies, name).map(({ key }) => [key, ""])), name, options),
+        ];
+    }
+    // Split the plain value so no percent-escape is cut in half.
+    const chunks = [];
+    let current = "";
+    for (const character of value) {
+        if (encodeURIComponent(current + character).length > CHUNK_SIZE) {
+            chunks.push(current);
+            current = "";
+        }
+        current += character;
+    }
+    if (current)
+        chunks.push(current);
+    const written = chunks.map((chunk, index) => serializeCookie(`${name}.${index}`, chunk, options));
+    const stale = clearChunked(cookies, name, options).filter((line) => {
+        const key = line.slice(0, line.indexOf("="));
+        const index = Number(key.slice(name.length + 1));
+        return key === name || index >= chunks.length;
+    });
+    return [...written, ...stale];
+}

package/dist/core.d.ts

@@ -0,0 +1,123 @@
+import { type OidcCallContext, type OidcErrorEvent, type OidcMiddlewareOptions } from "./config.js";
+import { type AuthUser } from "./models.js";
+import { type TokenSet } from "./provider.js";
+import { type Session } from "./session.js";
+export type OidcAuth = {
+    user: AuthUser | null;
+};
+/** The caller's deadline passed before the provider answered. */
+export declare class OidcDeadlineError extends Error {
+    name: string;
+    constructor();
+}
+/**
+ * Settles with the work, or rejects once the caller's deadline passes. Each
+ * provider request also has its own timeout, so abandoned work still ends.
+ */
+export declare function withinDeadline<T>(work: Promise<T>, context?: OidcCallContext, now?: number): Promise<T>;
+/** The provider authenticated a user whom the host denied a session. */
+export declare class SessionAccessDeniedError extends Error {
+    name: string;
+    constructor();
+}
+export type CallbackResult = {
+    ok: true;
+    location: string;
+    setCookies: string[];
+} | {
+    ok: false;
+    error: unknown;
+    setCookies: string[];
+};
+export type GrantResult = {
+    ok: true;
+    user: AuthUser;
+    tokens: TokenSet;
+    returnPathname: string;
+    setCookies: string[];
+} | {
+    ok: false;
+    error: unknown;
+    setCookies: string[];
+};
+export type GrantRefresh = {
+    status: "refreshed";
+    tokens: TokenSet;
+} | {
+    status: "refused";
+};
+export declare function createOidcCore(options: OidcMiddlewareOptions): {
+    /** Reads, and when needed refreshes or clears, the request's session. */
+    resolve(request: Request, context?: OidcCallContext): Promise<{
+        cookies: Map<string, string>;
+        session: {
+            user: {
+                sub: string;
+                email: string;
+                name: string | null;
+                picture?: string | null | undefined;
+                roles?: string[] | undefined;
+            };
+            accessToken: string;
+            expiresAt: number;
+            sid: string;
+            issuedAt: number;
+            lastSeenAt: number;
+            refreshToken?: string | undefined;
+            idToken?: string | undefined;
+            idpSid?: string | undefined;
+        } | null;
+        setCookies: string[];
+    }>;
+    /** An authorization URL plus the flow's verifier cookie. */
+    signIn(request: Request, cookies: Map<string, string>, returnPathname?: string | null, context?: OidcCallContext): Promise<{
+        url: string;
+        setCookies: string[];
+    }>;
+    /** Verifies the flow, exchanges the code, and issues the session. */
+    callback(request: Request, cookies: Map<string, string>, context?: OidcCallContext): Promise<CallbackResult>;
+    /**
+     * Starts a grant: an authorization like sign-in whose tokens the app
+     * keeps for itself, returning on `grantCallbackPath`. It writes no
+     * session, so the browser's own session is untouched.
+     */
+    startGrant(request: Request, cookies: Map<string, string>, returnPathname: string, context?: OidcCallContext): Promise<{
+        url: string;
+        setCookies: string[];
+    }>;
+    /** Verifies a grant's callback and exchanges its code for tokens. */
+    finishGrant(request: Request, cookies: Map<string, string>, context?: OidcCallContext): Promise<GrantResult>;
+    /**
+     * Refreshes a grant's tokens. `refused` means the provider ended the
+     * grant (`invalid_grant`); any other failure throws, since the provider
+     * may only be unreachable.
+     */
+    refreshGrant(refreshToken: string, context?: OidcCallContext): Promise<GrantRefresh>;
+    /**
+     * Ends the session server-side (every session of the user with
+     * `everywhere`), clears the cookie, and returns the provider logout URL.
+     * Throws when the revocation cannot be recorded, so a sign-out is never
+     * reported done while the cookie would still work.
+     */
+    signOut(request: Request, cookies: Map<string, string>, session: Session | null, context?: OidcCallContext, everywhere?: boolean): Promise<{
+        location: string;
+        setCookies: string[];
+    }>;
+    /**
+     * Handles a provider's back-channel logout: verifies the posted
+     * logout_token and ends the sessions it names. Answers 400 for an
+     * invalid token and 503 when the provider's keys or the revocation
+     * store cannot be reached, so the provider can retry.
+     */
+    backchannelLogout(request: Request, context?: OidcCallContext): Promise<{
+        status: 200 | 400 | 503;
+    }>;
+    /** Reports a failure through the configured `onError`. */
+    report: (event: OidcErrorEvent) => void;
+    /**
+     * Throws one error naming every missing or invalid setting, so the
+     * app can refuse to serve before the first sign-in needs them.
+     */
+    assertConfigured(): void;
+};
+export type OidcCore = ReturnType<typeof createOidcCore>;