2IZI Guard — Documentazione

Per le azioni applicative

La sicurezza è una decisione del server, non lo stato di un widget.

2IZI Guard protegge moduli e azioni pubbliche con valutazione locale del rischio, frizione adattiva e token server monouso. Nessun runtime CAPTCHA esterno obbligatorio.

PHP 8.1+Core runtime

MariaDB / MySQLBaseline storage

0required outbound runtime calls

256-bitopaque token entropy

PRE-1.0Il branch attuale ha architettura security-first e coverage automatica regression/red-team. Prima Shadow Mode, poi enforcement calibrato su traffico reale.

Quick start

Superficie ridotta. Il permesso finale resta sul server.

Il core attuale punta a PHP 8.1+ ed è framework-independent al confine di sicurezza. Proteggi ogni action esplicitamente e consuma il token prima dell’operazione business.

1. Frontend

FrontendHTML

<script src="/guard/public/assets/guard.js?v=0.4.10" defer></script>
<form data-guard-action="contact">
  …
</form>

2. Protected action

Action protettaPHP

$result = Guard::verifyAndConsume(
    $_POST['guard_token'] ?? '',
    'contact'
);

if (!$result->allowed()) {
    http_response_code(403);
    exit;
}

Action tipiche

loginregisterpassword_resetcontactcheckoutfile_upload

Server authorityIl successo JavaScript non è mai autorizzazione. Il server verifica e consuma il token Guard.

Come funziona

Una action protetta. Cinque controlli indipendenti.

Il browser può partecipare alla challenge, ma il permesso business viene sempre emesso e consumato dal server.

Valida contesto

Controlla Origin, action, session e limiti base prima del lavoro costoso.

Valuta localmente

Segnali server e applicativi producono una decisione di rischio spiegabile.

Aggiunge friction

La policy sceglie PASS, PoW, interaction, throttle o deny.

Emette una volta

Token opaco casuale 256-bit legato a session/action/origin e TTL breve.

Consuma atomicamente

L’endpoint business consuma una volta; replay, mismatch e expiry vengono rifiutati.

Policy modes

ShadowObserve and predict; no enforcement.

InvisibleNo visible challenge.

AdaptiveRisk-based PASS / PoW / interaction / deny.

Always challengeRequire step-up for every protected request.

Traffico affidabile può passare in silenzio; rischio maggiore può attivare PoW, hold, throttle o deny.

Integrazione

Integration contract

Il core attuale punta a PHP 8.1+ ed è framework-independent al confine di sicurezza. Proteggi ogni action esplicitamente e consuma il token prima dell’operazione business.

Action registry

The server defines allowed action names. Never use a client-provided action as authorization context.

'contact' => [
  'mode' => 'adaptive',
  'fail_mode' => 'open_with_limit'
]

Origin / session binding

token opachi 256-bit · storage solo hash · TTL breve · binding action/session/origin · integrità HMAC · consume atomico singolo · segnali business solo server · fail-closed per action critiche.

UI isolation

Shadow DOM isolates Guard visuals from host CSS. It is a UI reliability layer, not a security boundary.

Localization

UI locale is BCP-47-style, UTF-8, RTL-ready, touch/keyboard compatible, and extendable with locale packs.

Modello di minaccia

Assumiamo che l’attaccante conosca tutto il codice.

Codice, JavaScript, API, schema DB, PoW e soglie possono essere noti. Segreti e autorizzazione restano server-side.

Assumiamo che l’attaccante abbia

codice sorgente completo
modelli AI moderni
Playwright / Selenium / headless Chromium
proxy residenziali
catture del proprio traffico

La sicurezza non dipende dal nascondere

JavaScript
algoritmi challenge
nomi campi
endpoint
risk threshold

Invarianti coretoken opachi 256-bit · storage solo hash · TTL breve · binding action/session/origin · integrità HMAC · consume atomico singolo · segnali business solo server · fail-closed per action critiche.

Limite dichiaratoNessuna challenge browser può provare matematicamente “umano biologico”. Le action critiche richiedono comunque passkey/WebAuthn, MFA, account verificati, autorizzazione transazioni e limiti business.

Open source

Il codice pubblico deve aumentare l’auditabilità, non indebolire il modello.

Leggere l’implementazione non deve creare bypass di autorizzazione. La review pubblica richiede release, chiavi, permessi repository e vulnerability handling disciplinati.

Pubblicare

sorgente e cronologia modifiche
SECURITY.md e responsible disclosure
threat model e architettura
test security / red-team automatici
checksum release e note

Tenere privato

production config/guard.php
APP_KEY e chiavi HMAC/privacy/rate-limit
dump DB e security events reali
cookie, token e sessioni reali
segreti deploy e infrastruttura privata

Operations

Diagnostics, tests and updates

Diagnostics

php bin/diagnose.php

Check database state, key material, Origin configuration and registered actions before enabling enforcement.

Regression / red-team

bash tests/run-all.sh

Release acceptance includes replay, proxy, risk, tampering, UI and integration checks. Run disposable MariaDB/MySQL concurrency tests where available.

Updates

Read release notes and migrations first. Do not overwrite production config/guard.php with a distribution template. Rotate keys only when a release explicitly requires it.

Rollout

Start with Shadow Mode, review predicted decisions and false positives, tune action policies, then enable calibrated enforcement.

Stato attuale

0.4.10 · pre-1.0 · sviluppo attivo

Il branch attuale ha architettura security-first e coverage automatica regression/red-team. Prima Shadow Mode, poi enforcement calibrato su traffico reale.

PHP coreDisponibile

Webasyst / Shop-Script adapterDopo stabilizzazione core

Verified agents / Privacy PassFuturo / dipende dagli standard

0.4.10The responsive-layout hotfix changes UI sizing and preview embedding only; database schema, token/challenge protocol, keys, risk engine and server authorization logic are unchanged.