soajs.controller 4.2.42 → 4.2.43

package/docs/middleware/cors.md

@@ -0,0 +1,88 @@
+# CORS Middleware
+
+**File:** `mw/cors/index.js`
+
+**Order:** 2
+
+The CORS middleware handles Cross-Origin Resource Sharing headers and preflight (OPTIONS) requests.
+
+## Purpose
+
+- Handles OPTIONS preflight requests
+- Sets appropriate CORS headers on all responses
+- Configurable via registry `serviceConfig.cors`
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Check CORS     │ registry.serviceConfig.cors.enabled?
+  │  Enabled?       │
+  └────────┬────────┘
+           │
+           ├─── No ──▶ next()
+           │
+           ▼
+  ┌─────────────────┐
+  │  Is OPTIONS     │ req.method === 'OPTIONS'?
+  │  Request?       │
+  └────────┬────────┘
+           │
+           ├─── Yes ──▶ Set headers, return 204 No Content
+           │
+           ▼
+  ┌─────────────────┐
+  │  Set CORS       │ Access-Control-Allow-Origin
+  │  Headers        │ Access-Control-Allow-Credentials
+  └────────┬────────┘ Access-Control-Expose-Headers
+           │
+           ▼
+       next()
+```
+
+## Configuration
+
+Located in `registry.serviceConfig.cors`:
+
+```javascript
+{
+  "cors": {
+    "enabled": true,
+    "origin": "*",                    // Default: "*"
+    "credentials": "true",            // Default: "true"
+    "methods": "GET,HEAD,PUT,PATCH,POST,DELETE",
+    "headers": "__env,key,soajsauth,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type",
+    "maxage": 1728000                 // Default: 1728000 (20 days)
+  }
+}
+```
+
+## Response Headers
+
+### Preflight (OPTIONS) Response
+
+| Header | Value |
+|--------|-------|
+| `Access-Control-Allow-Origin` | Configured origin or `*` |
+| `Access-Control-Allow-Credentials` | `true` |
+| `Access-Control-Allow-Methods` | Configured methods |
+| `Access-Control-Allow-Headers` | Configured headers |
+| `Access-Control-Max-Age` | Configured max age |
+| `Access-Control-Expose-Headers` | Configured headers |
+
+### Regular Response
+
+| Header | Value |
+|--------|-------|
+| `Access-Control-Allow-Origin` | Configured origin or `*` |
+| `Access-Control-Allow-Credentials` | `true` |
+| `Access-Control-Expose-Headers` | Configured headers |
+
+## Usage Notes
+
+- If CORS is not enabled in config, middleware passes through without action
+- OPTIONS requests return immediately with 204 status (no body)
+- Default headers include SOAJS-specific headers (`__env`, `key`, `soajsauth`)

package/docs/middleware/enhancer.md

@@ -0,0 +1,75 @@
+# Enhancer Middleware
+
+**File:** `mw/enhancer/index.js`
+
+**Order:** 5
+
+The Enhancer middleware adds utility methods to the request object for header handling and client IP detection.
+
+## Purpose
+
+- Adds `req.get()` for case-insensitive header retrieval
+- Adds `req.getClientIP()` for client IP address extraction
+- Handles proxy headers (X-Forwarded-For)
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Attach get()   │ Case-insensitive header getter
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Attach         │ Client IP extraction
+  │  getClientIP()  │
+  └────────┬────────┘
+           │
+           ▼
+       next()
+```
+
+## Methods Added
+
+### `req.get(headerName)`
+
+Retrieves a header value (case-insensitive).
+
+**Parameters:**
+- `headerName` - Name of the header to retrieve
+
+**Returns:** Header value or `undefined`
+
+**Example:**
+```javascript
+let key = req.get("key");           // Works
+let key = req.get("Key");           // Also works
+let key = req.get("KEY");           // Also works
+```
+
+### `req.getClientIP()`
+
+Extracts the client's IP address, handling proxy scenarios.
+
+**Logic:**
+1. Check `X-Forwarded-For` header (first IP if comma-separated)
+2. Fall back to `req.connection.remoteAddress`
+3. Fall back to `req.socket.remoteAddress`
+4. Fall back to `req.connection.socket.remoteAddress`
+
+**Returns:** Client IP address string
+
+**Example:**
+```javascript
+let clientIP = req.getClientIP();
+// "192.168.1.100" or "::1" for localhost
+```
+
+## Usage Notes
+
+- `get()` is used throughout the codebase for header access
+- `getClientIP()` is used by IP whitelist/blacklist checks
+- Proxy support requires `X-Forwarded-For` header from load balancer

