npm - @aifabrix/miso-client - Versions diffs - 4.4.0 → 4.4.2 - Mend

@aifabrix/miso-client 4.4.0 → 4.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/CHANGELOG.md +1259 -1234
package/README.md +21 -21
package/dist/api/applications.api.d.ts +42 -0
package/dist/api/applications.api.d.ts.map +1 -0
package/dist/api/applications.api.js +91 -0
package/dist/api/applications.api.js.map +1 -0
package/dist/api/index.d.ts +5 -0
package/dist/api/index.d.ts.map +1 -1
package/dist/api/index.js +2 -0
package/dist/api/index.js.map +1 -1
package/dist/api/types/applications.types.d.ts +65 -0
package/dist/api/types/applications.types.d.ts.map +1 -0
package/dist/api/types/applications.types.js +16 -0
package/dist/api/types/applications.types.js.map +1 -0
package/dist/api/types/encryption.types.d.ts +2 -2
package/dist/api/types/encryption.types.d.ts.map +1 -1
package/dist/index.d.ts +39 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +54 -1
package/dist/index.js.map +1 -1
package/dist/services/encryption.service.d.ts +1 -1
package/dist/services/encryption.service.js +2 -2
package/dist/services/encryption.service.js.map +1 -1
package/dist/utils/config-loader.js +2 -2
package/dist/utils/config-loader.js.map +1 -1
package/package.json +16 -15

package/CHANGELOG.md CHANGED Viewed

