Actions & Esecuzione in Sandbox

Il Problema: Estensibilità Senza Fork

Ogni piattaforma di identità affronta alla fine la stessa tensione: i clienti hanno bisogno di logica personalizzata nei loro flussi di autenticazione, ma la piattaforma non può anticipare ogni requisito.

Senza un meccanismo di estensibilità, le opzioni sono: feature request (lente), webhook a servizi esterni (aggiunge latenza, richiede al cliente di ospitare un server webhook), fork della piattaforma (incubo di manutenzione), o regole solo configurazione (troppo limitate).

Ciò di cui i clienti hanno effettivamente bisogno è la capacità di eseguire codice personalizzato in punti specifici del flusso di autenticazione — prima del login (per bloccare tentativi sospetti), dopo il login (per arricchire i token con claim personalizzati), dopo la registrazione (per innescare workflow di onboarding), e altro ancora.

Come Funziona la Sandbox di Auris

Le Actions di Auris eseguono JavaScript personalizzato all’interno di un ambiente controllato usando il costruttore Function di JavaScript. Questo meccanismo crea una funzione da una stringa di codice con uno scope esplicito — il codice dell’action vede solo le variabili che Auris fornisce esplicitamente.

Pipeline di Esecuzione

Passo 1: Analisi Statica

Prima di eseguire qualsiasi codice, Auris scansiona il sorgente dell’action per pattern bloccati:

const BLOCKED_PATTERNS = [
  'require',       // Nessun caricamento di moduli
  'import',        // Nessun import ES module
  'process',       // Nessun accesso a process.env, process.exit, ecc.
  'global',        // Nessun accesso all'oggetto global
  'child_process', // Nessun avvio di sottoprocessi
  'fs',            // Nessun accesso al filesystem
]

Passo 2: Costruzione della Funzione

Il codice dell’action viene usato per costruire una funzione con context come unico parametro. La funzione risultante si comporta come:

// Concettualmente equivalente a:
function anonymous(context) {
  // Il codice dell'action viene eseguito qui
  // Può accedere SOLO a:
  //   - 'context' (l'argomento)
  //   - JavaScript built-in (Array, Object, String, Math, Date, JSON, ecc.)
  //   - fetch (fornito esplicitamente per HTTP outbound)
  //   - console (catturato, non stdout reale)
}

La proprietà critica: la funzione non ha closure sulle variabili del server. Non può accedere a require, process, connessioni al database, o qualsiasi altro stato lato server.

Passo 3: L’Oggetto Context

Il parametro context fornisce all’action informazioni sull’evento di autenticazione corrente:

interface ActionContext {
  user: {
    id: string
    email: string
    username: string
    roles: string[]
    metadata: Record<string, unknown>
  }
  request: {
    ip: string
    userAgent: string
    geoip?: { country: string; city: string }
  }
  tenant: { id: string; name: string }
  application: { id: string; clientId: string; name: string }
  trigger: string // 'pre_login' | 'post_login' | 'pre_signup' | 'post_signup' | ...
  fetch: typeof fetch   // HTTP outbound
  console: {            // Logging catturato (va su ActionLog, non su stdout)
    log: (...args: unknown[]) => void
    warn: (...args: unknown[]) => void
    error: (...args: unknown[]) => void
  }
}

Passo 4: Applicazione del Timeout

Ogni esecuzione di action è avvolta in un Promise.race() con un timeout configurabile (default 5 secondi). Se l’action non si risolve entro il timeout, viene trattata come un fallimento.

Passo 5: Elaborazione del Risultato

interface ActionResult {
  allow?: boolean                      // false = blocca il login/registrazione
  claims?: Record<string, unknown>     // Aggiunge claim personalizzati al JWT
  metadata?: Record<string, unknown>   // Aggiunge metadata al record utente
  reason?: string                      // Motivo di rifiuto leggibile (mostrato all'utente)
}

La Pipeline dei Trigger

Le Actions sono organizzate per trigger — il punto nel flusso di autenticazione dove vengono eseguite:

Esecuzione Sequenziale

Più actions possono essere registrate per lo stesso trigger. Vengono eseguite sequenzialmente nell’ordine definito dal campo order. Se un’action restituisce { allow: false }, le successive vengono saltate.

Se un’action lancia un’eccezione non gestita, il flusso viene bloccato per default (fail-secure). Questo previene che un’action rotta consenta accidentalmente accessi non autorizzati.

Il Modello di Sicurezza in Dettaglio

Cosa le Actions POSSONO Fare

Cosa le Actions NON POSSONO Fare

Caratteristiche di Performance

L’Editor Blueprint Visuale

Per i team che preferiscono la programmazione visuale rispetto alla scrittura di JavaScript, Auris fornisce un Blueprint Editor — un editor visuale basato su nodi.

Tipi di Nodo

L’Editor Blueprint mantiene una mappatura bidirezionale tra il grafo visuale e il codice JavaScript. Non tutto il JavaScript è rappresentabile nell’editor visuale — la logica complessa (loop, ricorsione, pattern async) richiede la modifica solo in codice.

Esempi di Codice: Pattern Action Comuni

Bloccare Provider Email Temporanei

// Trigger: pre_signup
const disposableDomains = [
  'tempmail.com', 'throwaway.email', 'guerrillamail.com',
  'mailinator.com', '10minutemail.com', 'yopmail.com'
]
 
const domain = context.user.email.split('@')[1]
 
if (disposableDomains.includes(domain)) {
  return {
    allow: false,
    reason: 'Gli indirizzi email temporanei non sono consentiti.'
  }
}
 
return { allow: true }

Arricchire il Token con Dati Esterni

// Trigger: post_login
try {
  const response = await context.fetch(
    'https://hr.internal/api/employee?email=' +
      encodeURIComponent(context.user.email),
    { headers: { 'X-Api-Key': 'hr-api-key' } }
  )
 
  if (response.ok) {
    const employee = await response.json()
    return {
      claims: {
        department: employee.department,
        manager_id: employee.managerId,
        cost_center: employee.costCenter
      }
    }
  }
} catch (err) {
  context.console.error('Chiamata API HR fallita:', err.message)
}
 
// Se l'API HR non risponde, non bloccare il login
return {}

Restrizione Geografica del Login

// Trigger: pre_login
const allowedCountries = ['US', 'CA', 'GB', 'DE', 'FR', 'IT', 'ES']
const country = context.request.geoip?.country
 
if (country && !allowedCountries.includes(country)) {
  context.console.warn('Login bloccato da', country, 'per utente', context.user.email)
  return {
    allow: false,
    reason: 'Il login non è disponibile dalla tua posizione attuale.'
  }
}
 
return { allow: true }

Concetti Correlati

• OAuth 2.0 & OIDC — I flussi di autenticazione a cui le Actions si agganciano
• Token Spiegati — Come i claim personalizzati delle Actions appaiono nei JWT
• MFA Adattivo & Risk Scoring — Il risk scoring può innescare MFA step-up, complementando le Actions
• Multi-Tenancy — Come l’isolamento dei tenant si applica alle Actions