node-red-contrib-aws-sqs-variable 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# node-red-contrib-aws-sqs-variable
+
+A production-ready Node-RED node for AWS SQS operations that sends and receives messages with flexible credential handling.
+
+## Features
+
+- 📬 Send messages to AWS SQS
+- 📥 Receive messages from AWS SQS
+- 🏗️ Flexible credential configuration (IAM roles, direct credentials, context variables)
+- 🎯 TypedInput support for dynamic Queue URL and payload
+- 🔄 FIFO support with Message Group and Deduplication IDs
+- 🧾 Optional JSON parsing for received messages
+- ⏱️ Built-in polling mode with status indicator
+- 🛡️ Production-ready with comprehensive error handling
+
+## Installation
+
+Run the following command in your Node-RED user directory (typically `~/.node-red`):
+
+```bash
+npm install node-red-contrib-aws-sqs-variable
+```
+
+After installation, restart Node-RED to load the new nodes.
+
+## Configuration
+
+### AWS Configuration Node
+
+The module uses a configuration node that supports multiple authentication methods:
+
+#### IAM Role Authentication (Recommended)
+- ✅ Use when running on EC2 instances with IAM roles
+- ✅ No credentials needed in Node-RED
+- ✅ Automatic credential rotation
+
+#### Access Key Authentication
+Supports multiple credential sources:
+
+- **String**: Stored securely in Node-RED credentials (encrypted)
+- **Flow Context**: Retrieved from flow context variables
+- **Global Context**: Retrieved from global context variables  
+- **Environment Variables**: Retrieved from environment variables
+
+## Usage
+
+### Basic Usage
+
+1. **Create AWS Configuration**
+   - Add an "aws-sqs-config" node
+   - Configure your AWS region and credentials
+
+2. **Add AWS SQS Node**
+   - Drag "aws-sqs" node to your flow
+   - Select your AWS configuration
+   - Choose operation: Send or Receive
+
+### Send Messages
+
+Configure:
+- **Queue URL** (string, msg, flow, global, env)
+- **Message Body** (string, msg, flow, global, env)
+
+Optional for FIFO:
+- **Message Group ID** (required for FIFO)
+- **Deduplication ID** (optional if content-based deduplication is enabled)
+
+### Receive Messages
+
+Configure:
+- **Queue URL**
+- **Max Messages** (1-10)
+- **Wait Time (s)** (0-20, long polling)
+- **Visibility Timeout (s)**
+- **Delete After Receive**
+- **Parse JSON Body** (optional)
+
+Polling:
+- Enable **Polling** to receive messages on a schedule
+- Set **Poll Interval (s)**
+
+## Input
+
+### Message Properties
+
+- `msg.queueUrl` (optional): Queue URL if not configured in node
+- `msg.messageGroupId` (optional): FIFO Message Group ID
+- `msg.messageDeduplicationId` (optional): FIFO Deduplication ID
+
+### Example Input
+
+```javascript
+msg = {
+  queueUrl: "https://sqs.eu-central-1.amazonaws.com/123456789012/my-queue",
+  payload: { message: "Hello!" }
+}
+```
+
+## Output
+
+### Send Success Response
+
+```javascript
+msg = {
+  payload: {
+    messageId: "abcd-1234",
+    md5OfMessageBody: "e99a18c428cb38d5f260853678922e03"
+  }
+}
+```
+
+### Receive Success Response
+
+```javascript
+msg = {
+  payload: [
+    {
+      MessageId: "...",
+      ReceiptHandle: "...",
+      Body: "raw string or parsed JSON when enabled"
+    }
+  ]
+}
+```
+
+### Error Response
+
+```javascript
+msg = {
+  payload: {
+    error: "Error message"
+  }
+}
+```
+
+## FIFO Notes
+
+- **Message Group ID** is required for FIFO queues
+- **Deduplication ID** must be unique within a 5-minute window
+- Ordering is guaranteed only within the same Message Group
+
+## Security Best Practices
+
+- ✅ Use IAM roles when possible (recommended for EC2 instances)
+- ✅ Store credentials in context variables rather than hardcoding
+- ✅ Use environment variables for sensitive configuration
+- ✅ Rotate access keys regularly
+- ✅ Follow the principle of least privilege
+- ✅ Enable AWS CloudTrail for audit logging
+
+## Error Handling
+
+The node provides comprehensive error handling:
+
+- **Configuration errors**: Missing or invalid AWS configuration
+- **Authentication errors**: Invalid credentials or permissions
+- **Queue errors**: Invalid Queue URL or insufficient permissions
+- **Network errors**: Connection issues with AWS
+
+All errors are logged and sent in the message payload for downstream processing.
+
+## Requirements
+
+- Node.js >= 12.0.0
+- Node-RED >= 2.0.0
+- AWS account with SQS access
+- Appropriate IAM permissions
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+If you encounter any issues or have questions, please open an issue in the project repository.

