raffel 0.1.2

package/dist/http/oidc.d.ts

@@ -0,0 +1,310 @@
+/**
+ * OpenID Connect (OIDC) Authentication Middleware
+ *
+ * Extends OAuth2 with ID tokens, discovery, and backchannel logout support.
+ *
+ * @example
+ * import { oidc, discoverOidcProvider } from 'raffel/http'
+ *
+ * // Auto-discover provider configuration
+ * const provider = await discoverOidcProvider({
+ *   issuer: 'https://accounts.google.com',
+ *   clientId: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ * })
+ *
+ * app.use('/auth/*', oidc({
+ *   providers: [provider],
+ *   onSuccess: async (tokens, userInfo, provider, c) => {
+ *     const session = c.get('session')
+ *     session.set('user', userInfo)
+ *     return c.redirect('/dashboard')
+ *   }
+ * }))
+ */
+import type { HttpContextInterface } from './context.js';
+import type { HttpMiddleware } from './app.js';
+import type { OAuth2Tokens, OAuth2Provider, OAuth2Error } from './oauth2.js';
+/**
+ * OIDC provider configuration
+ * Extends OAuth2Provider with OIDC-specific endpoints
+ */
+export interface OidcProvider extends OAuth2Provider {
+    /**
+     * Issuer identifier URL
+     */
+    issuer: string;
+    /**
+     * JWKS (JSON Web Key Set) endpoint URL
+     */
+    jwksUri?: string;
+    /**
+     * End session endpoint URL (for front-channel logout)
+     */
+    endSessionUrl?: string;
+    /**
+     * Backchannel logout URL (for your app to receive logout notifications)
+     */
+    backchannelLogoutUri?: string;
+    /**
+     * Supported ID token signing algorithms
+     */
+    idTokenSigningAlgValues?: string[];
+}
+/**
+ * OIDC discovery document
+ */
+export interface OidcDiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint?: string;
+    jwks_uri?: string;
+    end_session_endpoint?: string;
+    backchannel_logout_supported?: boolean;
+    backchannel_logout_session_supported?: boolean;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    grant_types_supported?: string[];
+    id_token_signing_alg_values_supported?: string[];
+}
+/**
+ * OIDC user info (standard claims)
+ */
+export interface OidcUserInfo {
+    /**
+     * Subject (unique user identifier)
+     */
+    sub: string;
+    /**
+     * Full name
+     */
+    name?: string;
+    /**
+     * Given/first name
+     */
+    given_name?: string;
+    /**
+     * Family/last name
+     */
+    family_name?: string;
+    /**
+     * Profile page URL
+     */
+    profile?: string;
+    /**
+     * Profile picture URL
+     */
+    picture?: string;
+    /**
+     * Email address
+     */
+    email?: string;
+    /**
+     * Whether email is verified
+     */
+    email_verified?: boolean;
+    /**
+     * Locale
+     */
+    locale?: string;
+    /**
+     * Additional claims
+     */
+    [key: string]: unknown;
+}
+/**
+ * Decoded ID token claims
+ */
+export interface IdTokenClaims {
+    /**
+     * Issuer
+     */
+    iss: string;
+    /**
+     * Subject (user ID)
+     */
+    sub: string;
+    /**
+     * Audience (client ID)
+     */
+    aud: string | string[];
+    /**
+     * Expiration timestamp
+     */
+    exp: number;
+    /**
+     * Issued at timestamp
+     */
+    iat: number;
+    /**
+     * Auth time
+     */
+    auth_time?: number;
+    /**
+     * Nonce
+     */
+    nonce?: string;
+    /**
+     * Access token hash
+     */
+    at_hash?: string;
+    /**
+     * Session ID (for backchannel logout)
+     */
+    sid?: string;
+    /**
+     * Additional claims
+     */
+    [key: string]: unknown;
+}
+/**
+ * OIDC middleware options
+ */
+export interface OidcOptions<E extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * OIDC providers to support
+     */
+    providers: OidcProvider[];
+    /**
+     * Path prefix for OIDC routes
+     * @default '/auth'
+     */
+    pathPrefix?: string;
+    /**
+     * Login path pattern
+     * @default '/login/:provider'
+     */
+    loginPath?: string;
+    /**
+     * Callback path pattern
+     * @default '/callback/:provider'
+     */
+    callbackPath?: string;
+    /**
+     * Logout path
+     * @default '/logout'
+     */
+    logoutPath?: string;
+    /**
+     * Backchannel logout path
+     * @default '/backchannel-logout'
+     */
+    backchannelLogoutPath?: string;
+    /**
+     * Success callback after authentication
+     */
+    onSuccess: (tokens: OAuth2Tokens, userInfo: OidcUserInfo, provider: OidcProvider, c: HttpContextInterface<E>) => Response | Promise<Response>;
+    /**
+     * Error callback
+     */
+    onError?: (error: OAuth2Error, provider: OidcProvider | null, c: HttpContextInterface<E>) => Response | Promise<Response>;
+    /**
+     * Logout callback (front-channel)
+     */
+    onLogout?: (provider: OidcProvider | null, c: HttpContextInterface<E>) => Response | Promise<Response>;
+    /**
+     * Backchannel logout callback
+     */
+    onBackchannelLogout?: (sub: string, sid: string | undefined, provider: OidcProvider, c: HttpContextInterface<E>) => void | Promise<void>;
+    /**
+     * Callback URL generator
+     */
+    getCallbackUrl?: (provider: OidcProvider, c: HttpContextInterface<E>) => string;
+    /**
+     * Validate ID token
+     * @default true (basic validation)
+     */
+    validateIdToken?: boolean;
+    /**
+     * Fetch user info from userinfo endpoint
+     * @default true
+     */
+    fetchUserInfo?: boolean;
+}
+/**
+ * Options for discovering OIDC provider
+ */
+export interface DiscoverOidcProviderOptions {
+    /**
+     * Issuer URL (e.g., 'https://accounts.google.com')
+     */
+    issuer: string;
+    /**
+     * Client ID
+     */
+    clientId: string;
+    /**
+     * Client secret
+     */
+    clientSecret: string;
+    /**
+     * Override scopes (otherwise uses scopes_supported from discovery)
+     */
+    scopes?: string[];
+    /**
+     * Provider name (defaults to issuer hostname)
+     */
+    name?: string;
+}
+/**
+ * Discover OIDC provider configuration from well-known endpoint
+ *
+ * @param options - Discovery options
+ * @returns OIDC provider configuration
+ *
+ * @example
+ * const googleProvider = await discoverOidcProvider({
+ *   issuer: 'https://accounts.google.com',
+ *   clientId: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ * })
+ */
+export declare function discoverOidcProvider(options: DiscoverOidcProviderOptions): Promise<OidcProvider>;
+/**
+ * Create OIDC authentication middleware
+ *
+ * Handles OpenID Connect authentication flow with ID tokens and backchannel logout.
+ *
+ * @param options - OIDC configuration
+ * @returns Middleware function
+ *
+ * @example
+ * app.use('/auth/*', oidc({
+ *   providers: [googleProvider, azureProvider],
+ *   onSuccess: async (tokens, userInfo, provider, c) => {
+ *     // userInfo contains claims from ID token + userinfo endpoint
+ *     const session = c.get('session')
+ *     session.set('user', {
+ *       id: userInfo.sub,
+ *       email: userInfo.email,
+ *       name: userInfo.name,
+ *       picture: userInfo.picture,
+ *       provider: provider.name,
+ *     })
+ *     session.set('idToken', tokens.idToken)
+ *     return c.redirect('/dashboard')
+ *   },
+ *   onBackchannelLogout: async (sub, sid, provider) => {
+ *     // Invalidate session for user
+ *     await sessionStore.destroyBySub(sub)
+ *   }
+ * }))
+ */
+export declare function oidc<E extends Record<string, unknown> = Record<string, unknown>>(options: OidcOptions<E>): HttpMiddleware<E>;
+/**
+ * Build front-channel logout URL
+ *
+ * @param provider - OIDC provider with endSessionUrl
+ * @param idToken - ID token for hint
+ * @param postLogoutRedirectUri - Where to redirect after logout
+ * @returns Logout URL
+ */
+export declare function buildLogoutUrl(provider: OidcProvider, idToken?: string, postLogoutRedirectUri?: string): string;
+declare const _default: {
+    oidc: typeof oidc;
+    discoverOidcProvider: typeof discoverOidcProvider;
+    buildLogoutUrl: typeof buildLogoutUrl;
+};
+export default _default;
+//# sourceMappingURL=oidc.d.ts.map

package/dist/http/oidc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../../src/http/oidc.ts"],"names":[],"mappings":"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"}