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.

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.2

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.2
File Size Uploaded Provenance Actions
kamiwaza_extensions_lib-0.6.2.tar.gz 49.6 kB Without provenance Details for kamiwaza_extensions_lib-0.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kamiwaza-extensions-lib 0.6.2
File Interpreter ABI Platform Actions
kamiwaza_extensions_lib-0.6.2-py3-none-any.whl Python 3 none any Details for kamiwaza_extensions_lib-0.6.2-py3-none-any.whl

Total release size: 106.6 kB

Release files / kamiwaza_extensions_lib-0.6.2.tar.gz

Download URL kamiwaza_extensions_lib-0.6.2.tar.gz
Size 49.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a7362a90fa8bf5d8706109f22f14d7d15731d7e3e4b9f057bb3bf91319a9d917
BLAKE2b-256 checksum
How to use checksums
e9b7ff68f3d1f27666919708b0bcbb4eb9dcc1f38e937ab26aa14cdd94b99365
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","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.2-py3-none-any.whl

Download URL kamiwaza_extensions_lib-0.6.2-py3-none-any.whl
Size 57.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
660a7e1f27002f4377a3a01829e43f987d1de8d18511c187324be8fa739b2f10
BLAKE2b-256 checksum
How to use checksums
9c6a7e67ee04d8aede1ae9cf0da5467a924363dfbf90bc0838b25fa6e72f0943
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","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.2

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