Metadata-Version: 2.4
Name: Xorion-verify
Version: 0.1.0
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
Dynamic: license-file

# Xorion Verify

Xorion Verify is a self-hosted, zero-runtime-dependency ASGI middleware that displays an inline browser-check page, asks visitors to enter five generated words, rate-limits repeat requests, bounds verification POSTs to **1 MiB and 3 seconds**, and issues a short-lived, server-side-backed browser token.

> **Alpha software.** It has not received an independent security audit. It adds friction to some automated traffic; it does not prove a visitor is human and cannot stop a volumetric DDoS attack by itself.

## Install

    python -m pip install Xorion-verify

The package declares no runtime dependencies, imports no nh3, and uses no JavaScript CDN or tracking pixels.

## FastAPI / Starlette integration

    from fastapi import FastAPI
    from xorion_verify import XorionVerifyMiddleware

    app = FastAPI()
    app.add_middleware(
        XorionVerifyMiddleware,
        token_ttl=900,
        challenge_ttl=120,
        body_limit=1_048_576,
        verify_timeout=3.0,
        protected_paths=("/", "/dashboard", "/account"),
    )

Use HTTPS in production. The middleware intercepts HTML GET navigations, while subsequent requests in scope require a valid token. API routes are protected by default; add a path to bypass_paths only when it truly must be public. Configure protected_paths and bypass_paths for your application.

## How it works

1. The middleware returns a self-contained HTML/CSS/JS challenge page without external assets.
2. A visitor enters five random words. The browser also completes a small SHA-256 proof-of-work.
3. The server checks expiry, coarse browser-context binding, minimum submit time, answer, request size/time, same-origin status, and per-IP rate limits.
4. Success sets an HttpOnly, SameSite=Lax opaque token cookie. The opaque token is validated server-side on protected requests.

The default store is bounded and in-memory, per process. Challenges and tokens are lost on restart and are not shared among workers. Treat this as an alpha/local-evaluation implementation until a shared persistent store and operational controls have been added and reviewed.

## Extensions

Configure the repository that contains the trusted Extension folder, then pull an extension from Extension/name:

    export XORION_EXTENSION_REPOSITORY="OWNER/REPOSITORY"
    orion pull --extension my-extension

Or pass --repo OWNER/REPOSITORY. A branch or tag may be set through XORION_EXTENSION_REF or --ref. Files are downloaded through GitHub's API with path validation and strict size/type caps. The command does **not** execute or enable downloaded Python. Inspect the source first. Extensions are ordinary Python code, not sandboxes, and can access the privileges of the process that imports them.

## Security boundaries

- Use an edge proxy or WAF with upstream rate controls for network floods.
- In-memory quotas and tokens are per process and are not shared.
- IP and User-Agent binding is a coarse anti-replay signal and may create false positives when addresses change.
- Word challenges and proof-of-work can be automated; neither is proof of humanity or identity.
- Keep application authentication, authorization, CSRF defenses, and sensitive-action checks independent.
- Do not trust arbitrary forwarded-IP headers. Configure trusted proxy handling at your ASGI server.
- No independent security audit has been completed. Do not use this package as the only control for payments, account recovery, or sensitive data.

## Documentation

The separate documentation repository is <https://github.com/testfkij/orion-model>.
