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

package/README.md

@@ -1,3 +1,25 @@
-# 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 for a Node.js server. Handles discovery, code exchange with PKCE, sealed browser sessions, refresh, revocation and back-channel logout. Use the separate `@lpshanley/oidc-start-react` package for TanStack Start.
+
+```ts
+import { createOidcCore } from '@lpshanley/oidc-start-core'
+import { hasRole } from '@lpshanley/oidc-start-core/models'
+
+const auth = createOidcCore({
+  cookiePrefix: 'myapp',
+  callbackPath: '/auth/callback',
+  postLogoutPath: '/signed-out',
+  allowSession: user => hasRole(user, 'members'),
+  revocations: mySessionRevocationStore,
+})
+auth.assertConfigured()
+```
+
+Provide `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, and a `SESSION_SECRET` of at least 32 characters. Set `APP_ORIGIN` to the public app origin and `OIDC_ROLES_CLAIM` to the provider's role claim (default `roles`). Register the callback and post-logout URLs. Each app chooses its own role policy and supplies a `SessionRevocations` implementation shared by its server instances. The core checks that policy at sign-in, on session access and after refresh.
+
+Back-channel logout requires a signed token with an expiration (`exp`) and a nonempty token ID (`jti`). The signed issue time sets the revocation cutoff, in epoch seconds. For `revokeAllFor` and `revokeIdpSession`, atomically keep the greater of the stored and incoming timestamp so an older delivery cannot undo a newer revocation. A subject cutoff includes sessions issued in the same second.
+
+Use `startGrant` and `finishGrant` on the server to obtain an independent provider grant. Register a separate `grantCallbackPath` (default `/api/auth/grant-callback`). The sealed state binds each flow to its purpose. The host checks the returned subject and permissions, stores the credentials and decides which client can use them. `refreshGrant` returns `refused` for a provider rejection of the grant. Other errors propagate. A `RefreshNotDispatched` from `/provider` means the refresh request was never sent.
+
+The `/models` entry is safe to import in browser code. Credentials and session management belong on the server.

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>;