Webfinger-rs

webfinger-rs is a Rust library for handling WebFinger protocol defined by RFC 7033.

WebFinger is is used to discover information about people or other entities on the internet. The motivation of this library is to provide a transport-agnostic implementation of the WebFinger protocol for client and server-side application which can be used with different HTTP libraries such as Axum, and Reqwest. Additionally, the other available crates for WebFinger are either not actively maintained and have a license that is incompatible with incorporating the crate into other projects as a library (GPL-3.0).

Usage

To use this library, add it to your Cargo.toml:

cargo add webfinger-rs

The library also has a related CLI tool, webfinger-cli, which can be installed with:

cargo install webfinger-cli
webfinger acct:carol@example.com --rel http://webfinger.net/rel/avatar

Client Example

The following example connects to the WebFinger server at example.com and requests the profile page for the user carol@example.com. It requires the reqwest feature to be enabled. This example is also available in the repository at: https://github.com/joshka/webfinger-rs/blob/main/webfinger-rs/examples/client.rs.

use webfinger_rs::WebFingerRequest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request = WebFingerRequest::builder("acct:carol@example.com")?
        .host("example.com")
        .rel("http://webfinger.net/rel/profile-page")
        .build();
    let response = request.execute_reqwest().await?;
    dbg!(response);
    Ok(())
}

Server Example

The following example is an Axum handler that responds to WebFinger requests. It requires the axum feature to be enabled. This example is also available in the repository at: https://github.com/joshka/webfinger-rs/blob/main/webfinger-rs/examples/axum.rs.

use axum::response::Result as AxumResult;
use webfinger_rs::{Link, Rel, WebFingerRequest, WebFingerResponse};

async fn webfinger(request: WebFingerRequest) -> AxumResult<WebFingerResponse> {
    let subject = request.resource.to_string();
    if subject != "acct:carol@example.com" {
        Err((http::StatusCode::NOT_FOUND, "Not Found"))?;
    }
    let rel = Rel::new("http://webfinger.net/rel/profile-page");
    let response = if request.rels.is_empty() || request.rels.contains(&rel) {
        let link = Link::builder(rel).href(format!("https://example.com/profile/{subject}"));
        WebFingerResponse::builder(subject).link(link).build()
    } else {
        WebFingerResponse::builder(subject).build()
    };
    Ok(response)
}

Running the examples

To run the examples, you can use the following commands:

cargo run --example actix --features actix
cargo run --example axum --features axum

This will start a server on https://localhost:3000 that responds to WebFinger requests for a single user, carol@localhost. Use webfinger-cli tool to query these servers. The servers create self-signed certificates for localhost, which can be ignored with the --insecure flag.

cargo install webfinger-cli
webfinger acct:carol@localhost localhost:3000 --insecure --rel http://webfinger.net/rel/profile-page

Features / TODO list

• Client side types
• Reqwest interaction
• Server side types
• Axum integration
• Actix integration

Stability

This library is in early days and will have semver breaking changes in the 0.0.x releases. Once 0.1.0 is released, semver breaking changes will bump the minor version.

License

Copyright (c) 2024 Josh McKinney

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md.