io-pim-discovery 0.7.0

PIM discovery CLI and client library for Rust
Documentation

io-pim-discovery Documentation Matrix Mastodon Sponsor

PIM discovery CLI and client library for Rust

This project is composed of 3 feature-gated layers:

  • Low-level I/O-free coroutines: no_std state machines containing the whole discovery logic, usable anywhere
  • Mid-level clients, based on coroutines (standard, blocking)
  • High-level CLI, based on the std clients

Table of contents

Features

  • Email discovery: find a domain's incoming and outgoing mail servers through Mozilla autoconfig, the Thunderbird ISPDB, DNS SRV records, DNS TXT redirects and PACC well-known configuration.
  • Calendar and contacts discovery: locate a domain's CalDAV and CardDAV home through DNS SRV, DNS TXT context lookups and well-known probes.
  • JMAP discovery: resolve a domain to its JMAP session URL through DNS SRV and the well-known session probe.
  • Authentication discovery: probe a URL's authentication schemes and fetch a provider's OAuth 2.0 authorization-server and protected-resource metadata to learn where and how to obtain tokens.
  • Unified compose: from a single email address, chain the known-provider rules and every enabled mechanism into one ranked list of service configurations, either collecting all of them or stopping at the first match.
  • DNS over HTTPS: every DNS lookup accepts an HTTPS resolver so discovery works on networks that block plain DNS.
  • JSON output: machine-readable results from the CLI with a single flag.
  • TLS support:
    • Rustls with ring crypto (requires rustls-ring feature, enabled by default)
    • Rustls with aws crypto (requires rustls-aws feature)
    • Native TLS (requires native-tls feature)

[!TIP] io-pim-discovery is written in Rust and uses cargo features to gate each mechanism. The default feature set is declared in Cargo.toml or on docs.rs.

Coverage

Spec What is covered
Autoconfig Mozilla Thunderbird autoconfiguration: ISP main and well-known lookups, ISPDB, DNS MX retry and the DNS TXT mailconf redirect (requires autoconfig)
PACC Provider-authenticated client configuration: well-known JSON fetch with SHA-256 digest verification against the ua-auto-config TXT record (requires pacc)
6186 DNS SRV mail discovery: imap, imaps and submission records assembled into one report (requires rfc6186)
6764 CalDAV and CardDAV discovery: DNS SRV, DNS TXT context and well-known probe, chained into a context-root resolve (requires rfc6764)
8484 DNS over HTTPS: every lookup accepts an HTTPS dns-query resolver next to plain DNS over TCP
8620 JMAP autodiscovery: DNS SRV origin lookup and well-known session probe, chained into a session-URL resolve (requires rfc8620)
8414 OAuth 2.0 authorization server metadata: resolve an issuer into its authorization, token and registration endpoints (requires rfc8414)
9728 OAuth 2.0 protected resource metadata: resolve a resource into the authorization servers that can issue tokens for it (requires rfc9728)

Installation

The CLI binary pim-discovery has not been officially released yet. Pre-built binaries from the master branch are attached to the releases workflow, under its Artifacts section, built with the default features plus the cli feature.

Install from crates.io with cargo:

cargo install io-pim-discovery --locked --features cli

Or with Nix:

nix profile install github:pimalaya/io-pim-discovery

To use io-pim-discovery as a library, add it to your Cargo.toml and pick the mechanisms you need; the API is documented on docs.rs.

Usage

The CLI is organised by PIM domain (email, calendar, contact, file), plus all and auth; each mechanism is exposed independently and the source column tells the rows apart. A few real-world invocations:

pim-discovery all user@fastmail.com
pim-discovery email first user@fastmail.com
pim-discovery calendar dav fastmail.com
pim-discovery auth server https://api.fastmail.com
pim-discovery --json all user@fastmail.com

Run pim-discovery --help for the full command tree, flags and TLS options. See documentation at docs.rs.

Examples

See complete examples at ./examples.

FAQ

Use --log <level> where <level> is one of off, error, warn, info, debug, trace. The RUST_LOG environment variable, when set, overrides --log and supports per-target filters (see the env_logger documentation), and RUST_BACKTRACE=1 enables full error backtraces. Logs are written to stderr, so they can be redirected to a file.

License

This project is licensed under either of:

Social

Sponsoring

nlnet

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider sponsoring its development:

GitHub Ko-fi Buy Me a Coffee Liberapay thanks.dev PayPal