@govish/shared-services 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## Version 1.0.0
+
+### Added
+- **OfficerCacheService**: Redis-based caching service for officers with efficient indexing
+- **PenalCodeCacheService**: Redis-based caching service for penal codes
+- **DeviceCacheService**: Redis-based caching service for devices with indexing
+- **ApiKeyService**: Service for managing and validating API keys with Redis caching
+- **AuditService**: Comprehensive audit logging service with Kafka integration
+- **createAuthenticateDeviceOrOfficer**: Express middleware factory for multi-method authentication
+- **createSafeRedisGet**: Factory function for safe Redis GET operations
+- **createSafeRedisSet**: Factory function for safe Redis SET operations
+- **createSafeRedisUtils**: Factory function that creates both Redis utilities
+
+### Features
+- All services use dependency injection for testability and reusability
+- Automatic Redis reconnection handling
+- Efficient pipeline-based batch operations
+- Comprehensive error handling and logging
+- TypeScript type definitions included
+
+### Audit Service Enhancements
+- **Internal Kafka Connection**: Audit service can manage its own Kafka connection via `kafkaBrokers` configuration
+- **Custom Keys Support**: Add custom keys to audit event payloads dynamically
+- **Automatic Event Type Detection**: Automatically determines event types based on request path and method
+- **IP Address Detection**: Automatically detects client IP from multiple header sources
+- **Debug Logging Control**: `enableDebugLogs` flag to control verbose logging (defaults to `false`)
+- **Graceful Error Handling**: Silently handles Kafka unavailability without breaking requests
+- **Comprehensive Event Tracking**: Tracks user, device, officer, and microservice information
+- **Arrest-Specific Information**: Automatically extracts arrest-related data from requests
+
+### Configuration Options
+- `kafkaBrokers`: Kafka broker URLs for internal connection management
+- `kafkaClientId`: Custom Kafka client ID
+- `auditTopic`: Configurable Kafka topic (defaults to `'audit-log'`)
+- `enableDebugLogs`: Control verbose debug logging (defaults to `false`)
+- `serverName`: Server/microservice name for audit events

package/README.md

