WebFinger support for portable actors

[dahlia]

Background

FEP-ef61 defines portable actor IDs using ap: URIs, and Fedify plans to support ap+ef61: as the canonical portable-object scheme. Unlike ordinary HTTP(S) actor IDs, portable actor IDs do not contain a server host:

ap+ef61://did:key:z6MkAlice/actor

That creates a compatibility problem for WebFinger. Existing ActivityPub software expects actors to be discoverable through addresses such as:

acct:alice@server.example

FEP-ef61 addresses this in its compatibility section: the WebFinger address of a portable actor is obtained by the usual reverse discovery algorithm, but the hostname is taken from the first gateway in the actor's gateways array rather than from the actor ID.

For example, if a portable actor has:

{
  "id": "ap+ef61://did:key:z6MkAlice/actor",
  "preferredUsername": "alice",
  "gateways": [
    "https://server1.example",
    "https://server2.example"
  ]
}

then its WebFinger address should use server1.example:

acct:alice@server1.example

Fedify needs to support this compatibility model for portable actors.

Proposed work

Add WebFinger support for portable actors.

The work should cover both serving and lookup behavior where appropriate.

For serving WebFinger responses, Fedify should:

• allow applications to map a WebFinger resource such as acct:alice@server1.example to a portable actor;
• derive or validate the WebFinger host from the first gateway in the actor's gateways array;
• decide whether the WebFinger self link should point to the canonical ap+ef61: actor ID, a compatible gateway HTTP identifier, or both;
• preserve existing WebFinger behavior for ordinary HTTP(S) actors;
• work with existing mapHandle() and mapAlias() APIs where possible instead of introducing a parallel portable actor lookup API.

For WebFinger lookup, Fedify should:

• tolerate WebFinger self links that point to ap: or ap+ef61: actor IDs;
• tolerate WebFinger self links that point to compatible FEP-ef61 gateway identifiers;
• route portable self links through gateway dereferencing where needed;
• avoid treating the WebFinger server as the actor's origin when the actor ID is portable;
• keep existing HTTP(S) actor lookup behavior unchanged.

Design questions

The implementation should settle these details:

• Should a portable actor's WebFinger self link use the canonical ap+ef61: actor ID, a compatible HTTP identifier based on gateways[0], or both?
• Should Fedify derive the username from preferredUsername, or should applications provide an explicit handle mapping for portable actors?
• What happens when preferredUsername is missing?
• What happens when the actor has no gateways value, or the first gateway is not a valid HTTP(S) origin?
• If gateways[0] changes, should Fedify treat the WebFinger address as changed?
• Can the existing mapHandle() and mapAlias() APIs express the needed mapping cleanly, or do they need additional portable actor context?
• During lookup, should a compatible gateway identifier be preferred over a canonical ap+ef61: link for interoperability, or should canonical portable IDs take precedence when both are present?
• How should this interact with FEP-fe34 cryptographic origins and the existing WebFinger cross-origin protections?

Scope

This issue is only about WebFinger compatibility for portable actors.

It does not include:

• portable URI parsing and canonicalization;
• FEP-ef61 vocabulary terms;
• gateway dereferencing itself;
• compatible identifier conversion itself;
• Object Integrity Proof verification;
• actor registration;
• inbox or outbox forwarding;
• FEP-ae97 client-side signing.

Those lower-level pieces are tracked separately under #288.

Tests

Add regression tests for portable actor WebFinger behavior.

The tests should cover:

• serving a WebFinger response for a portable actor using the host from gateways[0];
• preserving ordinary WebFinger responses for HTTP(S) actors;
• deciding and testing the chosen self link shape for portable actors;
• rejecting or not resolving portable actors with missing or invalid gateways;
• lookup of a WebFinger response whose self link is an ap+ef61: actor ID;
• lookup of a WebFinger response whose self link is a compatible FEP-ef61 gateway identifier;
• ensuring portable actor lookup uses FEP-ef61 gateway dereferencing rather than ordinary HTTP(S) same-origin assumptions;
• behavior when both canonical and compatible self links are present.

This should be added as a sub-issue of #288.