@lpshanley/oidc-start-core 0.2.0 → 0.3.0

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 import { type OidcCallContext, type OidcErrorEvent, type OidcMiddlewareOptions } from "./config.js";
-import { type AuthUser } from "./models.js";
+import { type AuthUser, type SignInOptions } from "./models.js";
 import { type TokenSet } from "./provider.js";
 import { type Session } from "./session.js";
 export type OidcAuth = {
@@ -20,12 +20,14 @@ export declare class SessionAccessDeniedError extends Error {
     name: string;
     constructor();
 }
+export type CallbackErrorReason = "invalid_callback" | "sign_in_expired" | "invalid_state" | "access_denied" | "provider_error" | "token_exchange_failed" | "session_failed";
 export type CallbackResult = {
     ok: true;
     location: string;
     setCookies: string[];
 } | {
     ok: false;
+    reason: CallbackErrorReason | "session_access_denied";
     error: unknown;
     setCookies: string[];
 };
@@ -37,6 +39,7 @@ export type GrantResult = {
     setCookies: string[];
 } | {
     ok: false;
+    reason: CallbackErrorReason;
     error: unknown;
     setCookies: string[];
 };
@@ -66,12 +69,13 @@ export declare function createOidcCore(options: OidcMiddlewareOptions): {
             refreshToken?: string | undefined;
             refreshGeneration?: number | undefined;
             idToken?: string | undefined;
+            authTime?: number | 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<{
+    signIn(request: Request, cookies: Map<string, string>, options?: string | null | SignInOptions, context?: OidcCallContext): Promise<{
         url: string;
         setCookies: string[];
     }>;

package/dist/core.js

@@ -3,8 +3,8 @@ import { randomNonce, randomPKCECodeVerifier } from "openid-client";
 import { assertOidcConfigured, authOriginConfigurationSchema, authServiceOptionsSchema, oidcConfigurationSchema, sessionConfigurationSchema, } from "./config.js";
 import { parseCookies, serializeCookie, } from "./cookies.js";
 import { LOGOUT_TOKEN_MAX_AGE_SECONDS, LogoutTokenError } from "./logout-token.js";
-import { sanitizeReturnPath } from "./models.js";
-import { createProvider, } from "./provider.js";
+import { sanitizeReturnPath, signInOptionsSchema } from "./models.js";
+import { authorizationErrorCode, createProvider, } from "./provider.js";
 import { createSessionManager } from "./session.js";
 import { OidcStateError, STATE_MAX_AGE_SECONDS, sealState, staleVerifierNames, verifierCookieName, verifyCallbackState, } from "./state.js";
 /** The caller's deadline passed before the provider answered. */
@@ -99,18 +99,22 @@ export function createOidcCore(options) {
             ? redirectUri(request)
             : `${origin(request)}${settings.grantCallbackPath}`;
     }
-    async function begin(purpose, request, cookies, returnPathname, context) {
+    async function begin(purpose, request, cookies, options, context) {
         const nonce = randomNonce();
         const codeVerifier = randomPKCECodeVerifier();
         const state = await sealState({
             purpose,
             nonce,
             codeVerifier,
-            returnPathname: sanitizeReturnPath(returnPathname),
+            returnPathname: sanitizeReturnPath(options.returnPathname),
+            maxAge: options.maxAge,
         }, password());
         const name = verifierCookieName(prefix(), state);
         const url = await withinDeadline(provider().authorizationUrl({
             redirectUri: callbackUri(purpose, request),
+            loginHint: options.loginHint,
+            maxAge: options.maxAge,
+            prompt: options.prompt,
             state,
             nonce,
             codeVerifier,
@@ -136,29 +140,37 @@ export function createOidcCore(options) {
         const clearVerifier = state
             ? [expire(verifierCookieName(prefix(), state))]
             : [];
+        if (!state || !(url.searchParams.get("code") || url.searchParams.get("error"))) {
+            return { ok: false, reason: "invalid_callback", error: new OidcStateError("missing"), setCookies: clearVerifier };
+        }
+        let reason = "invalid_state";
         try {
-            if (!state || !(url.searchParams.get("code") || url.searchParams.get("error"))) {
-                throw new OidcStateError("missing");
-            }
             const flow = await verifyCallbackState({
                 state,
                 cookieValue: cookies.get(verifierCookieName(prefix(), state)),
                 password: password(),
                 purpose,
             });
+            reason = "token_exchange_failed";
             // Rebuild the callback on the registered redirect URI so a proxy
             // in front of the app doesn't change the URL being verified.
             const callbackUrl = new URL(callbackUri(purpose, request));
             callbackUrl.search = url.search;
-            const { user, tokens, idpSid } = await withinDeadline(provider().exchangeCode(callbackUrl, {
+            const { user, tokens, idpSid, authTime } = await withinDeadline(provider().exchangeCode(callbackUrl, {
                 state,
                 nonce: flow.nonce,
                 codeVerifier: flow.codeVerifier,
+                maxAge: flow.maxAge,
             }, context), context);
-            return { ok: true, flow, user, tokens, idpSid, clearVerifier };
+            return { ok: true, flow, user, tokens, idpSid, authTime, clearVerifier };
         }
         catch (error) {
-            return { ok: false, error, setCookies: clearVerifier };
+            const code = authorizationErrorCode(error);
+            if (code)
+                reason = code === "access_denied" ? "access_denied" : "provider_error";
+            else if (error instanceof OidcStateError && error.reason === "missing")
+                reason = "sign_in_expired";
+            return { ok: false, reason, error, setCookies: clearVerifier };
         }
     }
     const sessions = createSessionManager({
@@ -180,15 +192,18 @@ export function createOidcCore(options) {
             return { cookies, session, setCookies };
         },
         /** An authorization URL plus the flow's verifier cookie. */
-        signIn(request, cookies, returnPathname, context) {
-            return begin("session", request, cookies, returnPathname, context);
+        signIn(request, cookies, options, context) {
+            const signInOptions = typeof options === "string"
+                ? { returnPathname: options }
+                : signInOptionsSchema.parse(options ?? {});
+            return begin("session", request, cookies, signInOptions, context);
         },
         /** Verifies the flow, exchanges the code, and issues the session. */
         async callback(request, cookies, context) {
             const result = await complete("session", request, cookies, context);
             if (!result.ok)
                 return result;
-            const { user, tokens, idpSid, flow, clearVerifier } = result;
+            const { user, tokens, idpSid, authTime, flow, clearVerifier } = result;
             try {
                 if (!options.allowSession(user))
                     throw new SessionAccessDeniedError();
@@ -202,6 +217,7 @@ export function createOidcCore(options) {
                             ...tokens,
                             sid: crypto.randomUUID(),
                             ...(idpSid ? { idpSid } : {}),
+                            authTime,
                             issuedAt: now,
                             lastSeenAt: now,
                         })),
@@ -210,7 +226,8 @@ export function createOidcCore(options) {
                 };
             }
             catch (error) {
-                return { ok: false, error, setCookies: clearVerifier };
+                const reason = error instanceof SessionAccessDeniedError ? "session_access_denied" : "session_failed";
+                return { ok: false, reason, error, setCookies: clearVerifier };
             }
         },
         /**
@@ -219,7 +236,7 @@ export function createOidcCore(options) {
          * session, so the browser's own session is untouched.
          */
         startGrant(request, cookies, returnPathname, context) {
-            return begin("grant", request, cookies, returnPathname, context);
+            return begin("grant", request, cookies, { returnPathname }, context);
         },
         /** Verifies a grant's callback and exchanges its code for tokens. */
         async finishGrant(request, cookies, context) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createOidcCore, SessionAccessDeniedError, type OidcCore, type OidcAuth, type GrantRefresh, type GrantResult, } from "./core.js";
+export { createOidcCore, SessionAccessDeniedError, type OidcCore, type CallbackErrorReason, 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";

package/dist/models.d.ts

@@ -1,4 +1,17 @@
 import { z } from "zod";
+/** Options for a single authorization request. Omit prompt to allow provider SSO. */
+export declare const signInOptionsSchema: z.ZodObject<{
+    returnPathname: z.ZodOptional<z.ZodString>;
+    maxAge: z.ZodOptional<z.ZodNumber>;
+    loginHint: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        login: "login";
+        consent: "consent";
+        select_account: "select_account";
+    }>>;
+}, z.core.$strip>;
+export type SignInOptions = z.infer<typeof signInOptionsSchema>;
 export declare const authUserSchema: z.ZodObject<{
     sub: z.ZodString;
     email: z.ZodString;

package/dist/models.js

@@ -1,4 +1,12 @@
 import { z } from "zod";
+/** Options for a single authorization request. Omit prompt to allow provider SSO. */
+export const signInOptionsSchema = z.object({
+    returnPathname: z.string().optional(),
+    /** Maximum authentication age in seconds. Zero requests a fresh login. */
+    maxAge: z.number().int().nonnegative().optional(),
+    loginHint: z.string().min(1).optional(),
+    prompt: z.enum(["none", "login", "consent", "select_account"]).optional(),
+});
 export const authUserSchema = z.object({
     sub: z.string().min(1),
     email: z.string().min(1),

package/dist/provider.d.ts

@@ -1,5 +1,5 @@
 import type { OidcCallContext, OidcConfiguration } from "./config.js";
-import type { AuthUser } from "./models.js";
+import type { AuthUser, SignInOptions } from "./models.js";
 export type TokenSet = {
     accessToken: string;
     refreshToken?: string;
@@ -17,27 +17,31 @@ 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. */
+/** OAuth error code from an authorization response, including across bundles. */
+export declare function authorizationErrorCode(error: unknown): string | undefined;
 export declare function isAuthorizationDenied(error: unknown): boolean;
 export declare function createProvider(settings: OidcConfiguration, timeoutMs?: number): {
-    authorizationUrl: (input: Parameters<({ redirectUri, state, nonce, codeVerifier, }: {
+    authorizationUrl: (input: Parameters<({ maxAge, loginHint, prompt, redirectUri, state, nonce, codeVerifier, }: {
         redirectUri: string;
         state: string;
         nonce: string;
         codeVerifier: string;
-    }) => Promise<URL>>[0], context?: OidcCallContext) => Promise<URL>;
+    } & Pick<SignInOptions, "loginHint" | "prompt" | "maxAge">) => Promise<URL>>[0], context?: OidcCallContext) => Promise<URL>;
     exchangeCode: (url: URL, checks: Parameters<(callbackUrl: URL, checks: {
         state: string;
         nonce: string;
         codeVerifier: string;
+        maxAge?: number;
     }) => Promise<{
         user: AuthUser;
         tokens: TokenSet;
         idpSid?: string;
+        authTime?: number;
     }>>[1], context?: OidcCallContext) => Promise<{
         user: AuthUser;
         tokens: TokenSet;
         idpSid?: string;
+        authTime?: number;
     }>;
     refreshGrantTokens: (token: string, context?: OidcCallContext) => Promise<TokenSet>;
     refresh: (token: string, subject: string, context?: OidcCallContext) => Promise<RefreshedTokens>;

package/dist/provider.js

@@ -58,11 +58,14 @@ 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) {
+/** OAuth error code from an authorization response, including across bundles. */
+export function authorizationErrorCode(error) {
     return typeof error === "object" && error !== null
         && "code" in error && error.code === "OAUTH_AUTHORIZATION_RESPONSE_ERROR"
-        && "error" in error && error.error === "access_denied";
+        && "error" in error && typeof error.error === "string" ? error.error : undefined;
+}
+export function isAuthorizationDenied(error) {
+    return authorizationErrorCode(error) === "access_denied";
 }
 export function createProvider(settings, timeoutMs = PROVIDER_TIMEOUT_MS) {
     // The SDK caches discovery and JWKS clients and accepts a single transport hook.
@@ -136,10 +139,13 @@ export function createProvider(settings, timeoutMs = PROVIDER_TIMEOUT_MS) {
         return { config, response };
     }
     const api = {
-        async authorizationUrl({ redirectUri, state, nonce, codeVerifier, }) {
+        async authorizationUrl({ maxAge, loginHint, prompt, redirectUri, state, nonce, codeVerifier, }) {
             return client.buildAuthorizationUrl(await discover(), {
                 redirect_uri: redirectUri,
                 scope: settings.OIDC_SCOPES,
+                ...(loginHint && { login_hint: loginHint }),
+                ...(prompt && { prompt }),
+                ...(maxAge !== undefined && { max_age: String(maxAge) }),
                 state,
                 nonce,
                 code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),
@@ -152,11 +158,18 @@ export function createProvider(settings, timeoutMs = PROVIDER_TIMEOUT_MS) {
                 pkceCodeVerifier: checks.codeVerifier,
                 expectedState: checks.state,
                 expectedNonce: checks.nonce,
+                maxAge: checks.maxAge,
                 idTokenExpected: true,
             });
             const claims = response.claims();
             if (!claims?.sub)
                 throw new Error("ID token has no subject");
+            // openid-client validates the requested age. A future authentication time
+            // must never become evidence of a recent login as the local clock advances.
+            const authTime = claims.auth_time;
+            const inFuture = authTime !== undefined && authTime > Math.floor(Date.now() / 1000);
+            if (inFuture && checks.maxAge !== undefined)
+                throw new Error("ID token authentication time is in the future");
             let email = firstString(claims.email);
             const tokenRoles = roleList(claims[settings.OIDC_ROLES_CLAIM]);
             let info;
@@ -176,6 +189,7 @@ export function createProvider(settings, timeoutMs = PROVIDER_TIMEOUT_MS) {
                     roles: tokenRoles ?? roleList(info?.[settings.OIDC_ROLES_CLAIM]) ?? [],
                 },
                 tokens: tokenSet(response),
+                authTime: inFuture ? undefined : authTime,
                 // The provider's session id, matched by back-channel logout tokens.
                 idpSid: firstString(claims.sid) ?? undefined,
             };

package/dist/session.d.ts

@@ -22,6 +22,7 @@ declare const sessionSchema: z.ZodObject<{
     expiresAt: z.ZodNumber;
     sid: z.ZodString;
     issuedAt: z.ZodNumber;
+    authTime: z.ZodOptional<z.ZodNumber>;
     lastSeenAt: z.ZodNumber;
     idpSid: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;

package/dist/session.js

@@ -21,6 +21,8 @@ const sessionSchema = z.object({
     sid: z.string().min(1),
     /** Seconds since epoch of sign-in; bounds the absolute lifetime. */
     issuedAt: z.number(),
+    /** Provider authentication time from the sign-in ID token, in epoch seconds. */
+    authTime: z.number().nonnegative().optional(),
     /** Seconds since epoch of the last request; bounds the idle lifetime. */
     lastSeenAt: z.number(),
     /** The provider's session id (ID token `sid`), when it sends one. */

package/dist/state.d.ts

@@ -15,6 +15,7 @@ declare const flowStateSchema: z.ZodObject<{
     nonce: z.ZodString;
     codeVerifier: z.ZodString;
     returnPathname: z.ZodString;
+    maxAge: z.ZodOptional<z.ZodNumber>;
     issuedAt: z.ZodNumber;
 }, z.core.$strip>;
 export type FlowState = z.infer<typeof flowStateSchema>;

package/dist/state.js

@@ -13,6 +13,7 @@ const flowStateSchema = z.object({
     nonce: z.string().min(1),
     codeVerifier: z.string().min(1),
     returnPathname: z.string(),
+    maxAge: z.number().int().nonnegative().optional(),
     issuedAt: z.number(),
 });
 export class OidcStateError extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpshanley/oidc-start-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",