package/docs/middleware/favicon.md

@@ -0,0 +1,36 @@
+# Favicon Middleware
+
+**File:** `mw/favicon/index.js`
+
+**Order:** 3
+
+The Favicon middleware serves favicon requests to prevent them from being routed as service requests.
+
+## Purpose
+
+- Intercepts `/favicon.ico` requests
+- Returns an empty response immediately
+- Prevents favicon requests from reaching service routing
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Is Favicon     │ req.url === '/favicon.ico'?
+  │  Request?       │
+  └────────┬────────┘
+           │
+           ├─── Yes ──▶ res.writeHead(200), res.end()
+           │
+           ▼
+       next()
+```
+
+## Usage Notes
+
+- Simple passthrough middleware for non-favicon requests
+- Returns 200 OK with empty body for favicon requests
+- Prevents unnecessary service resolution for browser favicon requests

package/docs/middleware/gotoService.md

@@ -0,0 +1,146 @@
+# GotoService Middleware
+
+**File:** `mw/gotoService/index.js`
+
+**Order:** 13
+
+The GotoService middleware determines the routing strategy and prepares service parameters for request forwarding.
+
+## Purpose
+
+- Extracts and validates service build parameters
+- Handles special routes (`/soajs/acl`, `/soajs/proxy`, `/proxy/redirect`)
+- Selects appropriate routing strategy
+- Validates external key when required
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Is /soajs/acl  │ Gateway ACL route?
+  │  Route?         │
+  └────────┬────────┘
+           │
+           ├─── Yes ──▶ soajs_keyACL handler
+           │
+           ▼
+  ┌─────────────────┐
+  │  Is Proxy       │ /soajs/proxy or /proxy/redirect?
+  │  Route?         │
+  └────────┬────────┘
+           │
+           ├─── Yes ──▶ Mark as proxy, continue
+           │
+           ▼
+  ┌──────────────────────────┐
+  │  Extract Build           │ extractBuildParameters()
+  │  Parameters              │
+  └────────┬─────────────────┘
+           │
+           ├─── Error ──▶ Error 130
+           │
+           ▼
+  ┌──────────────────────────┐
+  │  Validate External       │ If extKeyRequired
+  │  Key (if required)       │
+  └────────┬─────────────────┘
+           │
+           ├─── Invalid key ──▶ Error 132
+           │
+           ▼
+  ┌──────────────────────────┐
+  │  Select Routing          │ Based on request type
+  │  Strategy                │
+  └────────┬─────────────────┘
+           │
+           ▼
+       next()
+```
+
+## Routing Strategies
+
+The middleware sets `req.soajs.controller.gotoservice` to one of:
+
+### 1. simpleRTS
+
+**Trigger:** `/oauth/passport/login`
+
+Lightweight OAuth flow for passport-based authentication.
+
+### 2. roaming
+
+**Trigger:** `soajsroaming` header present
+
+Cross-environment request forwarding.
+
+### 3. proxyRequest
+
+**Trigger:** `/soajs/proxy` or `/proxy/redirect` (deprecated)
+
+Service-to-service or external URL proxying.
+
+### 4. redirectToService (Default)
+
+**Trigger:** Standard service requests
+
+Standard REST API proxy to target service.
+
+```
+                            ┌─────────────────────────┐
+                            │    Incoming Request     │
+                            └───────────┬─────────────┘
+                                        │
+                    ┌───────────────────┼───────────────────┐
+                    │                   │                   │
+                    ▼                   ▼                   ▼
+        ┌───────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
+        │  Passport Login?  │ │  Roaming Header?│ │  Proxy Route?       │
+        │  /oauth/passport  │ │  soajsroaming   │ │  /soajs/proxy       │
+        │  /login           │ │                 │ │                     │
+        └─────────┬─────────┘ └────────┬────────┘ └──────────┬──────────┘
+                  │                    │                     │
+        ┌─────────▼─────────┐ ┌────────▼────────┐ ┌──────────▼──────────┐
+        │    simpleRTS      │ │    roaming      │ │    proxyRequest     │
+        └───────────────────┘ └─────────────────┘ └─────────────────────┘
+                                        │
+                                        │ (Default)
+                                        ▼
+                            ┌─────────────────────────┐
+                            │   redirectToService     │
+                            └─────────────────────────┘
+```
+
+## Build Parameters Extracted
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | Service name |
+| `version` | Service version |
+| `path` | API path |
+| `registry` | Service registry entry |
+| `extKeyRequired` | Whether external key is required |
+| `url` | Target URL (for endpoint services) |
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 130 | Service not found or missing port/hosts |
+| 132 | Missing or invalid external key |
+
+## Related Files
+
+- `lib/extractBuildParameters.js` - Parameter extraction logic
+- `simpleRTS.js` - Passport login handler
+- `roaming.js` - Cross-environment handler
+- `proxyRequest.js` - Proxy route handler
+- `redirectToService.js` - Standard service proxy
+
+## Usage Notes
+
+- `/proxy/redirect` is deprecated, logs warning
+- External key validation uses `core.key.getInfo()`
+- Build parameters stored in `req.soajs.controller.serviceParams`

