orion-verify 0.5.0__tar.gz

orion_verify-0.5.0/.env.example

@@ -0,0 +1,16 @@
+# Use a unique 64-character hex secret in production: python -c "import secrets; print(secrets.token_hex(32))"
+ORION_DATABASE_URL=postgresql+psycopg://orion:CHANGE_TO_URL_SAFE_PASSWORD@127.0.0.1:5432/orion
+ORION_MASTER_SECRET=REPLACE_WITH_64_HEX_CHARACTERS
+ORION_ADMIN_SECRET=REPLACE_WITH_RANDOM_SECRET
+ORION_IP_DAILY_TOKEN_LIMIT=30
+ORION_IP_DAILY_CHALLENGE_LIMIT=120
+ORION_POW_DIFFICULTY_BITS=16
+ORION_CHALLENGE_TTL_SECONDS=120
+ORION_TOKEN_TTL_SECONDS=120
+ORION_MAX_ACTIVE_KEYS=3
+# Defaults to loopback-only. Add only trusted management IP/CIDR entries if needed.
+ORION_ADMIN_ALLOWED_CIDRS=127.0.0.1/32,::1/128
+# Leave empty unless a reverse proxy is explicitly trusted and overwrites/appends X-Forwarded-For safely.
+ORION_TRUSTED_PROXY_CIDRS=
+ORION_MAX_REQUEST_BYTES=16384
+ORION_DNS_TIMEOUT_SECONDS=3.0

orion_verify-0.5.0/.github/workflows/build-package.yml

