Metadata-Version: 2.4
Name: Xorion-verify
Version: 0.2.1
Summary: Self-hosted ASGI browser verification middleware with bounded request handling
Author: Xorion Verify contributors
License-Expression: MIT
Project-URL: Documentation, https://github.com/testfkij/orion-model
Project-URL: Source, https://github.com/testfkij/orion-model
Keywords: browser-verification,anti-abuse,asgi,rate-limit,security
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: rich<15,>=13.7
Dynamic: license-file

# Xorion Verify

Xorion Verify is an alpha self-hosted ASGI middleware package that makes some automated traffic more expensive and adds request-layer exploit-probe blocking. It is **not a drop-in replacement for Cloudflare**, a guarantee of human users, or a substitute for application authentication.

**Status:** alpha; not independently audited. Local source is now version 0.2.1-alpha. It has not been published to PyPI.

## Install and integrate

    python -m pip install Xorion-verify

The verification page is plain white/gray HTML, CSS and JavaScript with a standard system font. It uses no CDN, trackers, external image API or JavaScript service. Image-choice tiles are generated locally as inline SVG, so there is no site key or third-party request.

Example composition (outer security guard screens requests before the browser verification middleware):

    from fastapi import FastAPI
    from xorion_verify import ExploitGuardMiddleware, XorionVerifyMiddleware

    site = FastAPI()
    # Register your routes on site first.
    verified_site = XorionVerifyMiddleware(
        site,
        token_ttl=900,
        challenge_ttl=120,
        body_limit=1_048_576,
        verify_timeout=3.0,
        protected_paths=("/", "/dashboard", "/account"),
    )
    app = ExploitGuardMiddleware(
        verified_site,
        rate_limit=(120, 60),
        max_concurrent_requests=64,
        max_body_bytes=1_048_576,
        body_read_timeout=5.0,
        waf_mode="block",
        inspect_body=False,
    )

Use HTTPS in production. Configure bypasses for large uploads, streaming routes, webhooks, health checks, and static resources as needed; do not bypass routes without understanding the risk. Keep application authentication, authorization, CSRF protection, and validation independently.

## Browser verification

The interstitial performs browser capability checks (secure context, Web Crypto, Fetch API, same-origin endpoint, automation signal), a SHA-256 proof-of-work, and three challenge steps:

1. Enter five randomly generated words.
2. Type a six-character code exactly, including uppercase, lowercase, and numbers (example format: ASDv8T).
3. Select every locally generated image tile matching a requested shape.

The server validates same-origin Origin, content type, available Fetch Metadata, challenge expiry and single-use state, browser binding, submission timing, the exact case-sensitive code, image tile selection, words, proof-of-work, per-client attempt limits, body size and timeout. Success issues an opaque short-lived HttpOnly SameSite cookie. This is friction and risk scoring, not proof that a visitor is human; sophisticated automation can solve visual and text challenges.

The built-in image tiles are a simple zero-dependency interaction, **not a professional CAPTCHA**. For a stronger accessibility-aware CAPTCHA, optionally integrate a maintained service yourself and validate its token server-side; credentials must stay on the server.

## Request protection and exploit detection

ExploitGuardMiddleware provides:

- Bounded concurrent request admission (default 64 active requests per process).
- Per-IP token-bucket limits (default 120/minute) with optional path-specific limits.
- Request target/header caps, duplicate/conflicting Content-Length checks, transfer framing sanity checks, a 1 MiB default body cap, and a total body-read deadline.
- IP/CIDR denylists and allowlists; forwarded client IP is trusted only when the peer matches an explicitly configured trusted proxy.
- Versioned built-in signatures for common scanner probes, exposed secrets, path traversal, XSS, SQL injection, template/JNDI injection, command injection, PHP execution, serialization probes, and scanner user agents.
- Up to three rounds of URL decoding to catch common encoded signatures. Optional bounded body scan via inspect_body=True.
- A stable pattern_version, rule IDs, request IDs, privacy-reduced IP prefix, and structured security logs/audit hook for blocked or suspicious requests.
- Response hardening headers, including HSTS on HTTPS.

