nis2-agile/docs/STANDARD_INSTALLER_INTEGRATION.md

STANDARD AgileHub — Installer Integration (canonico)

Autorità: AgileHub (single source of truth per la suite Agile Software). Versione: 1.0.1 — 2026-04-19 (patch: chiarimento payload tenants/report) Stato: ADOTTATO. Sostituisce qualsiasi proposta prodotto in caso di conflitto. Destinatari: team TRPG, SustainAI, NIS2, TAXAI (AllTax), LG231, DFM, MKTG, ALLRISK, WMS, MADEBYCLOUD, CertiSource. Spec origine: AGILEHUB_INSTALLER_INTEGRATION_SPEC.md v1.0 (TRPG, 2026-04-19) — recepita con override sotto. Registry DB: record master in nexus_hub.hub_standards (slug=installer-integration, version=1.0.1). Questo file è una copia derivata — in caso di disallineamento vince il DB.

Changelog

v1.0.1 — 2026-04-19 (patch, non breaking)

• §3.1 POST /api/tenants/report: chiarito che license_key è obbligatorio nel body (era implicito via "firma HMAC obbligatoria" ma non listato nel payload d'esempio). Serve al middleware HMAC per il lookup della hub_signing_key. Origine: smoke test TRPG 2026-04-19 21:15 — 404 LICENSE_NOT_FOUND senza license_key. Decisione AgileHub: consistency > minimal payload (defence in depth anti-tamper).
• TRPG già conforme via commit 5c1aa2e (2026-04-19).
• Altri prodotti: allineare payload tenants/report aggiungendo license_key string.

v1.0 — 2026-04-19

• Versione iniziale adottata. Spec origine TRPG recepita con override AgileHub.

---

1. Portata e autorità

Questo documento definisce il contratto unico fra AgileHub e i prodotti installati on-premise (o white-label) della suite. Vale per:

• Registrazione prodotti in AgileHub (hub_products)
• Provisioning istanze cliente (orchestrator SSH + installer script prodotto)
• Licensing + heartbeat + alert
• Onboarding tenant (consulting_firms) cross-istanza
• Firma HMAC + vault SSH

Regola di precedenza: in caso di conflitto fra una proposta prodotto (es. *_INTEGRATION_SPEC.md nel loro docs/) e questo standard, vince questo standard. Deviazioni motivate vanno chieste via ticket AgileHub con tag standard-exception.

---

2. Decisioni AgileHub (override sulla spec TRPG v1.0)

2.1 Hostname ufficiale

Ruolo	Hostname	Uso
Hub UI	https://agilehub.agile.software	Dashboard admin, /admin/products/*
Hub API (licensing)	https://agilehub.agile.software/api/license/*	endpoint validate/activate/register/report
Hub API (installer orchestrator)	https://agilehub.agile.software/api/installer/*	wizard, job status, log streaming

NO hub.agile.software. I prodotti che chiamano hub.agile.software vanno corretti prima del pilota.

2.2 Stack tecnico

Layer	Scelta
Backend licensing/installer	Node.js 20 + Express (pattern nexus-*-ms), microservizio nuovo nexus-hub-ms porta 4217
DB	MySQL host Hetzner (172.18.0.1:3306), DB dedicato nexus_hub, user nexus_user
Frontend	Next.js 15 + React 19 in nexus-dashboard, nuova sezione /admin/products/*
Job queue (Fase 3)	BullMQ su Redis (da aggiungere infra). Fino a Fase 2: cron + status polling
Email	Microservizio esistente email-automation-ms (NO SendGrid/MailHog esterni)
Secret vault	AES-256-GCM env-based, chiave in /etc/agilehub/vault.env (NO HashiCorp Vault/KMS)
SSH worker	ssh2 (npm) invocato da nexus-hub-ms, chiave decifrata on-demand

2.3 Prefisso tabelle e naming DB

• DB dedicato: nexus_hub
• Tabelle: prefisso hub_ mantenuto (compat con spec origine). Accesso esclusivo da nexus-hub-ms.
• Cross-DB query verso nexus_ticket_db, nexus_tenant_db, nexus_lead_db sono permesse solo via GRANT dedicato a nexus_user (pattern già in uso per SSO).

2.4 Ruoli

Ruolo	Permessi
hub_admin	Tutto tranne provisioning SSH
hub_installer	Nuovo. Lettura hub_*, esecuzione wizard, decrypt chiavi SSH con audit obbligatorio
hub_support	Solo lettura hub_instances, hub_tenants, hub_license_heartbeats

Il ruolo hub_installer è richiesto per Fase 3. Non riutilizzare hub_admin: blast radius troppo ampio.

2.5 Versioning

Recepita la regola TRPG: version mai hardcodata nei seed o nelle migration. La hub la registra da payload heartbeat. Per hub_products.version (ultima release disponibile) leggere on-demand via GET https://<product>.agile.software/version.json oppure aggiornare via POST /api/products/:slug/version (admin-only).

2.6 Integrazione obbligatoria con SSO

hub_tenants.owner_email DEVE essere foreign-key logica verso sso_identities.email (DB nexus_tenant_db). Al provisioning di un nuovo tenant:

1. nexus-hub-ms POST /api/auth/admin/tenants/create sull'istanza
2. L'istanza crea consulting_firm + user locale
3. nexus-hub-ms replica l'identità in sso_identities (se non esiste)
4. Prima login dell'owner → SSO flow standard (Fase 2 SSO)

Prodotti che non hanno ancora SSO dual-mode: finché non è attivo, hub_tenants funziona stand-alone ma owner_email deve comunque essere univoco cross-istanza.

2.7 Deprecazione products.json

/opt/agent-ai/hub/products.json è deprecato dalla Fase 2. Entro la Fase 2 completa:

• hub_products diventa la sorgente di verità
• La UI legge da hub_products, non più da products.json
• products.json resta come fallback statico per landing page esterne, generato da cron da hub_products

2.8 Multi-prodotto da subito

Fase 1 va implementata generica (non TRPG-specific). Lo schema, gli endpoint e le firme HMAC supportano product_slug variabile fin dal primo giorno. Il seed iniziale è per TRPG, ma il codice non hardcoda nulla.

---

3. Contratto API canonico

3.1 Endpoint hub (Istanza → AgileHub)

Tutti su https://agilehub.agile.software/api/..., header obbligatorio:

X-Product-Signature: hmac_sha256(body, HUB_SIGNING_KEY_<PRODUCT_SLUG_UPPER>)
Content-Type: application/json

Endpoint	Scopo	Chiamato da
POST /api/license/activate	Prima attivazione dopo install	install-<slug>.sh
POST /api/license/validate	Heartbeat periodico (24h default, 1h se anomalia)	cron istanza
POST /api/instances/register	Registrazione finale istanza	install-<slug>.sh
POST /api/tenants/report	Sync tenant create/update/archive	istanza, on-change
GET /api/products/:slug/version	Ultima versione disponibile	update-<slug>.sh

Payload: identici alla spec TRPG §6 (validate/activate/register/report). Campi obbligatori aggiuntivi in tutti i body:

• product_slug — sempre, anche dove la spec TRPG lo omette implicitamente
• license_key — sempre (v1.0.1 clarification). Serve al middleware HMAC per lookup di hub_signing_key prima della verifica firma. Include tenants/report che nella spec origine non lo listava esplicitamente.

Eccezione: POST /api/license/activate non porta X-Product-Signature (primo handshake, la chiave non esiste ancora) ma deve comunque includere license_key per il match iniziale.

3.2 Endpoint istanza (AgileHub → Istanza)

Ogni prodotto della suite deve esporre:

Endpoint	Scopo	Auth
POST /api/auth/admin/tenants/create	Onboarding tenant da hub	Bearer JWT service + X-Hub-Signature
POST /api/auth/admin/tenants/:id/suspend	Sospensione tenant	idem
POST /api/auth/admin/tenants/:id/resume	Riattivazione tenant	idem
GET /api/auth/admin/health	Health check completo per hub	API key service

Shape risposta: identica alla spec TRPG §5.2. Ogni prodotto implementa il proprio endpoint ma lo shape è vincolante.

3.3 Installer script non-interattivo (obbligatorio per prodotti orchestrati)

Ogni prodotto della suite che vuole supportare provisioning orchestrato da AgileHub deve fornire uno script:

install-<slug>.sh --non-interactive --json-output \
  --slug=... --domain=... --client-name=... --admin-email=... --admin-name=... \
  --license-key=... --hub-url=https://agilehub.agile.software \
  --<provider-key-1>=... --<provider-key-2>=... \
  [--smtp-host=... ...] [--force-reinstall]

Exit codes standard (identici per tutti i prodotti):

Codice	Significato
0	Success
10	Preflight failed (docker, RAM, disk, porte)
20	Secret generation failed
30	Hub activation failed (license invalid)
40	Docker load/up failed
50	Migration DB failed
60	Seed/admin creation failed
70	SSL setup failed
80	Verify-install failed
90	Internal error

JSON output: shape identica a spec TRPG §5.1. Campo product_slug obbligatorio in entrambi i rami (success/failure).

---

4. Schema DB canonico (DB nexus_hub)

Recepito integralmente dallo schema TRPG §3.1 (8 tabelle):

• hub_products
• hub_instances
• hub_instance_provisioning_logs
• hub_licenses
• hub_license_heartbeats
• hub_license_alerts
• hub_tenants
• hub_ssh_credentials

Modifiche AgileHub:

1. hub_products.framework VARCHAR(32) NULL — aggiunto, indica stack prodotto (php-vanilla, node-express, nextjs, ecc.) utile all'orchestrator
2. hub_instances.sso_enabled BOOLEAN DEFAULT FALSE — aggiunto, indica se il prodotto ha SSO attivo su quell'istanza
3. hub_tenants.sso_identity_id INT NULL — FK logica a sso_identities.id (riempito quando SSO attivo)
4. Tutte le tabelle hanno tenant_id INT NULL per compat futuro con multi-tenancy hub (oggi NULL, riservato)

Migration canonical: nexus-hub-ms/migrations/001-initial-schema.sql (da creare). Sub-approval obbligatoria prima dell'esecuzione su produzione (maintenance mode come da CLAUDE.md).

---

5. Sicurezza

5.1 Firma HMAC

• Algoritmo: HMAC-SHA256
• Chiave: HUB_SIGNING_KEY_<PRODUCT_SLUG_UPPER> (es. HUB_SIGNING_KEY_TRPG, HUB_SIGNING_KEY_SUSTAINAI)
• Generazione: openssl rand -hex 32
• Storage: in /etc/agilehub/vault.env sull'host AgileHub + .env di ogni istanza (propagata da installer al momento di activate)
• Rotazione: ogni 6 mesi, bidirezionale coordinata

5.2 SSH vault

• Cifratura: AES-256-GCM
• Master key: HUB_VAULT_KEY in /etc/agilehub/vault.env (NON in DB, NON in repo git)
• Ogni decrypt logga in hub_audit_logs con user_id, timestamp, source_ip, purpose
• Sudo whitelist sul server target: file /etc/sudoers.d/<slug>-installer con binari strettamente necessari

5.3 JWT service-to-service

• Algoritmo: RS256
• Chiave privata AgileHub + chiave pubblica distribuita ai prodotti al momento dell'attivazione
• Claim obbligatori: iss=agilehub, aud=<product_slug>, role=service, exp ≤ 5 minuti
• Ogni prodotto verifica iss + aud + exp + firma

---

6. Fasi di rollout (coordinate cross-prodotto)

Fase	Durata	Chi fa cosa	Bloccante per
Fase 1 — API licensing hub	2-3 gg	AgileHub: nexus-hub-ms + migration nexus_hub + 5 endpoint + seed 11 prodotti	Prima installazione cliente qualsiasi prodotto
Fase 1b — Installer script prodotto	3-5 gg/prodotto	Ogni prodotto: install-<slug>.sh non-interattivo + update-<slug>.sh + /api/auth/admin/tenants/* endpoint	Pilota white-label di quel prodotto
Fase 2 — UI Prodotti read-only	3-4 gg	AgileHub: sidebar "Prodotti", elenco, detail read-only, heartbeat dashboard	Visibilità pilota
Fase 3 — Orchestrator + wizard	6-8 gg	AgileHub: wizard 5-step, SSH worker, log streaming, rollback, BullMQ, encrypt vault	Onboarding cliente self-service
Fase 4 — Multi-prodotto generalizzato	2-3 gg	AgileHub: template wizard per prodotto, installer_orchestrator_config drive-based, billing hook	Scale-up suite

Pilota: TRPG primo. Dopo pilota OK, checklist per onboarding secondo prodotto (SustainAI probabile next).

---

7. Obblighi prodotti della suite

Per essere "orchestrabile" da AgileHub, un prodotto DEVE:

1. ✅ Fornire install-<slug>.sh --non-interactive --json-output con exit codes e shape JSON canonici
2. ✅ Fornire update-<slug>.sh (Fase 3, no urgenza) con stesso pattern
3. ✅ Esporre GET /version.json con {version, released_at, changelog_url}
4. ✅ Esporre GET /api/auth/admin/health autenticato
5. ✅ Esporre POST /api/auth/admin/tenants/create|:id/suspend|:id/resume con HMAC + JWT service
6. ✅ Chiamare POST /api/license/activate alla fine di install-<slug>.sh
7. ✅ Avere un cron license-heartbeat.sh che chiama POST /api/license/validate ogni 24h (1h se anomalia)
8. ✅ Chiamare POST /api/tenants/report ad ogni create/update/archive consulting_firm
9. ✅ Gestire stati licenza: valid → read_only (48h grace) → locked (168h) con banner UI maintenance
10. ✅ Propagare HUB_SIGNING_KEY_<SLUG> nel .env istanza al momento dell'attivazione

Un prodotto che non rispetta questi 10 punti non può fare parte del catalogo installer AgileHub. Può restare nel menu products.json come link esterno (installer_type=external_link) finché non si adegua.

---

8. Domande aperte — risposte ufficiali

Le 10 domande di §11 della spec TRPG trovano risposta nel capitolo 2 di questo doc. Riepilogo:

1. Framework hub: Node.js/Express (non PHP).
2. DB: MySQL host Hetzner, DB dedicato nexus_hub.
3. Job queue: cron fino a Fase 2, BullMQ/Redis da Fase 3.
4. UI: Next.js 15 + React 19 (nexus-dashboard).
5. Vault SSH: AES-256-GCM env-based.
6. Monitoring: /health endpoint + cron watchdog esistente. Prometheus opzionale in Fase 4.
7. Ruolo installer: nuovo hub_installer separato da hub_admin.
8. Email: email-automation-ms esistente.
9. Multi-prodotto: generico da Fase 1, seed TRPG ma codice agnostic.
10. Billing: nessun Stripe oggi. hub_customers placeholder, billing in Fase 4.

---

9. Prossimi passi

1. AgileHub: scaffold nexus-hub-ms + migration 001-initial-schema.sql (sub-approval richiesta)
2. AgileHub: distribuire questo documento a tutti i prodotti della suite via SSH Hetzner
3. TRPG: adeguare install-trpg.sh al contratto §3.3 (hostname agilehub.agile.software, exit codes canonici, JSON shape)
4. TRPG: implementare /api/auth/admin/tenants/* endpoint con HMAC + JWT (§3.2)
5. Suite: ogni team leggere questo doc e aprire ticket AgileHub con tag installer-readiness per dichiarare quando saranno pronti

---

10. Riferimenti

• Spec origine TRPG: /var/www/trpg-agile/docs/AGILEHUB_INSTALLER_INTEGRATION_SPEC.md (v1.0, 2026-04-19)
• Roadmap TRPG: /var/www/trpg-agile/docs/INSTALLER_ROADMAP.md
• White-label TRPG: /var/www/trpg-agile/docs/INSTALLER_WHITELABEL.md
• Licensing model TRPG: /var/www/trpg-agile/docs/PROTEZIONE_FASE4_LICENSING.md
• Multi-studio TRPG: /var/www/trpg-agile/docs/MULTI_STUDIO_SPEC.md
• SSO AgileHub: /projects/agile-services/docs/SPEC_SSO_SINGLE_SIGN_ON.md
• SSO fasi: /projects/agile-services/docs/SSO_FASI_IMPLEMENTAZIONE.md
• CLAUDE.md AgileHub: /projects/agile-services/CLAUDE.md (regole maintenance + agent + escalation)

---

Firma autorità: questo documento è canonico per la suite Agile Software. Modifiche richiedono consenso AgileHub + notifica a tutti i prodotti della suite.

Versione: 1.0 — 2026-04-19 Prossima revisione: dopo completamento pilota TRPG (stimata 2026-05-31).