swarmauri_keyprovider_remote_jwks 0.2.0.dev34
Remote JWKS-backed key provider for verification-only use
Requires Python: <3.13,>=3.10
Keywords: swarmauri, sdk, standards, keyprovider, remote, jwks, key-management

![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)


<p align="center">
    <a href="https://pypi.org/project/swarmauri_keyprovider_remote_jwks/">
        <img src="https://img.shields.io/pypi/dm/swarmauri_keyprovider_remote_jwks" alt="PyPI - Downloads"/></a>
    <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/standards/swarmauri_keyprovider_remote_jwks/">
        <img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/standards/swarmauri_keyprovider_remote_jwks.svg"/></a>
    <a href="https://pypi.org/project/swarmauri_keyprovider_remote_jwks/">
        <img src="https://img.shields.io/pypi/pyversions/swarmauri_keyprovider_remote_jwks" alt="PyPI - Python Version"/></a>
    <a href="https://pypi.org/project/swarmauri_keyprovider_remote_jwks/">
        <img src="https://img.shields.io/pypi/l/swarmauri_keyprovider_remote_jwks" alt="PyPI - License"/></a>
    <a href="https://pypi.org/project/swarmauri_keyprovider_remote_jwks/">
        <img src="https://img.shields.io/pypi/v/swarmauri_keyprovider_remote_jwks?label=swarmauri_keyprovider_remote_jwks&color=green" alt="PyPI - swarmauri_keyprovider_remote_jwks"/></a>
</p>

---

# Swarmauri Remote JWKS Key Provider

Key provider backed by a remote JWKS endpoint with local key management.

## Features

- Accepts either a direct JWKS URL or an OpenID Connect issuer and resolves the
  discovery document automatically.
- Caches the remote JWKS in memory with TTL support, conditional requests, and
  thread-safe refreshes through `refresh(force=True)`.
- Supports versioned key identifiers such as `kid.version` when discovering
  remote public keys.
- Embeds the standard `LocalKeyProvider` so that services can create, rotate,
  import, and destroy local keys without leaving memory.
- Exposes convenience helpers like `random_bytes()` and `hkdf()` for local
  cryptographic operations alongside the remote verification flow.

## Installation

Install the package with your preferred Python packaging tool:

```bash
pip install swarmauri_keyprovider_remote_jwks
```

```bash
poetry add swarmauri_keyprovider_remote_jwks
```

```bash
uv pip install swarmauri_keyprovider_remote_jwks
```

## Usage

The provider fetches verification keys from a remote JWKS URL or through an
OpenID Connect (OIDC) issuer.  It also embeds an in-memory key provider to
create and manage local keys.  The example below fetches a JWK from a JWKS
endpoint and prints its public fields:

```python
import asyncio
from swarmauri_keyprovider_remote_jwks import RemoteJwksKeyProvider


async def main() -> None:
    provider = RemoteJwksKeyProvider(
        jwks_url="https://example.com/.well-known/jwks.json"
    )

    # Optional: pre-fetch the JWKS; otherwise the first key lookup triggers it
    provider.refresh(force=True)

    jwk = await provider.get_public_jwk("test", version=1)
    print(jwk)


asyncio.run(main())
```

You can also construct the provider from an OIDC issuer.  The provider resolves
the issuer's discovery document to find the JWKS URL:

```python
RemoteJwksKeyProvider(issuer="https://issuer.example.com")
```

Locally created keys are available via the standard key provider APIs and are
included alongside remote keys when calling `jwks()`.

### Local vs remote keys

Remote keys and locally created keys serve different purposes:

- **Remote keys** are read-only public keys discovered from the JWKS endpoint.
  They normally belong to an external identity provider and are used only for
  verification. The provider never has access to their private material.
- **Local keys** are generated by the embedded `LocalKeyProvider`. They include
  secret material (when permitted by the `ExportPolicy`) and can be used for
  signing, encryption, or key agreement. These keys live only in memory unless
  you export them.

The following examples illustrate both flows.

#### Working with remote keys

```python
import asyncio
import jwt
from swarmauri_keyprovider_remote_jwks import RemoteJwksKeyProvider


async def main() -> None:
    provider = RemoteJwksKeyProvider(
        jwks_url="https://example.com/.well-known/jwks.json",
    )

    # Fetch a remote public key
    jwk = await provider.get_public_jwk("remote-kid")
    public_key = jwt.algorithms.RSAAlgorithm.from_jwk(jwk)

    token = "..."  # JWT issued by the remote service
    payload = jwt.decode(token, public_key, algorithms=["RS256"], audience="api")
    print(payload)


asyncio.run(main())
```

#### Managing local keys

Local keys can be created, rotated, and destroyed without network calls. They are
ideal when your service needs to issue tokens or perform encryption.

The snippet below signs and verifies a JWT using an HMAC key that never leaves
memory:

```python
import asyncio
import jwt
from swarmauri_keyprovider_remote_jwks import RemoteJwksKeyProvider
from swarmauri_core.key_providers.types import KeySpec, KeyClass, KeyAlg, ExportPolicy
from swarmauri_core.crypto.types import KeyUse


async def main() -> None:
    provider = RemoteJwksKeyProvider(
        jwks_url="https://example.com/.well-known/jwks.json",
    )

    spec = KeySpec(
        klass=KeyClass.symmetric,
        alg=KeyAlg.HMAC_SHA256,
        uses=(KeyUse.SIGN,),
        export_policy=ExportPolicy.SECRET_WHEN_ALLOWED,
    )
    key = await provider.create_key(spec)
    ref = await provider.get_key(key.kid, include_secret=True)

    token = jwt.encode({"sub": "123"}, ref.material, algorithm="HS256")
    decoded = jwt.decode(token, ref.material, algorithms=["HS256"])
    print(decoded)


asyncio.run(main())
```

Locally generated keys appear next to remote keys when exporting a JWKS:

```python
jwks = await provider.jwks()
print(jwks)
```

### Refreshing remote keys

Remote keys are cached for `cache_ttl_s` seconds. Call `refresh(force=True)` to
fetch the latest JWKS before a latency-sensitive operation:

```python
provider = RemoteJwksKeyProvider(
    jwks_url="https://example.com/.well-known/jwks.json",
    cache_ttl_s=60,            # default: 300 seconds
    request_timeout_s=2,       # default: 5 seconds
    user_agent="MyGateway/1.0",
)

# Block until the JWKS has been refreshed
provider.refresh(force=True)
```

## Want to help?

If you want to contribute to swarmauri-sdk, read up on our
[guidelines for contributing](https://github.com/swarmauri/swarmauri-sdk/blob/master/CONTRIBUTING.md)
that will help you get started.