keyshield 2.0.0__tar.gz

keyshield-2.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

keyshield-2.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

keyshield-2.0.0/.github/workflows/develop.yml

@@ -0,0 +1,107 @@
+name: Development Workflow
+
+on:
+  pull_request:
+    branches: [ development ]
+  push:
+    branches: [ development ]
+  # Allow this workflow to be called by other workflows
+  workflow_call:
+
+permissions:
+  contents: read
+  checks: none
+  pull-requests: none
+
+jobs:
+  lint:
+    name: Lint / Format / Type-check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up UV
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.14'
+
+      - name: Cache UV
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-3.14-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-3.14-
+
+      - name: Sync dev dependencies
+        run: uv sync --locked --all-extras --dev --no-progress -q
+
+      - name: Lint / Format / Type-check
+        run: make lint
+
+  tests:
+    name: Run tests (matrix)
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: [ '3.9', '3.10', '3.11', '3.12', '3.13', '3.14' ]
+      fail-fast: false
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up UV
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache UV
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ matrix.python-version }}-
+
+      - name: Sync dev dependencies
+        run: uv sync --locked --all-extras --dev --no-progress -q
+
+      - name: Run tests
+        run: uv run pytest
+
+  codecov:
+    name: Upload saved coverage to Codecov
+    runs-on: ubuntu-latest
+    needs: tests
+    steps:
+      # Codecov needs the full history to map commits correctly
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up UV
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache UV
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-3.14-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-3.14-
+
+      - name: Sync dev dependencies
+        run: uv sync --locked --all-extras --dev --no-progress -q
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

keyshield-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: CI & Publish (PyPI + Release)
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+    tags:
+      - '*'
+permissions:
+  contents: write     # For creating the release
+  id-token: write     # Required for PyPI Trusted Publisher
+  actions: read
+
+jobs:
+  dev:
+    name: Development Checks
+    uses: ./.github/workflows/develop.yml
+    secrets: inherit
+
+  publish:
+    needs: dev
+    name: Publish to PyPI & Create GitHub Release
+    runs-on: ubuntu-latest
+
+    # Runs only if on a version tag (e.g., refs/tags/1.2.3)
+    # Runs only when code is pushed to main (not on PRs)
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - name: Checkout (full history for changelog/tools)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up UV (publish runtime)
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+
+      - name: Sync dev dependencies
+        run: uv sync --locked --all-extras --dev --no-progress -q
+
+      - name: Build sdist & wheel with uv
+        run: uv build
+
+      # Publication via OIDC (Trusted Publisher) – no secret required on GitHub side
+      - name: Publish to PyPI
+        run: uv publish --verbose
+
+      # GitHub Release with auto notes + attached artifacts (sdist/wheel)
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+
+  docs:
+    name: Deploy MkDocs
+    runs-on: ubuntu-latest
+    needs: publish
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up UV
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev --no-progress -q
+
+      - name: Deploy MkDocs
+        run: uv run mkdocs gh-deploy --force

keyshield-2.0.0/.gitignore

