firetail-finchly 0.0.1__tar.gz

firetail_finchly-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest
+      - name: Check the package builds
+        run: python -m build

firetail_finchly-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: release
+
+# Publishes firetail_finchly when a version tag is pushed.
+# Uses PyPI trusted publishing: no PyPI token is stored. See README, "Release".
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check the tag matches the package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          version="$(python -c "exec(open('src/firetail_finchly/_version.py').read()); print(__version__)")"
+          if [ "v${version}" != "${TAG}" ]; then
+            echo "Tag ${TAG} does not match package version ${version}" >&2
+            exit 1
+          fi
+
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest
+      - run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

firetail_finchly-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.coverage
+.env
+.DS_Store

firetail_finchly-0.0.1/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `firetail_finchly`. Versions follow semver.
+
+## Unreleased
+
+## 0.0.1 - 2026-11-11
+
+The first release.
+
+- Package skeleton under its final name.
+- `load_config`: read and validate the `PLATFORM_*` settings.
+- `load_manifest`, `check_manifest`: load a manifest and check the fields
+  the SDK depends on.
+- `PLATFORM_API_VERSION`, `SUPPORTED_PLATFORM_API_VERSIONS`, `SDK_NAME`,
+  `SDK_VERSION`.
+- `IdentityVerifier`: verify the `x-platform-identity` token against the
+  gateway's published keys. Rejections are an `IdentityError` with a
+  `reason` from the specification. Tested against the identity token
+  conformance vectors.
+- New dependency: `PyJWT[crypto]`.
+- `ServiceClient`: call another service through the gateway, as the
+  service itself or for a user. Makes the instance key, registers it with
+  the service credential, and extends it before it expires. `url` and
+  `headers` let another HTTP client make the call.
+- `load_config` reads `PLATFORM_SERVICE_CREDENTIAL`.
+- New error codes: `service_call_invalid`, `service_key_rejected`.