The rule identifiers are deliberately stable so attempts matching signatures can be correlated in logs even after the application bug has been fixed. This is a secondary guardrail: it does not patch vulnerable code, detect every exploit variant, or guarantee that a repeated attempt will be recognized. Keep software and dependencies patched. Built-in signatures may cause false positives; validate routes and tune in staging before broad production blocking.

### Basic configuration

    app = ExploitGuardMiddleware(
        app,
        rate_limit=(120, 60),
        path_rate_limits={"/login": (10, 60), "/.well-known/xorion/verify": (12, 60)},
        max_concurrent_requests=64,
        max_body_bytes=1_048_576,
        body_read_timeout=5.0,
        max_target_bytes=8192,
        max_header_count=100,
        max_header_bytes=32768,
        waf_mode="block",        # "log" to observe first; "off" to disable signatures
        inspect_body=False,      # opt in only for APIs where body scanning is appropriate
        trusted_proxies=(),      # set only to networks of proxies you operate
        deny_ips=(),
    )

You can provide named custom_patterns=[("rule-id", r"pattern")]. Custom regular expressions must be trusted and reviewed for expensive backtracking. Do not treat an in-process pattern list as an automatically updated threat-intelligence service. Update the package through reviewed releases.

## DDoS and scaling limits

These controls help with some application-layer floods but cannot absorb network/transport volumetric DDoS, SYN floods, or traffic that saturates the network before Python receives it. The counters and verification state are process-local, reset on restart, and are not synchronized between workers or hosts. For exposed production sites, use a reputable edge/CDN/WAF with DDoS capacity and shared atomic rate limits (for example Redis) in front of the app. Set server/proxy connection and header timeouts too.

The request middleware buffers request bodies up to the configured maximum to enforce streaming limits and replay them to the app. Keep the limit suitable for your endpoints and bypass or separately handle large uploads, streaming requests, and long-lived connections. The challenge page's generated symbols are easy for sufficiently capable bots to classify; do not use this alpha build as the only control for payments, account recovery or sensitive data.

## Extensions

Extension source is pinned to testfkij/orion-model/Extension/<name> on GitHub. The repo is private, so the CLI requires authorized read access and a GITHUB_TOKEN with read-only Contents permission.

    orion pull --extension sample_policy
    orion extensions list
    orion extensions uninstall sample_policy

Downloaded Python is not automatically imported or executed. Extensions are still ordinary Python code, not sandboxes; explicitly importing one executes it with the current process privileges.

## Release and security status

Local source was updated but is not published merely by changing files. Run tests, review diffs, build the wheel and sdist, inspect package contents, perform false-positive checks and independent security review before a production release. No claim of a 80% security effectiveness rating is made. Feature coverage percentages depend on the features selected and are not a security measurement.

Documentation repository: https://github.com/testfkij/orion-model


## Repeated exploit-probe detection

By default, five matching exploit probes from the same peer within five minutes trigger a 15-minute in-memory quarantine for that IP. The transition is logged with a stable rule ID and pattern version. Configure repeat_probe_threshold, repeat_probe_window and repeat_probe_block_seconds to tune this behavior after staging tests. Storage is bounded and process-local.

Reviewed custom WAF signatures can be updated at runtime through trusted code using guard.update_patterns([("new-rule-id", "pattern")], version="reviewed-2026-10"). This preserves built-in signatures and changes the version in security events. Only load reviewed rules; Xorion does not auto-download unsigned threat patterns.


**Reverse-proxy TLS note:** when TLS terminates before the ASGI app and the internal ASGI scope reports HTTP, configure `cookie_secure=True` on `XorionVerifyMiddleware` so the verification cookie remains Secure. Only configure trusted proxy IP ranges you control.