@@ -0,0 +1,253 @@
+### PyCharm+all template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+junit.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Examples generated database files
+examples/*.sqlite3
+
+# Keep personal TODO list file
+TODO.md
+todo.md
+
+# Keep AI assistant conversation history
+CLAUDE.md

keyshield-2.0.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.8.3
+    hooks:
+      # Check the commit message when committing
+      - id: commitizen
+        stages: [commit-msg]
+
+      # Check all commits before pushing (optional but recommended)
+      - id: commitizen-branch
+        stages: [pre-push]
+
+  # Local hooks for linting and testing
+  - repo: local
+    hooks:
+      # Lint
+      - id: uv-lint
+        name: "Run linters and formatters"
+        entry: uv run lint
+        language: system           # we leave the binary as is
+        pass_filenames: false      # « uv run lint » don't need filenames
+        stages: [pre-commit]
+
+      # Tests
+      - id: uv-test
+        name: "Run tests"
+        entry: uv run test
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]

keyshield-2.0.0/.python-version

@@ -0,0 +1 @@
+3.14

keyshield-2.0.0/AGENTS.md

@@ -0,0 +1,145 @@
+# AGENTS.md
+
+This file guides automated coding agents working in this repository.
+Follow existing patterns and run the same tooling as humans.
+
+## Project overview
+
+- Language: Python 3.9+
+- Package: `keyshield` (src layout)
+- Async-first services and repositories
+- Optional extras for FastAPI, SQLAlchemy, Argon2, bcrypt, aiocache
+
+## Tooling and environment
+
+- Dependency manager: `uv`
+- Build backend: `hatchling`
+- Format/lint: Ruff
+- Type checks: Ty and Pyrefly
+- Security lint: Bandit
+- Tests: pytest + pytest-cov + pytest-asyncio
+
+## Build, lint, and test commands
+
+### Install (dev)
+
+- `uv sync --extra all --group dev`
+- `source .venv/bin/activate` (or Windows `.venv\Scripts\Activate.ps1`)
+
+### Lint and format
+
+- `make lint`
+  - Runs: `ruff format`, `ruff check --fix`, `ty check`, `pyrefly check`, `bandit`
+- Direct commands:
+  - `uv run ruff format .`
+  - `uv run ruff check --fix .`
+  - `uv run ty check .`
+  - `uv run pyrefly check .`
+  - `uv run bandit -c pyproject.toml -r src examples -q`
+
+### Tests
+
+- Full test suite: `uv run pytest`
+- Single test file: `uv run pytest tests/unit/test_service.py`
+- Single test by node id:
+  - `uv run pytest tests/unit/test_service.py::test_create_api_key`
+- Single test by keyword:
+  - `uv run pytest -k "create_api_key"`
+- Run a test class: `uv run pytest tests/unit/test_service.py::TestApiKeyService`
+
+### Coverage output
+
+Pytest defaults include coverage reports (XML/HTML/terminal) via `pyproject.toml`.
+Artifacts: `coverage.xml`, `htmlcov/`, `junit.xml`.
+
+## Code style and conventions
+
+### Formatting
+
+- Ruff handles formatting; follow it instead of manual styling.
+- Line length: 120 characters.
+- Indentation: 4 spaces.
+- Quotes: double quotes.
+
+### Imports
+
+- Standard library imports first, then third-party, then local.
+- Prefer explicit imports over wildcard.
+- Keep module-level imports; avoid local imports unless required to break cycles.
+- In optional dependency modules, guard imports with `try/except ModuleNotFoundError`.
+
+### Typing
+
+- Use Python 3.9+ type hints everywhere.
+- Prefer `Optional[T]` and `list[T]`/`dict[K, V]` style.
+- Return concrete types (`ApiKey`, `list[ApiKey]`, etc.) not `Any`.
+- Use `Annotated` for FastAPI params when needed.
+
+### Naming
+
+- Classes: `CamelCase` (e.g., `ApiKeyService`).
+- Functions/vars: `snake_case`.
+- Constants: `UPPER_SNAKE_CASE`.
+- Private helpers: prefix `_` (e.g., `_verify_entity`).
+- API key fields follow existing names (`key_id`, `key_secret`, `key_hash`).
+
+### Dataclasses and models
+
+- Use `@dataclass` for small data carriers (e.g., parsed key results).
+- Use Pydantic models for API request/response schemas.
+
+### Error handling
+
+- Domain exceptions live in `keyshield.domain.errors`.
+- Raise domain errors in services and repositories, translate to HTTP exceptions in API layer.
+- Preserve original errors with `raise ... from exc`.
+- Use specific exceptions (`KeyNotFound`, `InvalidKey`, `ConfigurationError`) rather than `ValueError` unless appropriate.
+- Validate inputs early; prefer guard clauses.
+
+### Async and I/O
+
+- Services and repositories are async; keep APIs async throughout.
+- Use `await` for repo calls and when composing service logic.
+- Avoid blocking I/O in async paths.
+
+### Security-sensitive behavior
+
+- Never log or return plaintext API keys after creation.
+- Enforce API key parsing/validation via `ParsedApiKey` and `_get_parts` patterns.
+- Use timing jitter on auth failures (`verify_key` behavior).
+- Treat secret pepper as external configuration; do not hardcode.
+
+### API layer
+
+- Use FastAPI dependency injection with `Depends`.
+- Map domain errors to `HTTPException` with correct status codes.
+- API responses use Pydantic models; keep output schemas stable.
+
+### Tests
+
+- Tests live in `tests/` with unit and integration subpackages.
+- Prefer clear arrange/act/assert structure.
+- Use fixtures from `tests/conftest.py` where available.
+
+## Repository layout
+
+- `src/keyshield/` core library
+- `tests/` unit/integration tests
+- `examples/` example applications (used in docs)
+
+## Repo-specific notes
+
+- `make lint` is the canonical lint entrypoint.
+- The project warns when the default pepper is used; tests expect that behavior.
+- Examples are used in docs; keep them runnable.
+
+## Cursor and Copilot rules
+
+- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found in this repo.
+
+## When editing
+
+- Preserve public API behavior and exception types.
+- Keep docstrings consistent with existing style.
+- Match current error messages when possible (tests may assert them).
+- Avoid introducing extra dependencies without updating optional extras.