foil-server 0.2.3__tar.gz

foil_server-0.2.3/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - codex/**
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m pip install -e .
+      - run: python -m unittest tests.test_client tests.test_contract tests.test_sealed_token
+      - run: python -m build
+
+  spec-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Check synced spec
+        run: bash ./scripts/check-spec-sync.sh
+
+  live-smoke:
+    runs-on: ubuntu-latest
+    needs: [test, spec-sync]
+    if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main') }}
+    env:
+      FOIL_LIVE_SMOKE: "1"
+      FOIL_SMOKE_SECRET_KEY: ${{ secrets.FOIL_SMOKE_SECRET_KEY }}
+      FOIL_SMOKE_ORGANIZATION_ID: ${{ secrets.FOIL_SMOKE_ORGANIZATION_ID }}
+      FOIL_SMOKE_BASE_URL: ${{ secrets.FOIL_SMOKE_BASE_URL }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Require smoke secrets
+        if: ${{ env.FOIL_SMOKE_SECRET_KEY == '' || env.FOIL_SMOKE_ORGANIZATION_ID == '' }}
+        run: |
+          echo "FOIL_SMOKE_SECRET_KEY and FOIL_SMOKE_ORGANIZATION_ID are required for live smoke tests."
+          exit 1
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e .
+      - name: Run live smoke suite
+        run: python -m unittest tests.test_live

foil_server-0.2.3/.github/workflows/release.yml

@@ -0,0 +1,142 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm_version:
+        description: Version in pyproject.toml to release
+        required: true
+        type: string
+      dry_run:
+        description: Build and verify without tagging or publishing
+        required: true
+        default: true
+        type: boolean
+
+permissions:
+  contents: read
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
+      commit_sha: ${{ steps.commit.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - id: commit
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - id: version
+        run: |
+          VERSION=$(python - <<'PY'
+          import pathlib
+          import tomllib
+
+          with pathlib.Path("pyproject.toml").open("rb") as handle:
+              data = tomllib.load(handle)
+          print(data["project"]["version"])
+          PY
+          )
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Validate release inputs
+        env:
+          EXPECTED_VERSION: ${{ inputs.confirm_version }}
+          ACTUAL_VERSION: ${{ steps.version.outputs.version }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          if [ "$EXPECTED_VERSION" != "$ACTUAL_VERSION" ]; then
+            echo "Expected version $EXPECTED_VERSION, found $ACTUAL_VERSION."
+            exit 1
+          fi
+
+          if [ "$DRY_RUN" != "true" ] && [ "$REF_NAME" != "main" ]; then
+            echo "Real releases must run from main."
+            exit 1
+          fi
+
+      - name: Ensure release tag is new
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          git fetch --tags --force
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "Tag $TAG already exists."
+            exit 1
+          fi
+
+      - run: python -m pip install --upgrade pip build
+      - run: python -m pip install -e .
+      - run: python -m unittest tests.test_client tests.test_contract tests.test_sealed_token
+      - run: python -m build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-artifacts
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    if: ${{ !inputs.dry_run }}
+    needs: prepare
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.prepare.outputs.commit_sha }}
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-artifacts
+          path: dist
+
+      - name: Ensure release is still new
+        env:
+          TAG: ${{ needs.prepare.outputs.tag }}
+        run: |
+          git fetch --tags --force
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "Tag $TAG already exists."
+            exit 1
+          fi
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "GitHub release $TAG already exists."
+            exit 1
+          fi
+
+      - name: Create and push release tag
+        env:
+          TAG: ${{ needs.prepare.outputs.tag }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+      - name: Create GitHub release
+        env:
+          TAG: ${{ needs.prepare.outputs.tag }}
+        run: gh release create "$TAG" dist/* --title "$TAG" --generate-notes --verify-tag

foil_server-0.2.3/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/

foil_server-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ABXY Labs
+
+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.

foil_server-0.2.3/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: foil-server
+Version: 0.2.3
+Summary: Official Foil Python server SDK
+Project-URL: Homepage, https://github.com/abxy-labs/foil-server-python
+Project-URL: Repository, https://github.com/abxy-labs/foil-server-python
+Project-URL: Issues, https://github.com/abxy-labs/foil-server-python/issues
+Author: ABXY Labs
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: cryptography<47,>=42
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# Foil Python Library
+
+![Preview](https://img.shields.io/badge/status-preview-111827)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)
+![License: MIT](https://img.shields.io/badge/license-MIT-0f766e.svg)
+
+The Foil Python library provides convenient access to the Foil API from applications written in Python. It includes a synchronous client for Sessions, Fingerprints, Organizations, Organization API key management, sealed token verification, Gate, and Gate delivery/webhook helpers.
+
+The library also provides:
+
+- a fast configuration path using `FOIL_SECRET_KEY`
+- iterator helpers for cursor-based pagination
+- structured API errors and built-in sealed token verification
+- webhook endpoint management, test sends, and event delivery history
+- public, bearer-token, and secret-key auth modes for Gate flows
+- Gate delivery/webhook helpers
+
+## Documentation
+
+See the [Foil docs](https://usefoil.com/docs) and [API reference](https://usefoil.com/docs/api-reference/introduction).
+
+## Installation
+
+You don't need this source code unless you want to modify the package. If you just want to use the package, run:
+
+```bash
+pip install foil-server
+```
+
+## Requirements
+
+- Python 3.10+
+
+## Usage
+
+Use `FOIL_SECRET_KEY` or `secret_key=...` for core detect APIs. For public or bearer-auth Gate flows, the client can also be created without a secret key:
+
+```python
+from foil_server import Foil
+
+client = Foil(secret_key="sk_live_...")
+
+page = client.sessions.list(verdict="bot", limit=25)
+session = client.sessions.get("sid_123")
+```
+
+### Sealed token verification
+
+```python
+from foil_server import safe_verify_foil_token
+
+result = safe_verify_foil_token(
+    sealed_token,
+    "sk_live_...",
+)
+
+if result.ok:
+    print(result.data.verdict, result.data.score)
+else:
+    print(result.error)
+```
+
+### Pagination
+
+```python
+for session in client.sessions.iter(search="signup"):
+    print(session.id, session.latest_decision.verdict)
+```
+
+### Fingerprints
+
+```python
+page = client.fingerprints.list(sort="seen_count")
+fingerprint = client.fingerprints.get("vid_123")
+```
+
+### Organizations
+
+```python
+organization = client.organizations.get("org_123")
+updated = client.organizations.update("org_123", name="New Name")
+```
+
+### Organization API keys
+
+```python
+created = client.organizations.api_keys.create(
+    "org_123",
+    name="Production",
+    type="secret",
+    scopes=["sessions:list", "sessions:read"],
+)
+
+client.organizations.api_keys.revoke("org_123", created.id)
+```
+
+### Webhooks
+
+```python
+endpoint = client.webhooks.create_endpoint(
+    "org_123",
+    name="Production alerts",
+    url="https://example.com/foil/webhook",
+    event_types=["session.result.persisted", "gate.session.approved"],
+)
+
+events = client.webhooks.list_events(
+    "org_123",
+    endpoint_id=endpoint.id,
+    type="session.result.persisted",
+)
+
+print(events.items[0].webhook_deliveries[0].status)
+```
+
+### Gate APIs
+
+```python
+from foil_server import Foil, create_delivery_key_pair
+
+client = Foil()
+services = client.gate.registry.list()
+session = client.gate.sessions.create(
+    service_id="foil",
+    account_name="my-project",
+    delivery=create_delivery_key_pair().delivery,
+)
+
+print(services[0].id, session.consent_url)
+```
+
+### Gate delivery and webhook helpers
+
+```python
+from foil_server import (
+    create_delivery_key_pair,
+    create_gate_approved_webhook_response,
+    decrypt_gate_delivery_envelope,
+    parse_webhook_event,
+    verify_gate_webhook_signature,
+)
+
+key_pair = create_delivery_key_pair()
+response = create_gate_approved_webhook_response(
+    {
+        "delivery": key_pair.delivery,
+        "outputs": {
+            "FOIL_PUBLISHABLE_KEY": "pk_live_...",
+            "FOIL_SECRET_KEY": "sk_live_...",
+        },
+    }
+)
+payload = decrypt_gate_delivery_envelope(key_pair.private_key, response.encrypted_delivery)
+print(payload.outputs["FOIL_SECRET_KEY"])
+raw_body = '{"id":"wevt_123","object":"webhook_event","type":"webhook.test","created":"2026-04-26T00:00:00.000Z","data":{}}'
+print(
+    verify_gate_webhook_signature(
+        secret="whsec_test",
+        timestamp="1735776000",
+        raw_body=raw_body,
+        signature="…",
+    )
+)
+event = parse_webhook_event(raw_body)
+print(event.type)
+```
+
+### Error handling
+
+```python
+from foil_server import FoilApiError
+
+try:
+    client.sessions.list(limit=999)
+except FoilApiError as error:
+    print(error.status, error.code, error.message)
+```
+
+## Support
+
+If you need help integrating Foil, start with [usefoil.com/docs](https://usefoil.com/docs).

foil_server-0.2.3/README.md

@@ -0,0 +1,181 @@
+# Foil Python Library
+
+![Preview](https://img.shields.io/badge/status-preview-111827)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)
+![License: MIT](https://img.shields.io/badge/license-MIT-0f766e.svg)
+
+The Foil Python library provides convenient access to the Foil API from applications written in Python. It includes a synchronous client for Sessions, Fingerprints, Organizations, Organization API key management, sealed token verification, Gate, and Gate delivery/webhook helpers.
+
+The library also provides:
+
+- a fast configuration path using `FOIL_SECRET_KEY`
+- iterator helpers for cursor-based pagination
+- structured API errors and built-in sealed token verification
+- webhook endpoint management, test sends, and event delivery history
+- public, bearer-token, and secret-key auth modes for Gate flows
+- Gate delivery/webhook helpers
+
+## Documentation
+
+See the [Foil docs](https://usefoil.com/docs) and [API reference](https://usefoil.com/docs/api-reference/introduction).
+
+## Installation
+
+You don't need this source code unless you want to modify the package. If you just want to use the package, run:
+
+```bash
+pip install foil-server
+```
+
+## Requirements
+
+- Python 3.10+
+
+## Usage
+
+Use `FOIL_SECRET_KEY` or `secret_key=...` for core detect APIs. For public or bearer-auth Gate flows, the client can also be created without a secret key:
+
+```python
+from foil_server import Foil
+
+client = Foil(secret_key="sk_live_...")
+
+page = client.sessions.list(verdict="bot", limit=25)
+session = client.sessions.get("sid_123")
+```
+
+### Sealed token verification
+
+```python
+from foil_server import safe_verify_foil_token
+
+result = safe_verify_foil_token(
+    sealed_token,
+    "sk_live_...",
+)
+
+if result.ok:
+    print(result.data.verdict, result.data.score)
+else:
+    print(result.error)
+```
+
+### Pagination
+
+```python
+for session in client.sessions.iter(search="signup"):
+    print(session.id, session.latest_decision.verdict)
+```
+
+### Fingerprints
+
+```python
+page = client.fingerprints.list(sort="seen_count")
+fingerprint = client.fingerprints.get("vid_123")
+```
+
+### Organizations
+
+```python
+organization = client.organizations.get("org_123")
+updated = client.organizations.update("org_123", name="New Name")
+```
+
+### Organization API keys
+
+```python
+created = client.organizations.api_keys.create(
+    "org_123",
+    name="Production",
+    type="secret",
+    scopes=["sessions:list", "sessions:read"],
+)
+
+client.organizations.api_keys.revoke("org_123", created.id)
+```
+
+### Webhooks
+
+```python
+endpoint = client.webhooks.create_endpoint(
+    "org_123",
+    name="Production alerts",
+    url="https://example.com/foil/webhook",
+    event_types=["session.result.persisted", "gate.session.approved"],
+)
+
+events = client.webhooks.list_events(
+    "org_123",
+    endpoint_id=endpoint.id,
+    type="session.result.persisted",
+)
+
+print(events.items[0].webhook_deliveries[0].status)
+```
+
+### Gate APIs
+
+```python
+from foil_server import Foil, create_delivery_key_pair
+
+client = Foil()
+services = client.gate.registry.list()
+session = client.gate.sessions.create(
+    service_id="foil",
+    account_name="my-project",
+    delivery=create_delivery_key_pair().delivery,
+)
+
+print(services[0].id, session.consent_url)
+```
+
+### Gate delivery and webhook helpers
+
+```python
+from foil_server import (
+    create_delivery_key_pair,
+    create_gate_approved_webhook_response,
+    decrypt_gate_delivery_envelope,
+    parse_webhook_event,
+    verify_gate_webhook_signature,
+)
+
+key_pair = create_delivery_key_pair()
+response = create_gate_approved_webhook_response(
+    {
+        "delivery": key_pair.delivery,
+        "outputs": {
+            "FOIL_PUBLISHABLE_KEY": "pk_live_...",
+            "FOIL_SECRET_KEY": "sk_live_...",
+        },
+    }
+)
+payload = decrypt_gate_delivery_envelope(key_pair.private_key, response.encrypted_delivery)
+print(payload.outputs["FOIL_SECRET_KEY"])
+raw_body = '{"id":"wevt_123","object":"webhook_event","type":"webhook.test","created":"2026-04-26T00:00:00.000Z","data":{}}'
+print(
+    verify_gate_webhook_signature(
+        secret="whsec_test",
+        timestamp="1735776000",
+        raw_body=raw_body,
+        signature="…",
+    )
+)
+event = parse_webhook_event(raw_body)
+print(event.type)
+```
+
+### Error handling
+
+```python
+from foil_server import FoilApiError
+
+try:
+    client.sessions.list(limit=999)
+except FoilApiError as error:
+    print(error.status, error.code, error.message)
+```
+
+## Support
+
+If you need help integrating Foil, start with [usefoil.com/docs](https://usefoil.com/docs).

foil_server-0.2.3/RELEASING.md

@@ -0,0 +1,35 @@
+# Releasing `foil-server`
+
+This repository uses a manual `release.yml` workflow. Versions are independent from the other Foil server SDKs.
+
+## Before the first real release
+
+Configure these GitHub and registry settings:
+
+1. Create a protected GitHub environment named `release` with required reviewer approval.
+2. Create the `foil-server` project on PyPI if it does not already exist.
+3. Add a pending PyPI trusted publisher for:
+   - repository: `abxy-labs/foil-server-python`
+   - workflow: `.github/workflows/release.yml`
+   - environment: `release`
+
+## Release flow
+
+1. Bump `pyproject.toml` to the target version in a pull request.
+2. Merge the version bump to `main`.
+3. Open GitHub Actions and run `Release`.
+4. Set `confirm_version` to the exact `pyproject.toml` version.
+5. Run a `dry_run=true` release first.
+6. Re-run with `dry_run=false` once the dry run looks correct and the `release` environment approval is in place.
+
+## What the workflow does
+
+- reads the release version from `pyproject.toml`
+- reruns the equivalent of the repo checks
+- builds the wheel and source distribution with `python -m build`
+- on real releases:
+  - creates tag `vX.Y.Z`
+  - publishes `foil-server` to PyPI with trusted publishing
+  - creates a GitHub Release with the built artifacts attached
+
+GitHub Release notes use autogenerated notes. There is no prerelease channel in this phase.