Skip to main content

VerifyOptions

Struct VerifyOptions 

Source
#[non_exhaustive]
pub struct VerifyOptions { pub max_age: Option<Duration>, pub clock: Option<Arc<dyn Clock>>, pub request_url: Option<String>, pub form_params: Option<Vec<(String, String)>>, pub verifying_material: Option<VerifyingKeyMaterial>, pub webhook_id: Option<String>, }
Expand description

Tuning knobs for crate::verify().

#[non_exhaustive]: new knobs are expected to arrive, and adding a field must never break downstream callers. Outside this crate the fields are therefore configured only through Default and the with_* builder methods — struct-literal construction is intentionally unavailable.

use std::time::Duration;
use webhook_verify::VerifyOptions;

let opts = VerifyOptions::default().with_max_age(Some(Duration::from_secs(600)));
assert_eq!(opts.max_age, Some(Duration::from_secs(600)));

Fields (Non-exhaustive)§

This struct is marked as non-exhaustive
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§max_age: Option<Duration>

Maximum allowed age between a signed timestamp and “now”, for providers whose scheme includes a timestamp. None disables the check (not recommended). Default: 300 seconds, matching Stripe’s and Slack’s own SDK defaults.

Providers that do not sign timestamps document explicitly that this option has no effect on them (see spec.md §3).

§clock: Option<Arc<dyn Clock>>

Clock used for “now”. None means real system time. Injectable for deterministic tests of timestamp-based providers.

§request_url: Option<String>

Full URL of the receiving endpoint, required by providers whose signature incorporates it (currently Square, whose scheme signs the notification URL followed by the raw body, and Twilio, which signs the full request URL). The value must match the URL configured with the provider exactly — a differing trailing slash or scheme makes every signature fail. Providers whose scheme does not sign the URL document that this option has no effect on them.

Supplying the configured constant from the provider dashboard is the intended use; reconstructing the URL from request headers behind a proxy is a common source of verification failures.

§form_params: Option<Vec<(String, String)>>

Parsed application/x-www-form-urlencoded fields, required by Twilio: its signature covers the request URL concatenated with the sorted form-field names/values, not the raw body. Pass every field as received — Twilio’s own docs warn against verifying against a hardcoded subset, since providers may add parameters without notice. Sorting is applied here (it is part of the signing scheme), so callers pass fields in any order. A duplicate field name keeps its received relative order.

An explicitly empty list is meaningful (Twilio’s JSON-body variant signs the URL alone); omitting the option entirely fails closed with crate::VerifyError::MissingContext so a caller that forgot to parse the body cannot be confused with an attacker-supplied input.

§verifying_material: Option<VerifyingKeyMaterial>

Verification material for providers whose scheme checks a signature against a configured public key/certificate rather than a shared secret (currently SendGrid and PayPal). See VerifyingKeyMaterial.

Required-but-absent fails closed with crate::VerifyError::MissingContext (caller misconfiguration, mirroring Square/Twilio’s context options); malformed material fails with crate::VerifyError::InvalidSecret.

This crate never fetches key material itself (spec.md §7): the caller supplies bytes that were already obtained and vetted out-of-band.

§webhook_id: Option<String>

PayPal’s webhook ID, required by PayPal’s signed-string construction (spec.md §3). It is not a request header or body field — it is the ID of the webhook subscription (shown in the PayPal Developer Portal for the listener URL) and must be supplied by the caller, mirroring Square/Twilio’s URL context.

Required-but-absent for Provider::PayPal fails closed with crate::VerifyError::MissingContext; an explicitly empty value is treated the same way, so operator misconfiguration is never surfaced as an attack-looking signature mismatch. Providers whose scheme does not sign a webhook ID document that this option has no effect on them.

Implementations§

Source§

impl VerifyOptions

Source

pub fn with_request_url(self, url: impl Into<String>) -> Self

Sets VerifyOptions::request_url, for URL-scoped schemes.

Source

pub fn with_form_params<I, K, V>(self, params: I) -> Self
where I: IntoIterator<Item = (K, V)>, K: Into<String>, V: Into<String>,

Sets VerifyOptions::form_params, for schemes that sign parsed form fields (currently Twilio). Order does not matter; fields are sorted into signing order during verification of Twilio’s signed string.

Source

pub fn with_max_age(self, max_age: Option<Duration>) -> Self

Sets VerifyOptions::max_age, the maximum allowed clock skew for providers whose scheme signs a timestamp. None disables the check (not recommended); the default is Some(Duration::from_secs(300)).

Providers that do not sign timestamps document explicitly that this option has no effect on them (see spec.md §3).

Source

pub fn with_clock(self, clock: Option<Arc<dyn Clock>>) -> Self

Sets VerifyOptions::clock, the source of “now” used for replay protection. None uses real system time. Injectable for deterministic tests of timestamp-based providers.

Source

pub fn with_verifying_material(self, material: VerifyingKeyMaterial) -> Self

Sets VerifyOptions::verifying_material, the asymmetric public-key /certificate material required by public-key schemes (currently SendGrid’s ECDSA P-256 key and PayPal’s X.509 certificate).

Source

pub fn with_webhook_id(self, webhook_id: impl Into<String>) -> Self

Sets VerifyOptions::webhook_id, PayPal’s webhook-subscription ID, required by PayPal’s signed-string construction (see the field docs).

Source

pub fn now(&self) -> u64

Resolves “now” in unix seconds from the injected clock, falling back to the real wall clock under std.

Trait Implementations§

Source§

impl Clone for VerifyOptions

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for VerifyOptions

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for VerifyOptions

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

Source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

Source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

Source§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more