soajs.controller 4.2.42 → 4.2.43

package/docs/middleware/keyACL.md

@@ -0,0 +1,139 @@
+# Key ACL Middleware
+
+**File:** `mw/keyACL/index.js`
+
+**Order:** 12
+
+The Key ACL middleware extracts and processes the Access Control List (ACL) from the tenant's key or package.
+
+## Purpose
+
+- Extracts ACL for the requested service
+- Resolves ACL from application or package level
+- Handles both old and new ACL schema formats
+- Supports version-specific and method-specific ACL
+
+## Flow
+
+```
+  Incoming Request (after key middleware)
+       │
+       ▼
+  ┌─────────────────┐
+  │  Have keyObj    │ keyObj && packObj exist?
+  │  and packObj?   │
+  └────────┬────────┘
+           │
+           ├─── No ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Extract ACL            │ Priority:
+  │  for Service            │ 1. keyObj.application.acl
+  └────────┬────────────────┘ 2. packObj.acl
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Detect Schema Type     │ Old: apis/apisRegExp at root
+  │                         │ New: versioned with methods
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Resolve Version        │ Match requested version
+  │  (if versioned)         │ or get latest from ACL
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Extract Method-        │ get, post, put, delete
+  │  Specific ACL           │
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Store finalAcl         │ req.soajs.controller.serviceParams.finalAcl
+  └────────┬────────────────┘
+           │
+           ▼
+       next()
+```
+
+## ACL Resolution Priority
+
+1. **Application ACL** - `keyObj.application.acl[serviceName]`
+2. **Package ACL** - `packObj.acl[serviceName]`
+
+## ACL Schema Formats
+
+### Old Schema (Deprecated)
+
+```javascript
+{
+  "serviceName": {
+    "access": true,
+    "apis": {
+      "/api/path": { "access": ["group1"] }
+    },
+    "apisRegExp": [
+      { "regExp": /^\/api\/.*/, "access": ["group2"] }
+    ]
+  }
+}
+```
+
+### New Schema (Versioned)
+
+```javascript
+{
+  "serviceName": {
+    "1": {                              // Version
+      "access": true,
+      "apisPermission": "restricted",
+      "get": {
+        "apis": { "/user": {} }
+      },
+      "post": {
+        "apis": { "/user": { "access": ["admin"] } }
+      }
+    }
+  }
+}
+```
+
+### New Schema (Method-Based, Non-Versioned)
+
+```javascript
+{
+  "serviceName": {
+    "access": true,
+    "apisPermission": "restricted",
+    "get": {
+      "apis": { "/user": {} }
+    },
+    "post": {
+      "apis": { "/user": { "access": ["admin"] } }
+    }
+  }
+}
+```
+
+## Properties Set
+
+| Property | Description |
+|----------|-------------|
+| `req.soajs.controller.serviceParams.finalAcl` | Processed ACL for the service |
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 154 | Requested version not found in ACL |
+
+## Usage Notes
+
+- Runs after key middleware loads keyObj and packObj
+- Application-level ACL overrides package ACL
+- If no version specified, uses latest version from ACL
+- Converts regex patterns for API matching
+- Method-specific ACL inherits service-level `access` and `apisPermission`

package/docs/middleware/lastSeen.md

