GitHub

API reference for jwks.

JSON Web Key Sets (Effect's effect/jose/Jwks): the Jwks service that resolves a token's verification key::

program.pipe(provide(jwks.layer_local(key_set)))
program.pipe(provide(jwks.layer_remote(url="https://issuer.example/jwks.json")))

A key matches when its family and curve fit the algorithm, its kid is the token's (when the token names one), and its alg, use and key_ops allow verifying with it. Keys of other families or curves are read and ignored; private and symmetric members fail the whole set.

The remote key set is fetched over HTTPS through HttpClient, kept for time_to_live, and refetched early when a token names an unknown key, at most once per cooldown. A failed fetch is retried after cooldown.

Re-exports

Values

AttributeTypeDescription
KeySetSchemaStructSchema[KeySet, Never, Never]

Classes

Functions

make_local

make_local(key_set) -> Effect[JwksService]

A Jwks service over a fixed key set.

ParameterTypeDescription
key_setKeySet

Returns Effect[JwksService]

def make_local(key_set: KeySet) -> Effect[JwksService]:
    """A ``Jwks`` service over a fixed key set."""

    def build() -> JwksService:
        keys = _supported_keys(key_set)
        return JwksService(
            lambda selection: _import_key(_candidates(keys, selection), selection.algorithm)
        )

    return sync(build)

layer_local

layer_local(key_set) -> Layer[Jwks]
ParameterTypeDescription
key_setKeySet

Returns Layer[Jwks]

def layer_local(key_set: KeySet) -> Layer[Jwks]:
    return layer_effect(Jwks, make_local(key_set))

make_remote

make_remote(url, *, time_to_live='10 minutes', cooldown='30 seconds', timeout='5 seconds', max_response_bytes=131072, max_keys=64) -> Effect[JwksService, JoseError, HttpClient | Scope]

A Jwks service over the key set at the HTTPS url, fetched on first use. Fetches run in the current scope and stop when it closes.

time_to_live is how long a fetched set is used (default 10 minutes); cooldown the least time between refetches for unknown keys and retries after a failure (30 seconds); timeout bounds each fetch (5 seconds); max_response_bytes (128 KiB) and max_keys (64) bound the document.

ParameterTypeDescription
urlstr
time_to_liveDurationInput = '10 minutes'
cooldownDurationInput = '30 seconds'
timeoutDurationInput = '5 seconds'
max_response_bytesint = 131072
max_keysint = 64

Returns Effect[JwksService, JoseError, HttpClient | Scope]

def make_remote(
    url: str,
    *,
    time_to_live: DurationInput = "10 minutes",
    cooldown: DurationInput = "30 seconds",
    timeout: DurationInput = "5 seconds",
    max_response_bytes: int = 131072,
    max_keys: int = 64,
) -> Effect[JwksService, JoseError, HttpClient | Scope]:
    """A ``Jwks`` service over the key set at the HTTPS ``url``, fetched on
    first use. Fetches run in the current scope and stop when it closes.

    ``time_to_live`` is how long a fetched set is used (default 10
    minutes); ``cooldown`` the least time between refetches for unknown
    keys and retries after a failure (30 seconds); ``timeout`` bounds each
    fetch (5 seconds); ``max_response_bytes`` (128 KiB) and ``max_keys``
    (64) bound the document."""

    @gen
    def body():
        options = _Options(
            href=(yield from _read_url(url)).href,
            time_to_live=(yield from _positive_millis("timeToLive", time_to_live)),
            cooldown=(yield from millis("cooldown", cooldown)),
            timeout=(yield from _positive_millis("timeout", timeout)),
            max_response_bytes=(
                yield from _positive_integer("maxResponseBytes", max_response_bytes)
            ),
            max_keys=(yield from _positive_integer("maxKeys", max_keys)),
        )
        client = (yield from HttpClient()).with_scope()
        scope = yield from Scope()
        remote = _Remote(options, client, scope)
        yield from scope.add_finalizer(lambda _exit: sync(remote.close))
        return JwksService(remote.resolve)

    return body

layer_remote

layer_remote(url, *, time_to_live='10 minutes', cooldown='30 seconds', timeout='5 seconds', max_response_bytes=131072, max_keys=64) -> Layer[Jwks, JoseError, HttpClient]

make_remote as a layer; fetches stop when the layer's scope closes.

ParameterTypeDescription
urlstr
time_to_liveDurationInput = '10 minutes'
cooldownDurationInput = '30 seconds'
timeoutDurationInput = '5 seconds'
max_response_bytesint = 131072
max_keysint = 64

Returns Layer[Jwks, JoseError, HttpClient]

def layer_remote(
    url: str,
    *,
    time_to_live: DurationInput = "10 minutes",
    cooldown: DurationInput = "30 seconds",
    timeout: DurationInput = "5 seconds",
    max_response_bytes: int = 131072,
    max_keys: int = 64,
) -> Layer[Jwks, JoseError, HttpClient]:
    """``make_remote`` as a layer; fetches stop when the layer's scope closes."""
    return layer_effect(
        Jwks,
        make_remote(
            url,
            time_to_live=time_to_live,
            cooldown=cooldown,
            timeout=timeout,
            max_response_bytes=max_response_bytes,
            max_keys=max_keys,
        ),
    )