Struct PubkeysEndpointLookup 

pub struct PubkeysEndpointLookup { /* private fields */ }

DEMOTED to convenience-only as of the gate-3 redesign (2026-09-13) — do NOT wire this as the default AttestationKeyLookup for verify_attestation/Client::verify_attestation. PinnedKeyMap is the default now. See the module-level “Design history” doc for why: fetching a verification key from the same service whose signature is being verified is architecturally circular — whoever controls /v1/pubkeys would control what “verifies.”

This type still fetches {base_url}/v1/pubkeys (the endpoint cleanlib-app publishes per cosign migration gate 1) and caches each key_id -> PEM pair for ttl, unauthenticated + no-store (same posture as /health). Its ONLY sanctioned use post-redesign is Self::describe_unknown_key — producing a human-readable advisory a caller can show a user when PinnedKeyMap doesn’t recognize a key_id, so they can go verify a fingerprint out of band. It must never feed a verify_attestation trust decision directly; AttestationKeyLookup::lookup_pem stays implemented here (so this type remains directly testable / usable standalone, e.g. by a caller building their own advisory UX), but verify_attestation’s DEFAULT path never reaches it.

Implementations

impl PubkeysEndpointLookup

pub fn new(base_url: &Url) -> Result<Self, CleanLibraryError>

base_url is the App origin (e.g. https://cleanapp.clnstrt.dev); this joins /v1/pubkeys per the gate-1 endpoint. Uses DEFAULT_PUBKEY_CACHE_TTL; see Self::with_ttl to override.

pub fn with_ttl(self, ttl: Duration) -> Self

pub async fn describe_unknown_key(&self, key_id: &str) -> Option<String>

Convenience-only advisory (see the type doc): when PinnedKeyMap doesn’t recognize a key_id, a caller MAY use this to look up whether /v1/pubkeys reports that key_id anyway, and produce a human-readable hint — “this key_id exists on the server, go verify its fingerprint out of band before deciding whether to pin it.” This NEVER returns a verified/trusted signal and must NEVER be fed into a trust decision — it only ever produces advisory text (Option<String>), never a PEM, never a bool, precisely so it cannot be mistaken for a verify result.

Returns None if the server is unreachable or doesn’t recognize the key_id either — absence of an advisory is not itself a security signal in either direction.

Trait Implementations

impl AttestationKeyLookup for PubkeysEndpointLookup

fn lookup_pem<'life0, 'life1, 'async_trait>( &'life0 self, key_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, CleanLibraryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve key_id (the exact string carried on SignedAttestation.key_id — the full KMS key-version resource path, e.g. projects/.../cryptoKeys/cleanlib-cosign-staging/cryptoKeyVersions/1) to a PEM-encoded SubjectPublicKeyInfo. Implementations should treat a “no such key_id” answer as AttestationInvalid (permanent — retrying the same key_id against the same catalog will not help) and a network/5xx failure as Transport (transient — retry may succeed).

impl Clone for PubkeysEndpointLookup

fn clone(&self) -> PubkeysEndpointLookup

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PubkeysEndpointLookup

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

Formats the value using the given formatter.