API Reference del Control Plane

Il Control Plane espone un’unica API versionata sotto /api/v1. Tre confini di fiducia, tre credenziali diverse — mai mescolarle.

Canale edge — Bearer <edge api_key> + x-edge-signature

Usato dai nodi edge. L’API key viene emessa al claim del bootstrap e ruotata a ogni re-claim; il Control Plane conserva solo il suo hash SHA-256. Ogni chiamata autenticata aggiorna anche l’heartbeat di flotta (last_poll_at).

I nodi con node_pubkey registrata devono inoltre firmare ogni richiesta: header x-edge-signature: ed25519.<b64> calcolata sui byte esatti del body HTTP — un JSON riserializzato non verifica. Nodo firmato senza firma → 403 EDGE_SIGNATURE_REQUIRED; firma errata → EDGE_SIGNATURE_INVALID. I nodi senza pubkey (rollout legacy) sono accettati non firmati. Il replay è un no-op grazie alla dedup, quindi le firme non portano timestamp. Identificazione del nodo via x-edge-node; heartbeat opzionale x-kernel-version.

Gli errori usano codici stabili (LICENSE_SUSPENDED, EDGE_CAP_EXCEEDED, DRAINING, BATCH_TOO_LARGE, EDGE_SIGNATURE_REQUIRED, EDGE_SIGNATURE_INVALID, SCOPE_INSUFFICIENT…). Un 503 con code: DRAINING indica spegnimento in corso — ritenta più tardi, non allarmarti.

I batch di ingest firmati sono conservati verbatim in cp_ingest_batches (body grezzo + firma + nodo); ogni evento memorizzato vi si collega via batch_id — è ciò che ri-verifica l’oracolo pubblico.

Wire contract (v1)

Shape canoniche dei payload — specchiate da src/contracts/edge-cloud.sync.v1.ts nel repo kernel. L’identità del tenant deriva sempre dalla Bearer key: i campi tenant_id inviati nei body sono tollerati ma ignorati.

// POST /sync/ingest — richiesta
{ "events": [{
    "id": "uuid",                    // chiave dedup globale (cp_event_dedup)
    "aggregate_type": "string",
    "aggregate_id": "uuid",
    "event_type": "string",
    "payload": { /* dati evento */ },
    "created_at": "ISO-8601"         // opzionale, timestamp lato edge
}]}
// → 201 { status, processed_count, duplicate_count, latest_manifest_version }

// POST /sync/edge-audit — una riga NDJSON per record
{ "id": "uuid", "ts": 1735000000.0, "node_id": "edge-01",
  "action": "string", "actor": "string", "status": "string",
  "details": { /* forma libera */ } }
// → 201 { status, received_count, duplicate_count }

// GET /sync/licenses → 200
{ "licenses": [{ "plugin_code": "string", "version": "string",
                 "expires_at": 1735689600000,    // epoch ms
                 "signature": "ed25519 hex" }],  // firma "tenant:plugin:expiresMs"
  "revoked": ["plugin_code"],
  "tenant_license": {                            // null per tenant legacy/dev
    "license": {                                 // ← nested! lo status vive QUI
      "type": "ax_tenant_license", "v": 1, "tenant_id": "uuid",
      "status": "trial | active | past_due | canceled",
      "plan": "string", "max_edges": 25, "monthly_event_cap": 25000000,
      "features": ["..."], "issued_at": "ISO-8601",
      "valid_until": "ISO-8601", "grace_offline_hours": 168
    },
    "signature": "ed25519 hex"                   // firma stable-stringify(license)
  }
}
// Leggere tenant_license.license.status — NON tenant_license.status.
// `canceled` o valid_until + grace scaduti → l'edge deve rifiutare le scritture.

// GET /sync/manifest → 200
{ "version": 12, "manifest_raw": "{...}",       // la firma copre i byte raw
  "signature": "ed25519 hex", "migrations": [...] }

Scope delle chiavi (key_scope)

Enforced al middleware, prima dell’heartbeat — una chiamata respinta non conta mai come segno di vita. Negato → 403 SCOPE_INSUFFICIENT.

Endpoint pubblici — nessuna credenziale

Portale tenant — Bearer <portal-session>

La superficie rivolta al cliente (utenti umani), servita dal Control Plane sullo stesso base URL /api/v1. Due credenziali intercambiabili:

