aeglis-sdk 1.0.0

package/index.js

@@ -0,0 +1,150 @@
+const axios = require('axios');
+const crypto = require('crypto');
+const FormData = require('form-data');
+const fs = require('fs');
+
+class Aeglis {
+    /**
+     * Initialize the Aeglis SDK
+     * @param {string} apiKey - Your B2B API Key from the Aeglis Dashboard
+     */
+    constructor(apiKey) {
+        if (!apiKey || typeof apiKey !== 'string') {
+            throw new Error('Aeglis Initialization Error: A valid API key is required.');
+        }
+
+        this.apiKey = apiKey;
+        this.baseURL = 'https://api.aeglis.com/v3/api';
+        
+        // Base HTTP Client for standard JSON requests
+        this.client = axios.create({
+            baseURL: this.baseURL,
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+
+    /**
+     * 🛡️ QUICK SCAN (Synchronous)
+     * Best for short texts, links, and messages.
+     * @param {string} inputText - The text or URL to scan.
+     * @param {string} [endUserId='anonymous'] - Optional tracking ID for your internal system.
+     * @returns {Promise<Object>} Scan results containing risk_level.
+     */
+    async scan(inputText, endUserId = 'anonymous') {
+        if (!inputText) {
+            throw new Error('Aeglis Error: inputText is required for Quick Scan.');
+        }
+
+        try {
+            const response = await this.client.post('/scan', {
+                input_text: inputText,
+                end_user_id: endUserId
+            });
+            return response.data;
+        } catch (error) {
+            this._handleApiError(error);
+        }
+    }
+
+    /**
+     * 🔍 DEEP SCAN (Asynchronous File Scanning)
+     * Triggers your configured Webhook upon completion.
+     * @param {string} filePath - Absolute or relative path to the file on disk.
+     * @param {Object} [options={}] - Additional scanning options.
+     * @param {string} [options.inputText=''] - Optional context text to accompany the file.
+     * @param {string} [options.endUserId='anonymous'] - Your system's reference ID (returned in webhook).
+     * @returns {Promise<Object>} Acknowledgment of task processing.
+     */
+    async deepScan(filePath, options = {}) {
+        if (!filePath || !fs.existsSync(filePath)) {
+            throw new Error('Aeglis Error: A valid file path is required for Deep Scan.');
+        }
+
+        const inputText = options.inputText || '';
+        const endUserId = options.endUserId || 'anonymous';
+
+        try {
+            const form = new FormData();
+            
+            // Append file stream
+            form.append('file', fs.createReadStream(filePath));
+            
+            // Append optional fields matching FastAPI requirements
+            if (inputText) {
+                form.append('input_text', inputText);
+            }
+            if (endUserId) {
+                form.append('end_user_id', endUserId);
+            }
+
+            // Execute multipart/form-data request
+            const response = await axios.post(`${this.baseURL}/deep-scan`, form, {
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    ...form.getHeaders()
+                }
+            });
+            
+            return response.data; 
+        } catch (error) {
+            this._handleApiError(error);
+        }
+    }
+
+    /**
+     * ⚡ WEBHOOK VERIFICATION (Security)
+     * Verifies the authenticity of incoming webhooks using HMAC SHA-256.
+     * @param {string|Buffer} rawPayload - The raw, unparsed request body.
+     * @param {string} signatureHeader - The 'x-aeglis-signature' header value.
+     * @param {string} webhookSecret - Your Endpoint Secret from the dashboard.
+     * @returns {Object} The parsed JSON payload if verification succeeds.
+     */
+    verifyWebhook(rawPayload, signatureHeader, webhookSecret) {
+        if (!rawPayload || !signatureHeader || !webhookSecret) {
+            throw new Error('Aeglis Webhook Error: Missing payload, signature header, or secret.');
+        }
+
+        // Ensure payload is a raw string, not a parsed object
+        const payloadString = Buffer.isBuffer(rawPayload) 
+            ? rawPayload.toString('utf8') 
+            : typeof rawPayload === 'object' 
+                ? JSON.stringify(rawPayload) 
+                : rawPayload;
+
+        try {
+            // Re-create the signature using the Aeglis 'v1=' standard
+            const expectedSignature = 'v1=' + crypto
+                .createHmac('sha256', webhookSecret)
+                .update(payloadString)
+                .digest('hex');
+
+            // Prevent Timing Attacks during comparison
+            const expectedBuffer = Buffer.from(expectedSignature, 'utf8');
+            const signatureBuffer = Buffer.from(signatureHeader, 'utf8');
+
+            if (expectedBuffer.length !== signatureBuffer.length || 
+                !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
+                throw new Error('Signature Mismatch');
+            }
+
+            return JSON.parse(payloadString);
+
+        } catch (error) {
+            throw new Error(`Aeglis Webhook Verification Failed: Invalid Signature or Payload format. Attempted spoofing blocked.`);
+        }
+    }
+
+    /**
+     * Internal Error Handler for cleaner console outputs
+     * @private
+     */
+    _handleApiError(error) {
+        const message = error.response?.data?.detail || error.response?.data?.message || error.message;
+        throw new Error(`Aeglis API Error: ${message}`);
+    }
+}
+
+module.exports = Aeglis;

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "aeglis-sdk",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for the Aeglis Security API.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Aeglis Systems",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "axios": "^1.16.1",
+    "form-data": "^4.0.5"
+  }
+}