package/docs/middleware/ip2ban.md

@@ -0,0 +1,70 @@
+# IP2Ban Middleware
+
+**File:** `mw/ip2ban/index.js`
+
+**Order:** 6
+
+The IP2Ban middleware blocks requests from blacklisted IP addresses.
+
+## Purpose
+
+- Enforces IP blacklist from custom registry
+- Returns 403 Forbidden for banned IPs
+- Early rejection before any service processing
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Get ip2ban     │ registry.custom.gateway.value.traffic.ip2ban
+  │  List           │
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Get Client IP  │ req.getClientIP()
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  IP in          │ ip2ban.includes(clientIP)?
+  │  Blacklist?     │
+  └────────┬────────┘
+           │
+           ├─── Yes ──▶ 403 Forbidden { msg: "banned" }
+           │
+           ▼
+       next()
+```
+
+## Configuration
+
+Located in `registry.custom.gateway.value.traffic.ip2ban`:
+
+```javascript
+{
+  "traffic": {
+    "ip2ban": [
+      "192.168.1.100",
+      "10.0.0.50",
+      "::1"
+    ]
+  }
+}
+```
+
+## Response
+
+Banned IPs receive:
+- HTTP Status: `403`
+- Body: `{ "msg": "banned" }`
+
+## Usage Notes
+
+- Runs early in the pipeline (order 6) for quick rejection
+- Simple exact-match comparison (no CIDR support at this level)
+- Use MT whitelist for CIDR range support
+- IPv6 addresses supported (e.g., `::1` for localhost)

package/docs/middleware/key.md

@@ -0,0 +1,196 @@
+# Key Middleware
+
+**File:** `mw/key/index.js`
+
+The Key middleware is responsible for loading and validating external tenant keys. It extracts the key from the request headers and retrieves the associated tenant, application, and package data from the provision database.
+
+## Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           KEY MIDDLEWARE FLOW                                   │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Extract Key    │ req.get("key") - from headers
+  │  from Headers   │
+  └────────┬────────┘
+           │
+           ├─── No key? ──▶ next() (continue without key data)
+           │
+           ▼
+  ┌─────────────────┐
+  │  Get External   │ provision.getExternalKeyData(key, serviceConfig.key)
+  │  Key Data       │
+  └────────┬────────┘
+           │
+           ├─── Error/Not found? ──▶ Error 148 (Invalid or disabled key)
+           │
+           ▼
+  ┌─────────────────┐
+  │  Store keyObj   │ req.soajs.controller.serviceParams.keyObj = keyObj
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Validate Key   │ Check if key.env matches current environment
+  │  Environment    │
+  └────────┬────────┘
+           │
+           ├─── Mismatch? ──▶ Error 144 (Key not valid for this environment)
+           │
+           ▼
+  ┌─────────────────────┐
+  │  Network Package    │ Check keyObj.config.gateway.networkPackages
+  │  Override           │ for network-based package substitution
+  └────────┬────────────┘
+           │
+           ├─── Override found? ──▶ Replace keyObj.application.package
+           │                        Log debug message
+           ▼
+  ┌─────────────────┐
+  │  Get Package    │ provision.getPackageData(keyObj.application.package)
+  │  Data           │
+  └────────┬────────┘
+           │
+           ├─── Not found? ──▶ Error 149 (Package not found)
+           │
+           ▼
+  ┌─────────────────┐
+  │  Store packObj  │ req.soajs.controller.serviceParams.packObj = packObj
+  └────────┬────────┘
+           │
+           ▼
+       next()
+```
+
+## Key Object Structure (keyObj)
+
+Source: `soajs.core.modules/soajs.core/provision/mongo.js` → `getKeyFromDb()`
+
+```javascript
+{
+  "key": "internal_key_value",               // Internal key identifier
+  "tenant": {
+    "id": "tenant_id",                       // Tenant MongoDB _id as string
+    "code": "TCODE",                         // Tenant code (uppercase)
+    "name": "Tenant Name",                   // Tenant display name
+    "locked": false,                         // Whether tenant is locked
+    "type": "product",                       // "product" or "client"
+    "profile": {},                           // Tenant profile metadata
+    "main": {                                // Only for type="client" tenants
+      "id": "main_tenant_id",                // Parent tenant ID
+      "code": "MAIN_TCODE"                   // Parent tenant code
+    }
+  },
+  "application": {
+    "product": "PRODUCT_CODE",               // Product code
+    "package": "PRODUCT_PACK",               // Package code for ACL lookup
+    "appId": "application_id",               // Application MongoDB _id as string
+    "acl": { ... },                          // Environment-specific ACL (resolved)
+    "acl_all_env": { ... }                   // Full ACL object for all environments
+  },
+  "extKeys": [                               // Array of external keys for this key
+    {
+      "extKey": "encrypted_external_key",    // The external key value
+      "env": "DEV",                          // Environment this extKey is valid for
+      "device": { ... },                     // Optional: Device restrictions
+      "geo": { ... },                        // Optional: Geo restrictions
+      "dashboardAccess": false,              // Whether key has dashboard access
+      "expDate": null                        // Expiration date (null = no expiry)
+    }
+  ],
+  "config": {                                // Environment-specific key configuration
+    // See configuration-services-config.md for details
+  },
+  "_TTL": 86400000,                          // Cache TTL in milliseconds
+  "_TIME": 1699999999999                     // Timestamp when loaded
+}
+```
+
+## Package Object Structure (packObj)
+
+Source: `soajs.core.modules/soajs.core/provision/mongo.js` → `getPackagesFromDb()`
+
+```javascript
+{
+  "acl": { ... },                            // Environment-specific ACL (resolved)
+  "acl_all_env": { ... },                    // Full ACL object for all environments
+  "_TTL": 86400000,                          // Cache TTL in milliseconds
+  "_TIME": 1699999999999                     // Timestamp when loaded
+}
+```
+
+## ACL Structure
+
+ACL can be defined in either `keyObj.application.acl` or `packObj.acl`:
+
+```javascript
+{
+  "serviceName": {
+    "version": {
+      "access": true,                        // or false, or ["group1", "group2"]
+      "apisPermission": "restricted",        // "restricted" means whitelist mode
+      "get": {
+        "apis": {
+          "/api/path": {
+            "access": ["owner", "admin"]     // Groups allowed for this API
+          }
+        }
+      },
+      "post": { ... },
+      "put": { ... },
+      "delete": { ... }
+    }
+  }
+}
+```
+
+## Network Package Override
+
+The key middleware supports network-based package substitution, allowing different packages to be loaded based on the network identifier configured in the custom registry.
+
+See [Services Config](../configuration-services-config.md) for the full configuration structure.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                 NETWORK PACKAGE OVERRIDE FLOW (Key Middleware)                  │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  1. Get network from registry
+     network = registry.custom.gateway.value.lastSeen.network    (e.g., "mw")
+
+  2. Get product from keyObj
+     product = keyObj.application.product                        (e.g., "AVAPP")
+
+  3. Check for network package config
+     config = keyObj.config.gateway.networkPackages[network][product]
+
+  4. If config.default exists:
+     ├── Original: keyObj.application.package = "AVAPP_EXMPL"
+     ├── Override: keyObj.application.package = "AVAPP_DEFAU"
+     └── Log: "Network package override: replaced package [AVAPP_EXMPL]
+              with [AVAPP_DEFAU] for network [mw] and product [AVAPP]"
+
+  5. Continue to load the (possibly overridden) package
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 144 | External key is not valid for this environment |
+| 148 | External key is invalid or has been disabled |
+| 149 | Product package not found |
+
+## Usage Notes
+
+- The key is extracted from the `key` header (case-insensitive)
+- If no key is provided, the middleware continues without setting key data
+- Key environment validation ensures keys are only used in their designated environment
+- Network package override allows different packages per network (requires `lastSeen.network` in custom registry)
+- The keyObj and packObj are stored in `req.soajs.controller.serviceParams` for downstream middleware
+- Subsequent middleware (keyACL, mt, oauth) depends on this data for ACL and authentication