soajs.controller 4.2.42 → 4.2.43

package/docs/middleware/response.md

@@ -0,0 +1,106 @@
+# Response Middleware
+
+**File:** `mw/response/index.js`
+
+**Order:** 4
+
+The Response middleware adds standardized response builder methods to the request object.
+
+## Purpose
+
+- Adds `req.soajs.buildResponse()` for creating SOAJS-formatted responses
+- Adds `req.soajs.controllerResponse()` for sending gateway responses
+- Provides consistent error/success response structure
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Attach buildResponse() │ Creates SOAJS response objects
+  └────────────┬────────────┘
+               │
+               ▼
+  ┌─────────────────────────────┐
+  │  Attach controllerResponse()│ Sends JSON responses
+  └────────────┬────────────────┘
+               │
+               ▼
+           next()
+```
+
+## Methods Added
+
+### `req.soajs.buildResponse(error, data)`
+
+Creates a SOAJS-formatted response object.
+
+**Parameters:**
+- `error` - Error object or array of errors (optional)
+- `data` - Response data (optional)
+
+**Returns:**
+```javascript
+// Success
+{
+  "result": true,
+  "data": { ... }
+}
+
+// Error
+{
+  "result": false,
+  "errors": {
+    "codes": [100, 101],
+    "details": [
+      { "code": 100, "message": "Error message" },
+      { "code": 101, "message": "Another error" }
+    ]
+  }
+}
+```
+
+### `req.soajs.controllerResponse(jsonObj)`
+
+Sends a JSON response and ends the request.
+
+**Parameters:**
+- `jsonObj` - Response object with optional `status`, `headObj`, `code`, `msg`
+
+**Examples:**
+```javascript
+// Success response
+req.soajs.controllerResponse({ data: { user: "john" } });
+
+// Error response
+req.soajs.controllerResponse({
+  status: 403,
+  code: 150,
+  msg: "Access denied"
+});
+
+// With custom headers
+req.soajs.controllerResponse({
+  status: 429,
+  msg: "Too many requests",
+  headObj: {
+    "Retry-After": 60,
+    "X-RateLimit-Limit": 100
+  }
+});
+```
+
+## Response Format
+
+All responses include:
+- `Content-Type: application/json` header
+- HTTP status code (default: 200)
+- JSON body
+
+## Usage Notes
+
+- `controllerResponse()` only available when `controllerResponse: true` in config
+- Prevents double-ending responses (tracks `ended` state)
+- Automatically formats errors using `buildResponse()` when `code` and `msg` provided

package/docs/middleware/soajs.md

@@ -0,0 +1,71 @@
+# SOAJS Middleware
+
+**File:** `mw/soajs/index.js`
+
+**Order:** 1
+
+The SOAJS middleware is the first middleware in the pipeline. It initializes the `req.soajs` context object that all subsequent middleware depend on.
+
+## Purpose
+
+- Creates the `req.soajs` namespace
+- Attaches the logger instance
+- Attaches the current registry reference
+- Attaches core utility modules (meta, validator)
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Create         │ if (!req.soajs) req.soajs = {}
+  │  req.soajs      │
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Attach Logger  │ req.soajs.log = log
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Attach         │ req.soajs.registry = registryModule.get()
+  │  Registry       │
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Attach Core    │ req.soajs.meta = core.meta
+  │  Modules        │ req.soajs.validator = core.validator
+  └────────┬────────┘
+           │
+           ▼
+       next()
+```
+
+## Configuration
+
+```javascript
+{
+  "log": logger,        // Logger instance
+  "core": coreModule    // soajs.core.libs module
+}
+```
+
+## Properties Set
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `req.soajs.log` | object | Logger instance for request-scoped logging |
+| `req.soajs.registry` | object | Current environment registry |
+| `req.soajs.meta` | object | Metadata utilities from core |
+| `req.soajs.validator` | object | JSON schema validator |
+
+## Usage Notes
+
+- This middleware MUST be first in the pipeline
+- All other middleware assume `req.soajs` exists
+- The registry is fetched fresh on each request (reference, not copy)
+- Logger supports: `debug()`, `info()`, `warn()`, `error()`, `fatal()`

