@relazio/plugin-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Relazio Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,255 @@
+# Relazio - Plugin SDK
+
+> Official SDK for building external plugins for Relazio
+
+[![Status](https://img.shields.io/badge/Status-In%20Development-yellow.svg)](https://github.com/relazio/plugin-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Platform**: Relazio (dal latino *relatio* - relazione, rapporto)  
+**Platform Version**: 2.0.0  
+**SDK Status**: 📋 Documentation Phase  
+**Target Release**: Q1 2026
+
+---
+
+## 📋 Overview
+
+Questo repository contiene la documentazione e, in futuro, il codice sorgente dell'SDK ufficiale per creare plugin esterni per **Relazio**.
+
+### Platform Features Implemented ✅
+
+Il sistema plugin esterni della piattaforma è **PRODUCTION READY** (Dicembre 2025):
+
+- ✅ Manifest validation (HTTPS, TLS, Zod)
+- ✅ Installation flow completo
+- ✅ Webhook system con HMAC-SHA256
+- ✅ Job queue con 7 stati
+- ✅ Rate limiting (30/min, 500/hour, 2000/day)
+- ✅ Timeout enforcement (30 min max)
+- ✅ Security completa
+- ✅ E2E testing (44 test, 91% pass)
+
+### SDK Packages Status
+
+- ✅ `@relazio/plugin-sdk` - NPM package (TypeScript/JavaScript) - **COMPLETO** ⭐
+  - ✅ Core plugin system
+  - ✅ Sync & async transforms  
+  - ✅ HMAC signature utilities
+  - ✅ Job progress tracking
+  - ✅ Express server integration
+  - ✅ **Multi-tenant support** (NEW!)
+- [ ] `relazio-plugin-sdk` - PyPI package (Python) - Q1 2026
+- [ ] CLI tool per scaffold plugin - Q1 2026
+- [ ] Mock platform per testing locale - Q2 2026
+- ✅ Repository esempi plugin - **4 esempi disponibili**
+
+---
+
+## 📚 Documentazione
+
+Tutta la documentazione è disponibile nella cartella `docs/`:
+
+### Per Utenti
+
+- **[EXTERNAL_PLUGINS_README.md](docs/EXTERNAL_PLUGINS_README.md)** - Quick start guide per installare e usare plugin esterni
+
+### Per Sviluppatori
+
+- **[QUICKSTART.md](QUICKSTART.md)** - ⭐ Quick start per creare plugin (3 righe di codice!)
+- **[SDK.md](docs/SDK.md)** - ⭐ SDK API reference completa (TypeScript/Python)
+- **[MULTI_TENANT.md](docs/MULTI_TENANT.md)** - Guida multi-tenancy (architettura standard)
+- **[CONFIGURATION.md](docs/CONFIGURATION.md)** - Guida configurazione (string, number, boolean, select)
+- **[EXTERNAL_PLUGINS.md](docs/EXTERNAL_PLUGINS.md)** - Architettura sistema plugin esterni
+- **[EXTERNAL_PLUGINS_FLOW.md](docs/EXTERNAL_PLUGINS_FLOW.md)** - Flussi dettagliati step-by-step
+- **[IMPLEMENTATION_EXTERNAL_PLUGINS.md](docs/IMPLEMENTATION_EXTERNAL_PLUGINS.md)** - Piano implementazione (reference)
+
+### Reference
+
+- **[EXTERNAL_PLUGINS_COMPLETE.md](docs/EXTERNAL_PLUGINS_COMPLETE.md)** - Riepilogo completo dell'implementazione platform
+- **[PLUGIN_SYSTEM.md](docs/PLUGIN_SYSTEM.md)** - Plugin built-in (reference)
+
+---
+
+## 🚀 Quick Start
+
+### Installazione
+
+```bash
+npm install @relazio/plugin-sdk
+```
+
+### Esempio Minimo
+
+```typescript
+import { RelazioPlugin } from '@relazio/plugin-sdk';
+
+const plugin = new RelazioPlugin({
+  id: 'my-plugin',
+  name: 'My Plugin',
+  version: '1.0.0',
+  author: 'Your Name',
+  description: 'What it does',
+  category: 'network'
+});
+
+// Registra transform
+plugin.transform({
+  id: 'my-transform',
+  name: 'My Transform',
+  description: 'Transforms data',
+  inputType: 'domain',
+  outputTypes: ['ip'],
+  
+  handler: async (input, config) => {
+    // input.organizationId contiene l'ID dell'organizzazione
+    console.log(`Processing for org: ${input.organizationId}`);
+    
+    return {
+      entities: [
+        {
+          type: 'ip',
+          value: '8.8.8.8',
+          label: 'Google DNS'
+        }
+      ],
+      edges: []
+    };
+  }
+});
+
+// Avvia server multi-tenant
+plugin.start({ 
+  port: 3000,
+  multiTenant: true  // ← Gestisce automaticamente tutto!
+});
+```
+
+**🎉 Il plugin gestisce automaticamente:**
+- ✅ Endpoint `/register` per nuove organizzazioni
+- ✅ Generazione automatica webhook secrets
+- ✅ Gestione separata per ogni organization
+- ✅ Zero configurazione manuale necessaria!
+
+### Esempi Completi
+
+Vedi la cartella `examples/` per esempi funzionanti:
+- **Email Parser** - Transform sincrona semplice
+- **DNS Toolkit** - Multiple transforms sincrone
+- **Multi-Tenant Plugin** - Transform asincrona con multi-organization
+
+---
+
+## 🎯 Roadmap
+
+### Phase 1: Documentation ✅ (Completata - Dicembre 2025)
+- [x] Architecture design
+- [x] SDK API design
+- [x] Flow documentation
+- [x] Security requirements
+- [x] Platform implementation
+
+### Phase 2: TypeScript SDK ✅ (Completata - Dicembre 2025)
+- [x] Core SDK implementation
+- [x] Manifest generator
+- [x] HMAC signing utilities
+- [x] Webhook handler
+- [x] Job progress tracking
+- [x] Testing utilities
+- [x] Esempi funzionanti
+- [ ] NPM package publication (Q1 2026)
+- [ ] CLI tool (Q1 2026)
+
+### Phase 3: Python SDK (Q1 2026)
+- [ ] Core SDK implementation
+- [ ] Manifest generator
+- [ ] HMAC signing utilities
+- [ ] Webhook handler (Flask/FastAPI)
+- [ ] Job progress tracking
+- [ ] Testing utilities
+- [ ] CLI tool
+- [ ] PyPI package publication
+
+### Phase 4: Developer Experience (Q2 2026)
+- [ ] Developer portal
+- [ ] Plugin examples repository
+- [ ] Video tutorials
+- [ ] Plugin templates (starter kits)
+- [ ] Testing playground
+- [ ] Plugin marketplace submission
+
+---
+
+## 🔐 Security Requirements
+
+### Mandatory (Enforced by Platform)
+
+- ✅ **HTTPS**: All endpoints must use HTTPS (HTTP rejected)
+- ✅ **TLS Valid**: Valid SSL certificate required
+- ✅ **HMAC Signature**: All webhooks must be signed with HMAC-SHA256
+- ✅ **Rate Limiting**: 30 req/min, 500 req/hour, 2000 req/day
+- ✅ **Timeouts**: 30s sync, 5s async response, 30 min job max
+
+### SDK Handles
+
+- HMAC signature generation
+- Webhook endpoint setup
+- Job progress tracking
+- Error handling
+- Timeout awareness
+
+---
+
+## 📦 Package Structure (Future)
+
+```
+@relazio/plugin-sdk/
+├── src/
+│   ├── core/
+│   │   ├── plugin.ts          # Main Plugin class
+│   │   ├── manifest.ts        # Manifest generator
+│   │   └── types.ts           # TypeScript types
+│   ├── server/
+│   │   ├── express.ts         # Express integration
+│   │   └── fastify.ts         # Fastify integration
+│   ├── security/
+│   │   └── hmac.ts            # HMAC utilities
+│   ├── jobs/
+│   │   └── progress.ts        # Job progress tracking
+│   └── testing/
+│       └── mock-platform.ts   # Mock platform for tests
+├── examples/
+│   ├── dns-plugin/
+│   ├── ip-lookup/
+│   └── shodan-integration/
+└── docs/
+    └── (all documentation files)
+```
+
+---
+
+## 🤝 Contributing
+
+Il progetto è attualmente in fase di sviluppo. I contributi saranno benvenuti a partire da Q1 2026.
+
+---
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+---
+
+## 🔗 Links
+
+- **Platform Repository**: [github.com/relazio/relazio](https://github.com/relazio/relazio)
+- **Documentation**: [docs/](docs/)
+- **Website**: Coming soon
+- **Discord**: Coming soon
+
+---
+
+**Status**: 📋 Documentation Complete, Implementation Q1 2026  
+**Platform**: ✅ Production Ready (Dicembre 2025)  
+**SDK**: 🚧 In Development (Q1 2026)
+
+

package/dist/core/manifest.d.ts

@@ -0,0 +1,21 @@
+import type { PluginManifest, PluginConfig, ConfigSchema, TransformConfig, AsyncTransformConfig, ManifestOptions } from '../core/types';
+/**
+ * Genera manifest JSON valido per la piattaforma Relazio
+ */
+export declare class ManifestGenerator {
+    private config;
+    private transforms;
+    private configSchema?;
+    constructor(config: PluginConfig);
+    setConfigSchema(schema: ConfigSchema): void;
+    addTransform(transform: TransformConfig | AsyncTransformConfig): void;
+    /**
+     * Genera manifest completo
+     */
+    generate(options: ManifestOptions): PluginManifest;
+    /**
+     * Genera manifest come JSON string
+     */
+    generateJSON(options: ManifestOptions, indent?: number): string;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/core/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/core/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,eAAe,EAEhB,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAqD;IACvE,OAAO,CAAC,YAAY,CAAC,CAAe;gBAExB,MAAM,EAAE,YAAY;IAIhC,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAI3C,YAAY,CAAC,SAAS,EAAE,eAAe,GAAG,oBAAoB,GAAG,IAAI;IAIrE;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc;IA4ElD;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,SAAI,GAAG,MAAM;CAI3D"}

package/dist/core/manifest.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManifestGenerator = void 0;
+/**
+ * Genera manifest JSON valido per la piattaforma Relazio
+ */
+class ManifestGenerator {
+    constructor(config) {
+        this.transforms = [];
+        this.config = config;
+    }
+    setConfigSchema(schema) {
+        this.configSchema = schema;
+    }
+    addTransform(transform) {
+        this.transforms.push(transform);
+    }
+    /**
+     * Genera manifest completo
+     */
+    generate(options) {
+        if (this.transforms.length === 0) {
+            throw new Error('Al least one transform is required');
+        }
+        // Allow HTTP for localhost/development, require HTTPS for production
+        const url = new URL(options.endpoint);
+        const isLocalhost = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '0.0.0.0';
+        if (!options.endpoint.startsWith('https://') && !isLocalhost) {
+            throw new Error('Endpoint must use HTTPS (except for localhost development)');
+        }
+        // Raccogli tutti gli input/output types
+        const inputTypes = new Set();
+        const outputTypes = new Set();
+        let hasAsync = false;
+        for (const transform of this.transforms) {
+            inputTypes.add(transform.inputType);
+            transform.outputTypes.forEach((type) => outputTypes.add(type));
+            // Check if it's async transform
+            if ('async' in transform) {
+                hasAsync = true;
+            }
+        }
+        const manifest = {
+            manifestVersion: '1.0',
+            plugin: {
+                id: this.config.id,
+                name: this.config.name,
+                description: this.config.description,
+                version: this.config.version,
+                author: this.config.author,
+                homepage: this.config.homepage,
+                documentation: this.config.documentation,
+                license: this.config.license || 'MIT',
+                icon: this.config.icon,
+                logoUrl: this.config.logoUrl,
+                category: this.config.category,
+                capabilities: {
+                    inputTypes: Array.from(inputTypes),
+                    outputTypes: Array.from(outputTypes),
+                    estimatedTime: hasAsync ? 'minutes' : 'seconds',
+                    supportsAsync: hasAsync,
+                },
+                transforms: this.transforms.map((transform) => ({
+                    id: transform.id,
+                    name: transform.name,
+                    description: transform.description,
+                    inputType: transform.inputType,
+                    outputTypes: transform.outputTypes,
+                    endpoint: `${options.endpoint}/${transform.id}`,
+                    method: 'POST',
+                    async: 'async' in transform,
+                })),
+                metadata: {
+                    tags: options.tags || [],
+                    minimumPlatformVersion: options.minimumPlatformVersion || '2.0.0',
+                },
+            },
+        };
+        // Aggiungi configurazione se presente
+        if (this.configSchema && Object.keys(this.configSchema).length > 0) {
+            manifest.plugin.configuration = {
+                required: Object.values(this.configSchema).some((field) => field.required),
+                schema: this.configSchema,
+            };
+        }
+        return manifest;
+    }
+    /**
+     * Genera manifest come JSON string
+     */
+    generateJSON(options, indent = 2) {
+        const manifest = this.generate(options);
+        return JSON.stringify(manifest, null, indent);
+    }
+}
+exports.ManifestGenerator = ManifestGenerator;

package/dist/core/plugin.d.ts

@@ -0,0 +1,110 @@
+import type { PluginConfig, ConfigSchema, TransformConfig, AsyncTransformConfig, StartOptions, ManifestOptions, PluginManifest, TransformInput, TransformResult } from './types';
+import { JobQueue, type WebhookSecretProvider } from '../jobs/progress';
+import { InstallationRegistry } from '../registry/installation';
+/**
+ * Classe principale per creare plugin Relazio
+ */
+export declare class RelazioPlugin {
+    private config;
+    private manifestGenerator;
+    private transforms;
+    private asyncTransforms;
+    private configSchema?;
+    private jobQueue?;
+    private server?;
+    private webhookSecret?;
+    private multiTenant;
+    private secretProvider?;
+    private registry?;
+    constructor(config: PluginConfig);
+    /**
+     * Definisci schema di configurazione
+     */
+    configure(schema: ConfigSchema): void;
+    /**
+     * Registra una transform sincrona
+     */
+    transform(config: TransformConfig): void;
+    /**
+     * Registra una transform asincrona
+     */
+    asyncTransform(config: AsyncTransformConfig): void;
+    /**
+     * Imposta webhook secret (single-tenant mode)
+     */
+    setWebhookSecret(secret: string): void;
+    /**
+     * Abilita multi-tenancy con secret provider
+     */
+    enableMultiTenant(secretProvider: WebhookSecretProvider): void;
+    /**
+     * Abilita multi-tenancy con gestione automatica in-memory
+     * Utile per development/testing
+     */
+    enableMultiTenantInMemory(): InstallationRegistry;
+    /**
+     * Ottieni registry (solo multi-tenant)
+     */
+    getRegistry(): InstallationRegistry | undefined;
+    /**
+     * Genera manifest JSON
+     */
+    generateManifest(options: ManifestOptions): PluginManifest;
+    /**
+     * Esegui una transform (usato internamente)
+     */
+    executeTransform(transformId: string, input: TransformInput): Promise<TransformResult>;
+    /**
+     * Esegui una transform asincrona (usato internamente)
+     */
+    executeAsyncTransform(transformId: string, input: TransformInput, callbackUrl: string, organizationId?: string): Promise<{
+        jobId: string;
+        estimatedTime?: number;
+    }>;
+    /**
+     * Avvia il server plugin
+     */
+    start(options: StartOptions): Promise<void>;
+    /**
+     * Ferma il server
+     */
+    stop(): Promise<void>;
+    /**
+     * Ottieni configurazione plugin
+     */
+    getConfig(): PluginConfig;
+    /**
+     * Ottieni lista transforms
+     */
+    getTransforms(): string[];
+    /**
+     * Ottieni lista async transforms
+     */
+    getAsyncTransforms(): string[];
+    /**
+     * Ottieni tutte le transforms
+     */
+    getAllTransforms(): Array<TransformConfig | AsyncTransformConfig>;
+    /**
+     * Verifica se una transform esiste
+     */
+    hasTransform(transformId: string): boolean;
+    /**
+     * Verifica se una transform è asincrona
+     */
+    isAsyncTransform(transformId: string): boolean;
+    /**
+     * Ottieni job queue (per monitoring)
+     */
+    getJobQueue(): JobQueue | undefined;
+    /**
+     * Verifica se è in modalità multi-tenant
+     */
+    isMultiTenant(): boolean;
+    /**
+     * Ottieni secret provider (solo multi-tenant)
+     */
+    getSecretProvider(): WebhookSecretProvider | undefined;
+}
+export { RelazioPlugin as OSINTPlugin };
+//# sourceMappingURL=plugin.d.ts.map

package/dist/core/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/core/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,QAAQ,EAAE,KAAK,qBAAqB,EAA0B,MAAM,kBAAkB,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGhE;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,eAAe,CAA2C;IAClE,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,cAAc,CAAC,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,CAAuB;gBAE5B,MAAM,EAAE,YAAY;IAKhC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAKrC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IASxC;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAkBlD;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAYtC;;OAEG;IACH,iBAAiB,CAAC,cAAc,EAAE,qBAAqB,GAAG,IAAI;IAiB9D;;;OAGG;IACH,yBAAyB,IAAI,oBAAoB;IAMjD;;OAEG;IACH,WAAW,IAAI,oBAAoB,GAAG,SAAS;IAI/C;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc;IAI1D;;OAEG;IACG,gBAAgB,CACpB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC;IAU3B;;OAEG;IACG,qBAAqB,CACzB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,MAAM,EACnB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAsCrD;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBjD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;OAEG;IACH,SAAS,IAAI,YAAY;IAIzB;;OAEG;IACH,aAAa,IAAI,MAAM,EAAE;IAIzB;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;OAEG;IACH,gBAAgB,IAAI,KAAK,CAAC,eAAe,GAAG,oBAAoB,CAAC;IAOjE;;OAEG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAI1C;;OAEG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAI9C;;OAEG;IACH,WAAW,IAAI,QAAQ,GAAG,SAAS;IAInC;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,iBAAiB,IAAI,qBAAqB,GAAG,SAAS;CAGvD;AAGD,OAAO,EAAE,aAAa,IAAI,WAAW,EAAE,CAAC"}