@@ -0,0 +1,111 @@
+# LastSeen Middleware
+
+**File:** `mw/lastSeen/index.js`
+
+**Order:** 17
+
+The LastSeen middleware asynchronously notifies a service (typically URAC) of user activity for tracking purposes.
+
+## Purpose
+
+- Tracks user activity (last seen time)
+- Asynchronous notification (non-blocking)
+- Configurable service endpoint
+- Only tracks authenticated users
+
+## Flow
+
+```
+  Incoming Request (after OAuth/MT)
+       │
+       ▼
+  ┌─────────────────┐
+  │  Call next()    │ Continue immediately (non-blocking)
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Have URAC Driver?      │ req.soajs.uracDriver exists?
+  └────────┬────────────────┘
+           │
+           ├─── No ──▶ (done)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  LastSeen Active?       │ custom.gateway.value.lastSeen.active?
+  └────────┬────────────────┘
+           │
+           ├─── No ──▶ (done)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Get User ID            │ From URAC profile
+  └────────┬────────────────┘
+           │
+           ├─── No user ID ──▶ (done, log debug)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Resolve Service Host   │ awareness.getHost()
+  └────────┬────────────────┘
+           │
+           ├─── No host ──▶ (done, log debug)
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  POST to LastSeen       │ http://host:port/api
+  │  API (async)            │ body: { network: ... }
+  └─────────────────────────┘
+```
+
+## Configuration
+
+Located in `registry.custom.gateway.value.lastSeen`:
+
+```javascript
+{
+  "lastSeen": {
+    "active": true,                      // Enable tracking
+    "serviceName": "urac",               // Target service
+    "serviceVersion": "3",               // Service version
+    "api": "/user/last/seen",            // API endpoint
+    "network": "internal"                // Optional network identifier
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `active` | boolean | `false` | Enable/disable tracking |
+| `serviceName` | string | `"urac"` | Service to notify |
+| `serviceVersion` | string | `"3"` | Service version |
+| `api` | string | `"/user/last/seen"` | API endpoint |
+| `network` | string | - | Network identifier in request body |
+
+## Request to URAC
+
+**Method:** POST
+
+**URL:** `http://{host}:{port}/user/last/seen`
+
+**Headers:**
+```
+Content-Type: application/json
+soajsinjectobj: <inject object from MT middleware>
+```
+
+**Body:**
+```javascript
+{
+  "network": "internal"                  // If configured
+}
+```
+
+## Usage Notes
+
+- Non-blocking: calls `next()` immediately
+- Only activates for authenticated users with URAC profile
+- Errors are logged but don't affect the request
+- Uses awareness for service host resolution
+- Forwards `soajsinjectobj` header for authentication context
+- Network identifier useful for tracking activity by location/network

package/docs/middleware/maintenanceMode.md

