@ouim/logto-authkit 0.3.0

package/dist/server/verify-auth.d.ts

@@ -0,0 +1,296 @@
+import type { AuthContext, VerifyAuthOptions, ExpressRequest, ExpressResponse, ExpressNext, NextRequest } from './types.js';
+/**
+ * Remove the cached JWKS entry for a specific Logto tenant.
+ *
+ * Useful after rotating signing keys, changing proxy/network configuration,
+ * or when an operator wants the next verification to force a fresh JWKS fetch.
+ *
+ * @param {string} logtoUrl - Logto server URL whose JWKS cache entry should be removed.
+ */
+export declare function invalidateJwksCache(logtoUrl: string): void;
+/**
+ * Clear all cached JWKS entries held in this process.
+ *
+ * Useful in tests, long-lived worker processes, or admin/debug flows where
+ * you want the next verification for every tenant to fetch fresh keys.
+ */
+export declare function clearJwksCache(): void;
+/**
+ * Verify JWT Token from Logto
+ *
+ * Verifies a Logto JWT token by:
+ * 1. Decoding the JWT header to extract key ID (kid) and algorithm
+ * 2. Fetching the JWKS (JSON Web Key Set) from Logto's OIDC endpoint (cached, default 5 min TTL)
+ * 3. Finding the matching public key
+ * 4. Verifying the token signature
+ * 5. Validating the payload shape (all required/typed fields present)
+ * 6. Validating all claims (issuer, audience, expiration, scope, etc.)
+ *
+ * Key-rotation resilience: if step 3 or 4 fails with a key-related error (e.g. Logto
+ * rotated its signing keys and the cached JWKS no longer contains the new `kid`), the
+ * cache entry is invalidated and a single retry is attempted with freshly fetched JWKS.
+ * Claims errors (wrong audience, expired token, etc.) are NOT retried.
+ *
+ * @param {string} token - The JWT token to verify (typically from Authorization header or cookie)
+ * @param {VerifyAuthOptions} options - Verification options
+ * @param {string} options.logtoUrl - Logto server URL (e.g., 'https://tenant.logto.app')
+ * @param {string | string[]} [options.audience] - Expected token audience or audiences (resource/API identifier)
+ * @param {string} [options.requiredScope] - Required scope that must be present in token
+ * @param {string} [options.cookieName] - Cookie name for token storage (default: 'logto_authtoken')
+ * @param {boolean} [options.allowGuest] - Allow unauthenticated guest access
+ * @param {number} [options.jwksCacheTtlMs=300000] - How long to cache fetched JWKS keys in memory per process
+ * @param {boolean} [options.skipJwksCache=false] - When true, bypass the in-memory JWKS cache for this verification call
+ *
+ * @returns {Promise<AuthContext>} Authentication context with user ID, authentication status, and token payload
+ *
+ * @example
+ * try {
+ *   const auth = await verifyLogtoToken(token, {
+ *     logtoUrl: 'https://tenant.logto.app',
+ *     audience: 'urn:logto:resource:api'
+ *   });
+ *   console.log(auth.userId); // User ID from token
+ * } catch (error) {
+ *   console.error('Token verification failed:', error.message);
+ * }
+ *
+ * @throws {Error} If token format is invalid, signature verification fails, or claims validation fails
+ */
+export declare function verifyLogtoToken(token: string, options: VerifyAuthOptions): Promise<AuthContext>;
+/**
+ * Create Express Middleware for Logto Authentication
+ *
+ * Creates Express middleware that automatically extracts and verifies Logto JWT tokens
+ * from incoming requests. Handles token extraction from cookies or Authorization headers,
+ * validates tokens, and attaches authentication context to the request object.
+ *
+ * @param {VerifyAuthOptions} options - Middleware configuration options
+ * @param {string} options.logtoUrl - Logto server URL
+ * @param {string | string[]} [options.audience] - Expected token audience or audiences
+ * @param {string} [options.requiredScope] - Required scope
+ * @param {string} [options.cookieName='logto_authtoken'] - Cookie name for token
+ * @param {boolean} [options.allowGuest=false] - Allow unauthenticated access as guest
+ *
+ * @returns {Function} Express middleware function
+ *
+ * @example
+ * import express from 'express';
+ * import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server';
+ *
+ * const app = express();
+ *
+ * // Apply middleware to all routes
+ * app.use(createExpressAuthMiddleware({
+ *   logtoUrl: process.env.LOGTO_ENDPOINT,
+ *   audience: 'urn:logto:resource:api'
+ * }));
+ *
+ * // Access authenticated user
+ * app.get('/api/me', (req, res) => {
+ *   if (req.auth?.isAuthenticated) {
+ *     res.json({ userId: req.auth.userId });
+ *   } else {
+ *     res.status(401).json({ error: 'Unauthorized' });
+ *   }
+ * });
+ *
+ * @example
+ * // Allow guest access
+ * app.use(createExpressAuthMiddleware({
+ *   logtoUrl: process.env.LOGTO_ENDPOINT,
+ *   allowGuest: true
+ * }));
+ *
+ * // Distinguish authenticated vs guest users
+ * app.get('/api/data', (req, res) => {
+ *   if (req.auth?.isGuest) {
+ *     res.json({ data: 'limited data for guests' });
+ *   } else {
+ *     res.json({ data: 'full data for authenticated users' });
+ *   }
+ * });
+ */
+export declare function createExpressAuthMiddleware(options: VerifyAuthOptions): (req: ExpressRequest, res: ExpressResponse, next: ExpressNext) => Promise<void>;
+/**
+ * Verify Next.js Request Authentication
+ *
+ * Verifies Logto authentication for Next.js API routes and middleware.
+ * Extracts JWT from cookies or Authorization header, verifies the token,
+ * and returns authentication context.
+ *
+ * @param {NextRequest} request - Next.js request-like object. Supports both middleware-style requests with `cookies.get()`
+ *   and App Router route-handler `Request` objects that only expose `headers.get()`.
+ * @param {VerifyAuthOptions} options - Verification options
+ * @param {string} options.logtoUrl - Logto server URL
+ * @param {string | string[]} [options.audience] - Expected token audience or audiences
+ * @param {string} [options.requiredScope] - Required scope
+ * @param {string} [options.cookieName='logto_authtoken'] - Cookie name
+ * @param {boolean} [options.allowGuest] - Allow unauthenticated guest access
+ *
+ * @returns {Promise<{success: true, auth: AuthContext} | {success: false, error: string, auth?: AuthContext}>}
+ * - `success: true` — token verified **or** a valid guest session (`allowGuest: true`).
+ *   Always check `result.auth.isAuthenticated` (or `result.auth.isGuest`) to distinguish
+ *   authenticated users from guests; do NOT rely on `success` alone as an auth gate.
+ * - `success: false` — no token found and guest mode is disabled, or an unrecoverable error.
+ *
+ * @example
+ * // In a Next.js API route — reject unauthenticated requests
+ * import { verifyNextAuth } from '@ouim/logto-authkit/server';
+ *
+ * export async function GET(request) {
+ *   const result = await verifyNextAuth(request, {
+ *     logtoUrl: process.env.LOGTO_ENDPOINT,
+ *     audience: 'urn:logto:resource:api'
+ *   });
+ *
+ *   if (!result.success) {
+ *     return new Response(JSON.stringify({ error: result.error }), { status: 401 });
+ *   }
+ *
+ *   return new Response(JSON.stringify({
+ *     userId: result.auth.userId,
+ *     authenticated: result.auth.isAuthenticated
+ *   }));
+ * }
+ *
+ * @example
+ * // In Next.js middleware — allow guests, block fully unauthenticated requests
+ * import { NextRequest, NextResponse } from 'next/server';
+ * import { verifyNextAuth } from '@ouim/logto-authkit/server';
+ *
+ * export async function middleware(request: NextRequest) {
+ *   const result = await verifyNextAuth(request, {
+ *     logtoUrl: process.env.LOGTO_ENDPOINT,
+ *     allowGuest: true
+ *   });
+ *
+ *   // success:true covers both authenticated users and guests when allowGuest is set.
+ *   // Use auth.isAuthenticated (or auth.isGuest) to distinguish the two cases.
+ *   if (result.success && result.auth.isAuthenticated) {
+ *     return NextResponse.next();
+ *   }
+ *   if (result.success && result.auth.isGuest) {
+ *     return NextResponse.next(); // allow guest through, or redirect to limited view
+ *   }
+ *
+ *   return NextResponse.redirect(new URL('/login', request.url));
+ * }
+ */
+export declare function verifyNextAuth(request: NextRequest, options: VerifyAuthOptions): Promise<{
+    success: true;
+    auth: AuthContext;
+} | {
+    success: false;
+    error: string;
+    auth?: AuthContext;
+}>;
+/**
+ * Generic Token/Request Authentication Verification
+ *
+ * Universal verification function that works with any Node.js environment.
+ * Accepts either a JWT token string directly or a request object (Express, Next.js, etc.)
+ * and verifies the authentication.
+ *
+ * @param {string | {cookies?: any, headers?: any}} tokenOrRequest - Either:
+ *   - A JWT token string to verify directly
+ *   - A request-like object with cookies and headers properties
+ * @param {VerifyAuthOptions} options - Verification options
+ * @param {string} options.logtoUrl - Logto server URL
+ * @param {string | string[]} [options.audience] - Expected token audience or audiences
+ * @param {string} [options.requiredScope] - Required scope
+ * @param {string} [options.cookieName='logto_authtoken'] - Cookie name
+ * @param {boolean} [options.allowGuest] - Allow unauthenticated guest access
+ *
+ * @returns {Promise<AuthContext>} Authentication context
+ *
+ * @example
+ * // Verify a token directly
+ * const auth = await verifyAuth(jwtToken, {
+ *   logtoUrl: 'https://tenant.logto.app',
+ *   audience: 'urn:logto:resource:api'
+ * });
+ *
+ * @example
+ * // Verify from a request object
+ * const auth = await verifyAuth(request, {
+ *   logtoUrl: process.env.LOGTO_ENDPOINT,
+ *   allowGuest: true
+ * });
+ *
+ * @throws {Error} If token verification fails or no token found and guest mode disabled
+ */
+export declare function verifyAuth(tokenOrRequest: string | {
+    cookies?: unknown;
+    headers?: unknown;
+}, options: VerifyAuthOptions): Promise<AuthContext>;
+/**
+ * Build a `Set-Cookie` header string that sets the auth token as an `HttpOnly` cookie.
+ *
+ * ## Why this exists — the XSS / non-httpOnly problem
+ *
+ * The client-side `jwtCookieUtils.saveToken()` sets the auth token from JavaScript.
+ * Because `HttpOnly` can only be set by the **server** (via a `Set-Cookie` response
+ * header), the client-set cookie is readable by any same-origin JavaScript, including
+ * scripts injected by an XSS attack.
+ *
+ * If your deployment includes a backend (Express, Next.js, etc.) that handles the
+ * post-authentication callback, you can upgrade security by having the server re-set
+ * the cookie with `HttpOnly`. The browser will then attach it to every request
+ * automatically and JavaScript can no longer read it.
+ *
+ * ## Recommended flow
+ *
+ * ```
+ * 1. Frontend CallbackPage exchanges the auth code via Logto SDK (as normal).
+ * 2. Frontend sends the obtained JWT to a backend endpoint, e.g. POST /api/session.
+ * 3. Backend verifies the JWT with verifyLogtoToken(), then calls buildAuthCookieHeader()
+ *    and sets it on the response.
+ * 4. The browser now holds an HttpOnly cookie — the frontend no longer needs to store
+ *    the JWT in its own document.cookie.
+ * ```
+ *
+ * @param {string} token - The verified JWT string to store in the cookie.
+ * @param {object} [options]
+ * @param {string} [options.cookieName='logto_authtoken'] - Cookie name. Must match the
+ *   `cookieName` used by the backend middleware so it finds the token on subsequent requests.
+ * @param {number} [options.maxAge=604800] - Cookie lifetime in **seconds** (default: 7 days).
+ * @param {string} [options.domain] - Cookie domain (omit to use the current host).
+ * @param {string} [options.path='/'] - Cookie path.
+ * @param {'Strict'|'Lax'|'None'} [options.sameSite='Strict'] - SameSite policy.
+ *   Use `'None'` only if you need the cookie on cross-site requests (requires `Secure`).
+ *
+ * @returns {string} A complete `Set-Cookie` header value ready to pass to `res.setHeader`.
+ *
+ * @example
+ * // Express — upgrade to HttpOnly after verifying the token
+ * import express from 'express';
+ * import { verifyLogtoToken, buildAuthCookieHeader } from '@ouim/logto-authkit/server';
+ *
+ * app.post('/api/session', async (req, res) => {
+ *   const token = req.body.token; // JWT sent from the frontend after Logto callback
+ *   const auth = await verifyLogtoToken(token, { logtoUrl: process.env.LOGTO_ENDPOINT });
+ *   const cookie = buildAuthCookieHeader(token);
+ *   res.setHeader('Set-Cookie', cookie);
+ *   res.json({ userId: auth.userId });
+ * });
+ *
+ * @example
+ * // Next.js Route Handler — same pattern
+ * import { verifyLogtoToken, buildAuthCookieHeader } from '@ouim/logto-authkit/server';
+ *
+ * export async function POST(request: Request) {
+ *   const { token } = await request.json();
+ *   const auth = await verifyLogtoToken(token, { logtoUrl: process.env.LOGTO_ENDPOINT });
+ *   const cookie = buildAuthCookieHeader(token);
+ *   return new Response(JSON.stringify({ userId: auth.userId }), {
+ *     headers: { 'Content-Type': 'application/json', 'Set-Cookie': cookie },
+ *   });
+ * }
+ */
+export declare function buildAuthCookieHeader(token: string, options?: {
+    cookieName?: string;
+    maxAge?: number;
+    domain?: string;
+    path?: string;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}): string;

