2IZI Guard — Dokumentacja

Dla akcji aplikacji

Bezpieczeństwo to decyzja serwera, nie stan widgetu.

2IZI Guard chroni formularze i publiczne akcje przez lokalną ocenę ryzyka, adaptacyjne utrudnienie i jednorazowe tokeny autoryzacyjne serwera. Bez obowiązkowej zewnętrznej CAPTCHA.

PHP 8.1+Core runtime

MariaDB / MySQLBaseline storage

0required outbound runtime calls

256-bitopaque token entropy

PRE-1.0Obecny branch ma security-first architecture i automatyczne regression/red-team coverage. Najpierw Shadow Mode, potem enforcement kalibrowany na realnym ruchu.

Quick start

Mała powierzchnia integracji. Ostateczna zgoda pozostaje na serwerze.

Obecny core celuje w PHP 8.1+ i jest framework-independent na granicy bezpieczeństwa. Chroń każdą action jawnie i zużyj token przed operacją biznesową.

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

Chroniona actionPHP

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

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

Typowe actions

loginregisterpassword_resetcontactcheckoutfile_upload

Server authoritySukces JavaScript nie jest autoryzacją. Serwer weryfikuje i zużywa token Guard.

Jak działa

Jedna chroniona action. Pięć niezależnych punktów kontroli.

Przeglądarka może uczestniczyć w challenge, ale zgoda biznesowa zawsze jest wydawana i zużywana przez serwer.

Sprawdź kontekst

Origin, action, session i limity przed kosztowną pracą.

Oceń lokalnie

Sygnały serwera i aplikacji tworzą wyjaśnialną decyzję ryzyka.

Dodaj utrudnienie

Policy wybiera PASS, PoW, interaction, throttle lub deny.

Wydaj raz

Losowy 256-bit opaque token związany z session/action/origin i krótkim TTL.

Zużyj atomowo

Endpoint biznesowy zużywa raz; replay, mismatch i expiry są odrzucane.

Policy modes

ShadowObserve and predict; no enforcement.

InvisibleNo visible challenge.

AdaptiveRisk-based PASS / PoW / interaction / deny.

Always challengeRequire step-up for every protected request.

Zaufany ruch może przejść niewidocznie; większe ryzyko może uruchomić PoW, hold, throttle lub deny.

Integracja

Integration contract

Obecny core celuje w PHP 8.1+ i jest framework-independent na granicy bezpieczeństwa. Chroń każdą action jawnie i zużyj token przed operacją biznesową.

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

256-bit opaque token · tylko hash · krótki TTL · binding action/session/origin · HMAC integrity · one-time atomic consume · server-only business signals · fail-closed dla krytycznych actions.

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.

Model zagrożeń

Zakładamy, że atakujący zna cały kod.

Kod, JavaScript, API, schemat DB, PoW i progi mogą być znane; sekrety i autoryzacja pozostają po stronie serwera.

Zakładamy, że atakujący ma

pełny kod źródłowy
nowoczesne modele AI
Playwright / Selenium / headless Chromium
residential proxies
zapisy własnego ruchu

Bezpieczeństwo nie zależy od ukrywania

JavaScript
algorytmów challenge
nazw pól
endpointów
risk thresholds

Główne niezmienniki256-bit opaque token · tylko hash · krótki TTL · binding action/session/origin · HMAC integrity · one-time atomic consume · server-only business signals · fail-closed dla krytycznych actions.

Uczciwe ograniczenieŻadna browser challenge nie udowodni matematycznie „biologicznego człowieka”. Krytyczne actions nadal wymagają passkey/WebAuthn, MFA, verified account, autoryzacji transakcji i limitów biznesowych.

Open source

Publiczny kod powinien zwiększać audytowalność, a nie osłabiać model.

Czytanie implementacji nie może tworzyć authorization bypass. Publiczny review wymaga zdyscyplinowanych releases, keys, repository permissions i vulnerability handling.

Publikować

source i historia zmian
SECURITY.md i responsible disclosure
threat model i architektura
automatyczne security / red-team tests
release checksum i notes

Zachować prywatne

production config/guard.php
APP_KEY i HMAC/privacy/rate-limit keys
DB dumps i real security events
real cookies/tokens/sessions
deployment secrets i private infrastructure

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.

Aktualny stan

0.4.10 · pre-1.0 · aktywny rozwój

Obecny branch ma security-first architecture i automatyczne regression/red-team coverage. Najpierw Shadow Mode, potem enforcement kalibrowany na realnym ruchu.

PHP coreDostępny

Webasyst / Shop-Script adapterPo stabilizacji core

Verified agents / Privacy PassPrzyszłość / zależne od standardów

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.