boundedllm 0.4.0__tar.gz

boundedllm-0.4.0/.dockerignore

@@ -0,0 +1,11 @@
+# Keep local environments, build data, and the attack simulator out of images.
+.git
+.venv
+.uv-cache
+.pytest_cache
+.ruff_cache
+.dist-check
+dist
+__pycache__
+*.db*
+testApp

boundedllm-0.4.0/.env.example

@@ -0,0 +1,41 @@
+# Copy into your secret manager configuration; never commit a populated .env.
+# Every GUARD_* value below is read only at startup and never from a request.
+
+GUARD_ENVIRONMENT=development
+GUARD_DATABASE_URL=sqlite:///guard.db
+
+# Signs the tamper-evident ledger. At least 32 bytes from a CSPRNG, generated
+# inside the secret manager or an HSM. Production refuses to start without it.
+GUARD_AUDIT_KEY=replace-with-at-least-32-random-bytes
+GUARD_AUDIT_KEY_ID=security-ledger-2026-q3
+
+# Retain the previous signing key for the whole rotation window. Pending
+# approvals and idempotency digests are verified against it, so removing it too
+# early strands unredeemed approvals and turns in-flight retries into conflicts.
+# GUARD_AUDIT_PREVIOUS_KEYS={"security-ledger-2026-q2":"old-key-at-least-32-bytes-long"}
+
+# Optional long-lived key used only for pseudonymization. Set it if analysts must
+# follow one subject across a signing-key rotation; it must never rotate with the
+# signing key. It is a re-identification risk of its own, so scope it as tightly.
+# GUARD_AUDIT_PSEUDONYM_KEY=replace-with-at-least-32-random-bytes
+
+# Identity. The package verifies tokens against this JWKS and never fetches a
+# jku or x5u value supplied by a token header.
+GUARD_ISSUER=https://id.example.com/
+GUARD_AUDIENCE=secure-ai-api
+GUARD_JWKS_URL=https://id.example.com/.well-known/jwks.json
+GUARD_ALLOWED_TENANTS='["tenant-a"]'
+
+# Model transport. Required for the bundled HTTP provider; a host embedding the
+# library with its own vendor SDK does not need it.
+GUARD_MODEL_URL=https://model.example.com/v1/complete
+# GUARD_MODEL_API_KEY=replace-from-secret-manager
+
+# Security event delivery to an OpenTelemetry collector or SIEM gateway.
+# GUARD_OTEL_LOGS_ENDPOINT=https://otel-collector.example.com/v1/logs
+# GUARD_OTEL_AUTHORIZATION=Bearer replace-from-secret-manager
+
+# DLP. "pattern" is a test baseline and is refused in production. Use "presidio"
+# for the bundled integration, or "reviewed" to supply your own evaluated
+# Scanner to create_app where Presidio's footprint is unacceptable.
+# GUARD_DLP_BACKEND=presidio

boundedllm-0.4.0/.gitattributes

@@ -0,0 +1,42 @@
+# Line-ending and binary policy.
+#
+# This exists because git silently corrupted a binary test fixture. With
+# core.autocrlf=true on Windows and no rule here, git applied CRLF conversion to
+# roadshield-claims-update-poisoned.pdf, adding 74 bytes. The file was fine in
+# the working tree and broken for everyone who cloned, and the failure surfaced
+# as "PDF could not be safely parsed" in CI rather than as anything resembling a
+# line-ending problem. Git for Windows also ships a default attribute marking
+# PDFs `diff: astextplain`, which makes them look text-like.
+
+# Normalize text to LF in the repository regardless of the committer's platform.
+# Checkout still converts for Windows users who want CRLF locally.
+* text=auto eol=lf
+
+# Never touch these. The list is deliberately broad: the cost of a missing entry
+# is a corrupted file that passes locally, and the cost of a spurious one is none.
+*.pdf   binary
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.ico   binary
+*.webp  binary
+*.zip   binary
+*.gz    binary
+*.tar   binary
+*.whl   binary
+*.db    binary
+*.sqlite binary
+*.sst   binary
+*.pem   binary
+*.p12   binary
+*.pfx   binary
+*.pyc   binary
+
+# Shell scripts must keep LF even when checked out on Windows, or they fail to
+# run in a Linux container with a confusing "bad interpreter" error.
+*.sh    text eol=lf
+Dockerfile text eol=lf
+
+# Lockfiles are generated; collapsing their diffs keeps reviews readable.
+uv.lock linguist-generated=true

