webfinger

README

go.mills.io/webfinger

go.mills.io/webfinger is a Go WebFinger client and server implementation and command-line tool.

go.mills.io/webfinger is based code borrowed from ant0ine/go-webfinger, sheenobu/go-webfinger and writeas/go-webfinger with the following improvements:

• Adds Go111Module support and declares the package as go.mills.io/webfinger
• Combines both client and server into a single library compatible with net/http
• Includes an installable command-line (CLI) client go install go.mills.io/webfinger/cmd/webfinger/...

Quick Start

As a command-line (CLI) tool:

go install go.mills.io/webfinger/cmd/webfinger@latest
webfinger prologic@twtxt.net

As a client library:

// TBD

AS a server library:

// TBD

License

go.mills.io/webfinger is licensed under the terms of the MIT license with code originally borrowed and forked from ant0ine/go-webfinger and sheenobu/go-webfinger and improvements borrowed from writeas/go-webfinger which were also all licensed under ther terms of a similar license.

Documentation

Overview

Package webfinger provides a simple client implementation of the WebFinger protocol.

Package webfinger is a server implementation of the webfinger specification. This is a general-case package which provides the HTTP handlers and interfaces for adding webfinger support for your system and resources.

The simplest way to use this is to call webfinger.Default() and then register the object as an HTTP handler:

myResolver = ...
wf := webfinger.Default(myResolver{})
wf.NotFoundHandler = // the rest of your app
http.ListenAndService(":8080", wf)

However, you can also register the specific webfinger handler to a path. This should work on any router that supports net/http.

myResolver = ...
wf := webfinger.Default(myResolver{})
http.Handle(webfinger.WebFingerPath, http.HandlerFunc(wf.Webfinger))
http.ListenAndService(":8080", nil)

In either case, the handlers attached to the webfinger service get invoked as needed.

Index

• Constants
• Variables
• func ErrorFromContext(ctx context.Context) error
• func Lookup(identifier string, rels []string) (*jrd.JRD, error)
• type Client
  • func NewClient(httpClient *http.Client) *Client
  • func (c *Client) Lookup(identifier string, rels []string) (*jrd.JRD, error)
  • func (c *Client) LookupURI(u *URI, rels []string) (*jrd.JRD, error)
• type ErrorKeyType
• type Link
• type Rel
• type Resolver
• type Resource
• type Service
  • func Default(ur Resolver) *Service
  • func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Service) Webfinger(w http.ResponseWriter, r *http.Request)
• type URI
  • func Parse(rawurl string) (*URI, error)
  • func (r *URI) JRDURL(host string, rels []string) *url.URL
  • func (r *URI) String() string
  • func (r *URI) WebFingerHost() string

Constants

const (
	NoCacheMiddleware     string = "NoCache"
	CorsMiddleware        string = "Cors"
	ContentTypeMiddleware string = "Content-Type"
)

Middleware constant keys

const (
	RelSelf        = "self" // https://www.iana.org/assignments/link-relations/link-relations.xhtml
	RelAvatar      = "https://webfinger.net/rel/avatar"
	RelProfilePage = "https://webfinger.net/rel/profile-page"
)

const WebFingerPath = "/.well-known/webfinger"

WebFingerPath defines the default path of the webfinger handler.

Variables

var DefaultClient = &Client{
	client: http.DefaultClient,
}

DefaultClient is the default Client and is used by Lookup.

Functions

func ErrorFromContext

func ErrorFromContext(ctx context.Context) error

ErrorFromContext gets the error from the context

func Lookup

func Lookup(identifier string, rels []string) (*jrd.JRD, error)

Lookup returns the JRD for the specified identifier.

Lookup is a wrapper around DefaultClient.Lookup.

Types

type Client

type Client struct {

	// Allow the use of HTTP endoints for lookups.  The WebFinger spec requires
	// all lookups be performed over HTTPS, so this should only ever be enabled
	// for development.
	AllowHTTP bool
	// contains filtered or unexported fields
}

A Client is a WebFinger client.

func NewClient

func NewClient(httpClient *http.Client) *Client

NewClient returns a new WebFinger Client. If a nil http.Client is provied, http.DefaultClient will be used.

func (*Client) Lookup

func (c *Client) Lookup(identifier string, rels []string) (*jrd.JRD, error)

Lookup returns the JRD for the specified identifier. If provided, only the specified rel values will be requested, though WebFinger servers are not obligated to respect that request.

func (*Client) LookupURI

func (c *Client) LookupURI(u *URI, rels []string) (*jrd.JRD, error)