@@ -0,0 +1,376 @@
+# Govish Shared Services Package
+
+This package contains shared services, middleware, and utilities that can be used across multiple microservices.
+
+## Quick Start
+
+```typescript
+import { 
+  AuditService,
+  createAuthenticateDeviceOrOfficer,
+  SharedServicesDependencies 
+} from '@govish/shared-services';
+
+const dependencies: SharedServicesDependencies = {
+  redisClient,
+  logger,
+  kafkaBrokers: process.env.KAFKA_BROKER || 'localhost:9092',
+  auditTopic: 'audit-log',
+  enableDebugLogs: false, // Set to true for verbose logging
+};
+
+const auditService = new AuditService(dependencies);
+const authenticateDeviceOrOfficer = createAuthenticateDeviceOrOfficer(dependencies);
+```
+
+## Services Included
+
+- **OfficerCacheService**: Redis-based caching service for officers with indexing and efficient queries
+- **PenalCodeCacheService**: Redis-based caching service for penal codes
+- **DeviceCacheService**: Redis-based caching service for devices with indexing
+- **ApiKeyService**: Service for managing and validating API keys with Redis caching
+- **AuditService**: Service for logging audit events to Kafka with comprehensive event tracking
+- **authenticateDeviceOrOfficer**: Express middleware for authenticating devices, officers, or microservices via API keys
+
+## Utilities Included
+
+- **createSafeRedisGet**: Factory function to create a safe Redis GET operation with automatic reconnection
+- **createSafeRedisSet**: Factory function to create a safe Redis SET operation with automatic reconnection
+- **createSafeRedisUtils**: Factory function that creates both safeRedisGet and safeRedisSet functions
+
+## Installation
+
+This is a local package. To use it in your project:
+
+```bash
+cd packages/ob-shared-services
+npm install
+npm run build
+```
+
+## Usage
+
+### Initialization
+
+All services require dependencies to be injected. Create a factory file in your project:
+
+```typescript
+import { 
+  OfficerCacheService, 
+  PenalCodeCacheService, 
+  DeviceCacheService, 
+  ApiKeyService,
+  createAuthenticateDeviceOrOfficer,
+  SharedServicesDependencies 
+} from '@ob-main/shared-services';
+import { redisClient } from './app';
+import { logger } from './utils/logger';
+// ... other dependencies
+
+const dependencies: SharedServicesDependencies = {
+  redisClient,
+  logger,
+  authHost: process.env.AUTH_HOST,
+  authPort: process.env.AUTH_PORT,
+  serverName: process.env.SERVER_NAME,
+  auditTopic: process.env.AUDIT_TOPIC || 'audit-log',
+  enableDebugLogs: process.env.AUDIT_DEBUG_LOGS === 'true',
+  jwtConfig,
+  
+  // Option 1: Use Kafka brokers (recommended - audit service manages its own connection)
+  kafkaBrokers: process.env.KAFKA_BROKER || process.env.KAFKA_BROKERS,
+  kafkaClientId: process.env.KAFKA_CLIENT_ID || 'audit-service',
+  
+  // Option 2: Use existing producer (backward compatibility)
+  // kafkaProducer: producer,
+  // isProducerConnected: () => kafkaProducerService?.getIsConnected() || false,
+  
+  ...createSafeRedisUtils(redisClient),  // Spreads safeRedisGet and safeRedisSet
+};
+
+// Initialize services
+export const officerCacheService = new OfficerCacheService(dependencies);
+export const penalCodeCacheService = new PenalCodeCacheService(dependencies);
+export const deviceCacheService = new DeviceCacheService(dependencies);
+export const apiKeyService = new ApiKeyService(dependencies);
+export const auditService = new AuditService(dependencies);
+
+// Create middleware
+export const authenticateDeviceOrOfficer = createAuthenticateDeviceOrOfficer(dependencies);
+
+// Export Redis utilities (optional - can also use createSafeRedisUtils directly)
+export const { safeRedisGet, safeRedisSet } = createSafeRedisUtils(redisClient);
+```
+
+### Using Services
+
+```typescript
+import { 
+  officerCacheService, 
+  penalCodeCacheService,
+  deviceCacheService,
+  apiKeyService,
+  auditService,
+  safeRedisGet,
+  safeRedisSet
+} from './services/sharedServicesFactory';
+
+// Get officer by ID
+const officer = await officerCacheService.getOfficerById(123);
+
+// Get officers by station
+const officers = await officerCacheService.getOfficersByStation(1);
+
+// Store officer
+await officerCacheService.storeOfficer(officerData);
+
+// Get penal codes
+const penalCodes = await penalCodeCacheService.getPenalCodes();
+
+// Validate API key
+const apiKey = await apiKeyService.validateApiKey('ak_xxx');
+
+// Log audit event
+await auditService.logAuditEvent(req, {
+  event_type: AuditEventType.ENDPOINT_ACCESSED
+});
+
+// Log audit event with custom keys
+await auditService.logAuditEvent(req, {
+  event_type: AuditEventType.ENDPOINT_ACCESSED,
+  custom_field: 'custom_value',
+  metadata: {
+    action: 'special_action',
+    reason: 'user_requested'
+  }
+});
+
+// Use Redis utilities
+const value = await safeRedisGet('some-key');
+await safeRedisSet('some-key', 'some-value');
+```
+
+### Using Middleware
+
+```typescript
+import { authenticateDeviceOrOfficer } from './services/sharedServicesFactory';
+import { Router } from 'express';
+
+const router = Router();
+router.get('/api/v1/officers', authenticateDeviceOrOfficer, getOfficers);
+```
+
+## Dependencies
+
+The package requires the following dependencies to be provided:
+
+### Required:
+- `redisClient`: Redis client instance
+- `logger`: Winston logger instance
+
+### Optional:
+- `authHost`: Auth service host (defaults to `process.env.AUTH_HOST`)
+- `authPort`: Auth service port (defaults to `process.env.AUTH_PORT`)
+- `serverName`: Server/microservice name (defaults to `process.env.SERVER_NAME`)
+- `auditTopic`: Kafka topic for audit logs (defaults to `process.env.AUDIT_TOPIC` or `'audit-log'`)
+- `jwtConfig`: JWT configuration object (for authentication middleware)
+- `enableDebugLogs`: Enable verbose debug logging (defaults to `false`, can be set via `AUDIT_DEBUG_LOGS=true`)
+- **Kafka Configuration (choose one):**
+  - `kafkaBrokers`: Kafka broker URLs as string or array (e.g., `'localhost:9092'` or `['broker1:9092', 'broker2:9092']`) - **Recommended**: Audit service manages its own connection
+  - `kafkaClientId`: Kafka client ID (defaults to `'audit-service'`)
+  - **OR** (for backward compatibility):
+    - `kafkaProducer`: Existing Kafka producer instance
+    - `isProducerConnected`: Function that returns boolean indicating Kafka connection status
+- `safeRedisGet`: Safe Redis get function (created via `createSafeRedisGet`)
+- `safeRedisSet`: Safe Redis set function (created via `createSafeRedisSet`)
+
+## Audit Service
+
+### Features
+
+#### Automatic Event Type Detection
+The audit service automatically determines event types based on request path and method:
+- **Login events**: `LOGIN_SUCCESS`, `LOGIN_FAILED`, `LOGIN_NOT_PERMITTED`
+- **Officer events**: `OFFICER_RETRIEVED`, `OFFICERS_LISTED`
+- **Device events**: `DEVICE_RETRIEVED`, `DEVICES_LISTED`
+- **Arrest events**: `ARREST_CREATED`, `ARREST_UPDATED`, `ARREST_DELETED`, `ARREST_RETRIEVED`, `ARRESTS_LISTED`
+- **General**: `ENDPOINT_ACCESSED`, `UNAUTHORIZED_ACCESS`, `FORBIDDEN_ACCESS`
+
+#### Custom Keys Support
+You can add custom keys to audit events - they will be included in the Kafka message:
+
+```typescript
+await auditService.logAuditEvent(req, {
+  custom_field: 'custom_value',
+  metadata: { action: 'special_action' },
+  any_other_key: 'any_value'
+});
+```
+
+#### IP Address Detection
+The audit service automatically detects client IP addresses from multiple sources (in order of priority):
+1. `x-forwarded-for` (most common behind proxies/load balancers)
+2. `cf-connecting-ip` (Cloudflare)
+3. `x-real-ip` (nginx)
+4. `true-client-ip` (Cloudflare Enterprise)
+5. `x-client-ip`
+6. `req.ip` (requires trust proxy)
+7. `req.socket.remoteAddress`
+8. `req.connection.remoteAddress`
+
+#### Kafka Connection Management
+The audit service can manage its own Kafka connection when `kafkaBrokers` is provided:
+- Creates its own Kafka client and producer
+- Handles connection lifecycle automatically
+- Connects on first use (lazy connection)
+- Gracefully handles connection failures
+- Falls back silently if Kafka is unavailable (doesn't break requests)
+
+#### User Information Tracking
+Automatically extracts and includes:
+- Officer information (id, name, service_number, email)
+- Device information (id, device_id)
+- Microservice information (for API key authentication)
+- Authentication type (officer, device, both, api_key, microservice)
+
+### Usage Examples
+
+```typescript
+import { auditService, AuditEventType } from './services/sharedServicesFactory';
+
+// Basic usage - event type determined automatically
+await auditService.logAuditEvent(req, {});
+
+// Explicit event type
+await auditService.logAuditEvent(req, {
+  event_type: AuditEventType.ARREST_CREATED
+});
+
+// With custom keys
+await auditService.logAuditEvent(req, {
+  event_type: AuditEventType.ARREST_CREATED,
+  custom_action: 'manual_review',
+  review_reason: 'suspicious_pattern'
+});
+
+// With response information
+await auditService.logAuditEvent(req, {
+  response_status: 200,
+  duration_ms: 150
+});
+
+// Log endpoint access (helper method)
+await auditService.logEndpointAccess(req);
+
+// Log with response status (helper method)
+const startTime = Date.now();
+// ... handle request ...
+await auditService.logEndpointAccessWithResponse(req, res, startTime);
+```
+
+## Environment Variables
+
+### Audit Service Configuration
+```bash
+# Kafka brokers (required for internal connection)
+KAFKA_BROKER=localhost:9092
+# or
+KAFKA_BROKERS=broker1:9092,broker2:9092
+
+# Kafka client ID (optional)
+KAFKA_CLIENT_ID=audit-service
+
+# Audit topic (optional, defaults to 'audit-log')
+AUDIT_TOPIC=audit-log
+
+# Enable debug logs (optional, defaults to false)
+AUDIT_DEBUG_LOGS=true
+```
+
+### Other Configuration
+```bash
+# Auth service (for device/officer service fallback)
+AUTH_HOST=localhost
+AUTH_PORT=3000
+
+# Server name
+SERVER_NAME=ob-main
+```
+
+## Environment Modes
+
+The package respects the `NODE_ENV` environment variable to control logging behavior:
+
+### Development Mode (`NODE_ENV=development` or `NODE_ENV=dev`)
+- All console logs are shown (debug, info, warnings, errors)
+- Detailed error information is displayed
+- Debug logging is enabled
+- Full stack traces are shown
+
+### Production Mode (`NODE_ENV=production` or `NODE_ENV=prod`)
+- Console logs are suppressed (only errors with minimal info)
+- Only warnings and errors are logged via Winston logger
+- Debug and info logs are hidden
+- Reduced logging for better performance
+
+### Usage
+
+The package provides utility functions for conditional logging:
+
+```typescript
+import { devLog, devError, devWarn, devDebug, isDevelopmentMode } from '@govish/shared-services';
+
+// Only logs in development mode
+devLog('This will only show in dev mode');
+devDebug('Debug information');
+devWarn('Warning message');
+
+// Errors always log, but with less detail in production
+devError('Error occurred', errorDetails);
+
+// Check mode programmatically
+if (isDevelopmentMode()) {
+  // Development-only code
+}
+```
+
+### Logger Configuration
+
+The Winston logger automatically adjusts based on environment:
+- **Development**: Logs all levels (debug, info, warn, error) to console and files
+- **Production**: Only logs warnings and errors to files (console disabled unless `LOG_TO_CONSOLE=true`)
+
+To enable console logging in production, set:
+```bash
+LOG_TO_CONSOLE=true
+```
+
+### Debug Logging Control
+
+The audit service has its own debug logging control via `enableDebugLogs`:
+
+```typescript
+// Enable all debug logs (console.log, console.error for audit service)
+const dependencies: SharedServicesDependencies = {
+  // ...
+  enableDebugLogs: true, // or set AUDIT_DEBUG_LOGS=true
+};
+```
+
+When `enableDebugLogs` is `false` (default):
+- No `[AUDIT KAFKA]` debug logs
+- No `[AUDIT]` user access logs
+- Only errors are logged via Winston logger
+
+When `enableDebugLogs` is `true`:
+- All `[AUDIT KAFKA]` debug logs are shown
+- `[AUDIT]` user access logs are shown
+- Detailed Kafka connection and send logs
+
+## Building
+
+```bash
+npm run build
+```
+
+This will compile TypeScript to JavaScript in the `dist/` directory.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { OfficerCacheService } from './services/officerCacheService';
+export { OfficerService } from './services/officerService';
+export { PenalCodeCacheService } from './services/penalCodeCacheService';
+export { DeviceCacheService } from './services/deviceCacheService';
+export { DeviceService } from './services/deviceService';
+export { ApiKeyService } from './services/apiKeyService';
+export type { ApiKeyData } from './services/apiKeyService';
+export { AuditService } from './services/auditService';
+export { AuditEventType } from './services/auditService';
+export type { AuditEventPayload } from './services/auditService';
+export { createAuthenticateDeviceOrOfficer } from './middleware/authenticateDevice';
+export { createSafeRedisGet, createSafeRedisSet, createSafeRedisUtils } from './utils/redis';
+export { getEnvironmentMode, isDevelopmentMode, isProductionMode, devLog, devError, devWarn, devDebug } from './utils/logMode';
+export type { EnvironmentMode } from './utils/logMode';
+export type { SharedServicesDependencies } from './types/dependencies';

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devDebug = exports.devWarn = exports.devError = exports.devLog = exports.isProductionMode = exports.isDevelopmentMode = exports.getEnvironmentMode = exports.createSafeRedisUtils = exports.createSafeRedisSet = exports.createSafeRedisGet = exports.createAuthenticateDeviceOrOfficer = exports.AuditEventType = exports.AuditService = exports.ApiKeyService = exports.DeviceService = exports.DeviceCacheService = exports.PenalCodeCacheService = exports.OfficerService = exports.OfficerCacheService = void 0;
+// Export services
+var officerCacheService_1 = require("./services/officerCacheService");
+Object.defineProperty(exports, "OfficerCacheService", { enumerable: true, get: function () { return officerCacheService_1.OfficerCacheService; } });
+var officerService_1 = require("./services/officerService");
+Object.defineProperty(exports, "OfficerService", { enumerable: true, get: function () { return officerService_1.OfficerService; } });
+var penalCodeCacheService_1 = require("./services/penalCodeCacheService");
+Object.defineProperty(exports, "PenalCodeCacheService", { enumerable: true, get: function () { return penalCodeCacheService_1.PenalCodeCacheService; } });
+var deviceCacheService_1 = require("./services/deviceCacheService");
+Object.defineProperty(exports, "DeviceCacheService", { enumerable: true, get: function () { return deviceCacheService_1.DeviceCacheService; } });
+var deviceService_1 = require("./services/deviceService");
+Object.defineProperty(exports, "DeviceService", { enumerable: true, get: function () { return deviceService_1.DeviceService; } });
+var apiKeyService_1 = require("./services/apiKeyService");
+Object.defineProperty(exports, "ApiKeyService", { enumerable: true, get: function () { return apiKeyService_1.ApiKeyService; } });
+var auditService_1 = require("./services/auditService");
+Object.defineProperty(exports, "AuditService", { enumerable: true, get: function () { return auditService_1.AuditService; } });
+var auditService_2 = require("./services/auditService");
+Object.defineProperty(exports, "AuditEventType", { enumerable: true, get: function () { return auditService_2.AuditEventType; } });
+// Export middleware
+var authenticateDevice_1 = require("./middleware/authenticateDevice");
+Object.defineProperty(exports, "createAuthenticateDeviceOrOfficer", { enumerable: true, get: function () { return authenticateDevice_1.createAuthenticateDeviceOrOfficer; } });
+// Export utilities
+var redis_1 = require("./utils/redis");
+Object.defineProperty(exports, "createSafeRedisGet", { enumerable: true, get: function () { return redis_1.createSafeRedisGet; } });
+Object.defineProperty(exports, "createSafeRedisSet", { enumerable: true, get: function () { return redis_1.createSafeRedisSet; } });
+Object.defineProperty(exports, "createSafeRedisUtils", { enumerable: true, get: function () { return redis_1.createSafeRedisUtils; } });
+var logMode_1 = require("./utils/logMode");
+Object.defineProperty(exports, "getEnvironmentMode", { enumerable: true, get: function () { return logMode_1.getEnvironmentMode; } });
+Object.defineProperty(exports, "isDevelopmentMode", { enumerable: true, get: function () { return logMode_1.isDevelopmentMode; } });
+Object.defineProperty(exports, "isProductionMode", { enumerable: true, get: function () { return logMode_1.isProductionMode; } });
+Object.defineProperty(exports, "devLog", { enumerable: true, get: function () { return logMode_1.devLog; } });
+Object.defineProperty(exports, "devError", { enumerable: true, get: function () { return logMode_1.devError; } });
+Object.defineProperty(exports, "devWarn", { enumerable: true, get: function () { return logMode_1.devWarn; } });
+Object.defineProperty(exports, "devDebug", { enumerable: true, get: function () { return logMode_1.devDebug; } });

package/dist/middleware/authenticateDevice.d.ts

@@ -0,0 +1,15 @@
+import { Request, Response, NextFunction } from 'express';
+import { SharedServicesDependencies } from '../types/dependencies';
+/**
+ * Middleware to authenticate either a device, an officer, or a microservice (via API key)
+ * Checks JWT token and validates against Device or Officer table
+ * Also checks for API keys for microservice authentication
+ *
+ * Supports multiple authentication methods:
+ * - X-API-Key: <api_key> (for microservice authentication)
+ * - Device-Token: <device_jwt_token> (for device authentication)
+ * - Authorization: Bearer <user_jwt_token> (for officer/user authentication)
+ *
+ * Priority: API Key > Device Token > Authorization Token
+ */
+export declare const createAuthenticateDeviceOrOfficer: (deps: SharedServicesDependencies) => (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;