@elogroup-sereduc/ser-front-core-client 1.1.1 → 2.0.0

package/README.md

@@ -1,474 +1,229 @@
-# @elogroup-sereduc/ser-front-core-client
+# Ser Auth Library
 
-Keycloak-based authentication and API client for Portal do Aluno and Backoffices.
+Sistema de autenticação OAuth/OIDC compatível com Keycloak, desenvolvido como substituto para keycloak-js com suporte a Silent SSO, PKCE S256, e gerenciamento automático de tokens.
 
-## Features
+## Características
 
-- ✅ Keycloak authentication integration
-- ✅ Memory-only JWT token storage (secure)
-- ✅ Proactive token refresh (30-second threshold)
-- ✅ Axios-based API client with automatic Bearer token injection
-- ✅ TypeScript support with full type definitions
-- ✅ Configurable error handling
-- ✅ Authentication utilities and helpers
+- ✅ **Silent SSO**: Autenticação invisível via iframe
+- ✅ **PKCE S256**: Segurança para SPAs (Single Page Applications)
+- ✅ **Token Refresh**: Renovação automática de tokens
+- ✅ **API Client**: Cliente HTTP com interceptadores automáticos
+- ✅ **Route Guards**: Proteção de rotas para frameworks como TanStack Router
+- ✅ **Zustand Store**: Gerenciamento de estado em memória
+- ✅ **IDP Hint**: Suporte a redirecionamento automático para provedores específicos
 
-## Installation
+## Instalação
 
 ```bash
 npm install @elogroup-sereduc/ser-front-core-client
 ```
 
-## Quick Start
+## Setup Básico
 
-### Basic API Client
+### 1. Configuração Inicial
 
 ```typescript
-import { createApiClient } from "@elogroup-sereduc/ser-front-core-client";
-
-// Create an API client with Keycloak authentication
-const apiClient = createApiClient({
-  keycloak: {
-    url: "https://your-keycloak-server",
-    realm: "your-realm",
-    clientId: "your-client-id",
-  },
-  api: {
-    baseURL: "https://your-api-server",
-  },
-});
-
-// Use like a normal axios instance
-const users = await apiClient.get("/users");
-const newUser = await apiClient.post("/users", userData);
-```
-
-### Simple Client Factory
+import {
+  createKeycloakAuthFromUrl,
+  initAuth,
+} from "@elogroup-sereduc/ser-front-core-client";
 
-```typescript
-import { createSimpleApiClient } from "@elogroup-sereduc/ser-front-core-client";
+// Criar instância do SerOAuth
+const kc = createKeycloakAuthFromUrl(
+  "https://seu-keycloak.com/realms/seu-realm/protocol/openid-connect/auth",
+  "seu-client-id",
+  "seu-idp-hint", // opcional
+);
 
-const apiClient = createSimpleApiClient("https://your-api-server", {
-  url: "https://your-keycloak-server",
-  realm: "your-realm",
-  clientId: "your-client-id",
-});
+// Inicializar autenticação
+const authenticated = await initAuth(kc, "/seu-base-path");
 ```
 
-## Configuration
+### 2. Arquivo Silent-Check-SSO
 
-### Application Base Path Support
+Copie o arquivo `public/silent-check-sso.html` para a pasta `public` da sua aplicação.
 
-For applications that don't run at the domain root (e.g., `/portal-aluno`, `/backoffice`), configure the `basePath`:
+### 3. Context de Autenticação (React)
 
 ```typescript
-const config = {
-  keycloak: {
-    url: "https://your-keycloak-server",
-    realm: "your-realm",
-    clientId: "your-client-id",
-    basePath: "/portal-aluno", // Application base path
-  },
-  api: {
-    baseURL: "https://your-api-server",
-  },
-};
-
-const apiClient = createApiClient(config);
-```
-
-The `basePath` is used to construct correct redirect URIs for:
-
-- Silent SSO check redirects
-- Login/logout redirects
-- Error handling redirects
+import { useAuthStore } from '@elogroup-sereduc/ser-front-core-client'
 
