Struct KeySelector 

pub struct KeySelector<'a> { /* private fields */ }

Policy-bound strict selector for a KeySet.

Implementations

impl<'a> KeySelector<'a>

pub fn select(&self, matcher: KeyMatcher<'_>) -> Result<&'a Key, SelectionError>

Selects exactly one key using strict cryptographic suitability checks.

Conceptually, strict selection applies the same per-key validation layers as Key::validate_for_use, but within a JWKS search and with extra policy rules such as verification allowlists, declared-alg matching, and ambiguity handling.

When kid is present in the matcher, candidate-level validation failures are surfaced with specific diagnostics (AlgorithmMismatch, IntentMismatch, InvalidKey, KeySuitabilityFailed, IncompatibleKeyType) using deterministic precedence.

When kid is not present, candidates that fail per-key checks are skipped and selection resolves by surviving cardinality (AmbiguousSelection / NoMatchingKey).

In kid-less mode, candidate-level mismatch diagnostics are intentionally suppressed. Early policy errors still surface (UnknownAlgorithm, UnknownOperation, OperationAlgorithmMismatch, allowlist failures).

Error precedence is deterministic:

1. UnknownAlgorithm
2. UnknownOperation
3. OperationAlgorithmMismatch
4. EmptyVerifyAllowlist / AlgorithmNotAllowed (verify only)
5. Candidate evaluation
6. If multiple candidates survive: AmbiguousSelection

If kid is present and no candidate survives, the most specific error is returned in this order: AlgorithmMismatch -> IntentMismatch -> InvalidKey -> KeySuitabilityFailed -> IncompatibleKeyType -> NoMatchingKey.

If kid is absent and no candidate survives, candidate-level diagnostics are suppressed and selection returns NoMatchingKey.

If kid is omitted and selection returns NoMatchingKey, use KeySet::find for discovery diagnostics to inspect broad candidates.

Examples

Verify selection with an explicit allowlist:

use jwk_simple::{Algorithm, KeyMatcher, KeyOperation, KeySet};

let json = r#"{"keys": [
  {"kty": "RSA", "kid": "my-kid", "use": "sig", "alg": "RS256", "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", "e": "AQAB"}
]}"#;
let jwks: KeySet = serde_json::from_str(json).unwrap();

let key = jwks
  .selector(&[Algorithm::Rs256, Algorithm::Es256])
  .select(KeyMatcher::new(KeyOperation::Verify, Algorithm::Rs256).with_kid("my-kid"))
  .unwrap();
assert_eq!(key.kid(), Some("my-kid"));

Sign selection (allowlist is not consulted for signing):

use jwk_simple::{Algorithm, KeyMatcher, KeyOperation, KeySet};

let json = r#"{"keys": [
  {"kty": "EC", "kid": "sign-kid", "use": "sig", "alg": "ES256", "crv": "P-256", "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4", "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM", "d": "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE"}
]}"#;
let jwks: KeySet = serde_json::from_str(json).unwrap();

let key = jwks
  .selector(&[])
  .select(KeyMatcher::new(KeyOperation::Sign, Algorithm::Es256).with_kid("sign-kid"))
  .unwrap();
assert_eq!(key.kid(), Some("sign-kid"));

Trait Implementations

impl<'a> Clone for KeySelector<'a>

fn clone(&self) -> KeySelector<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for KeySelector<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.