Metadata-Version: 2.5
Name: orion-verify
Version: 0.6.0
Summary: ORION Model: self-hosted domain ownership verification and browser anti-abuse SDK
Project-URL: Homepage, https://pypi.org/project/orion-verify/
Project-URL: Documentation, https://pypi.org/project/orion-verify/
Author: ORION Model contributors
License-Expression: MIT
License-File: LICENSE
Keywords: anti-abuse,browser,domain-ownership,orion-model,privacy,self-hosted,starlette,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: dnspython<3,>=2.6
Requires-Dist: httpx<1,>=0.27
Requires-Dist: rich<15,>=13.9
Requires-Dist: sqlalchemy<3,>=2.0
Requires-Dist: starlette<1,>=0.40
Requires-Dist: uvicorn<1,>=0.30
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'postgres'
Description-Content-Type: text/markdown

# ORION Verify — Python package

**Current release: 0.6.0 alpha.** ORION is a self-hosted domain-ownership and browser anti-abuse service with a Python SDK and command-line tools. It is distributed through PyPI as `orion-verify` and imported as `orion_verify`. This version does not include a hosted account dashboard or require an ORION web account.

ORION raises the cost of automated abuse; proof-of-work does not prove that a visitor is human. The project has not had an independent security audit. Do not use it as the only access-control layer for payments, account recovery, sensitive data, or other high-risk actions.

## Install and start

```bash
python -m pip install --upgrade orion-verify==0.6.0
orion quick-start
```

`quick-start` creates a private `.env` only when one does not already exist, then starts the API at `127.0.0.1:8000`. It never overwrites an existing configuration. SQLite is the convenient local-development default; production needs durable shared storage behind HTTPS. A function-local SQLite file is not suitable for persistent state across serverless instances.

## CLI commands

```bash
orion quick-start --no-run
orion init
orion check --database
orion setup example.com
orion example.com --setup
orion connection-check
orion verify example.com
orion cleanup --retention-days 7
orion --get https://github.com/OWNER/REPO/tree/main/path/to/extension
orion --uninstall extension-name
```

`orion setup DOMAIN` (also `orion DOMAIN --setup`) reads public HTTPS HTML and inspects ORION widget markup. It does not modify a site, change DNS, install code, or check private server environment values.

## Actual server connection check

On your website backend, configure these server-only variables:

```text
ORION_VERIFY_URL=https://your-orion-api.example
ORION_SITE_KEY=or_pub_your_public_site_key
ORION_SERVER_SECRET=your_private_per_site_server_secret
```

Then execute `orion connection-check` on that server. It checks `/health` and calls `/v1/sitecheck` with the real private secret. A response is successful only when the HTTP status and JSON confirm a matching active key. Incorrect credentials, an inactive key, redirects, invalid JSON and network errors fail closed. The displayed key is masked and the private secret is never printed.

`ORION_MASTER_SECRET` and `ORION_ADMIN_SECRET` belong only on the ORION service host. Never put them in browser code or client-side environment variables. A browser event or token is not proof by itself: the website backend must redeem it through `/v1/siteverify` before granting access.

## Browser widget

After registering a domain and verifying DNS ownership, add this markup to the site:

```html
<div data-orion-verify></div>
<script defer src="https://your-orion-api.example/widget.js"
        data-api="https://your-orion-api.example"
        data-sitekey="or_pub_your_public_site_key"></script>
```

The public site key is not a secret. Admin endpoints require `X-ORION-Admin-Key` and a configured management-network allowlist. Publish the exact DNS TXT ownership proof before using a site key. The default limit is three active/pending site registrations per ORION service.

## Python SDK

```python
from orion_verify import VerifyClient

client = VerifyClient(
    base_url="https://your-orion-api.example",
    server_secret="YOUR_PRIVATE_SERVER_SECRET",
)
result = client.verify(token_from_your_request, site_key="or_pub_YOUR_SITE_KEY")
if result.success is not True:
    raise PermissionError("Verification required")
```

Use `connect_from_env()` for server-only variables, or `connection_status()` for masked connection diagnostics. Network failures and unexpected responses must be treated as failure.

## Security features and limitations

The API applies bounded JSON request bodies, security headers, origin checks, short-lived site-bound tokens, one-time token redemption, replay prevention and per-IP daily quotas. Forwarded IP headers are ignored unless the direct proxy is explicitly trusted. `/v1/sitecheck` checks an active site's private credentials without consuming a token; `/v1/siteverify` redeems a token.

The `--get` and `--uninstall` extension commands manage files only. They do not execute downloaded code or automatically install dependencies. Review extensions and their dependencies before running them; the file-type filter is not a malware scanner.

## License

MIT.
