Gateway dereferencing for portable vocabulary references

[dahlia]

Background

FEP-ef61 defines how portable objects identified by ap: URIs are dereferenced through gateway endpoints. Fedify also plans to support ap+ef61: as the canonical portable-object scheme.

In Fedify, dereferencing is already exposed through generated vocabulary accessors such as Activity.getObject(), Activity.getActor(), Object.getReplyTargets(), and similar get*() methods. These accessors currently use documentLoader to fetch URL-valued references. For portable object IDs, calling the document loader directly with an ap: or ap+ef61: URL is not enough: the object must be fetched through one of its gateways.

This issue is about integrating FEP-ef61 gateway dereferencing with the existing vocabulary dereferencing model, not just adding a standalone fetch helper.

Proposed work

Add gateway-aware dereferencing support for portable vocabulary references.

The work should include:

• defining how generated dereferencing accessors receive gateway information when the referenced ID is an ap: or ap+ef61: URI;
• extending dereferencing accessor options, or adding a shared lower-level dereferencing hook, so callers can pass an ordered list of gateway base URLs;
• using the compatible identifier conversion helper to construct fixed /.well-known/apgateway/... URLs;
• sending GET requests with the ActivityPub JSON-LD Accept header;
• parsing successful responses through the existing vocabulary JSON-LD parsing path;
• verifying that the returned object's portable ID canonically matches the requested portable ID;
• applying the FEP-ef61 proof policy for returned portable actors, activities, and objects;
• preserving the existing documentLoader behavior for HTTP(S) references;
• preserving existing FEP-fe34 cross-origin behavior for non-portable references.

The first version should require gateways to be passed explicitly by the caller. Automatic gateway discovery can be added later.

Design questions

The implementation should settle these API details before the code path is finalized:

• Should gateway-aware dereferencing be implemented as new options on generated get*() accessors, or as behavior in the shared generated dereferencing helper?
• What should the option shape be? For example, gateways?: readonly (string | URL)[] may be enough for the first version.
• Should the helper support gateway hints embedded in ap:/ap+ef61: query parameters in this issue, or should that remain follow-up work?
• How should this interact with custom documentLoader implementations? The gateway fetch probably still needs to be overrideable, but the ap: to gateway URL conversion should not be left to every application.
• What should happen when no gateways are available for a portable reference: return null, throw, or fall back to the caller's documentLoader?

Scope

This issue is only about read-only client-side dereferencing of portable references through generated vocabulary accessors or their shared dereferencing helper.

It does not include:

• serving local gateway endpoints;
• actor registration;
• inbox or outbox forwarding;
• FEP-ae97 client-side signing;
• media upload, serving, or deletion;
• arbitrary gateway path support;
• automatic gateway discovery from actor documents;
• unsecured portable collection trust policy.

Private object access and signed GET behavior should be considered during design. If it requires broader API changes, it can be split into a follow-up issue.

Tests

Add regression tests for gateway-aware vocabulary dereferencing.

The tests should cover:

• a generated get*() accessor dereferencing an ap+ef61: reference through an explicit gateway list;
• constructing the expected /.well-known/apgateway/... URL for a portable ID;
• sending the expected ActivityPub JSON-LD Accept header;
• returning the parsed object when the gateway serves a matching portable object;
• rejecting a response whose object ID does not canonically match the requested ID;
• rejecting a response whose proof fails the FEP-ef61 proof policy;
• trying the next gateway after 404 Not Found if multiple gateways are provided;
• behavior for network errors;
• behavior for non-404 HTTP errors;
• preserving existing HTTP(S) dereferencing accessor behavior.

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