boundedllm-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,109 @@
+# Publish to PyPI on a version tag, using Trusted Publishing.
+#
+# There is no API token anywhere in this workflow or in repository secrets. PyPI
+# verifies a short-lived OIDC identity issued by GitHub for this exact repository,
+# workflow, and environment, and mints a token valid for minutes. A leaked repo
+# secret is the usual way packages get hijacked; this removes the secret.
+#
+# One-time setup on PyPI, before the first tag:
+#   1. https://pypi.org/manage/account/publishing/  ->  Add a pending publisher
+#        PyPI project name : boundedllm
+#        Owner             : taskul
+#        Repository        : boundedllm
+#        Workflow          : release.yml
+#        Environment       : pypi
+#   2. In GitHub: Settings -> Environments -> New environment -> "pypi".
+#      Add yourself as a required reviewer so a tag cannot publish unattended.
+#
+# Then:  git tag v0.4.0 && git push origin v0.4.0
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # Build once. The same artifacts are tested, published, and attached to the
+  # release, so what people install is what CI checked.
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with: { enable-cache: true }
+
+      # The tag must match the packaged version, or users get a release whose
+      # contents disagree with its name.
+      - name: Tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(uv run --no-project python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          test "$TAG" = "$PKG" || { echo "tag $TAG != version $PKG"; exit 1; }
+          grep -q "## \[$PKG\]" CHANGELOG.md || { echo "no CHANGELOG entry for $PKG"; exit 1; }
+
+      - run: uv build
+      # twine check catches a README that will not render on PyPI, which is only
+      # discoverable after an irreversible upload otherwise.
+      - run: uvx twine check --strict dist/*
+
+      # Install the built wheel in a clean environment and use it. A package that
+      # imports only from the source tree passes every other job and fails here.
+      - name: Installed wheel is importable and runnable
+        run: |
+          uv venv /tmp/fresh
+          VIRTUAL_ENV=/tmp/fresh uv pip install dist/*.whl
+          /tmp/fresh/bin/python -c "import boundedllm; print('import ok', boundedllm.__version__)"
+          VIRTUAL_ENV=/tmp/fresh uv pip install "$(ls dist/*.whl)[sql]"
+          /tmp/fresh/bin/boundedllm demo > /dev/null && echo "cli ok"
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/boundedllm
+    permissions:
+      # The OIDC token PyPI verifies. Nothing else needs write access.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      # Signs the artifacts so a downloader can prove they came from this workflow.
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
+        with:
+          subject-path: dist/*
+      - uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          body: |
+            Install: `pip install boundedllm==${{ github.ref_name }}`
+
+            See [CHANGELOG.md](CHANGELOG.md) for what changed and whether it breaks.

boundedllm-0.4.0/.github/workflows/security.yml

@@ -0,0 +1,204 @@
+# Every prompt, policy, dependency, and code change runs deterministic checks.
+#
+# Actions are pinned to commit SHAs, not tags. A tag is mutable, so an upstream
+# account compromise would otherwise reach a workflow that holds repository
+# credentials. The comment after each SHA records the human-readable version.
+# Re-resolve them with a tool rather than by hand:
+#   go install github.com/suzuki-shunsuke/pinact/cmd/pinact@latest && pinact run
+name: security
+on: [push, pull_request]
+permissions:
+  contents: read
+
+jobs:
+  library:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with: { enable-cache: true }
+      - run: uv sync --locked --dev --all-extras
+      - run: uv run pytest -q
+      # The quickstart example is executed by tests/test_documentation.py.
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      # pip-audit's --locked flag reads a PEP 751 pylock.toml, not uv.lock, so it
+      # failed to resolve anything to audit. Export the locked runtime set and
+      # audit that instead: it is the exact dependency set the wheel ships.
+      - run: uv export --no-dev --no-emit-project --all-extras --format requirements-txt -o requirements.lock.txt
+      - run: uv run pip-audit -r requirements.lock.txt --disable-pip
+
+  # The core's whole claim is that a host keeps its own storage. If importing it
+  # ever needs a database driver again, this job fails before anything else does.
+  core-has-no-storage-dependency:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with: { enable-cache: true }
+      # Deliberately no extras: install the package exactly as `pip install
+      # boundedllm` would, then use it.
+      - run: uv venv && uv pip install .
+      - run: |
+          uv run --no-project python - <<'PY'
+          import importlib.util
+          for forbidden in ("sqlalchemy", "fastapi", "httpx", "jwt", "pydantic_settings"):
+              assert importlib.util.find_spec(forbidden) is None, f"{forbidden} reached the core install"
+          import boundedllm
+          from boundedllm import ChatRequest, Guard, Limits, Principal  # noqa: F401
+          print("core import surface is storage-free:", boundedllm.__version__)
+          PY
+
+  # PostgreSQL is where production runs and was the least-exercised path.
+  postgres:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: guard_test
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+        ports: ["5432:5432"]
+    env:
+      TEST_POSTGRES_URL: postgresql+psycopg://postgres:postgres@localhost:5432/guard_test
+      GUARD_DATABASE_URL: postgresql+psycopg://postgres:postgres@localhost:5432/guard_test
+      GUARD_AUDIT_KEY: ci-only-not-a-secret-at-least-32-bytes-long
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with: { enable-cache: true }
+      - run: uv sync --locked --dev --all-extras
+      # Migrations must apply cleanly and then report no drift from the models.
+      # Drift is how a schema quietly stops matching the ACL predicates built on it.
+      - run: uv run boundedllm migrate
+      - run: uv run alembic -c src/boundedllm/adapters/sql/alembic.ini check
+      - run: uv run boundedllm enable-rls
+      # RLS isolation, the contrib adapters' ACL predicates, and the concurrent
+      # audit-chain test all need a real database.
+      # RLS isolation, the contrib adapters' ACL predicates, the concurrent
+      # audit chain, and the monetary paths all need a database that actually
+      # honours with_for_update(). On SQLite those locks are silent no-ops.
+      - run: uv run pytest -q tests/test_postgres.py tests/test_contrib.py tests/test_money_concurrency.py
+
+  attack-lab:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with: { enable-cache: true }
+      - run: uv sync --locked --dev
+        working-directory: testApp
+      - run: uv run pytest -q
+        working-directory: testApp
+      - run: uv run ruff check roadshield tests scripts run.py
+        working-directory: testApp
+      - run: uv run ruff format --check roadshield tests scripts run.py
+        working-directory: testApp
+
+  image:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - run: docker build -t boundedllm:ci .
+      # Run it the way the Dockerfile documents: read-only tree, tmpfs, no extra
+      # capabilities. A container that only starts when it can write to itself is
+      # not the artifact we intend to ship.
+      - run: |
+          docker run -d --name guard-ci -p 8000:8000 \
+            --read-only --tmpfs /tmp:rw,noexec,nosuid,size=64m \
+            --cap-drop ALL --security-opt no-new-privileges \
+            -e GUARD_AUDIT_KEY=ci-only-not-a-secret-at-least-32-bytes-long \
+            -e GUARD_DATABASE_URL=sqlite:////tmp/guard.db \
+            -e GUARD_MODEL_URL=https://model.example.com/v1/complete \
+            boundedllm:ci
+          for i in $(seq 1 30); do
+            if curl -fsS http://127.0.0.1:8000/health/live; then echo; break; fi
+            if [ "$i" = "30" ]; then echo "never became live"; docker logs guard-ci; exit 1; fi
+            sleep 2
+          done
+          test "$(docker inspect -f '{{.Config.User}}' boundedllm:ci)" = "app" \
+            || { echo "image does not run as the unprivileged app user"; exit 1; }
+      - if: always()
+        run: docker rm -f guard-ci || true
+
+  # A dependency inventory that ships with the release, so a downstream consumer
+  # can answer "are we affected" without rebuilding the image.
+  sbom:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with: { enable-cache: true }
+      - run: uv sync --locked --all-extras --no-dev
+      - uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0
+        with:
+          path: .
+          format: cyclonedx-json
+          artifact-name: sbom.cyclonedx.json
+
+  codeql:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: github/codeql-action/init@faaca9a8f6edddba5725ffe5adefdab6669a2eca # v3
+        with:
+          languages: python
+          queries: security-extended
+      - uses: github/codeql-action/analyze@faaca9a8f6edddba5725ffe5adefdab6669a2eca # v3
+
+  secrets:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          # Full history: a key removed in a later commit is still a leaked key.
+          fetch-depth: 0
+      # .gitleaks.toml extends the defaults. Verified against synthetic
+      # high-entropy credentials: the defaults catch AWS, GitHub, Stripe and
+      # Slack but have no Anthropic rule, which is this repository's most likely
+      # leak. Do not drop the config and assume useDefault covers it.
+      - uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_CONFIG: .gitleaks.toml
+          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: "false"
+
+  # Not a benchmark. This asserts the ceilings actually bind under concurrency,
+  # because a quota that only holds in a single-threaded test is not a quota.
+  load:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: guard_load
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+        ports: ["5432:5432"]
+    env:
+      GUARD_DATABASE_URL: postgresql+psycopg://postgres:postgres@localhost:5432/guard_load
+      GUARD_AUDIT_KEY: ci-only-not-a-secret-at-least-32-bytes-long
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with: { enable-cache: true }
+      - run: uv sync --locked --dev --all-extras
+      - run: uv run boundedllm migrate
+      - run: uv run python scripts/load_check.py

boundedllm-0.4.0/.gitignore

@@ -0,0 +1,62 @@
+# What must never reach a commit, and why.
+#
+# This is a security package, so the cost of a mistake here is asymmetric: a
+# missing cache entry is noise, a committed key is an incident. Patterns are
+# grouped by consequence rather than by tool, and the secret group is first.
+
+# --- Credentials and key material -------------------------------------------
+# .env.example is the committed template and is deliberately excluded from the
+# exclusion. Everything else shaped like an environment file stays local.
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+# Certificate stores exported for local troubleshooting.
+*.sst
+# The lab's development pepper. It keeps local password hashes and sessions
+# valid across restarts, which makes it a credential even though it is synthetic.
+.roadshield-dev-secret
+
+# --- Local databases --------------------------------------------------------
+# These hold seeded customer records, conversations, and the signed audit
+# ledger. Synthetic today, but the habit of committing them is the problem.
+*.db
+*.db-shm
+*.db-wal
+
+# --- Environments and caches ------------------------------------------------
+.venv/
+venv/
+.uv-cache/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# --- Build output -----------------------------------------------------------
+dist/
+build/
+*.egg-info/
+.dist-check/
+
+# --- Generated by CI, never committed ---------------------------------------
+# The workflow regenerates these on every run. A stale copy in the repository
+# would look authoritative while describing an older dependency set.
+requirements.lock.txt
+sbom*.json
+results.sarif
+gitleaks-report.json
+.coverage
+htmlcov/
+
+# --- Working notes ----------------------------------------------------------
+# A personal design document and its plain-text extraction. Kept local: it was
+# written as private notes rather than for readers, and it describes the
+# pre-0.3.0 architecture, so publishing it would point people at a design this
+# package no longer has. README.md is the authoritative description.
+llm-security-field-guide.html
+guide-extracted.txt

boundedllm-0.4.0/.gitleaks.toml

@@ -0,0 +1,67 @@
+# Secret-scanning rules, extending the gitleaks defaults.
+#
+# The defaults were verified against synthetic high-entropy credentials and do
+# detect AWS, GitHub, Stripe, and Slack tokens. They do **not** detect an
+# Anthropic API key: as of gitleaks v8.30.1 there is no rule for the
+# `sk-ant-...` format, and the `generic-api-key` heuristic did not fire on it
+# either, though it did fire on an OpenAI key in the same file.
+#
+# That matters more here than it would elsewhere. This repository ships an
+# example application wired to Claude, so an Anthropic key in a `.env` is the
+# single most likely credential to be committed by accident. Relying on the
+# default ruleset would have left exactly that case unscanned.
+#
+# The provider rules below are written as explicit prefixes rather than entropy
+# heuristics, because a prefix match has no false-negative cliff at short
+# lengths and these formats are unambiguous.
+
+[extend]
+useDefault = true
+
+[[rules]]
+id = "anthropic-api-key"
+description = "Anthropic API key (sk-ant-...)"
+# Covers both the standard api keys and admin keys, whose middle segment differs.
+regex = '''sk-ant-(?:api|admin)[0-9]{0,3}-[A-Za-z0-9_\-]{32,200}'''
+keywords = ["sk-ant-"]
+
+[[rules]]
+id = "openai-api-key-explicit"
+description = "OpenAI API key (sk-... / sk-proj-...)"
+# The default config catches this only via the generic heuristic, which depends
+# on the surrounding assignment. An explicit rule removes that dependency.
+regex = '''sk-(?:proj-)?[A-Za-z0-9_\-]{32,200}'''
+keywords = ["sk-proj-", "sk-"]
+
+[[rules]]
+id = "guard-audit-key"
+description = "This package's own audit signing key"
+# GUARD_AUDIT_KEY signs the tamper-evident ledger. A leaked one lets an attacker
+# forge audit records, so it is a credential in its own right even though it has
+# no vendor prefix to match on.
+regex = '''(?i)GUARD_AUDIT(?:_PSEUDONYM)?_KEY\s*[=:]\s*["']?([A-Za-z0-9_\-+/=]{32,})'''
+keywords = ["GUARD_AUDIT_KEY", "GUARD_AUDIT_PSEUDONYM_KEY"]
+
+[allowlist]
+description = "Documented placeholders and test fixtures that are not credentials"
+paths = [
+  # Dependency caches and build output are not part of the repository.
+  '''\.venv/''',
+  '''\.uv-cache/''',
+  '''\.dist-check/''',
+  '''uv\.lock''',
+]
+regexes = [
+  # The committed example file and the docs deliberately show the shape of a
+  # secret without containing one.
+  '''replace-with-at-least-32-random-bytes''',
+  '''replace-me-32-bytes-minimum-secret''',
+  '''ci-only-not-a-secret-at-least-32-bytes-long''',
+  '''old-key-at-least-32-bytes-long''',
+  '''test-secret-never-logged''',
+  # tests/test_adversarial.py asserts that secret-shaped model output is blocked
+  # before release. The fixture has to look like a credential for the test to
+  # mean anything. Allowlisted by exact value rather than by exempting the tests
+  # directory, so a genuine credential committed there would still be reported.
+  '''sk-live-4f9a2b7c1d8e6f3a0b5c9d2e''',
+]