• Sessione portale — Bearer UUID. Si ottiene riscattando un invito pi_* monouso (/portal/invites/claim, arriva via email) o con /portal/login. TTL 12h, revocabile singolarmente, legata a un utente portale e a un tenant.
• API key dispositivo ak_* + tenant_id — back-compat: funziona su questa superficie solo con scope full. Le chiavi emesse al bootstrap claim sono scope sync → 403 qui, by design.

Una stessa email può esistere su più tenant (consulenti multi-cliente): se la password corrisponde a più account il login risponde 401 + code: TENANT_AMBIGUOUS — riprova passando tenant_id. La risposta non rivela mai a quali tenant l’email appartiene.

Ruoli: owner (completo) / member (lettura + submit, niente approvazioni).

Audit trail — export hash-chained + webhook SIEM

Ogni mutazione admin sul tenant finisce in cp_admin_audit — journal append-only con hash-chain (SHA-256 prev_hash → hash per tenant, ancorato al genesis). La superficie tenant lo espone read-only per i collector SIEM; la verifica della catena è self-service.

// GET /tenant/audit — una riga NDJSON per evento
{ "audit_version": "1.0",
  "seq": "100523",              // BIGSERIAL a 64 bit come STRINGA — i parser
                                // JS perdono precisione oltre 2^53; fare Number()
  "event_id": "adm_100523",
  "timestamp": "ISO-8601",
  "tenant_id": "uuid",
  "actor": { "id": "…", "ip": "…", "request_id": "…" },
  "action": "TENANT_PROVISIONED | SUBSCRIPTION_PATCHED | SYSTEM_RETENTION_PRUNED | …",
  "target": "…",
  "details": { /* dati evento */ },
  "integrity": { "prev_hash": "sha256 hex", "hash": "sha256 hex" }
}

Rate limit export: 60 req/min per tenant. Gli ingester devono conservare since_seq = ultimo seq ricevuto e fare polling incrementale.

Accesso dati tenant — proiezioni via data-link

Non esistono endpoint di business hard-coded sulla superficie tenant. I dati verticali (lotti, misure, ordini…) vivono nelle tabelle biz_* del tenant dichiarate dal data_link_engine del manifest, e le letture passano per lo stesso engine: le query di lettura dichiarate nel manifest sono indirizzabili come trigger azione che restituiscono righe. Lo stream di eventi sincronizzato in cp_events è ispezionabile dalla superficie admin (GET /api/v1/admin/tenants/:id/events /aggregates).

CORS

/waitlist è l’unica rotta sempre CORS-aperta. Le route portale/tenant usano un modello ibrido:

• PORTAL_ALLOWED_ORIGINS (env): le origini cloud nostre — valide per qualunque tenant (es. cockpit hostato su cp.axiom-trace.eu).
• cp_tenants.portal_origin (per-tenant, via admin PATCH …/portal-origin): il dominio on-prem del cliente — vincolato a quel tenant. Una richiesta dall’origine del tenant A con la sessione del tenant B → 403. Le origini registrate sono in cache ~60s; la PATCH admin invalida istantaneamente.

Il preflight OPTIONS è risposto sull’unione env ∪ DB (niente credenziali sul preflight); il binding per-tenant è enforced sulla richiesta reale. Senza header Origin niente CORS: curl, server-to-server e proxy same-origin restano identici.

Provalo live — l’API Playground è una console read-only su questa origine: accedi con un account portale e chiama gli endpoint GET qui sopra contro il tuo tenant. Prima volta? Leggi Il Contratto, poi gli esempi end-to-end.

Admin — Bearer <admin-session>

Le sessioni vengono da POST /api/v1/admin/login (rate-limited, password scrypt, scadenza enforced). Ogni chiamata admin mutante è registrata in cp_admin_audit.

Webhook Stripe — Stripe-Signature verificata

Eventi gestiti: checkout.session.completed (provisioning self-service del tenant + token bootstrap + welcome email), customer.subscription.* (state machine del contratto), invoice.paid / invoice.payment_failed (riattivazione / dunning + grace). Endpoint non firmato → 503 se STRIPE_WEBHOOK_SECRET non è configurato — fail-closed.

Convenzioni

• requestId su ogni risposta per correlazione edge ↔ cloud; includilo nelle segnalazioni di supporto.
• Idempotenza: l’ingest deduplica su id evento; ogni chiamata di sync è sicura da ritentare.
• Rate limit: tetto globale più bucket per rotta sugli endpoint pubblici, più bucket per-tenant su /sync/ingest e /sync/edge-audit così il flush post-blackout di un tenant non affama la flotta. Un 429 porta l’header Retry-After — rispettalo (backoff con jitter), non tempesta di retry.