@@ -0,0 +1,81 @@
+# Maintenance Mode Middleware
+
+**File:** `mw/maintenanceMode/index.js`
+
+**Order:** 7
+
+The Maintenance Mode middleware returns a configurable response when the gateway is in maintenance mode.
+
+## Purpose
+
+- Blocks all requests when maintenance mode is enabled
+- Returns configurable status code and message
+- Supports `Retry-After` header for clients
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────┐
+  │  Get Maintenance    │ registry.custom.gateway.value.maintenanceMode
+  │  Mode Config        │
+  └────────┬────────────┘
+           │
+           ▼
+  ┌─────────────────────┐
+  │  Maintenance        │ maintenanceMode.on === true?
+  │  Enabled?           │
+  └────────┬────────────┘
+           │
+           ├─── Yes ──▶ Return configured status/message
+           │            Set Retry-After header if configured
+           ▼
+       next()
+```
+
+## Configuration
+
+Located in `registry.custom.gateway.value.maintenanceMode`:
+
+```javascript
+{
+  "maintenanceMode": {
+    "on": true,                              // Enable maintenance mode
+    "status": 503,                           // HTTP status code
+    "message": "System maintenance",         // Response message
+    "retryAfter": 3600                       // Retry-After header (seconds)
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `on` | boolean | `false` | Enable/disable maintenance mode |
+| `status` | number | `503` | HTTP status code |
+| `message` | string | `"Maintenance mode is on, come back soon"` | Response message |
+| `retryAfter` | number | - | Seconds until retry |
+
+## Response
+
+When maintenance mode is enabled:
+```
+HTTP/1.1 503 Service Unavailable
+Content-Type: application/json
+Retry-After: 3600
+
+{
+  "result": false,
+  "errors": {
+    "codes": [xxx],
+    "details": [{ "code": xxx, "message": "System maintenance" }]
+  }
+}
+```
+
+## Usage Notes
+
+- All requests blocked when enabled (no exceptions)
+- Configure via Core DB custom registry
+- Use maintenance port (5000) for health checks during maintenance

package/docs/middleware/mt.md

@@ -0,0 +1,188 @@
+# MT (Multi-Tenant) Middleware
+
+**File:** `mw/mt/index.js`
+
+**Order:** 14
+
+The MT middleware handles multi-tenant security checks, URAC integration, and prepares the injection header for target services.
+
+## Purpose
+
+- Enforces multi-tenant security pipeline
+- Loads tenant and application context
+- Integrates with URAC for user profiles
+- Prepares `soajsinjectobj` header for downstream services
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Is Proxy Route?        │ Skip security for proxy
+  └────────┬────────────────┘
+           │
+           ├─── Yes ──▶ Execute OAuth check → next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  External Key           │ Based on service config
+  │  Required?              │
+  └────────┬────────────────┘
+           │
+           ├─── No ──▶ Mark as public API → OAuth check
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Load Tenant Context    │ From keyObj
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Security Pipeline      │ Waterfall checks:
+  │                         │ 1. IP Whitelist
+  │                         │ 2. Geo Check
+  │                         │ 3. Device Check
+  │                         │ 4. ACL Check
+  │                         │ 5. OAuth Check (if required)
+  │                         │ 6. URAC Check
+  │                         │ 7. URAC ACL Check
+  │                         │ 8. Service Check
+  │                         │ 9. API Check
+  └────────┬────────────────┘
+           │
+           ├─── Any check fails ──▶ Error response
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Build Inject Object    │ Tenant, key, app, user info
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Resolve InterConnect   │ Service-to-service awareness
+  │  (if configured)        │
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Set soajsinjectobj     │ req.headers.soajsinjectobj = JSON
+  │  Header                 │
+  └────────┬────────────────┘
+           │
+           ▼
+       next()
+```
+
+## Security Pipeline (utils.js)
+
+| Order | Check | Description |
+|-------|-------|-------------|
+| 1 | `ipWhitelist` | Validates IP against whitelist |
+| 2 | `securityGeoCheck` | Validates geographic location |
+| 3 | `securityDeviceCheck` | Validates device fingerprint |
+| 4 | `aclCheck` | Validates service-level ACL |
+| 5 | `oauthCheck` | Validates OAuth token (if required) |
+| 6 | `uracCheck` | Loads user profile from URAC |
+| 7 | `aclUrackCheck` | Validates user-specific ACL |
+| 8 | `serviceCheck` | Validates service access |
+| 9 | `apiCheck` | Validates API access |
+
+## Injection Object Structure
+
+The `soajsinjectobj` header contains:
+
+```javascript
+{
+  "tenant": {
+    "id": "tenant_id",
+    "name": "Tenant Name",
+    "code": "TCODE",
+    "locked": false,
+    "roaming": null,
+    "type": "product",
+    "main": { ... },           // If client tenant
+    "profile": { ... }         // If tenant_Profile enabled
+  },
+  "key": {
+    "config": { ... },
+    "iKey": "internal_key",
+    "eKey": "external_key"
+  },
+  "application": {
+    "product": "PRODUCT",
+    "package": "PACKAGE",
+    "appId": "app_id",
+    "acl": { ... },            // If provision_ACL enabled
+    "acl_all_env": { ... }
+  },
+  "package": {
+    "acl": { ... },            // If provision_ACL enabled
+    "acl_all_env": { ... }
+  },
+  "device": { ... },
+  "geo": { ... },
+  "awareness": {
+    "host": "controller_host",
+    "port": 4000,
+    "interConnect": [...]      // If configured
+  },
+  "urac": {                    // If authenticated
+    "_id": "user_id",
+    "username": "user",
+    "firstName": "John",
+    "lastName": "Doe",
+    "email": "user@example.com",
+    "groups": ["group1"],
+    "tenant": { "id": "...", "code": "..." },
+    "profile": { ... },        // If urac_Profile enabled
+    "acl": { ... },            // If urac_ACL enabled
+    "config": { ... },         // If urac_Config enabled
+    "groupsConfig": { ... }    // If urac_GroupConfig enabled
+  },
+  "param": {
+    "urac_Profile": true,
+    "urac_ACL": true
+  }
+}
+```
+
+## Service Parameters
+
+Service-level configuration that affects MT processing:
+
+| Parameter | Description |
+|-----------|-------------|
+| `urac` | Include URAC user info |
+| `urac_Profile` | Include user profile |
+| `urac_ACL` | Include user ACL |
+| `urac_Config` | Include user config |
+| `urac_GroupConfig` | Include group config |
+| `tenant_Profile` | Include tenant profile |
+| `provision_ACL` | Include full ACL data |
+| `extKeyRequired` | Require external key |
+| `oauth` | Require OAuth token |
+| `interConnect` | Service-to-service discovery |
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 133 | Service version not found |
+| 135 | Inject header too large |
+| 152 | Package not loaded |
+| 153 | Key not loaded |
+| 158 | Login required for ACL route |
+
+## Related Files
+
+- `mw/mt/utils.js` - Security check implementations
+- `mw/mt/urac.js` - URAC driver integration
+
+## Usage Notes
+
+- Proxy routes bypass all MT checks except OAuth
+- Header size limited by `SOAJS_MAX_INJECT_HEADER_SIZE` (default: 64KB)
+- InterConnect enables service-to-service awareness info
+- URAC integration loads user profile asynchronously

package/docs/middleware/oauth.md

@@ -0,0 +1,173 @@
+# OAuth Middleware
+
+**File:** `mw/oauth/index.js`
+
+**Order:** 15
+
+The OAuth middleware handles authentication by validating OAuth2 tokens or JWT tokens.
+
+## Purpose
+
+- Validates OAuth2 access tokens via oauth2-server
+- Validates JWT tokens via jsonwebtoken
+- Supports tenant-specific OAuth configuration
+- Sets `req.oauth` with token information
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Determine OAuth Type   │ tenantOauth.type or
+  │                         │ registry.serviceConfig.oauth.type
+  └────────┬────────────────┘
+           │
+           ├─── Type 0 (JWT) ──▶ JWT Validation
+           │
+           ├─── Type 2 (OAuth2) ──▶ OAuth2 Server Validation
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Set req.oauth          │ { bearerToken, type }
+  └────────┬────────────────┘
+           │
+           ▼
+       next() or Error
+```
+
+## OAuth Types
+
+### Type 2: OAuth2 (Default)
+
+Uses oauth2-server library for token validation.
+
+```
+  Request with access_token
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  oauth2-server          │ Validates token against DB
+  │  authorise()            │
+  └────────┬────────────────┘
+           │
+           ├─── Invalid ──▶ OAuth2Error
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  req.oauth = {          │
+  │    bearerToken: user,   │
+  │    type: 2              │
+  │  }                      │
+  └─────────────────────────┘
+```
+
+### Type 0: JWT
+
+Uses jsonwebtoken library for JWT validation.
+
+```
+  Request with Authorization: Bearer <jwt>
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Extract Bearer Token   │ from Authorization header
+  └────────┬────────────────┘
+           │
+           ├─── No match ──▶ Error 143
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  jwt.verify()           │ Using secret and algorithms
+  └────────┬────────────────┘
+           │
+           ├─── Invalid ──▶ Error 143
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  req.oauth = {          │
+  │    bearerToken: decoded,│
+  │    type: 0              │
+  │  }                      │
+  └─────────────────────────┘
+```
+
+## Configuration
+
+### OAuth2 Configuration
+
+Located in `registry.serviceConfig.oauth`:
+
+```javascript
+{
+  "oauth": {
+    "type": 2,
+    "grants": ["password", "refresh_token"],
+    "debug": false,
+    "accessTokenLifetime": 7200,
+    "refreshTokenLifetime": 1209600
+  }
+}
+```
+
+### JWT Configuration
+
+```javascript
+{
+  "oauth": {
+    "type": 0,
+    "secret": "jwt_secret_key",
+    "algorithms": ["HS256"],
+    "audience": "my-app"
+  }
+}
+```
+
+### Tenant-Specific OAuth
+
+Tenants can override OAuth settings via `tenantOauth`:
+
+```javascript
+{
+  "type": 0,                    // Override to JWT
+  "secret": "tenant_jwt_secret"
+}
+```
+
+## OAuth Service Integration
+
+Default OAuth service configuration:
+
+```javascript
+{
+  "oauthService": {
+    "name": "oauth",
+    "tokenApi": "/token",
+    "authorizationApi": "/authorization",
+    "pinApi": "/pin"
+  }
+}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 143 | Invalid or missing JWT token |
+| OAuth2Error | Various OAuth2 errors (invalid_token, expired, etc.) |
+
+## Properties Set
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `req.oauth.bearerToken` | object | Decoded token or user object |
+| `req.oauth.type` | number | OAuth type (0=JWT, 2=OAuth2) |
+
+## Usage Notes
+
+- OAuth type can be set globally or per-tenant
+- JWT requires `Authorization: Bearer <token>` header
+- OAuth2 uses `access_token` query parameter or header
+- Tenant OAuth settings override global settings
+- OAuth model is provided by configuration (provision module)