solvapay-python 0.8.0__tar.gz → 0.9.1__tar.gz

solvapay_python-0.9.1/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - ci

solvapay_python-0.9.1/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "0 7 * * *"  # nightly security sweep
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --all-extras --dev
+      - name: bandit (high-severity, high-confidence only)
+        run: uv run bandit -r src/ -lll
+      - name: Install osv-scanner
+        run: |
+          curl -fsSL -o /tmp/osv-scanner.tar.gz \
+            https://github.com/google/osv-scanner/releases/download/v1.9.2/osv-scanner_linux_amd64.tar.gz
+          mkdir -p /tmp/osv && tar -xzf /tmp/osv-scanner.tar.gz -C /tmp/osv
+          sudo mv /tmp/osv/osv-scanner /usr/local/bin/osv-scanner
+          osv-scanner --version
+      - name: osv-scanner (lockfile vuln DB cross-check)
+        run: osv-scanner --lockfile=uv.lock
+
+
+  test:
+    strategy:
+      matrix:
+        include:
+          # Linux — full Python matrix
+          - os: ubuntu-latest
+            python-version: "3.10"
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          # macOS — 3.12 only
+          - os: macos-latest
+            python-version: "3.12"
+          # Windows — 3.12 only
+          - os: windows-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy src
+      - run: uv run pytest -v
+      - run: uv run python tools/api_diff.py
+      - run: uv run lint-imports --config tools/importlinter.cfg
+      - run: uv run python tools/lint_invariants.py
+      - name: pip-audit
+        run: uv run pip-audit
+      - name: Check changelog fragment on PRs touching src/
+        if: github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          changed=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+          if echo "$changed" | grep -q "^src/"; then
+            if ! echo "$changed" | grep -q "^changelog.d/"; then
+              echo "ERROR: src/ modified without a changelog.d/ fragment. Add one — see changelog.d/README.md"
+              exit 1
+            fi
+          fi

solvapay_python-0.9.1/.github/workflows/contract.yml

@@ -0,0 +1,22 @@
+name: contract
+
+on:
+  schedule:
+    - cron: "0 2 * * *"  # nightly at 02:00 UTC
+  workflow_dispatch:
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras --dev
+      - name: Run contract tests
+        run: uv run pytest tests/contract/ -m contract -v
+        env:
+          SOLVAPAY_SANDBOX_KEY: ${{ secrets.SOLVAPAY_SANDBOX_KEY }}
+          SOLVAPAY_TEST_CUSTOMER_REF: ${{ secrets.SOLVAPAY_TEST_CUSTOMER_REF }}
+          SOLVAPAY_TEST_PRODUCT_REF: ${{ secrets.SOLVAPAY_TEST_PRODUCT_REF }}

solvapay_python-0.9.1/.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: docs
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --group docs
+      - name: Deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

