@eulab/connect 0.8.1 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AUTOMATIONS.md +144 -0
- package/INTEGRATION.md +191 -0
- package/README.md +43 -0
- package/dist/application-store.d.ts +33 -0
- package/dist/application-store.js +68 -0
- package/dist/application.d.ts +218 -0
- package/dist/application.js +432 -0
- package/dist/automations.d.ts +119 -0
- package/dist/automations.js +17 -0
- package/dist/browser.js +32 -3
- package/dist/server.d.ts +188 -0
- package/dist/server.js +91 -2
- package/examples/workshop/.env.example +18 -0
- package/examples/workshop/README.md +13 -0
- package/examples/workshop/app.js +9 -0
- package/examples/workshop/index.html +6 -0
- package/examples/workshop/package.json +8 -0
- package/examples/workshop/schema.sql +10 -0
- package/examples/workshop/server.mjs +88 -0
- package/migrations/001-application-store.sql +7 -0
- package/package.json +34 -7
package/AUTOMATIONS.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Automazioni server — 0.12.0
|
|
2
|
+
|
|
3
|
+
Richiede Connect con schema **015** e API/runner aggiornati insieme. Contratto aggiuntivo: invii manuali, delega bot e `verifyWebhook` mantengono le firme esistenti. Nessuna pubblicazione npm implicita.
|
|
4
|
+
|
|
5
|
+
## Autorizzazione e credenziali
|
|
6
|
+
|
|
7
|
+
`ConnectServer.automations(accessToken?)` è disponibile solo nell’entrypoint `@eulab/connect/server`. Creazione e recupero richiedono credenziale dell’installazione e token personale corrente dell’autore. Il worker usa la credenziale della delega e quella dell’installazione, senza token UI o refresh token. Le route rifiutano chiamate con `Origin` o `Sec-Fetch-Site`, oltre a quelle prive dell’autenticazione server.
|
|
8
|
+
|
|
9
|
+
La delega registra autore verificato dal guard, installazione/app, finalità, canale, funzioni, archivio del numero WhatsApp, revisione, scadenza e revoca. Non assegna ruoli o permessi. Nessun `subject`, `admin` o token personale è accettato nel payload del job. Anche un amministratore deve possedere i diritti applicativi correnti: nessun bypass tecnico viene conservato nella delega.
|
|
10
|
+
|
|
11
|
+
Per `whatsapp` sono obbligatorie esattamente `whatsapp.manage` e `whatsapp.send`, oltre all’archivio appartenente all’installazione. Il controllo corrente comprende installazione/app, identità e membership abilitate, link locale, revoca applicativa, ruoli, catalogo, entitlement acquistato/abilitato, licenza attiva/non scaduta. Il provider identità viene letto tramite il servizio identità esistente: autore assente/disabilitato nega l’autorizzazione; indisponibilità nega l’effetto. Il token browser non viene conservato nella delega o nella sua outbox.
|
|
12
|
+
|
|
13
|
+
`application_notification` ed `email` richiedono deleghe **distinte**, con funzioni esistenti nel catalogo dell’app e prive del prefisso `whatsapp.`. Non ammettono `archiveId`. Il loro uso è autorizzabile con `verify`; gli effetti applicativi/email restano al consumer. Questo candidato non aggiunge un servizio di invio email delegato e non estende `POST /v1/notifications`.
|
|
14
|
+
|
|
15
|
+
Connect conserva la credenziale cifrata con la chiave dati esistente, più un hash per verificarla. `AutomationGrant` e `WebhookRegistration` contengono segreti: il consumer deve persisterli cifrati nel proprio store server, senza loggarli o restituirli al browser. `get`, `verify`, `revoke`, stato outbox, overview e liste webhook non restituiscono credenziali. Non passare segreti in URL o query string.
|
|
16
|
+
|
|
17
|
+
## Metodi SDK e route
|
|
18
|
+
|
|
19
|
+
Prefisso `R = /v1/installations/:installationId/automations`.
|
|
20
|
+
|
|
21
|
+
| SDK | HTTP | Autenticazione oltre alla credenziale installazione |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| `create(input, key)` | `POST R/delegations` | Token personale, `Idempotency-Key` |
|
|
24
|
+
| `recover(key)` | `GET R/delegations/by-key/:key` | Token personale dello stesso autore |
|
|
25
|
+
| `get(id, credential?)` | `GET R/delegations/:id` | Credenziale delega oppure token dello stesso autore |
|
|
26
|
+
| `verify(id, scope, credential?)` | `POST R/delegations/:id/verify` | Come `get` |
|
|
27
|
+
| `revoke(id, credential?)` | `DELETE R/delegations/:id` | Come `get`; ripetibile |
|
|
28
|
+
| `send(id, credential, input, key)` | `POST R/delegations/:id/messages` | `X-Connect-Delegation`, `Idempotency-Key` |
|
|
29
|
+
| `message(id, credential, key)` | `GET R/delegations/:id/messages/by-key/:key` | `X-Connect-Delegation` |
|
|
30
|
+
| `withdraw(id, credential, input, key)` | `POST R/delegations/:id/messages/by-key/:key/withdraw` | `X-Connect-Delegation`, stesso comando originale nel body |
|
|
31
|
+
| `webhooks.create(url, key)` | `POST R/webhooks` | Token personale con `whatsapp.manage`, `Idempotency-Key` |
|
|
32
|
+
| `webhooks.recover(key)` | `GET R/webhooks/by-key/:key` | Token personale dello stesso autore con `whatsapp.manage` |
|
|
33
|
+
|
|
34
|
+
Le chiavi sono obbligatorie, 8–128 caratteri `[A-Za-z0-9_-]`. Lo SDK non le genera e non ripete automaticamente le chiamate. `create` restituisce `{delegation, credential}`; `webhooks.create/recover` restituiscono `{id, url, enabled, secret}`. `verify` riceve `{purpose, channel, functions}` e restituisce `{allowed, reason}`. Errori di autenticazione, input, conflitto o indisponibilità restano errori HTTP/`ConnectApiError`.
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import {ConnectServer} from '@eulab/connect/server';
|
|
38
|
+
|
|
39
|
+
// Eseguito esclusivamente nel backend. binding proviene dallo store server cifrato.
|
|
40
|
+
const connect = new ConnectServer({apiUrl, ...binding});
|
|
41
|
+
const grant = await connect.automations(currentAccessToken).create({
|
|
42
|
+
purpose: 'appointments.reminder',
|
|
43
|
+
channel: 'whatsapp',
|
|
44
|
+
functions: ['whatsapp.manage', 'whatsapp.send'],
|
|
45
|
+
archiveId,
|
|
46
|
+
expiresAt: '2026-12-01T00:00:00Z',
|
|
47
|
+
}, persistedGrantKey);
|
|
48
|
+
// consumerVault è lo store cifrato del consumer, da implementare/riusare nel consumer.
|
|
49
|
+
await consumerVault.putEncrypted(grant.delegation.id, grant.credential);
|
|
50
|
+
// Al browser restituire solo stato, scadenza e motivo sicuro.
|
|
51
|
+
const ui = {id: grant.delegation.id, expiresAt: grant.delegation.expiresAt};
|
|
52
|
+
|
|
53
|
+
// Giorni dopo, anche con sessione UI scaduta:
|
|
54
|
+
const worker = connect.automations();
|
|
55
|
+
const credential = await consumerVault.readDecrypted(ui.id);
|
|
56
|
+
const accepted = await worker.send(ui.id, credential, {
|
|
57
|
+
purpose: 'appointments.reminder', sessionId,
|
|
58
|
+
payload: {kind: 'text', to: recipient, text: reminder},
|
|
59
|
+
}, persistedMessageKey);
|
|
60
|
+
const authoritative = await worker.message(ui.id, credential, persistedMessageKey);
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Con la facciata esistente, creazione/recupero si eseguono dentro `application.services(sessionId, (client, token) => ...)`, salvando il segreto nel backend e proiettando solo campi sicuri. Il worker successivo usa il binding server e la credenziale cifrata salvata, senza riaprire quella sessione.
|
|
64
|
+
|
|
65
|
+
## Idempotenza, scadenza e outbox
|
|
66
|
+
|
|
67
|
+
Creazione: ricevuta unica per `(installazione, autore, chiave)` e hash del payload canonico. Replay identico o `recover` restituiscono la stessa credenziale senza rotazione; il recupero ricontrolla i diritti correnti. Cambiare finalità, archivio, scadenza o funzioni con la stessa chiave produce `409`. Le funzioni sono ordinate e deduplicate; l’ordine delle proprietà JSON non cambia la ricevuta. La scadenza iniziale deve essere futura ed entro 366 giorni. Una delega scaduta/revocata non si rinnova con la stessa chiave.
|
|
68
|
+
|
|
69
|
+
Invio: stessa outbox Connect, stessa unicità `(installazione, chiave)`. La ricevuta include delega, autore, sessione, finalità e payload. Replay discordante produce `409`, anche tra deleghe/canali/manuale/bot. Una risposta HTTP persa si recupera con `message` o con lo stesso `send`, senza cambiare chiave. La lettura della ricevuta originaria resta possibile dopo revoca/scadenza/disconnessione, mentre nuovi invii sono negati. L’accesso API richiede comunque una credenziale installazione ancora abilitata. Una nuova sessione sullo stesso archivio è ammessa con una nuova richiesta; una sessione di altro numero/installazione è rifiutata. Un invio già accettato sulla sessione precedente non viene trasferito automaticamente.
|
|
70
|
+
|
|
71
|
+
| Stato | Significato |
|
|
72
|
+
|---|---|
|
|
73
|
+
| `queued` | Accettato in outbox; nessuna prova di invio |
|
|
74
|
+
| `sending` | Tentativo acquisito una sola volta; esito ancora aperto |
|
|
75
|
+
| `sent` | Provider ha restituito un identificatore, commit outbox/evento riuscito; non prova consegna al dispositivo |
|
|
76
|
+
| `cancelled` | Ritiro esplicito o arresto prima dell’effetto per revoca/scadenza/sessione non valida |
|
|
77
|
+
| `failed` | Stato storico compatibile; il nuovo percorso non deduce un rifiuto certo da un timeout |
|
|
78
|
+
| `uncertain` | Esito ambiguo o worker interrotto; nessun reinvio automatico |
|
|
79
|
+
|
|
80
|
+
Il runner ricontrolla il grant corrente prima di acquisire il tentativo e immediatamente prima della chiamata provider. L’acquisizione serializza con la revoca; anche una revoca conclusa tra acquisizione e ultimo controllo impedisce l’effetto. Non è possibile annullare una chiamata già entrata nel provider o garantire atomicità distribuita tra SQL, provider identità e WhatsApp. Un crash prima/dopo l’effetto lascia `sending`, trasformato in `uncertain` all’avvio: si conserva l’incertezza anche se il messaggio potrebbe non essere mai partito. Un errore del provider identità prima dell’acquisizione lascia il comando in coda, senza effetto.
|
|
81
|
+
|
|
82
|
+
Non usare una nuova chiave per aggirare `uncertain`. Il consumer deve mantenere la stessa chiave per lo stesso comando di dominio e gestire la riconciliazione esplicita. Le ricevute hanno la durata dei dati: l’eliminazione esplicita di archivio/installazione può eliminarle; non è una procedura di retry.
|
|
83
|
+
|
|
84
|
+
## Ritiro del singolo comando (0.12.0)
|
|
85
|
+
|
|
86
|
+
Il ritiro usa `connect.automations().withdraw(id, credential, originalInput, originalKey)` senza token browser. `originalInput` ha lo stesso tipo `DelegatedMessageInput` e la stessa normalizzazione di `send`: `{purpose, sessionId, payload}`. `originalKey` è la chiave dell’invio, presente nel path; non serve una seconda chiave di idempotenza. Le firme di `send`, `message`, `revoke` e delle API manuali/bot restano invariate.
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
const result = await connect.automations().withdraw(
|
|
90
|
+
delegationId, credential, originalCommand, persistedMessageKey,
|
|
91
|
+
);
|
|
92
|
+
if (result.outcome === 'withdrawn') {
|
|
93
|
+
// result.message.state è tipizzato come 'cancelled'.
|
|
94
|
+
// Questa ricevuta impedisce anche un successivo replay di send.
|
|
95
|
+
} else if (result.outcome === 'effect_started') {
|
|
96
|
+
// 'sending', 'sent' o 'uncertain': non dichiarare annullato l’effetto.
|
|
97
|
+
// Leggere message con la stessa chiave; nessun nuovo tentativo automatico.
|
|
98
|
+
} else {
|
|
99
|
+
// 'already_terminal': fallito o già cancellato per un altro motivo.
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Il risultato è l’unione discriminata `DelegatedMessageWithdrawal`, con `{outcome, message}`. `message` contiene la stessa proiezione autorevole di `message()`, senza payload o credenziali.
|
|
104
|
+
|
|
105
|
+
| Stato trovato sotto lock | Esito | Transizione |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| Comando assente | `withdrawn` | Ricevuta preventiva nella stessa outbox: `cancelled`, `error='command_withdrawn'`; mai `queued` |
|
|
108
|
+
| `queued` | `withdrawn` | Stessa riga/ID passa a `cancelled`, `error='command_withdrawn'` |
|
|
109
|
+
| `cancelled` con `command_withdrawn` | `withdrawn` | Nessuna modifica; replay del ritiro già riuscito |
|
|
110
|
+
| `cancelled` per altro motivo oppure `failed` | `already_terminal` | Nessuna modifica; non è una nuova cancellazione |
|
|
111
|
+
| `sending`, `sent`, `uncertain` | `effect_started` | Nessuna modifica; l’effetto acquisito non viene dichiarato ritirato |
|
|
112
|
+
|
|
113
|
+
La ricevuta è vincolata a installazione, delega/autore, finalità, sessione, chiave e hash canonico del payload originale, identico a quello di `send`. Se la chiave è già occupata da un altro comando, delega o invio manuale, oppure i dati originali non coincidono, il ritiro restituisce `409` e non cambia la riga. Per una ricevuta ancora assente si verifica comunque che la delega sia WhatsApp, la finalità coincida e la sessione appartenga all’installazione e all’archivio autorizzati; non occorre una sessione attualmente connessa. Credenziali installazione ancora valide e possesso della credenziale delega restano obbligatori. Una delega estranea non è visibile (`404`), un binding di installazione discordante è rifiutato; le chiavi restano nel namespace della rispettiva installazione.
|
|
114
|
+
|
|
115
|
+
**Serializzazione:** ritiro, `send` e acquisizione runner prendono il medesimo lock della delega prima del lock della riga outbox. Un `send` che non ha ancora inserito/commesso mantiene già quel lock: il ritiro attende il commit/rollback e poi cancella la coda o riserva la ricevuta preventiva, purché il runner non abbia già acquisito il tentativo; in quel caso restituisce `effect_started`. Se il ritiro arriva prima, la riga `cancelled` viene commessa prima che il `send` possa proseguire; quest’ultimo legge la stessa ricevuta senza accodare. Il vincolo univoco `(installazione, chiave)` e il confronto del digest risolvono anche collisioni tra deleghe differenti. Il ritiro non si conclude con un `404` per il solo fatto che l’invio non è ancora visibile.
|
|
116
|
+
|
|
117
|
+
Non è richiesta una migrazione: il candidato riusa colonne, stato terminale e vincoli dello schema 015. Non viene aggiunta una seconda outbox o una coda di cancellazioni. Il replay del ritiro riuscito restituisce lo stesso ID/stato; una risposta persa dopo commit si recupera ripetendo `withdraw` o leggendo `message`, con la stessa chiave. La ricevuta non viene riaperta da `send`, anche dopo scadenza/revoca. La lettura dello stato corrente di un tentativo già acquisito può invece evolvere, ad esempio da `sending` a `sent`: il ritiro resta `effect_started`, senza congelare uno stato vecchio.
|
|
118
|
+
|
|
119
|
+
Ritiro e lettura sono operazioni di proprietà, permesse anche dopo scadenza/revoca della delega e senza interrogare il provider identità o ampliare i diritti. Nuovi invii restano soggetti ai controlli correnti. Una revoca che aveva già cancellato la riga produce `already_terminal`; un comando ancora assente può essere riservato come ritirato anche con grant scaduto/revocato. Il ritiro non revoca la delega condivisa e non modifica le altre prenotazioni.
|
|
120
|
+
|
|
121
|
+
Nessuna cancellazione dal dispositivo, nessuna rotazione di credenziali e nessun annullamento di una chiamata già entrata nel provider. L’aggiornamento della prenotazione ALORA e il ritiro Connect non condividono una transazione: ALORA deve mantenere visibili gli esiti `effect_started` e `uncertain`, senza inventare un nuovo invio. Le ricevute durano quanto i dati dell’archivio/installazione, secondo il confine di conservazione già previsto; l’eliminazione esplicita dello storico non è una procedura di retry.
|
|
122
|
+
|
|
123
|
+
## Webhook recuperabili
|
|
124
|
+
|
|
125
|
+
Le nuove route usano `webhook_endpoints` esistente. Creazione concorrente o risposta persa dopo commit: ripetere la stessa chiave/URL o usare `recover`, con stesso autore e installazione. ID e segreto restano invariati. URL diverso con stessa chiave: `409`. Un endpoint disabilitato rimane disabilitato anche al replay. Gli endpoint storici/manuali non vengono adottati né duplicati da un recupero: senza ricevuta la nuova route restituisce `404`. L’API manuale storica resta disponibile.
|
|
126
|
+
|
|
127
|
+
Il trasporto mantiene HTTPS/443, controllo DNS e rifiuto di indirizzi privati. Un test loopback non dimostra raggiungibilità pubblica; non abilitare localhost nel runner per collaudare il consumer.
|
|
128
|
+
|
|
129
|
+
## Eventi firmati e risposte interattive
|
|
130
|
+
|
|
131
|
+
Envelope aggiuntivo compatibile: `{id, kind, createdAt, installationId, sessionId, payload}`. Il runner conserva `x-eulab-event-id`, `x-eulab-timestamp`, `x-eulab-signature`; HMAC-SHA256 su `timestamp.rawBody`. Riutilizzare `verifyWebhook(secret, rawBody, timestamp, signature)` esistente, con tolleranza di cinque minuti. Verificare il corpo originale prima del parsing; la firma non deduplica e non autorizza un’azione ALORA.
|
|
132
|
+
|
|
133
|
+
`message.received` conserva il nome storico e può indicare anche un messaggio proprio: controllare sempre `direction` e `fromMe`. Il payload tipizzato `WhatsAppMessageEventPayload` include:
|
|
134
|
+
|
|
135
|
+
- `messageId`, `providerId`, `chatId`, `sessionId`, `messageSessionId`, `archiveId`;
|
|
136
|
+
- `direction` (`in`, `out`, `unknown`), `fromMe`, `senderId`, `recipientId`;
|
|
137
|
+
- `occurredAt`, `observedAt`, `timestampSource` (`provider`, `connect`, `unknown`), `source`, `addressingVerified`;
|
|
138
|
+
- `kind`, `body.text`, `body.selectedButtonId` e contenuti interattivi supportati; il corpo storico resta compatibile.
|
|
139
|
+
|
|
140
|
+
`sessionId` identifica la connessione che ha osservato l’evento; `messageSessionId` quella della prima archiviazione del messaggio. `archiveId` identifica il numero attraverso le riconnessioni. Callback di sessioni chiuse/estranee sono scartate. Un’origine o timestamp incompleto è esplicito e il consumer deve negare azioni automatiche se non verificabile.
|
|
141
|
+
|
|
142
|
+
La selezione normalizzata produce **`message.interactive_response`**, con una ricevuta durevole unica `(messageId, kind)` nella stessa transazione di messaggio/evento/consegne. Funziona anche se `message.received` aveva già deduplicato lo stesso provider ID; callback duplicate o contraddittorie non producono altre selezioni. Se la normalizzazione arriva per prima, vengono emessi i due eventi distinti. L’ordine di consegna non è garantito. Le ricevute degli eventi ordinari storici vengono adottate dalla migrazione senza alterare l’evento originale.
|
|
143
|
+
|
|
144
|
+
Il consumer deve persistere la deduplica per event ID, verificare installazione/sessione/archivio, verso in ingresso, mittente/destinatario, timestamp e correlazione del pulsante al proprio piano/revisione/scadenza. Per selezioni usare `message.interactive_response`; non applicare lo stesso comando anche da `message.received`. Il provider non conosce conto, agenda o appuntamento ALORA. I formati SDK `WhatsAppPayload.kind='interactive'`, pulsanti reply/list e `InteractiveResponse` esistenti sono riusati.
|
package/INTEGRATION.md
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# Integrazione server Connect SDK 0.10.0
|
|
2
|
+
|
|
3
|
+
Nuova esportazione `@eulab/connect/application`, indipendente da Nest/Angular. `ConnectServer`, `ConnectBrowser`, `ConnectOnboardingSource` e le API `/v1/team` della 0.9.0 restano disponibili. Il nuovo modulo compone questi servizi e OIDC; nessuna dipendenza da Prisma, ALORA, profili aziendali o browser storage. Node >=22, dipendenza runtime `jose`; per lo store pronto installare `pg`.
|
|
4
|
+
|
|
5
|
+
## Installazione e prerequisiti
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install /percorso/eulab-connect-0.10.0.tgz pg
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Per presentare la prima pratica **non servono applicazione, sorgente approvata, licenza o client OIDC**. Un amministratore Connect emette una credenziale tecnica da **Attivazioni e migrazioni**, oppure `POST /v1/onboarding/presenters`: nome, deploymentIdentity stabile, scadenza; origini/app verificate sono attestazioni amministrative opzionali. Consegnare ID e segreto una sola volta al backend consumer mediante il proprio secret manager. Non usare credenziali Admin EULAB nel consumer.
|
|
12
|
+
|
|
13
|
+
La prima discovery/invio autenticata riserva `sourceId` al deployment e registra soltanto la provenienza non approvata. Non crea app, aziende, installazioni, identità, licenze o sessioni. Un altro presenter non può assumere un sourceId riservato; ruotare il segreto dello stesso presenter conserva il vincolo. Revoca/scadenza bloccano anche il recupero della configurazione.
|
|
14
|
+
|
|
15
|
+
Sul server Connect applicare le migrazioni fino a **013-onboarding-presenters.sql** tramite il normale comando amministrativo `npm run db:migrate`, dopo revisione/backup. Non applicarle nel database consumer. La candidata non esegue questo aggiornamento operativo automaticamente.
|
|
16
|
+
|
|
17
|
+
Nel consumer preparare PostgreSQL condiviso, chiave AES-256 casuale di 64 cifre esadecimali e namespace stabile distinto per sorgente/app/ambiente. Eseguire `store.migrate()` o `migrations/001-application-store.sql` nel database consumer. Conservare chiave e credenziali solo sul backend.
|
|
18
|
+
|
|
19
|
+
Il percorso precedente resta compatibile: `POST /v1/connect-sources` registra una sorgente con segreto backend; issuer/clientId/redirectUri possono essere forniti staticamente. Le sorgenti esistenti restano approvate per compatibilità: nessuna conversione automatica in presenter.
|
|
20
|
+
|
|
21
|
+
HTTP è rifiutato salvo `allowLoopbackHttp: true` e host `localhost`, `127.0.0.1` o `[::1]`. Configurare HTTPS in ambienti condivisi. Non usare il bypass HTTP per domini privati o reti Docker. URL senza password, frammenti o credenziali. Usare issuer canonico senza slash finale.
|
|
22
|
+
|
|
23
|
+
## Una sola istanza
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import {ConnectApplication, PostgresConnectApplicationStore} from '@eulab/connect/application';
|
|
27
|
+
import {defineFunctions} from '@eulab/connect/server';
|
|
28
|
+
import pg from 'pg';
|
|
29
|
+
|
|
30
|
+
const pool = new pg.Pool({connectionString: process.env.DATABASE_URL});
|
|
31
|
+
const store = new PostgresConnectApplicationStore(pool, 'my-app:development:source-1');
|
|
32
|
+
const connect = new ConnectApplication({
|
|
33
|
+
apiUrl, sourceId, appId, sourceSecret,
|
|
34
|
+
issuer, clientId, clientSecret, redirectUri, appOrigin,
|
|
35
|
+
encryptionKey, store,
|
|
36
|
+
catalog: defineFunctions({appId, version: 1, functions}),
|
|
37
|
+
accounts: {verifyLegacy, provision, restrict},
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Per partire prima dell’integrazione, usare lo stesso costruttore senza `sourceSecret`, `issuer`, `clientId`, `clientSecret` e `redirectUri`, aggiungendo:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
presenter: {
|
|
45
|
+
id: process.env.CONNECT_PRESENTER_ID,
|
|
46
|
+
secret: process.env.CONNECT_PRESENTER_SECRET,
|
|
47
|
+
deployment: {
|
|
48
|
+
name: 'Workshop sviluppo', environment: 'development',
|
|
49
|
+
origins: [appOrigin], catalogUrl: appOrigin + '/.well-known/eulab-connect.json',
|
|
50
|
+
oidcCallbacks: [appOrigin + '/callback'],
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
I metadati dichiarati non provano proprietà di app, email o URL. L’app verificata univoca può preselezionare il piano, senza concedere accesso. L’amministratore seleziona/crea app, cliente e installazione nella stessa pratica, assegna licenza/ruoli e collega esplicitamente eventuali identità esistenti, poi usa **Esegui migrazione**. Per nuovi presenter `prepare` verifica il piano senza creare oggetti. Password e permessi locali non diventano concessioni automatiche.
|
|
56
|
+
|
|
57
|
+
Prima di completare il piano, registrare nel provider il client Authorization Code/PKCE S256, callback esatta e audience `connect-api`; non abilitare password grant nel consumer. L’amministratore salva issuer/clientId/redirectUri ed eventuale segreto confidential nel piano, separatamente cifrato. Il segreto non torna nel JSON del piano o nell’audit. La configurazione diventa disponibile solo dopo completamento.
|
|
58
|
+
|
|
59
|
+
Il backend esegue `await connect.configuration.sync()` tramite un job o handler POST con Origin verificato; la risposta pubblicabile contiene solo stato e appId. `POST /v1/app-onboarding/configuration` richiede il medesimo presenter e segreto, non il solo deploymentId. La facciata valida origine callback, cifra la configurazione nello store condiviso e la ricarica al riavvio. Non richiamare il metodo basso livello dal browser: la risposta server include segreti. Non sincronizza automaticamente altri processi già avviati: richiamare sync anche su quelle istanze dopo una modifica amministrativa.
|
|
60
|
+
|
|
61
|
+
Prima del completamento sync può restituire `plannedAppId`, utile **solo** per pubblicare `connect.catalog` con l’app selezionata se diversa da quella dichiarata. Richiamare sync all’avvio del backend e dopo un cambio piano; questo suggerimento non è persistito né abilita SSO. Servire il catalogo dalla proprietà `connect.catalog`, non ricostruire il protocollo. Pubblicare un catalogo HTTPS raggiungibile dal server Connect prima dell’esecuzione reale.
|
|
62
|
+
|
|
63
|
+
Le variabili sono lette dalla configurazione backend, mai da un bundle frontend. Lo store è obbligatorio; non esiste un default in memoria. Conservare chiave e namespace identici fra istanze della stessa applicazione. La rotazione della chiave invalida i flussi/sessioni precedenti: pianificare una nuova autenticazione; non è presente un keyring automatico.
|
|
64
|
+
|
|
65
|
+
## Adattatori dell’applicazione
|
|
66
|
+
|
|
67
|
+
- `verifyLegacy({email,password}) → LegacyAccount | null`: verifica locale della password, restituisce ID azienda/persona, nome, ruolo e permessi proposti. Nessun hash o segreto nel risultato. Ambiguità fra aziende deve essere rifiutata o risolta nel proprio contesto locale, mai indovinata. Non crea sessioni.
|
|
68
|
+
- `provision(context,{operationId,transaction}) → {localTenantId,localUserId}`: eseguito **solo dopo** ID token firmato, issuer/audience/nonce/subject, accesso Connect e collegamenti verificati. Risolve gli ID espliciti autorizzati, preserva password/hash/profili esistenti, rifiuta conflitti. Non cercare un account da collegare tramite email. Per utenti Connect-only creare il profilo operativo senza copiare alcuna password Connect nel database locale.
|
|
69
|
+
- `restrict(profile,functionKey,resource) → boolean`: applica isolamento aziendale e restrizioni personali. L’autorizzazione Connect non filtra il database applicativo. Ogni query deve avere anche il proprio predicato sull’azienda autorizzata.
|
|
70
|
+
- `ConnectApplicationStore`: persistenza secondo il contratto TypeScript; usare l’adattatore PostgreSQL pronto se non occorre uno store custom. Catalogo funzioni dichiarato una sola volta nella configurazione.
|
|
71
|
+
|
|
72
|
+
I ruoli locali del contratto sorgente restano quelli pubblici 0.9.0 (`owner`, `manager`, `reception`, `collaborator`); non si sostituisce il modello autorizzativo locale con ruoli inventati dal consumer.
|
|
73
|
+
|
|
74
|
+
## Handler BFF
|
|
75
|
+
|
|
76
|
+
Ogni handler costruisce `BrowserContext = {origin,cookies}`. Per POST verificare l’**Origin reale** della richiesta contro `appOrigin`, prima della chiamata SDK. Non riempire `origin` con un valore fisso che aggiri il controllo. Per callback GET usare l’origine della URL effettiva dopo verifica di Host/proxy fidato: state e cookie proteggono il ritorno OIDC. Non fidarsi di Forwarded/Host arbitrari.
|
|
77
|
+
|
|
78
|
+
Applicare tutte le `CookieDirective` restituite come Set-Cookie: HttpOnly, SameSite=Lax, Secure con HTTPS, Path=/, Max-Age. I cookie HTTPS usano prefisso `__Host-`; non impostare Domain. Non pubblicare `cookies` come JSON sostitutivo dei veri header.
|
|
79
|
+
|
|
80
|
+
| Handler | Metodo SDK | Risultato UI |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| POST login | `auth.signIn({email,password?},ctx)` | `redirect`, `migration_required`, `pending`, `administrative_required` o `configuration_required` |
|
|
83
|
+
| POST sincronizza configurazione | `configuration.sync()` | `pending`, `configuration_required` o `ready` (solo metadati sicuri) |
|
|
84
|
+
| POST consenso | `migration.submit({challenge,legacyPassword,consentVersion,idempotencyKey,newConnectPassword?},ctx)` | stato/azione della richiesta |
|
|
85
|
+
| POST attivazione | `activation.submit({kind:'activation',companyName,applicant,initialPassword,consentVersion,idempotencyKey},ctx)` | stato/azione; nessuna sessione |
|
|
86
|
+
| GET callback | `auth.callback({state,code,error,iss},ctx)` | handoff opaco, cookie e redirect interno fisso |
|
|
87
|
+
| POST handoff | `auth.exchange(handoff,ctx)` | sessione locale e cookie; nessun token provider |
|
|
88
|
+
| Richiesta autenticata | `auth.resolve(auth.fromCookies(ctx))` | profilo verificato, subject, scadenza |
|
|
89
|
+
| POST refresh | `auth.refresh(sessionId)` | sessione; mai replay della mutazione applicativa |
|
|
90
|
+
| POST logout | `auth.logout(sessionId,ctx)` | `revoked`, `providerRevoked`, cookie eliminato |
|
|
91
|
+
| Operazione sui dati | `access.authorize(sessionId,functionKey,resource)` | autorizzazione centrale + restrizione locale |
|
|
92
|
+
|
|
93
|
+
`sessionId` è il solo handle casuale locale; il BFF può ometterlo dal JSON e conservarlo esclusivamente nel cookie HttpOnly. Non esporre mai `source.loginContext()` o un `ConnectServer` direttamente al browser: sono API backend che includono contesto/credenziali d’installazione. Anche `services()` è una callback **server**.
|
|
94
|
+
|
|
95
|
+
Usare un redirect interno fisso dopo callback. Se il BFF consegna l’handoff alla UI, usare un fragment, `Referrer-Policy: no-referrer`, niente log di URL/credenziali, rimuovere subito il fragment e inviarlo a `auth.exchange`. Non aggiungere un `returnTo` arbitrario. Il demo include tutti gli handler e una UI minima che rende gli esiti discriminati.
|
|
96
|
+
|
|
97
|
+
## Discovery, migrazione e stati
|
|
98
|
+
|
|
99
|
+
`signIn` invoca prima la sorgente Connect. Un collegamento autorizzato conduce direttamente a SSO; la password legacy non viene verificata. Un errore di sorgente o una revoca blocca il flusso, senza fallback legacy operativo.
|
|
100
|
+
|
|
101
|
+
Un conflitto di provenienza restituisce `administrative_required`; un accesso approvato senza configurazione OIDC restituisce `configuration_required`. Non verificano legacy né creano challenge/sessioni. Una pratica pendente restituisce attesa senza provisioning. Se serve una migrazione/reinvio/nuova password, una prova legacy valida crea un challenge opaco di 120 secondi legato al cookie. `migration.submit` richiede consenso versione `2026-10-21-mandatory-v1`, consuma il challenge una volta e ripete la verifica legacy. Non conserva la password legacy nello store. Un errore dopo il consumo richiede una nuova prova/challenge; non ripetere automaticamente.
|
|
102
|
+
|
|
103
|
+
Gli endpoint sorgente aggiungono `nextAction` a `{requestId,state}`. Il campo è opzionale nei tipi SDK per interoperabilità con server 0.9; in assenza di azione esplicita, i fallimenti richiedono assistenza (nessuna deduzione da messaggi HTTP).
|
|
104
|
+
|
|
105
|
+
| `nextAction` | UI e comportamento |
|
|
106
|
+
|---|---|
|
|
107
|
+
| `wait` | Attesa; aggiornamento tramite nuova discovery esplicita |
|
|
108
|
+
| `sign_in` | Nuovo login SSO |
|
|
109
|
+
| `choose_connect_password` | Solo migrazione legacy recuperabile: nuova prova locale + consenso + password Connect diversa |
|
|
110
|
+
| `resubmit` | Nuova prova e consenso, invio esplicito secondo i vincoli server |
|
|
111
|
+
| `contact_admin` | Attivazione con password rifiutata, collegamento esplicito o verifica amministrativa; nessuna prova legacy né merge per email |
|
|
112
|
+
| `closed` | Richiesta/pratica chiusa; nessuna riapertura tramite recupero |
|
|
113
|
+
|
|
114
|
+
Compatibilità: il server conserva il reinvio già supportato di una richiesta personale scaduta, **solo se la pratica aziendale è ancora riutilizzabile**. Le pratiche aziendali `rejected`, `expired`, `completed` e quelle `migrating` non vengono riaperte dal recupero. Una richiesta completata resta completata.
|
|
115
|
+
|
|
116
|
+
## Recupero password rifiutata
|
|
117
|
+
|
|
118
|
+
Una policy provider può produrre `failed` / `password_change_required` dopo la cancellazione della credenziale transitoria. La discovery restituisce `choose_connect_password` soltanto per una migrazione legacy recuperabile, senza subject o collegamento amministrativo, in una pratica ancora aperta. Una nuova attivazione restituisce `contact_admin`: il contratto attuale non offre un recupero pubblico senza prova legacy. Anche richieste già collegate richiedono assistenza; una pratica in esecuzione restituisce `wait`, una pratica terminale non propone recupero. Discovery, replay e recupero usano gli stessi criteri server. Con `contact_admin`, `auth.signIn` restituisce `pending` senza invocare `verifyLegacy`, creare challenge o rilasciare sessioni.
|
|
119
|
+
|
|
120
|
+
La UI chiede due campi distinti: password locale per la prova, nuova password per Connect. La facciata confronta le due, rifiuta valori uguali, verifica di nuovo il legacy e invia **solo la nuova credenziale** a `POST /v1/app-onboarding/password-recovery`. La password locale non viene inviata in questo recupero. Il consenso è legato al challenge monouso verificato.
|
|
121
|
+
|
|
122
|
+
Il contratto backend di recupero richiede schemaVersion, appId/sourceId, requestId, localTenantId, localUserId, email, consentVersion e newPassword. Il bearer della sorgente autentica il backend che **attesta** prova legacy fresca, consenso e distinzione delle password: Connect non può verificare la password del database locale. Se si usa il metodo basso livello `ConnectOnboardingSource.recoverPassword`, il chiamante deve attuare questi controlli; per la prossima app utilizzare `ConnectApplication.migration.submit`.
|
|
123
|
+
|
|
124
|
+
Il server blocca la pratica con lo stesso lock usato da esecuzione/rifiuto, verifica sorgente/app/ID locali, richiede stato failed + password_change_required, assenza di subject/collegamento esplicito e una **nuova chiave idempotente**. Cifra la nuova password con AAD requestId e TTL esistenti, imposta pending, non crea identità né esegue la migrazione automaticamente. L’amministratore deve eseguire la pratica. La chiave di recupero resta riservata: lo stesso invio restituisce lo stato corrente e non sostituisce la credenziale; una nuova credenziale dopo un altro rifiuto richiede un’altra chiave e una nuova prova/consenso. Non cambia hash legacy o password di identità esistenti.
|
|
125
|
+
|
|
126
|
+
## Atomicità e concorrenza
|
|
127
|
+
|
|
128
|
+
Store PostgreSQL: transazioni READ COMMITTED, lock advisory **di sessione** su namespace + chiave del flusso/sessione. Occorre un Pool con connessioni dedicate fino al rilascio; non usare PgBouncer in transaction pooling. I lock sono rilasciati anche su rollback; una connessione persa rilascia il lock nel server PostgreSQL. Timeout lock 15 secondi; chiamate OIDC/sorgente con timeout 10 secondi. Dimensionare il pool in base alla concorrenza; gli handler non devono mantenere altre transazioni locali in attesa dello stesso flusso.
|
|
129
|
+
|
|
130
|
+
- State, nonce, PKCE e contesto sono cifrati AES-256-GCM con AAD source/app/record; cookie contiene solo un valore casuale correlato.
|
|
131
|
+
- Callback: consumo state **prima** del grant, in transazione già confermata. Un crash impedisce il replay ma richiede nuovo login. TTL 10 minuti. ID token verificato con JWKS, issuer, audience, azp, nonce e subject; accesso e mapping locali verificati nuovamente.
|
|
132
|
+
- Handoff: TTL 60 secondi; cookie correlato, lock esclusivo, verifica accesso, provisioning e consumo nella stessa transazione. Se il provisioning usa `transaction.sql` sullo stesso database, i suoi cambiamenti e il consumo sono atomici. Non chiamare `checkpoint()` nell’adattatore account.
|
|
133
|
+
- Database diverso: nessuna promessa di transazione distribuita. Usare `operationId` come chiave idempotente persistente nel sistema locale e riconciliare una chiamata ripetuta dopo rollback/crash; restituire sempre gli stessi ID autorizzati. Il flusso può richiamare provision più volte, ma deve produrre un solo profilo.
|
|
134
|
+
- Sessioni: scadenza assoluta (8 ore di default, configurabile 60–604800 secondi), refresh preventivo sotto 30 secondi. Ogni resolve/azione riverifica sorgente e `/v1/access`, includendo subject, app, installazione e ID locale. Nessuna fiducia in una licenza memorizzata nel cookie.
|
|
135
|
+
- Refresh: lock per sessione fra processi. Un timestamp condiviso deduplica refresh forzati per 5 secondi. Prima del grant viene scritto un intento cifrato e chiamato `checkpoint()` (commit che **mantiene il lock di sessione**). Una nuova generazione diventa valida solo al commit del nuovo token. Timeout, risposta ambigua o crash conservano l’intento e rendono inutilizzabile la vecchia sessione; nuovo SSO richiesto, mai replay del vecchio refresh token. Gli intenti scadono con la sessione e vengono rimossi dal pruning.
|
|
136
|
+
- Logout: revoca locale durevole sotto lo stesso lock, prima del logout provider. `providerRevoked:false` segnala il fallimento remoto; `null` segnala nessuna credenziale disponibile e nessun tentativo remoto; la sessione locale resta revocata. Dopo una revoca rilevata da resolve la sessione provider può restare attiva nel provider fino a scadenza/logout globale; non si certifica revoca globale senza conferma.
|
|
137
|
+
- Nessuna chiamata applicativa viene ritentata automaticamente dopo rinnovo o risposta incerta.
|
|
138
|
+
|
|
139
|
+
Eseguire `store.prune()` periodicamente per eliminare ciphertext scaduti. Scadenza e consumo vengono comunque verificati a ogni lettura; il pruning non è una condizione per la sicurezza. Non registrare request body, cookie, state/code, token o ciphertext in audit applicativi.
|
|
140
|
+
|
|
141
|
+
## Servizi esistenti e diagnostica
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
await connect.services(sessionId, (server, token) => server.teamOverview(token));
|
|
145
|
+
await connect.services(sessionId, (server, token) => server.whatsapp(token).outbox());
|
|
146
|
+
await connect.services(sessionId, server => server.registerFunctions(catalogUrl));
|
|
147
|
+
const report = await connect.diagnose(emailFacoltativa);
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`services` condivide contesto e sessione autenticati; non consegnare la callback o il token al frontend. Configurare l’URL del catalogo esplicitamente per `registerFunctions(catalogUrl)`.
|
|
151
|
+
|
|
152
|
+
`ConnectApplicationError.code` è un’unione sicura: invalid_configuration, invalid_credentials, invalid_context, invalid_flow, invalid_consent, invalid_password, access_denied, session_expired, provider_unavailable, provision_conflict. Il BFF deve rendere soltanto code tipizzati; per le API basso livello restano gli errori compatibili precedenti. Non esporre errori database/provider grezzi.
|
|
153
|
+
|
|
154
|
+
`diagnose` è read-only: verifica configurazione già validata dal costruttore, discovery issuer e autenticazione sorgente. `authorization` resta `not_checked`: né discovery, né email, né raggiungibilità certificano un token utente, client OIDC autorizzato, licenza o associazione applicativa. Il costruttore segnala la configurazione non valida con `invalid_configuration`; `ConnectApplication.diagnose(config)` permette alla CLI di ottenere un report tipizzato anche prima della costruzione valida. Nessun segreto nei risultati. Per ALORA la configurazione richiesta è descritta in `docs/SDK-ALORA-DEVELOPMENT.md` del repository Connect; Il riferimento iniziale era ALORA in sola lettura; per l’adozione consumer successiva vedere la sezione finale di questa guida.
|
|
155
|
+
|
|
156
|
+
## Esempio e verifica
|
|
157
|
+
|
|
158
|
+
`examples/workshop` è un’app eseguibile con pagine HTML, BFF Node, account/project store SQL, migrazioni, diagnostica e seed legacy esplicito. Copiarla e installare il tarball; non copia alcun protocollo. I test `connect-application.test.ts` coprono provider simulato e possono usare PostgreSQL reale con `CONNECT_SDK_TEST_DATABASE_URL`. `node scripts/check-sdk-real-provider.mjs` crea e rimuove PostgreSQL e Keycloak temporanei: recupero password reale, SSO/PKCE/ID token, refresh e revoche; Connect usa il proprio harness PGlite e amministrazione simulata. Il report distingue esattamente questi livelli. Browser grafico, proxy/TLS pubblico e produzione richiedono collaudi separati.
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
## Riutilizzo nelle app e stato del consumer ALORA
|
|
162
|
+
|
|
163
|
+
Il consumer ALORA ha adottato presenter e configuration.sync della candidata schema 013, eliminando il proprio percorso enrollment separato. La configurazione tecnica è predisposta; il collaudo utente finale non è stato eseguito automaticamente. Non confondere l’emissione del presenter con l’approvazione di un’integrazione.
|
|
164
|
+
|
|
165
|
+
Una nuova app riusa lo stesso modulo, store e metodi; implementa soltanto adattatori di dominio e HTTP. Eventuali token/sessioni legacy dell’app restano un adattatore di compatibilità, non un secondo protocollo da propagare. Lo SDK attuale assume endpoint provider Keycloak, appOrigin/callback nella stessa origine e quattro ruoli locali interoperabili (owner/manager/reception/collaborator). Altri modelli devono essere adattati esplicitamente senza ampliare permessi, o richiedono un’evoluzione coordinata del contratto. Questo limite non riguarda i ruoli Connect configurabili e le permission key applicative.
|
|
166
|
+
|
|
167
|
+
La facciata non risolve da sola DNS/TLS del deployment: issuer canonico, URL catalogo ammesso e raggiungibilità da browser/backend/Connect devono essere configurati nell’ambiente reale. Il client OIDC dedicato resta una responsabilità amministrativa. Non usare localhost nel container presumendo che indichi l’host.
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
## Origine di trasporto backend del provider
|
|
171
|
+
|
|
172
|
+
`oidcTransportOrigin` opzionale configura esclusivamente l’origine delle chiamate server discovery/token/JWKS/logout, preservando il percorso del realm. È un parametro server amministrativo, non ricevuto dal browser. Sono ammessi solo HTTPS o HTTP loopback con opt-in esplicito; path diversi da `/`, query, fragment e credenziali sono rifiutati.
|
|
173
|
+
|
|
174
|
+
L’issuer canonico resta quello approvato: URL di autorizzazione nel browser, confronto `iss`, audience, nonce e PKCE non vengono riscritti né disattivati. Un esempio Docker locale è issuer `http://localhost:8080/realms/eulab` e origine di trasporto `https://nginx`, con CA attendibile e relay privato verso il medesimo Keycloak. Non usare il parametro per collegare un provider diverso dall’issuer approvato.
|
|
175
|
+
|
|
176
|
+
Correzione del 24 ottobre adottata per il problema di raggiungibilità rilevato in ALORA dopo la migrazione. Compilazione/pacchetto aggiornati; il login end-to-end viene riprovato dall’utente, non è dichiarato collaudato da questa modifica.
|
|
177
|
+
|
|
178
|
+
## Candidata 0.11.0 — account squadra
|
|
179
|
+
|
|
180
|
+
La candidata aggiunge `application.team.createUser(sessionId, input)`, usando la stessa istanza e la sessione backend già approvata. L'input contiene il profilo locale persistito (`localUserId`, email, nome/cognome, ruolo operativo e permessi), i `roleIds` esplicitamente scelti e una password iniziale facoltativa. Sorgente e azienda locale derivano dalla configurazione/sessione; lo username è generato se omesso. Non aggiungere un signup parallelo o chiamate amministrative nel browser.
|
|
181
|
+
|
|
182
|
+
Richiede API Connect aggiornata, migrazione 014 e bootstrap degli attributi provider riservati. La creazione conserva le restrizioni di licenza/delega e non sostituisce revisioni o riattivazioni amministrative. Risultato tipizzato `ApplicationTeamUserResult`; errori `ConnectApiError` con `status` e `code`. I rifiuti di business conservano la sessione operatore; nessun reinvio automatico di password o mutazioni dopo esiti incerti. `ssoSetupRequired` segnala eventuali azioni provider ancora necessarie.
|
|
183
|
+
|
|
184
|
+
La distribuzione npm 0.10.0 non contiene questo metodo. Questa candidata non comporta pubblicazione automatica. Specifica completa ed evidenze nel repository Connect: `docs/DELEGATED-ACCOUNTS-STEP-5.md`.
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
## Automazioni appuntamenti — 0.12.0
|
|
188
|
+
|
|
189
|
+
Il contratto server aggiuntivo è in [AUTOMATIONS.md](./AUTOMATIONS.md): `ConnectServer.automations(token)` per consenso/recupero, `ConnectServer.automations()` per worker con credenziale delegata. Richiede schema 015 e API/runner aggiornati insieme. La facciata esistente `services(sessionId, callback)` permette l’autorizzazione iniziale senza esportare token al browser. Persisti grant e segreto webhook cifrati nel backend; al browser proietta soltanto stato, scadenza e motivo sicuro. Non usare refresh token UI per job differiti e non cambiare chiave dopo un esito incerto.
|
|
190
|
+
|
|
191
|
+
La versione 0.12.0 aggiunge `client.automations().withdraw(id, credential, originalInput, originalKey)`. Usa gli stessi dati/chiave di `send`, senza token browser. Una ricevuta `cancelled` preventiva impedisce il commit tardivo di un nuovo invio; `sending`/`sent`/`uncertain` producono `effect_started`, senza annullamento promesso o reinvio. Contratto e unione tipizzata `DelegatedMessageWithdrawal` in [AUTOMATIONS.md](./AUTOMATIONS.md#ritiro-del-singolo-comando-0120-rc2). Nessuna nuova migrazione oltre allo schema 015.
|
package/README.md
CHANGED
|
@@ -1,3 +1,18 @@
|
|
|
1
|
+
### Novità 0.12.0
|
|
2
|
+
|
|
3
|
+
- Prima versione stabile della linea 0.12 (contenuto della 0.12.0-rc.2 provata in ALORA).
|
|
4
|
+
- Client browser: le risposte non JSON dei proxy (502/503/504) diventano messaggi chiari invece di errori di parsing.
|
|
5
|
+
|
|
6
|
+
## Automazioni server 0.12.0
|
|
7
|
+
|
|
8
|
+
Delega revocabile, invio/stato e ritiro idempotente del singolo comando sulla stessa outbox, webhook recuperabili: [contratto API/SDK](./AUTOMATIONS.md). Richiede schema Connect 015; candidato locale, non pubblicato. Le credenziali restano nel backend; le API manuali e bot esistenti restano disponibili.
|
|
9
|
+
|
|
10
|
+
## Facciata applicativa 0.10.0
|
|
11
|
+
|
|
12
|
+
`@eulab/connect/application` esporta `ConnectApplication` e lo store PostgreSQL condiviso. Una sola istanza governa discovery, migrazione/attivazione, recupero password, OIDC/PKCE, cookie/handoff, sessioni cifrate e rinnovi concorrenti. I metodi 0.9.0 restano compatibili.
|
|
13
|
+
|
|
14
|
+
Guida completa: [INTEGRATION.md](./INTEGRATION.md). Applicazione BFF indipendente pronta da eseguire: [Workshop](./examples/workshop/README.md). Migrazione store: `migrations/001-application-store.sql`. Il server Connect deve avere schema 013 per le credenziali tecniche prima dell’integrazione (012 per il recupero password). Una sola facciata permette richiesta senza sorgente approvata o client OIDC, attesa senza sessione e sincronizzazione cifrata della configurazione dopo approvazione. Nessuna pubblicazione automatica.
|
|
15
|
+
|
|
1
16
|
# EULab Connect SDK
|
|
2
17
|
|
|
3
18
|
SDK ESM per SSO, permessi, utenti e WhatsApp tramite EULab Connect. Richiede un'installazione Connect configurata; il server SDK richiede Node.js 22 o successivo.
|
|
@@ -30,4 +45,32 @@ Gli export browser e server includono le dichiarazioni TypeScript. Il pacchetto
|
|
|
30
45
|
|
|
31
46
|
`ConnectServer.mirrorUser()` collega un utente locale a Connect. Il campo opzionale `initialPassword` proviene da una verifica locale appena conclusa, serve solo a inizializzare una nuova identità nel provider e non viene conservato da Connect. Non è disponibile nell’SDK browser.
|
|
32
47
|
|
|
48
|
+
`ConnectOnboardingSource` (server, dalla versione 0.9.0) è il client backend del contratto di attivazione assistita. Richiede la credenziale bootstrap della sorgente, registrata da EULAB prima dell’app/installazione, e non deve essere usato nel browser:
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import {ConnectOnboardingSource} from '@eulab/connect/server';
|
|
52
|
+
const onboarding = new ConnectOnboardingSource({
|
|
53
|
+
apiUrl: 'https://auth.eulab.cloud',
|
|
54
|
+
sourceId: 'alora-produzione',
|
|
55
|
+
appId: 'alora',
|
|
56
|
+
secret: process.env.CONNECT_BOOTSTRAP_SECRET!,
|
|
57
|
+
});
|
|
58
|
+
const lookup = await onboarding.loginContext('persona@example.test');
|
|
59
|
+
if (lookup.status === 'not_found') {
|
|
60
|
+
const receipt = await onboarding.submit({
|
|
61
|
+
kind: 'migration',
|
|
62
|
+
consentVersion: '2026-10-21-mandatory-v1',
|
|
63
|
+
localTenant: {id: 'tenant-1', name: 'Azienda', slug: 'azienda'},
|
|
64
|
+
localUser: {id: 'user-1', email: 'persona@example.test', firstName: 'Nome', lastName: 'Cognome', role: 'owner', permissions: []},
|
|
65
|
+
initialPassword: passwordVerifiedLocally,
|
|
66
|
+
}, idempotencyKey);
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`loginContext` non autentica l’utente e restituisce un contesto solo per collegamenti espliciti autorizzati alla sorgente. `submit` accetta `Idempotency-Key` stabili: la stessa chiave con lo stesso body restituisce la pratica esistente, con un body diverso produce un errore 409 e non sostituisce la credenziale. `ConnectOnboardingError.status` conserva il codice HTTP (401/403/409/...) per la gestione consumer. La password transitoria non viene mai restituita, registrata o inclusa nei tipi di risposta.
|
|
71
|
+
|
|
33
72
|
Le API `/v1/team` sono esposte da `teamOverview`, `teamUsers`, `teamRoles`, `teamFunctions`, `createTeamRole`, `updateTeamRole`, `deleteTeamRole`, `setTeamUserRoles`, `revokeTeamUser` e `restoreTeamUser`. Cliente e applicazione derivano dall’installazione autenticata; ogni assegnazione resta limitata a funzioni attive, licenziate e presenti nella delega del chiamante. Le operazioni di modifica richiedono `team.manage` nella delega effettiva.
|
|
73
|
+
|
|
74
|
+
### Candidata 0.11.0: creazione account delegata
|
|
75
|
+
|
|
76
|
+
La facciata server espone `application.team.createUser(sessionId, {localUser, roleIds, initialPassword?})`. Il consumer fornisce un profilo con ID locale già persistito; lo SDK ricava sorgente/azienda dalla sessione e configura il mirror completo senza esporre credenziali nel browser. Servono API aggiornata, migrazione 014, bootstrap provider e `team.manage` effettivo. Errori di business tipizzati conservano la sessione; esiti incerti richiedono verifica e azione esplicita sullo stesso ID. Vedi `INTEGRATION.md` e la consegna `docs/DELEGATED-ACCOUNTS-STEP-5.md` nel repository. Il metodo non è disponibile nella distribuzione 0.10.0.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/** Minimal pg-compatible driver. Pass a Pool, never a single shared Client. */
|
|
2
|
+
export interface ConnectSqlClient {
|
|
3
|
+
query(sql: string, values?: any[]): Promise<{
|
|
4
|
+
rows: any[];
|
|
5
|
+
}>;
|
|
6
|
+
release(): void;
|
|
7
|
+
}
|
|
8
|
+
export interface ConnectSqlPool {
|
|
9
|
+
connect(): Promise<ConnectSqlClient>;
|
|
10
|
+
}
|
|
11
|
+
export interface ConnectStoreTransaction {
|
|
12
|
+
get(id: string): Promise<string | null>;
|
|
13
|
+
put(id: string, cipher: string, expiresAt: number): Promise<void>;
|
|
14
|
+
remove(id: string): Promise<void>;
|
|
15
|
+
/** Available for provisioning in the same database transaction. */
|
|
16
|
+
readonly sql?: ConnectSqlClient;
|
|
17
|
+
/** Commit a fail-closed refresh intent while retaining the exclusive lock. */
|
|
18
|
+
checkpoint(): Promise<void>;
|
|
19
|
+
}
|
|
20
|
+
export interface ConnectApplicationStore {
|
|
21
|
+
/** Exclusive cross-process lock, with commit/rollback of all writes in fn. */
|
|
22
|
+
transaction<T>(key: string, fn: (tx: ConnectStoreTransaction) => Promise<T>): Promise<T>;
|
|
23
|
+
}
|
|
24
|
+
export declare const connectApplicationStoreMigration = "\nCREATE TABLE IF NOT EXISTS connect_sdk_schema(version integer PRIMARY KEY);\nCREATE TABLE IF NOT EXISTS connect_sdk_records(\n namespace text NOT NULL, id text NOT NULL, cipher text NOT NULL,\n expires_at timestamptz NOT NULL, PRIMARY KEY(namespace,id));\nCREATE INDEX IF NOT EXISTS connect_sdk_expiry ON connect_sdk_records(expires_at);\nINSERT INTO connect_sdk_schema(version) VALUES(1) ON CONFLICT DO NOTHING;\n";
|
|
25
|
+
/** Records are encrypted by ConnectApplication; the store never sees provider tokens. */
|
|
26
|
+
export declare class PostgresConnectApplicationStore implements ConnectApplicationStore {
|
|
27
|
+
private readonly pool;
|
|
28
|
+
private readonly namespace;
|
|
29
|
+
constructor(pool: ConnectSqlPool, namespace: string);
|
|
30
|
+
migrate(): Promise<void>;
|
|
31
|
+
prune(): Promise<void>;
|
|
32
|
+
transaction<T>(key: string, fn: (tx: ConnectStoreTransaction) => Promise<T>): Promise<T>;
|
|
33
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
export const connectApplicationStoreMigration = `
|
|
2
|
+
CREATE TABLE IF NOT EXISTS connect_sdk_schema(version integer PRIMARY KEY);
|
|
3
|
+
CREATE TABLE IF NOT EXISTS connect_sdk_records(
|
|
4
|
+
namespace text NOT NULL, id text NOT NULL, cipher text NOT NULL,
|
|
5
|
+
expires_at timestamptz NOT NULL, PRIMARY KEY(namespace,id));
|
|
6
|
+
CREATE INDEX IF NOT EXISTS connect_sdk_expiry ON connect_sdk_records(expires_at);
|
|
7
|
+
INSERT INTO connect_sdk_schema(version) VALUES(1) ON CONFLICT DO NOTHING;
|
|
8
|
+
`;
|
|
9
|
+
/** Records are encrypted by ConnectApplication; the store never sees provider tokens. */
|
|
10
|
+
export class PostgresConnectApplicationStore {
|
|
11
|
+
pool;
|
|
12
|
+
namespace;
|
|
13
|
+
constructor(pool, namespace) {
|
|
14
|
+
this.pool = pool;
|
|
15
|
+
this.namespace = namespace;
|
|
16
|
+
if (!namespace || namespace.length > 200)
|
|
17
|
+
throw new Error('Invalid Connect store namespace');
|
|
18
|
+
}
|
|
19
|
+
async migrate() { const client = await this.pool.connect(); try {
|
|
20
|
+
await client.query('BEGIN');
|
|
21
|
+
await client.query('SELECT pg_advisory_xact_lock(901272)');
|
|
22
|
+
await client.query(connectApplicationStoreMigration);
|
|
23
|
+
await client.query('COMMIT');
|
|
24
|
+
}
|
|
25
|
+
catch (e) {
|
|
26
|
+
await client.query('ROLLBACK');
|
|
27
|
+
throw e;
|
|
28
|
+
}
|
|
29
|
+
finally {
|
|
30
|
+
client.release();
|
|
31
|
+
} }
|
|
32
|
+
async prune() { const client = await this.pool.connect(); try {
|
|
33
|
+
await client.query('DELETE FROM connect_sdk_records WHERE namespace=$1 AND expires_at<=now()', [this.namespace]);
|
|
34
|
+
}
|
|
35
|
+
finally {
|
|
36
|
+
client.release();
|
|
37
|
+
} }
|
|
38
|
+
async transaction(key, fn) {
|
|
39
|
+
const client = await this.pool.connect();
|
|
40
|
+
try {
|
|
41
|
+
await client.query("SET lock_timeout='15s'");
|
|
42
|
+
await client.query('SELECT pg_advisory_lock(hashtextextended($1,0))', [JSON.stringify([this.namespace, key])]);
|
|
43
|
+
await client.query('BEGIN');
|
|
44
|
+
const tx = { sql: client,
|
|
45
|
+
checkpoint: async () => { await client.query('COMMIT'); await client.query('BEGIN'); },
|
|
46
|
+
get: async (id) => (await client.query('SELECT cipher FROM connect_sdk_records WHERE namespace=$1 AND id=$2 AND expires_at>now()', [this.namespace, id])).rows[0]?.cipher ?? null,
|
|
47
|
+
put: async (id, cipher, expiry) => { await client.query('INSERT INTO connect_sdk_records(namespace,id,cipher,expires_at) VALUES($1,$2,$3,$4) ON CONFLICT(namespace,id) DO UPDATE SET cipher=EXCLUDED.cipher,expires_at=EXCLUDED.expires_at', [this.namespace, id, cipher, new Date(expiry)]); },
|
|
48
|
+
remove: async (id) => { await client.query('DELETE FROM connect_sdk_records WHERE namespace=$1 AND id=$2', [this.namespace, id]); }
|
|
49
|
+
};
|
|
50
|
+
const result = await fn(tx);
|
|
51
|
+
await client.query('COMMIT');
|
|
52
|
+
return result;
|
|
53
|
+
}
|
|
54
|
+
catch (e) {
|
|
55
|
+
await client.query('ROLLBACK');
|
|
56
|
+
throw e;
|
|
57
|
+
}
|
|
58
|
+
finally {
|
|
59
|
+
try {
|
|
60
|
+
await client.query('SELECT pg_advisory_unlock(hashtextextended($1,0))', [JSON.stringify([this.namespace, key])]);
|
|
61
|
+
await client.query('RESET lock_timeout');
|
|
62
|
+
}
|
|
63
|
+
finally {
|
|
64
|
+
client.release();
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|