Skip to Content

Licenze Software

Auris Licensing ti permette di proteggere il tuo software con chiavi di licenza — validazione online, fallback offline, gating delle funzionalità, limiti su postazioni e dispositivi, e automazione dell’emissione chiavi da Stripe o PayPal.

Questa guida ti accompagna attraverso il flusso completo: creare una policy, emettere una chiave e validarla nella tua app.

Come Funziona

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Auris Console  │     │   Auris API     │     │   Your App      │
│  (Admin UI)     │     │   (Backend)     │     │   (Desktop/Web) │
├─────────────────┤     ├─────────────────┤     ├─────────────────┤
│ Create Policy   │────▶│ Store policy    │     │                 │
│ Issue Key       │────▶│ Generate key    │     │                 │
│                 │     │ + JWT token     │     │                 │
│                 │     │                 │◀────│ validateLicense()│
│                 │     │ Check validity  │────▶│ ✓ or ✗          │
│                 │     │                 │◀────│ activateLicense()│
│                 │     │ Register device │────▶│ Device saved    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Tre modalità di validazione:

ModalitàCome funzionaIdeale per
OnlineOgni controllo interroga l’APISaaS, web app, sempre connesse
HybridPrima online, fallback JWT se offlineApp desktop, connettività intermittente
OfflineSolo JWT, nessuna rete necessariaAmbienti air-gapped, embedded, dispositivi sul campo

Guida Rapida

Crea una Policy

Nella Console Auris, vai su Licensing → Policies → New Policy.

Configura:

  • Name: Vigilante Pro
  • Slug: vigilante-pro
  • Validation Mode: Hybrid
  • Dimensions: Abilita postazioni (max 3), dispositivi (max 2), scadenza (365 giorni)
  • Features: threat-intel, vuln-scan, api-access
  • Key Format: Prefisso VIG, 4 segmenti × 4 caratteri, Base32

Emetti una Chiave

Vai su Licensing → Keys → Issue Key, seleziona la policy e inserisci le informazioni del licenziatario. Otterrai una chiave come:

VIG-A8BC-D3EF-G4HJ-K5LM

Installa l’SDK

npm install @auris/js

Valida nella Tua App

import { validateLicense } from '@auris/js'
 
const result = await validateLicense('VIG-A8BC-D3EF-G4HJ-K5LM', 'auth.yourdomain.com')
 
if (result.valid) {
  console.log('License is valid!')
  console.log('Features:', result.features)   // ['threat-intel', 'vuln-scan', 'api-access']
  console.log('Seats:', result.seats)          // { used: 1, max: 3 }
  console.log('Expires:', result.expiresAt)    // '2027-03-15T00:00:00Z'
} else {
  console.log('Invalid:', result.reason)       // 'EXPIRED', 'REVOKED', etc.
}

Ecco fatto. Una singola chiamata di funzione.

Integrazione App Desktop

Per le app desktop (Electron, Tauri, ecc.), tipicamente vorrai l’attivazione del dispositivo e il fallback offline.

Esempio Completo

import {
  validateLicense,
  validateLicenseJwt,
  activateLicense,
  deactivateLicense,
} from '@auris/js'
 
const DOMAIN = 'auth.yourdomain.com'
 
// ── Step 1: Activation (first launch) ────────────────────────
// The user enters their license key. You register the device.
 
async function activate(key: string) {
  const fingerprint = getDeviceFingerprint() // e.g. machine UUID
  await activateLicense(key, DOMAIN, fingerprint, os.hostname())
 
  // Save key locally for future launches
  store.set('licenseKey', key)
}
 
// ── Step 2: Validation (every launch) ────────────────────────
// Check the license. Online if possible, offline fallback.
 
async function checkLicense(): Promise<boolean> {
  const key = store.get('licenseKey')
  if (!key) return false
 
  const result = await validateLicense(key, DOMAIN)
 
  // Online validation succeeded
  if (result.valid) {
    // Cache the JWT for offline use
    if (result.jwtToken) store.set('licenseJwt', result.jwtToken)
    return true
  }
 
  // Network error — try offline
  if (result.reason === 'NETWORK_ERROR') {
    const jwt = store.get('licenseJwt')
    if (jwt) {
      const offline = await validateLicenseJwt(jwt, DOMAIN)
      return offline.valid
    }
  }
 
  return false
}
 
// ── Step 3: Feature gating ───────────────────────────────────
 
async function hasFeature(feature: string): Promise<boolean> {
  const result = await validateLicense(store.get('licenseKey')!, DOMAIN)
  return result.valid && (result.features?.includes(feature) ?? false)
}
 
// ── Step 4: Deactivation (uninstall / sign out) ──────────────
 