LookupURI returns the JRD for the specified URI. If provided, only the specified rel values will be requested, though WebFinger servers are not obligated to respect that request.

type ErrorKeyType

type ErrorKeyType int

ErrorKeyType is the type for the context error key

var ErrorKey ErrorKeyType

ErrorKey is the key for the context error

type Link

type Link struct {
	HRef       string             `json:"href"`
	Type       string             `json:"type,omitempty"`
	Rel        string             `json:"rel"`
	Properties map[string]*string `json:"properties,omitempty"`
	Titles     map[string]string  `json:"titles,omitempty"`
}

A Link is a series of user details

type Rel

type Rel string

Rel allows referencing a subset of the users details

type Resolver

type Resolver interface {

	// FindUser finds the user given the username and hostname.
	FindUser(username string, hostname, requestHost string, r []Rel) (*Resource, error)

	// DummyUser allows us to return a dummy user to avoid user-enumeration via webfinger 404s. This
	// can be done in the webfinger code itself but then it would be obvious which users are real
	// and which are not real via differences in how the implementation works vs how
	// the general webfinger code works. This does not match the webfinger specification
	// but is an extra precaution. Returning a NotFound error here will
	// keep the webfinger 404 behavior.
	DummyUser(username string, hostname string, r []Rel) (*Resource, error)

	// IsNotFoundError returns true if the given error is a not found error.
	IsNotFoundError(err error) bool
}

The Resolver is how the webfinger service looks up a user or resource. The resolver must be provided by the developer using this package, as each webfinger service may be exposing a different set or users or resources or services.

type Resource

type Resource struct {
	Subject    string            `json:"subject,omitempty"`
	Aliases    []string          `json:"aliases,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
	Links      []Link            `json:"links"`
}

A Resource is the top-level JRD resource object.

type Service

type Service struct {

	// PreHandlers are invoked at the start of each HTTP method, used to
	// setup things like CORS, caching, etc. You can delete or replace
	// a handler by setting service.PreHandlers[name] = nil
	PreHandlers map[string]http.Handler

	// NotFoundHandler is the handler to invoke when a URL is not matched. It does NOT
	// handle the case of a non-existing users unless your Resolver.DummyUser returns
	// an error that matches Resolver.IsNotFoundError(err) == true.
	NotFoundHandler http.Handler

	// MethodNotSupportedHandler is the handler invoked when an unsupported
	// method is called on the webfinger HTTP service.
	MethodNotSupportedHandler http.Handler

	// MalformedRequestHandler is the handler invoked if the request routes
	// but is malformed in some way. The default behavior is to return 400 BadRequest,
	// per the webfinger specification
	MalformedRequestHandler http.Handler

	// NoTLSHandler is the handler invoked if the request is not
	// a TLS request. The default behavior is to redirect to the TLS
	// version of the URL, per the webfinger specification. Setting
	// this to nil will allow nonTLS connections, but that is not advised.
	NoTLSHandler http.Handler

	// ErrorHandler is the handler invoked when an error is called. The request
	// context contains the error in the webfinger.ErrorKey and can be fetched
	// via webfinger.ErrorFromContext(ctx)
	ErrorHandler http.Handler

	// Resolver is the interface for resolving user details
	Resolver Resolver
}

Service is the webfinger service containing the required HTTP handlers and defaults for webfinger implementations.

func Default

func Default(ur Resolver) *Service

Default creates a new service with the default registered handlers

func (*Service) ServeHTTP

func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Service) Webfinger

func (s *Service) Webfinger(w http.ResponseWriter, r *http.Request)

Webfinger is the webfinger handler

type URI

type URI url.URL

URI is a resource for which a WebFinger query can be issued.

func Parse

func Parse(rawurl string) (*URI, error)

Parse parses rawurl into a WebFinger URI. The rawurl should be an absolute URL, or an email-like identifier (e.g. "bob@example.com").

func (*URI) JRDURL

func (r *URI) JRDURL(host string, rels []string) *url.URL

JRDURL returns the WebFinger query URL at the specified host for this resource. If host is an empty string, the default host for the resource will be used, as returned from WebFingerHost().

func (*URI) String

func (r *URI) String() string

String reassembles the URI into a valid URL string.

func (*URI) WebFingerHost

func (r *URI) WebFingerHost() string

WebFingerHost returns the default host for issuing WebFinger queries for this resource. For URI(s) with a host component, that value is used. For URLs that do not have a host component, the host is determined by other mains if possible (for example, the domain in the addr-spec of a mailto URL). If the host cannot be determined from the URL, this value will be an empty string.