-### KeycloakConfig
+export function AuthContext({ children }) {
+  const authState = useAuthStore()
 
-```typescript
-interface KeycloakConfig {
-  url: string; // Keycloak server URL
-  realm: string; // Keycloak realm
-  clientId: string; // Client ID
-  basePath?: string; // Application base path (e.g., '/portal-aluno', '/backoffice')
-  initOptions?: {
-    // Optional Keycloak initialization options
-    onLoad?: "login-required" | "check-sso";
-    silentCheckSsoRedirectUri?: string;
-    checkLoginIframe?: boolean;
-    // ... other KeycloakInitOptions
-  };
+  return (
+    <AuthProvider value={{
+      authenticated: authState.authenticated,
+      user: extractUserFromToken(authState.idToken),
+      login: () => kc.login(),
+      logout: () => kc.logout(),
+    }}>
+      {children}
+    </AuthProvider>
+  )
 }
 ```
 
-### ApiClientConfig
+### 4. Cliente API
 
 ```typescript
-interface ApiClientConfig {
-  baseURL: string; // API base URL
-  headers?: Record<string, string>; // Default headers
-  withCredentials?: boolean; // Include cookies (default: true)
-  onTokenRefreshFailed?: (error: Error) => void; // Custom error handler
-  loginRedirectUrl?: string; // Custom login redirect URL
-}
-```
-
-### Login Interfaces
+import { createApiClient } from "@elogroup-sereduc/ser-front-core-client";
 
-```typescript
-interface DirectLoginCredentials {
-  username: string; // Username for direct login
-  password: string; // Password for direct login
-}
+const api = createApiClient(kc, "https://sua-api.com");
 
-interface LoginOptions {
-  redirectUri?: string; // Custom redirect URI after login
-  credentials?: DirectLoginCredentials; // For direct login (internal users)
-  loginHint?: string; // Login hint for external login
-  prompt?: "none" | "login" | "consent" | "select_account"; // OIDC prompt parameter
-}
+// O cliente automaticamente:
+// - Adiciona Bearer token nos headers
+// - Renova token em caso de 401
+// - Retenta requisição com novo token
 ```
 
-## Authentication Management
-
-### Login Types
-
-This package supports three types of login:
-
-1. **External Login (Default)**: Redirects to Keycloak login page
-2. **Direct Login (Internal Users)**: Uses username/password without external redirect
-3. **Silent Login**: Checks authentication status without user interaction
-
-### External Login (Standard Flow)
+### 5. Route Guards
 
 ```typescript
-import { createAuthService } from "@elogroup-sereduc/ser-front-core-client";
-
-const authService = await createAuthService({
-  url: "https://your-keycloak-server",
-  realm: "your-realm",
-  clientId: "your-client-id",
-});
-
-// Redirects user to Keycloak login page
-await authService.login();
-```
-
-### Direct Login (Internal Users)
-
-For internal users that don't need external redirect, you can use direct login with username/password:
+import { createAuthGuard } from "@elogroup-sereduc/ser-front-core-client";
+import { createFileRoute } from "@tanstack/react-router";
 
-```typescript
-import {
-  createAuthService,
-  type DirectLoginCredentials,
-  DirectLoginError,
-} from "@elogroup-sereduc/ser-front-core-client";
+const requireAuth = createAuthGuard(kc);
 
-const authService = await createAuthService(keycloakConfig);
-
-// Direct login without external redirect
-try {
-  await authService.login({
-    credentials: {
-      username: "internal.user@company.com",
-      password: "userPassword123",
-    },
-  });
-  console.log("User logged in successfully!");
-} catch (error) {
-  if (error instanceof DirectLoginError) {
-    console.error("Direct login failed:", error.message);
-    // Handle specific direct login errors:
-    // - Invalid credentials
-    // - Account locked
-    // - Client not configured for direct access
-  }
-}
+export const Route = createFileRoute("/protected")({
+  beforeLoad: requireAuth,
+  component: ProtectedComponent,
+});
 ```
 
-**📋 Keycloak Configuration Requirements for Direct Login:**
-
-1. In Keycloak Admin Console, go to your client settings
-2. Enable "Direct Access Grants Enabled" in the Capability config
-3. Ensure the client has the appropriate roles and scope mappings
-4. For production, consider IP restrictions and additional security measures
+## API Reference
 
-### Silent Login
-
-Silent login allows checking authentication status without user interaction, perfect for checking if a user is already logged in:
+### SerOAuth
 
 ```typescript
-import {
-  createAuthService,
-  AuthenticationError,
-} from "@elogroup-sereduc/ser-front-core-client";
+class SerOAuth {
+  constructor(config: SerOAuthConfig);
 
-const authService = await createAuthService(keycloakConfig);
-
-// Check if user is already authenticated silently
-try {
-  const isAuthenticated = await authService.silentLogin();
-  if (isAuthenticated) {
-    console.log("User is already logged in");
-    // Continue with app
-  } else {
-    console.log("User needs to login");
-    // Show login form or redirect to login
-  }
-} catch (error) {
-  console.error("Silent login check failed:", error);
-  // Fallback to normal login flow
-}
-```
-
-**📋 Keycloak Configuration Requirements for Silent Login:**
+  // Métodos principais
+  async init(options?: InitOptions): Promise<boolean>;
+  async login(options?: LoginOptions): Promise<void>;
+  async logout(options?: LogoutOptions): Promise<void>;
+  async updateToken(minValidity?: number): Promise<boolean>;
 
-1. In Keycloak Admin Console, add to Valid Redirect URIs:
-   - `https://your-domain.com/silent-callback`
-   - `https://your-domain.com/your-base-path/silent-callback` (if using basePath)
-2. Ensure "Standard Flow Enabled" is enabled
-3. Create `public/silent-callback.html` file (provided with package)
+  // Propriedades
+  get authenticated(): boolean;
+  get token(): string | null;
+  get refreshToken(): string | null;
+  get idToken(): string | null;
 
-### Mixed Login Scenarios
-
-You can handle both internal and external users in the same application:
-
-```typescript
-async function handleLogin(
-  isInternalUser: boolean,
-  credentials?: DirectLoginCredentials,
-) {
-  try {
-    if (isInternalUser && credentials) {
-      // Direct login for internal users
-      await authService.login({ credentials });
-    } else {
-      // External redirect for external users
-      await authService.login();
-    }
-  } catch (error) {
-    console.error("Login failed:", error);
-  }
+  // Callbacks
+  onAuthSuccess?: () => void;
+  onAuthError?: (err: unknown) => void;
+  onAuthLogout?: () => void;
+  onTokenExpired?: () => void;
+  onTokenRefreshed?: () => void;
 }
 ```
 
-### Manual Authentication
+### Configuração
 
 ```typescript
-import {
-  createAuthService,
-  getAuthState,
-} from "@elogroup-sereduc/ser-front-core-client";
-
-// Create standalone auth service
-const authService = await createAuthService({
-  url: "https://your-keycloak-server",
-  realm: "your-realm",
-  clientId: "your-client-id",
-});
-
-// Check authentication state
-const authState = getAuthState(authService);
-console.log("Is authenticated:", authState.isAuthenticated);
-
-// Login (external redirect)
-if (!authState.isAuthenticated) {
-  await authService.login();
-}
-
-// Direct login for internal users (no external redirect)
-if (!authState.isAuthenticated) {
-  await authService.login({
-    credentials: {
-      username: "internal.user@company.com",
-      password: "userPassword123",
-    },
-  });
-}
+type SerOAuthConfig = {
+  url: string; // https://seu-keycloak.com
+  realm: string; // nome-do-realm
+  clientId: string; // seu-client-id
+  idp?: string; // hint para IDP específico
+};
 
-// Logout
-await authService.logout();
+type InitOptions = {
+  onLoad?: "check-sso" | "login-required";
+  silentCheckSsoRedirectUri?: string;
+  pkceMethod?: "S256";
+};
 ```
 
-### Access Keycloak Service from API Client
+### Store (Zustand)
 
 ```typescript
-import { getKeycloakService } from "@elogroup-sereduc/ser-front-core-client";
-
-const apiClient = createApiClient(config);
-const keycloakService = getKeycloakService(apiClient);
-
-if (keycloakService) {
-  const authState = keycloakService.getAuthState();
-  console.log("User info:", authState.userInfo);
-}
+const authState = useAuthStore();
+// {
+//   accessToken: string | null
+//   refreshToken: string | null
+//   idToken: string | null
+//   accessExpiresAt: number | null
+//   authenticated: boolean
+//   setTokens: (tokens: TokenSet) => void
+//   clear: () => void
+// }
 ```
 
-## Authentication Utilities
+## Migração do keycloak-js
 
-### Token Management
+### Antes (keycloak-js)
 
 ```typescript
-import {
-  isTokenExpired,
-  parseTokenUserInfo,
-  hasRole,
-  getUserRoles,
-} from "@elogroup-sereduc/ser-front-core-client";
-
-// Check if token is expired
-const expired = isTokenExpired(token, 30); // 30-second buffer
+import Keycloak from "keycloak-js";
 
-// Parse user info from token
-const userInfo = parseTokenUserInfo(token);
+const keycloak = new Keycloak({
+  url: "https://keycloak.com",
+  realm: "myrealm",
+  clientId: "myclient",
+});
 
-// Check user roles
-const isAdmin = hasRole(token, "admin");
-const userRoles = getUserRoles(token);
+await keycloak.init({ onLoad: "check-sso" });
 ```
 
-### URL Building with Base Path
+### Depois (ser-auth)
 
 ```typescript
 import {
-  buildUrl,
-  logout,
-  redirectToLogin,
+  createSerOAuth,
+  initAuth,
 } from "@elogroup-sereduc/ser-front-core-client";
 
-// Build URLs with base path support
-const silentSsoUrl = buildUrl("/silent-check-sso.html", "/portal-aluno");
-// Result: 'https://domain.com/portal-aluno/silent-check-sso.html'
-
-const homeUrl = buildUrl("/", "/backoffice");
-// Result: 'https://domain.com/backoffice/'
-
-// Use with auth functions
-const keycloakService = getKeycloakService(apiClient);
-
-// Logout with base path
-await logout(keycloakService, undefined, "/portal-aluno");
+const kc = createSerOAuth({
+  url: "https://keycloak.com",
+  realm: "myrealm",
+  clientId: "myclient",
+});
 
-// Redirect to login with base path
-redirectToLogin(undefined, "/portal-aluno");
+await initAuth(kc);
 ```
 
-## Error Handling
-
-### Improved Error Messages
+## Exemplos Avançados
 
-The package now provides detailed error messages for common issues:
+### Custom Error Handling
 
 ```typescript
-import {
-  createAuthService,
-  AuthenticationError,
-} from "@elogroup-sereduc/ser-front-core-client";
+kc.onAuthError = (error) => {
+  console.error("Auth error:", error);
+  // Redirecionar para página de erro
+};
 
-try {
-  const authService = await createAuthService({
-    url: "https://invalid-keycloak-server",
-    realm: "nonexistent-realm",
-    clientId: "wrong-client-id",
-  });
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error("Detailed error:", error.message);
-    // Possible messages:
-    // - "Keycloak URL is required"
-    // - "Invalid Keycloak URL: ..."
-    // - "Cannot connect to Keycloak server at ..."
-    // - "Keycloak realm 'nonexistent-realm' not found"
-    // - "CORS error connecting to Keycloak..."
-  }
-}
+kc.onTokenExpired = () => {
+  console.log("Token expirado, renovando...");
+};
 ```
 
-### Default Behavior
-
-By default, when token refresh fails, the user is redirected to the login page.
-
-### Custom Error Handling
+### Múltiplas Instâncias
 
 ```typescript
-const apiClient = createApiClient({
-  keycloak: {
-    /* ... */
-  },
-  api: {
-    baseURL: "https://api.example.com",
-    onTokenRefreshFailed: (error) => {
-      console.error("Auth failed:", error);
-      // Custom handling - show modal, redirect to specific page, etc.
-      showAuthErrorModal();
-    },
-  },
+const adminKc = createSerOAuth({
+  url: "https://admin-sso.com",
+  realm: "admin",
+  clientId: "admin-client",
 });
-```
 
-## Silent SSO Setup
-
-For silent SSO, create a `silent-check-sso.html` file in your public folder:
-
-```html
-<!doctype html>
-<html>
-  <body>
-    <script>
-      parent.postMessage(location.href, location.origin);
-    </script>
-  </body>
-</html>
+const userKc = createSerOAuth({
+  url: "https://user-sso.com",
+  realm: "users",
+  clientId: "user-client",
+});
 ```
 
-Then configure your client:
+### Interceptação Customizada
 
 ```typescript
-const config = {
-  keycloak: {
-    url: "https://your-keycloak-server",
-    realm: "your-realm",
-    clientId: "your-client-id",
-    initOptions: {
-      onLoad: "check-sso",
-      silentCheckSsoRedirectUri: `${window.location.origin}/silent-check-sso.html`,
-    },
-  },
-  // ...
-};
-```
-
-## TypeScript Support
+const api = createApiClient(kc);
 
-Full TypeScript support with comprehensive type definitions:
-
-```typescript
-import type {
-  CoreClientConfig,
-  AuthState,
-  KeycloakConfig,
-  LoginOptions,
-  DirectLoginCredentials,
-  AuthenticationError,
-  TokenRefreshError,
-  DirectLoginError,
-} from "@elogroup-sereduc/ser-front-core-client";
+api.interceptors.request.use((config) => {
+  // Adicionar headers customizados
+  config.headers["X-Custom-Header"] = "value";
+  return config;
+});
 ```
-
-## Differences from portal-aluno-api-client
-
-- ✅ **Memory-only storage**: Tokens stored in memory (more secure)
-- ✅ **Proactive refresh**: Uses `updateToken(30)` before requests instead of 401/403 retry
-- ✅ **Keycloak integration**: OIDC-based authentication instead of session-based
-- ✅ **Per-client config**: Keycloak config provided per API client
-- ✅ **No retry logic**: Does not retry requests on auth failure
-- ✅ **Direct login support**: Internal users can login with username/password without external redirect
-- ✅ **Silent login support**: Check authentication status without user interaction using OIDC prompt=none
-- ✅ **Base path support**: Applications running in subfolders (e.g., /portal-aluno, /backoffice) are fully supported
-- ✅ **Mixed authentication**: Supports both internal (direct) and external (redirect) users in the same app
-- ✅ **Enhanced error handling**: Detailed error messages for debugging connection and configuration issues
-- ✅ **Automatic validation**: Configuration validation with specific error messages
-
-## License
-
-MIT

package/dist/{axios.d.ts → api-client.d.ts}

@@ -1,7 +1,7 @@
 import { type AxiosInstance } from "axios";
 import { KeycloakService } from "./keycloak.js";
-import type { CoreClientConfig, ApiClientConfig } from "./types/index.js";
+import type { CoreClientConfig } from "./types/index.js";
 export declare function createApiClient(config: CoreClientConfig): AxiosInstance;
-export declare function createSimpleApiClient(baseURL: string, keycloakConfig: CoreClientConfig["keycloak"], options?: Partial<ApiClientConfig>): AxiosInstance;
+export declare function createSimpleApiClient(config: CoreClientConfig): AxiosInstance;
 export declare function getKeycloakService(apiClient: AxiosInstance): KeycloakService | undefined;
-//# sourceMappingURL=axios.d.ts.map
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAc,EACZ,KAAK,aAAa,EAGnB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,kBAAkB,CAAC;AAM1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CA8EvE;AAyBD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAE7E;AAKD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,GACvB,eAAe,GAAG,SAAS,CAE7B"}

package/dist/{axios.js → api-client.js}

@@ -2,8 +2,14 @@ import axios from "axios";
 import { KeycloakService } from "./keycloak.js";
 import { AuthenticationError, TokenRefreshError } from "./types/index.js";
 export function createApiClient(config) {
-    const keycloakService = new KeycloakService(config.keycloak);
-    const initPromise = keycloakService.initialize();
+    const keycloakService = KeycloakService.getInstance(config.keycloak);
+    let initPromise;
+    if (!keycloakService.isInitialized) {
+        initPromise = keycloakService.initialize();
+    }
+    else {
+        initPromise = Promise.resolve(true);
+    }
     const apiClient = axios.create({
         baseURL: config.api.baseURL,
         withCredentials: config.api.withCredentials ?? true,
@@ -57,16 +63,10 @@ async function handleAuthenticationFailure(error, config) {
         window.location.href = redirectUrl;
     }
 }
-export function createSimpleApiClient(baseURL, keycloakConfig, options) {
-    return createApiClient({
-        keycloak: keycloakConfig,
-        api: {
-            baseURL,
-            ...options,
-        },
-    });
+export function createSimpleApiClient(config) {
+    return createApiClient(config);
 }
 export function getKeycloakService(apiClient) {
     return apiClient.keycloak;
 }
-//# sourceMappingURL=axios.js.map
+//# sourceMappingURL=api-client.js.map