package/docs/middleware/traffic.md

@@ -0,0 +1,190 @@
+# Traffic Middleware
+
+**File:** `mw/traffic/index.js`
+
+**Order:** 16
+
+The Traffic middleware implements rate limiting (throttling) with configurable strategies and storage backends.
+
+## Purpose
+
+- Enforces rate limiting per tenant/IP
+- Supports configurable throttling strategies
+- Provides memory and MongoDB storage backends
+- Returns rate limit headers in responses
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────────────┐
+  │  Check Prerequisites    │ registry, tenant, controller exist?
+  └────────┬────────────────┘
+           │
+           ├─── Missing ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Determine Strategy     │ publicAPIStrategy or privateAPIStrategy
+  └────────┬────────────────┘
+           │
+           ├─── No strategy ──▶ next()
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Get Throttling Config  │ Priority:
+  │                         │ 1. servicesConfig.gateway.throttling
+  │                         │ 2. custom.gateway.value.traffic.throttling
+  │                         │ 3. serviceConfig.throttling
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  Check Throttling       │ Get/increment counter
+  │  Counter                │ Compare to limit
+  └────────┬────────────────┘
+           │
+           ├─── Under limit ──▶ next()
+           │
+           ├─── Over limit, retries left ──▶ Delay and retry
+           │
+           └─── Over limit, no retries ──▶ 429 Too Many Requests
+```
+
+## Configuration
+
+### Strategy Definition
+
+Located in `registry.serviceConfig.throttling`:
+
+```javascript
+{
+  "throttling": {
+    "publicAPIStrategy": "default",      // For unauthenticated requests
+    "privateAPIStrategy": "heavy",       // For authenticated requests
+    "default": {
+      "status": 1,                       // 0=Off, 1=On
+      "type": 1,                         // 0=tenant, 1=tenant+IP
+      "window": 60000,                   // Time window in ms
+      "limit": 50,                       // Max requests per window
+      "retries": 2,                      // Retries when over limit
+      "delay": 1000                      // Delay between retries (ms)
+    },
+    "heavy": {
+      "status": 1,
+      "type": 1,
+      "window": 60000,
+      "limit": 500,
+      "retries": 2,
+      "delay": 1000
+    },
+    "strict": {
+      "status": 1,
+      "type": 1,
+      "window": 60000,
+      "limit": 10,
+      "retries": 0,
+      "delay": 0
+    }
+  }
+}
+```
+
+### Service-Specific Override
+
+Via custom registry or tenant config:
+
+```javascript
+{
+  "throttling": {
+    "oauth": {
+      "publicAPIStrategy": "strict",
+      "apis": ["/token"]                 // Only these APIs
+    },
+    "payment": {
+      "publicAPIStrategy": "strict",
+      "privateAPIStrategy": "heavy",
+      "apis": ["/charge", "/refund"]
+    }
+  }
+}
+```
+
+## Strategy Selection
+
+| Request Type | Strategy Used |
+|--------------|---------------|
+| Public API (no auth) | `publicAPIStrategy` |
+| Private API (authenticated) | `privateAPIStrategy` |
+
+Determined by: `req.soajs.controller.serviceParams.isAPIPublic`
+
+## Storage Backends
+
+### Memory (Default)
+
+- Fast, in-process storage
+- Lost on restart
+- Good for single-instance deployments
+
+### MongoDB
+
+- Persistent storage
+- Shared across instances
+- Required for multi-instance deployments
+
+Configure via `registry.custom.gateway.value.traffic.model`:
+
+```javascript
+{
+  "traffic": {
+    "model": "mongo"                     // or "memory"
+  }
+}
+```
+
+## Rate Limit Response
+
+When rate limit exceeded:
+
+```
+HTTP/1.1 429 Too Many Requests
+Content-Type: application/json
+Retry-After: 45
+X-RateLimit-Limit: 50
+X-RateLimit-Remaining: 0
+
+{
+  "result": false,
+  "errors": { ... }
+}
+```
+
+## Response Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-RateLimit-Limit` | Maximum requests allowed |
+| `X-RateLimit-Remaining` | Requests remaining in window |
+| `Retry-After` | Seconds until window resets |
+
+## Throttle Key Structure
+
+```javascript
+{
+  "l1": "tenant_id",
+  "l2": "client_ip"
+}
+```
+
+Creates unique tracking per tenant per IP.
+
+## Usage Notes
+
+- Throttling disabled if no strategy configured
+- Service-specific config overrides global config
+- APIs array allows targeting specific endpoints
+- Retries add delay before rejection
+- MongoDB model required for horizontal scaling