solvapay_python-0.9.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: publish
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - name: Generate CycloneDX SBOM
+        run: |
+          # Resolve runtime + all-extras deps from the lockfile and emit a CycloneDX SBOM.
+          uv export --no-dev --all-extras --no-emit-project --format requirements-txt > /tmp/sbom-requirements.txt
+          uv tool run --from cyclonedx-bom cyclonedx-py requirements \
+            --pyproject pyproject.toml \
+            --of JSON --sv 1.6 \
+            -o sbom.cdx.json \
+            /tmp/sbom-requirements.txt
+      - name: Publish to PyPI (Sigstore-signed via trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+      - name: Attach SBOM to GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${GITHUB_REF_NAME}" sbom.cdx.json --clobber

{solvapay_python-0.8.0 → solvapay_python-0.9.1}/.gitignore

@@ -12,3 +12,5 @@ htmlcov/
 .env
 .env.local
 *.egg
+.DS_Store
+site/

{solvapay_python-0.8.0 → solvapay_python-0.9.1}/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.9.1] — 2026-06-05
+
+Security & supply-chain quality patch (no public API change).
+
+### Features
+
+- ``publish.yml``: PyPI uploads now ship PEP 740 attestations (Sigstore-backed via OIDC trusted publishing) and attach a CycloneDX SBOM (``sbom.cdx.json``) to each GitHub release.
+- CI: new ``security`` job runs ``bandit -r src/ -lll`` (high-confidence high-severity only) and ``osv-scanner --lockfile=uv.lock`` as a cross-DB check against ``pip-audit``. Runs on PR and nightly cron.
+- ``tests/test_redaction.py``: property-based test with Hypothesis (100 derandomized cases) drives random API keys, hex tokens, and webhook secrets through the HTTP transport and asserts the secret never appears in ``caplog.text`` at any log level.
+- ``tests/test_webhook_timing.py``: smoke test that compares ``verify_webhook`` perf-counter distributions for perfect-match vs near-miss signatures, regressing if someone swaps ``hmac.compare_digest`` for ``==``.
+
+### Bug Fixes
+
+- ``pyproject.toml``: tighten ``httpx`` to ``<0.29`` (closes deviation: was unbounded). FastAPI extra remains unbounded by design — documented in-file.
+
+### Documentation
+
+- ``SECURITY.md``: explicit PCI-scope section — the SDK never transmits raw cardholder data; tokenization is server-side.
+
+---
+
+## 0.9.0 — 2026-05-23
+
+Production polish + C1 adversarial-review closure. API-version pinning, idempotency TTL, webhook secret rotation, ASGI adapter, retry/recording transports, contract tests, lint automation, doc site, supply-chain hardening.
+
+### Added
+- **API-version pinning**: `SolvaPay(api_version="2026-05-22")` and `AsyncSolvaPay(api_version=...)` send `Solvapay-Version` header. Default pinned to `"2026-05-22"`. `api_version=None` omits the header. (HLD V1.13)
+- **Idempotency time-bucket encoding**: `from_payload(*parts, time_bucket="day"|"hour"|None)`. Default `"day"` appends UTC date so keys roll at midnight, bounding replay ambiguity past server TTL. (HLD V1.14)
+- **Webhook secret rotation**: `MultiSecretVerifier` full implementation — tries primary then secondary on signature mismatch; both comparisons constant-time. (HLD V1.7)
+- **`AsyncInMemorySeenEventCache`**: async replay-dedup cache using `asyncio.Lock` for async webhook pipelines. (HLD V1.7)
+- **`sign_webhook(body, secret, *, timestamp)`**: public helper to produce a valid `sv-signature` header for testing and outbound webhook fanout.
+- **ASGI webhook adapter** (`solvapay[asgi]`): `webhook_app(pipeline, on_event, path)` returns a raw ASGI app mountable in Starlette, FastAPI, Litestar, or BlackSheep. (HLD V1.10)
+- **`RetryTransport`**: middleware that retries `APIConnectionError`, `APITimeoutError`, `APIServerError`, `RateLimitError` — exponential backoff with jitter, max 3 attempts. Consults `OpSpec.retry_safety`; refuses to retry `NEVER` ops. (HLD V1.4, `solvapay[retry]`)
+- **`RecordingTransport`**: records `(RequestSpec, ResponseSpec)` pairs to JSON cassettes; replays on subsequent runs. Enables offline contract tests. (HLD V1.4)
+- **Sandbox contract tests** (`tests/contract/`): one test per op against real sandbox via `RecordingTransport`. Nightly CI workflow (`contract.yml`).
+- **Lint invariants** (`tools/lint_invariants.py`): AST checks for 10 gotchas (future annotations, `hmac.compare_digest`, no `logging.basicConfig`, no `asyncio.run()`, alias discipline, etc.). Run in CI on every push.
+- **Towncrier changelog automation**: `changelog.d/` fragments, PR gate requiring a fragment when `src/` changes, `towncrier>=23` dev dep.
+- **MkDocs Material doc site**: `mkdocs.yml` + `docs/` skeleton (Quickstart, Reference, Architecture, Guides, Errors, Idempotency, Webhooks, Migration). Deploys to GitHub Pages on tag. (HLD V1.12)
+- **Dependabot**: weekly Python + GitHub Actions dependency updates (`.github/dependabot.yml`).
+- **`pip-audit` in CI**: dependency CVE scan on every push.
+- **CI matrix expanded**: Ubuntu 3.10/3.11/3.12 + macOS 3.12 + Windows 3.12. (HLD V1.15)
+- **`ResourceWarning` on unclosed `AsyncSolvaPay`**: `__del__` emits `ResourceWarning` if client is not closed and event loop is still running.
+- **OpenAPI investigation RFC**: `docs/rfcs/0002-openapi-investigation.md`.
+
+### Changed
+- `pytest.ini_options.filterwarnings`: adds `ignore::DeprecationWarning:solvapay` so tests exercising deprecated flat-shim API do not fail on expected warnings.
+
+---
+
 ## 0.8.0 — 2026-05-23
 
 V1 architecture spine + AI-agent moat. 10 atomic commits establishing locked architecture invariants per HLD §V1.1–V1.19.

