pata 0.0.1

A fast, lightweight, and evidence-driven email validation library for Rust
Documentation

pata — Evidence for every address

Pata is a fast, lightweight email validation library for Rust. It checks syntax, domain routing, and mailbox responses without presenting uncertain results as facts.

Pata supports Rust 1.94.1 and later.

The name comes from the Hindi and Urdu word pata (पता, پتہ): an address, location, clue, or knowledge.

Local validation

Local validation performs no network I/O:

use pata::{Validator, Verdict};

# async fn example() {
let validator = Validator::local();
let report = validator.validate("maya@example.com").await;

assert_eq!(report.verdict(), Verdict::Plausible);
assert_eq!(report.address().unwrap().domain().ascii(), "example.com");
# }

Malformed input is a validation result rather than an operational error:

use pata::{Validator, Verdict};

# async fn example() {
let report = Validator::local().validate("not an address").await;

assert_eq!(report.verdict(), Verdict::Invalid);
assert!(report.address().is_none());
# }

Pata deliberately does not call a passively inspected address “verified” or claim that it exists. A successful report is Plausible; proof of control belongs to a separate confirmation workflow.

Domain and mailbox checks

Network validation is opt-in. Enable runtime-portable for domain checks or runtime-portable-tls for domain and mailbox checks. Network::system reads the operating system's resolver configuration and uses portable async-io sockets and Futures I/O internally. The TLS feature adds authenticated Rustls STARTTLS. Neither feature requires the application to run Tokio or Smol. The first call starts one shared DNS worker thread that remains for the process lifetime.

# #[cfg(feature = "dns")]
use pata::{Network, Mode, Validator};

# #[cfg(feature = "dns")]
async fn inspect_domain() -> pata::Result<()> {
    let validator = Validator::builder()
        .mode(Mode::Domain)
        .network(Network::system()?)
        .build()?;

    let report = validator.validate("maya@example.com").await;
    println!("{:?}: {:?}", report.verdict(), report.domain_status());
    Ok(())
}

Mailbox observation additionally requires a multi-label DNS identity for the probing host. Pata opens a bounded SMTP conversation, attempts authenticated STARTTLS when advertised, uses the null reverse path, submits one RCPT TO, resets the transaction, and quits. It never issues DATA and never sends message content.

# #[cfg(all(feature = "dns", feature = "smtp"))]
use pata::{Network, Mode, Validator};

# #[cfg(all(feature = "dns", feature = "smtp"))]
async fn inspect_mailbox() -> pata::Result<()> {
    let validator = Validator::builder()
        .mode(Mode::Mailbox)
        .network(Network::system()?)
        .probe_identity("validator.example.com")?
        .build()?;

    let report = validator.validate("maya@example.com").await;
    println!("{:?}", report.mailbox_status());
    Ok(())
}

Domain reveals only the DNS domain to configured resolvers. Mailbox reveals the full address to a receiving mail server. Call Validator::plan before execution when an application needs to display or enforce that disclosure boundary.

Runtime model

The default adapter works when polled by any Futures-compatible executor. Advanced applications can supply an owned dns::Resolver and runtime::Connector, runtime::Timer, and optional authenticated runtime::TlsConnector. No Hickory, Rustls, Tokio, or Smol type appears in Pata's validation and report APIs.

runtime-portable supplies the built-in system DNS, TCP, and timer adapter. runtime-portable-tls adds its authenticated Rustls STARTTLS upgrader.

Drop a validation future to cancel that caller's operation. Pata returns no partial report after cancellation and never caches recipient outcomes. A shared DNS lookup can still serve another concurrent caller.

The opt-in serde feature serializes the complete report, including the original address. Debug output remains redacted. Applications must treat serialized reports as sensitive data and apply their own retention controls.

Classification and policy

The default classification feature provides versioned, checked-in data for role mailboxes, common free-mail services, reviewed disposable services, and a small conservative set of provider-domain typo suggestions. Reports retain the compiled data revision and never silently rewrite an address. Runtime FSTs live beside their Rust consumer. The snapshot manifest lives with its repository generator in examples/classifier_snapshot/. The crate root contains the third-party notice and license texts. The classifier_snapshot example verifies checked-in artifacts and rebuilds a named FST only when the supplied source matches its pinned checksum.

Application rules remain explicit policy inputs. Exact IDNA-normalized domain allow and deny rules are configured through Policy::builder; deny rules make Policy::accepts return false without inventing DNS or SMTP failures.