package/aws-sqs-config.html

@@ -0,0 +1,366 @@
+<script type="text/javascript">
+    RED.nodes.registerType('aws-sqs-config', {
+        category: 'config',
+        defaults: {
+            name: { value: "" },
+            region: { value: "eu-central-1", required: true },
+            regionType: { value: "str" },
+            regionContext: { value: "" },
+            useIAMRole: { value: false, required: true },
+            deferMissingConfig: { value: true },
+            accessKeyId: { value: "" },
+            accessKeyIdType: { value: "str" },
+            accessKeyIdContext: { value: "" },
+            secretAccessKey: { value: "" },
+            secretAccessKeyType: { value: "str" },
+            secretAccessKeyContext: { value: "" }
+        },
+        credentials: {
+            accessKeyId: { type: "text" },
+            secretAccessKey: { type: "password" }
+        },
+        label: function() {
+            return this.name || "AWS SQS Config (" + this.region + ")";
+        },
+        icon: "font-awesome/fa-key",
+        color: "#b2e2b2",
+        oneditprepare: function() {
+            // Set initial IAM role checkbox state
+            var useIAMRole = this.useIAMRole === true || this.useIAMRole === "true" || this.useIAMRole === 1;
+            $("#node-config-input-useIAMRole").prop('checked', useIAMRole);
+            $("#node-config-input-deferMissingConfig").prop('checked', this.deferMissingConfig === true || this.deferMissingConfig === "true");
+
+            // Initialize tooltips
+            $('.node-config-input').tooltip({
+                delay: { show: 500, hide: 100 },
+                trigger: 'hover'
+            });
+
+            // Use only flow, global, str, env for typedInput
+            var stdTypes = ['str', 'flow', 'global', 'env'];
+
+            // Initialize typedInput for Region
+            $("#node-config-input-region-typed").typedInput({
+                default: 'str',
+                types: stdTypes,
+                typeField: "#node-config-input-regionType"
+            });
+            $("#node-config-input-region-typed").typedInput('type', this.regionType || 'str');
+
+            if (this.regionType === 'str') {
+                $("#node-config-input-region-typed").typedInput('value', this.region || 'eu-central-1');
+            } else {
+                $("#node-config-input-region-typed").typedInput('value', this.regionContext || '');
+            }
+            
+            // Initialize typedInput for Access Key ID
+            $("#node-config-input-accessKeyId-typed").typedInput({
+                default: 'str',
+                types: stdTypes,
+                typeField: "#node-config-input-accessKeyIdType"
+            });
+            $("#node-config-input-accessKeyId-typed").typedInput('type', this.accessKeyIdType || 'str');
+            
+            // Set value based on type for Access Key ID
+            if (this.accessKeyIdType === 'str') {
+                // For string type, use credentials if available
+                var credValue = this.credentials && this.credentials.accessKeyId ? this.credentials.accessKeyId : '';
+                $("#node-config-input-accessKeyId-typed").typedInput('value', credValue);
+            } else {
+                // For context types, use the stored context value
+                $("#node-config-input-accessKeyId-typed").typedInput('value', this.accessKeyIdContext || '');
+            }
+
+            // Secret Access Key type selection
+            if (this.secretAccessKeyType && this.secretAccessKeyType !== 'str') {
+                // Context type
+                $("#node-config-input-secretAccessKey-type").val(this.secretAccessKeyType);
+                $("#node-config-input-secretAccessKey-context").val(this.secretAccessKeyContext || '');
+            } else {
+                // String type
+                $("#node-config-input-secretAccessKey-type").val('str');
+            }
+
+            // Secret Access Key field visibility logic
+            var updateSecretAccessKeyFieldVisibility = function() {
+                var secretAccessKeyType = $("#node-config-input-secretAccessKey-type").val();
+                
+                if (secretAccessKeyType === 'str') {
+                    $("#secretAccessKey-str-row").show();
+                    $("#secretAccessKey-context-row").hide();
+                } else {
+                    $("#secretAccessKey-str-row").hide();
+                    $("#secretAccessKey-context-row").show();
+                }
+            };
+
+            $("#node-config-input-secretAccessKey-type").on("change", updateSecretAccessKeyFieldVisibility);
+            
+            // Call immediately to set initial state
+            updateSecretAccessKeyFieldVisibility();
+
+            // Also call after a short delay to ensure DOM is ready
+            setTimeout(updateSecretAccessKeyFieldVisibility, 100);
+
+            // Sync visible password field with hidden credentials field
+            $("#node-config-input-secretAccessKey-visible").on("input", function() {
+                $("#node-config-input-secretAccessKey").val($(this).val());
+            });
+
+            // Handle placeholder behavior for Secret Access Key
+            $("#node-config-input-secretAccessKey-visible").on("focus", function() {
+                if ($(this).attr('placeholder') === '••••••••••••••••••••••••••••••••••••••••') {
+                    $(this).attr('placeholder', 'Enter new secret key or leave empty to keep existing');
+                }
+            });
+
+            $("#node-config-input-secretAccessKey-visible").on("blur", function() {
+                var inputVal = $(this).val();
+                if (!inputVal && this.credentials && this.credentials.has_secretAccessKey) {
+                    $(this).attr('placeholder', '••••••••••••••••••••••••••••••••••••••••');
+                }
+            }.bind(this));
+
+            // Load existing secret access key if available
+            if (this.credentials && this.credentials.secretAccessKey) {
+                $("#node-config-input-secretAccessKey-visible").val(this.credentials.secretAccessKey);
+                $("#node-config-input-secretAccessKey").val(this.credentials.secretAccessKey);
+            } else if (this.credentials && this.credentials.has_secretAccessKey) {
+                // Secret key exists but not shown for security - show placeholder
+                $("#node-config-input-secretAccessKey-visible").attr('placeholder', '••••••••••••••••••••••••••••••••••••••••');
+                $("#node-config-input-secretAccessKey-visible").val('');
+            } else {
+                // No secret key - set default placeholder
+                $("#node-config-input-secretAccessKey-visible").attr('placeholder', 'Enter secret access key');
+                $("#node-config-input-secretAccessKey-visible").val('');
+            }
+
+            // Handle IAM role toggle
+            $('#node-config-input-useIAMRole').change(function() {
+                var isIAMRole = $(this).is(':checked');
+                
+                if (isIAMRole) {
+                    $('.credentials-row').hide();
+                } else {
+                    $('.credentials-row').show();
+                    // Re-apply field visibility logic
+                    updateSecretAccessKeyFieldVisibility();
+                }
+            });
+
+            // Set initial visibility
+            if (useIAMRole) {
+                $('.credentials-row').hide();
+            } else {
+                // Ensure proper field visibility
+                setTimeout(function() {
+                    updateSecretAccessKeyFieldVisibility();
+                }, 200);
+            }
+        },
+        oneditsave: function() {
+            // Save basic configuration
+            this.name = $("#node-config-input-name").val();
+            // Handle Region
+            var regionType = $("#node-config-input-regionType").val();
+            var regionValue = $("#node-config-input-region-typed").typedInput('value');
+            this.regionType = regionType;
+            if (regionType === 'str') {
+                this.region = regionValue || '';
+                this.regionContext = '';
+                $("#node-config-input-region-context").val('');
+                $("#node-config-input-region").val(regionValue || '');
+            } else {
+                this.region = '';
+                this.regionContext = regionValue || '';
+                $("#node-config-input-region").val('');
+                $("#node-config-input-region-context").val(regionValue || '');
+            }
+            this.useIAMRole = $("#node-config-input-useIAMRole").is(':checked');
+            this.deferMissingConfig = $("#node-config-input-deferMissingConfig").is(':checked');
+
+            // Handle Access Key ID (TypedInput logic)
+            var accessKeyIdType = $("#node-config-input-accessKeyIdType").val();
+            var accessKeyIdValue = $("#node-config-input-accessKeyId-typed").typedInput('value');
+            
+            // Explicitly set the type first
+            this.accessKeyIdType = accessKeyIdType;
+            
+            if (accessKeyIdType === 'str') {
+                // String type - save to credentials, clear from defaults
+                this.accessKeyId = '';
+                this.accessKeyIdContext = '';
+                $("#node-config-input-accessKeyId-context").val('');
+                // Set the credential field
+                $("#node-config-input-accessKeyId").val(accessKeyIdValue || '');
+            } else {
+                // Context type - save to context field, clear credentials
+                this.accessKeyId = '';
+                this.accessKeyIdContext = accessKeyIdValue || '';
+                $("#node-config-input-accessKeyId").val('');
+                $("#node-config-input-accessKeyId-context").val(accessKeyIdValue || '');
+            }
+
+            // Handle Secret Access Key based on type
+            var secretAccessKeyType = $("#node-config-input-secretAccessKey-type").val();
+            this.secretAccessKeyType = secretAccessKeyType;
+            
+            if (secretAccessKeyType === 'str') {
+                // String secret key - save to credentials, clear context
+                this.secretAccessKeyContext = '';
+                this.secretAccessKey = '';  // Clear from defaults
+                $("#node-config-input-secretAccessKeyContext").val('');
+                // Sync visible field to hidden credentials field only if not empty
+                var visibleSecretAccessKey = $("#node-config-input-secretAccessKey-visible").val();
+                if (visibleSecretAccessKey) {
+                    $("#node-config-input-secretAccessKey").val(visibleSecretAccessKey);
+                }
+                // If empty, keep existing secret key (don't overwrite)
+            } else {
+                // Context secret key - save context reference
+                var secretAccessKeyValue = $("#node-config-input-secretAccessKey-context").val();
+                this.secretAccessKeyContext = secretAccessKeyValue || '';
+                this.secretAccessKey = '';  // Clear from defaults
+                $("#node-config-input-secretAccessKeyContext").val(secretAccessKeyValue || '');
+            }
+        }
+    });
+</script>
+
+<script type="text/x-red" data-template-name="aws-sqs-config">
+    <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="Configuration Name" style="width: 70%;">
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-region-typed">
+            <i class="fa fa-globe"></i> Region
+        </label>
+        <input type="text" id="node-config-input-region-typed" style="width: 70%;" placeholder="eu-central-1">
+        <input type="hidden" id="node-config-input-regionType">
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-useIAMRole">
+            <i class="fa fa-user"></i> Use IAM Role
+        </label>
+        <input type="checkbox" id="node-config-input-useIAMRole" style="display: inline-block; width: auto; vertical-align: middle;">
+        <span style="margin-left: 5px; vertical-align: middle;">Use IAM role for authentication<br><small>(recommended for EC2 instances)</small></span>
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-deferMissingConfig">
+            <i class="fa fa-clock-o"></i> Defer Missing Config
+        </label>
+        <input type="checkbox" id="node-config-input-deferMissingConfig" style="display: inline-block; width: auto; vertical-align: middle;">
+        <span style="margin-left: 5px; vertical-align: middle;">Wait for credentials/region without throwing errors</span>
+    </div>
+    <div class="form-row credentials-row">
+        <label for="node-config-input-accessKeyId-typed">
+            <i class="fa fa-key"></i> Access Key ID
+        </label>
+        <input type="text" id="node-config-input-accessKeyId-typed" style="width: 70%;">
+        <input type="hidden" id="node-config-input-accessKeyIdType">
+    </div>
+    <div class="form-row credentials-row">
+        <label for="node-config-input-secretAccessKey-type">
+            <i class="fa fa-key"></i> Secret Access Key Type
+        </label>
+        <select id="node-config-input-secretAccessKey-type" style="width: 70%;">
+            <option value="str">Direct Secret Key (secure)</option>
+            <option value="flow">Flow Context</option>
+            <option value="global">Global Context</option>
+            <option value="env">Environment Variable</option>
+        </select>
+    </div>
+    <div class="form-row credentials-row" id="secretAccessKey-str-row">
+        <label for="node-config-input-secretAccessKey-visible">
+            <i class="fa fa-key"></i> Secret Access Key
+        </label>
+        <input type="password" id="node-config-input-secretAccessKey-visible" style="width: 70%;">
+    </div>
+    <div class="form-row credentials-row" id="secretAccessKey-context-row" style="display: none;">
+        <label for="node-config-input-secretAccessKey-context">
+            <i class="fa fa-code"></i> Variable Name
+        </label>
+        <input type="text" id="node-config-input-secretAccessKey-context" style="width: 70%;">
+    </div>
+    <!-- Hidden fields for Node-RED credentials system -->
+    <input type="text" id="node-config-input-accessKeyId" style="display: none;">
+    <input type="password" id="node-config-input-secretAccessKey" style="display: none;">
+    <!-- Hidden field for region -->
+    <input type="text" id="node-config-input-region" style="display: none;">
+    <!-- Hidden field for region context value -->
+    <input type="text" id="node-config-input-region-context" style="display: none;">
+    <!-- Hidden field for accessKeyId context value -->
+    <input type="text" id="node-config-input-accessKeyId-context" style="display: none;">
+    <!-- Hidden field for secretAccessKeyContext -->
+    <input type="text" id="node-config-input-secretAccessKeyContext" style="display: none;">
+</script>
+
+<script type="text/x-red" data-help-name="aws-sqs-config">
+    <p>AWS SQS configuration node with flexible context support:</p>
+    
+    <h3>Authentication Methods</h3>
+    <ul>
+        <li><b>IAM Role</b>: Use IAM role for authentication (recommended for EC2 instances)</li>
+        <li><b>Access Keys</b>: Use AWS access key and secret key</li>
+    </ul>
+    
+    <h3>Credential Sources</h3>
+    <p>When not using IAM role, credentials support multiple input types:</p>
+    <ul>
+        <li><b>String</b>: Stored securely in Node-RED credentials (encrypted)</li>
+        <li><b>Flow Context</b>: Retrieved from flow context variables</li>
+        <li><b>Global Context</b>: Retrieved from global context variables</li>
+        <li><b>Environment Variable</b>: Retrieved from environment variables</li>
+    </ul>
+    
+    <h3>Security Notes</h3>
+    <ul>
+        <li>String credentials are stored encrypted in Node-RED's credentials store</li>
+        <li>Context types only store variable names, actual credentials retrieved at runtime</li>
+        <li>Use IAM roles when possible for better security</li>
+        <li>Rotate access keys regularly</li>
+        <li>Follow the principle of least privilege</li>
+    </ul>
+</script>
+
+<style>
+    .form-row {
+        margin-bottom: 10px;
+    }
+    .form-row label {
+        display: inline-block;
+        width: 120px;
+        vertical-align: top;
+        margin-top: 6px;
+    }
+    .form-row input[type="text"],
+    .form-row input[type="password"],
+    .form-row select {
+        width: 70%;
+    }
+    .form-row input[type="checkbox"] {
+        width: auto;
+        margin: 0;
+        vertical-align: middle;
+    }
+    .credentials-row {
+        margin-top: 10px;
+    }
+    .help-text {
+        font-size: 0.8em;
+        color: #666;
+        margin-top: 4px;
+        margin-left: 125px;
+    }
+    .error-text {
+        color: #d00;
+        font-size: 0.8em;
+        margin-top: 4px;
+    }
+    .input-error {
+        border-color: #d00 !important;
+    }
+</style>