Panoramica

Gli URL personalizzati sono la primitiva centrale di Snapp.

Un URL in Snapp non è semplicemente una mappatura shortcode → redirect. È un’entità strutturata con:

  • proprietà
  • scope organizzativo
  • segretezza opzionale
  • regole di ciclo di vita
  • accesso basato su permessi
  • controlli di sicurezza in fase di creazione e di risoluzione

Tutti gli enforcement avvengono lato server.

Modello URL

Ogni URL accorciato è definito da:

  • un URL di destinazione (originalUrl)
  • uno shortcode opzionale
  • un utente proprietario
  • un’organizzazione proprietaria
  • team opzionali
  • tag opzionali
  • scadenza opzionale
  • segreto opzionale
  • stato runtime (attivo / disabilitato)
  • metriche accumulate

Gli URL sono sempre scoped a un’organizzazione, derivata dall’host attivo.

Flusso di creazione

Prerequisiti

Per creare un URL:

  • l’utente deve essere autenticato
  • l’host attivo deve essere riconosciuto
  • il contesto organizzativo deve essere risolvibile dall’host
  • i limiti di rate e quota devono consentire la creazione

Se vengono specificati dei team, l’utente deve avere il permesso create su almeno uno di essi.

Applicazione dei limiti

Durante la creazione, Snapp verifica:

  • maxSnappPerUser (per host)
  • l’abilitazione dei limiti a livello host

Se i limiti sono abilitati e superati, la creazione viene rifiutata.

Validazione dell’URL

Prima di persistere un URL:

  1. Il dominio di destinazione viene estratto
  2. Il dominio viene confrontato con la watchlist interna
  3. Il dominio viene validato tramite VirusTotal (se configurato)

Un URL viene rifiutato se:

  • il dominio è in blacklist
  • VirusTotal lo segnala come non sicuro
  • il controllo API fallisce

Questi controlli sono obbligatori e non possono essere aggirati lato client.

Gestione dello shortcode

  • Gli shortcode sono opzionali
  • Valori vuoti o composti solo da spazi vengono ignorati
  • Se omesso, lo shortcode viene generato automaticamente
  • Le collisioni sono gestite a livello di database
  • Gli shortcode sono unici per organizzazione, non globalmente

Scadenza

Gli URL possono definire una scadenza.

  • La scadenza è memorizzata come timestamp assoluto
  • Gli URL scaduti vengono automaticamente disabilitati in fase di risoluzione
  • Gli URL scaduti non vengono mai reindirizzati

Segreti (URL protetti)

Gli URL possono essere protetti da un segreto.

Comportamento:

  • Il segreto viene hashato prima della memorizzazione
  • Il valore originale non viene mai persistito
  • In fase di accesso, l’utente deve fornire il segreto
  • I tentativi falliti vengono loggati
  • Una validazione riuscita produce un redirect normale

Flusso di aggiornamento

L’aggiornamento di un URL applica controlli di proprietà o di permesso.

Un utente può aggiornare un URL se:

  • è il proprietario
  • è un admin
  • ha il permesso update su almeno uno dei team associati

I campi aggiornabili includono:

  • URL di destinazione
  • scadenza
  • segreto
  • tag
  • team
  • parametri UTM
  • stato attivo

Tutti gli aggiornamenti avvengono all’interno di una transazione.

Abilitazione / disabilitazione degli URL

Gli URL possono essere impostati come attivi o inattivi.

Regole:

  • i proprietari possono gestire i propri URL
  • gli admin possono gestire qualsiasi URL
  • i membri dei team richiedono il permesso update

Gli URL disabilitati:

  • non vengono reindirizzati
  • restituiscono uno stato disabilitato
  • vengono loggati come non trovati

Eliminazione

Gli URL possono essere eliminati in bulk.

Regole di eliminazione:

  • gli admin possono eliminare qualsiasi URL
  • i proprietari possono eliminare i propri URL
  • i membri dei team devono avere il permesso delete su tutti i team associati

Se non vengono trovati URL eliminabili, l’operazione viene annullata.

Flusso di risoluzione

Quando viene richiesto uno shortcode:

  1. Gli URL scaduti vengono disabilitati

  2. Il sistema tenta la risoluzione in ordine:

    • match specifico per organizzazione
    • fallback case-insensitive (se abilitato)
    • fallback globale (match più vecchio)

  3. Se non viene trovato alcun match, la richiesta viene loggata come non trovata

Fallback case-insensitive

Se disable.lowerCaseFallback è false:

  • xYz può risolvere xyz
  • la risoluzione è scoped all’organizzazione
  • i match esatti hanno sempre priorità

Se disabilitato, sono ammessi solo match esatti.

Risoluzione con segreto

Se un URL ha un segreto:

  • il redirect viene sospeso
  • all’utente viene mostrato un form per il segreto
  • il redirect avviene solo dopo una validazione riuscita

I segreti sono validati lato server tramite confronti a tempo costante.

Controlli di sicurezza a runtime

Prima del redirect:

  • il dominio di destinazione viene rivalidato
  • le regole di watchlist vengono riapplicate
  • VirusTotal viene interrogato nuovamente

Se un URL diventa non sicuro dopo la creazione, viene bloccato in fase di risoluzione.

Gestione degli UTM

Gli URL possono definire parametri UTM.

Durante il redirect:

  • gli UTM vengono iniettati nell’URL di destinazione
  • i parametri di query esistenti vengono preservati
  • l’ordine è deterministico

Gli UTM sono usati anche per l’aggregazione delle metriche.

Metriche e logging

Ogni tentativo di risoluzione viene loggato:

  • visite riuscite
  • segreti non validi
  • URL disabilitati
  • URL non trovati

Le metriche sono raccolte solo lato server.

Garanzie

  • La risoluzione degli URL è deterministica
  • I permessi sono applicati lato server
  • I segreti non sono mai memorizzati in chiaro
  • Gli URL non sicuri vengono bloccati anche dopo la creazione
  • I confini organizzativi non vengono mai superati

Note

  • Non esiste fiducia lato client

  • Tutti i controlli sono ripetibili e auditabili

  • Il comportamento degli URL può cambiare a runtime se:

    • cambia la configurazione
    • le integrazioni di sicurezza segnalano un dominio
    • l’URL scade