@@ -1,1234 +1,1259 @@
-# Changelog
-All notable changes to this project will be documented in this file.
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-## [4.4.0] - 2026-02-04
-### Changed
-- **Logging API Simplification (Breaking)** - Removed auto-computable request fields from the public logging surface
-  - Deprecated setters for request/user context (`withToken`, `addUser`, `addCorrelation`, `addApplication`) and removed `getWithToken`
-  - Introduced `withResponseMetrics(responseSize, durationMs)` to replace request-metric setters
-  - Public logging now relies on request middleware/AsyncLocalStorage for request/user context
-### Fixed
-- **Timer cleanup** - Unref’d internal timeouts/intervals to avoid keeping the process alive during tests
-- **Timeout handling** - Ensured request timeout promises are cleared on completion
-### Technical
-- **Tests** - Jest runs in-band with `--detectOpenHandles` for stability
-- **Docs/Examples** - Updated logging documentation and examples to reflect the simplified API
-## [4.3.1] - 2026-02-01
-### Fixed
-- **DataClient ApiRequestOptions** - Resolved type conflict between DataClient's `cache` option and `RequestInit.cache`
-  - `ApiRequestOptions` now extends `Omit<RequestInit, "cache">` so the DataClient-specific cache options object does not conflict with the standard fetch cache type
-- **InternalHttpClient post/put** - Prevented duplicate or conflicting request body when `config.data` was passed together with the body argument
-  - `post()` and `put()` now omit `data` from the config object before calling axios so the body is only passed via the second argument
-### Technical
-- **TypeScript config** - Added `DOM` to `lib` for fetch/RequestInit types, `preserveSymlinks: true`; Jest types limited to test config via `tsconfig.test.json`
-## [4.3.0] - 2026-01-27
-### Added
-- **Authentication Method Detection** - Enhanced 401 error responses with `authMethod` field to identify which authentication mechanism failed
-  - New `AuthErrorMethod` type: `'bearer' | 'api-key' | 'client-token' | 'client-credentials' | null`
-  - `MisoClientError.authMethod` property indicates which auth method caused the failure
-  - `ErrorResponse.authMethod` field included in structured error responses
-  - New `detectAuthMethodFromHeaders()` helper for client-side auth method detection when controller doesn't return it
-  - Exported `AuthErrorMethod` type and `detectAuthMethodFromHeaders` helper from SDK
-  - Unit tests for auth method detection and error handling
-### Technical
-- **Code Size Compliance** - Refactored `internal-http-client.ts` to comply with 500-line file limit
-  - Extracted client token management into new `client-token-manager.ts` (226 lines)
-  - Reduced `internal-http-client.ts` from 541 to 366 lines
-  - New helper functions: `generateCorrelationId()`, `createHttpAgent()`, `extractTokenFromResponse()`, `formatTokenFetchError()`, `fetchClientToken()`, `refreshClientTokenFromCallback()`, `isTokenValid()`
-## [4.2.0] - 2026-01-26
-### Added
-- **User Info Caching** - Added caching for `getUserInfo()` to reduce redundant controller API calls
-  - Cache key format: `user:{userId}` with configurable TTL (default 300 seconds / 5 minutes)
-  - Automatically extracts userId from JWT token for cache key generation
-  - Falls back to controller when cache miss or Redis unavailable
-  - New `clearUserCache(token)` method to invalidate cached user info
-  - `logout()` now clears user cache in addition to token cache
-  - New `userTTL` configuration option in `cache` settings
-### Changed
-- **RFC 7807 Compliance** - Improved error responses in `client-token-endpoint.ts`
-  - All 11 error responses now use RFC 7807 Problem Details format
-  - Added 504 Gateway Timeout to error type mappings
-  - Error responses include `type`, `title`, `status`, `detail`, and `instance` fields
-### Technical
-- **Code Quality Refactoring** - Refactored 13 methods across 11 files to comply with 30-line method limit
-  - `auth.service.ts`: Extracted `extractTokenFromEnvResponse()` helper
-  - `internal-http-client.ts`: Extracted `createHttpAgent()`, `extractTokenFromResponse()`, `formatTokenFetchError()`
-  - `client-token-endpoint.ts`: Extracted `extractHttpStatus()`, `isNetworkOrTimeoutError()`, `handleTokenError()`, `buildConfigResponse()`
-  - `role.service.ts`: Extracted `buildAuthStrategy()`, `getEnvironmentParams()`, `resolveUserId()`, `fetchRolesFromController()`
-  - `permission.service.ts`: Similar helper extraction pattern
-  - `config-loader.ts`: Extracted `loadRedisConfig()`, `loadAuthStrategy()`, `loadKeycloakConfig()`, `loadAllowedOrigins()`
-  - `errors.ts`: Extracted `transformErrorEnvelope()`, `transformDirectError()`
-  - `error-handler.ts`: Added lookup tables `PRISMA_ERROR_MAP`, `MESSAGE_PATTERN_MAP`, extracted `logError()`
-  - `error-types.ts`: Extracted `ERROR_TYPE_MAP`, `ERROR_TITLE_MAP` lookup tables
-  - `data-client.ts`: Extracted `checkCircuitBreaker()`, `recordFailure()`, `executeRequest()`
-  - `logger-context.middleware.ts`: Extracted `buildLoggerContext()`
-- File size reduction in `auth.service.ts` from 515 to 500 lines via JSDoc consolidation
-## [4.1.0] - 2026-01-21
-### Changed
-- **Encryption Key Parameter** - `encryptionKey` is now sent to the controller for server-side validation
-  - Added `encryptionKey` field to `EncryptRequest` and `DecryptRequest` interfaces
-  - `EncryptionService` validates encryption key is configured before API calls
-  - Throws `ENCRYPTION_KEY_REQUIRED` error with helpful message if key is missing
-### Added
-- `ENCRYPTION_KEY_REQUIRED` error code in `EncryptionError` class
-- Tests for encryption key validation in `EncryptionService`
-- Tests for `MISO_ENCRYPTION_KEY` environment variable loading in `config-loader`
-### Technical
-- `EncryptionError.parameterName` is now optional (not applicable for `ENCRYPTION_KEY_REQUIRED` errors)
-- `EncryptionService` constructor accepts optional `encryptionKey` parameter
-- `MisoClient` passes `config.encryptionKey` to `EncryptionService`
-## [4.0.0] - 2026-01-20
-### Breaking Changes
-- **Removed `EncryptionUtil` class** - Local encryption via `EncryptionUtil.encrypt()`/`decrypt()` is no longer supported. Use the new controller-based `client.encryption` service instead.
-- **Encryption Key Required** - The `encryptionKey` config option is now required for encryption operations
-  - Load from `MISO_ENCRYPTION_KEY` environment variable
-  - Or provide `encryptionKey` in `MisoClientConfig`
-  - Throws `ENCRYPTION_KEY_REQUIRED` error if not configured when using encrypt/decrypt
-### Migration Guide
-**Before (v3.x) - Local encryption:**
-```typescript
-import { EncryptionUtil } from '@aifabrix/miso-client';
-EncryptionUtil.initialize(); // Required ENCRYPTION_KEY env var
-const encrypted = EncryptionUtil.encrypt('my-secret');
-const decrypted = EncryptionUtil.decrypt(encrypted);
-```
-**After (v4.0) - Controller-based encryption:**
-```typescript
-import { MisoClient, loadConfig } from '@aifabrix/miso-client';
-// Option 1: Use environment variable (recommended)
-// Set MISO_ENCRYPTION_KEY in your .env file
-const client = new MisoClient(loadConfig());
-// Option 2: Provide in config
-const client = new MisoClient({
-  controllerUrl: 'https://miso-controller.example.com',
-  clientId: 'my-app',
-  clientSecret: 'secret',
-  encryptionKey: 'your-encryption-key', // Required for encryption operations
-});
-const result = await client.encryption.encrypt('my-secret', 'param-name');
-// result.value: 'kv://param-name' (Key Vault) or 'enc://v1:...' (local)
-// result.storage: 'keyvault' or 'local'
-const decrypted = await client.encryption.decrypt(result.value, 'param-name');
-```
-### Why This Change?
-- **Centralized key management** - Encryption keys are managed by the controller, validated server-side
-- **Azure Key Vault support** - Production environments can use Azure Key Vault for secure secret storage
-- **Application isolation** - Each application can only access its own encrypted parameters
-- **Audit logging** - All encryption/decryption operations are logged by the controller
-- **Security** - Encryption key prevents misuse of rotated or leaked application credentials
-### Added
-- `client.encryption.encrypt(plaintext, parameterName)` - Encrypt a value via controller
-- `client.encryption.decrypt(value, parameterName)` - Decrypt a value via controller
-- `EncryptionService` class - Service layer with parameter and encryption key validation
-- `EncryptionError` class - Error class with codes: `ENCRYPTION_FAILED`, `DECRYPTION_FAILED`, `INVALID_PARAMETER_NAME`, `ACCESS_DENIED`, `PARAMETER_NOT_FOUND`, `ENCRYPTION_KEY_REQUIRED`
-- `EncryptResult` type - Return type for encrypt operations
-- `EncryptionApi` class - API layer for controller communication
-- `encryptionKey` config option - For server-side encryption key validation
-- `MISO_ENCRYPTION_KEY` environment variable support in `loadConfig()`
-### Removed
-- `EncryptionUtil` class - Use `client.encryption` instead
-### Technical
-- **New files**: `src/api/encryption.api.ts`, `src/api/types/encryption.types.ts`, `src/services/encryption.service.ts`, `src/utils/encryption-error.ts`
-- **Deleted files**: `src/express/encryption.ts`
-- **Tests**: `tests/unit/api/encryption.api.test.ts`, `tests/unit/services/encryption.service.test.ts`
-## [3.9.0] - 2026-01-14
-### Added
-- **Enhanced Filter System** - Comprehensive filter parsing, validation, and SQL compilation
-  - **Dual format parsing**: Support for both colon format (`status:eq:active`) and JSON format (`{"status":{"eq":"active"}}`)
-  - **Schema-based validation**: Define filterable fields, allowed operators, and value types per resource
-  - **Type coercion**: Automatic value validation and conversion for string, number, boolean, uuid, timestamp, and enum types
-  - **SQL compilation**: Generate PostgreSQL-safe parameterized WHERE clauses with `compileFilter()`
-  - **Human-readable errors**: RFC 7807 compliant structured error responses with error codes (UNKNOWN_FIELD, INVALID_OPERATOR, INVALID_TYPE, etc.)
-  - New `ilike` operator for case-insensitive pattern matching
-  - New types: `FilterSchema`, `FilterFieldDefinition`, `FilterError`, `CompiledFilter`
-  - New utilities: `validateFilter()`, `coerceValue()`, `compileFilter()`, `createFilterSchema()`
-  - Filter meta-schema for validating custom filter schemas (`src/schemas/filter.schema.json`)
-### Changed
-- **Code Size Compliance** - Refactored large files to comply with 500-line guideline
-  - `data-client.ts`: 995 → 416 lines (extracted to helper modules)
-  - `data-client-request.ts`: 683 → 280 lines
-  - `data-client-auth.ts`: 654 → 290 lines
-  - `internal-http-client.ts`: 741 → 496 lines
-  - `auth.service.ts`: 825 → 462 lines
-  - `index.ts`: 681 → 472 lines
-  - `logger.service.ts`: 597 → 480 lines
-- **Console Logging Audit** - Cleaned up debug logging
-  - Removed 10 debug `console.log` statements from `token-utils.ts` that could expose sensitive token data
-  - All remaining console calls are appropriate error/warning logs or guarded by debug checks
-### Technical
-- **New filter utilities**: `src/utils/filter-schema.utils.ts` (497 lines), `src/utils/filter-colon.utils.ts` (119 lines)
-- **New filter types**: `src/types/filter-schema.types.ts` (148 lines)
-- **New helper modules** for DataClient refactoring:
-  - `data-client-init.ts` - Initialization logic
-  - `data-client-permissions.ts` - Permission helpers
-  - `data-client-roles.ts` - Role helpers
-  - `data-client-response.ts` - Response processing
-  - `data-client-oauth.ts` - OAuth callback handling
-- **New HTTP helpers**: `http-error-handler.ts`, `http-response-validator.ts`
-- **New auth helper**: `auth-error-handler.ts` - Centralized auth error formatting
-- **New tests**: `filter-colon-format.test.ts` (178 lines), `filter-schema.utils.test.ts` (545 lines)
-- **Documentation**: Updated `docs/reference-utilities.md` with filter system examples
-## [3.8.2] - 2026-01-12
-### Added
-- **Keycloak Separate Private/Public URL Support** - Separate URLs for JWKS fetching and issuer validation
-  - New `authServerPrivateUrl` configuration option for server-side JWKS fetching (internal network)
-  - New `authServerPublicUrl` configuration option for browser-side and issuer validation (public network)
-  - New `resolveKeycloakUrl()` utility function that automatically detects environment and selects appropriate URL
-  - `validateTokenLocal()` now uses private URL for JWKS fetching on server, public URL for issuer validation
-  - Environment variable support: `KEYCLOAK_SERVER_URL` (maps to `authServerPrivateUrl`), `KEYCLOAK_PUBLIC_SERVER_URL` (maps to `authServerPublicUrl`)
-  - Maintains backward compatibility with existing `authServerUrl` configuration
-### Technical
-- **TokenValidationService** - Now uses `resolveKeycloakUrl()` for automatic URL resolution
-  - JWKS URI construction uses resolved URL (private on server, public on browser)
-  - Issuer validation always uses public URL (matches token's `iss` claim)
-  - `determineTokenType()` updated to use public URL for issuer matching
-- **controller-url-resolver.ts** - Added `resolveKeycloakUrl()` function (mirrors `resolveControllerUrl()` pattern)
-- **config-loader.ts** - Added Keycloak environment variable support
-- **Tests**: Comprehensive tests for `resolveKeycloakUrl()` and updated TokenValidationService tests
-## [3.8.1] - 2026-01-10
-### Changed
-- **Unified Application Context Service** - Centralized application and environment extraction
-  - New `ApplicationContextService` class to extract `application`, `applicationId`, and `environment` with consistent fallback logic
-  - Extracts from client token first (if available), then falls back to parsing `miso-controller-{environment}-{application}` format from clientId
-  - RoleService, PermissionService, LoggerService, and UnifiedLoggerService now use the unified service
-  - Reduces code duplication and ensures consistent behavior across all services
-  - Caches parsed results to avoid repeated extraction
-### Fixed
-- **Logger Context Application Fallback** - Fixed application fallback to use clientId when parsing fails
-  - Logger getter methods (`getLogWithRequest`, `getWithContext`, `getWithToken`) now properly fall back to `clientId` when `application` cannot be extracted from client token or parsed from clientId format
-  - Ensures application field is always populated in log entries, even when clientId format doesn't match expected pattern
-### Technical
-- **New service**: `src/services/application-context.service.ts` - Unified application context extraction (175 lines)
-- **Test coverage**: Comprehensive tests in `tests/unit/application-context.service.test.ts` (323 lines, 100% coverage)
-- **Code quality**: All services updated to use ApplicationContextService, reducing code duplication by ~50 lines
-## [3.8.0] - 2026-01-10
-### Added
-- **Unified Logging Interface**: New minimal API with automatic context extraction
-  - `getLogger()` factory function for automatic context detection from AsyncLocalStorage
-  - `setLoggerContext()` and `clearLoggerContext()` for manual context management
-  - `loggerContextMiddleware` Express middleware helper for automatic request context extraction
-  - AsyncLocalStorage-based context propagation across async boundaries
-  - Simplified API: `logger.info(message)`, `logger.error(message, error?)`, `logger.audit(action, resource, entityId?, oldValues?, newValues?)`
-  - Automatic context extraction from AsyncLocalStorage (set by Express middleware or manually)
-  - Works seamlessly in Express routes, service layers, and background jobs
-  - Zero configuration required when middleware is used
-### Documentation
-- Added unified logging examples and guides (`docs/examples/unified-logging.md`)
-- Updated Express middleware examples with unified logging pattern
-- Added background job logging examples with unified interface
-- Comprehensive API reference for UnifiedLogger interface in `docs/reference-services.md`
-## [3.7.2] - 2026-01-10
-### Added
-- **Comprehensive Integration Tests** - Full end-to-end integration tests for Auth and Logs API endpoints
-  - New `tests/integration/api-endpoints.integration.test.ts` with comprehensive endpoint coverage
-  - Tests all Auth and Logs endpoints against real controller using credentials from `.env`
-  - Validates endpoint paths, HTTP methods, request bodies, and response structures against OpenAPI specs
-  - Tests error cases (invalid tokens, missing params, etc.) with proper status code verification
-  - Gracefully skips tests if controller is unavailable (CI/CD friendly)
-  - New npm script `test:integration:api` for running integration tests
-### Changed
-- **Logger Service Refactoring** - Improved code organization and maintainability
-  - Moved logger service to modular structure in `src/services/logger/` directory
-  - Split `LoggerService` into focused modules: `logger-chain.ts`, `logger-context.ts`, `logger.service.ts`
-  - New barrel export `src/services/logger/index.ts` for cleaner imports
-  - Maintains backward compatibility (no breaking changes to public API)
-- **Error Handling Improvements** - Enhanced error handling across API layer
-  - Updated error handling in integration tests to gracefully skip unavailable controllers
-  - Improved error reporting and logging throughout API files
-  - Enhanced user information retrieval functionality
-- **Code Quality Improvements** - Refactoring for better readability and maintainability
-  - Updated various components for improved logging and error reporting
-  - Enhanced API response handling and validation
-  - Improved code organization and structure
-### Fixed
-- **Linting Issues** - Fixed ESLint errors in internal HTTP client
-  - Converted `require()` statements to use ESLint disable comments for Node.js-only code
-  - Fixed `@typescript-eslint/no-var-requires` errors in `src/utils/internal-http-client.ts`
-### Technical
-- **New test infrastructure**:
-  - Comprehensive integration test suite (`tests/integration/api-endpoints.integration.test.ts` - 554 lines)
-  - New npm script: `test:integration:api` for running integration tests
-  - Enhanced validation plans and summaries for API calls
-- **Code organization**:
-  - Logger service modularized into `src/services/logger/` directory structure
-  - Improved separation of concerns with focused modules
-  - Better code maintainability and testability
-- **Documentation**:
-  - Added endpoint validation summary documentation
-  - Updated validation plans for API calls
-## [3.7.1] - 2026-01-09
-### Added
-- **Enhanced Error Logging with Correlation IDs** - Comprehensive error logging system with structured error extraction
-  - New `extractErrorInfo()` utility in `src/utils/error-extractor.ts` for structured error information extraction
-  - New `logErrorWithContext()` utility in `src/utils/console-logger.ts` for enhanced console logging with correlation ID prefixes
-  - Supports all error types: `MisoClientError`, `ApiError`, `AuthenticationError`, `NetworkError`, `TimeoutError`, and generic `Error`
-  - Automatic correlation ID extraction from error responses or auto-generation when missing
-  - Enhanced error context includes endpoint, method, status codes, response bodies, and stack traces
-  - All API files updated with structured error logging (11 API files enhanced)
-  - DataClient and Express error handlers updated with enhanced logging
-- **Logger Service Getter Methods** - Public methods for external logger integration
-  - New `getLogWithRequest()` method - Extracts IP, method, path, userAgent, correlationId, userId from Express Request
-  - New `getWithContext()` method - Returns LogEntry with provided context and auto-generated correlation ID
-  - New `getWithToken()` method - Extracts userId, sessionId, applicationId from JWT token
-  - New `getForRequest()` method - Alias for `getLogWithRequest()` for consistency
-  - All methods return complete `LogEntry` objects for integration with external logger tables
-  - `generateCorrelationId()` method made public for consistent correlation ID generation
-- **Unified JSON Filter Model** - Standardized JSON format for all filter representations
-  - New filter operators: `isNull` and `isNotNull` for null/undefined checks
-  - JSON format parser supports multiple input formats: direct object, JSON string, URL-encoded JSON, array of filters
-  - Operator normalization (e.g., `equals` → `eq`, `>` → `gt`)
-  - Comprehensive validation with clear error messages and examples
-  - Filter conversion utilities: `filterQueryToJson()` and `jsonToFilterQuery()`
-  - Query string builder outputs URL-encoded JSON format
-  - Local filtering supports null checks with `isNull` and `isNotNull` operators
-- **Server Code Improvements** - Enhanced Express server error handling and logging
-  - Replaced all `console.log/error/warn` with MisoClient logger service
-  - All route handlers wrapped with `asyncHandler()` wrapper for automatic error handling
-  - Error middleware uses `handleRouteError()` from SDK for RFC 7807 compliance
-  - Error logger configured with MisoClient logger via `setErrorLogger()`
-  - All business logic errors use `AppError` for consistent error formatting
-  - Automatic correlation ID extraction and error logging with full context
-- **Frontend Code Improvements** - Enhanced React application error handling and code quality
-  - Centralized error handling utilities (`src/utils/error-handler.ts`)
-  - Centralized type definitions (`src/types/errors.ts`, `src/types/api.ts`)
-  - Input validation utilities (`src/utils/validation.ts`) for role names, permission names, endpoints
-  - Component refactoring: ApiTestingPage reduced from 589 to 79 lines (87% reduction)
-  - New custom hooks: `useApiTesting` for API testing logic, `useLoadingState` for loading state management
-  - Improved DataClientContext with retry logic and exponential backoff
-  - Simplified ErrorDetailsDialog component (115 lines, reduced from 193)
-- **Comprehensive Integration Tests** - Real integration tests for all auth and logs endpoints
-  - New `tests/integration/api-endpoints.integration.test.ts` with comprehensive endpoint coverage
-  - Tests all 24 auth endpoints against real controller using credentials from `.env`
-  - Tests all 15 logs endpoints with proper request/response validation
-  - Validates endpoint paths, HTTP methods, request bodies, and response structures against OpenAPI specs
-  - Tests error cases (invalid tokens, missing params, etc.) with proper status code verification
-  - Gracefully skips tests if controller is unavailable (CI/CD friendly)
-  - New npm script `test:integration:api` for running integration tests
-- **Logger Service Refactoring** - Improved code organization and maintainability
-  - Split `LoggerService` into modular structure following API layer pattern
-  - New `src/services/logger/logger-chain.ts` - LoggerChain class for method chaining
-  - New `src/services/logger/logger-context.ts` - Context extraction utilities (JWT, metadata, request)
-  - New `src/services/logger/index.ts` - Barrel export for logger modules
-  - Reduced main `logger.service.ts` from 866 lines to under 500 lines (code size compliance)
-  - Maintains backward compatibility (no breaking changes to public API)
-### Changed
-- **Error Logging** - Enhanced error logging across all API layer files
-  - All API files now use `extractErrorInfo()` and `logErrorWithContext()` for structured error logging
-  - Error logs include correlation ID prefixes: `[MisoClient] [correlation-id] Error details`
-  - Authentication errors have special handling with detailed context (authFlow: 'token_validation_failed')
-  - Enhanced audit logs include structured error info (errorType, errorCategory, httpStatusCategory)
-- **Filter Parsing** - Unified JSON format replaces colon-separated format
-  - Filter parser now accepts JSON format only: `{"field": {"op": value}}`
-  - Supports 12 operators: `eq`, `neq`, `in`, `nin`, `gt`, `lt`, `gte`, `lte`, `contains`, `like`, `isNull`, `isNotNull`
-  - FilterBuilder outputs JSON format (URL-encoded) in query strings
-  - Comprehensive validation with helpful error messages including examples
-- **Server Error Handling** - Standardized error handling patterns
-  - All route handlers use `asyncHandler()` wrapper (no manual try-catch needed)
-  - All errors automatically formatted as RFC 7807 Problem Details
-  - Error logger uses MisoClient logger with `forRequest()` for automatic context extraction
-  - Consistent error responses across all routes with correlation IDs
-- **Frontend Error Handling** - Centralized error handling patterns
-  - All components use shared error handling utilities
-  - RFC 7807 compliant error parsing with `parseError()` utility
-  - Consistent error message extraction with `getErrorMessage()` and `getErrorStatus()`
-  - Input validation integrated into authorization testing hooks
-- **API Layer Cleanup** - Removed duplicate code and improved code quality
-  - Removed duplicate roles/permissions methods from `AuthApi` class
-  - Removed `getRoles()`, `refreshRoles()`, `getPermissions()`, `refreshPermissions()` from `AuthApi`
-  - Services now use dedicated `RolesApi` and `PermissionsApi` classes (DRY principle)
-  - Removed unused endpoint constants and type imports from `AuthApi`
-  - Updated class JSDoc to reflect removed methods
-- **Error Handling Improvements** - Fixed duplicate throw statements across API layer
-  - Removed duplicate `throw error;` statements from `auth.api.ts`, `roles.api.ts`, `permissions.api.ts`
-  - Fixed duplicate throws in `logs-create.api.ts` and `logs-list.api.ts`
-  - Improved error handling consistency across all API files
-### Fixed
-- **Server Error Handling** - Fixed logic bug in server.ts (dead code removed)
-- **Server Logging** - Fixed inconsistent logging format (now uses MisoClient logger)
-- **Server Error Responses** - Fixed non-RFC 7807 error responses (now uses `handleRouteError()`)
-- **Frontend Component Size** - Fixed large component files exceeding 500-line limit
-  - ApiTestingPage: 589 → 79 lines (87% reduction)
-  - ConfigurationPage: 382 → 283 lines (26% reduction)
-- **Frontend Error Handling** - Fixed duplicate error handling logic across components
-- **Frontend Type Safety** - Fixed loose error typing with centralized type definitions
-- **Code Size Compliance** - Fixed logger service file size violation
-  - Refactored `LoggerService` from 866 lines to under 500 lines
-  - Split into focused modules: logger-chain.ts, logger-context.ts, index.ts
-  - Maintains all functionality while improving maintainability
-- **API Endpoint Validation** - Validated all endpoints against OpenAPI specifications
-  - Verified all 24 auth endpoints match OpenAPI spec paths and HTTP methods
-  - Verified all 15 logs endpoints match OpenAPI spec with proper request/response structures
-  - Confirmed audit logs include required fields (entityType, entityId, action) in data object
-  - Validated client token endpoints use correct paths (`/api/v1/auth/token` for legacy, `/api/v1/auth/client-token` for frontend)
-### Technical
-- **New utility files**:
-  - `src/utils/error-extractor.ts` - Error extraction utility (172 lines)
-  - `src/utils/console-logger.ts` - Enhanced console logger (72 lines)
-  - `src/utils/error-handler.ts` - Frontend error handling utilities (175 lines)
-  - `src/utils/validation.ts` - Frontend input validation utilities (139 lines)
-  - `src/types/errors.ts` - Frontend error type definitions (25 lines)
-  - `src/types/api.ts` - Frontend API type definitions (63 lines)
-- **Test coverage**:
-  - Error extraction utility: 18 tests (`tests/unit/utils/error-extractor.test.ts`)
-  - Console logger utility: 12 tests (`tests/unit/utils/console-logger.test.ts`)
-  - Logger getter methods: 31 tests (`tests/unit/services/logger-getter-methods.test.ts`)
-  - Filter utilities: 68 tests (`tests/unit/filter.utils.test.ts`)
-  - Frontend error handler: 21 tests (`server/frontend/src/utils/__tests__/error-handler.test.ts`)
-  - Frontend validation: 43 tests (`server/frontend/src/utils/__tests__/validation.test.ts`)
-  - Integration tests: Comprehensive tests for all 39 endpoints (`tests/integration/api-endpoints.integration.test.ts`)
-  - Total: 193+ new tests added, all passing
-- **New logger module structure**:
-  - `src/services/logger/logger-chain.ts` - LoggerChain class (method chaining support)
-  - `src/services/logger/logger-context.ts` - Context extraction utilities
-  - `src/services/logger/index.ts` - Barrel export
-  - `src/services/logger.service.ts` - Core LoggerService class (reduced to <500 lines)
-- **Code quality**:
-  - All new utilities follow camelCase naming convention
-  - All public methods have JSDoc comments with parameter types, return types, and examples
-  - File sizes within limits (all files ≤500 lines)
-  - Method sizes within limits (all methods ≤30 lines)
-  - Zero linting errors or warnings
-  - Proper error handling with try-catch for all async operations
-  - Removed duplicate code (roles/permissions methods from AuthApi)
-  - Fixed duplicate throw statements across API layer
-  - All endpoints validated against OpenAPI specs
-- **Documentation**:
-  - Updated `docs/reference-services.md` with logger getter methods documentation
-  - Updated `docs/reference-utilities.md` with filter JSON format examples
-  - Updated `server/README.md` with factory function pattern and error logger configuration
-  - Updated `docs/examples/express-middleware.md` with error logger configuration examples
-  - Updated `AuthApi` class JSDoc to remove references to removed methods
-  - Added integration test documentation explaining test structure and requirements
-## [3.6.0] - 2024-12-31
-### Added
-- **API Response Validation** - Runtime validation for API response structures
-  - New `validateSuccessResponse<T>()` type guard for standard success responses
-  - New `validatePaginatedResponse<T>()` type guard for paginated responses
-  - New `validateErrorResponse()` type guard for error responses (re-exports existing validation)
-  - New `getResponseType()` utility to determine response type (success, paginated, error)
-  - Response validation utilities in `src/utils/response-validator.ts` with comprehensive type guards
-  - All validation functions use TypeScript type guards for proper type narrowing
-  - Detailed validation error messages for debugging response structure mismatches
-- **Response Validation Configuration** - Configurable validation control
-  - New `validateResponses?: boolean` configuration option in `MisoClientConfig`
-  - Environment variable support: `MISO_VALIDATE_RESPONSES` (defaults to `true` in development, `false` in production)
-  - Validation is opt-in and backward compatible (doesn't break existing code)
-  - Non-breaking validation failures (logs warnings instead of throwing errors)
-### Changed
-- **HTTP Client Response Validation** - Enhanced HTTP client with response structure validation
-  - `InternalHttpClient` now validates all API responses when `validateResponses` is enabled
-  - All HTTP methods (`get`, `post`, `put`, `delete`, `request`, `authenticatedRequest`) validate responses
-  - Validation checks for standard success response format: `{ success: boolean, data?: T, message?: string, timestamp: string }`
-  - Validation checks for paginated response format: `{ data: T[], meta: {...}, links: {...} }`
-  - Validation handles both nested and flat response formats (backward compatibility)
-  - Validation failures log warnings with endpoint URL, expected structure, and actual response
-  - Graceful error handling - validation failures don't break existing functionality
-### Fixed
-- **Circuit breaker priority** - Fixed critical ordering issue where circuit breaker check now occurs before cache check
-  - Circuit breaker check moved before cache and pending request checks to prevent requests to failing endpoints
-  - Ensures failed endpoints are blocked even if cache is cleared, preventing unnecessary API calls during failures
-  - Improved error consistency by using `throw` instead of `Promise.reject()` for circuit breaker errors
-- **Cache key generation** - Fixed cache key generation to ensure HTTP method is always included
-  - Cache key now explicitly includes HTTP method from method parameter to ensure consistency
-  - Prevents potential cache key collisions when method might be undefined in options
-  - Ensures proper cache key generation for all HTTP methods (GET, POST, PUT, DELETE, etc.)
-### Technical
-- **New utility file**: `src/utils/response-validator.ts` - Response validation utilities (174 lines)
-  - Type guard functions for runtime type checking
-  - Support for success, paginated, and error response formats
-  - Comprehensive JSDoc documentation for all public functions
-  - Proper TypeScript type narrowing with type guards
-- **Test coverage**:
-  - Comprehensive tests in `tests/unit/utils/response-validator.test.ts` (413 lines)
-  - 36 test cases covering valid/invalid responses, edge cases, and backward compatibility
-  - Test coverage: **96.53%** (exceeds ≥80% requirement)
-    - Statements: 96.53% (167/173)
-    - Branches: 91.83% (45/49)
-    - Functions: 100% (4/4)
-    - Lines: 96.53% (167/173)
-  - All tests passing with execution time < 0.5 seconds
-- **Configuration updates**:
-  - Added `validateResponses?: boolean` to `MisoClientConfig` interface
-  - Added `MISO_VALIDATE_RESPONSES` environment variable support in config loader
-  - Defaults to `true` in development, `false` in production for performance
-- **Code quality**:
-  - All validation functions follow camelCase naming convention
-  - All public functions have JSDoc comments with parameter types and return types
-  - File size: 174 lines (≤500 lines requirement met)
-  - Method sizes: ≤30 lines (≤20-30 lines requirement met)
-  - Zero linting errors or warnings
-  - Proper error handling with try-catch for all async operations
-## [3.4.1] - 2025-12-30
-### Fixed
-- **Token validation caching** - Improved caching strategy for token validation
-  - Enhanced cache key generation using SHA-256 hash of token for security
-  - Smart TTL calculation based on token expiration with safety buffer
-  - Minimum TTL enforcement to prevent excessive API calls
-  - Better cache invalidation handling
-### Changed
-- **Error handling** - Enhanced error handling and logging for token retrieval
-  - Added detailed error responses for timeout scenarios in client token endpoint
-  - Updated AuthService to use shorter timeout for axios requests (aligns with handler timeout)
-  - Improved logging for token retrieval processes with controller URL details
-  - Integrated controller URL resolution in environment token utility for consistent URL handling
-### Technical
-- **Dependencies** - Updated dependencies and improved linting configuration
-  - Removed unnecessary "peer" flags from package-lock.json
-  - Updated linting scripts to ignore declaration files for better efficiency
-  - Updated package dependencies for improved functionality and performance
-## [3.4.0] - 2025-12-24
-### Added
-- **Local Token Validation** - JWKS-based JWT validation without API calls
-  - New `validateTokenLocal()` method for local JWT signature verification
-  - Supports Keycloak tokens and delegated OAuth provider tokens
-  - Dual-layer caching: JWKS keys (1 hour) + validation results (1 minute)
-  - `skipResultCache` option for high-security scenarios
-  - Auto-detection of token type based on issuer claim
-  - New `TokenValidationService` exported for advanced usage
-- **Keycloak Configuration** - Native Keycloak integration
-  - New `keycloak` config option in `MisoClientConfig`
-  - `setKeycloakConfig()` method for runtime configuration
-  - Audience validation support (opt-in via `verifyAudience`)
-- **Cache Management** - Fine-grained cache control
-  - `clearJwksCache(uri?)` - Clear JWKS key cache
-  - `clearValidationCache()` - Clear validation result cache
-  - `clearAllTokenCaches()` - Clear all caches
-### Changed
-- **Package Distribution** - Added CHANGELOG.md to npm package files
-### Dependencies
-- Added `jose` ^5.9.6 for JWT/JWKS operations
-## [3.3.0] - 2025-12-23
-### Added
-- **Centralized API layer** - Typed interfaces for all controller API calls
-  - New API layer in `src/api/` with domain-specific API classes (`AuthApi`, `RolesApi`, `PermissionsApi`, `LogsApi`)
-  - `ApiClient` class wraps `HttpClient` and organizes APIs by domain
-  - Centralized endpoint URLs as constants in each API class for maintainability
-  - All API request/response types use interfaces (not types) with camelCase naming convention
-  - Services can optionally use `ApiClient` instead of direct `HttpClient` calls (gradual migration pattern)
-  - Improved type safety and code organization for controller API interactions
-  - API classes are composed from specialized sub-modules to keep file sizes manageable
-### Changed
-- **Token validation enhancements** - Improved token acceptance criteria
-  - Updated token validation logic to accept both JWT and non-JWT token formats
-  - Enhanced validation to ensure tokens are non-empty and of reasonable length
-  - Improved error handling for token validation failures
-  - Updated unit tests to reflect changes in token acceptance criteria
-- **OAuth callback handling** - Enhanced error feedback
-  - Updated error handling in `handleOAuthCallback()` to provide clearer feedback on token validation failures
-  - Improved documentation for token validation and OAuth handling
-- **Service dependencies** - Optional API client support
-  - Services can now optionally include `ApiClient` for typed API access
-  - Allows for gradual migration from direct `HttpClient` usage to typed API layer
-  - Maintains backward compatibility with existing service implementations
-### Technical
-- **New API layer structure**:
-  - `src/api/index.ts` - Main `ApiClient` class
-  - `src/api/auth.api.ts` - Authentication API (composed from sub-modules)
-  - `src/api/roles.api.ts` - Roles API
-  - `src/api/permissions.api.ts` - Permissions API
-  - `src/api/logs.api.ts` - Logs API
-  - `src/api/types/` - API request/response type definitions
-- **Test coverage**:
-  - Updated mock patterns to include `ApiClient` for testing purposes
-  - Enhanced unit tests for token validation with new acceptance criteria
-- **Documentation**:
-  - Added API layer pattern documentation to project rules
-  - Updated usage examples to demonstrate API layer pattern
-  - Enhanced documentation for token validation and OAuth handling
-## [3.2.5] - 2025-12-22
-### Added
-- **Indexed logging fields** - Standardized indexed fields for improved query performance and observability
-  - New `extractLoggingContext()` utility function in `src/utils/logging-helpers.ts`
-  - Added indexed context fields to `LogEntry` interface: `sourceKey`, `sourceDisplayName`, `externalSystemKey`, `externalSystemDisplayName`, `recordKey`, `recordDisplayName`
-  - Added credential context fields: `credentialId`, `credentialType`
-  - Added request/response metrics: `requestSize`, `responseSize`, `durationMs`
-  - Added error classification fields: `errorCategory`, `httpStatusCategory`
-  - New `LoggerChain` methods: `withIndexedContext()`, `withCredentialContext()`, `withRequestMetrics()`
-  - Exported types: `IndexedLoggingContext`, `HasKey`, `HasExternalSystem`
-  - Improves query performance and root-cause analysis for audit logs
-- **Request context auto-extraction** - Automatic extraction of logging context from Express Request objects
-  - New `extractRequestContext()` utility function in `src/utils/request-context.ts`
-  - New `withRequest()` method on `LoggerChain` for automatic context extraction
-  - New `forRequest()` method on `LoggerService` for request-based logging
-  - Automatically extracts: IP address, HTTP method, path, user-agent, correlation ID, user from JWT, session ID, request ID
-  - Handles proxy IPs via `x-forwarded-for` header
-  - Reduces logging code from 10-15 lines to 2-3 lines per log call
-  - Exported `RequestContext` interface and `extractRequestContext` function
-- **Token validation caching** - Caching for token validation to reduce API calls
-  - Cache validation results by userId with 15-minute TTL (configurable via `config.cache?.tokenValidationTTL`)
-  - Cache key format: `token:${userId}` (consistent with roles/permissions caching)
-  - Automatic cache invalidation on logout (clears cache even if logout returns 400)
-  - New `clearTokenCache()` method in `AuthService` for manual cache clearing
-  - Extracts userId from JWT token before API call (avoids unnecessary validate API call)
-  - Graceful fallback to API call on cache failures
-  - Uses `CacheService` instead of `RedisService` for consistency
-- **User token refresh** - Token refresh functionality for secure token renewal
-  - New `refreshToken()` method in `AuthService` for backend applications
-  - New `onTokenRefresh` callback support in `DataClient` for frontend applications
-  - Automatic token refresh on 401 errors in DataClient with retry logic
-  - New `RefreshTokenResponse` interface with `accessToken`, `refreshToken`, `expiresIn`, `expiresAt`
-  - Exposed `refreshToken()` method in `MisoClient` class
-  - Prevents infinite retry loops with `tokenRefreshAttempted` flag
-  - Refresh tokens never stored in browser localStorage (security requirement)
-- **OAuth callback handler** - ISO 27001 compliant OAuth callback handling with hash fragments
-  - New `handleOAuthCallback()` function in `src/utils/data-client-auth.ts`
-  - New `handleOAuthCallback()` method in `DataClient` class
-  - Extracts tokens from URL hash fragments (`#token=...`) instead of query parameters
-  - Immediate hash cleanup (< 100ms) to prevent token exposure
-  - Token format validation (JWT format check)
-  - HTTPS enforcement in production environments
-  - Supports multiple parameter names: `token`, `access_token`, `accessToken`
-  - Auto-calls on DataClient initialization in browser environments
-  - Secure error handling without exposing tokens
-### Changed
-- **LoggerService enhancements** - Enhanced logging capabilities with indexed fields
-  - Updated `ClientLoggingOptions` interface with indexed context fields
-  - Updated `LogEntry` interface with indexed fields for fast queries
-  - Enhanced `LoggerChain` fluent API with new context methods
-  - Improved developer experience with automatic request context extraction
-- **AuthService improvements** - Enhanced authentication service with caching
-  - Updated constructor to accept `CacheService` instead of `RedisService`
-  - Added `extractUserIdFromToken()` private method for JWT extraction
-  - Enhanced `validateToken()` method with caching logic
-  - Updated `logout()` method to clear token cache on logout
-- **DataClient enhancements** - Improved token refresh and OAuth handling
-  - Added `refreshUserToken()` private method for token refresh
-  - Enhanced 401 error handling with automatic token refresh and retry
-  - Updated `redirectToLogin()` documentation for hash fragment flow
-  - Improved OAuth callback handling with security measures
-### Fixed
-- **Token validation performance** - Reduced API calls through caching
-  - Token validation now uses cache to avoid unnecessary controller API calls
-  - Cache hit significantly improves performance for repeated validations
-- **OAuth security** - Improved security for OAuth callback flow
-  - Tokens extracted from hash fragments (not sent to server, not in logs)
-  - Immediate cleanup prevents token exposure in address bar
-  - HTTPS enforcement prevents token transmission over HTTP in production
-### Technical
-- **New utility files**:
-  - `src/utils/logging-helpers.ts` - Logging context extraction utility (91 lines)
-  - `src/utils/request-context.ts` - Request context extraction utility (102 lines)
-- **Test coverage**:
-  - Comprehensive tests for logging helpers (15 tests)
-  - Comprehensive tests for request context extraction (33 tests)
-  - Enhanced tests for token caching (80 tests total in auth.service.test.ts)
-  - Comprehensive tests for token refresh (17 AuthService + 15 DataClient tests)
-  - Comprehensive tests for OAuth callback handler (34 tests)
-- **Type definitions**:
-  - Added `RefreshTokenResponse` interface to `src/types/config.types.ts`
-  - Added `tokenValidationTTL?: number` to cache config type
-  - Added `onTokenRefresh` callback to `DataClientConfig` interface
-- **Exports updated**:
-  - `src/index.ts` - Exports `extractLoggingContext`, `IndexedLoggingContext`, `HasKey`, `HasExternalSystem`
-  - `src/index.ts` - Exports `extractRequestContext`, `RequestContext`
-  - `src/index.ts` - Exports `refreshToken()` method in `MisoClient`
-## [3.2.0] - 2025-12-22
-### Added
-- **Circuit breaker for HTTP logging** - Prevents infinite retry loops when logging service is unavailable
-  - Added circuit breaker pattern to `LoggerService` and `AuditLogQueue`
-  - Automatically disables HTTP logging after 3 consecutive failures
-  - Circuit breaker opens for 60 seconds after failures, then resets
-  - Prevents performance degradation when controller logging endpoint is unavailable
-  - Gracefully handles network errors and server unavailability
-- **DataClient redirect utilities** - Comprehensive redirect handling for login flows
-  - New `data-client-redirect.ts` utility module with robust redirect logic
-  - Enhanced `redirectToLogin()` with comprehensive error handling
-  - URL validation prevents dangerous redirects (javascript:, data:, etc.)
-  - User-friendly error messages for network, CORS, and authentication errors
-  - Proper timeout handling (30 seconds) to prevent hanging requests
-  - Only redirects when controller returns valid login URL (no fallback redirects on error)
-  - Supports both nested (`data.loginUrl`) and flat (`loginUrl`) response formats
-- **Client token expiration checking** - Enhanced token validation with JWT expiration support
-  - Improved `getClientToken()` to check JWT expiration claims when expiration timestamp is missing
-  - Decodes JWT tokens to extract `exp` claim for expiration validation
-  - Better logging for debugging token expiration issues
-  - Handles missing expiration timestamps gracefully
-  - Automatically removes expired tokens from cache
-- **Auto-initialization improvements** - New utility for accessing cached configuration
-  - New `getCachedDataClientConfig()` function exported from `src/index.ts`
-  - Allows reading cached DataClient configuration without re-initializing
-  - Useful for accessing configuration values in application code
-  - Returns cached config or null if not found or expired
-- **Controller URL validation utility** - Exported URL validation function
-  - `validateUrl()` function now exported from `controller-url-resolver.ts`
-  - Validates HTTP/HTTPS URLs with comprehensive JSDoc documentation
-  - Useful for validating URLs before use in application code
-  - Exported from `src/index.ts` for public use
-### Changed
-- **Documentation restructure** - Improved documentation organization and clarity
-  - New reference documentation structure with dedicated files for each major component
-  - Added `docs/reference-authentication.md` - Comprehensive authentication guide
-  - Added `docs/reference-authorization.md` - RBAC and permissions documentation
-  - Added `docs/reference-dataclient.md` - Complete DataClient API reference
-  - Added `docs/reference-errors.md` - Error handling and troubleshooting guide
-  - Added `docs/reference-misoclient.md` - MisoClient API reference
-  - Added `docs/reference-services.md` - Service layer documentation
-  - Added `docs/reference-types.md` - TypeScript type definitions reference
-  - Added `docs/reference-utilities.md` - Utility functions documentation
-  - Enhanced examples with improved clarity and error handling
-  - Updated all example files with corrected import paths
-- **DataClient enhancements** - Improved robustness and developer experience
-  - Enhanced DataClient configuration and performance optimizations
-  - Improved authorization examples and documentation
-  - Better error handling in example code
-- **Audit logging error handling** - Improved handling of network errors in audit logging
-  - Enhanced error detection for network errors (ECONNREFUSED, ENOTFOUND, ERR_CONNECTION_REFUSED)
-  - Silently skips audit logging for expected network errors (server unavailable, misconfigured)
-  - Prevents error noise in development and demo environments
-  - Better error classification and handling
-### Fixed
-- **DataClient metrics** - Fixed handling of missing response times in metrics
-  - Modified `getMetrics()` method to handle cases where `responseTimes` may be undefined
-  - Ensures robust performance metrics retrieval without errors
-- **Example imports** - Fixed import paths in all example files
-  - Updated example imports for clarity and proper error handling
-  - Corrected script source references in demo applications
-- **Cache service test handling** - Fixed cleanup interval keeping process alive in tests
-  - Added `unref()` to cleanup interval in `CacheService` to prevent tests from hanging
-  - Ensures Node.js process can exit cleanly after tests complete
-  - Important for CI/CD environments and test suites
-### Removed
-- **Performance logging** - Removed deprecated performance logging functionality
-  - Eliminated all performance logging code from the codebase
-  - Removed PerformanceMetrics interface and related methods
-  - Removed performance tracking logic from logger service
-  - Functionality replaced by OpenTelemetry integration
-### Technical
-- **Code quality improvements** - Enhanced development workflow and configuration
-  - Updated ESLint and Jest configurations for improved testing and code quality
-  - Enhanced configuration files and scripts for better development workflow
-  - Improved .gitignore patterns
-  - Updated package.json for testing enhancements
-- **New utility file**: `src/utils/data-client-redirect.ts` - Comprehensive redirect handling
-  - Extracted redirect logic from DataClient into dedicated utility module
-  - 424 lines of robust redirect handling with comprehensive error handling
-  - URL validation, timeout handling, and user-friendly error messages
-  - Proper separation of concerns for better maintainability
-## [3.1.2] - 2025-12-15
-### Changed
-- **DataClient refactoring** - Improved code organization and maintainability
-  - Extracted request execution logic into separate utility modules
-  - Split DataClient into focused utility files: `data-client-request.ts`, `data-client-auth.ts`, `data-client-cache.ts`, `data-client-utils.ts`
-  - Improved code organization and separation of concerns
-  - Reduced code complexity in main DataClient class
-### Fixed
-- **TypeScript error handling** - Fixed TypeScript error in retry logic
-  - Fixed type checking for error constructor name in authentication error detection
-  - Improved error type safety in retry logic
-### Technical
-- **Code quality improvements** - Significant refactoring for better maintainability
-  - Reduced DataClient.ts from ~1600 lines to ~500 lines through modularization
-  - Improved test coverage and organization
-  - Better separation of concerns between authentication, caching, and request execution
-## [3.1.1] - 2025-12-15
-### Fixed
-- **DataClient retry logic** - Improved handling of 401 authentication errors in retry logic
-  - Enhanced error type detection to prevent retries on authentication errors
-  - Added explicit checks for AuthenticationError instances to ensure 401/403 errors are not retried
-  - Improved statusCode extraction from error objects for more reliable retry decisions
-## [3.1.0] - 2025-12-15
-### Added
-- **Public and Private Controller URL Support** - Separate URLs for browser and server environments
-  - New `controllerPublicUrl` configuration option for browser/Vite environments (accessible from internet)
-  - New `controllerPrivateUrl` configuration option for server environments (internal network access)
-  - New `resolveControllerUrl()` utility function that automatically detects environment and selects appropriate URL
-  - New `isBrowser()` utility function for environment detection (checks for window, localStorage, fetch globals)
-  - Environment variable support: `MISO_WEB_SERVER_URL` (maps to `controllerPublicUrl` for browser)
-  - Environment variable support: `MISO_CONTROLLER_URL` (maps to `controllerPrivateUrl` for server, maintains backward compatibility)
-  - Automatic URL resolution based on environment:
-    - Browser environment: Uses `controllerPublicUrl` → falls back to `controllerUrl`
-    - Server environment: Uses `controllerPrivateUrl` → falls back to `controllerUrl`
-  - URL validation ensures resolved URLs are valid HTTP/HTTPS URLs
-  - Clear error messages when no URL is configured
-### Changed
-- **InternalHttpClient** - Now uses `resolveControllerUrl()` for automatic URL resolution
-  - Constructor uses resolved URL instead of hardcoded `config.controllerUrl`
-  - Client token fetch uses resolved URL for temporary axios instance
-  - Maintains backward compatibility with existing `controllerUrl` configuration
-- **AuthService** - Now uses `resolveControllerUrl()` for axios instance creation
-  - Automatically selects appropriate URL based on environment
-  - Maintains backward compatibility with existing configurations
-- **Config Loader** - Enhanced environment variable parsing
-  - `MISO_WEB_SERVER_URL` loads into `controllerPublicUrl` (browser/public)
-  - `MISO_CONTROLLER_URL` loads into `controllerPrivateUrl` (server/private) and `controllerUrl` (backward compatibility)
-  - Maintains existing behavior for applications using `MISO_CONTROLLER_URL`
-- **Documentation** - Updated configuration documentation
-  - Added sections for public/private URL configuration in `docs/configuration.md`
-  - Added examples for browser and server setup patterns
-  - Updated `docs/api-reference.md` with new utility functions and configuration options
-  - Includes migration guide and usage examples
-### Technical
-- **New utility file**: `src/utils/controller-url-resolver.ts` - URL resolution with environment detection
-  - `resolveControllerUrl()` function (35 lines, comprehensive JSDoc)
-  - `isBrowser()` helper function (7 lines)
-  - `validateUrl()` private helper function (7 lines)
-  - 100% test coverage (28 tests in `tests/unit/controller-url-resolver.test.ts`)
-- **Test coverage** - Comprehensive tests for URL resolution
-  - Browser environment detection tests (mocked window, localStorage, fetch)
-  - Server environment detection tests (no browser globals)
-  - URL resolution priority tests (public → private → controllerUrl → error)
-  - Backward compatibility tests (existing `controllerUrl` still works)
-  - Environment variable parsing tests (`MISO_WEB_SERVER_URL`, `MISO_CONTROLLER_URL`)
-  - URL validation tests (invalid URLs throw errors)
-  - Updated `tests/unit/config-loader.test.ts` with 52 new test lines
-  - Updated `tests/unit/http-client.test.ts` and `tests/unit/client.test.ts` with URL resolution tests
-- **Exports updated**:
-  - `src/index.ts` - Exports `resolveControllerUrl` and `isBrowser` utilities
-  - Public API maintains camelCase naming convention
-## [3.0.1] - 2025-12-14
-### Fixed
-- **DataClient audit logging bug** - Fixed 401 Unauthorized errors when audit logging unauthenticated requests
-  - Added `hasClientToken()` and `hasAnyToken()` helper methods to check authentication status
-  - `logAuditEvent()` now skips audit logging when no authentication token is available (user token OR client token)
-  - Prevents circular dependency where login requests trigger audit logging that requires authentication
-  - Gracefully handles audit logging errors without breaking main requests
-  - Improved error handling for 401 errors in audit logging (silently skipped for unauthenticated requests)
-### Changed
-- **Documentation improvements** - Updated documentation files to match project style and improve clarity
-  - `docs/api-reference.md` - Streamlined API documentation
-  - `docs/configuration.md` - Reduced verbosity, focused on practical examples (reduced from ~1522 to ~785 lines)
-  - `docs/data-client.md` - Improved clarity and consistency (reduced from ~1497 to ~926 lines)
-  - `docs/examples.md` - Consolidated examples, removed redundancy (reduced from ~1014 to ~991 lines)
-  - `docs/troubleshooting.md` - More action-oriented format, clearer solutions (reduced from ~965 to ~707 lines)
-  - All documentation now follows consistent "You need to:" / "Here's how:" patterns
-  - Removed jargon and technical verbosity
-  - Added consistent "✅ Use standard .env parameters" patterns throughout
-### Technical
-- **Test coverage** - Added tests for audit logging skip behavior
-  - Updated `tests/unit/data-client.test.ts` with 69 new lines of test coverage
-  - Tests verify audit logging is skipped for unauthenticated requests
-  - Tests verify audit logging still works for authenticated requests
-## [3.0.0] - 2025-12-14
-### Added
-- **Configurable client token endpoint** - Customizable client token URI for authentication
-  - New `clientTokenUri` configuration option in `MisoClientConfig` (defaults to `/api/v1/auth/token`)
-  - Environment variable support: `MISO_CLIENT_TOKEN_URI`
-  - Backward compatible with existing implementations
-  - Used by `AuthService.getEnvironmentToken()` method
-- **Origin validation for security** - CORS origin validation with wildcard port support
-  - New `allowedOrigins` configuration option in `MisoClientConfig`
-  - Environment variable support: `MISO_ALLOWED_ORIGINS` (comma-separated list)
-  - Supports wildcard ports: `http://localhost:*` (matches any port)
-  - New `validateOrigin()` utility function exported for use in miso-controller backend
-  - Checks `origin` header first, falls back to `referer` header
-  - Security-first approach: validates origin before calling controller
-- **Server-side environment token wrapper** - Secure token fetching with origin validation
-  - New `getEnvironmentToken()` server-side wrapper function
-  - Validates request origin before calling controller
-  - ISO 27001 compliant audit logging with masked client credentials
-  - Logs error and audit events on validation failures
-  - Exported from `src/index.ts` and `src/express/index.ts`
-- **Client token decoding utility** - Extract application and environment info from tokens
-  - New `extractClientTokenInfo()` utility function
-  - Decodes JWT client tokens without verification (no secret available)
-  - Supports multiple field name variations:
-    - `application` or `app`
-    - `environment` or `env`
-    - `applicationId` or `app_id`
-    - `clientId` or `client_id`
-  - Returns `ClientTokenInfo` interface with optional fields
-  - Exported from `src/index.ts` and `src/express/index.ts`
-- **DataClient `getEnvironmentToken()` method** - Browser-side token fetching with caching
-  - New public method for browser applications
-  - Checks localStorage cache first (`miso:client-token` and `miso:client-token-expires-at`)
-  - Fetches from backend endpoint if cache miss or expired
-  - Uses `clientTokenUri` from config or defaults to `/api/v1/auth/client-token`
-  - Supports absolute URLs and relative paths
-  - Handles nested and flat response formats
-  - ISO 27001 audit logging integration
-  - Automatic cache expiration handling
-- **DataClient `getClientTokenInfo()` method** - Extract token metadata in browser
-  - New public method to extract application/environment info from client token
-  - Checks cached token first, then config token
-  - Returns `ClientTokenInfo` object or `null` if no token available
-  - Useful for displaying current application/environment in UI
-  - Handles decode errors gracefully
-- **DataClient `logout()` method** - Logout functionality for browser applications
-  - Calls controller logout API to invalidate server-side session
-  - Clears authentication tokens from localStorage (all configured token keys)
-  - Clears HTTP response cache
-  - Redirects to logout URL or login page
-  - Supports optional `redirectUrl` parameter for custom redirect after logout
-  - Gracefully handles API failures (always clears local state)
-  - SSR compatible (no-op in non-browser environments)
-- **DataClient `logoutUrl` configuration** - Custom logout redirect URL
-  - Optional `logoutUrl` property in `DataClientConfig`
-  - Falls back to `loginUrl` config if not provided
-  - Supports both relative paths and absolute URLs
-  - Defaults to `/login` if neither `logoutUrl` nor `loginUrl` is configured
-### Changed
-- **AuthService `getEnvironmentToken()`** - Now uses configurable `clientTokenUri`
-  - Changed from hardcoded `/api/v1/auth/token` to `this.config.clientTokenUri || '/api/v1/auth/token'`
-  - Maintains backward compatibility (defaults to existing endpoint)
-  - Existing error handling and correlation ID generation preserved
-- **MisoClientConfig interface** - Added new configuration options
-  - New optional property: `clientTokenUri?: string`
-  - New optional property: `allowedOrigins?: string[]`
-- **DataClient configuration** - Added `logoutUrl` option to `DataClientConfig` interface
-  - New optional property: `logoutUrl?: string`
-  - Follows same pattern as `loginUrl` configuration
-### Technical
-- **New utility files**:
-  - `src/utils/origin-validator.ts` - Origin validation with wildcard port support
-  - `src/utils/environment-token.ts` - Server-side wrapper with audit logging
-  - `src/utils/token-utils.ts` - Client token decoding utility
-- **New test files**:
-  - `tests/unit/origin-validator.test.ts` - 22 tests covering origin validation
-  - `tests/unit/token-utils.test.ts` - 20 tests covering token decoding
-  - `tests/unit/environment-token.test.ts` - 10 tests covering server-side wrapper
-  - Updated `tests/unit/data-client.test.ts` - Added 22 new tests
-  - Updated `tests/unit/config-loader.test.ts` - Added 7 new tests
-  - Updated `tests/unit/auth.service.test.ts` - Added 4 new tests
-- **Exports updated**:
-  - `src/index.ts` - Exports `validateOrigin`, `getEnvironmentToken`, `extractClientTokenInfo`, and types
-  - `src/express/index.ts` - Exports same utilities for Express applications
-- **Documentation updated**:
-  - `docs/data-client.md` - Added sections for `getEnvironmentToken()` and `getClientTokenInfo()`
-  - Includes browser usage examples, server-side route examples, configuration examples, and security best practices
-## [2.2.1] - 2025-12-13
-### Fixed
-- **DataClient `redirectToLogin()`** - Fixed redirect to use controller login endpoint
-  - Now calls controller's `/api/v1/auth/login` endpoint with redirect parameter
-  - Properly constructs full redirect URL instead of relative path
-  - Falls back to static loginUrl when misoClient is unavailable or controller call fails
-### Changed
-- **DataClient `redirectToLogin()`** - Enhanced with optional redirect URL parameter
-  - Made method async to support controller API calls
-  - Added optional `redirectUrl` parameter (defaults to current page URL)
-  - Returns controller's login URL for proper OAuth flow handling
-## [2.2.0] - 2025-12-13
-### Added
-- **DataClient Browser Wrapper** - Browser-compatible HTTP client wrapper around MisoClient
-  - Enhanced HTTP client capabilities for React/front-end applications
-  - ISO 27001 compliant audit logging with configurable levels (minimal, standard, detailed, full)
-  - Automatic sensitive data masking using DataMasker before audit logging
-  - Request/response interceptors for custom request/response transformation
-  - Response caching with configurable TTL and cache size limits
-  - Automatic retry logic with exponential backoff for retryable errors
-  - Request deduplication for concurrent duplicate requests
-  - Request metrics tracking (response times, error rates, cache hit rates)
-  - Custom error types (NetworkError, TimeoutError, AuthenticationError)
-  - Browser compatibility checks with SSR support
-  - Token management from localStorage with multiple key support
-  - Automatic login redirect on authentication errors
-  - Support for all HTTP methods (GET, POST, PUT, PATCH, DELETE)
-  - Request cancellation via AbortController
-  - Per-request timeout support
-  - Integration with MisoClient for authentication and audit logging
-  - **Client Token Pattern** - Secure browser usage without exposing clientSecret
-    - Support for server-provided client tokens (`clientToken`, `clientTokenExpiresAt`)
-    - Token refresh callback pattern (`onClientTokenRefresh`) for browser applications
-    - Automatic token refresh with proactive expiration handling (60s buffer)
-    - Memory-only token storage (never persisted to localStorage)
-### Changed
-- **MisoClientConfig** - `clientSecret` is now optional when using client token pattern
-  - Added `clientToken?: string` - Pre-obtained client token for browser usage
-  - Added `clientTokenExpiresAt?: Date | string` - Token expiration tracking
-  - Added `onClientTokenRefresh?: () => Promise<{ token: string; expiresIn: number }>` - Refresh callback
-  - `InternalHttpClient` now supports both clientSecret (server-side) and clientToken (browser) patterns
-## [2.1.2] - 2025-12-11
-### Added
-- **Express.js Utilities** - Complete set of utilities for building Express.js REST APIs
-  - `ResponseHelper` - Standardized API response formatting (success, created, paginated, noContent, accepted)
-  - `injectResponseHelpers` - Middleware to inject response helpers into Express Response
-  - `asyncHandler` and `asyncHandlerNamed` - Automatic error handling for async route handlers
-  - `ValidationHelper` - Common validation patterns (findOrFail, ensureNotExists, ensureOwnershipOrAdmin, etc.)
-  - `AppError` - Application error class with RFC 7807 support
-  - `handleRouteError` - Centralized error handling for Express routes
-  - `setErrorLogger` - Injectable error logger for custom logging
-  - `EncryptionUtil` - AES-256-GCM encryption utility (replaces EncryptionService)
-  - Express Response type augmentation for TypeScript
-- **Sort Utilities** - Client-side sorting helpers
-  - `applySorting()` - Apply sorting to in-memory data arrays
-  - `parseSortParams()` - Parse sort query parameters (already existed)
-- **GitHub Workflows** - Manual release management
-  - Manual Version Bump workflow - Bump version, create git tags, and GitHub Releases
-  - Manual Publish to NPM workflow - Publish to npm with validation and verification
-- **Package Configuration**
-  - Express as optional peer dependency (^4.18.0 || ^5.0.0)
-  - @types/express as dev dependency
-- **Authentication API Updates**
-  - `LoginResponse` and `LogoutResponse` types for standardized authentication responses
-  - Updated `login()` method to make API call to `/api/v1/auth/login` with query parameters (redirect, state)
-  - Updated `logout()` method to accept token parameter and make API call to `/api/v1/auth/logout`
-  - Comprehensive test coverage for `response-middleware.ts` (100% coverage)
-### Changed
-- **Package Description** - Updated to include Express.js utilities
-- **EncryptionService** - Replaced instance-based EncryptionService with static EncryptionUtil class
-- **Workflow Strategy** - Removed automatic publish on push, added manual workflows for better control
-- **Authentication Methods** - Breaking changes:
-  - `login()` - Changed from synchronous method returning URL string to async method returning `LoginResponse` object
-  - `logout()` - Now requires `{ token: string }` parameter and returns `LogoutResponse` object
-### Removed
-- Old automatic npm-publish workflow (replaced by manual workflows)
-- EncryptionService class (replaced by EncryptionUtil)
-## [2.0.0] - Previous Release
-See git history for previous changes.
+# Changelog
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [4.4.2] - 2026-02-10
+### Technical
+- Release 4.4.2 – version bump and validation.
+## [4.4.1] - 2026-02-09
+### Added
+- **Application status and URLs (server-side)** - New SDK methods for updating and fetching application status
+  - `updateMyApplicationStatus(body, options?)` - Update current application's status, url, internalUrl, port via POST self/status
+  - `getApplicationStatus(envKey, appKey, authStrategy?)` - Fetch any application's status and URLs (without configuration)
+  - `getMyApplicationStatus(options?, authStrategy?)` - Fetch current application's status using context when envKey/appKey omitted
+  - Uses `ApplicationContextService` for default envKey/appKey when omitted (client token / clientId parsing)
+  - New types: `UpdateSelfStatusRequest`, `UpdateSelfStatusResponse`, `ApplicationStatusResponse`
+  - Endpoints: `POST /api/v1/environments/:envKey/applications/self/status`, `GET /api/v1/environments/:envKey/applications/:appKey/status`
+- **LoggerContextStorage** - Exported for background operation context (e.g. Keycloak sync, cron jobs)
+  - Use `LoggerContextStorage.getInstance().runWithContextAsync(context, async () => { ... })` for operations without request middleware
+### Changed
+- **Encryption key configuration** - Renamed environment variable from `MISO_ENCRYPTION_KEY` to `ENCRYPTION_KEY` across types, services, config loader, and tests for consistency
+- **README** - Updated API documentation links and usage instructions for the AI Fabrix Builder
+## [4.4.0] - 2026-02-04
+### Changed
+- **Logging API Simplification (Breaking)** - Removed auto-computable request fields from the public logging surface
+  - Deprecated setters for request/user context (`withToken`, `addUser`, `addCorrelation`, `addApplication`) and removed `getWithToken`
+  - Introduced `withResponseMetrics(responseSize, durationMs)` to replace request-metric setters
+  - Public logging now relies on request middleware/AsyncLocalStorage for request/user context
+### Fixed
+- **Timer cleanup** - Unref’d internal timeouts/intervals to avoid keeping the process alive during tests
+- **Timeout handling** - Ensured request timeout promises are cleared on completion
+### Technical
+- **Tests** - Jest runs in-band with `--detectOpenHandles` for stability
+- **Docs/Examples** - Updated logging documentation and examples to reflect the simplified API
+## [4.3.1] - 2026-02-01
+### Fixed
+- **DataClient ApiRequestOptions** - Resolved type conflict between DataClient's `cache` option and `RequestInit.cache`
+  - `ApiRequestOptions` now extends `Omit<RequestInit, "cache">` so the DataClient-specific cache options object does not conflict with the standard fetch cache type
+- **InternalHttpClient post/put** - Prevented duplicate or conflicting request body when `config.data` was passed together with the body argument
+  - `post()` and `put()` now omit `data` from the config object before calling axios so the body is only passed via the second argument
+### Technical
+- **TypeScript config** - Added `DOM` to `lib` for fetch/RequestInit types, `preserveSymlinks: true`; Jest types limited to test config via `tsconfig.test.json`
+## [4.3.0] - 2026-01-27
+### Added
+- **Authentication Method Detection** - Enhanced 401 error responses with `authMethod` field to identify which authentication mechanism failed
+  - New `AuthErrorMethod` type: `'bearer' | 'api-key' | 'client-token' | 'client-credentials' | null`
+  - `MisoClientError.authMethod` property indicates which auth method caused the failure
+  - `ErrorResponse.authMethod` field included in structured error responses
+  - New `detectAuthMethodFromHeaders()` helper for client-side auth method detection when controller doesn't return it
+  - Exported `AuthErrorMethod` type and `detectAuthMethodFromHeaders` helper from SDK
+  - Unit tests for auth method detection and error handling
+### Technical
+- **Code Size Compliance** - Refactored `internal-http-client.ts` to comply with 500-line file limit
+  - Extracted client token management into new `client-token-manager.ts` (226 lines)
+  - Reduced `internal-http-client.ts` from 541 to 366 lines
+  - New helper functions: `generateCorrelationId()`, `createHttpAgent()`, `extractTokenFromResponse()`, `formatTokenFetchError()`, `fetchClientToken()`, `refreshClientTokenFromCallback()`, `isTokenValid()`
+## [4.2.0] - 2026-01-26
+### Added
+- **User Info Caching** - Added caching for `getUserInfo()` to reduce redundant controller API calls
+  - Cache key format: `user:{userId}` with configurable TTL (default 300 seconds / 5 minutes)
+  - Automatically extracts userId from JWT token for cache key generation
+  - Falls back to controller when cache miss or Redis unavailable
+  - New `clearUserCache(token)` method to invalidate cached user info
+  - `logout()` now clears user cache in addition to token cache
+  - New `userTTL` configuration option in `cache` settings
+### Changed
+- **RFC 7807 Compliance** - Improved error responses in `client-token-endpoint.ts`
+  - All 11 error responses now use RFC 7807 Problem Details format
+  - Added 504 Gateway Timeout to error type mappings
+  - Error responses include `type`, `title`, `status`, `detail`, and `instance` fields
+### Technical
+- **Code Quality Refactoring** - Refactored 13 methods across 11 files to comply with 30-line method limit
+  - `auth.service.ts`: Extracted `extractTokenFromEnvResponse()` helper
+  - `internal-http-client.ts`: Extracted `createHttpAgent()`, `extractTokenFromResponse()`, `formatTokenFetchError()`
+  - `client-token-endpoint.ts`: Extracted `extractHttpStatus()`, `isNetworkOrTimeoutError()`, `handleTokenError()`, `buildConfigResponse()`
+  - `role.service.ts`: Extracted `buildAuthStrategy()`, `getEnvironmentParams()`, `resolveUserId()`, `fetchRolesFromController()`
+  - `permission.service.ts`: Similar helper extraction pattern
+  - `config-loader.ts`: Extracted `loadRedisConfig()`, `loadAuthStrategy()`, `loadKeycloakConfig()`, `loadAllowedOrigins()`
+  - `errors.ts`: Extracted `transformErrorEnvelope()`, `transformDirectError()`
+  - `error-handler.ts`: Added lookup tables `PRISMA_ERROR_MAP`, `MESSAGE_PATTERN_MAP`, extracted `logError()`
+  - `error-types.ts`: Extracted `ERROR_TYPE_MAP`, `ERROR_TITLE_MAP` lookup tables
+  - `data-client.ts`: Extracted `checkCircuitBreaker()`, `recordFailure()`, `executeRequest()`
+  - `logger-context.middleware.ts`: Extracted `buildLoggerContext()`
+- File size reduction in `auth.service.ts` from 515 to 500 lines via JSDoc consolidation
+## [4.1.0] - 2026-01-21
+### Changed
+- **Encryption Key Parameter** - `encryptionKey` is now sent to the controller for server-side validation
+  - Added `encryptionKey` field to `EncryptRequest` and `DecryptRequest` interfaces
+  - `EncryptionService` validates encryption key is configured before API calls
+  - Throws `ENCRYPTION_KEY_REQUIRED` error with helpful message if key is missing
+### Added
+- `ENCRYPTION_KEY_REQUIRED` error code in `EncryptionError` class
+- Tests for encryption key validation in `EncryptionService`
+- Tests for `MISO_ENCRYPTION_KEY` environment variable loading in `config-loader`
+### Technical
+- `EncryptionError.parameterName` is now optional (not applicable for `ENCRYPTION_KEY_REQUIRED` errors)
+- `EncryptionService` constructor accepts optional `encryptionKey` parameter
+- `MisoClient` passes `config.encryptionKey` to `EncryptionService`
+## [4.0.0] - 2026-01-20
+### Breaking Changes
+- **Removed `EncryptionUtil` class** - Local encryption via `EncryptionUtil.encrypt()`/`decrypt()` is no longer supported. Use the new controller-based `client.encryption` service instead.
+- **Encryption Key Required** - The `encryptionKey` config option is now required for encryption operations
+  - Load from `MISO_ENCRYPTION_KEY` environment variable
+  - Or provide `encryptionKey` in `MisoClientConfig`
+  - Throws `ENCRYPTION_KEY_REQUIRED` error if not configured when using encrypt/decrypt
+### Migration Guide
+**Before (v3.x) - Local encryption:**
+```typescript
+import { EncryptionUtil } from '@aifabrix/miso-client';
+EncryptionUtil.initialize(); // Required ENCRYPTION_KEY env var
+const encrypted = EncryptionUtil.encrypt('my-secret');
+const decrypted = EncryptionUtil.decrypt(encrypted);
+```
+**After (v4.0) - Controller-based encryption:**
+```typescript
+import { MisoClient, loadConfig } from '@aifabrix/miso-client';
+// Option 1: Use environment variable (recommended)
+// Set MISO_ENCRYPTION_KEY in your .env file
+const client = new MisoClient(loadConfig());
+// Option 2: Provide in config
+const client = new MisoClient({
+  controllerUrl: 'https://miso-controller.example.com',
+  clientId: 'my-app',
+  clientSecret: 'secret',
+  encryptionKey: 'your-encryption-key', // Required for encryption operations
+});
+const result = await client.encryption.encrypt('my-secret', 'param-name');
+// result.value: 'kv://param-name' (Key Vault) or 'enc://v1:...' (local)
+// result.storage: 'keyvault' or 'local'
+const decrypted = await client.encryption.decrypt(result.value, 'param-name');
+```
+### Why This Change?
+- **Centralized key management** - Encryption keys are managed by the controller, validated server-side
+- **Azure Key Vault support** - Production environments can use Azure Key Vault for secure secret storage
+- **Application isolation** - Each application can only access its own encrypted parameters
+- **Audit logging** - All encryption/decryption operations are logged by the controller
+- **Security** - Encryption key prevents misuse of rotated or leaked application credentials
+### Added
+- `client.encryption.encrypt(plaintext, parameterName)` - Encrypt a value via controller
+- `client.encryption.decrypt(value, parameterName)` - Decrypt a value via controller
+- `EncryptionService` class - Service layer with parameter and encryption key validation
+- `EncryptionError` class - Error class with codes: `ENCRYPTION_FAILED`, `DECRYPTION_FAILED`, `INVALID_PARAMETER_NAME`, `ACCESS_DENIED`, `PARAMETER_NOT_FOUND`, `ENCRYPTION_KEY_REQUIRED`
+- `EncryptResult` type - Return type for encrypt operations
+- `EncryptionApi` class - API layer for controller communication
+- `encryptionKey` config option - For server-side encryption key validation
+- `MISO_ENCRYPTION_KEY` environment variable support in `loadConfig()`
+### Removed
+- `EncryptionUtil` class - Use `client.encryption` instead
+### Technical
+- **New files**: `src/api/encryption.api.ts`, `src/api/types/encryption.types.ts`, `src/services/encryption.service.ts`, `src/utils/encryption-error.ts`
+- **Deleted files**: `src/express/encryption.ts`
+- **Tests**: `tests/unit/api/encryption.api.test.ts`, `tests/unit/services/encryption.service.test.ts`
+## [3.9.0] - 2026-01-14
+### Added
+- **Enhanced Filter System** - Comprehensive filter parsing, validation, and SQL compilation
+  - **Dual format parsing**: Support for both colon format (`status:eq:active`) and JSON format (`{"status":{"eq":"active"}}`)
+  - **Schema-based validation**: Define filterable fields, allowed operators, and value types per resource
+  - **Type coercion**: Automatic value validation and conversion for string, number, boolean, uuid, timestamp, and enum types
+  - **SQL compilation**: Generate PostgreSQL-safe parameterized WHERE clauses with `compileFilter()`
+  - **Human-readable errors**: RFC 7807 compliant structured error responses with error codes (UNKNOWN_FIELD, INVALID_OPERATOR, INVALID_TYPE, etc.)
+  - New `ilike` operator for case-insensitive pattern matching
+  - New types: `FilterSchema`, `FilterFieldDefinition`, `FilterError`, `CompiledFilter`
+  - New utilities: `validateFilter()`, `coerceValue()`, `compileFilter()`, `createFilterSchema()`
+  - Filter meta-schema for validating custom filter schemas (`src/schemas/filter.schema.json`)
+### Changed
+- **Code Size Compliance** - Refactored large files to comply with 500-line guideline
+  - `data-client.ts`: 995 → 416 lines (extracted to helper modules)
+  - `data-client-request.ts`: 683 → 280 lines
+  - `data-client-auth.ts`: 654 → 290 lines
+  - `internal-http-client.ts`: 741 → 496 lines
+  - `auth.service.ts`: 825 → 462 lines
+  - `index.ts`: 681 → 472 lines
+  - `logger.service.ts`: 597 → 480 lines
+- **Console Logging Audit** - Cleaned up debug logging
+  - Removed 10 debug `console.log` statements from `token-utils.ts` that could expose sensitive token data
+  - All remaining console calls are appropriate error/warning logs or guarded by debug checks
+### Technical
+- **New filter utilities**: `src/utils/filter-schema.utils.ts` (497 lines), `src/utils/filter-colon.utils.ts` (119 lines)
+- **New filter types**: `src/types/filter-schema.types.ts` (148 lines)
+- **New helper modules** for DataClient refactoring:
+  - `data-client-init.ts` - Initialization logic
+  - `data-client-permissions.ts` - Permission helpers
+  - `data-client-roles.ts` - Role helpers
+  - `data-client-response.ts` - Response processing
+  - `data-client-oauth.ts` - OAuth callback handling
+- **New HTTP helpers**: `http-error-handler.ts`, `http-response-validator.ts`
+- **New auth helper**: `auth-error-handler.ts` - Centralized auth error formatting
+- **New tests**: `filter-colon-format.test.ts` (178 lines), `filter-schema.utils.test.ts` (545 lines)
+- **Documentation**: Updated `docs/reference-utilities.md` with filter system examples
+## [3.8.2] - 2026-01-12
+### Added
+- **Keycloak Separate Private/Public URL Support** - Separate URLs for JWKS fetching and issuer validation
+  - New `authServerPrivateUrl` configuration option for server-side JWKS fetching (internal network)
+  - New `authServerPublicUrl` configuration option for browser-side and issuer validation (public network)
+  - New `resolveKeycloakUrl()` utility function that automatically detects environment and selects appropriate URL
+  - `validateTokenLocal()` now uses private URL for JWKS fetching on server, public URL for issuer validation
+  - Environment variable support: `KEYCLOAK_SERVER_URL` (maps to `authServerPrivateUrl`), `KEYCLOAK_PUBLIC_SERVER_URL` (maps to `authServerPublicUrl`)
+  - Maintains backward compatibility with existing `authServerUrl` configuration
+### Technical
+- **TokenValidationService** - Now uses `resolveKeycloakUrl()` for automatic URL resolution
+  - JWKS URI construction uses resolved URL (private on server, public on browser)
+  - Issuer validation always uses public URL (matches token's `iss` claim)
+  - `determineTokenType()` updated to use public URL for issuer matching
+- **controller-url-resolver.ts** - Added `resolveKeycloakUrl()` function (mirrors `resolveControllerUrl()` pattern)
+- **config-loader.ts** - Added Keycloak environment variable support
+- **Tests**: Comprehensive tests for `resolveKeycloakUrl()` and updated TokenValidationService tests
+## [3.8.1] - 2026-01-10
+### Changed
+- **Unified Application Context Service** - Centralized application and environment extraction
+  - New `ApplicationContextService` class to extract `application`, `applicationId`, and `environment` with consistent fallback logic
+  - Extracts from client token first (if available), then falls back to parsing `miso-controller-{environment}-{application}` format from clientId
+  - RoleService, PermissionService, LoggerService, and UnifiedLoggerService now use the unified service
+  - Reduces code duplication and ensures consistent behavior across all services
+  - Caches parsed results to avoid repeated extraction
+### Fixed
+- **Logger Context Application Fallback** - Fixed application fallback to use clientId when parsing fails
+  - Logger getter methods (`getLogWithRequest`, `getWithContext`, `getWithToken`) now properly fall back to `clientId` when `application` cannot be extracted from client token or parsed from clientId format
+  - Ensures application field is always populated in log entries, even when clientId format doesn't match expected pattern
+### Technical
+- **New service**: `src/services/application-context.service.ts` - Unified application context extraction (175 lines)
+- **Test coverage**: Comprehensive tests in `tests/unit/application-context.service.test.ts` (323 lines, 100% coverage)
+- **Code quality**: All services updated to use ApplicationContextService, reducing code duplication by ~50 lines
+## [3.8.0] - 2026-01-10
+### Added
+- **Unified Logging Interface**: New minimal API with automatic context extraction
+  - `getLogger()` factory function for automatic context detection from AsyncLocalStorage
+  - `setLoggerContext()` and `clearLoggerContext()` for manual context management
+  - `loggerContextMiddleware` Express middleware helper for automatic request context extraction
+  - AsyncLocalStorage-based context propagation across async boundaries
+  - Simplified API: `logger.info(message)`, `logger.error(message, error?)`, `logger.audit(action, resource, entityId?, oldValues?, newValues?)`
+  - Automatic context extraction from AsyncLocalStorage (set by Express middleware or manually)
+  - Works seamlessly in Express routes, service layers, and background jobs
+  - Zero configuration required when middleware is used
+### Documentation
+- Added unified logging examples and guides (`docs/examples/unified-logging.md`)
+- Updated Express middleware examples with unified logging pattern
+- Added background job logging examples with unified interface
+- Comprehensive API reference for UnifiedLogger interface in `docs/reference-services.md`
+## [3.7.2] - 2026-01-10
+### Added
+- **Comprehensive Integration Tests** - Full end-to-end integration tests for Auth and Logs API endpoints
+  - New `tests/integration/api-endpoints.integration.test.ts` with comprehensive endpoint coverage
+  - Tests all Auth and Logs endpoints against real controller using credentials from `.env`
+  - Validates endpoint paths, HTTP methods, request bodies, and response structures against OpenAPI specs
+  - Tests error cases (invalid tokens, missing params, etc.) with proper status code verification
+  - Gracefully skips tests if controller is unavailable (CI/CD friendly)
+  - New npm script `test:integration:api` for running integration tests
+### Changed
+- **Logger Service Refactoring** - Improved code organization and maintainability
+  - Moved logger service to modular structure in `src/services/logger/` directory
+  - Split `LoggerService` into focused modules: `logger-chain.ts`, `logger-context.ts`, `logger.service.ts`
+  - New barrel export `src/services/logger/index.ts` for cleaner imports
+  - Maintains backward compatibility (no breaking changes to public API)
+- **Error Handling Improvements** - Enhanced error handling across API layer
+  - Updated error handling in integration tests to gracefully skip unavailable controllers
+  - Improved error reporting and logging throughout API files
+  - Enhanced user information retrieval functionality
+- **Code Quality Improvements** - Refactoring for better readability and maintainability
+  - Updated various components for improved logging and error reporting
+  - Enhanced API response handling and validation
+  - Improved code organization and structure
+### Fixed
+- **Linting Issues** - Fixed ESLint errors in internal HTTP client
+  - Converted `require()` statements to use ESLint disable comments for Node.js-only code
+  - Fixed `@typescript-eslint/no-var-requires` errors in `src/utils/internal-http-client.ts`
+### Technical
+- **New test infrastructure**:
+  - Comprehensive integration test suite (`tests/integration/api-endpoints.integration.test.ts` - 554 lines)
+  - New npm script: `test:integration:api` for running integration tests
+  - Enhanced validation plans and summaries for API calls
+- **Code organization**:
+  - Logger service modularized into `src/services/logger/` directory structure
+  - Improved separation of concerns with focused modules
+  - Better code maintainability and testability
+- **Documentation**:
+  - Added endpoint validation summary documentation
+  - Updated validation plans for API calls
+## [3.7.1] - 2026-01-09
+### Added
+- **Enhanced Error Logging with Correlation IDs** - Comprehensive error logging system with structured error extraction
+  - New `extractErrorInfo()` utility in `src/utils/error-extractor.ts` for structured error information extraction
+  - New `logErrorWithContext()` utility in `src/utils/console-logger.ts` for enhanced console logging with correlation ID prefixes
+  - Supports all error types: `MisoClientError`, `ApiError`, `AuthenticationError`, `NetworkError`, `TimeoutError`, and generic `Error`
+  - Automatic correlation ID extraction from error responses or auto-generation when missing
+  - Enhanced error context includes endpoint, method, status codes, response bodies, and stack traces
+  - All API files updated with structured error logging (11 API files enhanced)
+  - DataClient and Express error handlers updated with enhanced logging
+- **Logger Service Getter Methods** - Public methods for external logger integration
+  - New `getLogWithRequest()` method - Extracts IP, method, path, userAgent, correlationId, userId from Express Request
+  - New `getWithContext()` method - Returns LogEntry with provided context and auto-generated correlation ID
+  - New `getWithToken()` method - Extracts userId, sessionId, applicationId from JWT token
+  - New `getForRequest()` method - Alias for `getLogWithRequest()` for consistency
+  - All methods return complete `LogEntry` objects for integration with external logger tables
+  - `generateCorrelationId()` method made public for consistent correlation ID generation
+- **Unified JSON Filter Model** - Standardized JSON format for all filter representations
+  - New filter operators: `isNull` and `isNotNull` for null/undefined checks
+  - JSON format parser supports multiple input formats: direct object, JSON string, URL-encoded JSON, array of filters
+  - Operator normalization (e.g., `equals` → `eq`, `>` → `gt`)
+  - Comprehensive validation with clear error messages and examples
+  - Filter conversion utilities: `filterQueryToJson()` and `jsonToFilterQuery()`
+  - Query string builder outputs URL-encoded JSON format
+  - Local filtering supports null checks with `isNull` and `isNotNull` operators
+- **Server Code Improvements** - Enhanced Express server error handling and logging
+  - Replaced all `console.log/error/warn` with MisoClient logger service
+  - All route handlers wrapped with `asyncHandler()` wrapper for automatic error handling
+  - Error middleware uses `handleRouteError()` from SDK for RFC 7807 compliance
+  - Error logger configured with MisoClient logger via `setErrorLogger()`
+  - All business logic errors use `AppError` for consistent error formatting
+  - Automatic correlation ID extraction and error logging with full context
+- **Frontend Code Improvements** - Enhanced React application error handling and code quality
+  - Centralized error handling utilities (`src/utils/error-handler.ts`)
+  - Centralized type definitions (`src/types/errors.ts`, `src/types/api.ts`)
+  - Input validation utilities (`src/utils/validation.ts`) for role names, permission names, endpoints
+  - Component refactoring: ApiTestingPage reduced from 589 to 79 lines (87% reduction)
+  - New custom hooks: `useApiTesting` for API testing logic, `useLoadingState` for loading state management
+  - Improved DataClientContext with retry logic and exponential backoff
+  - Simplified ErrorDetailsDialog component (115 lines, reduced from 193)
+- **Comprehensive Integration Tests** - Real integration tests for all auth and logs endpoints
+  - New `tests/integration/api-endpoints.integration.test.ts` with comprehensive endpoint coverage
+  - Tests all 24 auth endpoints against real controller using credentials from `.env`
+  - Tests all 15 logs endpoints with proper request/response validation
+  - Validates endpoint paths, HTTP methods, request bodies, and response structures against OpenAPI specs
+  - Tests error cases (invalid tokens, missing params, etc.) with proper status code verification
+  - Gracefully skips tests if controller is unavailable (CI/CD friendly)
+  - New npm script `test:integration:api` for running integration tests
+- **Logger Service Refactoring** - Improved code organization and maintainability
+  - Split `LoggerService` into modular structure following API layer pattern
+  - New `src/services/logger/logger-chain.ts` - LoggerChain class for method chaining
+  - New `src/services/logger/logger-context.ts` - Context extraction utilities (JWT, metadata, request)
+  - New `src/services/logger/index.ts` - Barrel export for logger modules
+  - Reduced main `logger.service.ts` from 866 lines to under 500 lines (code size compliance)
+  - Maintains backward compatibility (no breaking changes to public API)
+### Changed
+- **Error Logging** - Enhanced error logging across all API layer files
+  - All API files now use `extractErrorInfo()` and `logErrorWithContext()` for structured error logging
+  - Error logs include correlation ID prefixes: `[MisoClient] [correlation-id] Error details`
+  - Authentication errors have special handling with detailed context (authFlow: 'token_validation_failed')
+  - Enhanced audit logs include structured error info (errorType, errorCategory, httpStatusCategory)
+- **Filter Parsing** - Unified JSON format replaces colon-separated format
+  - Filter parser now accepts JSON format only: `{"field": {"op": value}}`
+  - Supports 12 operators: `eq`, `neq`, `in`, `nin`, `gt`, `lt`, `gte`, `lte`, `contains`, `like`, `isNull`, `isNotNull`
+  - FilterBuilder outputs JSON format (URL-encoded) in query strings
+  - Comprehensive validation with helpful error messages including examples
+- **Server Error Handling** - Standardized error handling patterns
+  - All route handlers use `asyncHandler()` wrapper (no manual try-catch needed)
+  - All errors automatically formatted as RFC 7807 Problem Details
+  - Error logger uses MisoClient logger with `forRequest()` for automatic context extraction
+  - Consistent error responses across all routes with correlation IDs
+- **Frontend Error Handling** - Centralized error handling patterns
+  - All components use shared error handling utilities
+  - RFC 7807 compliant error parsing with `parseError()` utility
+  - Consistent error message extraction with `getErrorMessage()` and `getErrorStatus()`
+  - Input validation integrated into authorization testing hooks
+- **API Layer Cleanup** - Removed duplicate code and improved code quality
+  - Removed duplicate roles/permissions methods from `AuthApi` class
+  - Removed `getRoles()`, `refreshRoles()`, `getPermissions()`, `refreshPermissions()` from `AuthApi`
+  - Services now use dedicated `RolesApi` and `PermissionsApi` classes (DRY principle)
+  - Removed unused endpoint constants and type imports from `AuthApi`
+  - Updated class JSDoc to reflect removed methods
+- **Error Handling Improvements** - Fixed duplicate throw statements across API layer
+  - Removed duplicate `throw error;` statements from `auth.api.ts`, `roles.api.ts`, `permissions.api.ts`
+  - Fixed duplicate throws in `logs-create.api.ts` and `logs-list.api.ts`
+  - Improved error handling consistency across all API files
+### Fixed
+- **Server Error Handling** - Fixed logic bug in server.ts (dead code removed)
+- **Server Logging** - Fixed inconsistent logging format (now uses MisoClient logger)
+- **Server Error Responses** - Fixed non-RFC 7807 error responses (now uses `handleRouteError()`)
+- **Frontend Component Size** - Fixed large component files exceeding 500-line limit
+  - ApiTestingPage: 589 → 79 lines (87% reduction)
+  - ConfigurationPage: 382 → 283 lines (26% reduction)
+- **Frontend Error Handling** - Fixed duplicate error handling logic across components
+- **Frontend Type Safety** - Fixed loose error typing with centralized type definitions
+- **Code Size Compliance** - Fixed logger service file size violation
+  - Refactored `LoggerService` from 866 lines to under 500 lines
+  - Split into focused modules: logger-chain.ts, logger-context.ts, index.ts
+  - Maintains all functionality while improving maintainability
+- **API Endpoint Validation** - Validated all endpoints against OpenAPI specifications
+  - Verified all 24 auth endpoints match OpenAPI spec paths and HTTP methods
+  - Verified all 15 logs endpoints match OpenAPI spec with proper request/response structures
+  - Confirmed audit logs include required fields (entityType, entityId, action) in data object
+  - Validated client token endpoints use correct paths (`/api/v1/auth/token` for legacy, `/api/v1/auth/client-token` for frontend)
+### Technical
+- **New utility files**:
+  - `src/utils/error-extractor.ts` - Error extraction utility (172 lines)
+  - `src/utils/console-logger.ts` - Enhanced console logger (72 lines)
+  - `src/utils/error-handler.ts` - Frontend error handling utilities (175 lines)
+  - `src/utils/validation.ts` - Frontend input validation utilities (139 lines)
+  - `src/types/errors.ts` - Frontend error type definitions (25 lines)
+  - `src/types/api.ts` - Frontend API type definitions (63 lines)
+- **Test coverage**:
+  - Error extraction utility: 18 tests (`tests/unit/utils/error-extractor.test.ts`)
+  - Console logger utility: 12 tests (`tests/unit/utils/console-logger.test.ts`)
+  - Logger getter methods: 31 tests (`tests/unit/services/logger-getter-methods.test.ts`)
+  - Filter utilities: 68 tests (`tests/unit/filter.utils.test.ts`)
+  - Frontend error handler: 21 tests (`server/frontend/src/utils/__tests__/error-handler.test.ts`)
+  - Frontend validation: 43 tests (`server/frontend/src/utils/__tests__/validation.test.ts`)
+  - Integration tests: Comprehensive tests for all 39 endpoints (`tests/integration/api-endpoints.integration.test.ts`)
+  - Total: 193+ new tests added, all passing
+- **New logger module structure**:
+  - `src/services/logger/logger-chain.ts` - LoggerChain class (method chaining support)
+  - `src/services/logger/logger-context.ts` - Context extraction utilities
+  - `src/services/logger/index.ts` - Barrel export
+  - `src/services/logger.service.ts` - Core LoggerService class (reduced to <500 lines)
+- **Code quality**:
+  - All new utilities follow camelCase naming convention
+  - All public methods have JSDoc comments with parameter types, return types, and examples
+  - File sizes within limits (all files ≤500 lines)
+  - Method sizes within limits (all methods ≤30 lines)
+  - Zero linting errors or warnings
+  - Proper error handling with try-catch for all async operations
+  - Removed duplicate code (roles/permissions methods from AuthApi)
+  - Fixed duplicate throw statements across API layer
+  - All endpoints validated against OpenAPI specs
+- **Documentation**:
+  - Updated `docs/reference-services.md` with logger getter methods documentation
+  - Updated `docs/reference-utilities.md` with filter JSON format examples
+  - Updated `server/README.md` with factory function pattern and error logger configuration
+  - Updated `docs/examples/express-middleware.md` with error logger configuration examples
+  - Updated `AuthApi` class JSDoc to remove references to removed methods
+  - Added integration test documentation explaining test structure and requirements
+## [3.6.0] - 2024-12-31
+### Added
+- **API Response Validation** - Runtime validation for API response structures
+  - New `validateSuccessResponse<T>()` type guard for standard success responses
+  - New `validatePaginatedResponse<T>()` type guard for paginated responses
+  - New `validateErrorResponse()` type guard for error responses (re-exports existing validation)
+  - New `getResponseType()` utility to determine response type (success, paginated, error)
+  - Response validation utilities in `src/utils/response-validator.ts` with comprehensive type guards
+  - All validation functions use TypeScript type guards for proper type narrowing
+  - Detailed validation error messages for debugging response structure mismatches
+- **Response Validation Configuration** - Configurable validation control
+  - New `validateResponses?: boolean` configuration option in `MisoClientConfig`
+  - Environment variable support: `MISO_VALIDATE_RESPONSES` (defaults to `true` in development, `false` in production)
+  - Validation is opt-in and backward compatible (doesn't break existing code)
+  - Non-breaking validation failures (logs warnings instead of throwing errors)
+### Changed
+- **HTTP Client Response Validation** - Enhanced HTTP client with response structure validation
+  - `InternalHttpClient` now validates all API responses when `validateResponses` is enabled
+  - All HTTP methods (`get`, `post`, `put`, `delete`, `request`, `authenticatedRequest`) validate responses
+  - Validation checks for standard success response format: `{ success: boolean, data?: T, message?: string, timestamp: string }`
+  - Validation checks for paginated response format: `{ data: T[], meta: {...}, links: {...} }`
+  - Validation handles both nested and flat response formats (backward compatibility)
+  - Validation failures log warnings with endpoint URL, expected structure, and actual response
+  - Graceful error handling - validation failures don't break existing functionality
+### Fixed
+- **Circuit breaker priority** - Fixed critical ordering issue where circuit breaker check now occurs before cache check
+  - Circuit breaker check moved before cache and pending request checks to prevent requests to failing endpoints
+  - Ensures failed endpoints are blocked even if cache is cleared, preventing unnecessary API calls during failures
+  - Improved error consistency by using `throw` instead of `Promise.reject()` for circuit breaker errors
+- **Cache key generation** - Fixed cache key generation to ensure HTTP method is always included
+  - Cache key now explicitly includes HTTP method from method parameter to ensure consistency
+  - Prevents potential cache key collisions when method might be undefined in options
+  - Ensures proper cache key generation for all HTTP methods (GET, POST, PUT, DELETE, etc.)
+### Technical
+- **New utility file**: `src/utils/response-validator.ts` - Response validation utilities (174 lines)
+  - Type guard functions for runtime type checking
+  - Support for success, paginated, and error response formats
+  - Comprehensive JSDoc documentation for all public functions
+  - Proper TypeScript type narrowing with type guards
+- **Test coverage**:
+  - Comprehensive tests in `tests/unit/utils/response-validator.test.ts` (413 lines)
+  - 36 test cases covering valid/invalid responses, edge cases, and backward compatibility
+  - Test coverage: **96.53%** (exceeds ≥80% requirement)
+    - Statements: 96.53% (167/173)
+    - Branches: 91.83% (45/49)
+    - Functions: 100% (4/4)
+    - Lines: 96.53% (167/173)
+  - All tests passing with execution time < 0.5 seconds
+- **Configuration updates**:
+  - Added `validateResponses?: boolean` to `MisoClientConfig` interface
+  - Added `MISO_VALIDATE_RESPONSES` environment variable support in config loader
+  - Defaults to `true` in development, `false` in production for performance
+- **Code quality**:
+  - All validation functions follow camelCase naming convention
+  - All public functions have JSDoc comments with parameter types and return types
+  - File size: 174 lines (≤500 lines requirement met)
+  - Method sizes: ≤30 lines (≤20-30 lines requirement met)
+  - Zero linting errors or warnings
+  - Proper error handling with try-catch for all async operations
+## [3.4.1] - 2025-12-30
+### Fixed
+- **Token validation caching** - Improved caching strategy for token validation
+  - Enhanced cache key generation using SHA-256 hash of token for security
+  - Smart TTL calculation based on token expiration with safety buffer
+  - Minimum TTL enforcement to prevent excessive API calls
+  - Better cache invalidation handling
+### Changed
+- **Error handling** - Enhanced error handling and logging for token retrieval
+  - Added detailed error responses for timeout scenarios in client token endpoint
+  - Updated AuthService to use shorter timeout for axios requests (aligns with handler timeout)
+  - Improved logging for token retrieval processes with controller URL details
+  - Integrated controller URL resolution in environment token utility for consistent URL handling
+### Technical
+- **Dependencies** - Updated dependencies and improved linting configuration
+  - Removed unnecessary "peer" flags from package-lock.json
+  - Updated linting scripts to ignore declaration files for better efficiency
+  - Updated package dependencies for improved functionality and performance
+## [3.4.0] - 2025-12-24
+### Added
+- **Local Token Validation** - JWKS-based JWT validation without API calls
+  - New `validateTokenLocal()` method for local JWT signature verification
+  - Supports Keycloak tokens and delegated OAuth provider tokens
+  - Dual-layer caching: JWKS keys (1 hour) + validation results (1 minute)
+  - `skipResultCache` option for high-security scenarios
+  - Auto-detection of token type based on issuer claim
+  - New `TokenValidationService` exported for advanced usage
+- **Keycloak Configuration** - Native Keycloak integration
+  - New `keycloak` config option in `MisoClientConfig`
+  - `setKeycloakConfig()` method for runtime configuration
+  - Audience validation support (opt-in via `verifyAudience`)
+- **Cache Management** - Fine-grained cache control
+  - `clearJwksCache(uri?)` - Clear JWKS key cache
+  - `clearValidationCache()` - Clear validation result cache
+  - `clearAllTokenCaches()` - Clear all caches
+### Changed
+- **Package Distribution** - Added CHANGELOG.md to npm package files
+### Dependencies
+- Added `jose` ^5.9.6 for JWT/JWKS operations
+## [3.3.0] - 2025-12-23
+### Added
+- **Centralized API layer** - Typed interfaces for all controller API calls
+  - New API layer in `src/api/` with domain-specific API classes (`AuthApi`, `RolesApi`, `PermissionsApi`, `LogsApi`)
+  - `ApiClient` class wraps `HttpClient` and organizes APIs by domain
+  - Centralized endpoint URLs as constants in each API class for maintainability
+  - All API request/response types use interfaces (not types) with camelCase naming convention
+  - Services can optionally use `ApiClient` instead of direct `HttpClient` calls (gradual migration pattern)
+  - Improved type safety and code organization for controller API interactions
+  - API classes are composed from specialized sub-modules to keep file sizes manageable
+### Changed
+- **Token validation enhancements** - Improved token acceptance criteria
+  - Updated token validation logic to accept both JWT and non-JWT token formats
+  - Enhanced validation to ensure tokens are non-empty and of reasonable length
+  - Improved error handling for token validation failures
+  - Updated unit tests to reflect changes in token acceptance criteria
+- **OAuth callback handling** - Enhanced error feedback
+  - Updated error handling in `handleOAuthCallback()` to provide clearer feedback on token validation failures
+  - Improved documentation for token validation and OAuth handling
+- **Service dependencies** - Optional API client support
+  - Services can now optionally include `ApiClient` for typed API access
+  - Allows for gradual migration from direct `HttpClient` usage to typed API layer
+  - Maintains backward compatibility with existing service implementations
+### Technical
+- **New API layer structure**:
+  - `src/api/index.ts` - Main `ApiClient` class
+  - `src/api/auth.api.ts` - Authentication API (composed from sub-modules)
+  - `src/api/roles.api.ts` - Roles API
+  - `src/api/permissions.api.ts` - Permissions API
+  - `src/api/logs.api.ts` - Logs API
+  - `src/api/types/` - API request/response type definitions
+- **Test coverage**:
+  - Updated mock patterns to include `ApiClient` for testing purposes
+  - Enhanced unit tests for token validation with new acceptance criteria
+- **Documentation**:
+  - Added API layer pattern documentation to project rules
+  - Updated usage examples to demonstrate API layer pattern
+  - Enhanced documentation for token validation and OAuth handling
+## [3.2.5] - 2025-12-22
+### Added
+- **Indexed logging fields** - Standardized indexed fields for improved query performance and observability
+  - New `extractLoggingContext()` utility function in `src/utils/logging-helpers.ts`
+  - Added indexed context fields to `LogEntry` interface: `sourceKey`, `sourceDisplayName`, `externalSystemKey`, `externalSystemDisplayName`, `recordKey`, `recordDisplayName`
+  - Added credential context fields: `credentialId`, `credentialType`
+  - Added request/response metrics: `requestSize`, `responseSize`, `durationMs`
+  - Added error classification fields: `errorCategory`, `httpStatusCategory`
+  - New `LoggerChain` methods: `withIndexedContext()`, `withCredentialContext()`, `withRequestMetrics()`
+  - Exported types: `IndexedLoggingContext`, `HasKey`, `HasExternalSystem`
+  - Improves query performance and root-cause analysis for audit logs
+- **Request context auto-extraction** - Automatic extraction of logging context from Express Request objects
+  - New `extractRequestContext()` utility function in `src/utils/request-context.ts`
+  - New `withRequest()` method on `LoggerChain` for automatic context extraction
+  - New `forRequest()` method on `LoggerService` for request-based logging
+  - Automatically extracts: IP address, HTTP method, path, user-agent, correlation ID, user from JWT, session ID, request ID
+  - Handles proxy IPs via `x-forwarded-for` header
+  - Reduces logging code from 10-15 lines to 2-3 lines per log call
+  - Exported `RequestContext` interface and `extractRequestContext` function
+- **Token validation caching** - Caching for token validation to reduce API calls
+  - Cache validation results by userId with 15-minute TTL (configurable via `config.cache?.tokenValidationTTL`)
+  - Cache key format: `token:${userId}` (consistent with roles/permissions caching)
+  - Automatic cache invalidation on logout (clears cache even if logout returns 400)
+  - New `clearTokenCache()` method in `AuthService` for manual cache clearing
+  - Extracts userId from JWT token before API call (avoids unnecessary validate API call)
+  - Graceful fallback to API call on cache failures
+  - Uses `CacheService` instead of `RedisService` for consistency
+- **User token refresh** - Token refresh functionality for secure token renewal
+  - New `refreshToken()` method in `AuthService` for backend applications
+  - New `onTokenRefresh` callback support in `DataClient` for frontend applications
+  - Automatic token refresh on 401 errors in DataClient with retry logic
+  - New `RefreshTokenResponse` interface with `accessToken`, `refreshToken`, `expiresIn`, `expiresAt`
+  - Exposed `refreshToken()` method in `MisoClient` class
+  - Prevents infinite retry loops with `tokenRefreshAttempted` flag
+  - Refresh tokens never stored in browser localStorage (security requirement)
+- **OAuth callback handler** - ISO 27001 compliant OAuth callback handling with hash fragments
+  - New `handleOAuthCallback()` function in `src/utils/data-client-auth.ts`
+  - New `handleOAuthCallback()` method in `DataClient` class
+  - Extracts tokens from URL hash fragments (`#token=...`) instead of query parameters
+  - Immediate hash cleanup (< 100ms) to prevent token exposure
+  - Token format validation (JWT format check)
+  - HTTPS enforcement in production environments
+  - Supports multiple parameter names: `token`, `access_token`, `accessToken`
+  - Auto-calls on DataClient initialization in browser environments
+  - Secure error handling without exposing tokens
+### Changed
+- **LoggerService enhancements** - Enhanced logging capabilities with indexed fields
+  - Updated `ClientLoggingOptions` interface with indexed context fields
+  - Updated `LogEntry` interface with indexed fields for fast queries
+  - Enhanced `LoggerChain` fluent API with new context methods
+  - Improved developer experience with automatic request context extraction
+- **AuthService improvements** - Enhanced authentication service with caching
+  - Updated constructor to accept `CacheService` instead of `RedisService`
+  - Added `extractUserIdFromToken()` private method for JWT extraction
+  - Enhanced `validateToken()` method with caching logic
+  - Updated `logout()` method to clear token cache on logout
+- **DataClient enhancements** - Improved token refresh and OAuth handling
+  - Added `refreshUserToken()` private method for token refresh
+  - Enhanced 401 error handling with automatic token refresh and retry
+  - Updated `redirectToLogin()` documentation for hash fragment flow
+  - Improved OAuth callback handling with security measures
+### Fixed
+- **Token validation performance** - Reduced API calls through caching
+  - Token validation now uses cache to avoid unnecessary controller API calls
+  - Cache hit significantly improves performance for repeated validations
+- **OAuth security** - Improved security for OAuth callback flow
+  - Tokens extracted from hash fragments (not sent to server, not in logs)
+  - Immediate cleanup prevents token exposure in address bar
+  - HTTPS enforcement prevents token transmission over HTTP in production
+### Technical
+- **New utility files**:
+  - `src/utils/logging-helpers.ts` - Logging context extraction utility (91 lines)
+  - `src/utils/request-context.ts` - Request context extraction utility (102 lines)
+- **Test coverage**:
+  - Comprehensive tests for logging helpers (15 tests)
+  - Comprehensive tests for request context extraction (33 tests)
+  - Enhanced tests for token caching (80 tests total in auth.service.test.ts)
+  - Comprehensive tests for token refresh (17 AuthService + 15 DataClient tests)
+  - Comprehensive tests for OAuth callback handler (34 tests)
+- **Type definitions**:
+  - Added `RefreshTokenResponse` interface to `src/types/config.types.ts`
+  - Added `tokenValidationTTL?: number` to cache config type
+  - Added `onTokenRefresh` callback to `DataClientConfig` interface
+- **Exports updated**:
+  - `src/index.ts` - Exports `extractLoggingContext`, `IndexedLoggingContext`, `HasKey`, `HasExternalSystem`
+  - `src/index.ts` - Exports `extractRequestContext`, `RequestContext`
+  - `src/index.ts` - Exports `refreshToken()` method in `MisoClient`
+## [3.2.0] - 2025-12-22
+### Added
+- **Circuit breaker for HTTP logging** - Prevents infinite retry loops when logging service is unavailable
+  - Added circuit breaker pattern to `LoggerService` and `AuditLogQueue`
+  - Automatically disables HTTP logging after 3 consecutive failures
+  - Circuit breaker opens for 60 seconds after failures, then resets
+  - Prevents performance degradation when controller logging endpoint is unavailable
+  - Gracefully handles network errors and server unavailability
+- **DataClient redirect utilities** - Comprehensive redirect handling for login flows
+  - New `data-client-redirect.ts` utility module with robust redirect logic
+  - Enhanced `redirectToLogin()` with comprehensive error handling
+  - URL validation prevents dangerous redirects (javascript:, data:, etc.)
+  - User-friendly error messages for network, CORS, and authentication errors
+  - Proper timeout handling (30 seconds) to prevent hanging requests
+  - Only redirects when controller returns valid login URL (no fallback redirects on error)
+  - Supports both nested (`data.loginUrl`) and flat (`loginUrl`) response formats
+- **Client token expiration checking** - Enhanced token validation with JWT expiration support
+  - Improved `getClientToken()` to check JWT expiration claims when expiration timestamp is missing
+  - Decodes JWT tokens to extract `exp` claim for expiration validation
+  - Better logging for debugging token expiration issues
+  - Handles missing expiration timestamps gracefully
+  - Automatically removes expired tokens from cache
+- **Auto-initialization improvements** - New utility for accessing cached configuration
+  - New `getCachedDataClientConfig()` function exported from `src/index.ts`
+  - Allows reading cached DataClient configuration without re-initializing
+  - Useful for accessing configuration values in application code
+  - Returns cached config or null if not found or expired
+- **Controller URL validation utility** - Exported URL validation function
+  - `validateUrl()` function now exported from `controller-url-resolver.ts`
+  - Validates HTTP/HTTPS URLs with comprehensive JSDoc documentation
+  - Useful for validating URLs before use in application code
+  - Exported from `src/index.ts` for public use
+### Changed
+- **Documentation restructure** - Improved documentation organization and clarity
+  - New reference documentation structure with dedicated files for each major component
+  - Added `docs/reference-authentication.md` - Comprehensive authentication guide
+  - Added `docs/reference-authorization.md` - RBAC and permissions documentation
+  - Added `docs/reference-dataclient.md` - Complete DataClient API reference
+  - Added `docs/reference-errors.md` - Error handling and troubleshooting guide
+  - Added `docs/reference-misoclient.md` - MisoClient API reference
+  - Added `docs/reference-services.md` - Service layer documentation
+  - Added `docs/reference-types.md` - TypeScript type definitions reference
+  - Added `docs/reference-utilities.md` - Utility functions documentation
+  - Enhanced examples with improved clarity and error handling
+  - Updated all example files with corrected import paths
+- **DataClient enhancements** - Improved robustness and developer experience
+  - Enhanced DataClient configuration and performance optimizations
+  - Improved authorization examples and documentation
+  - Better error handling in example code
+- **Audit logging error handling** - Improved handling of network errors in audit logging
+  - Enhanced error detection for network errors (ECONNREFUSED, ENOTFOUND, ERR_CONNECTION_REFUSED)
+  - Silently skips audit logging for expected network errors (server unavailable, misconfigured)
+  - Prevents error noise in development and demo environments
+  - Better error classification and handling
+### Fixed
+- **DataClient metrics** - Fixed handling of missing response times in metrics
+  - Modified `getMetrics()` method to handle cases where `responseTimes` may be undefined
+  - Ensures robust performance metrics retrieval without errors
+- **Example imports** - Fixed import paths in all example files
+  - Updated example imports for clarity and proper error handling
+  - Corrected script source references in demo applications
+- **Cache service test handling** - Fixed cleanup interval keeping process alive in tests
+  - Added `unref()` to cleanup interval in `CacheService` to prevent tests from hanging
+  - Ensures Node.js process can exit cleanly after tests complete
+  - Important for CI/CD environments and test suites
+### Removed
+- **Performance logging** - Removed deprecated performance logging functionality
+  - Eliminated all performance logging code from the codebase
+  - Removed PerformanceMetrics interface and related methods
+  - Removed performance tracking logic from logger service
+  - Functionality replaced by OpenTelemetry integration
+### Technical
+- **Code quality improvements** - Enhanced development workflow and configuration
+  - Updated ESLint and Jest configurations for improved testing and code quality
+  - Enhanced configuration files and scripts for better development workflow
+  - Improved .gitignore patterns
+  - Updated package.json for testing enhancements
+- **New utility file**: `src/utils/data-client-redirect.ts` - Comprehensive redirect handling
+  - Extracted redirect logic from DataClient into dedicated utility module
+  - 424 lines of robust redirect handling with comprehensive error handling
+  - URL validation, timeout handling, and user-friendly error messages
+  - Proper separation of concerns for better maintainability
+## [3.1.2] - 2025-12-15
+### Changed
+- **DataClient refactoring** - Improved code organization and maintainability
+  - Extracted request execution logic into separate utility modules
+  - Split DataClient into focused utility files: `data-client-request.ts`, `data-client-auth.ts`, `data-client-cache.ts`, `data-client-utils.ts`
+  - Improved code organization and separation of concerns
+  - Reduced code complexity in main DataClient class
+### Fixed
+- **TypeScript error handling** - Fixed TypeScript error in retry logic
+  - Fixed type checking for error constructor name in authentication error detection
+  - Improved error type safety in retry logic
+### Technical
+- **Code quality improvements** - Significant refactoring for better maintainability
+  - Reduced DataClient.ts from ~1600 lines to ~500 lines through modularization
+  - Improved test coverage and organization
+  - Better separation of concerns between authentication, caching, and request execution
+## [3.1.1] - 2025-12-15
+### Fixed
+- **DataClient retry logic** - Improved handling of 401 authentication errors in retry logic
+  - Enhanced error type detection to prevent retries on authentication errors
+  - Added explicit checks for AuthenticationError instances to ensure 401/403 errors are not retried
+  - Improved statusCode extraction from error objects for more reliable retry decisions
+## [3.1.0] - 2025-12-15
+### Added
+- **Public and Private Controller URL Support** - Separate URLs for browser and server environments
+  - New `controllerPublicUrl` configuration option for browser/Vite environments (accessible from internet)
+  - New `controllerPrivateUrl` configuration option for server environments (internal network access)
+  - New `resolveControllerUrl()` utility function that automatically detects environment and selects appropriate URL
+  - New `isBrowser()` utility function for environment detection (checks for window, localStorage, fetch globals)
+  - Environment variable support: `MISO_WEB_SERVER_URL` (maps to `controllerPublicUrl` for browser)
+  - Environment variable support: `MISO_CONTROLLER_URL` (maps to `controllerPrivateUrl` for server, maintains backward compatibility)
+  - Automatic URL resolution based on environment:
+    - Browser environment: Uses `controllerPublicUrl` → falls back to `controllerUrl`
+    - Server environment: Uses `controllerPrivateUrl` → falls back to `controllerUrl`
+  - URL validation ensures resolved URLs are valid HTTP/HTTPS URLs
+  - Clear error messages when no URL is configured
+### Changed
+- **InternalHttpClient** - Now uses `resolveControllerUrl()` for automatic URL resolution
+  - Constructor uses resolved URL instead of hardcoded `config.controllerUrl`
+  - Client token fetch uses resolved URL for temporary axios instance
+  - Maintains backward compatibility with existing `controllerUrl` configuration
+- **AuthService** - Now uses `resolveControllerUrl()` for axios instance creation
+  - Automatically selects appropriate URL based on environment
+  - Maintains backward compatibility with existing configurations
+- **Config Loader** - Enhanced environment variable parsing
+  - `MISO_WEB_SERVER_URL` loads into `controllerPublicUrl` (browser/public)
+  - `MISO_CONTROLLER_URL` loads into `controllerPrivateUrl` (server/private) and `controllerUrl` (backward compatibility)
+  - Maintains existing behavior for applications using `MISO_CONTROLLER_URL`
+- **Documentation** - Updated configuration documentation
+  - Added sections for public/private URL configuration in `docs/configuration.md`
+  - Added examples for browser and server setup patterns
+  - Updated `docs/api-reference.md` with new utility functions and configuration options
+  - Includes migration guide and usage examples
+### Technical
+- **New utility file**: `src/utils/controller-url-resolver.ts` - URL resolution with environment detection
+  - `resolveControllerUrl()` function (35 lines, comprehensive JSDoc)
+  - `isBrowser()` helper function (7 lines)
+  - `validateUrl()` private helper function (7 lines)
+  - 100% test coverage (28 tests in `tests/unit/controller-url-resolver.test.ts`)
+- **Test coverage** - Comprehensive tests for URL resolution
+  - Browser environment detection tests (mocked window, localStorage, fetch)
+  - Server environment detection tests (no browser globals)
+  - URL resolution priority tests (public → private → controllerUrl → error)
+  - Backward compatibility tests (existing `controllerUrl` still works)
+  - Environment variable parsing tests (`MISO_WEB_SERVER_URL`, `MISO_CONTROLLER_URL`)
+  - URL validation tests (invalid URLs throw errors)
+  - Updated `tests/unit/config-loader.test.ts` with 52 new test lines
+  - Updated `tests/unit/http-client.test.ts` and `tests/unit/client.test.ts` with URL resolution tests
+- **Exports updated**:
+  - `src/index.ts` - Exports `resolveControllerUrl` and `isBrowser` utilities
+  - Public API maintains camelCase naming convention
+## [3.0.1] - 2025-12-14
+### Fixed
+- **DataClient audit logging bug** - Fixed 401 Unauthorized errors when audit logging unauthenticated requests
+  - Added `hasClientToken()` and `hasAnyToken()` helper methods to check authentication status
+  - `logAuditEvent()` now skips audit logging when no authentication token is available (user token OR client token)
+  - Prevents circular dependency where login requests trigger audit logging that requires authentication
+  - Gracefully handles audit logging errors without breaking main requests
+  - Improved error handling for 401 errors in audit logging (silently skipped for unauthenticated requests)
+### Changed
+- **Documentation improvements** - Updated documentation files to match project style and improve clarity
+  - `docs/api-reference.md` - Streamlined API documentation
+  - `docs/configuration.md` - Reduced verbosity, focused on practical examples (reduced from ~1522 to ~785 lines)
+  - `docs/data-client.md` - Improved clarity and consistency (reduced from ~1497 to ~926 lines)
+  - `docs/examples.md` - Consolidated examples, removed redundancy (reduced from ~1014 to ~991 lines)
+  - `docs/troubleshooting.md` - More action-oriented format, clearer solutions (reduced from ~965 to ~707 lines)
+  - All documentation now follows consistent "You need to:" / "Here's how:" patterns
+  - Removed jargon and technical verbosity
+  - Added consistent "✅ Use standard .env parameters" patterns throughout
+### Technical
+- **Test coverage** - Added tests for audit logging skip behavior
+  - Updated `tests/unit/data-client.test.ts` with 69 new lines of test coverage
+  - Tests verify audit logging is skipped for unauthenticated requests
+  - Tests verify audit logging still works for authenticated requests
+## [3.0.0] - 2025-12-14
+### Added
+- **Configurable client token endpoint** - Customizable client token URI for authentication
+  - New `clientTokenUri` configuration option in `MisoClientConfig` (defaults to `/api/v1/auth/token`)
+  - Environment variable support: `MISO_CLIENT_TOKEN_URI`
+  - Backward compatible with existing implementations
+  - Used by `AuthService.getEnvironmentToken()` method
+- **Origin validation for security** - CORS origin validation with wildcard port support
+  - New `allowedOrigins` configuration option in `MisoClientConfig`
+  - Environment variable support: `MISO_ALLOWED_ORIGINS` (comma-separated list)
+  - Supports wildcard ports: `http://localhost:*` (matches any port)
+  - New `validateOrigin()` utility function exported for use in miso-controller backend
+  - Checks `origin` header first, falls back to `referer` header
+  - Security-first approach: validates origin before calling controller
+- **Server-side environment token wrapper** - Secure token fetching with origin validation
+  - New `getEnvironmentToken()` server-side wrapper function
+  - Validates request origin before calling controller
+  - ISO 27001 compliant audit logging with masked client credentials
+  - Logs error and audit events on validation failures
+  - Exported from `src/index.ts` and `src/express/index.ts`
+- **Client token decoding utility** - Extract application and environment info from tokens
+  - New `extractClientTokenInfo()` utility function
+  - Decodes JWT client tokens without verification (no secret available)
+  - Supports multiple field name variations:
+    - `application` or `app`
+    - `environment` or `env`
+    - `applicationId` or `app_id`
+    - `clientId` or `client_id`
+  - Returns `ClientTokenInfo` interface with optional fields
+  - Exported from `src/index.ts` and `src/express/index.ts`
+- **DataClient `getEnvironmentToken()` method** - Browser-side token fetching with caching
+  - New public method for browser applications
+  - Checks localStorage cache first (`miso:client-token` and `miso:client-token-expires-at`)
+  - Fetches from backend endpoint if cache miss or expired
+  - Uses `clientTokenUri` from config or defaults to `/api/v1/auth/client-token`
+  - Supports absolute URLs and relative paths
+  - Handles nested and flat response formats
+  - ISO 27001 audit logging integration
+  - Automatic cache expiration handling
+- **DataClient `getClientTokenInfo()` method** - Extract token metadata in browser
+  - New public method to extract application/environment info from client token
+  - Checks cached token first, then config token
+  - Returns `ClientTokenInfo` object or `null` if no token available
+  - Useful for displaying current application/environment in UI
+  - Handles decode errors gracefully
+- **DataClient `logout()` method** - Logout functionality for browser applications
+  - Calls controller logout API to invalidate server-side session
+  - Clears authentication tokens from localStorage (all configured token keys)
+  - Clears HTTP response cache
+  - Redirects to logout URL or login page
+  - Supports optional `redirectUrl` parameter for custom redirect after logout
+  - Gracefully handles API failures (always clears local state)
+  - SSR compatible (no-op in non-browser environments)
+- **DataClient `logoutUrl` configuration** - Custom logout redirect URL
+  - Optional `logoutUrl` property in `DataClientConfig`
+  - Falls back to `loginUrl` config if not provided
+  - Supports both relative paths and absolute URLs
+  - Defaults to `/login` if neither `logoutUrl` nor `loginUrl` is configured
+### Changed
+- **AuthService `getEnvironmentToken()`** - Now uses configurable `clientTokenUri`
+  - Changed from hardcoded `/api/v1/auth/token` to `this.config.clientTokenUri || '/api/v1/auth/token'`
+  - Maintains backward compatibility (defaults to existing endpoint)
+  - Existing error handling and correlation ID generation preserved
+- **MisoClientConfig interface** - Added new configuration options
+  - New optional property: `clientTokenUri?: string`
+  - New optional property: `allowedOrigins?: string[]`
+- **DataClient configuration** - Added `logoutUrl` option to `DataClientConfig` interface
+  - New optional property: `logoutUrl?: string`
+  - Follows same pattern as `loginUrl` configuration
+### Technical
+- **New utility files**:
+  - `src/utils/origin-validator.ts` - Origin validation with wildcard port support
+  - `src/utils/environment-token.ts` - Server-side wrapper with audit logging
+  - `src/utils/token-utils.ts` - Client token decoding utility
+- **New test files**:
+  - `tests/unit/origin-validator.test.ts` - 22 tests covering origin validation
+  - `tests/unit/token-utils.test.ts` - 20 tests covering token decoding
+  - `tests/unit/environment-token.test.ts` - 10 tests covering server-side wrapper
+  - Updated `tests/unit/data-client.test.ts` - Added 22 new tests
+  - Updated `tests/unit/config-loader.test.ts` - Added 7 new tests
+  - Updated `tests/unit/auth.service.test.ts` - Added 4 new tests
+- **Exports updated**:
+  - `src/index.ts` - Exports `validateOrigin`, `getEnvironmentToken`, `extractClientTokenInfo`, and types
+  - `src/express/index.ts` - Exports same utilities for Express applications
+- **Documentation updated**:
+  - `docs/data-client.md` - Added sections for `getEnvironmentToken()` and `getClientTokenInfo()`
+  - Includes browser usage examples, server-side route examples, configuration examples, and security best practices
+## [2.2.1] - 2025-12-13
+### Fixed
+- **DataClient `redirectToLogin()`** - Fixed redirect to use controller login endpoint
+  - Now calls controller's `/api/v1/auth/login` endpoint with redirect parameter
+  - Properly constructs full redirect URL instead of relative path
+  - Falls back to static loginUrl when misoClient is unavailable or controller call fails
+### Changed
+- **DataClient `redirectToLogin()`** - Enhanced with optional redirect URL parameter
+  - Made method async to support controller API calls
+  - Added optional `redirectUrl` parameter (defaults to current page URL)
+  - Returns controller's login URL for proper OAuth flow handling
+## [2.2.0] - 2025-12-13
+### Added
+- **DataClient Browser Wrapper** - Browser-compatible HTTP client wrapper around MisoClient
+  - Enhanced HTTP client capabilities for React/front-end applications
+  - ISO 27001 compliant audit logging with configurable levels (minimal, standard, detailed, full)
+  - Automatic sensitive data masking using DataMasker before audit logging
+  - Request/response interceptors for custom request/response transformation
+  - Response caching with configurable TTL and cache size limits
+  - Automatic retry logic with exponential backoff for retryable errors
+  - Request deduplication for concurrent duplicate requests
+  - Request metrics tracking (response times, error rates, cache hit rates)
+  - Custom error types (NetworkError, TimeoutError, AuthenticationError)
+  - Browser compatibility checks with SSR support
+  - Token management from localStorage with multiple key support
+  - Automatic login redirect on authentication errors
+  - Support for all HTTP methods (GET, POST, PUT, PATCH, DELETE)
+  - Request cancellation via AbortController
+  - Per-request timeout support
+  - Integration with MisoClient for authentication and audit logging
+  - **Client Token Pattern** - Secure browser usage without exposing clientSecret
+    - Support for server-provided client tokens (`clientToken`, `clientTokenExpiresAt`)
+    - Token refresh callback pattern (`onClientTokenRefresh`) for browser applications
+    - Automatic token refresh with proactive expiration handling (60s buffer)
+    - Memory-only token storage (never persisted to localStorage)
+### Changed
+- **MisoClientConfig** - `clientSecret` is now optional when using client token pattern
+  - Added `clientToken?: string` - Pre-obtained client token for browser usage
+  - Added `clientTokenExpiresAt?: Date | string` - Token expiration tracking
+  - Added `onClientTokenRefresh?: () => Promise<{ token: string; expiresIn: number }>` - Refresh callback
+  - `InternalHttpClient` now supports both clientSecret (server-side) and clientToken (browser) patterns
+## [2.1.2] - 2025-12-11
+### Added
+- **Express.js Utilities** - Complete set of utilities for building Express.js REST APIs
+  - `ResponseHelper` - Standardized API response formatting (success, created, paginated, noContent, accepted)
+  - `injectResponseHelpers` - Middleware to inject response helpers into Express Response
+  - `asyncHandler` and `asyncHandlerNamed` - Automatic error handling for async route handlers
+  - `ValidationHelper` - Common validation patterns (findOrFail, ensureNotExists, ensureOwnershipOrAdmin, etc.)
+  - `AppError` - Application error class with RFC 7807 support
+  - `handleRouteError` - Centralized error handling for Express routes
+  - `setErrorLogger` - Injectable error logger for custom logging
+  - `EncryptionUtil` - AES-256-GCM encryption utility (replaces EncryptionService)
+  - Express Response type augmentation for TypeScript
+- **Sort Utilities** - Client-side sorting helpers
+  - `applySorting()` - Apply sorting to in-memory data arrays
+  - `parseSortParams()` - Parse sort query parameters (already existed)
+- **GitHub Workflows** - Manual release management
+  - Manual Version Bump workflow - Bump version, create git tags, and GitHub Releases
+  - Manual Publish to NPM workflow - Publish to npm with validation and verification
+- **Package Configuration**
+  - Express as optional peer dependency (^4.18.0 || ^5.0.0)
+  - @types/express as dev dependency
+- **Authentication API Updates**
+  - `LoginResponse` and `LogoutResponse` types for standardized authentication responses
+  - Updated `login()` method to make API call to `/api/v1/auth/login` with query parameters (redirect, state)
+  - Updated `logout()` method to accept token parameter and make API call to `/api/v1/auth/logout`
+  - Comprehensive test coverage for `response-middleware.ts` (100% coverage)
+### Changed
+- **Package Description** - Updated to include Express.js utilities
+- **EncryptionService** - Replaced instance-based EncryptionService with static EncryptionUtil class
+- **Workflow Strategy** - Removed automatic publish on push, added manual workflows for better control
+- **Authentication Methods** - Breaking changes:
+  - `login()` - Changed from synchronous method returning URL string to async method returning `LoginResponse` object
+  - `logout()` - Now requires `{ token: string }` parameter and returns `LogoutResponse` object
+### Removed
+- Old automatic npm-publish workflow (replaced by manual workflows)
+- EncryptionService class (replaced by EncryptionUtil)
+## [2.0.0] - Previous Release
+See git history for previous changes.