{solvapay_python-0.8.0 → solvapay_python-0.9.1}/CONTRIBUTING.md

@@ -30,13 +30,26 @@ The SDK has a strict layer hierarchy — see [docs/architecture/layers.md](docs/
 
 CI fails on violations via `import-linter`.
 
+## Changelog fragment (required)
+
+Every PR that modifies `src/` must include a towncrier fragment in `changelog.d/`.
+
+```bash
+# Create a fragment (replace 42 with your issue/PR number)
+echo "Add RetryTransport middleware for automatic retry on transient errors." > changelog.d/42.feature
+```
+
+See `changelog.d/README.md` for naming conventions and types.
+
+PRs that touch `src/` without a `changelog.d/` entry will fail CI.
+
 ## PR checklist
 
 - [ ] Tests added for new behavior
-- [ ] `CHANGELOG.md` updated
+- [ ] `changelog.d/<issue>.<type>` fragment added (required for `src/` changes)
 - [ ] `docs/` updated if public API changed
 - [ ] Layer DAG respected (`uv run lint-imports` passes)
-- [ ] Stability manifest updated if new public exports added
+- [ ] Stability manifest updated if new public exports added (`uv run python tools/api_diff.py`)
 
 ## Commit style
 

{solvapay_python-0.8.0 → solvapay_python-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvapay-python
-Version: 0.8.0
+Version: 0.9.1
 Summary: Community Python SDK for SolvaPay (agent-native payment rails)
 Project-URL: Homepage, https://github.com/dhruv-sanan/solvapay-python
 Project-URL: Issues, https://github.com/dhruv-sanan/solvapay-python/issues
@@ -21,14 +21,17 @@ Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: httpx>=0.27
-Requires-Dist: pydantic<2.13,>=2.6
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pydantic<2.14,>=2.6
+Provides-Extra: asgi
 Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.110; extra == 'fastapi'
 Provides-Extra: langchain
-Requires-Dist: langchain-core<0.4,>=0.3; extra == 'langchain'
+Requires-Dist: langchain-core<1.5,>=0.3; extra == 'langchain'
 Provides-Extra: mcp
-Requires-Dist: fastmcp<0.5,>=0.4; extra == 'mcp'
+Requires-Dist: fastmcp<4,>=3.2.0; extra == 'mcp'
+Provides-Extra: retry
+Requires-Dist: tenacity<10,>=8.2; extra == 'retry'
 Description-Content-Type: text/markdown
 
 # solvapay-python
@@ -135,16 +138,23 @@ if limits.within_limits:
 
 ## Idempotency
 
-All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys from request content:
+All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys:
 
 ```python
 from solvapay.idempotency import from_payload
 
+# Default: key includes UTC date — rolls at midnight, bounds replay past server TTL
 key = from_payload("track_usage", customer_ref, product_ref, "requests", units)
 sv.usage.track(..., idempotency_key=key)   # retry-safe
+
+# Hourly bucket (high-frequency ops)
+key = from_payload("charge", customer_ref, time_bucket="hour")
+
+# Pure payload hash — caller manages TTL externally
+key = from_payload("idempotent_op", ref, time_bucket=None)
 ```
 
-Retried POSTs **must reuse the same key**. Key should change only when the logical request changes.
+Retried POSTs **must reuse the same key**. A bucket roll (midnight / hour boundary) produces a new key — the server treats it as a new request.
 
 ---
 
@@ -171,7 +181,7 @@ except SolvaPayError as e:
     ...  # catch-all
 ```
 
-No built-in retries by design. Layer `tenacity` manually. `solvapay[retry]` RetryTransport ships in v0.9.
+No built-in retries by default. `solvapay[retry]` ships `RetryTransport` — exponential backoff with jitter, 3 attempts, respects `OpSpec.retry_safety` (won't retry non-idempotent ops without an idempotency key). Or layer `tenacity` manually.
 
 ---
 
@@ -190,6 +200,29 @@ pipeline = WebhookPipeline(
 envelope = pipeline.process(body=request.body, signature=request.headers["sv-signature"])
 ```
 
+**Secret rotation** — pass multiple secrets; primary tried first, secondary on mismatch:
+
+```python
+pipeline = WebhookPipeline(["whsec_new...", "whsec_old..."])
+```
+
+**Sign a webhook** (testing / outbound fanout):
+
+```python
+from solvapay.webhooks import sign_webhook
+
+header = sign_webhook(body=b'{"type":"purchase.created"}', secret="whsec_...")
+# → "t=1716470000,v1=abc123..."
+```
+
+**ASGI adapter** — mount directly in FastAPI / Starlette / Litestar:
+
+```python
+from solvapay.adapters.asgi import webhook_app
+
+app.mount("/webhook", webhook_app(pipeline, on_event=handle))
+```
+
 **Typed events** — discriminated union over 13 event types:
 
 ```python
@@ -276,6 +309,8 @@ pip install solvapay-python                   # core
 pip install 'solvapay-python[mcp]'            # + FastMCP adapter (FastMCP ≥0.4)
 pip install 'solvapay-python[langchain]'      # + LangChain adapter (langchain-core ≥0.3)
 pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
+pip install 'solvapay-python[asgi]'           # + raw ASGI webhook adapter (no extra deps)
+pip install 'solvapay-python[retry]'          # + RetryTransport (tenacity)
 ```
 
 ## Environment variables
@@ -299,17 +334,40 @@ pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
 
 ---
 
+## API version pinning
+
+Pin the API version your code was written against — prevents silent breakage when the server evolves:
+
+```python
+sv = SolvaPay(api_version="2026-05-22")   # sends Solvapay-Version header
+sv = SolvaPay(api_version=None)            # omit header (use server default)
+```
+
+Default is `"2026-05-22"` (v0.9 ship date). Bump only on major SDK versions.
+
+---
+
 ## Roadmap
 
 | Version | Theme |
 |---------|-------|
 | v0.8 ✅ | V1 architecture spine — Transport kernel, OpSpec registry, paywall/webhook packages, `@payable_tool`, stability manifest, layer DAG CI gate |
-| v0.9 | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, contract tests, lint automation, doc site (MkDocs Material), supply-chain hygiene |
-| v1.0 | Gated on founder signal — OpenAPI-generated models, full secret rotation, production hardening |
+| v0.9 ✅ | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, ASGI adapter, secret rotation, `sign_webhook`, contract tests, lint automation, MkDocs site, supply-chain hygiene |
+| v0.9.1 ✅ | Security & supply-chain quality — PyPI attestations (PEP 740 / Sigstore), CycloneDX SBOM on releases, `bandit` + `osv-scanner` CI, Hypothesis-driven secret-redaction property tests, constant-time `verify_webhook` smoke test, explicit PCI-scope statement |
+| v1.0 | Gated on founder signal — OpenAPI-generated models, WSGI/Lambda adapters, V2 planning |
 
 ---
 
 ## Status
 
-**v0.8.0** — V1 architecture spine + AI-agent moat. `mypy --strict` clean (43 files). 261 tests. 89% line coverage.  
+**v0.9.1** — Security & supply-chain quality patch. PyPI uploads now carry PEP 740 attestations (Sigstore-backed via OIDC trusted publishing); each GitHub release ships a CycloneDX SBOM (`sbom.cdx.json`). `mypy --strict` clean (45 files). 302 tests. 87% line / 85% branch coverage.
+
+**Supply chain & security posture:**
+- PyPI trusted publishing with PEP 740 attestations (Sigstore)
+- CycloneDX 1.6 SBOM attached to every release
+- CI runs `bandit -r src/ -lll`, `osv-scanner --lockfile=uv.lock`, and `pip-audit` (cross-DB vuln check) on PR and nightly cron
+- Constant-time HMAC comparison (`hmac.compare_digest`) regression-smoked
+- Hypothesis-driven property tests assert no API key, hex token, or webhook secret leaks into log output at any level
+- Tightened upper bounds on volatile deps (`httpx<0.29`, `pydantic<2.14`, `langchain-core<1.5`)
+
 Community SDK, not official. Proposal: [solvapay/solvapay-sdk#187](https://github.com/solvapay/solvapay-sdk/issues/187).

{solvapay_python-0.8.0 → solvapay_python-0.9.1}/README.md

@@ -102,16 +102,23 @@ if limits.within_limits:
 
 ## Idempotency
 
-All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys from request content:
+All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys:
 
 ```python
 from solvapay.idempotency import from_payload
 
+# Default: key includes UTC date — rolls at midnight, bounds replay past server TTL
 key = from_payload("track_usage", customer_ref, product_ref, "requests", units)
 sv.usage.track(..., idempotency_key=key)   # retry-safe
+
+# Hourly bucket (high-frequency ops)
+key = from_payload("charge", customer_ref, time_bucket="hour")
+
+# Pure payload hash — caller manages TTL externally
+key = from_payload("idempotent_op", ref, time_bucket=None)
 ```
 
-Retried POSTs **must reuse the same key**. Key should change only when the logical request changes.
+Retried POSTs **must reuse the same key**. A bucket roll (midnight / hour boundary) produces a new key — the server treats it as a new request.
 
 ---
 
@@ -138,7 +145,7 @@ except SolvaPayError as e:
     ...  # catch-all
 ```
 
-No built-in retries by design. Layer `tenacity` manually. `solvapay[retry]` RetryTransport ships in v0.9.
+No built-in retries by default. `solvapay[retry]` ships `RetryTransport` — exponential backoff with jitter, 3 attempts, respects `OpSpec.retry_safety` (won't retry non-idempotent ops without an idempotency key). Or layer `tenacity` manually.
 
 ---
 
@@ -157,6 +164,29 @@ pipeline = WebhookPipeline(
 envelope = pipeline.process(body=request.body, signature=request.headers["sv-signature"])
 ```
 
+**Secret rotation** — pass multiple secrets; primary tried first, secondary on mismatch:
+
+```python
+pipeline = WebhookPipeline(["whsec_new...", "whsec_old..."])
+```
+
+**Sign a webhook** (testing / outbound fanout):
+
+```python
+from solvapay.webhooks import sign_webhook
+
+header = sign_webhook(body=b'{"type":"purchase.created"}', secret="whsec_...")
+# → "t=1716470000,v1=abc123..."
+```
+
+**ASGI adapter** — mount directly in FastAPI / Starlette / Litestar:
+
+```python
+from solvapay.adapters.asgi import webhook_app
+
+app.mount("/webhook", webhook_app(pipeline, on_event=handle))
+```
+
 **Typed events** — discriminated union over 13 event types:
 
 ```python
@@ -243,6 +273,8 @@ pip install solvapay-python                   # core
 pip install 'solvapay-python[mcp]'            # + FastMCP adapter (FastMCP ≥0.4)
 pip install 'solvapay-python[langchain]'      # + LangChain adapter (langchain-core ≥0.3)
 pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
+pip install 'solvapay-python[asgi]'           # + raw ASGI webhook adapter (no extra deps)
+pip install 'solvapay-python[retry]'          # + RetryTransport (tenacity)
 ```
 
 ## Environment variables
@@ -266,17 +298,40 @@ pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
 
 ---
 
+## API version pinning
+
+Pin the API version your code was written against — prevents silent breakage when the server evolves:
+
+```python
+sv = SolvaPay(api_version="2026-05-22")   # sends Solvapay-Version header
+sv = SolvaPay(api_version=None)            # omit header (use server default)
+```
+
+Default is `"2026-05-22"` (v0.9 ship date). Bump only on major SDK versions.
+
+---
+
 ## Roadmap
 
 | Version | Theme |
 |---------|-------|
 | v0.8 ✅ | V1 architecture spine — Transport kernel, OpSpec registry, paywall/webhook packages, `@payable_tool`, stability manifest, layer DAG CI gate |
-| v0.9 | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, contract tests, lint automation, doc site (MkDocs Material), supply-chain hygiene |
-| v1.0 | Gated on founder signal — OpenAPI-generated models, full secret rotation, production hardening |
+| v0.9 ✅ | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, ASGI adapter, secret rotation, `sign_webhook`, contract tests, lint automation, MkDocs site, supply-chain hygiene |
+| v0.9.1 ✅ | Security & supply-chain quality — PyPI attestations (PEP 740 / Sigstore), CycloneDX SBOM on releases, `bandit` + `osv-scanner` CI, Hypothesis-driven secret-redaction property tests, constant-time `verify_webhook` smoke test, explicit PCI-scope statement |
+| v1.0 | Gated on founder signal — OpenAPI-generated models, WSGI/Lambda adapters, V2 planning |
 
 ---
 
 ## Status
 
-**v0.8.0** — V1 architecture spine + AI-agent moat. `mypy --strict` clean (43 files). 261 tests. 89% line coverage.  
+**v0.9.1** — Security & supply-chain quality patch. PyPI uploads now carry PEP 740 attestations (Sigstore-backed via OIDC trusted publishing); each GitHub release ships a CycloneDX SBOM (`sbom.cdx.json`). `mypy --strict` clean (45 files). 302 tests. 87% line / 85% branch coverage.
+
+**Supply chain & security posture:**
+- PyPI trusted publishing with PEP 740 attestations (Sigstore)
+- CycloneDX 1.6 SBOM attached to every release
+- CI runs `bandit -r src/ -lll`, `osv-scanner --lockfile=uv.lock`, and `pip-audit` (cross-DB vuln check) on PR and nightly cron
+- Constant-time HMAC comparison (`hmac.compare_digest`) regression-smoked
+- Hypothesis-driven property tests assert no API key, hex token, or webhook secret leaks into log output at any level
+- Tightened upper bounds on volatile deps (`httpx<0.29`, `pydantic<2.14`, `langchain-core<1.5`)
+
 Community SDK, not official. Proposal: [solvapay/solvapay-sdk#187](https://github.com/solvapay/solvapay-sdk/issues/187).

{solvapay_python-0.8.0 → solvapay_python-0.9.1}/SECURITY.md

@@ -13,8 +13,17 @@ This is a **community** Python SDK. It is not an official SolvaPay product.
 - SolvaPay server-side vulnerabilities
 - Issues requiring a SolvaPay account to reproduce
 
-**PCI scope:** The SDK never transmits raw cardholder data (PAN, CVV, expiry).
-It only exchanges SolvaPay API keys and customer references over HTTPS.
+## PCI Scope
+
+The SDK **never transmits raw cardholder data (PAN, CVV, expiry, track data)**.
+All tokenization happens **server-side** at the SolvaPay API; the SDK only
+exchanges SolvaPay API keys, customer references, and tokenized identifiers
+over HTTPS. Integrators using this SDK do not bring PAN data into their
+own application scope through it.
+
+If you discover any code path that would cause raw cardholder data to traverse
+the SDK boundary, treat it as a high-severity vulnerability and report it via
+the channel below.
 
 ## Reporting a Vulnerability
 
@@ -25,6 +34,9 @@ Please include:
 - Steps to reproduce
 - Any proof-of-concept code (privately)
 
+Encrypt sensitive payloads with the maintainer's public key on request.
+Do **not** open public GitHub issues for suspected vulnerabilities.
+
 **Response SLA:** Best-effort; typically within 7 days.
 **Disclosure policy:** 90-day coordinated disclosure. Public CVE filed only for confirmed SDK bugs.
 
@@ -32,5 +44,6 @@ Please include:
 
 | Version | Supported |
 |---------|-----------|
+| 0.9.x   | Yes       |
 | 0.8.x   | Yes       |
 | < 0.8   | No — upgrade recommended |

solvapay_python-0.9.1/changelog.d/README.md

@@ -0,0 +1,35 @@
+# Changelog Fragments
+
+This directory contains towncrier changelog fragments. Each file represents one change entry.
+
+## Fragment naming
+
+```
+<issue_or_pr_number>.<type>
+```
+
+**Types:** `feature`, `bugfix`, `doc`, `removal`
+
+**Examples:**
+```
+42.feature     → "Add RetryTransport middleware"
+55.bugfix      → "Fix idempotency key not sent on retry"
+60.doc         → "Document api_version pinning"
+99.removal     → "Remove deprecated SolvaPayAPIError alias"
+```
+
+## Required for PRs
+
+Any PR that touches `src/` **must** include at least one fragment. PRs without a fragment will fail CI.
+
+Example fragment content:
+```
+Add ``api_version`` kwarg to ``SolvaPay`` and ``AsyncSolvaPay`` for server-side API version pinning.
+```
+
+## Building the changelog
+
+```bash
+uv run towncrier build --version 0.9.0 --draft   # preview
+uv run towncrier build --version 0.9.0            # write to CHANGELOG.md
+```

solvapay_python-0.9.1/docs/errors.md

@@ -0,0 +1,50 @@
+# Errors
+
+```
+SolvaPayError
+├── APIError(status_code, body, request_id, error_code, error_message)
+│   ├── AuthenticationError    # 401
+│   ├── PermissionError        # 403
+│   ├── NotFoundError          # 404
+│   ├── RateLimitError(retry_after)   # 429
+│   ├── InvalidRequestError    # other 4xx
+│   └── APIServerError         # 5xx
+├── APIConnectionError         # network failure
+├── APITimeoutError            # timeout
+└── PaywallRequired            # paywall gate hit
+    .checkout_url: str | None
+    .checkout_mint_error: APIError | None
+```
+
+## Handling errors
+
+```python
+from solvapay import SolvaPay
+from solvapay.exceptions import (
+    AuthenticationError,
+    RateLimitError,
+    APIConnectionError,
+    PaywallRequired,
+)
+
+sv = SolvaPay()
+
+try:
+    sv.limits.check(customer_ref="cus_1", product_ref="prd_1")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except APIConnectionError:
+    print("Network failure — safe to retry with idempotency key")
+except PaywallRequired as e:
+    print(f"Paywall hit. Checkout: {e.checkout_url}")
+```
+
+## `request_id`
+
+Every `APIError` captures `request_id` from `x-request-id` or `x-correlation-id` response headers. Include this in support tickets.
+
+## Legacy alias
+
+`SolvaPayAPIError` is an alias for `APIError`. It emits `DeprecationWarning` and will be removed in v2.0. Use `APIError` directly.