package/docs/middleware/url.md

@@ -0,0 +1,102 @@
+# URL Middleware
+
+**File:** `mw/url/index.js`
+
+**Order:** 8
+
+The URL middleware parses the request URL and extracts service routing information.
+
+## Purpose
+
+- Parses URL into components (service name, version, path)
+- Validates service exists in registry
+- Normalizes header and query parameters (key, access_token)
+- Creates `req.soajs.controller.serviceParams` structure
+
+## Flow
+
+```
+  Incoming Request
+       │
+       ▼
+  ┌─────────────────┐
+  │  Ensure         │ if (!req.soajs.controller)
+  │  Controller     │    req.soajs.controller = {}
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Parse URL      │ url.parse(req.url, true)
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────┐
+  │  Extract        │ service_n, service_v, service_nv
+  │  Service Info   │ serviceInfo, path
+  └────────┬────────┘
+           │
+           ├─── No service name? ──▶ Error 136
+           │
+           ├─── Service not in registry? ──▶ Error 130
+           │
+           ▼
+  ┌─────────────────┐
+  │  Normalize      │ key, access_token from headers/query
+  │  Auth Params    │
+  └────────┬────────┘
+           │
+           ▼
+       next()
+```
+
+## URL Parsing
+
+**URL Format:** `/{service}/{version}/{path}`
+
+| Component | Example | Description |
+|-----------|---------|-------------|
+| `service_n` | `oauth` | Service name |
+| `service_v` | `1` | Service version (optional) |
+| `service_nv` | `oauth/1` | Service with version |
+| `path` | `/token` | API path |
+
+**Examples:**
+```
+/oauth/token         → service: oauth, version: null, path: /token
+/oauth/1/token       → service: oauth, version: 1, path: /token
+/urac/3/user/login   → service: urac, version: 3, path: /user/login
+```
+
+## Properties Set
+
+| Property | Description |
+|----------|-------------|
+| `req.soajs.controller.serviceParams.service_n` | Service name |
+| `req.soajs.controller.serviceParams.service_v` | Service version |
+| `req.soajs.controller.serviceParams.service_nv` | Service with version |
+| `req.soajs.controller.serviceParams.serviceInfo` | URL path segments array |
+| `req.soajs.controller.serviceParams.parsedUrl` | Full parsed URL object |
+| `req.query` | Query parameters |
+
+## Auth Parameter Normalization
+
+The middleware normalizes authentication parameters:
+
+1. **Key:** `req.headers.key` ← `req.headers.key || req.query.key`
+2. **Access Token:** `req.query.access_token` ←
+   - `req.query.access_token`
+   - `req.headers.access_token`
+   - Bearer token from `Authorization` header
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 130 | Service not found in registry |
+| 136 | Empty or missing service name |
+
+## Usage Notes
+
+- Throws TypeError if SOAJS middleware hasn't run first
+- Special handling for `soajs` service name (gateway routes)
+- Authorization header is deleted after extracting Bearer token

package/docs/multi-tenant-security.md