async function deactivate() {
  const key = store.get('licenseKey')
  if (key) {
    await deactivateLicense(key, DOMAIN, getDeviceFingerprint())
    store.delete('licenseKey')
    store.delete('licenseJwt')
  }
}

Il fallback offline funziona perché ogni chiave di licenza ha un token JWT associato che contiene i diritti (funzionalità, postazioni, scadenza) firmati da Auris. L’SDK valida la firma JWT e controlla la lista di revoca localmente. Il periodo di grazia (configurabile per policy, predefinito 7 giorni) determina per quanto tempo la validazione offline rimane valida.

Integrazione Web App

Per le web app sempre online, ti basta validateLicense:

import { validateLicense } from '@auris/js'
 
// Middleware or API route
export async function checkLicense(licenseKey: string) {
  const result = await validateLicense(licenseKey, 'auth.yourdomain.com')
  if (!result.valid) throw new Error(`License invalid: ${result.reason}`)
  return result
}

Integrazione React

Usa @auris/react per il controllo delle licenze basato su hook:

import { useAuris } from '@auris/react'
import { validateLicense } from '@auris/js'
import { useQuery } from '@tanstack/react-query'
 
function useLicense(key: string) {
  const { domain } = useAuris()
  return useQuery({
    queryKey: ['license', key],
    queryFn: () => validateLicense(key, domain),
    staleTime: 5 * 60 * 1000, // cache for 5 minutes
  })
}
 
function ProFeature({ children }: { children: React.ReactNode }) {
  const { data } = useLicense(userLicenseKey)
 
  if (!data?.valid) return <UpgradePrompt />
  if (!data.features?.includes('pro-feature')) return <UpgradePrompt />
 
  return <>{children}</>
}

Automatizzare l’Emissione delle Chiavi

Invece di emettere le chiavi manualmente, collega Stripe o PayPal per emetterle automaticamente al pagamento.

Crea una Regola di Automazione

Nella Console, vai su Licensing → Automation → New Rule:

  • Provider: Stripe
  • Trigger: checkout.session.completed
  • Action: issue_key
  • Linked Policy: Vigilante Pro

Configura il Webhook

Nella Dashboard di Stripe, aggiungi un endpoint webhook:

https://auth.yourdomain.com/api/licensing/webhooks/stripe

Eventi da ascoltare: checkout.session.completed

Imposta STRIPE_LICENSING_WEBHOOK_SECRET nel tuo ambiente API Auris.

Fatto

Quando un cliente completa il checkout, Auris emette automaticamente una chiave sotto la policy collegata. La chiave è disponibile tramite l’API e può essere inviata al cliente via email o mostrata nella tua app.

Pattern di Feature Gating

Flag di Funzionalità Booleani

const result = await validateLicense(key, domain)
 
const canExport = result.features?.includes('export') ?? false
const canUseApi = result.features?.includes('api-access') ?? false

Accesso a Livelli

// Define tiers as policies with different feature sets
// Free:  ['basic']
// Pro:   ['basic', 'analytics', 'export']
// Enterprise: ['basic', 'analytics', 'export', 'api-access', 'sso']
 
function getTier(features: string[]): 'free' | 'pro' | 'enterprise' {
  if (features.includes('sso')) return 'enterprise'
  if (features.includes('analytics')) return 'pro'
  return 'free'
}

Applicazione Limite Postazioni

const result = await validateLicense(key, domain)
 
if (result.seats && result.seats.used >= (result.seats.max ?? Infinity)) {
  throw new Error('Seat limit reached. Please upgrade your plan.')
}

Tracciamento Utilizzo

Traccia l’utilizzo a consumo (chiamate API, storage, ecc.) per una chiave:

import { recordLicenseUsage, getLicenseUsage } from '@auris/js'
 
// Record usage
await recordLicenseUsage(key, domain, 'api_calls', 1)
 
// Check usage
const usage = await getLicenseUsage(key, domain)
// { api_calls: { used: 142, max: 1000, period: 'month', resetsAt: '2026-04-01' } }

Riferimento SDK

Tutte le funzioni di licensing sono esportate da @auris/js:

FunzioneDescrizione
validateLicense(key, domain)Validazione online — restituisce validità, funzionalità, postazioni, dispositivi, scadenza
validateLicenseJwt(jwt, domain)Validazione offline — controlla scadenza JWT + lista di revoca
activateLicense(key, domain, fingerprint, name?)Registra un dispositivo
deactivateLicense(key, domain, fingerprint)Rimuovi un dispositivo
recordLicenseUsage(key, domain, metric, amount?)Traccia utilizzo a consumo
getLicenseUsage(key, domain)Ottieni l’utilizzo corrente per una chiave
refreshRevocationList(domain)Aggiorna manualmente la cache di revoca offline

Consulta il riferimento completo del JavaScript SDK e il riferimento API Licenze per i dettagli.

Architettura