firetail_finchly-0.0.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: firetail_finchly
+Version: 0.0.1
+Summary: Python SDK for the Finchly platform
+Project-URL: Repository, https://github.com/firetail-io/finchly-sdk-py
+Project-URL: Changelog, https://github.com/firetail-io/finchly-sdk-py/blob/main/CHANGELOG.md
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyjwt[crypto]<3,>=2.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# firetail_finchly
+
+Python SDK for the [Finchly](https://github.com/firetail-io/finchly)
+platform. A service or app uses it to register with a Finchly deployment,
+verify who is calling it, and reach the platform's database, object store,
+queue and other services.
+
+Status: early. The package is tested, but only the first four modules
+exist.
+
+The SDK implements the platform API, which is specified in
+`firetail-io/finchly` under `spec/`. This release speaks platform API `v1`
+(draft).
+
+## Install
+
+```
+pip install firetail_finchly
+```
+
+Requires Python 3.10 or later. Depends on PyJWT with its `crypto` extra.
+
+## Use
+
+```python
+from firetail_finchly import load_config, load_manifest
+
+config = load_config()                         # reads PLATFORM_* settings
+manifest = load_manifest(config.manifest_path)
+```
+
+Both raise a `FinchlyError` with a stable `code` and a `problems` tuple that
+names everything wrong, so a misconfigured container fails once with the
+full picture.
+
+### Who is calling
+
+The gateway puts a short-lived signed token in the `x-platform-identity`
+header of every request it proxies. It is the only identity a service
+should accept.
+
+```python
+from firetail_finchly import IdentityError, IdentityVerifier
+
+# Once, at startup. It caches the gateway's issuer and signing keys, and
+# is safe to share between threads.
+identity = IdentityVerifier(slug=manifest["slug"], gateway_url=config.gateway_url)
+
+# Per request.
+try:
+    caller = identity.from_headers(request.headers)
+    caller.subject   # user id, or "service:<slug>"
+    caller.email     # None for a service calling as itself
+    caller.groups    # platform groups
+    caller.roles     # roles for this service: "user", "operator"
+    caller.actor     # "service:<slug>" when a service acts for the user
+except IdentityError as err:
+    ...  # Unauthenticated: respond 401. err.reason is for logs only.
+```
+
+Any other `FinchlyError` from the verifier means the gateway could not be
+reached; respond 503.
+
+A token is rejected unless it is signed with ES256 by a key the gateway
+publishes, names that gateway as issuer and this service as its only
+audience, and has not expired. The rules are in `spec/identity-token.md` in
+`firetail-io/finchly`.
+
+No other header is ever consulted. On a path the manifest declares in
+`publicPaths` there is no token, and the service authenticates the request
+itself.
+
+### Calling another service
+
+Services never address each other directly. A call goes through the
+gateway, signed by this instance's own key.
+
+```python
+from firetail_finchly import ServiceClient
+
+# Once, at startup. Safe to share between threads.
+service = ServiceClient(
+    slug=manifest["slug"],
+    gateway_url=config.gateway_url,
+    credential=config.service_credential,
+)
+service.start()   # optional: fail now, not on the first call
+
+# As the service itself.
+response = service.call(
+    "notification-service",
+    "/api/send",
+    method="POST",
+    headers={"Content-Type": "application/json"},
+    body=b'{"text": "hello"}',
+)
+response.status, response.headers, response.body, response.json()
+
+# For a user: the target sees that user, and this service acting for them.
+service.call("notification-service", "/api/inbox", as_user=caller.subject)
+```
+
+`call` returns the response, whatever its status.
+
+- **403** means this service's manifest does not list the target in
+  `calls`, or the user has no access to the target.
+- **A redirect is handed back, not followed.**
+- **Nothing is retried.** After a 401 the next call registers the key
+  again, in case the gateway no longer knows it.
+
+To use another HTTP client, such as `requests` or `httpx`, take the address
+and the header from the client and send the request yourself. A token is
+for one target and is valid for a minute, so get fresh headers each time:
+
+```python
+requests.post(
+    service.url("notification-service", "/api/send"),
+    headers=service.headers("notification-service"),
+    json={"text": "hello"},
+    allow_redirects=False,
+)
+```
+
+The instance makes an ES256 key pair in memory the first time it is needed.
+The private half never leaves the process. The public half is registered
+with the gateway using the credential the service was deployed with, and
+extended by itself for as long as the instance runs. The rules are in
+`spec/service-token.md` and `spec/registration.md` in `firetail-io/finchly`.
+
+Only a built-in service has a credential. An app's key is accepted when it
+registers, which the `app` module will do; until then an app cannot use
+`service`.
+
+### Settings
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `PLATFORM_GATEWAY_URL` | yes | The gateway's internal address |
+| `PLATFORM_MANIFEST_PATH` | no | Manifest path in the container. Default `/finchly/manifest.json` |
+| `PLATFORM_APP_ADDRESS` | no | Address the gateway should use to reach this service |
+| `PLATFORM_ENROLMENT_TOKEN` | no | Token for self-registration |
+| `PLATFORM_SERVICE_CREDENTIAL` | no | What a built-in service registers its instance key with |
+
+The enrolment token and the service credential are left out of the
+config's `repr`, so logging the config does not leak them.
+
+## Modules
+
+The Python SDK may trail the Node SDK for modules that only Node services
+use.
+
+| Module | What it does | State |
+|---|---|---|
+| `config` | Read and validate the platform settings | Done |
+| `manifest` | Load the manifest and check what the SDK depends on | Done |
+| `identity` | Verify `x-platform-identity` | Done. Directory lookups (`list_users`, `members_of`) and `require_*` helpers are planned |
+| `app` | Register with the platform, serve `/_platform/*`, renew keys, fetch settings | Next |
+| `service` | Call other services through the gateway, as the service or for a user | Done for built-in services. An app's first key waits on `app` |
+| `db` | PostgreSQL: queries, transactions, advisory locks, migrations | Planned |
+| `blobs` | Object storage with conditional writes | Planned |
+| `queue` | Publish, lease, ack, nack | Planned |
+| `secrets` | Secrets and envelope encryption | Planned |
+| `llm` | Model calls through the platform | Planned |
+| `audit`, `usage`, `notify`, `schedule`, `connectors` | Clients for platform services | Planned |
+| `ui` | Shared header, footer and theme | Not planned; Node only |
+
+The manifest check here is not the full schema. The platform runs the full
+check at registration and is the authority.
+
+## Develop
+
+```
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest
+```
+
+Without a local Python environment, run them in a container:
+
+```
+docker run --rm -v "$PWD":/src:ro python:3.12-slim sh -c \
+  "cp -r /src /w && cd /w && pip install -q -e '.[dev]' && python -m pytest -q"
+```
+
+### Conformance vectors
+
+`tests/conformance/` holds test vectors copied from `firetail-io/finchly`
+(`conformance/vectors/`). Both SDKs must reach the verdict each vector
+states. Do not edit them here: change them in `finchly`, regenerate, and
+copy the file to both SDK repositories. Until `finchly` publishes its
+conformance suite as an image, the copy is made by hand.
+
+## Release
+
+Each package version follows semver, independent of the Node SDK and of the
+platform.
+
+1. Changes land on `main` by pull request. Each one adds a line to
+   `CHANGELOG.md` under "Unreleased".
+2. To release, set the version in `src/firetail_finchly/_version.py`, move
+   the changelog entries under that version, merge, and tag the merge
+   commit `v` plus the version, for example `v1.2.0`.
+3. The `release` workflow checks the tag matches the version, runs the
+   tests, builds the sdist and wheel, and publishes.
+4. A release candidate uses the PEP 440 form, `1.2.0rc1`, tagged
+   `v1.2.0rc1`. pip does not install pre-releases unless asked.
+5. A bad release is yanked on PyPI and followed by a patch release.
+
+Publishing uses PyPI trusted publishing: the workflow proves its identity to
+PyPI with its GitHub Actions token, so no PyPI token is stored in this
+repository.
+
+One-time setup, not yet done:
+
+- On PyPI, add a pending trusted publisher for the project
+  `firetail_finchly`: owner `firetail-io`, repository `finchly-sdk-py`,
+  workflow `release.yml`, environment `pypi`.
+- Create a GitHub environment called `pypi` in this repository, restricted
+  to tags.
+
+Still to add: the conformance suite from `firetail-io/finchly`, run in CI on
+every change, once that suite exists.

firetail_finchly-0.0.1/README.md

@@ -0,0 +1,222 @@
+# firetail_finchly
+
+Python SDK for the [Finchly](https://github.com/firetail-io/finchly)
+platform. A service or app uses it to register with a Finchly deployment,
+verify who is calling it, and reach the platform's database, object store,
+queue and other services.
+
+Status: early. The package is tested, but only the first four modules
+exist.
+
+The SDK implements the platform API, which is specified in
+`firetail-io/finchly` under `spec/`. This release speaks platform API `v1`
+(draft).
+
+## Install
+
+```
+pip install firetail_finchly
+```
+
+Requires Python 3.10 or later. Depends on PyJWT with its `crypto` extra.
+
+## Use
+
+```python
+from firetail_finchly import load_config, load_manifest
+
+config = load_config()                         # reads PLATFORM_* settings
+manifest = load_manifest(config.manifest_path)
+```
+
+Both raise a `FinchlyError` with a stable `code` and a `problems` tuple that
+names everything wrong, so a misconfigured container fails once with the
+full picture.
+
+### Who is calling
+
+The gateway puts a short-lived signed token in the `x-platform-identity`
+header of every request it proxies. It is the only identity a service
+should accept.
+
+```python
+from firetail_finchly import IdentityError, IdentityVerifier
+
+# Once, at startup. It caches the gateway's issuer and signing keys, and
+# is safe to share between threads.
+identity = IdentityVerifier(slug=manifest["slug"], gateway_url=config.gateway_url)
+
+# Per request.
+try:
+    caller = identity.from_headers(request.headers)
+    caller.subject   # user id, or "service:<slug>"
+    caller.email     # None for a service calling as itself
+    caller.groups    # platform groups
+    caller.roles     # roles for this service: "user", "operator"
+    caller.actor     # "service:<slug>" when a service acts for the user
+except IdentityError as err:
+    ...  # Unauthenticated: respond 401. err.reason is for logs only.
+```
+
+Any other `FinchlyError` from the verifier means the gateway could not be
+reached; respond 503.
+
+A token is rejected unless it is signed with ES256 by a key the gateway
+publishes, names that gateway as issuer and this service as its only
+audience, and has not expired. The rules are in `spec/identity-token.md` in
+`firetail-io/finchly`.
+
+No other header is ever consulted. On a path the manifest declares in
+`publicPaths` there is no token, and the service authenticates the request
+itself.
+
+### Calling another service
+
+Services never address each other directly. A call goes through the
+gateway, signed by this instance's own key.
+
+```python
+from firetail_finchly import ServiceClient
+
+# Once, at startup. Safe to share between threads.
+service = ServiceClient(
+    slug=manifest["slug"],
+    gateway_url=config.gateway_url,
+    credential=config.service_credential,
+)
+service.start()   # optional: fail now, not on the first call
+
+# As the service itself.
+response = service.call(
+    "notification-service",
+    "/api/send",
+    method="POST",
+    headers={"Content-Type": "application/json"},
+    body=b'{"text": "hello"}',
+)
+response.status, response.headers, response.body, response.json()
+
+# For a user: the target sees that user, and this service acting for them.
+service.call("notification-service", "/api/inbox", as_user=caller.subject)
+```
+
+`call` returns the response, whatever its status.
+
+- **403** means this service's manifest does not list the target in
+  `calls`, or the user has no access to the target.
+- **A redirect is handed back, not followed.**
+- **Nothing is retried.** After a 401 the next call registers the key
+  again, in case the gateway no longer knows it.
+
+To use another HTTP client, such as `requests` or `httpx`, take the address
+and the header from the client and send the request yourself. A token is
+for one target and is valid for a minute, so get fresh headers each time:
+
+```python
+requests.post(
+    service.url("notification-service", "/api/send"),
+    headers=service.headers("notification-service"),
+    json={"text": "hello"},
+    allow_redirects=False,
+)
+```
+
+The instance makes an ES256 key pair in memory the first time it is needed.
+The private half never leaves the process. The public half is registered
+with the gateway using the credential the service was deployed with, and
+extended by itself for as long as the instance runs. The rules are in
+`spec/service-token.md` and `spec/registration.md` in `firetail-io/finchly`.
+
+Only a built-in service has a credential. An app's key is accepted when it
+registers, which the `app` module will do; until then an app cannot use
+`service`.
+
+### Settings
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `PLATFORM_GATEWAY_URL` | yes | The gateway's internal address |
+| `PLATFORM_MANIFEST_PATH` | no | Manifest path in the container. Default `/finchly/manifest.json` |
+| `PLATFORM_APP_ADDRESS` | no | Address the gateway should use to reach this service |
+| `PLATFORM_ENROLMENT_TOKEN` | no | Token for self-registration |
+| `PLATFORM_SERVICE_CREDENTIAL` | no | What a built-in service registers its instance key with |
+
+The enrolment token and the service credential are left out of the
+config's `repr`, so logging the config does not leak them.
+
+## Modules
+
+The Python SDK may trail the Node SDK for modules that only Node services
+use.
+
+| Module | What it does | State |
+|---|---|---|
+| `config` | Read and validate the platform settings | Done |
+| `manifest` | Load the manifest and check what the SDK depends on | Done |
+| `identity` | Verify `x-platform-identity` | Done. Directory lookups (`list_users`, `members_of`) and `require_*` helpers are planned |
+| `app` | Register with the platform, serve `/_platform/*`, renew keys, fetch settings | Next |
+| `service` | Call other services through the gateway, as the service or for a user | Done for built-in services. An app's first key waits on `app` |
+| `db` | PostgreSQL: queries, transactions, advisory locks, migrations | Planned |
+| `blobs` | Object storage with conditional writes | Planned |
+| `queue` | Publish, lease, ack, nack | Planned |
+| `secrets` | Secrets and envelope encryption | Planned |
+| `llm` | Model calls through the platform | Planned |
+| `audit`, `usage`, `notify`, `schedule`, `connectors` | Clients for platform services | Planned |
+| `ui` | Shared header, footer and theme | Not planned; Node only |
+
+The manifest check here is not the full schema. The platform runs the full
+check at registration and is the authority.
+
+## Develop
+
+```
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest
+```
+
+Without a local Python environment, run them in a container:
+
+```
+docker run --rm -v "$PWD":/src:ro python:3.12-slim sh -c \
+  "cp -r /src /w && cd /w && pip install -q -e '.[dev]' && python -m pytest -q"
+```
+
+### Conformance vectors
+
+`tests/conformance/` holds test vectors copied from `firetail-io/finchly`
+(`conformance/vectors/`). Both SDKs must reach the verdict each vector
+states. Do not edit them here: change them in `finchly`, regenerate, and
+copy the file to both SDK repositories. Until `finchly` publishes its
+conformance suite as an image, the copy is made by hand.
+
+## Release
+
+Each package version follows semver, independent of the Node SDK and of the
+platform.
+
+1. Changes land on `main` by pull request. Each one adds a line to
+   `CHANGELOG.md` under "Unreleased".
+2. To release, set the version in `src/firetail_finchly/_version.py`, move
+   the changelog entries under that version, merge, and tag the merge
+   commit `v` plus the version, for example `v1.2.0`.
+3. The `release` workflow checks the tag matches the version, runs the
+   tests, builds the sdist and wheel, and publishes.
+4. A release candidate uses the PEP 440 form, `1.2.0rc1`, tagged
+   `v1.2.0rc1`. pip does not install pre-releases unless asked.
+5. A bad release is yanked on PyPI and followed by a patch release.
+
+Publishing uses PyPI trusted publishing: the workflow proves its identity to
+PyPI with its GitHub Actions token, so no PyPI token is stored in this
+repository.
+
+One-time setup, not yet done:
+
+- On PyPI, add a pending trusted publisher for the project
+  `firetail_finchly`: owner `firetail-io`, repository `finchly-sdk-py`,
+  workflow `release.yml`, environment `pypi`.
+- Create a GitHub environment called `pypi` in this repository, restricted
+  to tags.
+
+Still to add: the conformance suite from `firetail-io/finchly`, run in CI on
+every change, once that suite exists.

firetail_finchly-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "firetail_finchly"
+dynamic = ["version"]
+description = "Python SDK for the Finchly platform"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "PyJWT[crypto]>=2.8,<3",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/firetail-io/finchly-sdk-py"
+Changelog = "https://github.com/firetail-io/finchly-sdk-py/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2"]
+
+[tool.hatch.version]
+path = "src/firetail_finchly/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/firetail_finchly"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

firetail_finchly-0.0.1/src/firetail_finchly/__init__.py

@@ -0,0 +1,37 @@
+"""Python SDK for the Finchly platform."""
+
+from ._version import __version__
+from .config import DEFAULT_MANIFEST_PATH, PlatformConfig, load_config
+from .errors import IDENTITY_REJECTIONS, FinchlyError, IdentityError
+from .identity import IDENTITY_HEADER, Identity, IdentityVerifier
+from .manifest import check_manifest, load_manifest
+from .platform_api import (
+    MANIFEST_VERSION,
+    PLATFORM_API_VERSION,
+    SDK_NAME,
+    SDK_VERSION,
+    SUPPORTED_PLATFORM_API_VERSIONS,
+)
+from .service import ServiceClient, ServiceResponse
+
+__all__ = [
+    "DEFAULT_MANIFEST_PATH",
+    "FinchlyError",
+    "IDENTITY_HEADER",
+    "IDENTITY_REJECTIONS",
+    "Identity",
+    "IdentityError",
+    "IdentityVerifier",
+    "MANIFEST_VERSION",
+    "PLATFORM_API_VERSION",
+    "PlatformConfig",
+    "SDK_NAME",
+    "SDK_VERSION",
+    "SUPPORTED_PLATFORM_API_VERSIONS",
+    "ServiceClient",
+    "ServiceResponse",
+    "__version__",
+    "check_manifest",
+    "load_config",
+    "load_manifest",
+]

firetail_finchly-0.0.1/src/firetail_finchly/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"