@@ -0,0 +1,183 @@
+# Multi-Tenant Security Pipeline
+
+The SOAJS Controller Gateway implements a comprehensive security pipeline for multi-tenant environments.
+
+## Security Check Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                         MULTI-TENANT SECURITY CHECKS                            │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  Incoming Request with Key
+          │
+          ▼
+  ┌───────────────────┐
+  │ 1. IP Whitelist   │ Check application-level IP restrictions
+  │    Validation     │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 2. Geo-Location   │ Validate request origin geography
+  │    Check          │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 3. Device         │ Verify device fingerprint
+  │    Fingerprint    │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 4. ACL Check      │ Validate service/API access permission
+  │                   │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 5. OAuth Check    │ Validate token (OAuth2 or JWT)
+  │                   │ FAIL → 401 Unauthorized
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 6. URAC Profile   │ Load user profile and groups
+  │    Resolution     │ Resolve user-specific ACL
+  └─────────┬─────────┘
+            │
+            ▼
+     Continue to Service
+```
+
+## Security Checks Detail
+
+### 1. IP Whitelist Validation
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates that the request IP is allowed to access the application.
+
+- Configured per external key in the key's `geo` field
+- Supports CIDR notation for IP ranges
+- Also supports gateway-level whitelist via custom registry
+
+### 2. Geo-Location Check
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates request origin based on geographic location.
+
+- Configured in external key's `geo` field
+- Supports country-level restrictions
+
+### 3. Device Fingerprint
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates device fingerprint for mobile/app authentication.
+
+- Configured in external key's `device` field
+- Useful for mobile app authentication
+
+### 4. ACL Check
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates that the tenant has access to the requested service/API.
+
+ACL Resolution Priority:
+1. User-specific ACL (from URAC profile)
+2. Application ACL (from tenant application)
+3. Package ACL (from product package)
+
+### 5. OAuth Check
+
+**Middleware:** `mw/oauth/index.js`
+
+Validates OAuth2 tokens or JWT.
+
+- Supports OAuth2 password grant
+- Supports JWT validation
+- Configurable per service
+
+### 6. URAC Profile Resolution
+
+**Middleware:** `mw/mt/urac.js`
+
+Loads user profile from URAC for authenticated requests.
+
+- Resolves user groups
+- Applies user-specific ACL overrides
+- Handles network package override for user packages
+
+## IP Whitelist Configuration
+
+### Gateway-Level Whitelist
+
+```javascript
+// In custom registry: gateway.value.mt.whitelist
+{
+  "mt": {
+    "whitelist": {
+      "ips": ["10.0.0.0/8", "192.168.1.0/24"],
+      "acl": true,     // Skip ACL checks for whitelisted IPs
+      "oauth": true    // Skip OAuth checks for whitelisted IPs
+    }
+  }
+}
+```
+
+### Key-Level Restrictions
+
+```javascript
+// In external key definition
+{
+  "extKey": "...",
+  "env": "DEV",
+  "geo": {
+    "ips": ["192.168.1.0/24"],
+    "countries": ["US", "CA"]
+  },
+  "device": {
+    "allow": ["iOS", "Android"]
+  }
+}
+```
+
+## ACL Structure
+
+```javascript
+{
+  "serviceName": {
+    "version": {
+      "access": true,                        // or false, or ["group1", "group2"]
+      "apisPermission": "restricted",        // "restricted" = whitelist mode
+      "get": {
+        "apis": {
+          "/api/path": {
+            "access": ["owner", "admin"]     // Groups allowed
+          }
+        }
+      },
+      "post": { ... },
+      "put": { ... },
+      "delete": { ... }
+    }
+  }
+}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 150 | ACL validation failed - no access to service |
+| 151 | ACL validation failed - no access to API |
+| 152 | ACL validation failed - version mismatch |
+| 153 | Geo-location validation failed |
+| 154 | Device validation failed |
+| 155 | IP whitelist validation failed |
+| 401 | OAuth token invalid or expired |
+| 403 | Access forbidden |