apikee 0.1.2__tar.gz → 0.1.2.dev0__tar.gz

apikee-0.1.2.dev0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Default owners for everything in the repo.
+# Required for branch protection's "Require review from Code Owners".
+* @usmhic

apikee-0.1.2.dev0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Report a problem with the apikee Python package
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: false
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      placeholder: e.g. apikee==0.1.2 (or a .devN pre-release)
+    validations:
+      required: false
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      placeholder: Python version, optional extras installed (fast/server/fastapi/all), OS, etc.
+    validations:
+      required: false

apikee-0.1.2.dev0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & discussions
+    url: https://github.com/apikee-dev/python/discussions
+    about: Ask questions and discuss ideas with the community

apikee-0.1.2.dev0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Suggest an idea for the apikee Python package
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

apikee-0.1.2.dev0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Summary
+
+<!-- What does this PR do, and why? -->
+
+## Checklist
+
+- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) (e.g. `feat: ...`, `fix: ...`)
+- [ ] `pytest -q` and `python -m build` pass locally
+- [ ] Documentation updated (README, CONTRIBUTING.md) if needed

apikee-0.1.2.dev0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      pip-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

apikee-0.1.2.dev0/.github/workflows/release.yml

@@ -0,0 +1,196 @@
+name: python-cicd
+
+on:
+  pull_request:
+    paths:
+      - "apikee/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  push:
+    branches:
+      - main
+      - dev
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  validate:
+    name: Validate, Test, Package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[all]
+          pip install build twine pytest pytest-asyncio httpx
+
+      - name: Test
+        run: pytest -q
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check artifacts
+        run: twine check dist/*
+
+      - name: Upload package artifact (PR)
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-${{ github.event.pull_request.number }}
+          path: dist/*
+          if-no-files-found: error
+
+      - name: Dependency review (PR)
+        if: github.event_name == 'pull_request'
+        uses: actions/dependency-review-action@v4
+
+      - name: Vulnerability scan (Trivy)
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          format: table
+          severity: CRITICAL,HIGH
+          ignore-unfixed: true
+          exit-code: 1
+
+  pr-title:
+    name: PR Title (Conventional Commits)
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  release-please:
+    name: Release Please
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish-dev:
+    name: Publish Dev (dev)
+    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+    needs: validate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Compute next dev version
+        run: |
+          python - <<'PY'
+          import json, re, pathlib, urllib.request
+
+          text = pathlib.Path("pyproject.toml").read_text()
+          m = re.search(r'^version\s*=\s*"([^"]+)"', text, re.M)
+          if not m:
+              raise SystemExit("Could not find version in pyproject.toml")
+          base = re.sub(r"\.dev\d+$", "", m.group(1))
+
+          next_num = 0
+          try:
+              with urllib.request.urlopen("https://pypi.org/pypi/apikee/json", timeout=10) as r:
+                  releases = json.loads(r.read()).get("releases", {})
+              pat = re.compile(r"^" + re.escape(base) + r"\.dev(\d+)$")
+              nums = [int(mm.group(1)) for v in releases for mm in [pat.match(v)] if mm]
+              if nums:
+                  next_num = max(nums) + 1
+          except Exception:
+              pass
+
+          dev_version = f"{base}.dev{next_num}"
+          new_text = re.sub(r'^version\s*=\s*"[^"]+"', f'version = "{dev_version}"', text, count=1, flags=re.M)
+          pathlib.Path("pyproject.toml").write_text(new_text)
+          print(f"Dev version: {dev_version}")
+          PY
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check artifacts
+        run: twine check dist/*
+
+      - name: Publish dev to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  publish-release:
+    name: Publish Release (main)
+    needs: [validate, release-please]
+    if: |
+      needs.validate.result == 'success' &&
+      needs.release-please.result == 'success' &&
+      needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check artifacts
+        run: twine check dist/*
+
+      - name: Publish release to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

apikee-0.1.2.dev0/.gitignore

@@ -0,0 +1,32 @@
+# Python caches
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Build outputs
+dist/
+build/
+*.egg-info/
+
+# Coverage
+.coverage
+coverage.xml
+htmlcov/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+.vscode/
+.idea/

apikee-0.1.2.dev0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.2"
+}

apikee-0.1.2.dev0/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md — apikee Python
+
+This file orients AI coding agents (and humans) working in this repository.
+
+## What this project is
+
+`apikee` is an API key creation/validation plugin for Python — local-only by default
+(zero dependencies), with optional integrations for FastAPI, Flask, and Starlette/ASGI.
+It creates and verifies HMAC-signed API keys (`apikee_<claims>.<signature>`) carrying
+tenant, scopes, and expiry, and can optionally talk to a self-hosted Apikee server for
+key rotation, encrypted payloads (X25519 + AES-256-GCM), and RSA-signed requests. See
+[README.md](./README.md) for usage examples and environment variables.
+
+## Build, test, lint
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .[all]   # all extras: fast (msgpack), server (cryptography), fastapi
+pytest -q
+python -m build         # build sdist + wheel
+```
+
+There is no separate lint step configured.
+
+## Source layout
+
+```
+apikee/
+  __init__.py   Public API surface — Apikee, ApikeeClaims, get_apikee(), etc.
+  core.py       Apikee class — create()/verify()/protect(), config + env fallbacks
+  key.py        Local key encode/decode/HMAC verify, RSA request signing (zero I/O)
+  crypto.py     X25519 ECDH + AES-256-GCM encrypted channel for server mode
+  server.py     ApikeeServer — HTTP client for a self-hosted Apikee instance
+  fastapi.py    SecuredFastAPI, ApikeeDepends(), require_scope() for FastAPI
+  flask.py      init_apikee(), apikee_required, require_scope() for Flask
+tests/
+  test_apikee.py  Unit tests (pytest)
+  smoke.py        Smoke test for the installed package
+examples/
+  fastapi/      Todo API example using apikee.fastapi
+  flask/        Notes API example using apikee.flask
+  starlette/    Items API example using Apikee().middleware (ASGI)
+```
+
+## Conventions
+
+- **Local-only mode has zero runtime dependencies.** Optional extras
+  (`fast`/`server`/`fastapi`, see `pyproject.toml [project.optional-dependencies]`) are
+  required only for msgpack serialisation, the encrypted server channel, and FastAPI
+  integration respectively.
+- `Apikee(...)` and `init_apikee()`/`SecuredFastAPI()` are zero-config — all server-mode
+  and crypto options fall back to `APIKEE_*` environment variables when not passed
+  explicitly (see `core.py`'s module docstring for the full list).
+- Commit messages and PR titles follow [Conventional Commits](https://www.conventionalcommits.org/)
+  (`feat:`, `fix:`, `chore:`, `docs:`, `feat!:` for breaking changes).
+- Branching: `dev` is the integration branch; every push queries the PyPI JSON API for the
+  latest published `.devN` counter with the same base version, increments it, and publishes.
+  `main` is the stable branch. **release-please** owns `version` in `pyproject.toml` and
+  `CHANGELOG.md` — never hand-edit either.
+
+## Contribution process
+
+For the branch/PR workflow, release process, and required CI secrets and runtime
+environment variables, see [CONTRIBUTING.md](./CONTRIBUTING.md).

apikee-0.1.2.dev0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing — apikee Python
+
+Thanks for contributing! This guide covers the contribution workflow, branch
+and release process, and required secrets/environment variables.
+
+For build/test commands, project layout, and coding conventions, see
+[AGENTS.md](./AGENTS.md) — the same reference used by AI coding agents.
+
+## Local setup
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .[all]
+pytest -q
+python -m build
+```
+
+## Branch & PR flow
+
+| Branch | Purpose | On push |
+|---|---|---|
+| `dev` | integration branch — branch your work from here | publishes a `.devN` pre-release to PyPI (`pip install --pre apikee`) |
+| `main` | stable branch, protected | release-please opens/updates a release PR; merging it publishes the stable release |
+
+1. Branch from `dev`, naming it after the [Conventional Commits](https://www.conventionalcommits.org/)
+   type it corresponds to: `feature/<short-description>` (`feat:`), `fix/<short-description>`
+   (`fix:`), `chore/<short-description>` (`chore:`), `docs/<short-description>` (`docs:`).
+2. Open a PR into `dev` (or `main` for urgent hotfixes). CI runs the test suite, builds the
+   package, runs a dependency review, and scans for vulnerabilities (Trivy).
+3. **PR titles must follow Conventional Commits** (`type(scope?): description`) — a bot
+   checks this on open/edit. Examples: `feat: add async client support`, `fix(server):
+   correct signature verification`, `feat!: rename ApikeeClient constructor argument`
+   (the `!` marks a breaking change and triggers a major version bump).
+4. `main` and `dev` are protected branches — all changes land via a reviewed PR that
+   passes CI.
+
+## Releases
+
+Versioning and `CHANGELOG.md` are fully automated by
+[release-please](https://github.com/googleapis/release-please) from Conventional Commits
+PR titles — never hand-edit `version` in `pyproject.toml` or commit dev versions.
+
+- **Push to `dev`** → CI queries the PyPI JSON API for the latest published `.devN` version
+  with the same base (e.g. `0.1.2`), increments the counter by one, and publishes it to PyPI.
+  The first push for a new base starts at `0`. Install with `pip install --pre apikee`.
+- **Merging the release-please PR on `main`** → CI publishes the stable release to PyPI.
+  PEP 440 guarantees `1.0.0 > 1.0.0.devN`, so `pip install apikee` always resolves to
+  the stable release. No additional deprecation step is needed.
+
+## Secrets & environment
+
+### CI/CD secrets (GitHub Actions)
+
+| Secret | Used for | Notes |
+|---|---|---|
+| `GITHUB_TOKEN` | release-please, PR title check | auto-provided by GitHub Actions, no setup needed |
+| *(none)* | PyPI publish | uses PyPI Trusted Publishing (OIDC) via `id-token: write` — no secret to configure, but the `apikee` project on PyPI must have a Trusted Publisher set up for `apikee-dev/python` |
+
+### Runtime environment variables
+
+These configure the `apikee` package itself (used by the examples, tests, and any app
+that depends on it):
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `APIKEE_SECRET` | yes\* | HMAC signing secret(s) used for local key creation/verification |
+| `APIKEE_BASE_URL` | no | URL of a self-hosted Apikee instance — enables server mode |
+| `APIKEE_SERVER_KEY` | no | API key for the Apikee instance (server mode) |
+| `APIKEE_PROJECT_ENV` | no | project-env slug (server mode) |
+| `APIKEE_SERVER_PUBLIC_KEY` | no | X25519 public key (base64) — enables payload encryption |
+| `APIKEE_PRIVATE_KEY` | no | RSA private key (PEM) — signs server validation requests |
+
+\* Not required if you only use server mode (`APIKEE_BASE_URL` + `APIKEE_SERVER_KEY`),
+since the server validates keys remotely.
+
+For local development, create a `.env` file (gitignored) with at least:
+
+```env
+APIKEE_SECRET=replace-with-strong-random-secret
+```

{apikee-0.1.2 → apikee-0.1.2.dev0}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.4
 Name: apikee
-Version: 0.1.2
+Version: 0.1.2.dev0
 Summary: API key creation, validation & developer platform integration
-Project-URL: Homepage, https://apikee.dev
+Project-URL: Homepage, https://github.com/apikee-dev/python
 Project-URL: Repository, https://github.com/apikee-dev/python
-Project-URL: Documentation, https://apikee.dev/docs/python
 License: MIT
 License-File: LICENSE
 Keywords: api-key,authentication,middleware,security
@@ -14,6 +13,8 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.10
 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.10
@@ -42,17 +43,19 @@ API key plugin for Python — FastAPI, Flask, and Starlette.
 ```bash
 pip install apikee                # local mode, zero deps
 pip install "apikee[fastapi]"     # + FastAPI middleware
-pip install "apikee[server]"      # + encrypted server channel (apikee.dev)
+pip install "apikee[server]"      # + encrypted server channel
 pip install "apikee[all]"         # everything
+pip install --pre apikee          # latest dev pre-release
 ```
 
-## Configure (set 1 env var)
+## Configure
 
 ```bash
 export APIKEE_SECRET=$(openssl rand -hex 32)
 
-# Optional — enables server mode (usage tracking, rate limits, fraud detection)
-export APIKEE_SERVER_KEY=sk_live_...
+# Optional server mode — point to your self-hosted Apikee instance
+export APIKEE_BASE_URL=https://apikee.example.com/api/v1
+export APIKEE_SERVER_KEY=sk_...
 export APIKEE_PROJECT_ENV=my-api-production
 ```
 
@@ -121,24 +124,43 @@ export APIKEE_SECRET=new-secret        # new keys signed with this
 apikee = Apikee(secrets=["new-secret", "old-secret"])
 ```
 
-## Workflows
+## Environment Variables (.env)
 
-| Workflow | Trigger | Action |
-|----------|---------|--------|
-| `ci.yml` | push / PR | Lint + test matrix (Python 3.10–3.12 × 3 OS) |
-| `release.yml` | tag `v*.*.*` or manual | Build → PyPI → GitHub Release |
-| `version-bump.yml` | PR label or manual | Bump version, commit, push tag |
-| `hotfix.yml` | manual | Fast-track patch from main |
+Python frameworks (FastAPI, Flask, Starlette/ASGI) use the same variables.
 
-**Release:** `git tag v1.2.3 && git push --tags`
+Required:
 
-**Secrets needed** (repo → Settings → Secrets → Actions):
+```env
+APIKEE_SECRET=replace-with-strong-random-secret
+```
+
+Optional (server mode — requires a running Apikee instance):
+
+```env
+APIKEE_BASE_URL=https://apikee.example.com/api/v1
+APIKEE_SERVER_KEY=sk_...
+APIKEE_PROJECT_ENV=my-api-production
+APIKEE_SERVER_PUBLIC_KEY=base64-x25519-public-key   # enables payload encryption
+APIKEE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."  # enables RSA request signing
+```
+
+## Project structure
+
+```
+apikee/     Library source — core + framework modules (FastAPI, Flask, server)
+tests/      Test suite
+examples/   Example apps (FastAPI, Flask, Starlette)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, branch naming
+conventions, and the release process.
+
+## License
 
-| Secret | Notes |
-|--------|-------|
-| PyPI trusted publishing | Configure at pypi.org/manage/account/publishing — no token needed |
-| `PYPI_API_TOKEN` | Alternative to OIDC — uncomment in `release.yml` |
+[MIT](./LICENSE)
 
 ## Docs
 
-[apikee.com/docs](https://apikee.com/docs) · [apikee.dev](https://apikee.dev)
+[github.com/apikee-dev](https://github.com/apikee-dev)

{apikee-0.1.2 → apikee-0.1.2.dev0}/README.md

@@ -9,17 +9,19 @@ API key plugin for Python — FastAPI, Flask, and Starlette.
 ```bash
 pip install apikee                # local mode, zero deps
 pip install "apikee[fastapi]"     # + FastAPI middleware
-pip install "apikee[server]"      # + encrypted server channel (apikee.dev)
+pip install "apikee[server]"      # + encrypted server channel
 pip install "apikee[all]"         # everything
+pip install --pre apikee          # latest dev pre-release
 ```
 
-## Configure (set 1 env var)
+## Configure
 
 ```bash
 export APIKEE_SECRET=$(openssl rand -hex 32)
 
-# Optional — enables server mode (usage tracking, rate limits, fraud detection)
-export APIKEE_SERVER_KEY=sk_live_...
+# Optional server mode — point to your self-hosted Apikee instance
+export APIKEE_BASE_URL=https://apikee.example.com/api/v1
+export APIKEE_SERVER_KEY=sk_...
 export APIKEE_PROJECT_ENV=my-api-production
 ```
 
@@ -88,24 +90,43 @@ export APIKEE_SECRET=new-secret        # new keys signed with this
 apikee = Apikee(secrets=["new-secret", "old-secret"])
 ```
 
-## Workflows
+## Environment Variables (.env)
 
-| Workflow | Trigger | Action |
-|----------|---------|--------|
-| `ci.yml` | push / PR | Lint + test matrix (Python 3.10–3.12 × 3 OS) |
-| `release.yml` | tag `v*.*.*` or manual | Build → PyPI → GitHub Release |
-| `version-bump.yml` | PR label or manual | Bump version, commit, push tag |
-| `hotfix.yml` | manual | Fast-track patch from main |
+Python frameworks (FastAPI, Flask, Starlette/ASGI) use the same variables.
 
-**Release:** `git tag v1.2.3 && git push --tags`
+Required:
 
-**Secrets needed** (repo → Settings → Secrets → Actions):
+```env
+APIKEE_SECRET=replace-with-strong-random-secret
+```
+
+Optional (server mode — requires a running Apikee instance):
+
+```env
+APIKEE_BASE_URL=https://apikee.example.com/api/v1
+APIKEE_SERVER_KEY=sk_...
+APIKEE_PROJECT_ENV=my-api-production
+APIKEE_SERVER_PUBLIC_KEY=base64-x25519-public-key   # enables payload encryption
+APIKEE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."  # enables RSA request signing
+```
+
+## Project structure
+
+```
+apikee/     Library source — core + framework modules (FastAPI, Flask, server)
+tests/      Test suite
+examples/   Example apps (FastAPI, Flask, Starlette)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, branch naming
+conventions, and the release process.
+
+## License
 
-| Secret | Notes |
-|--------|-------|
-| PyPI trusted publishing | Configure at pypi.org/manage/account/publishing — no token needed |
-| `PYPI_API_TOKEN` | Alternative to OIDC — uncomment in `release.yml` |
+[MIT](./LICENSE)
 
 ## Docs
 
-[apikee.com/docs](https://apikee.com/docs) · [apikee.dev](https://apikee.dev)
+[github.com/apikee-dev](https://github.com/apikee-dev)