airelays 0.2.0__tar.gz

airelays-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and test dependencies
+        run: python -m pip install --upgrade pip && python -m pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest -q
+
+      - name: Byte-compile source and tests
+        run: python -m compileall src tests
+
+      - name: Build distribution artifacts
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*

airelays-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,58 @@
+name: Publish PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    environment:
+      name: pypi
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches project version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          python - <<'PY'
+          import os
+          import pathlib
+          import tomllib
+
+          payload = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+          version = payload["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if tag != expected:
+              raise SystemExit(f"Tag {tag!r} does not match project version {expected!r}.")
+          PY
+
+      - name: Install project and build tooling
+        run: python -m pip install --upgrade pip build twine -e .[dev]
+
+      - name: Run test suite
+        run: pytest -q
+
+      - name: Compile sources
+        run: python -m compileall src tests
+
+      - name: Build distribution artifacts
+        run: python -m build
+
+      - name: Verify distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

airelays-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+.DS_Store
+
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+
+.coverage
+coverage.xml
+htmlcov/
+
+.airelay/
+.openai-endpoint/
+logs/
+
+build/
+dist/
+*.egg-info/

airelays-0.2.0/ACKNOWLEDGEMENTS.md

@@ -0,0 +1,5 @@
+# Acknowledgements
+
+- The public Codex CLI repository informed the compatible login and auth-storage model reused here.
+- The observed subscription-backend behavior defined the current compatibility boundary.
+- AIRelay is an independent third-party project. Provider and product names are used only to describe compatibility and upstream behavior.

airelays-0.2.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0
+
+- Renamed the project surface to `AIRelay`, with package name `airelay` and CLI command `airelay`.
+- Added `airelay init`, `airelay status`, and `airelay token rotate` to make first-run setup and local token management explicit.
+- Added a local config file at `~/.config/airelay/config.toml` with `AIRELAY_*` overrides and legacy `OPENAI_ENDPOINT_*` fallback support.
+- Added default bearer-token protection for `/v1/*` and `/no-tools/v1/*`.
+- Added in-memory per-IP request rate limits, concurrent-request caps, and temporary blocks after repeated invalid tokens.
+- Added protected `GET /v1/relay/status` diagnostics and reduced public `GET /healthz` to a minimal liveness payload.
+- Added bounded local upload limits with explicit `413` failures instead of unbounded buffering.
+- Made bearer-token bootstrap explicit by default: `airelay init` creates the token, while `airelay serve` fails fast if bearer auth is enabled and no token is configured.
+- Clarified relay-token setup and client usage in the CLI output, startup banner, and user documentation.
+- Corrected auth readiness so API-key-only state is not reported as request-ready.
+- Moved upstream auth storage to AIRelay-owned state instead of reusing Codex-owned auth storage.
+- Removed `codex_home` from the public AIRelay configuration surface.
+- Added structured security events to the JSONL traffic log.
+- Updated the landing page, docs, and API guidance to use the AIRelay token as the client API key.
+- Added GitHub Actions workflows for CI and PyPI publishing preparation.

airelays-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code Of Conduct
+
+This project expects direct, respectful, and technically grounded collaboration.
+
+Participants should:
+
+- focus on evidence and reproducible behavior
+- avoid harassment, intimidation, and personal attacks
+- assume good faith while still challenging weak technical claims directly
+- keep security-sensitive details out of public discussion when responsible disclosure is warranted
+
+Maintainers may remove content or participation that undermines a safe and productive collaboration environment.

airelays-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Development Setup
+
+Contributor setup from a local checkout:
+
+```bash
+python -m pip install -e .[dev]
+pytest -q
+python -m compileall src tests
+```
+
+## Project Rules
+
+- preserve the explicit compatibility boundary
+- do not silently widen support claims
+- do not add truncation or hidden coercion for files, modalities, or token accounting
+- prefer explicit errors over compatibility theater
+- keep AIRelay auth storage independent from Codex or any other external tool state
+
+## Pull Request Expectations
+
+- include tests for behavioral changes
+- update docs when API behavior changes
+- update ADRs when a durable engineering rule changes

airelays-0.2.0/DISCLAIMER.md

@@ -0,0 +1,9 @@
+# Disclaimer
+
+AIRelay is an independent third-party project. It is not affiliated with, endorsed by, or sponsored by OpenAI or any other model provider.
+
+Provider and product names are used only to describe compatibility targets, client shapes, and upstream protocol behavior.
+
+AIRelay is designed for a single user operating a local relay for personal convenience. It is not presented as a shared, pooled, multi-user, or resale service.
+
+You are responsible for reviewing and complying with the terms, policies, and usage limits that apply to any upstream account or subscription you use with AIRelay.

airelays-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laurent-Philippe Albou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

airelays-0.2.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: airelays
+Version: 0.2.0
+Summary: AIRelay: an independent OpenAI-compatible local relay for single-user subscription-backed access.
+Author: Laurent-Philippe Albou
+License: MIT
+License-File: LICENSE
+Keywords: ai,gateway,openai-compatible,relay,subscription
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: keyring>=25.5.0
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: uvicorn>=0.35.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AIRelay
+
+`AIRelay` is an independent local OpenAI-compatible HTTP server backed by a ChatGPT subscription login that AIRelay stores independently. It exposes the verified OpenAI-shaped routes this upstream can support, protects the local relay with its own bearer token, and logs every transit to hourly JSONL files.
+
+`AIRelay` does not require a user-supplied OpenAI platform API key for upstream inference. Instead, it uses the same upstream ChatGPT login protocol that Codex uses while keeping AIRelay auth storage separate from Codex storage. Clients that call `AIRelay` should use the relay bearer token as the local client credential they present to AIRelay.
+
+## Independence And Intended Use
+
+- AIRelay is an independent third-party project. It is not affiliated with, endorsed by, or sponsored by OpenAI.
+- Provider and product names are used only to describe compatibility targets and upstream behavior.
+- AIRelay is designed for a single user running a local relay for personal convenience.
+- AIRelay is not presented as a shared, pooled, multi-user, or resale service.
+- You are responsible for complying with the terms and usage policies that apply to any upstream account or subscription you use with AIRelay.
+
+See [DISCLAIMER.md](DISCLAIMER.md) for the short project notice.
+
+## Quick Start
+
+```bash
+python -m pip install .
+airelay init
+airelay login
+airelay serve --port 8080
+```
+
+If you are installing from a published package instead of a source checkout, use `python -m pip install airelay`.
+
+Smoke test the public and protected surfaces:
+
+```bash
+curl http://127.0.0.1:8080/healthz
+curl http://127.0.0.1:8080/v1/relay/status \
+  -H 'authorization: Bearer YOUR_AIRELAY_TOKEN'
+```
+
+Inspect the resolved relay and upstream-auth state at any point:
+
+```bash
+airelay status
+```
+
+CLI status and setup commands default to readable terminal output. Use `--json` on `airelay init`, `airelay status`, `airelay logout`, `airelay token show`, or `airelay token rotate` when you need machine-readable output for automation.
+
+Point your client at:
+
+```text
+http://127.0.0.1:8080/v1
+```
+
+Use the token generated by `airelay init` as the client credential when you point an OpenAI-compatible SDK at AIRelay. Standard OpenAI SDKs will then send `Authorization: Bearer <relay-token>` automatically.
+
+If you want to provide the relay token yourself instead of using the default token file, launch the server with:
+
+```bash
+AIRELAY_BEARER_TOKEN='YOUR_AIRELAY_TOKEN' airelay serve --port 8080
+```
+
+or point AIRelay at a specific token file:
+
+```bash
+airelay serve --bearer-token-file /path/to/relay-token --port 8080
+```
+
+## What AIRelay Does
+
+- Uses the same upstream login protocol as Codex browser login and device-code login.
+- Stores upstream auth under AIRelay-owned state instead of reusing `~/.codex`.
+- Generates and persists a separate relay bearer token for client-to-relay access.
+- Protects `/v1/*` and `/no-tools/v1/*` with bearer auth, per-IP rate limits, concurrent-request caps, and temporary blocks after repeated bad tokens.
+- Exposes OpenAI-compatible routes for:
+  - `GET /v1/models`
+  - `GET /v1/subscription/status`
+  - `GET /v1/account/rate_limits`
+  - `POST /v1/completions`
+  - `POST /v1/responses`
+  - `POST /v1/chat/completions`
+  - `POST /v1/files`
+  - `GET /v1/files`
+  - `GET /v1/files/{file_id}`
+  - `GET /v1/files/{file_id}/content`
+  - `DELETE /v1/files/{file_id}`
+  - `POST /v1/conversations`
+  - `GET /v1/conversations/{conversation_id}`
+  - `POST /v1/conversations/{conversation_id}`
+  - `DELETE /v1/conversations/{conversation_id}`
+  - `/no-tools/v1/models`
+  - `/no-tools/v1/completions`
+  - `/no-tools/v1/responses`
+  - `/no-tools/v1/chat/completions`
+- Logs inbound requests, endpoint rejects, outbound responses, upstream requests, upstream responses, stream lines, and usage summaries to `logs/YYYY/MM/DD-HH.log`.
+
+## First-Run Flow
+
+1. `airelay init`
+   - writes `~/.config/airelay/config.toml` if it does not already exist
+   - creates `~/.airelay/relay-token` with `0600` permissions if a relay token is missing
+   - prints a formatted setup summary and reveals the token only when it was newly created
+2. `airelay login`
+   - creates an AIRelay-owned ChatGPT subscription session
+3. `airelay serve --port 8080`
+   - starts the protected local endpoint
+   - fails fast if bearer auth is enabled but no relay token is configured
+   - prints the client base URL, token file path, and the required `Authorization` header shape
+
+You can show the current relay token at any time:
+
+```bash
+airelay token show
+```
+
+You can also rotate the relay token later:
+
+```bash
+airelay token rotate
+```
+
+## Example Client Usage
+
+Python with the OpenAI SDK:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://127.0.0.1:8080/v1",
+    api_key="YOUR_AIRELAY_TOKEN",
+)
+
+response = client.responses.create(
+    model="gpt-5.4-mini",
+    input="Summarize the purpose of AIRelay.",
+)
+print(response.output_text)
+```
+
+Raw `curl`:
+
+```bash
+curl http://127.0.0.1:8080/v1/responses \
+  -H 'authorization: Bearer YOUR_AIRELAY_TOKEN' \
+  -H 'content-type: application/json' \
+  -d '{
+    "model": "gpt-5.4-mini",
+    "input": "Summarize the purpose of AIRelay.",
+    "stream": false
+  }'
+```
+
+Shell example with the OpenAI Python SDK environment variables:
+
+```bash
+export OPENAI_BASE_URL='http://127.0.0.1:8080/v1'
+export OPENAI_API_KEY="$(tr -d '\n' < ~/.airelay/relay-token)"
+```
+
+## Verified Compatibility Boundary
+
+This server is intentionally explicit about what is and is not verified.
+
+- Inference uses `https://chatgpt.com/backend-api/codex`.
+- Subscription status uses `https://chatgpt.com/backend-api/wham/usage`.
+- The upstream requires `stream=true`, so non-stream OpenAI responses are reconstructed locally from streamed event sequences.
+- The upstream requires `store=false`, so requests that try to enable upstream storage are rejected with `422`.
+- The upstream requires non-empty `instructions`, so the compatibility layer injects the minimal verified placeholder `"."` only when the caller omitted instructions entirely.
+- Image input is supported.
+- Text and JSON-like document input is supported by local inlining up to 1 MB.
+- Local file uploads are capped at 32 MiB each and 256 MiB total by default.
+- Audio input, embeddings, image generation, realtime sessions, and other unverified routes return explicit `501 unsupported_error`.
+
+## Security Defaults
+
+- Listener default: `127.0.0.1:8080`
+- Protected routes: `/v1/*` and `/no-tools/v1/*`
+- Public routes: `/` and a minimal `GET /healthz`
+- Protected diagnostics: `GET /v1/relay/status`
+- Relay auth: bearer token required by default
+- Token storage: `~/.airelay/relay-token`
+- Default rate limit: `120` requests/minute with burst `40`
+- Default concurrent request cap: `8` per IP
+- Default repeated-auth-failure block: `8` bad attempts in `300` seconds -> `900` second block
+
+See [Security](docs/security.md) for the full behavior.
+
+## Configuration
+
+AIRelay reads configuration in this order:
+
+1. explicit CLI flags such as `--config`, `--port`, or `--auth-storage`
+2. `AIRELAY_*` environment variables
+3. legacy `OPENAI_ENDPOINT_*` environment variables where supported as a migration fallback
+4. `~/.config/airelay/config.toml`
+5. built-in defaults
+
+`auth.storage = "auto"` prefers the AIRelay keyring namespace and falls back to `~/.airelay/auth.json` when keyring access is unavailable.
+
+Important paths:
+
+- config: `~/.config/airelay/config.toml`
+- data dir: `~/.airelay`
+- upstream auth fallback file: `~/.airelay/auth.json`
+- logs: `~/.airelay/logs`
+- relay token: `~/.airelay/relay-token`
+
+To override the default token source at launch time:
+
+- `AIRELAY_BEARER_TOKEN`
+- `airelay serve --bearer-token-file /path/to/relay-token`
+
+See [Configuration](docs/configuration.md) for field details and a sample config.
+
+## Publication Surface
+
+- package name: `airelay`
+- CLI command: `airelay`
+- legacy CLI alias kept for migration: `openai-endpoint`
+- Python package: `airelay`
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
+- [Security](docs/security.md)
+- [Disclaimer](DISCLAIMER.md)
+- [API Notes](docs/api.md)
+- [Architecture](docs/architecture.md)
+- [Subscription Status](docs/subscription-status.md)
+- [FAQ](docs/faq.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [ADR Index](docs/adr/README.md)