WebFinger

Definition

WebFinger is an Internet Engineering Task Force Standards Track protocol published as RFC 7033 in September 2013 by Paul E. Jones, Gonzalo Salgueiro, Michael B. Jones, and Joseph Smarr. It defines a way to discover information about people, organizations, devices, accounts, or other resources identified by a URI.

The protocol is deliberately narrow. A client asks a domain about a resource, and the domain returns a JSON Resource Descriptor, usually abbreviated JRD. The JRD can name the subject, provide aliases, expose properties, and list typed links. It does not prove that a human endorsed a use, that an account is safe, or that a client is authorized to act.

For Spiralist purposes, WebFinger is a naming and lookup layer. It turns a socially familiar handle or URI into machine-readable pointers, making distributed systems easier to navigate and accounts easier to enumerate.

How It Works

A WebFinger client sends an HTTP GET request to the queried domain's well-known endpoint, /.well-known/webfinger, with a resource query parameter containing the URI. RFC 7033 requires HTTPS and valid server certificates. The expected response is a JRD with the media type application/jrd+json.

A JRD can contain a subject, an aliases array, a properties object, and a links array. Each link can carry a relation type, media type, target URI, titles, and properties. The protocol also lets a client request certain link relation types, but their meaning is defined by the application using WebFinger, not by WebFinger alone.

The most recognizable query uses the acct: URI scheme. RFC 7565, written by Peter Saint-Andre and published in May 2015, defines acct: as a URI scheme for identifying an account at a service provider. A query such as acct:bob@example.com asks example.com for metadata about that account. The acct: URI identifies the account; it does not specify how to email, message, authenticate as, or control it.

Agent Context

WebFinger matters for AI agents because agents need discovery before action. A crawler, moderation assistant, social client, or identity broker may need to resolve a handle into a profile page, actor document, service endpoint, or authorization issuer. WebFinger gives such systems a standardized first question: what does this domain say about this resource?

In the ActivityPub world, a 2024 W3C Social Web Incubator Community Group report documents a common pattern: construct an acct: URI from a username and hostname, query the host's WebFinger endpoint, and find a link to an actor document. The report is a community final report, not a W3C Recommendation. It describes interoperability practice around ActivityPub; it does not turn every social handle into a universal authority token.

An agent that uses WebFinger should log the resource URI, queried domain, HTTP status, final endpoint after redirects, JRD subject, aliases, selected link relation, and action taken after discovery. Without that record, lookup can become an unexplained delegation chain.

Governance Risks

The privacy risk is built into the strength of the protocol. RFC 7033 warns that WebFinger can make personal data easier to discover. It also says systems exposing personal data through WebFinger must give users control over what is exposed and must not publish that data without explicit authorization from the person whose information is shared.

Enumeration is the second risk. RFC 7565 notes that an acct: URI can prove that an account exists and that harvesting such URIs could help spammers or similar attackers. The W3C SocialCG ActivityPub/WebFinger report makes the same point for federated social systems: discovering an actor can reveal where unwanted messages can be delivered.

The third risk is semantic overreach. A JRD link can say where a profile, actor document, feed, issuer, or service endpoint might be found. It does not say that a downstream agent may scrape, train on, impersonate, message, purchase, moderate, or disclose anything. Treating discovery as consent is a governance failure.

Governance Pattern

• Normalize the query. Store the exact resource URI, normalized form, queried hostname, redirect chain, and response timestamp.
• Enforce transport rules. Use HTTPS, validate certificates, reject unexpected content types, parse JRD as data, and treat malformed JSON as failure.
• Check subject and aliases. Confirm that the returned subject and aliases match the application expectation before following a link.
• Whitelist relations. Follow only link relation types your application understands, and ignore unknown relations rather than inventing meaning.
• Separate discovery from authority. Require separate authentication, authorization, consent, and policy checks before any consequential agent action.
• Minimize exposure. Publish only needed properties, rate-limit enumeration, monitor abusive lookup patterns, and let users remove public metadata.

Spiralist Reading

Spiralism reads WebFinger as a small directory ritual: a name is spoken to a domain, and the domain replies with pointers.

That ritual is useful because it makes distributed identity less brittle. It is dangerous because discoverability becomes a substrate for profiling, automation, and social reach. The moral work is not the lookup itself. The moral work is deciding what power is allowed to follow from being found.

Related Pages

• ActivityPub
• AT Protocol
• Decentralized Identifiers
• AI Agent Identity
• Agent-Native Internet
• Web Bot Auth
• HTTP Message Signatures
• OpenID Connect
• Data Minimization
• Platform Governance

Sources

• P. Jones, G. Salgueiro, M. Jones, and J. Smarr, IETF, RFC 7033: WebFinger, Standards Track, September 2013.
• P. Saint-Andre, IETF, RFC 7565: The 'acct' URI Scheme, Standards Track, May 2015.
• W3C Social Web Incubator Community Group, ActivityPub and WebFinger, Community Final Report, June 8, 2024.

Return to Wiki