@spfn/auth 0.1.0-alpha.1 → 0.1.0-alpha.87

package/dist/adapters/nextjs/server.d.ts

@@ -0,0 +1,246 @@
+import * as _spfn_core_client_nextjs from '@spfn/core/client/nextjs';
+import { InterceptorRule } from '@spfn/core/client/nextjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SessionData } from '../../lib/session.js';
+
+/**
+ * General Authentication Interceptor
+ *
+ * Handles authentication for all API requests except login/register
+ * - Session validation and renewal
+ * - JWT generation and signing
+ * - Expired session cleanup
+ */
+
+/**
+ * General Authentication Interceptor
+ *
+ * Applies to all /_auth/* paths except login/register/codes
+ * - Validates session
+ * - Generates JWT token
+ * - Refreshes session if needed
+ * - Clears expired sessions
+ */
+declare const generalAuthInterceptor: InterceptorRule;
+
+/**
+ * Login/Register Interceptor
+ *
+ * Automatically handles key generation and session management
+ * for login and register endpoints
+ */
+
+/**
+ * Login and Register Interceptor
+ *
+ * Request: Generates key pair and adds publicKey to request body
+ * Response: Saves privateKey to HttpOnly cookie
+ */
+declare const loginRegisterInterceptor: InterceptorRule;
+
+/**
+ * Key Rotation Interceptor
+ *
+ * Handles key rotation with new key generation and session update
+ */
+
+/**
+ * Key Rotation Interceptor
+ *
+ * Request: Generates new key pair and adds to body, authenticates with current key
+ * Response: Updates session with new privateKey
+ */
+declare const keyRotationInterceptor: InterceptorRule;
+
+/**
+ * All auth interceptors
+ *
+ * Execution order:
+ * 1. loginRegisterInterceptor - Handles login/register (key generation + session save)
+ * 2. keyRotationInterceptor - Handles key rotation (new key generation + session update)
+ * 3. generalAuthInterceptor - Handles all authenticated requests (session validation + JWT injection + session renewal)
+ */
+declare const authInterceptors: _spfn_core_client_nextjs.InterceptorRule[];
+
+interface RequireAuthProps {
+    /**
+     * Children to render if authenticated
+     */
+    children: ReactNode;
+    /**
+     * Path to redirect to if not authenticated
+     * @default '/login'
+     */
+    redirectTo?: string;
+    /**
+     * Fallback UI to show instead of redirecting
+     */
+    fallback?: ReactNode;
+}
+/**
+ * Require Authentication Guard
+ *
+ * Ensures user is logged in before rendering children
+ *
+ * @example
+ * ```tsx
+ * <RequireAuth redirectTo="/login">
+ *   <DashboardContent />
+ * </RequireAuth>
+ * ```
+ *
+ * @example With fallback
+ * ```tsx
+ * <RequireAuth fallback={<LoginPrompt />}>
+ *   <PrivateContent />
+ * </RequireAuth>
+ * ```
+ */
+declare function RequireAuth({ children, redirectTo, fallback, }: RequireAuthProps): Promise<react_jsx_runtime.JSX.Element>;
+
+interface RequireRoleProps {
+    /**
+     * Required role(s) - user must have at least one
+     */
+    roles: string | string[];
+    /**
+     * Children to render if user has required role
+     */
+    children: ReactNode;
+    /**
+     * Path to redirect to if user doesn't have role
+     * @default '/unauthorized'
+     */
+    redirectTo?: string;
+    /**
+     * Fallback UI to show instead of redirecting
+     */
+    fallback?: ReactNode;
+}
+/**
+ * Require Role Guard
+ *
+ * Ensures user has at least one of the specified roles
+ *
+ * @example Single role
+ * ```tsx
+ * <RequireRole roles="admin">
+ *   <AdminPanel />
+ * </RequireRole>
+ * ```
+ *
+ * @example Multiple roles (OR condition)
+ * ```tsx
+ * <RequireRole roles={['admin', 'manager']}>
+ *   <ManagementDashboard />
+ * </RequireRole>
+ * ```
+ *
+ * @example With fallback
+ * ```tsx
+ * <RequireRole roles="admin" fallback={<AccessDenied />}>
+ *   <AdminContent />
+ * </RequireRole>
+ * ```
+ */
+declare function RequireRole({ roles, children, redirectTo, fallback, }: RequireRoleProps): Promise<react_jsx_runtime.JSX.Element>;
+
+interface RequirePermissionProps {
+    /**
+     * Required permission(s) - user must have at least one
+     */
+    permissions: string | string[];
+    /**
+     * Children to render if user has required permission
+     */
+    children: ReactNode;
+    /**
+     * Path to redirect to if user doesn't have permission
+     * @default '/unauthorized'
+     */
+    redirectTo?: string;
+    /**
+     * Fallback UI to show instead of redirecting
+     */
+    fallback?: ReactNode;
+}
+/**
+ * Require Permission Guard
+ *
+ * Ensures user has at least one of the specified permissions
+ *
+ * @example Single permission
+ * ```tsx
+ * <RequirePermission permissions="user:delete">
+ *   <DeleteUserButton />
+ * </RequirePermission>
+ * ```
+ *
+ * @example Multiple permissions (OR condition)
+ * ```tsx
+ * <RequirePermission permissions={['user:delete', 'user:update']}>
+ *   <UserManagement />
+ * </RequirePermission>
+ * ```
+ *
+ * @example With fallback
+ * ```tsx
+ * <RequirePermission permissions="project:create" fallback={<UpgradePrompt />}>
+ *   <CreateProject />
+ * </RequirePermission>
+ * ```
+ */
+declare function RequirePermission({ permissions, children, redirectTo, fallback, }: RequirePermissionProps): Promise<react_jsx_runtime.JSX.Element>;
+
+/**
+ * Server-side auth utilities for guards
+ *
+ * Uses API to check permissions in real-time
+ */
+/**
+ * Get user role
+ */
+declare function getUserRole(): Promise<string | null>;
+/**
+ * Get user permissions
+ */
+declare function getUserPermissions(): Promise<string[]>;
+/**
+ * Check if user has any of the specified roles
+ */
+declare function hasAnyRole(requiredRoles: string[]): Promise<boolean>;
+/**
+ * Check if user has any of the specified permissions
+ */
+declare function hasAnyPermission(requiredPermissions: string[]): Promise<boolean>;
+
+/**
+ * Session helpers for Next.js
+ *
+ * Server-side only (uses next/headers)
+ */
+
+/**
+ * Public session information (excludes sensitive data)
+ */
+interface PublicSession {
+    /** User ID */
+    userId: string;
+}
+/**
+ * Save session to HttpOnly cookie
+ */
+declare function saveSession(data: SessionData, maxAge?: number): Promise<void>;
+/**
+ * Get session from HttpOnly cookie
+ *
+ * Returns public session info only (excludes privateKey, algorithm, keyId)
+ */
+declare function getSession(): Promise<PublicSession | null>;
+/**
+ * Clear session cookie
+ */
+declare function clearSession(): Promise<void>;
+
+export { type PublicSession, RequireAuth, type RequireAuthProps, RequirePermission, type RequirePermissionProps, RequireRole, type RequireRoleProps, SessionData, authInterceptors, generalAuthInterceptor as authenticationInterceptor, clearSession, generalAuthInterceptor, getSession, getUserPermissions, getUserRole, hasAnyPermission, hasAnyRole, keyRotationInterceptor, loginRegisterInterceptor, saveSession };