kamiwaza-extensions-lib
Runtime library for Kamiwaza extensions. Provides FastAPI auth middleware, identity extraction, a typed Kamiwaza model client, and session management for extension backends.
This package is intentionally separate from kamiwaza-sdk: extension
backends need a lightweight async library, not the full SDK with its sync
HTTP client and 20+ service modules.
Install
pip install 'kamiwaza-extensions-lib>=0.6,<0.7'
Usage
from kamiwaza_extensions_lib import (
KamiwazaExtClient,
platform_request,
require_auth,
extract_identity,
)
Deployment-scoped ForwardAuth
On Envoy-routed extension deployments, the platform sets
FORWARDAUTH_SIGNATURE_REQUIRED=true, FORWARDAUTH_SIGNATURE_AUDIENCE to the
deployment UUID, and FORWARDAUTH_SIGNATURE_SECRET to that deployment's derived
verifier key. extract_identity() and require_auth() then verify Core's stable
signature before trusting user or workroom headers. Missing verifier settings,
an absent or modified signature, a different audience, or an expired timestamp
reject the request. A configured audience requires verification even if the
separate required flag is absent; a conflicting false flag is rejected.
X-User-Marking-Level is accepted only when Core's signature covers it; an
envelope from pre-ENG-8982 Core that signed the retired X-User-System-High
name still verifies (with no marking_level projected), and an unsigned claim
under either name, or non-empty values under both, is rejected. identity_from_headers() remains permissive in shape but
returns an anonymous identity when required verification fails. The platform
must supply the derived key; do not put its master signing secret in an extension.
Where server-side code dials the platform
The platform tells an extension's backend which in-cluster address to connect
to for platform and model calls through one variable,
KAMIWAZA_PLATFORM_GATEWAY_URL, an origin with no path. Two optional
companions describe how to verify it: KAMIWAZA_GATEWAY_CA_FILE (a PEM file to
add to the trust store for that origin) and KAMIWAZA_GATEWAY_TLS_SERVER_NAME
(the TLS server name for that origin; when absent, verify the request's public
host). Keep the platform's public host as the HTTP Host header: only the
connection target changes.
from kamiwaza_extensions_lib.platform_gateway import platform_gateway_from_env
gateway = platform_gateway_from_env() # None: use KAMIWAZA_ORIGIN
Kamiwaza 1.4 emits it on Envoy, GreyMatter and Istio installs. On GreyMatter it
is emitted only to extensions that declare KAMIWAZA_PLATFORM_GATEWAY_CONTRACT=1
in a service's environment, because readers built before this contract select
the canonical name without its TLS server name. On older
platforms the helper reads the deprecated KAMIWAZA_INTERNAL_GATEWAY_URL and
KAMIWAZA_TRAEFIK_GATEWAY_HOST instead, with a one-time warning. A value that
is not an origin raises PlatformGatewayContractError (an UnexpectedContextError) naming the
variable.
The gateway is only the connection target. platform_request() still builds
its URLs from KAMIWAZA_API_URL; code that builds its own platform or model
requests connects to the gateway origin, keeps the platform's public host as
the Host header, and adds KAMIWAZA_GATEWAY_CA_FILE on top of its default
trust store (for example ssl.create_default_context() followed by
load_verify_locations(ca_file)), never as a replacement for it. The
contract itself ships as contracts/platform_gateway/contract.json, with
Core's recorded render per provider for tests.
Calling platform APIs from an extension backend
Use platform_request() with the incoming FastAPI request and the exact,
canonical platform route. The path must be root-relative and include the
platform /api prefix; collection routes must include their canonical trailing
slash when the platform declares one:
response = await platform_request(
request,
"GET",
"/api/catalog/datasets/",
)
response.raise_for_status()
datasets = response.json()
The helper uses the container-routable platform URL, forwards the current
ForwardAuth envelope, and deliberately refuses to follow HTTP redirects. Set
the optional timeout= in seconds when the 30-second default is unsuitable.
Each call currently uses a short-lived client; connection pooling is tracked in
GitHub issue #63. Do not
construct absolute platform URLs or use a raw httpx.AsyncClient for
request-bound platform calls. Caller headers cannot replace the envelope's
authentication, routing, framing, or X-Request-Id correlation fields.
User-bound clients ignore HTTP_PROXY, HTTPS_PROXY, SSL_CERT_FILE, and
SSL_CERT_DIR. For a private CA, mount its PEM bundle in the backend container
and set KAMIWAZA_CA_BUNDLE to that file path. Do not disable certificate
verification in production.
For untrusted content, set max_response_bytes= to a positive integer to limit
the returned body, including error responses. This option is unreleased; it
requires a runtime-library release containing the bounded-response change.
Bounded calls request identity encoding and reject compressed responses before
reading the body. They close the stream on overflow or cancellation. The limit
bounds the retained body, rather than total process memory or network buffers.
Calls without a limit keep their existing behavior.
The helper raises:
ValueErrorfor invalid paths, methods, headers, or caller overridesMisboundAuthErrorwhen the platform-provided ForwardAuth envelope is malformed or contains an ambiguous duplicate fieldUnexpectedContextErrorwhenKAMIWAZA_API_URLis missing or invalid, or a bounded response uses compressed encoding despite requesting identity encodingPlatformRedirectError(a specializedUnexpectedContextError) when the canonical route redirectsPlatformOutageErrorfor network, timeout, or upstream protocol failuresPlatformResponseTooLargeErrorwhen a bounded response exceeds its byte limit
See CHANGELOG.md in this directory for release notes.
Metadata
Release files for kamiwaza-extensions-lib 0.6.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kamiwaza_extensions_lib-0.6.3.tar.gz | 57.0 kB | Without provenance | Details for kamiwaza_extensions_lib-0.6.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kamiwaza_extensions_lib-0.6.3-py3-none-any.whl | Python 3 | none | any | Details for kamiwaza_extensions_lib-0.6.3-py3-none-any.whl |
Total release size: 123.2 kB
Release files / kamiwaza_extensions_lib-0.6.3.tar.gz
| Download URL | kamiwaza_extensions_lib-0.6.3.tar.gz |
|---|---|
| Size | 57.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c08ba3f057a419ed6e1f7bc7c8ebbda0176d9e698edc88e42796f3a705f9720f
|
|
BLAKE2b-256 checksum How to use checksums |
298574f30a9c9d638218b9a96b4a2d9222d47ccc1b6e70081202f457338e5706
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / kamiwaza_extensions_lib-0.6.3-py3-none-any.whl
| Download URL | kamiwaza_extensions_lib-0.6.3-py3-none-any.whl |
|---|---|
| Size | 66.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ea842a44de0fff562394c089355404820a9378f4c429168e6bada449a97c0e20
|
|
BLAKE2b-256 checksum How to use checksums |
563e97c4155c4a74f884d973ae35fdb62a4655dd8d74e8cf27245fa7efa54dd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for kamiwaza-extensions-lib 0.6.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.