package/dist/signin.d.ts

@@ -0,0 +1,42 @@
+import type { SignInPageProps } from './types.js';
+/**
+ * SignInPage Component
+ *
+ * Internal page component that auto-initiates the sign-in flow. This is a special route
+ * that automatically starts the Logto sign-in process when loaded.
+ *
+ * In redirect flow:
+ * - If user is not authenticated, initiates sign-in redirect to Logto
+ * - User is redirected back to /callback after Logto authentication
+ * - Redirects to home page on success
+ *
+ * In popup flow (when opened from parent with ?popup=true):
+ * - Detects it's running in a popup (via window.opener or sessionStorage flag)
+ * - Initiates sign-in without opening nested popups
+ * - Notifies parent window via postMessage when complete
+ * - Self-closes the popup
+ *
+ * @component
+ *
+ * @example
+ * // Set up route for the sign-in page
+ * // In Next.js or React Router
+ * <Route path="/signin" component={SignInPage} />
+ *
+ * // AuthProvider with popup sign-in enabled
+ * <AuthProvider config={logtoConfig} enablePopupSignIn={true}>
+ *   <App />
+ * </AuthProvider>
+ *
+ * @param {string} [className] - CSS classes to apply to the loading/error container
+ * @param {React.ReactNode} [loadingComponent] - Custom loading UI shown while auth state is resolving
+ * @param {React.ReactNode | ((error: Error) => React.ReactNode)} [errorComponent] - Custom error UI shown if sign-in initiation fails
+ *
+ * @returns {React.ReactElement|null} Loading spinner during auth, null otherwise
+ *
+ * @see {@link CallbackPage} for the callback handler page
+ * @see {@link SignInButton} for a button component to trigger sign-in
+ *
+ * @internal
+ */
+export declare function SignInPage({ className, loadingComponent, errorComponent }: SignInPageProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+import type { LogtoConfig } from '@logto/react';
+export type LogtoUser = {
+    id: string;
+    name?: string;
+    email?: string;
+    avatar?: string;
+    [key: string]: any;
+};
+export type AuthMiddleware = 'auth' | 'guest' | undefined;
+export interface NavigationOptions {
+    replace?: boolean;
+    force?: boolean;
+}
+export interface AuthOptions {
+    middleware?: AuthMiddleware;
+    redirectTo?: string;
+    redirectIfAuthenticated?: string;
+    navigationOptions?: NavigationOptions;
+}
+export interface UsePermissionOptions {
+    claimKeys?: string[];
+    mode?: 'all' | 'any';
+}
+export interface AuthContextType {
+    user: LogtoUser | null;
+    isLoadingUser: boolean;
+    signIn: (callbackUrl?: string, usePopup?: boolean) => Promise<void>;
+    signOut: (options?: {
+        callbackUrl?: string;
+        global?: boolean;
+    }) => Promise<void>;
+    refreshAuth: () => Promise<void>;
+    enablePopupSignIn?: boolean;
+}
+export type AuthSignOutReason = 'user' | 'auth_error' | 'missing_access_token' | 'transient_error_limit';
+export interface AuthTokenRefreshEvent {
+    user: LogtoUser;
+    accessToken: string;
+    expiresAt?: number;
+    previousExpiresAt?: number;
+}
+export interface AuthErrorEvent {
+    error: Error;
+    isTransient: boolean;
+    willSignOut: boolean;
+}
+export interface AuthSignOutEvent {
+    reason: AuthSignOutReason;
+    global: boolean;
+    callbackUrl?: string;
+    error?: Error;
+}
+export interface AuthProviderProps {
+    children: React.ReactNode;
+    config: LogtoConfig;
+    callbackUrl?: string;
+    customNavigate?: (url: string, options?: NavigationOptions) => void;
+    enablePopupSignIn?: boolean;
+    onTokenRefresh?: (event: AuthTokenRefreshEvent) => void;
+    onAuthError?: (event: AuthErrorEvent) => void;
+    onSignOut?: (event: AuthSignOutEvent) => void;
+}
+export interface CallbackPageProps {
+    className?: string;
+    loadingComponent?: React.ReactNode;
+    successComponent?: React.ReactNode;
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+    /** URL to redirect to after successful authentication. Defaults to `'/'`. */
+    redirectTo?: string;
+}
+export interface SignInPageProps {
+    className?: string;
+    loadingComponent?: React.ReactNode;
+    errorComponent?: React.ReactNode | ((error: Error) => React.ReactNode);
+}
+export interface AdditionalPage {
+    link: string;
+    text: string;
+    icon?: React.ReactNode;
+}

package/dist/useAuth.d.ts

@@ -0,0 +1,55 @@
+import type { AuthOptions, AuthContextType } from './types.js';
+/**
+ * useAuth Hook
+ *
+ * Main hook to access authentication state and functions. Provides user information,
+ * loading state, and methods for sign-in/sign-out. Automatically handles route protection
+ * based on middleware configuration.
+ *
+ * @param {AuthOptions} [options] - Configuration options for auth behavior
+ * @param {AuthMiddleware} [options.middleware] - Route protection mode:
+ *   - `'auth'` - Protect route - redirects unauthenticated users to `redirectTo` URL
+ *   - `'guest'` - Guest-only route - redirects authenticated users to `redirectIfAuthenticated` URL
+ *   - `undefined` - No protection
+ * @param {string} [options.redirectTo] - URL to redirect to when middleware='auth' and user is not authenticated (default: '/signin')
+ * @param {string} [options.redirectIfAuthenticated] - URL to redirect to when middleware='guest' and user is authenticated
+ * @param {NavigationOptions} [options.navigationOptions] - Navigation behavior options
+ *
+ * @returns {AuthContextType} Object containing:
+ *   - `user` - Current user object or null if not authenticated
+ *   - `isLoadingUser` - Whether user data is still loading
+ *   - `signIn` - Function to initiate sign-in flow
+ *   - `signOut` - Function to sign out user
+ *   - `refreshAuth` - Function to manually refresh authentication state
+ *   - `enablePopupSignIn` - Whether popup sign-in is enabled
+ *
+ * @example
+ * // Access user data and sign-in/sign-out functions
+ * function Dashboard() {
+ *   const { user, isLoadingUser, signOut } = useAuth({ middleware: 'auth' })
+ *
+ *   if (isLoadingUser) return <div>Loading...</div>
+ *   if (!user) return null // Would have redirected by middleware
+ *
+ *   return (
+ *     <div>
+ *       Welcome, {user.name}!
+ *       <button onClick={() => signOut()}>Sign Out</button>
+ *     </div>
+ *   )
+ * }
+ *
+ * @example
+ * // Protect a guest-only login page
+ * function LoginPage() {
+ *   const { user } = useAuth({
+ *     middleware: 'guest',
+ *     redirectIfAuthenticated: '/dashboard'
+ *   })
+ *
+ *   return <div>Sign in form...</div>
+ * }
+ *
+ * @throws {Error} If used outside of AuthProvider context
+ */
+export declare const useAuth: (options?: AuthOptions) => AuthContextType;

package/dist/usePermission.d.ts

@@ -0,0 +1,9 @@
+import type { UsePermissionOptions } from './types.js';
+/**
+ * Return `true` when the current frontend auth user contains the requested permission claim.
+ *
+ * Reads the client-side `user` object exposed by `AuthProvider`, which is built from
+ * Logto's frontend claims. This is intended for conditional rendering only. Use the
+ * backend verifier helpers for authoritative server-side authorization decisions.
+ */
+export declare function usePermission(permission: string | string[], options?: UsePermissionOptions): boolean;

package/dist/user-center.d.ts

@@ -0,0 +1,49 @@
+import React from 'react';
+import type { AdditionalPage } from './types.js';
+/**
+ * UserCenter Component
+ *
+ * User profile and account management dropdown component. Displays the current user's
+ * avatar and name in a dropdown menu with sign-out and additional custom pages.
+ *
+ * Features:
+ * - Displays user avatar with fallback initials
+ * - Dropdown menu with user options
+ * - Sign-out functionality with configurable redirect
+ * - Support for additional custom pages/links
+ * - Dark mode support
+ * - Prevents hydration issues with client-only rendering
+ *
+ * @component
+ * @param {string} [className] - CSS classes for the container element
+ * @param {boolean} [globalSignOut=false] - Whether to perform global sign-out (logs out of entire Logto ecosystem) or local only
+ * @param {string} [signoutCallbackUrl] - URL to redirect to after sign-out (default: current page)
+ * @param {AdditionalPage[]} [additionalPages] - Array of custom pages/links to show in dropdown
+ * @param {string} [themeClassnames] - Tailwind classnames for theming (light/dark mode)
+ *
+ * @example
+ * // Basic user center
+ * <UserCenter />
+ *
+ * @example
+ * // With custom pages and dark mode
+ * <UserCenter
+ *   globalSignOut={false}
+ *   signoutCallbackUrl="/"
+ *   additionalPages={[
+ *     { link: '/settings', text: 'Settings', icon: <Settings /> },
+ *     { link: '/profile', text: 'Profile' }
+ *   ]}
+ *   themeClassnames="dark:bg-slate-900 dark:text-white bg-gray-50 text-gray-900"
+ * />
+ *
+ * @returns {React.ReactElement} Dropdown component with user profile
+ */
+export interface UserCenterProps {
+    className?: string;
+    globalSignOut?: boolean;
+    themeClassnames?: string;
+    signoutCallbackUrl?: string;
+    additionalPages?: AdditionalPage[];
+}
+export declare const UserCenter: React.FC<UserCenterProps>;