The registration policy accepts reports with retained risk warnings. The strict policy rejects those reports. The transactional policy also requires an explicit or implicit mail route. Domain allow rules change policy evaluation without removing the underlying classifier findings.

Batch and operational capabilities

Validator::validate_all accepts a stream, applies bounded concurrency, coalesces successful domain lookups, and preserves input order. Shared cache keys contain domains only; recipient outcomes and complete addresses are never cached.

Optional features keep operational concerns additive:

  • diagnostics audits DNS route safety and configured SMTP/TLS capabilities without accepting or disclosing a recipient;
  • proxy provides a bounded runtime-neutral SOCKS5 connector with redacted RFC 1929 credentials and local DNS destination revalidation;
  • posture inspects SPF, DMARC, MTA-STS, and TLS-RPT publication separately from address deliverability;
  • tracing emits completion metadata without the address or domain; and
  • serde explicitly serializes complete sensitive reports.

The default feature set contains only classification. It performs no network I/O and keeps DNS, SMTP, TLS, proxy, provider, and confirmation dependencies opt-in. --no-default-features retains parsing, local findings, policy, reports, inspection, and batch validation without classifier data or network code.

Interpreting results

Pata reports observations separately from application policy:

  • Invalid means the input grammar failed.
  • Undeliverable requires a decisive domain or recipient result.
  • Unknown means the requested network observation could not conclude.
  • Risky records policy-selected warnings such as disposable service use.
  • Plausible means the requested checks found no decisive failure; it is not proof of ownership or future delivery.

External lookups and confirmation

These capabilities are separate, opt-in operations. They never run during Validator::validate, never add findings, and never change Verdict:

  • gravatar derives Gravatar's SHA-256 identifier and provides a bounded, runtime-neutral profile client with optional authentication. A lookup discloses a deterministic address hash to Gravatar. The profile endpoint resolves only a profile's primary address, and profile presence does not validate the mailbox.
  • breach provides authenticated HIBP direct and hash-range lookups. Direct lookup sends the complete address and returns public breach details. Hash-range lookup sends only the first six SHA-1 characters and returns breach names. Neither path caches address results. Both distinguish absence from authentication, access, rate limiting, transport, and provider failures. Rate-limited results retain a whole-second Retry-After hint when HIBP supplies one. Applications that display HIBP-derived results must provide the attribution required by HIBP's Creative Commons license.
  • confirmation generates cryptographically random one-time tokens, stores only SHA-256 token identifiers with the challenged address and expiry, compares identifiers in constant time, and requires application-provided asynchronous storage and delivery. The store's atomic-consume contract provides single use across concurrent callers.
# #[cfg(feature = "gravatar")]
# {
use pata::{Address, gravatar::GravatarId};

let address = Address::parse("maya@example.com")?;
let id = GravatarId::new(&address);
assert_eq!(id.as_str().len(), 64);
# }
# Ok::<(), pata::ParseError>(())

Provider acceptance of a confirmation message is not proof. Only successful atomic consumption of the recipient's token creates a confirmation::Confirmation, recording the controlled address and confirmation time.

Feature flags

  • Default: classification.
  • Data and validation: classification, dns, smtp, serde.
  • Runtime and operations: runtime-portable, runtime-portable-tls, proxy, diagnostics, posture, tracing.
  • Explicit external capabilities: gravatar, breach, confirmation.

--no-default-features retains owned parsing, policy, reports, planning, and batch validation with no network implementation. Optional provider clients use Pata's runtime-neutral Tez transport privately; no Tokio, Smol, Tez, Hickory, or Rustls type appears in their public contracts.

Security and privacy

Pata blocks loopback, private, link-local, multicast, documentation, benchmark, and other non-public SMTP destinations after DNS resolution. It bounds input, concurrency, DNS routes, protocol responses, connections, commands, and total execution time. One mailbox observation tries at most 16 destinations and accepts at most 8 KiB for each SMTP reply. SMTP probes never authenticate, never issue DATA, and never send message content.

Address debug output, proxy credentials, API keys, confirmation tokens, and deterministic Gravatar identifiers are redacted. The serde feature intentionally serializes complete reports, including their original address; applications own access controls, retention, and deletion.

What Pata can establish

Syntax, DNS, and SMTP are observations at different strengths. SMTP acceptance may be a catch-all, delayed policy decision, or anti-enumeration response. Gravatar and breach corpus membership are enrichment, not validation. Only a completed confirmation demonstrates control, and even that proof ages independently of future deliverability. Pata preserves those distinctions so applications can apply policy without manufacturing certainty.