@@ -0,0 +1,25 @@
+name: Build package
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v5
+        with:
+          name: orion-model-dist
+          path: dist/*
+          if-no-files-found: error

orion_verify-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: orion
+          POSTGRES_PASSWORD: test-password
+          POSTGRES_DB: orion
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U orion -d orion"
+          --health-interval 10s --health-timeout 5s --health-retries 5
+    env:
+      ORION_DATABASE_URL: postgresql+psycopg://orion:test-password@localhost:5432/orion
+      ORION_MASTER_SECRET: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+      ORION_ADMIN_SECRET: ci-only-admin-secret
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[test,postgres]' build twine
+      - run: python -m compileall -q src tests
+      - run: pytest -q
+      - run: python -m build
+      - run: python -m twine check dist/*

orion_verify-0.5.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,64 @@
+name: Publish to PyPI (manual release gate)
+on:
+  workflow_dispatch:
+    inputs:
+      version_tag:
+        description: Existing version tag to build, e.g. v0.5.0
+        required: true
+        type: string
+      confirm_publish:
+        description: Confirm that tests, package name, metadata, ownership proof and release review have passed
+        required: true
+        default: false
+        type: boolean
+permissions:
+  contents: read
+jobs:
+  build:
+    if: ${{ inputs.confirm_publish == true }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ inputs.version_tag }}
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Verify tag matches package version
+        env:
+          RELEASE_TAG: ${{ inputs.version_tag }}
+        run: |
+          python - <<'PY'
+          import os, tomllib
+          from pathlib import Path
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = "v" + version
+          actual = os.environ["RELEASE_TAG"].strip()
+          if actual != expected:
+              raise SystemExit(f"Tag {actual!r} does not match package version {expected!r}")
+          PY
+      - uses: actions/upload-artifact@v5
+        with:
+          name: orion-model-release-dist
+          path: dist/*
+          if-no-files-found: error
+  publish:
+    needs: build
+    if: ${{ inputs.confirm_publish == true }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/orion-verify/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: orion-model-release-dist
+          path: dist
+      # Configure the PyPI Trusted Publisher for owner testfkij, repository orion-model,
+      # workflow .github/workflows/publish-pypi.yml, and environment pypi first.
+      - uses: pypa/gh-action-pypi-publish@release/v1

orion_verify-0.5.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+
+# Local release/test logs and review artifacts
+.build-review/

orion_verify-0.5.0/ANNOUNCEMENT.md

@@ -0,0 +1,15 @@
+<!-- Docs reviewed: 2026-10-18; update this date and related docs with every code/security/API change. -->
+
+# Official announcement: ORION Model
+
+**ORION Verify is being rebranded as ORION Model.** The 0.5.0 alpha continues the same domain-ownership verification and browser anti-abuse project, with compatibility maintained for existing `orion-verify` Python installs, `orion_verify` imports, and command aliases during the transition.
+
+This update adds `orion-model verify DOMAIN` for DNS ownership feedback, dedicated client/server connection modules, and the canonical `Codes.md` codebook. Security hardening adds a separate daily challenge request limit, a configurable proof-of-work threshold, single-attempt challenges, safer request-body handling, and scheduled retention cleanup.
+
+## Security status
+
+ORION Model remains alpha software. This update is based on source review and automated local tests; it has **not** been independently audited and no public DDoS test was performed. Proof-of-work is not identity proof, and ORION Model must not replace your application's own authentication, authorization, CSRF protections, or account-creation checks. Run behind HTTPS, keep management endpoints private, separate the master key from each site's server secret, and configure edge rate limiting and monitoring.
+
+## Compatibility and release status
+
+The existing PyPI distribution name `orion-verify` is kept in this codebase for compatibility. PyPI does not rename an existing project by changing source metadata; a new `orion-model` distribution would need its name checked and reserved on the target index, with publishing permissions configured. Version 0.5.0 is prepared in source here; do not treat it as published until the package index confirms upload.

orion_verify-0.5.0/API_REFERENCE.md

@@ -0,0 +1,77 @@
+<!-- Docs reviewed: 2026-10-18; update this date and related docs with every code/security/API change. -->
+
+# HTTP API reference
+
+All request bodies are JSON objects. The API applies request-size limits and conservative response headers. Production deployments should use HTTPS.
+
+## Health
+
+GET /health
+
+Returns service status and version. Do not use this endpoint alone as a readiness check for database-dependent operations.
+
+## Public challenge
+
+POST /v1/challenges
+
+Request body:
+
+    {"site_key":"or_pub_YOUR_SITE_KEY"}
+
+The request Origin is checked against the active site's registered domain. A successful response includes challenge_id, nonce, and expires_in.
+
+## Submit proof
+
+POST /v1/verify
+
+Request body:
+
+    {"site_key":"or_pub_YOUR_SITE_KEY","challenge_id":"CHALLENGE_ID","proof":"12345"}
+
+The proof must be the value found by the widget. Challenges expire, are bound to a site and source-IP digest, and can be consumed only once. Successful responses contain a short-lived token.
+
+## Server-side redemption
+
+POST /v1/siteverify
+
+Headers:
+
+    Authorization: Bearer YOUR_PRIVATE_SERVER_SECRET
+    Content-Type: application/json
+
+Request body:
+
+    {"site_key":"or_pub_YOUR_SITE_KEY","token":"TOKEN_FROM_BROWSER"}
+
+A valid token returns {"success":true} once. A second redemption returns false. Keep the secret only on the server. Do not use browser-origin requests for this endpoint.
+
+## Management endpoints
+
+Management routes require both a valid X-ORION-Admin-Key and a client address inside ORION_ADMIN_ALLOWED_CIDRS.
+
+- POST /v1/admin/sites — register a domain and create pending DNS ownership proof.
+- POST /v1/admin/sites/verify — verify the DNS TXT proof and activate a site key.
+- POST /v1/admin/sites/revoke — disable a key and invalidate outstanding challenges and tokens.
+
+Management request bodies are deliberately limited to known fields. Keep these routes reachable only through a private management network.
+
+## Common response codes
+
+| Status | Meaning |
+|---|---|
+| 200 | Request accepted; inspect the JSON body for success details. |
+| 400 | Invalid body or verification request. |
+| 401 | Missing/invalid management or server credentials. |
+| 403 | Origin, ownership proof, or management network is not allowed. |
+| 413 | Request body is too large. |
+| 415 | JSON content type required. |
+| 422 | Body fields or field lengths are invalid. |
+| 429 | Quota or pending-challenge limit reached. |
+| 503 | A required service, such as DNS, is unavailable. |
+
+Error messages are intentionally generic for some failures. Do not expose secrets, tokens, or raw authorization headers in logs.
+
+
+### Challenge response additions (0.5.0)
+
+`POST /v1/challenges` returns `challenge_id`, `nonce`, `expires_in`, and `difficulty_bits`. A client should honor the advertised difficulty for compatibility, but the server's configured `ORION_POW_DIFFICULTY_BITS` is authoritative. Valid or invalid proof submissions consume that challenge; request a new challenge after any failed proof. Challenge issuance is independently limited by `ORION_IP_DAILY_CHALLENGE_LIMIT` (default 120 per source IP per UTC day), while successfully issued tokens are separately limited by `ORION_IP_DAILY_TOKEN_LIMIT` (default 30).

orion_verify-0.5.0/ARCHITECTURE.md

@@ -0,0 +1,49 @@
+<!-- Docs reviewed: 2026-10-18; update this date and related docs with every code/security/API change. -->
+
+# ORION Model architecture
+
+ORION Model is a self-hosted anti-abuse verification service. It is not an identity provider, CAPTCHA guarantee, account system, or replacement for application authorization.
+
+## Request flow
+
+1. An operator registers a site through the management API from a trusted network.
+2. The operator publishes the exact DNS TXT proof at _orion-verify.<domain>.
+3. The service resolves that record and activates the site key only when the proof matches.
+4. The public widget requests a short-lived challenge from the API.
+5. The browser solves the bounded proof-of-work challenge in a worker and submits the proof.
+6. The service issues a short-lived signed token after checking site state, origin, challenge expiry, single-use state, and quota.
+7. The application backend redeems the token with its private server secret. Redemption is single-use and site-bound.
+8. The application separately checks its own user session, CSRF token, permissions, rate limits, and business rules before performing a sensitive action.
+
+## Trust boundaries
+
+- **Browser:** untrusted. The public site key is not a secret. Browser events and client-side UI state never authorize a protected operation by themselves.
+- **Application backend:** owns user identity and authorization. It must never send the ORION server secret to the browser.
+- **ORION API:** validates challenge proofs and token redemption. Protect the management API with the admin secret and management-network allowlist.
+- **Database:** stores site records, challenge state, token redemption state, and hashed IP quota identifiers. Restrict network access and backups.
+- **Reverse proxy:** trusted only when its direct peer is explicitly listed in ORION_TRUSTED_PROXY_CIDRS. Do not accept arbitrary client-supplied forwarding headers.
+
+## Persistence
+
+SQLite is convenient for local development and tests. PostgreSQL is the recommended production database for multiple workers and concurrent requests. Configure backups, migrations, retention, monitoring, and restore tests before production use.
+
+## Operational controls
+
+- Keep .env, database files, logs, backups, and secrets out of Git.
+- Use HTTPS outside loopback development.
+- Use a unique high-entropy master and admin secret.
+- Keep management routes private; don't expose them to the public internet.
+- Apply request-size and timeout limits at both the application and reverse proxy.
+- Monitor 4xx/5xx rates, quota exhaustion, database availability, and DNS verification failures without logging tokens or secrets.
+- Run the full test suite and dependency/security checks before each release.
+
+## Current scope
+
+The repository includes the verification API, Python SDK, CLI, browser widget, a minimal integration demo, tests, and deployment examples. A multi-user hosted account portal is not currently part of the shipped API. Do not represent a static dashboard mockup as a working account system.
+
+
+## ORION Model 0.5.0 security changes
+
+Challenges are single-attempt: the database conditional update and commit consumes a challenge before the proof is evaluated. An invalid proof cannot be repeatedly tested against the same nonce. Daily challenge request counts are recorded atomically in the existing daily quota table with an additive `challenge_requests` column; the existing `issued` count remains dedicated to token issuance. Retention cleanup is outside the hot request path and should be scheduled with `orion cleanup`.
+
+The master signing key is held by the ORION Model service. Each registered site receives a separate one-time private server secret that is stored only by the associated application backend. Browser code receives only the public site key and one-time challenge token.

orion_verify-0.5.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+<!-- Docs reviewed: 2026-10-18; update this date and related docs with every code/security/API change. -->
+
+# Changelog
+
+## Unreleased — ORION Model security and extension update (2026-10-18)
+
+- Rebranded product docs to ORION Model while retaining the `orion-verify` distribution and `orion_verify` import namespace for compatibility.
+- Added `orion --get GITHUB_FOLDER_URL` and `orion --uninstall NAME` with explicit confirmation, bounded file types/size, source/owner/version/storage logs, and no automatic code execution or dependency installation.
+- Added a review-first anti-spam signal extension example and tests.
+- Updated security notes for privacy-preserving anti-abuse signals, DDoS defense-in-depth, extension supply-chain risk, and audit scope.
+- Fixed the demo test loader to avoid collision with Python’s standard-library `test` package and aligned the demo branding.
+- The release is not independently audited and is not published to PyPI merely because local metadata changes.
+
+## 0.5.0 — 2026-10-18 — ORION Model alpha hardening
+
+- Rebranded the product as ORION Model while retaining the `orion-verify` Python distribution/import name and old CLI aliases for compatibility.
+- Added `orion-model verify DOMAIN` for DNS ownership activation/status feedback on the service host.
+- Added `client_connect.widget_markup()` and `server_connect.connect_from_env()`; browser helpers accept only public site keys and server-side redemption uses a private per-site secret.
+- Increased the default proof-of-work difficulty to 16 bits and made the allowed difficulty configurable from 12–20 bits; server-side checks remain authoritative.
+- Added an independent atomic daily challenge-request quota (default 120 per IP), separate from the 30-token issuance quota.
+- Changed verification challenges to be consumed before proof validation, preventing repeated guesses against the same live nonce.
+- Moved expired-record cleanup out of public requests to `orion cleanup` maintenance to avoid unbounded work per challenge request.
+- Added an additive database migration, canonical `Codes.md` codebook, and release/security documentation updates.
+- Added tests for failed-proof challenge consumption, challenge quotas, connect-module input safety, and cleanup.
+
+## 0.4.0 — 2026-10-17
+
+- Added `orion` / `orion-verify` CLI aliases and `quick-start`, `init`, `check`, and `cleanup` commands.
+- Added DNS TXT ownership verification and key revocation; site keys remain inactive until verified.
+- Added origin-aware CORS, request body limits, JSON content-type enforcement, safe response headers, and server-to-server bearer auth.
+- Hardened SDK URL validation, TLS defaults, bounded timeouts, and redirect handling.
+- Made daily quota increments atomic on PostgreSQL and SQLite; added concurrent quota test coverage.
+- Added website integration codebook, security guidance, GitHub package-build workflow, and a gated manual PyPI workflow.
+- Disabled legacy alpha registrations during schema upgrade until they are re-registered and domain-verified.
+
+## 0.3.0 — Alpha
+
+- Initial self-hosted FastAPI/PostgreSQL verification service, widget, Python client, Docker Compose, and basic tests.

orion_verify-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+<!-- Docs reviewed: 2026-10-18; update this date and related docs with every code/security/API change. -->
+
+# Contributing
+
+Thanks for helping improve ORION Model. Security and correctness take priority over adding features.
+
+## Development setup
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[test]'
+python -m compileall -q src tests
+python -m pytest -q
+```
+
+PostgreSQL-backed CI runs through GitHub Actions. When changing persistence, quota enforcement, token signing, DNS ownership, or origin rules, add tests for both success and rejection cases and consider concurrency and transaction rollback behavior.
+
+## Pull requests
+
+- Keep changes focused and explain security consequences.
+- Do not commit `.env`, secrets, verification tokens, real site keys, database dumps, or private customer data.
+- Add/update README, `code.md`, `SECURITY.md`, and `CHANGELOG.md` when behavior changes.
+- Keep the Python SDK fail-closed on network errors; do not turn outages into successful verification.
+- Do not add invasive fingerprinting or claim proof-of-work proves humanity.
+- Make sure test workflows and package builds pass before requesting review.
+
+## Reporting security issues
+
+Follow the private reporting guidance in [`SECURITY.md`](SECURITY.md); do not publish exploit details before coordination.
+
+
+## Documentation is part of every change
+
+Update `README.md`, `Codes.md`, `API_REFERENCE.md`, `ARCHITECTURE.md`, `SECURITY.md`, `SECURITY_AUDIT.md`, `THREAT_MODEL.md`, `CHANGELOG.md`, and `RELEASE_CHECKLIST.md` whenever a code change affects their behavior or public API. A version bump must update `pyproject.toml`, `src/orion_verify/__init__.py`, package metadata in the health endpoint, tests, and release documentation together. Never claim an independent audit or a published package without evidence from the external reviewer/index.
+
+
+## Documentation maintenance
+
+When changing behavior, update README, Codes.md, API_REFERENCE.md, SECURITY.md, SECURITY_AUDIT.md, THREAT_MODEL.md, CHANGELOG.md, and ANNOUNCEMENT.md as applicable. Update the review date in each touched document. Never describe a local test run as an independent audit.