@inteli.city/node-red-contrib-http-plus 1.0.0

package/README.md

@@ -0,0 +1,516 @@
+# @inteli.city/node-red-contrib-http+
+
+Enhanced HTTP nodes for Node-RED with built-in authentication and request validation.
+
+---
+
+## What is this?
+
+`@inteli.city/node-red-contrib-http+` provides enhanced versions of Node-RED's HTTP nodes with built-in authentication, validation, and improved request handling.
+
+These nodes are designed to be compatible with the standard Node-RED HTTP flow while adding capabilities commonly implemented manually in flows.
+
+---
+
+## Key differences from standard HTTP nodes
+
+| Feature | Standard nodes | http+ nodes |
+|---------|----------------|-------------|
+| Authentication | Not built-in | Built-in (Basic + Cognito) |
+| Request validation | Manual (function nodes) | Built-in (Zod) |
+| File upload handling | Basic | Structured (`msg.files`) |
+| Data normalization | Manual | Built-in via Zod transforms |
+| Streaming responses | Limited/manual | First-class support |
+
+---
+
+## Compatibility
+
+- `http.in+` and `http.out+` follow the same flow model as the standard nodes
+- `http.request+` is a drop-in replacement for the standard `http request` node
+- Existing flows can be migrated incrementally
+
+```
+Standard:  http in ──→ function ──→ http response
+With http+: http.in+ ──→ (validated + authenticated) ──→ http.out+
+```
+
+---
+
+## When to use http+ nodes
+
+Use http+ when you need:
+
+- Authentication at the HTTP boundary
+- Input validation without extra function nodes
+- Cleaner and more predictable request handling
+
+Use standard nodes when:
+
+- You need minimal setup
+- You are prototyping quickly without constraints
+
+---
+
+## Index
+
+- [Nodes](#nodes)
+- [Install](#install)
+- [Core Concepts](#core-concepts)
+- [Authentication](#authentication)
+- [Validation with Zod](#validation-with-zod)
+- [Swagger / OpenAPI](#swagger--openapi)
+- [File uploads](#file-uploads)
+- [http.request+](#httprequest)
+- [http.out+](#httpout)
+- [Best practices](#best-practices)
+
+---
+
+## Nodes
+
+| Node | Role |
+|------|------|
+| `http.in+` | Receives HTTP requests. Runs auth and Zod validation before sending `msg` downstream. |
+| `http.request+` | Makes outgoing HTTP requests. Drop-in replacement for the standard `http request` node. |
+| `http.out+` | Sends the HTTP response back to the caller. Works identically to the standard `http response` node. |
+
+## Install
+
+```bash
+cd ~/.node-red
+npm install @inteli.city/node-red-contrib-http+
+```
+
+---
+
+## Core Concepts
+
+### Message properties
+
+| Property | Contains |
+|----------|----------|
+| `msg.payload` | Request body (POST/PUT/PATCH) or query object (GET) |
+| `msg.req.query` | Query string as object — `GET /search?term=abc` → `{ term: "abc" }` |
+| `msg.req.params` | Route parameters — `GET /users/42` → `{ id: "42" }` |
+| `msg.req.headers` | Request headers |
+| `msg.validated` | Parsed + validated object from Zod (only when validation passes) |
+| `msg.user` | Mapped user identity. For Basic Auth: the username string. For Cognito: fields mapped from the JWT payload (only when "Expose user to flow" is enabled). |
+| `msg.res` | Response handle — passed to `http.out+` to send the reply |
+
+### Basic flow
+
+```
+http.in+ ──→ [your logic] ──→ http.out+
+```
+
+```
+inject ──→ http.request+ ──→ debug
+```
+
+---
+
+## Authentication
+
+Configure authentication by creating an **`http.auth.config+`** config node and attaching it to `http.in+`.
+
+| Type | Behaviour |
+|------|-----------|
+| None | All requests pass through |
+| Basic Auth | Validates `Authorization: Basic …` header. Browser login popup triggered automatically via `WWW-Authenticate`. Supports single-user and multi-user modes (see below). |
+| Cognito JWT | Validates a Bearer token against a JWKS endpoint. Token accepted from `Authorization: Bearer <token>` or `?token=`. JWKS keys are cached for 1 hour. |
+
+Failed authentication returns **401** and stops the flow.
+
+### Basic Auth modes
+
+**Single-user (default):** Enter a username and password directly in the config node. Credentials are stored securely via Node-RED's credentials system (not in the exported flow).
+
+**Multiple users (JSON):** Enable the "Use multiple users" option and provide a JSON object mapping usernames to passwords:
+
+```json
+{
+  "admin": "password123",
+  "user": "abc123"
+}
+```
+
+> **Warning:** Passwords in JSON mode are stored in plain text in the flow configuration. Use only in trusted environments.
+
+### JWKS caching
+
+Cognito public keys (JWKS) are cached in memory to reduce latency and avoid repeated requests to AWS.
+
+- Cache duration: **1 hour**
+- Keys are cached per `kid` (key ID)
+- A new key is fetched automatically if an unknown `kid` is received
+
+This improves performance while still supporting key rotation. If AWS rotates signing keys, new keys will be picked up automatically after cache expiration or when a new `kid` appears.
+
+### Cognito user mapping
+
+After successful JWT validation, the `Authorization` header and `?token=` query parameter are always removed from the request before it enters the flow.
+
+To expose user identity in `msg.user`, enable **"Expose user to flow"** in the config node and provide a JSON mapping:
+
+```json
+{
+  "id": "sub",
+  "email": "email",
+  "roles": "cognito:groups"
+}
+```
+
+Keys are the output field names in `msg.user`; values are the JWT claim names to read from. Fields missing from the token are set to `undefined`.
+
+If **"Expose user to flow"** is disabled, `msg.user` is not set — no JWT data propagates into the flow.
+
+### Request sanitization
+
+After successful authentication, credentials are removed from the request before dispatch:
+
+| Auth type | Removed |
+|-----------|---------|
+| Basic Auth | `msg.req.headers.authorization` |
+| Cognito JWT | `msg.req.headers.authorization`, `msg.req.query.token` |
+
+This prevents tokens and passwords from leaking into downstream nodes.
+
+---
+
+## Validation with Zod
+
+`http.in+` can validate every incoming request before passing it downstream.
+
+### Enabling validation
+
+1. Open the `http.in+` node editor.
+2. Check **Enable Zod validation**.
+3. Enter a Zod schema expression in the **Schema** textarea.
+
+The schema receives a single object:
+
+```js
+{
+  body:   // request body (msg.payload)
+  query:  // query string parameters (msg.req.query)
+  params: // route parameters (msg.req.params)
+  files:  // uploaded file metadata (when file upload is enabled)
+}
+```
+
+Use the appropriate field depending on the HTTP method:
+
+| Method | Use |
+|--------|-----|
+| GET, DELETE | `query`, `params` only — no body |
+| POST, PUT, PATCH | `body`, `query`, `params` |
+
+> Defining `body` in a GET or DELETE schema is ignored at runtime. A warning is logged at deploy time.
+
+> Full usage guidance (method table, type coercion, Swagger behavior) is available inline in the node editor UI.
+
+If validation **passes**, `msg.validated` contains the parsed result and the flow continues normally.
+
+If validation **fails**, the node returns HTTP **400** immediately — no downstream node is executed:
+
+```json
+{
+  "error": "invalid_request",
+  "details": [
+    { "code": "invalid_type", "path": ["body", "age"], "message": "Expected number, received string" }
+  ]
+}
+```
+
+### Important: query and param values are always strings
+
+HTTP query strings and route params arrive as strings. Use `z.coerce` to convert them:
+
+```js
+z.coerce.number()   // "42" → 42
+z.coerce.boolean()  // "true" → true
+```
+
+### Transforms and normalization
+
+Zod can transform values as part of validation — trimming whitespace, converting case, coercing types, etc. The transformed result is what ends up in `msg.validated`. `msg.payload` always remains the original, unmodified request body.
+
+```js
+z.object({
+  query: z.object({
+    term: z.string().trim().toLowerCase(),
+    page: z.coerce.number().int().min(1)
+  })
+})
+```
+
+The flow receives `msg.validated.query.term` already trimmed and lowercased — no manual cleanup needed.
+
+### File validation
+
+Zod validates file **metadata** (mime type, size, etc.), not file content. Files from the upload are available in `msg.files` as an array — validate the first entry or a named field:
+
+```js
+z.object({
+  files: z.object({
+    avatar: z.object({
+      mimetype: z.enum(["image/png", "image/jpeg"]),
+      size: z.number().max(2_000_000)
+    })
+  })
+})
+```
+
+---
+
+## Examples
+
+### Example 1 — Body validation (POST)
+
+**Route:** `POST /users`
+
+**Schema:**
+```js
+z.object({
+  body: z.object({
+    name: z.string().min(1),
+    age:  z.number().int().min(0)
+  })
+})
+```
+
+**Valid request body:**
+```json
+{ "name": "Alice", "age": 30 }
+```
+
+**Invalid — returns 400:**
+```json
+{ "name": "", "age": -1 }
+```
+
+---
+
+### Example 2 — Query validation (GET)
+
+**Route:** `GET /search?term=node-red&page=2`
+
+**Schema:**
+```js
+z.object({
+  query: z.object({
+    term: z.string().min(1),
+    page: z.coerce.number().int().min(1).optional()
+  })
+})
+```
+
+`page` arrives as a string from the URL — `z.coerce.number()` converts it automatically.
+
+---
+
+### Example 3 — Route parameter validation
+
+**Route:** `GET /users/:id`
+
+**Schema:**
+```js
+z.object({
+  params: z.object({
+    id: z.string().uuid()
+  })
+})
+```
+
+Rejects any request where `:id` is not a valid UUID before your logic runs.
+
+---
+
+### Example 4 — Combined: params + query + body
+
+**Route:** `PATCH /users/:id?notify=true`
+
+**Schema:**
+```js
+z.object({
+  params: z.object({
+    id: z.string().uuid()
+  }),
+  query: z.object({
+    notify: z.coerce.boolean().optional()
+  }).optional(),
+  body: z.object({
+    email: z.string().email().optional(),
+    role:  z.enum(["admin", "user", "viewer"]).optional()
+  })
+})
+```
+
+`msg.validated` will contain the fully parsed and typed object for use downstream.
+
+---
+
+## Validation error format
+
+```json
+{
+  "error": "invalid_request",
+  "details": [
+    {
+      "code":    "invalid_type",
+      "path":    ["body", "age"],
+      "message": "Expected number, received string"
+    },
+    {
+      "code":    "too_small",
+      "path":    ["body", "name"],
+      "message": "String must contain at least 1 character(s)"
+    }
+  ]
+}
+```
+
+`details` is the raw Zod `ZodError.errors` array. Each entry contains a `path` array indicating exactly which field failed.
+
+---
+
+## Best practices
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Required identifiers | Use route params (`:id`) with `z.string().uuid()` or similar |
+| Filters and options | Use query string with `z.coerce` for number/boolean |
+| Structured input data | Use request body (`body`) — POST/PUT/PATCH only |
+| GET / DELETE filtering | Use `query` — never `body` |
+| All query/param values | Always use `z.coerce.*` — they arrive as strings |
+| Optional sections | Wrap entire `query` or `params` in `.optional()` if the route doesn't always have them |
+| Schema errors at deploy | The node logs the error and disables validation — it does **not** crash |
+| Swagger visibility | Only nodes with a valid Zod schema appear in `/docs` |
+
+---
+
+## Swagger / OpenAPI
+
+`http.in+` nodes with a valid Zod schema are automatically registered in an OpenAPI 3.0 spec. No extra configuration is required.
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET /openapi.json` | Raw OpenAPI spec (JSON) |
+| `GET /docs` | Swagger UI |
+
+Only endpoints where Zod validation is enabled **and** the schema compiled successfully appear in the spec. The spec updates automatically on each deploy — no stale entries.
+
+For schema field usage, method rules, and type coercion guidance, see the inline help panel in the node editor.
+
+---
+
+## File uploads
+
+`http.in+` supports multipart (`multipart/form-data`) file uploads on **POST** routes. The upload option is not available for GET, PUT, PATCH, or DELETE.
+
+If file upload is enabled, uploaded files are available in `msg.files` — they are **not** included in `msg.payload`.
+
+### Enabling uploads
+
+1. Open the `http.in+` node editor.
+2. Check **Enable file uploads**.
+3. Choose **Storage**: `Memory (buffer)` or `Disk (temp files)`.
+4. Set **Max size (MB)** (default: 5 MB).
+5. For disk storage, optionally set a **Temp dir** (defaults to the OS temp directory).
+
+### `msg.files`
+
+When files are uploaded, `msg.files` is an array of objects:
+
+| Property | Present | Contains |
+|----------|---------|----------|
+| `fieldname` | always | Form field name used for the upload |
+| `originalname` | always | Original filename from the client |
+| `mimetype` | always | MIME type (e.g. `image/png`) |
+| `size` | always | File size in bytes |
+| `storage` | always | `"memory"` or `"disk"` |
+| `buffer` | memory only | `Buffer` containing the file data |
+| `path` | disk only | Absolute path to the saved file |
+
+### Size limit
+
+If a file exceeds the configured limit, the node returns **413** immediately:
+
+```json
+{ "error": "file_too_large" }
+```
+
+### Disk storage — cleanup
+
+When using disk storage, files are written to the temp directory and **not deleted automatically**. Your flow is responsible for removing them after use (e.g. via a function node calling `fs.unlink`).
+
+---
+
+## http.request+
+
+Drop-in replacement for the standard `http request` node with identical behaviour.
+
+**Input message properties used:**
+
+| Property | Effect |
+|----------|--------|
+| `msg.url` | Target URL (overrides node config) |
+| `msg.method` | HTTP method (when node is set to "use msg.method") |
+| `msg.payload` | Request body |
+| `msg.headers` | Additional request headers |
+
+**Output message properties set:**
+
+| Property | Contains |
+|----------|----------|
+| `msg.payload` | Response body |
+| `msg.statusCode` | HTTP status code |
+| `msg.headers` | Response headers |
+| `msg.responseUrl` | Final URL after redirects |
+| `msg.redirectList` | List of redirects followed |
+
+Supports TLS config, proxy config (`http.proxy+`), Basic/Digest/Bearer auth, and persistent connections.
+
+---
+
+## http.out+
+
+Sends the HTTP response back to the original caller. Must be connected to the same flow started by `http.in+`.
+
+**Controlling the response via `msg`:**
+
+| Property | Effect |
+|----------|--------|
+| `msg.payload` | Response body |
+| `msg.statusCode` | HTTP status code (default: 200) |
+| `msg.headers` | Extra response headers |
+| `msg.cookies` | Cookies to set or clear |
+
+If `msg.payload` is an object, the response is sent as JSON automatically.
+
+### Streaming responses
+
+You can stream a response instead of sending a buffer. Useful for large files or when proxying a stream from another source.
+
+Set `msg.stream` to any readable Node.js stream:
+
+```js
+msg.stream = fs.createReadStream("/tmp/file.zip");
+```
+
+If `msg.stream` is set, the stream is piped directly to the response. If it is not set, `msg.payload` is sent normally.
+
+`msg.headers` and `msg.statusCode` behave the same in both modes.
+
+---
+
+## File structure
+
+```
+httpproxy+.js/.html         — http.proxy+ config node (proxy for http.request+); includes proxy resolution utility
+httpin+.js/.html            — http.in+ and http.out+ nodes
+httprequest+.js/.html       — http.request+ node
+http-auth-config+.js/.html  — http.auth.config+ config node
+libs/swagger.js             — OpenAPI spec generation and /docs + /openapi.json route registration
+```

package/http-auth-config+.html

@@ -0,0 +1,167 @@
+<!--
+  Authentication config node for http.in+
+  Supports: none, Basic Auth (simple + multi-user), AWS Cognito JWT (JWKS)
+-->
+
+<style>
+#auth-help-simple code,
+#auth-help-json code,
+.auth-row-cognito.help-text code {
+    font-size: 12px;
+    background: none;
+    padding: 0;
+}
+</style>
+
+<script type="text/html" data-template-name="http.auth.config+">
+    <div style="min-width:580px; height:0; overflow:hidden;"></div>
+    <div class="form-row">
+        <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-config-input-name" placeholder="optional label">
+    </div>
+
+    <div class="form-row">
+        <label for="node-config-input-authType"><i class="fa fa-lock"></i> Auth Type</label>
+        <select id="node-config-input-authType" style="width:70%;">
+            <option value="none">None</option>
+            <option value="basic">Basic Auth</option>
+            <option value="cognito">AWS Cognito JWT</option>
+        </select>
+    </div>
+
+    <!-- Basic Auth -->
+    <div class="form-row auth-row-basic" style="display:none;">
+        <input type="checkbox" id="node-config-input-useJsonUsers" style="display:inline-block; width:auto; vertical-align:top;">
+        <label for="node-config-input-useJsonUsers" style="width:auto;"> Use multiple users (JSON)</label>
+    </div>
+
+    <div class="auth-row-basic" id="auth-help-simple" style="display:none; font-size:12px; color:#666; margin: -4px 0 8px 110px; line-height:1.5;">
+        Credentials are stored securely via Node-RED's credentials system.
+    </div>
+    <div class="auth-row-basic" id="auth-help-json" style="display:none; font-size:12px; color:#666; margin: -4px 0 8px 110px; line-height:1.5;">
+        Passwords are stored in plain text in the flow configuration.<br>
+        <em>Note: use only in trusted environments.</em>
+    </div>
+
+    <div class="form-row auth-row-basic auth-simple-row" style="display:none;">
+        <label for="node-config-input-username"><i class="fa fa-user"></i> Username</label>
+        <input type="text" id="node-config-input-username" autocomplete="off">
+    </div>
+    <div class="form-row auth-row-basic auth-simple-row" style="display:none;">
+        <label for="node-config-input-password"><i class="fa fa-key"></i> Password</label>
+        <input type="password" id="node-config-input-password" autocomplete="off">
+    </div>
+
+    <div class="form-row auth-row-basic auth-json-row" style="display:none;">
+        <label for="node-config-input-usersJson" style="vertical-align:top; margin-top:4px;"><i class="fa fa-users"></i> Users</label>
+        <textarea id="node-config-input-usersJson" rows="5"
+                  style="width:70%; font-family:monospace; font-size:12px; resize:vertical;"
+                  placeholder='{&#10;  "admin": "password123",&#10;  "user1": "abc123"&#10;}'
+                  autocomplete="off"></textarea>
+    </div>
+
+    <!-- Cognito JWT -->
+    <div class="form-row auth-row-cognito" style="display:none;">
+        <label for="node-config-input-jwksUrl"><i class="fa fa-link"></i> JWKS URL</label>
+        <input type="text" id="node-config-input-jwksUrl"
+               placeholder="https://cognito-idp.{region}.amazonaws.com/{pool-id}/.well-known/jwks.json"
+               style="width:70%;">
+    </div>
+    <div class="form-row auth-row-cognito" style="display:none;">
+        <label for="node-config-input-audience"><i class="fa fa-id-badge"></i> Audience</label>
+        <input type="text" id="node-config-input-audience" placeholder="optional" style="width:70%;">
+    </div>
+    <div class="form-row auth-row-cognito" style="display:none;">
+        <label for="node-config-input-issuer"><i class="fa fa-building"></i> Issuer</label>
+        <input type="text" id="node-config-input-issuer" placeholder="optional" style="width:70%;">
+    </div>
+    <div class="auth-row-cognito help-text" style="display:none; font-size:12px; color:#666; margin: 4px 0 8px 110px; line-height:1.5;">
+        <b>JWKS URL</b> — public key endpoint of your Cognito User Pool:<br>
+        <code>https://cognito-idp.{region}.amazonaws.com/{pool-id}/.well-known/jwks.json</code><br>
+        <b>Audience</b> — App Client ID. Tokens issued to a different client are rejected.<br>
+        <b>Issuer</b> — User Pool base URL: <code>https://cognito-idp.{region}.amazonaws.com/{pool-id}</code><br>
+        <em>Note: Audience and Issuer are optional but strongly recommended.</em>
+    </div>
+
+    <div class="form-row auth-row-cognito" style="display:none;">
+        <input type="checkbox" id="node-config-input-exposeUser" style="display:inline-block; width:auto; vertical-align:top;">
+        <label for="node-config-input-exposeUser" style="width:auto;"> Expose user to flow (<code>msg.user</code>)</label>
+    </div>
+    <div class="form-row auth-row-cognito cognito-mapping-row" style="display:none;">
+        <label for="node-config-input-userMapping" style="vertical-align:top; margin-top:4px;"><i class="fa fa-user-o"></i> User mapping</label>
+        <textarea id="node-config-input-userMapping" rows="5"
+                  style="width:70%; font-family:monospace; font-size:12px; resize:vertical;"
+                  placeholder='{"id":"sub","email":"email","roles":"cognito:groups"}'></textarea>
+    </div>
+    <div class="auth-row-cognito cognito-mapping-row" style="display:none; font-size:12px; color:#666; margin: -4px 0 8px 110px; line-height:1.5;">
+        Map JWT payload fields into <code>msg.user</code>. Keys are the output field names, values are JWT claim names. The raw JWT token is never exposed in the flow — only the mapped fields are.<br>
+        <em>Example: <code>{"id":"sub","email":"email","roles":"cognito:groups"}</code></em>
+    </div>
+</script>
+
+<script type="text/javascript">
+(function() {
+    RED.nodes.registerType('http.auth.config+', {
+        category: 'config',
+        color: "#9575CD",
+        defaults: {
+            name:         { value: '' },
+            authType:     { value: 'none' },
+            useJsonUsers: { value: false },
+            usersJson:    { value: '' },
+            jwksUrl:      { value: '' },
+            audience:     { value: '' },
+            issuer:       { value: '' },
+            exposeUser:   { value: false },
+            userMapping:  { value: '{\n  "id": "sub",\n  "email": "email",\n  "roles": "cognito:groups"\n}' }
+        },
+        credentials: {
+            username: { type: 'text' },
+            password: { type: 'password' }
+        },
+        label: function() {
+            var labels = { none: 'None', basic: 'Basic Auth', cognito: 'Cognito JWT' };
+            return this.name || ('Auth: ' + (labels[this.authType] || this.authType));
+        },
+        oneditprepare: function() {
+            function updateSections() {
+                var type = $('#node-config-input-authType').val();
+                $('.auth-row-basic').toggle(type === 'basic');
+                $('.auth-row-cognito').toggle(type === 'cognito');
+                if (type === 'basic') {
+                    updateBasicMode();
+                    $('.cognito-mapping-row').hide();
+                } else if (type === 'cognito') {
+                    $('.auth-simple-row').hide();
+                    $('.auth-json-row').hide();
+                    $('#auth-help-simple').hide();
+                    $('#auth-help-json').hide();
+                    updateCognitoMapping();
+                } else {
+                    $('.auth-simple-row').hide();
+                    $('.auth-json-row').hide();
+                    $('#auth-help-simple').hide();
+                    $('#auth-help-json').hide();
+                    $('.cognito-mapping-row').hide();
+                }
+            }
+            function updateBasicMode() {
+                var isJson = $('#node-config-input-useJsonUsers').is(':checked');
+                $('.auth-simple-row').toggle(!isJson);
+                $('.auth-json-row').toggle(isJson);
+                $('#auth-help-simple').toggle(!isJson);
+                $('#auth-help-json').toggle(isJson);
+            }
+            function updateCognitoMapping() {
+                var expose = $('#node-config-input-exposeUser').is(':checked');
+                $('.cognito-mapping-row').toggle(expose);
+            }
+            $('#node-config-input-authType').on('change', updateSections);
+            $('#node-config-input-useJsonUsers').on('change', updateBasicMode);
+            $('#node-config-input-exposeUser').on('change', updateCognitoMapping);
+            updateSections();
+            setTimeout(updateSections, 0);
+        }
+    });
+})();
+</script>