Skip to main content

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:

  • ValueError for invalid paths, methods, headers, or caller overrides
  • MisboundAuthError when the platform-provided ForwardAuth envelope is malformed or contains an ambiguous duplicate field
  • UnexpectedContextError when KAMIWAZA_API_URL is missing or invalid, or a bounded response uses compressed encoding despite requesting identity encoding
  • PlatformRedirectError (a specialized UnexpectedContextError) when the canonical route redirects
  • PlatformOutageError for network, timeout, or upstream protocol failures
  • PlatformResponseTooLargeError when 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)

Source distribution for kamiwaza-extensions-lib 0.6.3
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)

Table of built distributions (wheels) for kamiwaza-extensions-lib 0.6.3
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page