Package org.apache.juneau.rest.server.mcp.v20260728

Interface KeyProvider

All Known Implementing Classes:
EphemeralKeyProvider, StaticKeyProvider
public interface KeyProvider
SPI for supplying the key(s) used to seal/unseal MCP MRTR requestState continuation tokens (see AeadRequestStateCodec).

A dedicated abstraction beneath the AEAD codec so an operator can supply a stable, shared sealing key (fixing horizontally-scaled RESUME behind a load balancer) and rotate keys via a keyId, while the codec's zero-config default (EphemeralKeyProvider) keeps today's per-process ephemeral-key behavior unchanged.

Thread-safety. A single provider instance is shared across all requests against a binding (the codec is per-binding), so implementations must be safe for concurrent calls to both currentKey() and resolveKey(String).

Never-throw contract. resolveKey(String) is called on the unseal path with an untrusted, client-supplied keyId. Implementations must treat any unknown or retired keyId as Optional.empty() and must never throw — the caller (AeadRequestStateCodec#unseal) has no exception-handling path for this call.

Not annotated @FunctionalInterface: unlike single-method SPIs such as ApiKeyStore, this SPI declares two abstract methods.

See Also:
Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    KeyedSecret
    currentKey()
    The key to seal new tokens with, together with its identifier.
    Optional<SecretKey>
    resolveKey(String keyId)
    Resolves a keyId seen on an incoming token to the key that sealed it.

  • Method Details

    • currentKey

      KeyedSecret currentKey()
      The key to seal new tokens with, together with its identifier.

      May return a different value over time — a changing return value is the sanctioned mechanism for live runtime key rotation in a custom provider. Built-in providers (EphemeralKeyProvider, StaticKeyProvider) return a fixed value for the lifetime of the instance.

      Returns:
      The current sealing key. Never null.

    • resolveKey

      Optional<SecretKey> resolveKey(String keyId)
      Resolves a keyId seen on an incoming token to the key that sealed it.
      Parameters:
      keyId - The key identifier read from the untrusted, client-supplied token, before decryption. Never null.
      Returns:
      The resolved key, or Optional.empty() if keyId is unknown or retired. Never throws.