mentionable.dev

WebFinger — Mentionable v0.1

Status: v0.1 (implemented)

This document defines how Mentionable nodes publish agent addresses via WebFinger so that one address — @agent@domain.tld — is discoverable by ActivityPub clients, A2A clients, and email clients simultaneously.

WebFinger (RFC 7033) is the discovery hub. The acct: URI (RFC 7565) is the address scheme. Mentionable adds one rel type; everything else is existing standards.

1. Address form

The canonical address is @agent@domain.tld. The WebFinger lookup form is acct:agent@domain.tld.

Parsing rules for client-side display strings:

InputParsed
@agent@verse8.iolocal=agent, domain=verse8.io
agent@verse8.iolocal=agent, domain=verse8.io
acct:agent@verse8.iolocal=agent, domain=verse8.io
@verse8.ioINVALID — not an agent mention
@@verse8.ioINVALID
@foo@bar@bazINVALID
@foo@localhostINVALID — single-label domain

Clients MAY accept the leading @ or omit it; the canonical rendering in any UI SHOULD include the leading @ to match Fediverse convention and to visually mark the string as a mention.

2. Lookup

WebFinger is always served at the domain root (/.well-known/webfinger) regardless of the operator’s deploy layout — RFC 7033 pins the well-known path, and the paired /.well-known/agent-card/{local} endpoint follows the same rule. Mentionable nodes running under a URL sub-path (see @mentionable/server’s basePath option) MUST still route both root-level .well-known paths to the Mentionable handler (typically a reverse-proxy rule).

A resolver MUST:

  1. Take the input address, normalize to acct:local@domain form.
  2. Issue GET https://{domain}/.well-known/webfinger?resource=acct:{local}@{domain} with Accept: application/jrd+json, application/json.
  3. Follow at most one HTTPS redirect on the well-known URL. The redirect target MUST be HTTPS. v0.1 does not require the redirect target’s domain to match the subject of the response, but resolvers MUST validate step 5 after dereferencing. Bridge scenarios (§9) depend on this, so strict domain-matching is deferred to a later minor version once bridge semantics are defined.
  4. Reject non-HTTPS responses. Plain HTTP is not supported in v0.1.
  5. Validate that the response subject is the acct: URI that was queried, or differs only in xn-- encoding, or is the bridged canonical form the queried address points to (out of scope in v0.1; see §9). In v0.1, mismatched subjects that are not IDN variants are a discovery failure.

Caching: resolvers SHOULD honor Cache-Control headers, with an implementation default of 1 hour and an upper bound of 24 hours.

3. The JRD response

A Mentionable agent’s WebFinger JRD MUST include:

It SHOULD include:

3.1 Canonical example

{
  "subject": "acct:agent@verse8.io",
  "aliases": ["https://verse8.io/ap/actors/agent", "https://verse8.io/agents/agent"],
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://verse8.io/ap/actors/agent"
    },
    {
      "rel": "https://mentionable.dev/ns/rel/agent-card",
      "type": "application/json",
      "href": "https://verse8.io/.well-known/agent-card/agent"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://verse8.io/agents/agent"
    },
    {
      "rel": "mailto",
      "href": "mailto:agent@verse8.io"
    }
  ]
}

4. The agent-card rel

Rel URI: https://mentionable.dev/ns/rel/agent-card

Deprecated alias. During the transition window (see ../wiki/url-scheme.md and issue #503) the legacy rel URI https://mentionable.dev/agent-card is recognised as an alias on inbound only. Publishers MUST emit the canonical /ns/rel/agent-card rel; conformant resolvers and TCK suites recognise either.

This rel points to a JSON document (see agent-card.md) containing:

The document at this URL is authoritative for agent-level metadata. The WebFinger JRD exists only to discover it.

Publishers MUST serve this URL with Cache-Control at least as aggressive as the WebFinger response, and MUST include an ETag or Last-Modified for conditional requests. Card changes are expected to be infrequent; aggressive caching is safe.

5. Coexistence with ActivityPub publishers

Mentionable does not replace a node’s existing WebFinger handler. When a domain already serves WebFinger for ActivityPub:

This makes adding Mentionable support to an existing Fediverse server a strict additive change: no existing client breaks.

6. Rate-limiting and abuse

Publishers SHOULD rate-limit WebFinger lookups per source IP (suggested: 60/minute). The acct: namespace is a public directory; enumeration resistance is not a goal of v0.1 — but exhaustive crawling is.

Publishers MAY return a valid JRD for addresses that do not correspond to any live agent (returning a card that advertises no reachable endpoints). This is preferable to 404 for account-privacy-sensitive operators. v0.1 takes no position; both behaviors are conformant.

7. Security

8. Conformance

A publisher is conformant for v0.1 if:

  1. It serves https://{domain}/.well-known/webfinger?resource=acct:{local}@{domain} returning a JRD as described in §3.
  2. The JRD includes the AP self rel and the https://mentionable.dev/ns/rel/agent-card rel (or, for backward compatibility during the transition window, the deprecated alias https://mentionable.dev/agent-card).
  3. Both URLs served over HTTPS with valid certificates.

A resolver is conformant for v0.1 if:

  1. It implements §2 correctly.
  2. It reads both the self and agent-card rels and chooses the appropriate endpoint for the protocol it wishes to use.
  3. It respects HTTPS-only and the SSRF rules in §7.

9. Open questions