object

# `open_id_jwks_cache`

JWKS caching and key-rotation helpers.

Availability:
`logtalk_load(open_id(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-07-12
Compilation flags:
`static, context_switching_calls`
Imports:
`public` open_id_helpers
Uses:
open_id_client
open_id_jwt
os
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `cached_jwks/3`

Returns a cached JWKS for a provider, refreshing it when the cache is stale or missing.

Compilation flags:
`static`
Template:
`cached_jwks(Provider,JWKSet,Options)`
Mode and number of proofs:
`cached_jwks(+compound,-term,+list(compound))` - `one_or_error`
Exceptions:
`Options` is a variable or a partial list:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The provider metadata is missing a JWKS endpoint:
`domain_error(open_id_provider,missing(jwks_uri))`
The JWKS endpoint returned a non-success status:
`domain_error(open_id_http_status,Code)`
The JWKS endpoint response body is not JSON:
`domain_error(open_id_json_response,Body)`

### `verify_id_token/4`

Verifies an ID-token using cached JWKS data, refreshing the cache once when the token key identifier is unknown.

Compilation flags:
`static`
Template:
`verify_id_token(Token,Provider,Claims,Options)`
Mode and number of proofs:
`verify_id_token(+atom,+compound,-term,+list(compound))` - `zero_or_one_or_error`
Exceptions:
`Options` is a variable or a partial list:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(option,Option)`
The provider metadata is missing a JWKS endpoint:
`domain_error(open_id_provider,missing(jwks_uri))`
The JWKS endpoint returned a non-success status:
`domain_error(open_id_http_status,Code)`
The JWKS endpoint response body is not JSON:
`domain_error(open_id_json_response,Body)`
`Token` is a variable:
`instantiation_error`
`Token` is neither a variable nor an atom:
`type_error(atom,Token)`
`Token` is an atom but not a valid compact JWT:
`domain_error(jwt_compact_serialization,Token)`
`Token` contains Base64URL data with characters outside the Base64URL alphabet:
`representation_error(base64)`
The JWT header does not contain a valid `alg` member:
`domain_error(jwt_header,Header)`
The JWT algorithm is unsupported or disallowed:
`domain_error(open_id_jwt_algorithm,Algorithm)`
`JWKSet` is not a JSON Web Key Set with a `keys` list:
`domain_error(jwt_jwks,JWKSet)`
No compatible key exists for the JWT header:
`existence_error(jwt_jwk,Header)`
The selected JWK is not a supported public key:
`domain_error(jwt_jwk_public_key,Key)`
The ES256 signature is not 64 bytes long:
`domain_error(jwt_es256_signature,Signature)`
The OpenSSL executable does not exist:
`existence_error(os_command,Executable)`
The `iss` claim does not match the provider issuer:
`domain_error(open_id_claim(iss),Value)`
A required OpenID ID-token claim is missing:
`domain_error(open_id_claims,missing(Name))`
The expected audience option is missing:
`domain_error(open_id_claims,missing(expected_audience))`
An OpenID ID-token claim has an invalid value:
`domain_error(open_id_claim(Name),Value)`
An OpenID ID-token time claim value is not a number:
`type_error(time_number,Name-Time)`

### `clear/0`

Clears all cached JWKS entries.

Compilation flags:
`static`
Mode and number of proofs:
`clear` - `one`

### `clear/1`

Clears the cached JWKS entry for a provider.

Compilation flags:
`static`
Template:
`clear(Provider)`
Mode and number of proofs:
`clear(+compound)` - `one_or_error`
Exceptions:
The provider metadata is missing a JWKS endpoint:
`domain_error(open_id_provider,missing(jwks_uri))`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

### `cached_jwks_/3`

Cached JWKS entries indexed by URI and fetch time.

Compilation flags:
`dynamic`
Template:
`cached_jwks_(URI,FetchedAt,JWKSet)`
Mode and number of proofs:
`cached_jwks_(?atom,?number,?term)` - `zero_or_more`

## Operators

(none)