Protocollo WebBlocks Support 1.0

WebBlocks CMS e altri prodotti utilizzano questo protocollo per connettere un'installazione a un fornitore di supporto senza dare all'installazione un'estensione a livello di organizzazione credenziale. WebBlocks Workbench è un fornitore; le agenzie possono implementare il stesso contratto sulla propria origine HTTPS.

Individuazione

GET /.well-known/webblocks-support restituisce JSON:

{
  "protocol": "webblocks-support",
  "version": "1.0",
  "name": "Example Support",
  "api_base_url": "https://support.example.com/api/webblocks-support/v1",
  "capabilities": ["ticket.create", "ticket.list", "ticket.read", "ticket.reply", "diagnostics.request", "diagnostics.consent"],
  "activation_methods": ["invitation_code"]
}

L'URL di rilevamento e l'URL di base dell'API devono utilizzare la stessa origine HTTPS pubblica. I reindirizzamenti non vengono seguiti. CMS 1.0 richiede tutti e quattro i ticket capacità.

Attivazione dell'installazione

POST {api_base_url}/activations accetta:

{
  "install_ref": "random-install-uuid",
  "product": "webblocks-cms",
  "product_version": "1.74.0",
  "site_url": "https://example.com",
  "environment": "production",
  "invitation_code": "WBS-ABCD-EFGH-IJKL"
}

L'invito deve essere valido, non utilizzato ed emesso per il prodotto richiesto. Esso viene consumato atomicamente quando viene creata l'attivazione. Il provider restituisce un file segreto di attivazione per il polling e un codice di riferimento rivolto all'utente:

{
  "activation_id": "act_123",
  "activation_secret": "one-install-polling-secret",
  "user_code": "ABCD-EFGH",
  "expires_at": "2026-08-28T14:00:00Z"
}

Non è richiesto l'accesso al provider o una pagina di attivazione esterna. Il fornitore l'operatore esamina la richiesta supportata da invito e i sondaggi CMS GET {api_base_url}/activations/{activation_id} con il segreto di attivazione come token al portatore. Una risposta in sospeso è {"status":"pending"}. Una volta approvato restituisce:

{
  "status": "active",
  "credential": "installation-scoped-bearer-secret",
  "plan_name": "Support",
  "entitlement_expires_at": "2027-08-28T00:00:00Z"
}

Le credenziali devono essere limitate a un prodotto e a un'installazione. Non deve consentire l'organizzazione, il progetto, il piano o altra amministrazione di installazione.

Biglietti

Tutte le chiamate ticket vengono autenticate con le credenziali di installazione. Gli endpoint sono relativi a api_base_url:

  • POST /tickets
  • GET /tickets?external_user_ref=...&install_ref=...
  • GET /tickets/{ticket}?install_ref=...
  • POST /tickets/{ticket}/comments
  • DELETE /installation per revocare la credenziale di installazione

La creazione del biglietto include title, body, type, external_user_ref, external_user_name, install_ref, product, product_version, site_url e environment. Il fornitore deriva il proprio progetto e il proprio diritto dal file credenziale; il cliente non fornisce mai un progetto id.

La lettura dei ticket deve essere limitata dalle credenziali e da install_ref. Prima di mostrare un ticket, il CMS verifica anche external_user_ref, quindi un amministratore non può leggere il ticket di un altro indovinandone l’ID.

Un fornitore che pubblicizza diagnostics.request potrebbe includere messaggi in sospeso diagnostic_requests nel GET /tickets/{ticket}. Ogni richiesta contiene un ID opaco e un insieme di categorie consentite: system_summary, recent_application_errors e plugin_health.

L'installazione deve mostrare tali categorie al proprietario del biglietto e ricevere un approvazione esplicita prima di ritirare o inviare qualsiasi cosa. Risponde con POST /tickets/{ticket}/diagnostics/{diagnostic} e nessuno dei due {"action":"decline"} o {"action":"submit","snapshot":{...}}. Lo snapshot ha un limite di 64 KiB e può contenere solo le categorie richieste.

Il protocollo non accetta mai un percorso del file system o un comando arbitrario. Diagnostico la raccolta esclude .env, credenziali, cookie e log completi; errore recente le linee sono delimitate e oscurate localmente prima della trasmissione. I fornitori mantengono i timestamp della richiesta, del consenso e dell'invio come traccia di controllo.

Gestione dei segreti

Le credenziali di attivazione e installazione sono segreti da server a server. Loro non devono mai essere restituiti a un browser, registrati, inseriti in un sito esportato o esposti di nuovo nell'interfaccia utente. CMS li memorizza crittografati con la chiave dell'applicazione.